@hotmeshio/long-tail 0.1.0

package/build/services/yaml-workflow/workers/events.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapWithEvents = wrapWithEvents;
+const logger_1 = require("../../logger");
+const publish_1 = require("../../events/publish");
+/**
+ * Wrap a worker callback with activity lifecycle event publishing.
+ * Publishes activity.started before and activity.completed/failed after.
+ */
+function wrapWithEvents(activity, appId, stepIndex, totalSteps, callback) {
+    return async (data) => {
+        const meta = data.metadata;
+        const jid = meta?.jid || 'unknown';
+        const wfn = meta?.wfn || appId;
+        const eventBase = {
+            workflowId: jid,
+            workflowName: wfn,
+            taskQueue: appId,
+            activityName: activity.activity_id,
+            data: {
+                title: activity.title,
+                toolName: activity.mcp_tool_name,
+                toolSource: activity.tool_source,
+                stepIndex,
+                totalSteps,
+            },
+        };
+        (0, publish_1.publishActivityEvent)({ type: 'activity.started', ...eventBase });
+        try {
+            const result = await callback(data);
+            (0, publish_1.publishActivityEvent)({ type: 'activity.completed', ...eventBase });
+            return result;
+        }
+        catch (err) {
+            logger_1.loggerRegistry.error(`[yaml-worker] ${activity.activity_id} failed: ${err.message}`);
+            (0, publish_1.publishActivityEvent)({
+                type: 'activity.failed',
+                ...eventBase,
+                data: { ...eventBase.data, error: err.message },
+            });
+            // Return the error as data instead of throwing — prevents HotMesh
+            // retry storms when the engine reprocesses failed stream messages.
+            return {
+                metadata: { ...data.metadata },
+                data: { error: err.message, is_error: true },
+            };
+        }
+    };
+}

package/build/services/yaml-workflow/workers/index.d.ts

@@ -0,0 +1,4 @@
+export { buildToolContextFromScope, wrapWithScope } from './scope';
+export { compactForLlm, buildLlmCallback, buildTransformCallback } from './callbacks';
+export { wrapWithEvents } from './events';
+export { registerWorkersForWorkflow, registerAllActiveWorkers } from './register';

package/build/services/yaml-workflow/workers/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAllActiveWorkers = exports.registerWorkersForWorkflow = exports.wrapWithEvents = exports.buildTransformCallback = exports.buildLlmCallback = exports.compactForLlm = exports.wrapWithScope = exports.buildToolContextFromScope = void 0;
+var scope_1 = require("./scope");
+Object.defineProperty(exports, "buildToolContextFromScope", { enumerable: true, get: function () { return scope_1.buildToolContextFromScope; } });
+Object.defineProperty(exports, "wrapWithScope", { enumerable: true, get: function () { return scope_1.wrapWithScope; } });
+var callbacks_1 = require("./callbacks");
+Object.defineProperty(exports, "compactForLlm", { enumerable: true, get: function () { return callbacks_1.compactForLlm; } });
+Object.defineProperty(exports, "buildLlmCallback", { enumerable: true, get: function () { return callbacks_1.buildLlmCallback; } });
+Object.defineProperty(exports, "buildTransformCallback", { enumerable: true, get: function () { return callbacks_1.buildTransformCallback; } });
+var events_1 = require("./events");
+Object.defineProperty(exports, "wrapWithEvents", { enumerable: true, get: function () { return events_1.wrapWithEvents; } });
+var register_1 = require("./register");
+Object.defineProperty(exports, "registerWorkersForWorkflow", { enumerable: true, get: function () { return register_1.registerWorkersForWorkflow; } });
+Object.defineProperty(exports, "registerAllActiveWorkers", { enumerable: true, get: function () { return register_1.registerAllActiveWorkers; } });

package/build/services/yaml-workflow/workers/register.d.ts

