@c4t4/heyamigo 0.9.2 → 0.9.3

package/dist/index.js

@@ -5,6 +5,7 @@ import { attachIncoming } from './gateway/incoming.js';
 import { handleReply } from './gateway/outgoing.js';
 import { logger } from './logger.js';
 import { startScheduler } from './memory/scheduler.js';
+import { requestShutdown, startOrchestrator, stopOrchestrator, } from './queue/orchestrator.js';
 import { replayPending } from './queue/queue.js';
 import { startSenderWorker, stopSenderWorker } from './queue/sender-worker.js';
 import { startSocket } from './wa/socket.js';
@@ -14,6 +15,16 @@ async function main() {
     initDb();
     // Derived view: populate persons + identities from access.json.
     syncIdentitiesFromAccess();
+    // Orchestrator handles cross-cutting bookkeeping: control table
+    // signals, stuck-claim reclaim, dead-worker detection, cron polling
+    // (Phase 2.2+). Starts before workers so it can see them register.
+    startOrchestrator({
+        onShutdownDrained: () => {
+            stopSenderWorker();
+            stopOrchestrator();
+            closeDb();
+        },
+    });
     // Sender worker drains outbound queue → channel adapters. Started
     // before the socket so it's ready when handleReply enqueues rows.
     startSenderWorker();
@@ -30,17 +41,17 @@ async function main() {
         await handleReply(job, result, {});
     }).catch((err) => logger.error({ err }, 'replay failed'));
 }
