@cohortapp/agent-sdk 2.3.0

package/scripts/poller/gmail-poller.mjs

@@ -0,0 +1,192 @@
+// Gmail Poller — polls the agent's inbox via native Node.js IMAP.
+// Uses imapflow + mailparser to fetch unseen emails from the agent's
+// configured email address (config/agent.json#/email) and write them as
+// .json files to state/inbox/gmail/.
+//
+// All IMAP logic is in imap-client.mjs, shared with the principal poller.
+
+import { readFileSync, readdirSync, renameSync } from "fs";
+import { join } from "path";
+import { readCursor, writeCursor, AGENT_REPO_DIR } from "./utils.mjs";
+import { pollImapInbox } from "./imap-client.mjs";
+
+const GMAIL_INBOX_DIR = join(AGENT_REPO_DIR, "state", "inbox", "gmail");
+const MAX_ITEMS_PER_POLL = 10;
+
+// Load agent identity once. Email + first-name used as account labels.
+let _agent = null;
+function loadAgent() {
+  if (_agent) return _agent;
+  try {
+    _agent = JSON.parse(readFileSync(join(AGENT_REPO_DIR, "config/agent.json"), "utf-8"));
+  } catch {
+    _agent = { firstName: "agent", email: "" };
+  }
+  return _agent;
+}
+
+/**
+ * Load the agent's Gmail app password from env or the agent's .env file.
+ */
+function loadGmailPassword() {
+  if (process.env.GMAIL_APP_PASSWORD) return process.env.GMAIL_APP_PASSWORD;
+  try {
+    const envFile = readFileSync(join(AGENT_REPO_DIR, ".env"), "utf-8");
+    for (const line of envFile.split("\n")) {
+      if (line.startsWith("GMAIL_APP_PASSWORD=")) {
+        let val = line.split("=", 2)[1].trim();
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+          val = val.slice(1, -1);
+        }
+        return val;
+      }
+    }
+  } catch { /* no .env file */ }
+  return "";
+}
+
+/**
+ * Extract sender name from email "From" header.
+ */
+function extractSenderName(from) {
+  const match = from.match(/^"?([^"<]+)"?\s*</);
+  return match ? match[1].trim() : from.trim();
+}
+
+/**
+ * Extract sender email from "From" header.
+ */
+function extractSenderEmail(from) {
+  const match = from.match(/<([^>]+)>/);
+  return match ? match[1].trim() : from.trim();
+}
+
+/**
+ * Determine sender privilege from email address. The principal (CEO) is
+ * recognised by matching against the agent's `principal.email` or
+ * `principal.firstName` from config/agent.json — never hardcode names.
+ *
+ * INTERNAL classification comes from CONFIG, never a hardcoded domain: the
+ * optional `internal_domains[]` array in config/agent.json, defaulting to the
+ * domain of the agent's own `email` there. Exact domain match (not substring)
+ * so `evil-corp.example.attacker.net` never rides an `example` allowance.
+ */
+function internalDomains(me) {
+  const configured = Array.isArray(me.internal_domains)
+    ? me.internal_domains.map((d) => String(d).toLowerCase().replace(/^@/, "")).filter(Boolean)
+    : [];
+  if (configured.length) return configured;
+  const own = String(me.email || "");
+  const at = own.lastIndexOf("@");
+  return at > 0 ? [own.slice(at + 1).toLowerCase()] : [];
+}
+
+function resolveSenderPrivilege(email) {
+  const lower = email.toLowerCase();
+  const me = loadAgent();
+  const principalEmail = (me.principal?.email || "").toLowerCase();
+  const principalFirst = (me.principal?.firstName || "").toLowerCase();
+  if (principalEmail && lower === principalEmail) return "ceo";
+  if (principalFirst && lower.includes(principalFirst)) return "ceo";
+  const domain = lower.includes("@") ? lower.slice(lower.lastIndexOf("@") + 1) : "";
+  if (domain && internalDomains(me).includes(domain)) return "internal";
+  return "external";
+}
+
+export async function pollGmail() {
+  const items = [];
+  const errors = [];
+
+  // Run native IMAP poll for the agent's configured email address.
+  const me = loadAgent();
+  const agentSlug = (me.firstName || "agent").toLowerCase();
+  try {
+    const result = await pollImapInbox({
+      email: me.email,
+      password: loadGmailPassword(),
+      account: agentSlug,
+      fileSuffix: "email",
+      eventType: `${agentSlug}_email`,
+      logPrefix: `[${agentSlug}-gmail]`,
+    });
+    if (result.errors.length > 0) {
+      errors.push(...result.errors);
+    }
+  } catch (err) {
+    const msg = `Agent Gmail IMAP poll failed: ${err.message}`;
+    console.error(`[gmail] ${msg}`);
+    errors.push(msg);
+  }
+
+  // Read resulting JSON files (same as before — the IMAP client writes them)
+  try {
+    const files = readdirSync(GMAIL_INBOX_DIR)
+      .filter((f) => f.endsWith("-email.json") && !f.endsWith(".processed"))
+      .sort()
+      .slice(0, MAX_ITEMS_PER_POLL);
+
+    for (const file of files) {
+      try {
+        const raw = readFileSync(join(GMAIL_INBOX_DIR, file), "utf-8");
+        const data = JSON.parse(raw);
+        const email = data.email || {};
+        const senderEmail = extractSenderEmail(email.from || "unknown");
+        const senderName = extractSenderName(email.from || "unknown");
+        const privilege = resolveSenderPrivilege(senderEmail);
+        const id = file.replace(/-email\.json$/, "");
+
+        // Pass through attachment metadata
+        const attachments = data.attachments
+          ? data.attachments.map((a) => ({
+              name: a.name || "unnamed",
+              mimetype: a.mimetype || "unknown",
+              size: a.size || 0,
+              local_path: a.local_path || null,
+            }))
+          : undefined;
+
+        items.push({
+          id,
+          service: "gmail",
+          channel: `email/${senderEmail}`,
+          sender: senderName,
+          sender_email: senderEmail,
+          sender_privilege: privilege,
+          timestamp: data.received_at || email.date || new Date().toISOString(),
+          subject: (email.subject || "").replace(/\r\n/g, " ").trim(),
+          content: `Email from ${email.from || "unknown"}\nSubject: ${email.subject || "(no subject)"}\nDate: ${email.date || "unknown"}`,
+          thread_id: email.message_id || "",
+          is_reply: (email.subject || "").toLowerCase().startsWith("re:"),
+          attachments,
+          priority_signals: {
+            from_ceo: privilege === "ceo",
+            tagged_urgent: /urgent|asap|critical/i.test(email.subject || ""),
+            contains_deadline: /deadline|due|by\s+(monday|tuesday|wednesday|thursday|friday|tomorrow|end of)/i.test(email.subject || ""),
+            mentions_agent: new RegExp(agentSlug, "i").test(email.subject || ""),
+          },
+          raw_ref: `gmail:${id}`,
+          _inbox_file: file,
+        });
+
+        // Mark as processed after reading
+        try {
+          renameSync(
+            join(GMAIL_INBOX_DIR, file),
+            join(GMAIL_INBOX_DIR, file + ".processed"),
+          );
+        } catch {
+          // Already processed
+        }
+      } catch (err) {
+        errors.push(`Gmail file ${file}: ${err.message}`);
+      }
+    }
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      errors.push(`Gmail inbox scan: ${err.message}`);
+    }
+  }
+
+  writeCursor("gmail", new Date().toISOString());
+  return { items, errors };
+}