@@ -0,0 +1,15 @@
+import type { LTYamlWorkflowRecord } from '../../../types/yaml-workflow';
+/**
+ * Register HotMesh workers for all activities in a YAML workflow.
+ * Each worker delegates based on tool_source:
+ * - 'db'  -> callDbTool() (internal DB MCP server)
+ * - 'mcp' -> mcpClient.callServerTool() (external MCP servers)
+ * - 'llm' -> callLLM() with prompt template interpolation
+ */
+export declare function registerWorkersForWorkflow(workflow: LTYamlWorkflowRecord): Promise<void>;
+/**
+ * Register workers for all active YAML workflows.
+ * Groups by app_id so flows sharing a namespace share a single engine/connection pool.
+ * Called at startup in workers/index.ts.
+ */
+export declare function registerAllActiveWorkers(): Promise<void>;

package/build/services/yaml-workflow/workers/register.js

@@ -0,0 +1,233 @@
+"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.registerWorkersForWorkflow = registerWorkersForWorkflow;
+exports.registerAllActiveWorkers = registerAllActiveWorkers;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const pg_1 = require("pg");
+const config_1 = require("../../../modules/config");
+const logger_1 = require("../../logger");
+const ephemeral_1 = require("../../iam/ephemeral");
+const mcpClient = __importStar(require("../../mcp/client"));
+const yamlDb = __importStar(require("../db"));
+const scope_1 = require("./scope");
+const callbacks_1 = require("./callbacks");
+const events_1 = require("./events");
+/** Track which topics already have registered workers */
+const registeredTopics = new Set();
+/**
+ * Register HotMesh workers for all activities in a YAML workflow.
+ * Each worker delegates based on tool_source:
+ * - 'db'  -> callDbTool() (internal DB MCP server)
+ * - 'mcp' -> mcpClient.callServerTool() (external MCP servers)
+ * - 'llm' -> callLLM() with prompt template interpolation
+ */
+async function registerWorkersForWorkflow(workflow) {
+    const workerConfigs = [];
+    // Clear previously registered workers for this workflow so redeployments
+    // pick up updated manifests (e.g., new hook_topic bindings).
+    for (const a of workflow.activity_manifest) {
+        if (a.type === 'worker') {
+            const key = a.workflow_name ? `${a.topic}:${a.workflow_name}` : a.topic;
+            registeredTopics.delete(key);
+        }
+    }
+    // Build lookup: for escalate_and_wait workers, find the following hook's topic
+    const hookTopicByEscalationTool = new Map();
+    for (const hookAct of workflow.activity_manifest.filter(a => a.type === 'hook' && a.hook_topic)) {
+        // Find the worker that transitions TO this hook — it's the escalation tool
+        // Convention: the escalation worker's activity_id precedes the hook in sequence
+        const hookIdx = workflow.activity_manifest.indexOf(hookAct);
+        if (hookIdx > 0) {
+            const preceding = workflow.activity_manifest[hookIdx - 1];
+            if (preceding.mcp_tool_name === 'escalate_and_wait') {
+                hookTopicByEscalationTool.set(preceding.activity_id, hookAct.hook_topic);
+            }
+        }
+    }
+    const workerActivities = workflow.activity_manifest.filter((a) => {
+        if (a.type !== 'worker')
+            return false;
+        const key = a.workflow_name ? `${a.topic}:${a.workflow_name}` : a.topic;
+        return !registeredTopics.has(key);
+    });
+    const totalSteps = workerActivities.length;
+    let stepIndex = 0;
+    for (const activity of workerActivities) {
+        const currentStep = stepIndex++;
+        const toolSource = activity.tool_source || (activity.mcp_server_id === 'db' ? 'db' : 'mcp');
+        const wrap = (cb) => (0, events_1.wrapWithEvents)(activity, workflow.app_id, currentStep, totalSteps, (0, scope_1.wrapWithScope)(cb));
+        if (toolSource === 'transform') {
+            // Transform/reshape step — deterministic data mapping between steps
+            workerConfigs.push({
+                topic: activity.topic,
+                workflowName: activity.workflow_name,
+                connection: { class: pg_1.Client, options: config_1.postgres_options },
+                callback: wrap((0, callbacks_1.buildTransformCallback)(activity)),
+            });
+        }
+        else if (toolSource === 'llm') {
+            // LLM interpretation step
+            workerConfigs.push({
+                topic: activity.topic,
+                workflowName: activity.workflow_name,
+                connection: { class: pg_1.Client, options: config_1.postgres_options },
+                callback: wrap((0, callbacks_1.buildLlmCallback)(activity)),
+            });
+        }
+        else if (toolSource === 'db') {
+            if (!activity.mcp_tool_name)
+                continue;
+            const toolName = activity.mcp_tool_name;
+            const dbServerId = activity.mcp_server_id || 'long-tail-db';
+            const toolArgs = activity.tool_arguments;
+            workerConfigs.push({
+                topic: activity.topic,
+                workflowName: activity.workflow_name,
+                connection: { class: pg_1.Client, options: config_1.postgres_options },
+                callback: wrap(async (data) => {
+                    const args = (data.data || {});
+                    let mergedArgs = toolArgs ? { ...toolArgs, ...args } : args;
+                    delete mergedArgs._scope;
+                    delete mergedArgs.workflowName;
+                    mergedArgs = await (0, ephemeral_1.exchangeTokensInArgs)(mergedArgs);
+                    const result = await mcpClient.callServerTool(dbServerId, toolName, mergedArgs);
+                    return { metadata: { ...data.metadata }, data: result };
+                }),
+            });
+        }
+        else {
+            if (!activity.mcp_tool_name)
+                continue;
+            const toolName = activity.mcp_tool_name;
+            const serverId = activity.mcp_server_id;
+            if (!serverId)
+                continue;
+            const storedArgs = activity.tool_arguments;
+            const yamlHookTopic = hookTopicByEscalationTool.get(activity.activity_id);
+            if (toolName === 'escalate_and_wait') {
+                logger_1.loggerRegistry.info(`[yaml-workflow] escalate_and_wait worker: activityId=${activity.activity_id}, hookTopic=${yamlHookTopic || 'NONE'}, mapKeys=[${[...hookTopicByEscalationTool.keys()].join(',')}]`);
+            }
+            workerConfigs.push({
+                topic: activity.topic,
+                workflowName: activity.workflow_name,
+                connection: { class: pg_1.Client, options: config_1.postgres_options },
+                callback: wrap(async (data) => {
+                    const args = (data.data || {});
+                    const mergedArgs = storedArgs ? { ...storedArgs } : {};
+                    for (const [key, value] of Object.entries(args)) {
+                        if (key === '_scope' || key === 'workflowName')
+                            continue;
+                        if (value !== undefined && value !== null && value !== '') {
+                            mergedArgs[key] = value;
+                        }
+                    }
+                    // For escalate_and_wait: inject YAML signal routing so the MCP tool
+                    // stores engine:'yaml' + hookTopic + jobId in the escalation metadata
+                    if (yamlHookTopic) {
+                        const jid = data.metadata?.jid;
+                        mergedArgs._yaml_signal_routing = {
+                            engine: 'yaml',
+                            appId: workflow.app_id,
+                            hookTopic: yamlHookTopic,
+                            jobId: jid,
+                            workflowType: workflow.graph_topic,
+                            workflowId: jid,
+                            taskQueue: workflow.app_id,
+                        };
+                    }
+                    const exchangedArgs = await (0, ephemeral_1.exchangeTokensInArgs)(mergedArgs);
+                    const result = await mcpClient.callServerTool(serverId, toolName, exchangedArgs);
+                    if (result && typeof result === 'object' && 'error' in result) {
+                        logger_1.loggerRegistry.error(`[yaml-workflow:worker] ${toolName} error: ${JSON.stringify(result).slice(0, 200)}`);
+                    }
+                    return { metadata: { ...data.metadata }, data: result };
+                }),
+            });
+        }
+        const regKey = activity.workflow_name ? `${activity.topic}:${activity.workflow_name}` : activity.topic;
+        registeredTopics.add(regKey);
+    }
+    if (workerConfigs.length === 0)
+        return;
+    await hotmesh_1.HotMesh.init({
+        appId: workflow.app_id,
+        engine: {
+            connection: { class: pg_1.Client, options: config_1.postgres_options },
+        },
+        workers: workerConfigs,
+    });
+    logger_1.loggerRegistry.info(`[yaml-workflow] registered ${workerConfigs.length} workers for ${workflow.app_id}`);
+}
+/**
+ * Register workers for all active YAML workflows.
+ * Groups by app_id so flows sharing a namespace share a single engine/connection pool.
+ * Called at startup in workers/index.ts.
+ */
+async function registerAllActiveWorkers() {
+    logger_1.loggerRegistry.info('[yaml-workflow] checking for active YAML workflows...');
+    try {
+        const workflows = await yamlDb.getActiveYamlWorkflows();
+        logger_1.loggerRegistry.info(`[yaml-workflow] found ${workflows.length} active workflow(s)`);
+        if (workflows.length === 0)
+            return;
+        // Group by app_id to register all workers for the same app together
+        const byAppId = new Map();
+        for (const wf of workflows) {
+            const group = byAppId.get(wf.app_id) || [];
+            group.push(wf);
+            byAppId.set(wf.app_id, group);
+        }
+        for (const [appId, group] of byAppId) {
+            try {
+                for (const wf of group) {
+                    await registerWorkersForWorkflow(wf);
+                }
+                logger_1.loggerRegistry.info(`[yaml-workflow] ${appId}: registered workers for ${group.length} flow(s)`);
+            }
+            catch (err) {
+                logger_1.loggerRegistry.error(`[yaml-workflow] failed to register workers for ${appId}: ${err.message}`);
+            }
+        }
+    }
+    catch (err) {
+        // Table may not exist yet if migration hasn't run
+        if (err.message?.includes('does not exist')) {
+            logger_1.loggerRegistry.info('[yaml-workflow] table not yet created, skipping worker registration');
+            return;
+        }
+        logger_1.loggerRegistry.error(`[yaml-workflow] startup worker registration failed: ${err.message}`);
+    }
+}

