@c4t4/heyamigo 0.9.1 → 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/memory/digest-flag.js

@@ -14,6 +14,7 @@ const KINDS = [
     'JOURNAL-NEW',
     'ASYNC',
     'ASYNC-BROWSER',
+    'SEND-TEXT',
 ];
 // Walk backwards from the end of the string, tracking bracket depth, to find
 // the `[` that matches the final `]`. Returns the tag kind, its payload, and
@@ -74,6 +75,7 @@ export function extractFlags(reply) {
     const journalCreates = [];
     const asyncTasks = [];
     const asyncBrowserTasks = [];
+    const sendTexts = [];
     while (true) {
         const peeled = peelTrailingTag(current);
         if (!peeled)
@@ -105,6 +107,11 @@ export function extractFlags(reply) {
                 asyncBrowserTasks.unshift({ description: payload });
             }
         }
+        else if (kind === 'SEND-TEXT') {
+            const parsed = parseSendTextPayload(payload);
+            if (parsed)
+                sendTexts.unshift(parsed);
+        }
     }
     return {
         clean: current,
@@ -113,6 +120,7 @@ export function extractFlags(reply) {
         journalCreates,
         asyncTasks,
         asyncBrowserTasks,
+        sendTexts,
     };
 }
 // Legacy helper kept so existing callers still compile.
@@ -121,6 +129,26 @@ export function extractDigestFlag(reply) {
     return { clean: r.clean, flag: r.digest };
 }
 const JOURNAL_SEP_RE = /\s*(?:[—\-–]|:)\s*/;
+// Parse `address=<addr> body="..."` style key=value payload.
+// Body is delimited by double quotes; everything else by whitespace.
+// Returns null if address or body is missing.
+function parseSendTextPayload(payload) {
+    // Grab body="..." first (longest match so quoted body can contain spaces)
+    const bodyMatch = payload.match(/\bbody\s*=\s*"((?:[^"\\]|\\.)*)"/);
+    if (!bodyMatch)
+        return null;
+    const body = bodyMatch[1]
+        .replace(/\\"/g, '"')
+        .replace(/\\\\/g, '\\');
+    if (!body.trim())
+        return null;
+    // Strip the body=... portion so address parsing doesn't trip on it
+    const withoutBody = payload.replace(bodyMatch[0], '').trim();
+    const addrMatch = withoutBody.match(/\baddress\s*=\s*([^\s]+)/);
+    if (!addrMatch)
+        return null;
+    return { address: addrMatch[1], body };
+}
 function parseJournalPayload(payload) {
     // Split on first em-dash, en-dash, hyphen, or colon between slug and note.
     const match = payload.match(/^([a-zA-Z0-9][a-zA-Z0-9-]*)(.*)$/);

package/dist/queue/async-tasks.js

@@ -124,7 +124,20 @@ async function executeAsyncTask(task) {
     // as markers; clean pre-marker text is only sent to chat when short (a
     // failure explanation or tight ack) or when no markers fired at all.
     const { extractFlags } = await import('../memory/digest-flag.js');
-    const { clean, digest, journals, journalCreates } = extractFlags(output);
+    const { clean, digest, journals, journalCreates, sendTexts } = extractFlags(output);
+    // SEND-TEXT: async task wants to text a different chat too.
+    if (sendTexts.length > 0) {
+        const { enqueueOutbound } = await import('./outbound.js');
+        for (let i = 0; i < sendTexts.length; i++) {
+            const t = sendTexts[i];
+            enqueueOutbound({
+                address: t.address,
+                kind: 'text',
+                text: t.body,
+                idempotencyKey: `async-sendtext-${task.id}-${i}`,
+            });
+        }
+    }
     // Journal creates run first so an entry flagged in the same output against
     // a new slug lands correctly.
     const { appendEntry, createJournal, getJournal, isValidSlug } = await import('../memory/journals.js');
@@ -402,7 +415,19 @@ async function runBrowserTask(task) {
     }
     // Route markers the same way the general async lane does.
     const { extractFlags } = await import('../memory/digest-flag.js');
-    const { clean, digest, journals, journalCreates } = extractFlags(reply);
+    const { clean, digest, journals, journalCreates, sendTexts } = extractFlags(reply);
+    if (sendTexts.length > 0) {
+        const { enqueueOutbound } = await import('./outbound.js');
+        for (let i = 0; i < sendTexts.length; i++) {
+            const t = sendTexts[i];
+            enqueueOutbound({
+                address: t.address,
+                kind: 'text',
+                text: t.body,
+                idempotencyKey: `browser-sendtext-${task.id}-${i}`,
+            });
+        }
+    }
     const { appendEntry, createJournal, getJournal, isValidSlug } = await import('../memory/journals.js');
     for (const op of journalCreates) {
         if (!isValidSlug(op.slug))

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/dist/queue/worker.js

@@ -7,6 +7,7 @@ import { extractFlags } from '../memory/digest-flag.js';
 import { appendEntry, createJournal, getJournal, isValidSlug, } from '../memory/journals.js';
 import { scheduleDigest } from '../memory/scheduler.js';
 import { enqueueAsyncTask, enqueueBrowserTask } from './async-tasks.js';
+import { enqueueOutbound } from './outbound.js';
 function isStaleSessionError(err) {
     return (err instanceof Error &&
         err.message.includes('No conversation found'));
@@ -39,7 +40,7 @@ async function callClaude(job) {
     if (job.senderNumber) {
         addDailyTokens(job.senderNumber, usage.inputTokens + usage.outputTokens);
     }
-    const { clean, digest, journals, journalCreates, asyncTasks, asyncBrowserTasks, } = extractFlags(reply);
+    const { clean, digest, journals, journalCreates, asyncTasks, asyncBrowserTasks, sendTexts, } = extractFlags(reply);
     if (digest) {
         logger.info({ jid: job.jid, number: job.senderNumber, reason: digest }, 'DIGEST flag raised, scheduling');
         scheduleDigest({
@@ -105,6 +106,19 @@ async function callClaude(job) {
             allowedTools: job.allowedTools ?? 'all',
         });
     }
+    // SEND-TEXT: cross-chat text send. Agent specified the destination
+    // address explicitly. Just drops a row in outbound; sender worker
+    // dispatches by channel.
+    for (let i = 0; i < sendTexts.length; i++) {
+        const t = sendTexts[i];
+        enqueueOutbound({
+            address: t.address,
+            kind: 'text',
+            text: t.body,
+            idempotencyKey: `sendtext-${job.jid}-${Date.now()}-${i}`,
+        });
+        logger.info({ from: job.jid, to: t.address, chars: t.body.length }, 'SEND-TEXT enqueued');
+    }
     return {
         reply: clean,
         stats: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4t4/heyamigo",
-  "version": "0.9.1",
+  "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",