@hotmeshio/long-tail 0.25.4 → 0.26.0

package/build/services/machines/testing/fake-long-tail.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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).
+ */
+import { type Actor, type CreateRowInput } from '../gateway/actions';
+import { type LineEscalations, type RowItem, type VerbResult } from '../gateway/escalations';
+import { type HandoffFacets } from '../contracts';
+import type { MemoryEscalationFeed } from '../../../lib/machines/transport';
+import type { OpenRowQuery } from '../rows';
+export interface FakeRow {
+    id: string;
+    type: string;
+    subtype?: string;
+    role: string;
+    status: 'pending' | 'resolved' | 'cancelled' | 'expired';
+    assigned_to?: string;
+    metadata: Record<string, any>;
+    items: {
+        itemKey: string;
+        payload: any;
+        actor: Actor;
+    }[];
+    resolver_payload?: Record<string, any>;
+    resolved_by?: string;
+    envelope?: string;
+    escalation_payload?: string;
+}
+export interface Call {
+    verb: string;
+    as: Actor;
+    id: string;
+    payload?: any;
+}
+export declare class FakeLongTail implements LineEscalations {
+    private readonly feed;
+    readonly rows: Map<string, FakeRow>;
+    readonly calls: Call[];
+    private seq;
+    private failing;
+    /** The next `times` calls of `verb` fail as a Long Tail outage would (5xx). */
+    failNext(verb: 'claim' | 'accumulate' | 'resolve' | 'create', times?: number): void;
+    /** Roles each actor holds; an actor outside a row's role gets not found, as Long Tail's RBAC answers. */
+    readonly holds: Map<string, Set<string>>;
+    private hidden;
+    private outage;
+    constructor(feed: MemoryEscalationFeed);
+    private emit;
+    private add;
+    /** What the unit workflow's conditionalAccumulator does: park a handoff row. */
+    park(role: string, facets: HandoffFacets): FakeRow;
+    /** Park any row, as a host workflow parks its own. */
+    parkRow(input: {
+        type: string;
+        role: string;
+        subtype?: string;
+        metadata: Record<string, any>;
+    }): FakeRow;
+    /** A person resolving a row on the dashboard. */
+    personResolves(id: string, payload: Record<string, any>, person?: string): void;
+    /** A person or the workflow cancelling the row. */
+    cancel(id: string): void;
+    /** The row's timeout firing (conditional `timeout`). */
+    expire(id: string): void;
+    claim(as: Actor, id: string): Promise<VerbResult>;
+    accumulate(as: Actor, id: string, itemKey: string, payload: Record<string, any>, metadata?: Record<string, any>): Promise<VerbResult>;
+    resolve(as: Actor, id: string, payload: Record<string, any>): Promise<VerbResult>;
+    create(_as: Actor, input: CreateRowInput): Promise<{
+        id: string;
+    }>;
+    itemKeys(id: string): Promise<string[]>;
+    items(id: string): Promise<RowItem[]>;
+    get(id: string): Promise<Record<string, any> | null>;
+    listOpen(query: OpenRowQuery): Promise<Record<string, any>[]>;
+    ofType(type: string): FakeRow[];
+    ended(id: string, ms?: number): Promise<FakeRow>;
+}

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

@@ -0,0 +1,155 @@
+"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: [] };
+        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 },
+            // 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 }));
+    }
+    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/index.js

@@ -5,6 +5,9 @@ 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 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");
@@ -67,8 +70,15 @@ async function start(startConfig) {
     (0, adapters_1.registerAdapters)(startConfig);
     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 +95,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();
         }