package/build/services/yaml-workflow/workers/scope.d.ts

@@ -0,0 +1,13 @@
+import type { StreamData, StreamDataResponse } from '@hotmeshio/hotmesh/build/types/stream';
+import type { ToolContext } from '../../../types/tool-context';
+/**
+ * Build a ToolContext from the `_scope` input parameter.
+ * YAML activities receive `_scope` threaded from the trigger through every step.
+ */
+export declare function buildToolContextFromScope(scope: Record<string, any>): ToolContext;
+/**
+ * Wrap a worker callback with scope injection via AsyncLocalStorage.
+ * If `_scope` is present in the input data, builds a ToolContext and
+ * wraps the callback so `getToolContext()` works inside tool code.
+ */
+export declare function wrapWithScope(callback: (data: StreamData) => Promise<StreamDataResponse>): (data: StreamData) => Promise<StreamDataResponse>;

package/build/services/yaml-workflow/workers/scope.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildToolContextFromScope = buildToolContextFromScope;
+exports.wrapWithScope = wrapWithScope;
+const context_1 = require("../../iam/context");
+/**
+ * Build a ToolContext from the `_scope` input parameter.
+ * YAML activities receive `_scope` threaded from the trigger through every step.
+ */
+function buildToolContextFromScope(scope) {
+    return {
+        principal: scope.principal,
+        ...(scope.initiatingPrincipal
+            ? { initiatingPrincipal: scope.initiatingPrincipal }
+            : {}),
+        credentials: {
+            scopes: scope.scopes ?? [],
+        },
+        trace: {},
+    };
+}
+/**
+ * Wrap a worker callback with scope injection via AsyncLocalStorage.
+ * If `_scope` is present in the input data, builds a ToolContext and
+ * wraps the callback so `getToolContext()` works inside tool code.
+ */
+function wrapWithScope(callback) {
+    return async (data) => {
+        const input = (data.data || {});
+        const scope = input._scope;
+        if (scope?.principal) {
+            const ctx = buildToolContextFromScope(scope);
+            return (0, context_1.runWithToolContext)(ctx, () => callback(data));
+        }
+        return callback(data);
+    };
+}