package/scripts/poller/imap-client.mjs

@@ -0,0 +1,289 @@
+// imap-client.mjs — Shared native IMAP polling for the agent's inbox and
+// any other inbox the agent has explicit access to (e.g. principal-gmail).
+// Replaces external Python scripts with direct Node.js IMAP via imapflow.
+//
+// Each inbox gets its own credentials and file-naming convention, but the
+// connect → search UNSEEN → fetch headers+body → write JSON → disconnect
+// flow is identical and lives here.
+
+import { ImapFlow } from "imapflow";
+import { writeFileSync, existsSync, readFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { createHash } from "crypto";
+import { AGENT_REPO_DIR } from "./utils.mjs";
+
+const INBOX_DIR = join(AGENT_REPO_DIR, "state", "inbox", "gmail");
+const ATTACHMENTS_DIR = join(AGENT_REPO_DIR, "state", "inbox", "attachments");
+const MAX_EMAILS_PER_CYCLE = 20;
+const SNIPPET_LENGTH = 500;
+const IMAP_TIMEOUT_MS = 25_000;
+
+// ── Helpers ─────────────────────────────────────────────────────────────
+
+function messageIdHash(messageId, fromAddr = "", subject = "", date = "") {
+  const key = messageId || `${fromAddr}${subject}${date}`;
+  return createHash("md5").update(key).digest("hex").slice(0, 16);
+}
+
+function stripHtml(html) {
+  let text = html.replace(/<(style|script)[^>]*>[\s\S]*?<\/\1>/gi, "");
+  text = text.replace(/<br\s*\/?>/gi, "\n");
+  text = text.replace(/<\/(p|div|tr|li)>/gi, "\n");
+  text = text.replace(/<[^>]+>/g, "");
+  text = text.replace(/&nbsp;/g, " ").replace(/&amp;/g, "&");
+  text = text.replace(/&lt;/g, "<").replace(/&gt;/g, ">");
+  text = text.replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+  text = text.replace(/&\w+;/g, "");
+  text = text.replace(/[ \t]+/g, " ");
+  text = text.replace(/\n{3,}/g, "\n\n");
+  return text.trim();
+}
+
+function extractSnippet(textBody, htmlBody, maxLen = SNIPPET_LENGTH) {
+  let body = (textBody || "").trim();
+  if (!body && htmlBody) body = stripHtml(htmlBody);
+  return body.length > maxLen ? body.slice(0, maxLen) + "..." : body;
+}
+
+function isAlreadyProcessed(midHash, suffix) {
+  const baseName = `${midHash}-${suffix}.json`;
+  return (
+    existsSync(join(INBOX_DIR, baseName)) ||
+    existsSync(join(INBOX_DIR, baseName + ".processed"))
+  );
+}
+
+// ── Cursor Management ───────────────────────────────────────────────────
+
+function cursorPath(account) {
+  return join(AGENT_REPO_DIR, "state", "polling", `${account}-gmail-cursor.yaml`);
+}
+
+function readImapCursor(account) {
+  const path = cursorPath(account);
+  try {
+    const content = readFileSync(path, "utf-8");
+    const cursor = {};
+    for (const line of content.split("\n")) {
+      const m = line.match(/^(\w+):\s*"?([^"\n]*)"?/);
+      if (m) {
+        let val = m[2].trim();
+        if (val === "null" || val === "") val = null;
+        cursor[m[1]] = val;
+      }
+    }
+    return {
+      last_poll: cursor.last_poll || null,
+      last_message_id: cursor.last_message_id || null,
+      messages_processed: parseInt(cursor.messages_processed || "0", 10) || 0,
+    };
+  } catch {
+    return { last_poll: null, last_message_id: null, messages_processed: 0 };
+  }
+}
+
+function writeImapCursor(account, lastPoll, lastMessageId, messagesProcessed) {
+  const path = cursorPath(account);
+  mkdirSync(dirname(path), { recursive: true });
+  const lp = lastPoll ? `"${lastPoll}"` : "null";
+  const lm = lastMessageId ? `"${lastMessageId}"` : "null";
+  writeFileSync(
+    path,
+    `last_poll: ${lp}\nlast_message_id: ${lm}\nmessages_processed: ${messagesProcessed}\n`,
+  );
+}
+
+// ── Attachment Extraction ───────────────────────────────────────────────
+
+function saveAttachments(parsed, midHash) {
+  const attachments = [];
+  if (!parsed.attachments || parsed.attachments.length === 0) return attachments;
+
+  mkdirSync(ATTACHMENTS_DIR, { recursive: true });
+  for (const att of parsed.attachments) {
+    if (!att.filename) continue;
+    // Skip tiny inline images (likely signatures)
+    if ((att.contentType || "").startsWith("image/") && att.content && att.content.length < 1024) continue;
+
+    const safeName = att.filename.replace(/[^a-zA-Z0-9._-]/g, "_");
+    const localName = `${midHash}-${safeName}`;
+    const localPath = join(ATTACHMENTS_DIR, localName);
+    try {
+      writeFileSync(localPath, att.content);
+      attachments.push({
+        name: att.filename,
+        mimetype: att.contentType || "unknown",
+        size: att.content.length,
+        local_path: localPath,
+      });
+    } catch {
+      // Non-fatal
+    }
+  }
+  return attachments;
+}
+
+// ── Core IMAP Poll ──────────────────────────────────────────────────────
+
+/**
+ * Poll a Gmail inbox via IMAP and write new messages as JSON to the inbox dir.
+ *
+ * @param {object} opts
+ * @param {string} opts.email       — Email address to poll
+ * @param {string} opts.password    — Gmail app password
+ * @param {string} opts.account     — Account slug for cursor/file naming (e.g. agent's first name)
+ * @param {string} opts.fileSuffix  — JSON file suffix
+ * @param {string} opts.eventType   — Event type tag
+ * @param {string} opts.logPrefix   — Console log prefix
+ * @returns {Promise<{newCount: number, errors: string[]}>}
+ */
+export async function pollImapInbox({
+  email: emailAddr,
+  password,
+  account,
+  fileSuffix,
+  eventType,
+  logPrefix,
+}) {
+  const errors = [];
+
+  if (!password) {
+    console.log(`${logPrefix} App password not set, skipping`);
+    return { newCount: 0, errors };
+  }
+
+  mkdirSync(INBOX_DIR, { recursive: true });
+
+  const cursor = readImapCursor(account);
+  const now = new Date().toISOString();
+  let newCount = 0;
+  let skipped = 0;
+  let unseenCount = 0;
+  let lastMid = cursor.last_message_id;
+  let totalProcessed = cursor.messages_processed;
+
+  const client = new ImapFlow({
+    host: "imap.gmail.com",
+    port: 993,
+    secure: true,
+    auth: { user: emailAddr, pass: password },
+    logger: false, // Suppress imapflow debug logs
+    socketTimeout: IMAP_TIMEOUT_MS,
+    greetTimeout: IMAP_TIMEOUT_MS,
+  });
+
+  try {
+    await client.connect();
+    const lock = await client.getMailboxLock("INBOX");
+
+    try {
+      // Search for unseen messages
+      const unseen = await client.search({ seen: false });
+      if (!unseen || unseen.length === 0) {
+        console.log(`${logPrefix} No unseen messages`);
+        writeImapCursor(account, now, lastMid, totalProcessed);
+        lock.release();
+        await client.logout();
+        return { newCount: 0, errors };
+      }
+
+      unseenCount = unseen.length;
+      console.log(`${logPrefix} Found ${unseenCount} unseen messages`);
+
+      // Rate limit: process most recent N
+      const toFetch = unseen.length > MAX_EMAILS_PER_CYCLE
+        ? unseen.slice(-MAX_EMAILS_PER_CYCLE)
+        : unseen;
+
+      if (unseen.length > MAX_EMAILS_PER_CYCLE) {
+        console.log(`${logPrefix} Rate limited to last ${MAX_EMAILS_PER_CYCLE}`);
+      }
+
+      // Fetch messages using PEEK (don't mark as read)
+      for (const seq of toFetch) {
+        try {
+          const msg = await client.fetchOne(seq, {
+            envelope: true,
+            bodyStructure: true,
+            source: true, // Full raw source for body/attachment extraction
+          }, { uid: false });
+
+          if (!msg || !msg.envelope) continue;
+
+          const env = msg.envelope;
+          const fromAddr = env.from?.[0]?.address || "";
+          const fromName = env.from?.[0]?.name || fromAddr;
+          const subject = env.subject || "";
+          const dateStr = env.date ? env.date.toISOString() : "";
+          const messageId = env.messageId || "";
+
+          const midHash = messageIdHash(messageId, fromAddr, subject, dateStr);
+
+          if (isAlreadyProcessed(midHash, fileSuffix)) {
+            skipped++;
+            continue;
+          }
+
+          // Parse the full message for body and attachments
+          let snippet = "";
+          let emailAttachments = [];
+          if (msg.source) {
+            try {
+              const { simpleParser } = await import("mailparser");
+              const parsed = await simpleParser(msg.source);
+              snippet = extractSnippet(parsed.text, parsed.html);
+              emailAttachments = saveAttachments(parsed, midHash);
+            } catch {
+              // Fall back to envelope-only data
+              snippet = "";
+            }
+          }
+
+          const record = {
+            received_at: now,
+            event_type: eventType,
+            source: `${account}_gmail_poll`,
+            email: {
+              from: `${fromName} <${fromAddr}>`,
+              from_name: fromName,
+              from_addr: fromAddr,
+              to: emailAddr,
+              subject,
+              date: dateStr,
+              message_id: messageId,
+              snippet,
+            },
+            attachments: emailAttachments.length > 0 ? emailAttachments : null,
+            triage_hint: null,
+          };
+
+          const filepath = join(INBOX_DIR, `${midHash}-${fileSuffix}.json`);
+          writeFileSync(filepath, JSON.stringify(record, null, 2));
+
+          newCount++;
+          lastMid = messageId;
+          console.log(`${logPrefix} New: ${fromName} <${fromAddr}> — ${subject.slice(0, 60)}`);
+        } catch (err) {
+          errors.push(`${logPrefix} Message fetch error: ${err.message}`);
+        }
+      }
+    } finally {
+      lock.release();
+    }
+
+    totalProcessed += newCount;
+    writeImapCursor(account, now, lastMid, totalProcessed);
+    await client.logout();
+
+    console.log(
+      `${logPrefix} Poll complete: ${newCount} new, ${skipped} skipped, ${unseenCount} unseen total`,
+    );
+  } catch (err) {
+    errors.push(`${logPrefix} IMAP error: ${err.message}`);
+    console.error(`${logPrefix} IMAP error: ${err.message}`);
+    writeImapCursor(account, now, lastMid, totalProcessed);
+    try { await client.logout(); } catch { /* already disconnected */ }
+  }
+
+  return { newCount, errors };
+}

