@hotmeshio/long-tail 0.25.4 → 0.27.0

package/build/services/machines/testing/fake-long-tail.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * An in-memory Long Tail for the machine gateway: escalation rows with the
+ * claim / accumulate / resolve / create verbs, each publishing the lifecycle
+ * event Long Tail publishes, plus helpers that play the unit workflow and the
+ * people (exit, operator).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FakeLongTail = void 0;
+const actions_1 = require("../gateway/actions");
+const escalations_1 = require("../gateway/escalations");
+const contracts_1 = require("../contracts");
+const wait_1 = require("./wait");
+class FakeLongTail {
+    /** The next `times` calls of `verb` fail as a Long Tail outage would (5xx). */
+    failNext(verb, times = 1) {
+        this.failing.set(verb, times);
+    }
+    hidden(as, row) {
+        const roles = this.holds.get(as);
+        return !!row && !!roles && !roles.has(row.role);
+    }
+    outage(verb) {
+        const left = this.failing.get(verb) ?? 0;
+        if (left <= 0)
+            return;
+        this.failing.set(verb, left - 1);
+        throw new Error(`Long Tail unavailable (${verb})`);
+    }
+    constructor(feed) {
+        this.feed = feed;
+        this.rows = new Map();
+        this.calls = [];
+        this.seq = 0;
+        this.failing = new Map();
+        /** Roles each actor holds; an actor outside a row's role gets not found, as Long Tail's RBAC answers. */
+        this.holds = new Map();
+    }
+    emit(row, verb, extra = {}) {
+        this.feed.emit({
+            type: `system.escalation.${row.role}.${row.id}.${verb}`, escalationId: row.id, role: row.role,
+            data: { id: row.id, type: row.type, subtype: row.subtype, role: row.role, status: row.status, assigned_to: row.assigned_to, metadata: row.metadata, ...extra },
+        });
+    }
+    add(input) {
+        const row = { ...input, id: `e${++this.seq}`, status: 'pending', items: [], created_at: new Date().toISOString() };
+        this.rows.set(row.id, row);
+        this.emit(row, 'created');
+        return row;
+    }
+    /** What the unit workflow's conditionalAccumulator does: park a handoff row. */
+    park(role, facets) {
+        return this.add({ type: contracts_1.ROW_TYPE.HANDOFF, role, metadata: { ...facets } });
+    }
+    /** Park any row, as a host workflow parks its own. */
+    parkRow(input) {
+        return this.add({ ...input, metadata: { ...input.metadata } });
+    }
+    /** A person resolving a row on the dashboard. */
+    personResolves(id, payload, person = 'person-1') {
+        const row = this.rows.get(id);
+        row.status = 'resolved';
+        row.resolver_payload = payload;
+        row.resolved_by = person;
+        this.emit(row, 'resolved', { resolved_by: person });
+    }
+    /** A person or the workflow cancelling the row. */
+    cancel(id) {
+        const row = this.rows.get(id);
+        row.status = 'cancelled';
+        this.emit(row, 'cancelled');
+    }
+    /** The row's timeout firing (conditional `timeout`). */
+    expire(id) {
+        const row = this.rows.get(id);
+        row.status = 'expired';
+        this.emit(row, 'expired');
+    }
+    async claim(as, id) {
+        this.outage('claim');
+        this.calls.push({ verb: 'claim', as, id });
+        const row = this.rows.get(id);
+        if (!row || row.status !== 'pending')
+            return { outcome: escalations_1.VERB_OUTCOME.ALREADY };
+        row.assigned_to = as;
+        this.emit(row, 'claimed');
+        return { outcome: escalations_1.VERB_OUTCOME.DONE };
+    }
+    async accumulate(as, id, itemKey, payload, metadata) {
+        this.outage('accumulate');
+        this.calls.push({ verb: 'accumulate', as, id, payload: { itemKey, ...payload } });
+        const row = this.rows.get(id);
+        if (this.hidden(as, row))
+            return { outcome: escalations_1.VERB_OUTCOME.ALREADY, status: 404 };
+        if (!row || row.status !== 'pending')
+            return { outcome: escalations_1.VERB_OUTCOME.ALREADY };
+        if (row.items.some((i) => i.itemKey === itemKey))
+            return { outcome: escalations_1.VERB_OUTCOME.ALREADY };
+        row.items.push({ itemKey, payload, actor: as });
+        if (metadata)
+            row.metadata = { ...row.metadata, ...metadata };
+        return { outcome: escalations_1.VERB_OUTCOME.DONE, itemKeys: row.items.map((i) => i.itemKey) };
+    }
+    async resolve(as, id, payload) {
+        this.outage('resolve');
+        this.calls.push({ verb: 'resolve', as, id, payload });
+        const row = this.rows.get(id);
+        if (!row || row.status !== 'pending')
+            return { outcome: escalations_1.VERB_OUTCOME.ALREADY };
+        // Long Tail refuses a resolve by id while someone else holds a live claim (409).
+        if (row.assigned_to && row.assigned_to !== as)
+            return { outcome: escalations_1.VERB_OUTCOME.ALREADY, detail: 'claimed by another' };
+        row.status = 'resolved';
+        row.resolver_payload = payload;
+        row.resolved_by = as;
+        this.emit(row, 'resolved', { resolved_by: as });
+        return { outcome: escalations_1.VERB_OUTCOME.DONE };
+    }
+    async create(_as, input) {
+        this.outage('create');
+        return { id: this.add({ ...input }).id };
+    }
+    async itemKeys(id) {
+        return (this.rows.get(id)?.items ?? []).map((i) => i.itemKey);
+    }
+    async items(id) {
+        return (this.rows.get(id)?.items ?? []).map((i) => ({ itemKey: i.itemKey, payload: i.payload }));
+    }
+    async get(id) {
+        const row = this.rows.get(id);
+        if (!row || this.hidden(actions_1.CONTROLLER, row))
+            return null;
+        return {
+            id: row.id, type: row.type, subtype: row.subtype, role: row.role, status: row.status,
+            assigned_to: row.assigned_to ?? null, resolved_by: row.resolved_by ?? null, metadata: { ...row.metadata }, created_at: row.created_at ?? null,
+            // Stored serialized, as Long Tail returns it.
+            resolver_payload: row.resolver_payload ? JSON.stringify(row.resolver_payload) : null,
+        };
+    }
+    async listOpen(query) {
+        return [...this.rows.values()]
+            .filter((r) => r.status === 'pending' && (!query.type || r.type === query.type) && (!query.role || r.role === query.role))
+            .map((r) => ({
+            id: r.id, type: r.type, subtype: r.subtype, role: r.role, status: r.status, assigned_to: r.assigned_to ?? null, metadata: r.metadata,
+            created_at: r.created_at ?? null,
+        }));
+    }
+    ofType(type) {
+        return [...this.rows.values()].filter((r) => r.type === type);
+    }
+    ended(id, ms = 1_000) {
+        return (0, wait_1.until)(() => {
+            const row = this.rows.get(id);
+            return row && row.status !== 'pending' ? row : undefined;
+        }, ms);
+    }
+}
+exports.FakeLongTail = FakeLongTail;