package/build/start/adapters.d.ts

@@ -0,0 +1,6 @@
+import type { LTStartConfig } from '../types/startup';
+/**
+ * Register all adapters (logging, telemetry, events, maintenance,
+ * escalation strategy, MCP) based on the startup config.
+ */
+export declare function registerAdapters(startConfig: LTStartConfig): void;

package/build/start/adapters.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAdapters = registerAdapters;
+const logger_1 = require("../services/logger");
+const pino_1 = require("../services/logger/pino");
+const telemetry_1 = require("../services/telemetry");
+const honeycomb_1 = require("../services/telemetry/honeycomb");
+const events_1 = require("../services/events");
+const nats_1 = require("../services/events/nats");
+const socketio_1 = require("../services/events/socketio");
+const maintenance_1 = require("../services/maintenance");
+const maintenance_2 = require("../modules/maintenance");
+const mcp_1 = require("../services/mcp");
+const adapter_1 = require("../services/mcp/adapter");
+const escalation_strategy_1 = require("../services/escalation-strategy");
+const default_1 = require("../services/escalation-strategy/default");
+const mcp_2 = require("../services/escalation-strategy/mcp");
+/**
+ * Register all adapters (logging, telemetry, events, maintenance,
+ * escalation strategy, MCP) based on the startup config.
+ */
+function registerAdapters(startConfig) {
+    // Logging (register first so subsequent log calls use it)
+    if (startConfig.logging?.adapter) {
+        logger_1.loggerRegistry.register(startConfig.logging.adapter);
+    }
+    else if (startConfig.logging?.pino) {
+        logger_1.loggerRegistry.register(new pino_1.PinoLoggerAdapter(startConfig.logging.pino));
+    }
+    // Telemetry
+    if (startConfig.telemetry?.adapter) {
+        telemetry_1.telemetryRegistry.register(startConfig.telemetry.adapter);
+    }
+    else if (startConfig.telemetry?.honeycomb) {
+        telemetry_1.telemetryRegistry.register(new honeycomb_1.HoneycombTelemetryAdapter(startConfig.telemetry.honeycomb));
+    }
+    // Events — always register socket.io (zero-cost until HTTP server attaches).
+    // NATS is additive: when configured, events publish to both transports.
+    if (startConfig.events?.adapters) {
+        for (const adapter of startConfig.events.adapters) {
+            events_1.eventRegistry.register(adapter);
+        }
+    }
+    else {
+        if (startConfig.events?.nats) {
+            events_1.eventRegistry.register(new nats_1.NatsEventAdapter(startConfig.events.nats));
+        }
+        events_1.eventRegistry.register(new socketio_1.SocketIOEventAdapter());
+    }
+    // Maintenance
+    if (startConfig.maintenance === false) {
+        // Disabled
+    }
+    else if (startConfig.maintenance === true || startConfig.maintenance === undefined) {
+        maintenance_1.maintenanceRegistry.register(maintenance_2.defaultMaintenanceConfig);
+    }
+    else {
+        maintenance_1.maintenanceRegistry.register(startConfig.maintenance);
+    }
+    // Escalation strategy
+    if (startConfig.escalation?.adapter) {
+        escalation_strategy_1.escalationStrategyRegistry.register(startConfig.escalation.adapter);
+    }
+    else if (startConfig.escalation?.strategy === 'mcp') {
+        escalation_strategy_1.escalationStrategyRegistry.register(new mcp_2.McpEscalationStrategy());
+    }
+    else {
+        escalation_strategy_1.escalationStrategyRegistry.register(new default_1.DefaultEscalationStrategy());
+    }
+    // MCP
+    if (startConfig.mcp?.adapter) {
+        mcp_1.mcpRegistry.register(startConfig.mcp.adapter);
+    }
+    else if (startConfig.mcp) {
+        mcp_1.mcpRegistry.register(new adapter_1.BuiltInMcpAdapter({
+            server: startConfig.mcp.server,
+            autoConnect: startConfig.mcp.autoConnect,
+        }));
+    }
+}

