herdr-plugin-amq 0.1.7 → 0.1.9

package/src/bridge.mjs

@@ -6,9 +6,15 @@ import {
   getStateDir,
   getConfigDir,
   findAmqRoot,
+  getRepoRootFromAmq,
   getAgentHandles,
   execCmd,
 } from "./config.mjs";
+import { listBacklogTasks, getAgentTaskStats } from "./board.mjs";
+import { loadLocalTemplate, renderTemplate } from "./templates.mjs";
+import { isSafeMailIdentifier, listMaildirMessageFiles, readMaildirMessageFile, writeBoundedFileAtomic } from "./protocol.mjs";
+
+const MAX_DOORBELL_PROMPT_BYTES = 64 * 1024;
 
 function getPidFile() {
   return path.join(getStateDir(), "bridge.pid");
@@ -120,12 +126,13 @@ function healAgentName(handle, dryRun = false) {
 }
 
 function promptAgent(handle, text, dryRun = false) {
+  const boundedText = boundDoorbellPrompt(text);
   if (dryRun || process.env.HERDR_DISABLE_PROMPT === "1" || process.env.NODE_ENV === "test") {
-    console.log(`[bridge] DRY: would prompt ${handle}: ${text.slice(0, 60)}...`);
+    console.log(`[bridge] DRY: would prompt ${handle}: ${boundedText.slice(0, 60)}...`);
     return true;
   }
   try {
-    runHerdr(["agent", "prompt", handle, text]);
+    runHerdr(["agent", "prompt", handle, boundedText]);
     return true;
   } catch (err) {
     console.warn(`[bridge] Warning: prompt ${handle} failed: ${err.message}`);
@@ -149,12 +156,50 @@ function recordAlert(handle, count, from, dryRun = false) {
   } catch {}
 }
 
+function safeStateText(value, maxLength = 512) {
+  if (typeof value !== "string") return "";
+  return value.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim().slice(0, maxLength);
+}
+
+function sanitizeDeliveredState(value) {
+  const delivered = {};
+  const deliveredTasks = {};
+  if (!value || typeof value !== "object") return { delivered, deliveredTasks, recoveryRequired: true };
+
+  for (const [id, entry] of Object.entries(value.delivered || {})) {
+    if (!isSafeMailIdentifier(id) || !entry || typeof entry !== "object") continue;
+    if (!isSafeMailIdentifier(entry.to, 128) || !isSafeMailIdentifier(entry.from, 128)) continue;
+    if (typeof entry.at !== "string") continue;
+    delivered[id] = {
+      at: entry.at,
+      to: entry.to,
+      from: entry.from,
+      attempts: Number.isFinite(entry.attempts) ? Math.max(1, Math.trunc(entry.attempts)) : 1,
+    };
+  }
+
+  for (const [id, entry] of Object.entries(value.deliveredTasks || {})) {
+    if (!isSafeMailIdentifier(id) || !entry || typeof entry !== "object") continue;
+    if (!isSafeMailIdentifier(entry.to, 128) || typeof entry.at !== "string") continue;
+    deliveredTasks[id] = {
+      at: entry.at,
+      to: entry.to,
+      title: safeStateText(entry.title),
+      attempts: Number.isFinite(entry.attempts) ? Math.max(1, Math.trunc(entry.attempts)) : 1,
+    };
+  }
+
+  return { delivered, deliveredTasks, recoveryRequired: false };
+}
+
 function loadDeliveredState() {
   const stateFile = getStateFile();
   try {
-    return JSON.parse(fs.readFileSync(stateFile, "utf8"));
+    const content = readMaildirMessageFile(stateFile, 2 * 1024 * 1024);
+    if (content === null) return { delivered: {}, deliveredTasks: {}, recoveryRequired: true };
+    return sanitizeDeliveredState(JSON.parse(content));
   } catch {
-    return { delivered: {} };
+    return { delivered: {}, deliveredTasks: {}, recoveryRequired: true };
   }
 }
 
@@ -167,7 +212,14 @@ function saveDeliveredState(state) {
       delete state.delivered[id];
     }
   }
-  fs.writeFileSync(stateFile, JSON.stringify(state, null, 1), "utf8");
+  const taskIds = Object.keys(state.deliveredTasks || {});
+  if (taskIds.length > 2000) {
+    taskIds.sort();
+    for (const id of taskIds.slice(0, taskIds.length - 1500)) {
+      delete state.deliveredTasks[id];
+    }
+  }
+  writeBoundedFileAtomic(stateFile, JSON.stringify(state, null, 1), 2 * 1024 * 1024);
 }
 
 export function listInbox(amqRoot, handle) {
@@ -190,11 +242,12 @@ export function listInbox(amqRoot, handle) {
   try {
     const newDir = path.join(amqRoot, "agents", handle, "inbox", "new");
     if (!fs.existsSync(newDir)) return [];
-    const files = fs.readdirSync(newDir).filter((f) => !f.startsWith("."));
+    const files = listMaildirMessageFiles(newDir).filter((f) => !f.startsWith("."));
     const msgs = [];
     for (const f of files) {
       const fullPath = path.join(newDir, f);
-      const content = fs.readFileSync(fullPath, "utf8");
+      const content = readMaildirMessageFile(fullPath);
+      if (content === null) continue;
       const jsonMatch = content.match(/^---json\r?\n([\s\S]*?)\r?\n---/);
       if (jsonMatch) {
         try {
@@ -239,16 +292,115 @@ export function listInbox(amqRoot, handle) {
   }
 }
 
-const buildDoorbellPrompt = (handle, msgs) => {
-  const senders = [...new Set(msgs.map((m) => m.from))].join(", ");
-  const n = msgs.length;
-  return (
-    `AMQ doorbell: ${n} new message(s) in your inbox (from ${senders}). ` +
-    `Run: amq drain --me ${handle} --include-body, then reply to the sender on the same ` +
-    `thread with amq reply --id <msg_id>. After replying, resume your work.`
-  );
+function boundDoorbellPrompt(text, maxBytes = MAX_DOORBELL_PROMPT_BYTES) {
+  const value = typeof text === "string" ? text : String(text ?? "");
+  const bytes = Buffer.from(value, "utf8");
+  return bytes.length <= maxBytes
+    ? value
+    : bytes.subarray(0, Math.max(0, maxBytes)).toString("utf8");
+}
+
+function safeCount(value) {
+  const count = Number(value);
+  return Number.isFinite(count) ? Math.max(0, Math.trunc(count)) : 0;
+}
+
+function safeSender(value) {
+  const sender = typeof value === "string" ? value.trim() : "";
+  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(sender) ? sender : "unknown";
+}
+
+function normalizeDoorbellStats(taskStatsOrBacklog) {
+  const raw = Array.isArray(taskStatsOrBacklog)
+    ? { backlog: taskStatsOrBacklog.length, blocked: 0, doing: 0, done: 0 }
+    : taskStatsOrBacklog && typeof taskStatsOrBacklog === "object"
+      ? taskStatsOrBacklog
+      : { backlog: 0, blocked: 0, doing: 0, done: 0 };
+  const stats = {
+    backlog: safeCount(raw.backlog),
+    blocked: safeCount(raw.blocked),
+    doing: safeCount(raw.doing),
+    done: safeCount(raw.done),
+  };
+  stats.total = safeCount(raw.total ?? Object.values(stats).reduce((sum, value) => sum + value, 0));
+  return stats;
+}
+
+function buildDoorbellContext(handle, msgs, stats) {
+  return {
+    agent: { handle },
+    mail: {
+      count: safeCount(msgs.length),
+      senders: [...new Set(msgs.map((message) => safeSender(message.from)))].slice(0, 16).join(", "),
+    },
+    board: stats,
+  };
+}
+
+function buildRequiredDoorbellActions(handle, context) {
+  const actions = [];
+  if (context.mail.count > 0) {
+    actions.push(`Run: herdr-amq mail drain --me ${handle} --include-body.`);
+  }
+  if (context.board.backlog > 0) {
+    actions.push(`Run: herdr-amq task drain --me ${handle}; claim with herdr-amq task next --me ${handle}.`);
+  }
+  if (context.mail.count > 0) {
+    actions.push("Reply only when a message explicitly requests action or asks a question.");
+  }
+  return actions.join(" ");
+}
+
+function buildDefaultDoorbellPrompt(handle, msgs, stats) {
+  const context = buildDoorbellContext(handle, msgs, stats);
+  const taskDetails = [];
+  if (context.board.blocked > 0) taskDetails.push(`${context.board.blocked} blocked`);
+  if (context.board.doing > 0) taskDetails.push(`${context.board.doing} in progress`);
+  if (context.board.done > 0) taskDetails.push(`${context.board.done} done`);
+  const details = taskDetails.length ? ` (${taskDetails.join(", ")})` : "";
+  let summary;
+  if (context.mail.count > 0 && context.board.backlog > 0) {
+    summary = `AMQ & Task doorbell: ${context.mail.count} new message(s) from ${context.mail.senders}. You have ${context.board.backlog} task(s) in backlog${details}.`;
+  } else if (context.board.backlog > 0) {
+    summary = `Task doorbell: You have ${context.board.backlog} task(s) in backlog${details}.`;
+  } else {
+    summary = `AMQ doorbell: ${context.mail.count} new message(s) in your inbox from ${context.mail.senders}${details}.`;
+  }
+  return boundDoorbellPrompt(`${summary} ${buildRequiredDoorbellActions(handle, context)}`.trim());
+}
+
+export const buildDoorbellPrompt = (handle, msgs = [], taskStatsOrBacklog = null, templateSource = null) => {
+  const stats = normalizeDoorbellStats(taskStatsOrBacklog);
+  const context = buildDoorbellContext(handle, msgs, stats);
+  const fallback = buildDefaultDoorbellPrompt(handle, msgs, stats);
+  if (!templateSource) return fallback;
+
+  try {
+    const custom = renderTemplate(templateSource, context).trim();
+    if (!custom) return fallback;
+    const requiredActions = `Required actions: ${buildRequiredDoorbellActions(handle, context)}`;
+    const bodyLimit = Math.max(0, MAX_DOORBELL_PROMPT_BYTES - Buffer.byteLength(requiredActions, "utf8") - 2);
+    return `${boundDoorbellPrompt(custom, bodyLimit)}\n\n${requiredActions}`;
+  } catch {
+    return fallback;
+  }
 };
 
+export const DEFAULT_DOORBELL_COOLDOWN_MS = 45000; // 45s cooldown window
+
+/**
+ * Determines whether an item was recently doorbelled and is still in-flight.
+ * If the item has not been drained after the cooldown window, it no longer
+ * counts as delivered and will be re-doorbelled.
+ */
+export function isItemPendingDrain(deliveryEntry, cooldownMs = DEFAULT_DOORBELL_COOLDOWN_MS, force = false) {
+  if (force) return false;
+  if (!deliveryEntry || !deliveryEntry.at) return false;
+  const deliveredAt = new Date(deliveryEntry.at).getTime();
+  if (isNaN(deliveredAt)) return false;
+  return Date.now() - deliveredAt < cooldownMs;
+}
+
 // ─── Doorbell Pass ────────────────────────────────────────────────────────────
 
 export function runDoorbellPass({
@@ -256,6 +408,14 @@ export function runDoorbellPass({
   handles = null,
   targetHandle = null,
   dryRun = false,
+  force = false,
+  allowPrompt = false,
+  persistState = false,
+  state: injectedState = null,
+  getStatus = getAgentStatus,
+  healName = healAgentName,
+  prompt = promptAgent,
+  cooldownMs = parseInt(process.env.HERDR_DOORBELL_COOLDOWN_MS || String(DEFAULT_DOORBELL_COOLDOWN_MS), 10),
 } = {}) {
   if (!amqRoot) {
     return { ok: false, error: "No .agent-mail queue found." };
@@ -266,59 +426,113 @@ export function runDoorbellPass({
     : (handles && handles.length > 0 ? handles : getAgentHandles(amqRoot));
 
   if (!agentList.length) {
-    return { ok: true, checked: 0, doorbelled: 0, message: "No registered agents found." };
+    return { ok: true, checked: 0, doorbelled: 0, doorbelledTasks: 0, message: "No registered agents found." };
   }
 
-  const state = loadDeliveredState();
+  const repoRoot = getRepoRootFromAmq(amqRoot);
+  const doorbellTemplate = loadLocalTemplate(amqRoot, "doorbell");
+  const state = injectedState || loadDeliveredState();
   state.delivered = state.delivered || {};
+  state.deliveredTasks = state.deliveredTasks || {};
 
   let doorbelledCount = 0;
+  let doorbelledTasksCount = 0;
   const results = [];
 
   for (const handle of agentList) {
+    if (typeof handle !== "string" || !/^[a-z0-9_-]{1,128}$/.test(handle)) {
+      results.push({ handle: String(handle), status: "invalid", count: 0, tasksCount: 0, action: "invalid_handle" });
+      continue;
+    }
     const rawMsgs = listInbox(amqRoot, handle);
     // Ignore self-messages
     const msgs = rawMsgs.filter((m) => m.from !== handle);
+    // If message is still in inbox/new after cooldown, the agent did NOT drain it!
+    const undeliveredMsgs = msgs.filter((m) => !isItemPendingDrain(state.delivered[m.id], cooldownMs, force));
 
-    if (!msgs.length) continue;
+    const backlogTasks = listBacklogTasks(repoRoot, amqRoot, handle);
+    // If task is still in backlog after cooldown, the agent did NOT claim/drain it!
+    const undeliveredTasks = backlogTasks.filter((t) => !isItemPendingDrain(state.deliveredTasks?.[t.id], cooldownMs, force));
 
-    // Filter messages not yet delivered
-    const undelivered = msgs.filter((m) => !state.delivered[m.id]);
-    if (!undelivered.length) continue;
+    if (!undeliveredMsgs.length && !undeliveredTasks.length) continue;
 
-    let status = getAgentStatus(handle);
+    let status = getStatus(handle);
     if (status === "missing") {
-      const healed = healAgentName(handle, dryRun);
+      const healed = healName(
+        handle,
+        dryRun || !allowPrompt || process.env.HERDR_DISABLE_PROMPT === "1"
+      );
       if (healed) status = getAgentStatus(handle);
     }
 
+    const taskStats = getAgentTaskStats(repoRoot, amqRoot, handle);
+    taskStats.backlog = undeliveredTasks.length > 0 ? undeliveredTasks.length : backlogTasks.length;
+
     if (status === "idle" || status === "done") {
-      const text = buildDoorbellPrompt(handle, undelivered);
-      const ok = promptAgent(handle, text, dryRun);
+      const text = buildDoorbellPrompt(handle, undeliveredMsgs, taskStats, doorbellTemplate?.source || null);
+      const ok = prompt(handle, text, dryRun || !allowPrompt);
       if (ok) {
-        doorbelledCount += undelivered.length;
+        doorbelledCount += undeliveredMsgs.length;
+        doorbelledTasksCount += undeliveredTasks.length;
         if (!dryRun) {
-          for (const m of undelivered) {
+          for (const m of undeliveredMsgs) {
+            const prev = state.delivered[m.id];
             state.delivered[m.id] = {
               at: new Date().toISOString(),
               to: handle,
               from: m.from,
+              attempts: (prev?.attempts || 0) + 1,
+            };
+          }
+          for (const t of undeliveredTasks) {
+            const prev = state.deliveredTasks[t.id];
+            state.deliveredTasks[t.id] = {
+              at: new Date().toISOString(),
+              to: handle,
+              title: t.title,
+              attempts: (prev?.attempts || 0) + 1,
             };
           }
         }
-        results.push({ handle, status, count: undelivered.length, action: "prompted" });
+        results.push({
+          handle,
+          status,
+          count: undeliveredMsgs.length,
+          tasksCount: undeliveredTasks.length,
+          action: allowPrompt && !dryRun ? "prompted" : "simulated",
+        });
       }
     } else if (status === "working") {
-      results.push({ handle, status, count: undelivered.length, action: "working_wait" });
+      results.push({
+        handle,
+        status,
+        count: undeliveredMsgs.length,
+        tasksCount: undeliveredTasks.length,
+        action: "working_wait",
+      });
     } else if (status === "blocked") {
-      recordAlert(handle, undelivered.length, undelivered[0]?.from, dryRun);
-      results.push({ handle, status, count: undelivered.length, action: "alert_blocked" });
+      if (undeliveredMsgs.length) {
+        recordAlert(handle, undeliveredMsgs.length, undeliveredMsgs[0]?.from, dryRun || !allowPrompt);
+      }
+      results.push({
+        handle,
+        status,
+        count: undeliveredMsgs.length,
+        tasksCount: undeliveredTasks.length,
+        action: "alert_blocked",
+      });
     } else {
-      results.push({ handle, status, count: undelivered.length, action: "unknown_state" });
+      results.push({
+        handle,
+        status,
+        count: undeliveredMsgs.length,
+        tasksCount: undeliveredTasks.length,
+        action: "unknown_state",
+      });
     }
   }
 
-  if (!dryRun && doorbelledCount > 0) {
+  if (allowPrompt && persistState && !dryRun && (doorbelledCount > 0 || doorbelledTasksCount > 0)) {
     saveDeliveredState(state);
   }
 
@@ -327,6 +541,7 @@ export function runDoorbellPass({
     amqRoot,
     agentsChecked: agentList.length,
     doorbelled: doorbelledCount,
+    doorbelledTasks: doorbelledTasksCount,
     results,
   };
 }
@@ -359,7 +574,7 @@ export function startDaemonLoop({ interval = 3000, dryRun = false } = {}) {
   const tick = () => {
     try {
       const handles = getAgentHandles(amqRoot);
-      const res = runDoorbellPass({ amqRoot, handles, dryRun });
+      const res = runDoorbellPass({ amqRoot, handles, dryRun, allowPrompt: true, persistState: true });
       if (res.doorbelled > 0) {
         console.log(`[bridge] Doorbelled ${res.doorbelled} message(s)`);
       }

package/src/config.mjs

@@ -1,13 +1,37 @@
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function getPluginVersion() {
+  try {
+    const pkgPath = path.resolve(__dirname, "../package.json");
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+      return pkg.version || "unknown";
+    }
+  } catch {}
+  return "unknown";
+}
 
 export function getHerdrBin() {
   return process.env.HERDR_BIN_PATH || "herdr";
 }
 
 export function getStateDir() {
-  const dir = process.env.HERDR_PLUGIN_STATE_DIR || path.join(process.env.HOME || "/tmp", ".herdr-amq-state");
+  if (process.env.HERDR_PLUGIN_STATE_DIR) {
+    const dir = process.env.HERDR_PLUGIN_STATE_DIR;
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+  const legacyDir = path.join(process.env.HOME || "/tmp", ".herdr-amq-state");
+  if (fs.existsSync(legacyDir)) {
+    return legacyDir;
+  }
+  const base = process.env.XDG_STATE_HOME || path.join(process.env.HOME || "/tmp", ".local", "state");
+  const dir = path.join(base, "herdr-amq");
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }
@@ -22,7 +46,17 @@ export function getRepoRootFromAmq(amqRoot) {
 }
 
 export function getConfigDir() {
-  const dir = process.env.HERDR_PLUGIN_CONFIG_DIR || path.join(process.env.HOME || "/tmp", ".herdr-amq-config");
+  if (process.env.HERDR_PLUGIN_CONFIG_DIR) {
+    const dir = process.env.HERDR_PLUGIN_CONFIG_DIR;
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+  const legacyDir = path.join(process.env.HOME || "/tmp", ".herdr-amq-config");
+  if (fs.existsSync(legacyDir)) {
+    return legacyDir;
+  }
+  const base = process.env.XDG_CONFIG_HOME || path.join(process.env.HOME || "/tmp", ".config");
+  const dir = path.join(base, "herdr-amq");
   if (!fs.existsSync(dir)) {
     fs.mkdirSync(dir, { recursive: true });
   }