package/build/services/machines/testing/index.d.ts

@@ -0,0 +1,3 @@
+export * from './fake-long-tail';
+export * from './wait';
+export * from './recording-log';

package/build/services/machines/testing/index.js

@@ -0,0 +1,19 @@
+"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 __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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./fake-long-tail"), exports);
+__exportStar(require("./wait"), exports);
+__exportStar(require("./recording-log"), exports);

package/build/services/machines/testing/recording-log.d.ts

@@ -0,0 +1,14 @@
+import type { GatewayLog, GatewayLogEvent } from '../gateway/log';
+export interface LogEntry {
+    level: 'info' | 'warn' | 'error';
+    event: GatewayLogEvent;
+    context: Record<string, unknown>;
+}
+/** A gateway log that keeps every entry, for assertions. */
+export declare class RecordingLog implements GatewayLog {
+    readonly entries: LogEntry[];
+    info(event: GatewayLogEvent, context?: Record<string, unknown>): void;
+    warn(event: GatewayLogEvent, context?: Record<string, unknown>): void;
+    error(event: GatewayLogEvent, context?: Record<string, unknown>): void;
+    of(event: GatewayLogEvent): Record<string, unknown>[];
+}

package/build/services/machines/testing/recording-log.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecordingLog = void 0;
+/** A gateway log that keeps every entry, for assertions. */
+class RecordingLog {
+    constructor() {
+        this.entries = [];
+    }
+    info(event, context = {}) {
+        this.entries.push({ level: 'info', event, context });
+    }
+    warn(event, context = {}) {
+        this.entries.push({ level: 'warn', event, context });
+    }
+    error(event, context = {}) {
+        this.entries.push({ level: 'error', event, context });
+    }
+    of(event) {
+        return this.entries.filter((e) => e.event === event).map((e) => e.context);
+    }
+}
+exports.RecordingLog = RecordingLog;