package/build/start/config.d.ts

@@ -0,0 +1,10 @@
+import type { LTStartConfig } from '../types/startup';
+/**
+ * Apply database connection settings from the startup config
+ * to the shared postgres_options object.
+ */
+export declare function applyDatabaseConfig(db: LTStartConfig['database']): void;
+/**
+ * Apply server port and auth settings from the startup config.
+ */
+export declare function applyServerAuthConfig(startConfig: LTStartConfig): Promise<void>;

package/build/start/config.js

@@ -0,0 +1,88 @@
+"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.applyDatabaseConfig = applyDatabaseConfig;
+exports.applyServerAuthConfig = applyServerAuthConfig;
+const config_1 = require("../modules/config");
+const auth_1 = require("../modules/auth");
+/**
+ * Apply database connection settings from the startup config
+ * to the shared postgres_options object.
+ */
+function applyDatabaseConfig(db) {
+    if (db.connectionString) {
+        Object.assign(config_1.postgres_options, {
+            connectionString: db.connectionString,
+            host: undefined,
+            port: undefined,
+            user: undefined,
+            password: undefined,
+            database: undefined,
+        });
+    }
+    else {
+        Object.assign(config_1.postgres_options, {
+            host: db.host ?? config_1.postgres_options.host,
+            port: db.port ?? config_1.postgres_options.port,
+            user: db.user ?? config_1.postgres_options.user,
+            password: db.password ?? config_1.postgres_options.password,
+            database: db.database ?? config_1.postgres_options.database,
+        });
+    }
+}
+/**
+ * Apply server port and auth settings from the startup config.
+ */
+async function applyServerAuthConfig(startConfig) {
+    const serverPort = startConfig.server?.port ?? config_1.config.PORT;
+    config_1.config.PORT = serverPort;
+    if (startConfig.auth?.secret) {
+        config_1.config.JWT_SECRET = startConfig.auth.secret;
+    }
+    if (startConfig.auth?.adapter) {
+        (0, auth_1.setAuthAdapter)(startConfig.auth.adapter);
+    }
+    // Initialize OAuth providers (from startup config and/or env vars)
+    const { initializeOAuth } = await Promise.resolve().then(() => __importStar(require('../services/oauth')));
+    initializeOAuth(startConfig.auth?.oauth);
+    if (startConfig.auth?.oauth) {
+        const { setOAuthConfig } = await Promise.resolve().then(() => __importStar(require('../routes/oauth')));
+        setOAuthConfig({
+            autoProvision: startConfig.auth.oauth.autoProvision,
+            defaultRoleType: startConfig.auth.oauth.defaultRoleType,
+            baseUrl: startConfig.auth.oauth.baseUrl,
+        });
+    }
+}

package/build/start/index.d.ts

@@ -0,0 +1,21 @@
+import type { LTStartConfig, LTInstance } from '../types/startup';
+/**
+ * Start Long Tail with a declarative configuration.
+ *
+ * Handles database connection, migrations, adapter registration,
+ * worker startup, and the embedded API server. Returns a client
+ * for starting workflows and a shutdown function.
+ *
+ * ```typescript
+ * import { start } from '@hotmeshio/long-tail';
+ * import * as myWorkflow from './workflows/my-workflow';
+ *
+ * const lt = await start({
+ *   database: { host: 'localhost', port: 5432, user: 'postgres', password: 'password', database: 'mydb' },
+ *   workers: [
+ *     { taskQueue: 'my-queue', workflow: myWorkflow.myWorkflow },
+ *   ],
+ * });
+ * ```
+ */
+export declare function start(startConfig: LTStartConfig): Promise<LTInstance>;