package/scripts/poller/inbox-scan-poller.mjs

@@ -0,0 +1,156 @@
+/**
+ * inbox-scan-poller.mjs — generic poller for channel-bus inbox items.
+ *
+ * WS2 channels (Telegram, Baileys WhatsApp, …) deliver events through the
+ * daemon's channel bus, which serializes each to a byte-compatible inbox item
+ * via `eventToInboxItem` → `writeInboxItem("<service>", item)` under
+ * `state/inbox/<service>/*.yaml`. Unlike Slack/Gmail/Calendar/Voice, these
+ * channels have no dedicated API poller — so this scanner reads the YAML items
+ * back into the in-memory `{ items, errors }` shape the daemon's `poll()` loop
+ * already consumes, and the rest of the pipeline (classify → directed-gate →
+ * locks → dispatch) runs unchanged.
+ *
+ * The scanner is the inverse of `inboxItemToYaml` (scripts/poller/utils.mjs):
+ * it parses only the fields the daemon needs and ignores the rest. Items that
+ * have already been processed/deferred (renamed by the daemon) are skipped via
+ * the same sibling-file convention `writeInboxItem` uses, so the scanner never
+ * re-emits a handled item.
+ *
+ * Durable admission (F1 / H2): an item admitted-but-not-yet-closed is parked at
+ * `<name>.dispatched` (see `markDispatched` in utils.mjs). The scanner skips a
+ * fresh `.dispatched` file (no double-delivery on the happy path) but RECLAIMS a
+ * stale one (older than the reclaim window) — so a crash/restart that loses the
+ * daemon's in-memory queue still re-delivers the user's message instead of
+ * silently dropping it. `markInboxProcessed` retires it to `.processed` on
+ * success, which is terminal and never reclaimed.
+ *
+ * @module scripts/poller/inbox-scan-poller
+ */
+
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { AGENT_REPO_DIR } from "./utils.mjs";
+
+// Reclaim window for in-flight `.dispatched` items (F1 / H2 durable admission).
+// An item parked at `.dispatched` while its session is in-flight must NOT be
+// re-delivered on the happy path, but a crash/restart that loses the in-memory
+// queue must leave it re-deliverable. We reclaim a `.dispatched` file only once
+// it is older than this window — 2h matches the daemon's STALE_LOCK_MS and
+// comfortably exceeds every inbox session timeout, so a still-running session
+// is never double-delivered while a crashed one is recovered within one window.
+const DEFAULT_RECLAIM_MS = 2 * 60 * 60 * 1000;
+
+/**
+ * Parse a single inbox YAML body into the daemon's item shape. Tolerant of
+ * missing optional fields. Pure.
+ *
+ * @param {string} body
+ * @returns {object} item
+ */
+export function parseInboxItemYaml(body) {
+  const scalar = (key) => {
+    const m = body.match(new RegExp(`^${key}:\\s*"?([^"\\n]*)"?\\s*$`, "m"));
+    return m ? m[1] : "";
+  };
+  const bool = (key) => /true/i.test((body.match(new RegExp(`^${key}:\\s*(\\S+)`, "m")) || [])[1] || "");
+  const nestedBool = (key) => {
+    const m = body.match(new RegExp(`^\\s{2}${key}:\\s*(\\S+)`, "m"));
+    return /true/i.test((m || [])[1] || "");
+  };
+
+  // Block scalar `content: |` — capture the indented block.
+  const blockScalar = (key) => {
+    const re = new RegExp(`^${key}:\\s*\\|\\s*\\n((?:\\s{2}.*\\n?)*)`, "m");
+    const m = body.match(re);
+    if (!m) return scalar(key);
+    return m[1].replace(/^ {2}/gm, "").replace(/\n+$/, "");
+  };
+
+  return {
+    id: scalar("id"),
+    service: scalar("service"),
+    channel: scalar("channel"),
+    channel_id: scalar("channel_id"),
+    sender: scalar("sender"),
+    sender_privilege: scalar("sender_privilege"),
+    timestamp: scalar("timestamp"),
+    subject: scalar("subject"),
+    content: blockScalar("content"),
+    thread_id: scalar("thread_id"),
+    thread_context: (() => { const tc = blockScalar("thread_context"); return tc || null; })(),
+    is_reply: bool("is_reply"),
+    kind: scalar("kind") || "message",
+    priority_signals: {
+      from_ceo: nestedBool("from_ceo"),
+      tagged_urgent: nestedBool("tagged_urgent"),
+      contains_deadline: nestedBool("contains_deadline"),
+      mentions_agent: nestedBool("mentions_agent"),
+    },
+    raw_ref: scalar("raw_ref"),
+  };
+}
+
+/**
+ * Scan `state/inbox/<service>/` for unprocessed `*.yaml` items, plus any stale
+ * `*.dispatched` items left in-flight by a crashed session (F1 / H2 reclaim).
+ *
+ * @param {string} service
+ * @param {object} [opts]
+ * @param {string} [opts.agentRoot]
+ * @param {number} [opts.reclaimMs] age (ms) after which a `.dispatched` item is
+ *   considered crash-orphaned and re-delivered. Defaults to 2h (STALE_LOCK_MS).
+ * @param {number} [opts.now] injectable clock (epoch ms) for tests.
+ * @returns {{ items: object[], errors: string[] }}
+ */
+export function scanInbox(service, opts = {}) {
+  const agentRoot = opts.agentRoot || AGENT_REPO_DIR;
+  const reclaimMs = typeof opts.reclaimMs === "number" ? opts.reclaimMs : DEFAULT_RECLAIM_MS;
+  const now = typeof opts.now === "number" ? opts.now : Date.now();
+  const dir = join(agentRoot, "state", "inbox", service);
+  const items = [];
+  const errors = [];
+  if (!existsSync(dir)) return { items, errors };
+
+  let files;
+  try {
+    files = readdirSync(dir);
+  } catch (err) {
+    return { items, errors: [`readdir ${service}: ${err.message}`] };
+  }
+
+  for (const f of files) {
+    // Live items always emit. A `.dispatched` item is in-flight: emit it only
+    // once it is stale (crash-orphaned) so the happy path never double-delivers.
+    const isLive = f.endsWith(".yaml");
+    const isDispatched = f.endsWith(".dispatched");
+    if (!isLive && !isDispatched) continue; // skip .processed/.deferred/.bundled
+    const path = join(dir, f);
+    if (isDispatched) {
+      let ageMs;
+      try {
+        // Clamp at 0: filesystem mtime can read a hair ahead of the captured
+        // clock, which would otherwise make a just-dispatched file look like a
+        // negative (i.e. "future") age and skew the reclaim comparison.
+        ageMs = Math.max(0, now - statSync(path).mtimeMs);
+      } catch (err) {
+        errors.push(`stat ${f}: ${err.message}`);
+        continue;
+      }
+      if (ageMs < reclaimMs) continue; // still in-flight — do not re-deliver
+    }
+    try {
+      const item = parseInboxItemYaml(readFileSync(path, "utf-8"));
+      if (item.id) items.push(item);
+    } catch (err) {
+      errors.push(`parse ${f}: ${err.message}`);
+    }
+  }
+  return { items, errors };
+}
+
+/** Build a bound poller for a service, matching the poller fn contract. */
+export function makeInboxScanPoller(service, opts = {}) {
+  return async () => scanInbox(service, opts);
+}
+
+export default { scanInbox, parseInboxItemYaml, makeInboxScanPoller };