+// Graceful shutdown: signal handler writes a 'shutdown' row to the
+// control table; orchestrator picks it up, drains in-flight work,
+// then runs onShutdownDrained (stops workers, closes DB) and exits.
+// A 30s timer inside the orchestrator force-exits if drain hangs.
 process.on('SIGINT', () => {
-    logger.info('SIGINT received, shutting down');
-    stopSenderWorker();
-    closeDb();
-    process.exit(0);
+    logger.info('SIGINT received, requesting graceful shutdown');
+    requestShutdown('SIGINT');
 });
 process.on('SIGTERM', () => {
-    logger.info('SIGTERM received, shutting down');
-    stopSenderWorker();
-    closeDb();
-    process.exit(0);
+    logger.info('SIGTERM received, requesting graceful shutdown');
+    requestShutdown('SIGTERM');
 });
 main().catch((err) => {
     logger.error({ err }, 'fatal error during boot');

package/dist/queue/control.js

@@ -0,0 +1,40 @@
+// Helpers for the control table — the bot's runtime signalling
+// channel. SIGTERM, /shutdown chat command, or external trigger all
+// insert a control row; the orchestrator picks it up on its next tick
+// and acts.
+//
+// Single-row-per-key: PK on `key` gives natural upsert semantics.
+import { eq } from 'drizzle-orm';
+import { getDb } from '../db/index.js';
+import { control } from '../db/schema.js';
+export function requestControl(key, value = null, requestedBy = null) {
+    const db = getDb();
+    const now = Math.floor(Date.now() / 1000);
+    db.insert(control)
+        .values({ key, value, requestedBy, requestedAt: now })
+        .onConflictDoUpdate({
+        target: control.key,
+        set: { value, requestedBy, requestedAt: now },
+    })
+        .run();
+}
+export function readControl(key) {
+    const db = getDb();
+    const row = db.select().from(control).where(eq(control.key, key)).get();
+    if (!row)
+        return null;
+    return {
+        value: row.value,
+        requestedBy: row.requestedBy,
+        requestedAt: row.requestedAt,
+    };
+}
+export function clearControl(key) {
+    const db = getDb();
+    const result = db
+        .delete(control)
+        .where(eq(control.key, key))
+        .returning({ key: control.key })
+        .all();
+    return result.length > 0;
+}

package/dist/queue/orchestrator.js

@@ -0,0 +1,158 @@
+// Bot-wide orchestrator. One process-wide instance. Polls every
+// ~500ms and does the cross-cutting work no single worker should
+// own:
+//   - Read control table → apply shutdown/pause/reload signals.
+//   - Reclaim stuck claims on outbound (and later: async, browser,
+//     memory_writes).
+//   - Mark dead workers (last_seen past threshold).
+//   - Poll the cron table → enqueue due jobs (Phase 2.2; not yet).
+//   - Log queue depths to a metrics buffer (Phase 7; not yet).
+//
+// Distinct from the sender worker: sender pulls from outbound and
+// sends. Orchestrator pulls signals and metadata; it dispatches but
+// doesn't do per-row work itself.
+import { hostname } from 'os';
+import { and, eq, lt, ne } from 'drizzle-orm';
+import { getDb } from '../db/index.js';
+import { workers } from '../db/schema.js';
+import { logger } from '../logger.js';
+import { reclaimStuckOutbound } from './outbound.js';
+import { clearControl, readControl, requestControl } from './control.js';
+const TICK_INTERVAL_MS = 500;
+const HEARTBEAT_INTERVAL_MS = 5_000;
+const WORKER_DEAD_AFTER_SECONDS = 30;
+const SHUTDOWN_GRACE_MS = 30_000; // total drain window before force-exit
+let workerId = null;
+let stopping = false;
+let draining = false;
+let tickTimer = null;
+let heartbeatTimer = null;
+let exitHook = null;
+function newOrchestratorId() {
+    return `${hostname()}-${process.pid}-orchestrator-0`;
+}
+function registerSelf(id) {
+    const db = getDb();
+    const now = Math.floor(Date.now() / 1000);
+    db.insert(workers)
+        .values({
+        id,
+        kind: 'orchestrator',
+        status: 'idle',
+        currentJob: null,
+        lastSeen: now,
+        startedAt: now,
+    })
+        .onConflictDoUpdate({
+        target: workers.id,
+        set: { status: 'idle', currentJob: null, lastSeen: now, startedAt: now },
+    })
+        .run();
+}
+function heartbeat(id) {
+    const db = getDb();
+    db.update(workers)
+        .set({ lastSeen: Math.floor(Date.now() / 1000) })
+        .where(eq(workers.id, id))
+        .run();
+}
+// Mark workers as dead when their last_seen has aged past the
+// threshold. Used as a liveness signal in observability queries and
+// (eventually) to reclaim their claimed jobs across all queues.
+function markDeadWorkers() {
+    const db = getDb();
+    const cutoff = Math.floor(Date.now() / 1000) - WORKER_DEAD_AFTER_SECONDS;
+    const result = db
+        .update(workers)
+        .set({ status: 'dead' })
+        .where(and(lt(workers.lastSeen, cutoff), ne(workers.status, 'dead')))
+        .returning({ id: workers.id, kind: workers.kind })
+        .all();
+    for (const w of result) {
+        logger.warn({ id: w.id, kind: w.kind }, 'worker marked dead (no heartbeat)');
+    }
+    return result.length;
+}
+function busyWorkerCount() {
+    const db = getDb();
+    const row = db
+        .select({ id: workers.id })
+        .from(workers)
+        .where(eq(workers.status, 'busy'))
+        .all();
+    return row.length;
+}
+async function tick(id) {
+    try {
+        const ctl = readControl('shutdown');
+        if (ctl && !draining) {
+            logger.info({ requestedBy: ctl.requestedBy }, 'shutdown requested via control table');
+            draining = true;
+            // Mark ourselves draining so observability shows it.
+            const db = getDb();
+            db.update(workers)
+                .set({ status: 'draining' })
+                .where(eq(workers.id, id))
+                .run();
+        }
+        // Cross-queue housekeeping. More queues land in later phases.
+        const reclaimed = reclaimStuckOutbound();
+        if (reclaimed > 0) {
+            logger.info({ reclaimed }, 'reclaimed stuck outbound rows');
+        }
+        markDeadWorkers();
+        if (draining) {
+            const busy = busyWorkerCount();
+            if (busy === 0) {
+                logger.info('all workers idle, exiting cleanly');
+                clearControl('shutdown');
+                if (exitHook) {
+                    await exitHook();
+                }
+                process.exit(0);
+            }
+        }
+    }
+    catch (err) {
+        logger.error({ err }, 'orchestrator tick error');
+    }
+}
+export function startOrchestrator(opts = {}) {
+    if (workerId) {
+        logger.warn('orchestrator already started; ignoring');
+        return;
+    }
+    workerId = newOrchestratorId();
+    exitHook = opts.onShutdownDrained ?? null;
+    registerSelf(workerId);
+    heartbeatTimer = setInterval(() => workerId && heartbeat(workerId), HEARTBEAT_INTERVAL_MS);
+    const id = workerId;
+    tickTimer = setInterval(() => {
+        void tick(id);
+    }, TICK_INTERVAL_MS);
+    logger.info({ workerId }, 'orchestrator started');
+}
+export function stopOrchestrator() {
+    stopping = true;
+    if (tickTimer)
+        clearInterval(tickTimer);
+    if (heartbeatTimer)
+        clearInterval(heartbeatTimer);
+}
+// Public entry point for "begin graceful shutdown." Inserts the
+// control row + sets a force-exit timer so we don't hang forever if
+// some worker refuses to drain.
+export function requestShutdown(by) {
+    if (draining)
+        return;
+    requestControl('shutdown', 'requested', by);
+    setTimeout(() => {
+        if (!stopping) {
+            logger.warn({ graceMs: SHUTDOWN_GRACE_MS }, 'graceful shutdown timed out, forcing exit');
+            process.exit(1);
+        }
+    }, SHUTDOWN_GRACE_MS).unref();
+}
+export function isDraining() {
+    return draining;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4t4/heyamigo",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "description": "WhatsApp AI bot powered by Claude with long-term memory, browser control, and role-based access",
   "type": "module",
   "main": "dist/index.js",