package/build/services/machines/testing/wait.d.ts

@@ -0,0 +1,3 @@
+export declare const sleep: (ms: number) => Promise<unknown>;
+/** Resolve with the first truthy value `check` returns, or throw after `ms`. */
+export declare function until<T>(check: () => T | undefined | null | false, ms?: number): Promise<T>;

package/build/services/machines/testing/wait.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleep = void 0;
+exports.until = until;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+exports.sleep = sleep;
+/** Resolve with the first truthy value `check` returns, or throw after `ms`. */
+async function until(check, ms = 500) {
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        const value = check();
+        if (value)
+            return value;
+        await (0, exports.sleep)(2);
+    }
+    throw new Error('condition not met in time');
+}

package/build/services/mcp/db-server/schemas.d.ts

@@ -8,13 +8,13 @@ export declare const findTasksSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     limit: number;
     status?: "completed" | "pending" | "in_progress" | "needs_intervention" | "failed" | undefined;
-    workflow_type?: string | undefined;
     workflow_id?: string | undefined;
+    workflow_type?: string | undefined;
     origin_id?: string | undefined;
 }, {
     status?: "completed" | "pending" | "in_progress" | "needs_intervention" | "failed" | undefined;
-    workflow_type?: string | undefined;
     workflow_id?: string | undefined;
+    workflow_type?: string | undefined;
     origin_id?: string | undefined;
     limit?: number | undefined;
 }>;

package/build/start/adapters.js

@@ -6,6 +6,8 @@ const pino_1 = require("../lib/logger/pino");
 const telemetry_1 = require("../lib/telemetry");
 const honeycomb_1 = require("../lib/telemetry/honeycomb");
 const events_1 = require("../lib/events");
+const messaging_1 = require("../lib/messaging");
+const config_1 = require("../lib/messaging/config");
 const nats_1 = require("../lib/events/nats");
 const socketio_1 = require("../lib/events/socketio");
 const maintenance_1 = require("../services/maintenance");
@@ -44,6 +46,10 @@ function registerAdapters(startConfig) {
     else if (startConfig.telemetry?.honeycomb) {
         telemetry_1.telemetryRegistry.register(new honeycomb_1.HoneycombTelemetryAdapter(startConfig.telemetry.honeycomb));
     }
+    // Messaging: one provider shared by events and the machine surface.
+    const messaging = (0, config_1.resolveMessaging)(startConfig);
+    if (messaging.provider)
+        messaging_1.messagingRegistry.register(messaging.provider);
     // Events — register the configured transport.
     // Socket.IO is the default for single-container ("nothing but Postgres").
     // When NATS or custom adapters are configured, Socket.IO is NOT registered —
@@ -54,8 +60,11 @@ function registerAdapters(startConfig) {
             events_1.eventRegistry.register(adapter);
         }
     }
-    else if (startConfig.events?.nats) {
-        events_1.eventRegistry.register(new nats_1.NatsEventAdapter(startConfig.events.nats));
+    else if (messaging.provider?.name === config_1.MESSAGING_KIND.NATS) {
+        events_1.eventRegistry.register(new nats_1.NatsEventAdapter({
+            messaging: messaging.provider, wsUrl: messaging.ws.url, wsProxy: messaging.ws.proxy, token: messaging.ws.token,
+            subjectPrefix: startConfig.events?.nats?.subjectPrefix,
+        }));
     }
     else {
         events_1.eventRegistry.register(new socketio_1.SocketIOEventAdapter({

package/build/start/index.js

@@ -5,6 +5,10 @@ const hotmesh_1 = require("@hotmeshio/hotmesh");
 const logger_1 = require("../lib/logger");
 const telemetry_1 = require("../lib/telemetry");
 const events_1 = require("../lib/events");
+const messaging_1 = require("../lib/messaging");
+const callback_1 = require("../lib/events/callback");
+const surface_1 = require("../services/machines/surface");
+const roles_1 = require("../services/machines/roles");
 const maintenance_1 = require("../services/maintenance");
 const cron_1 = require("../services/cron");
 const mcp_1 = require("../services/mcp");
@@ -63,12 +67,23 @@ async function start(startConfig) {
     (0, config_1.applyDatabaseConfig)(startConfig.database);
     // 2. Apply server/auth config
     await (0, config_1.applyServerAuthConfig)(startConfig);
-    // 3. Register adapters
+    // 3. Register adapters; messaging connects first, since events and machines use it.
+    // An unreachable NATS is logged and Long Tail starts, as events always have; what needs streams fails then.
     (0, adapters_1.registerAdapters)(startConfig);
+    await messaging_1.messagingRegistry.connect().catch((err) => {
+        logger_1.loggerRegistry.error(`${messaging_1.MESSAGING_LOG.CONNECT_FAILED} ${err instanceof Error ? err.message : String(err)}`);
+    });
     logger_1.loggerRegistry.info('[long-tail] starting...');
     // 4-5. Collect workers, run migrations, start workers, seed data
+    if (startConfig.machines && startConfig.machines.declareRoles !== false) {
+        startConfig = { ...startConfig, roles: (0, roles_1.withMachineRoles)(startConfig.roles, startConfig.machines.lines) };
+    }
     const { workers, builtinMcpServerFactories } = await (0, workers_1.collectWorkers)(startConfig);
     const { adminUserId } = await (0, workers_1.startWorkers)(startConfig, workers, builtinMcpServerFactories);
+    // 5b. Machines, after the workers exist so their rows publish lifecycle events
+    const machines = startConfig.machines
+        ? surface_1.MachineSurface.start({ ...startConfig.machines, callbacks: events_1.eventRegistry.getAdapter(callback_1.CallbackEventAdapter) })
+        : null;
     // 6. Start embedded server (if enabled)
     const serverEnabled = startConfig.server?.enabled !== false;
     let httpServer = null;
@@ -85,6 +100,9 @@ async function start(startConfig) {
         if (httpServer) {
             await new Promise((resolve) => httpServer.close(() => resolve()));
         }
+        if (machines) {
+            await machines.stop();
+        }
         if (mcp_1.mcpRegistry.hasAdapter) {
             await mcp_1.mcpRegistry.disconnect();
         }
@@ -97,6 +115,7 @@ async function start(startConfig) {
         if (events_1.eventRegistry.hasAdapters) {
             await events_1.eventRegistry.disconnect();
         }
+        await messaging_1.messagingRegistry.disconnect();
         if (telemetry_1.telemetryRegistry.hasAdapter) {
             await telemetry_1.telemetryRegistry.disconnect();
         }