@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/src/hub/core/ids.mjs

@@ -0,0 +1,39 @@
+// agents-hub core/ids.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+export const TOPIC = /^(agent\/[A-Za-z0-9-]{8,80}|agent\/(manager|user)|stream\/[A-Za-z0-9._-]{1,80}\/[A-Za-z0-9._-]{1,80}|delivery\/[A-Za-z0-9-]{8,80}|role\/[A-Z][A-Z0-9-]{0,30}|manager|user|broadcast)$/;
+export const TYPE = /^[A-Z][A-Z0-9 _-]{0,30}$/;
+export const ADDRESS = /^([A-Za-z0-9-]{8,80}|manager|user)$/;
+export const MESSAGE_ID = /^m-[a-z0-9-]{4,120}$/;
+export const BODY_MAX = 4000;
+/** A reply or acknowledgement needs no answer; answering it would start a reply-to-a-reply loop. */
+export const isFyi = (m) => /^(REPLY|ACK|DONE|STATUS)$/.test(String((m && m.type) || '').toUpperCase()) || (!!(m && m.replyTo) && !m.needsAck);
+/** Every Cursor chat the headless manager has used (manager.json or the manager/config fact): never a delivery node. */
+export const managerChats = (config) => new Set([config && config.chatId, ...((config && Array.isArray(config.chatIds)) ? config.chatIds : [])]
+  .filter((id) => typeof id === 'string' && id));
+export const DEFAULT_TTL_MS = 24 * 3600e3;
+export const ONLINE_MS = 90e3;
+export const LEASE_MS = 30e3;
+export const SOURCE_RANK = { registered: 4, hook: 3, transcript: 2, channel: 1 };
+
+export const NODE_TYPES = ['user', 'manager', 'orchestrator', 'agent', 'channel_participant'];
+
+export function nodeTypeOf({ id, parentId, synthetic, role } = {}) {
+  if (id === 'user') return 'user';
+  if (id === 'manager') return 'manager';
+  if (synthetic || (id && /[/:]/.test(id))) return 'channel_participant';
+  if (parentId) return 'agent';
+  if (role === 'MANAGER') return 'manager';
+  if (role === 'USER') return 'user';
+  return 'orchestrator';
+}
+
+/** One title everywhere: Cursor chat title, else prompt title, else persona, else role. */
+export function displayTitle(actor) {
+  if (!actor) return '?';
+  if (actor.node_type === 'user' || actor.id === 'user') return actor.persona_name || 'You';
+  if (actor.node_type === 'manager' || actor.id === 'manager') return actor.persona_name || 'Manager';
+  if (actor.node_type === 'orchestrator') return actor.cursor_title || actor.prompt_title || actor.persona_name || 'Delivery';
+  if (actor.persona_name) return actor.persona_name;
+  if (actor.cursor_title) return actor.cursor_title;
+  if (actor.role) return String(actor.role).replace(/-/g, ' ');
+  return actor.prompt_title || actor.id;
+}

package/src/hub/core/leases.mjs

@@ -0,0 +1,55 @@
+// agents-hub core/leases.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Singleton leases for the HTTP server and the manager worker. Only one holder of each name is live.
+import crypto from 'node:crypto';
+import { withTx } from './db.mjs';
+
+const DEFAULT_TTL_MS = 15e3;
+
+function pidAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function holderPid(holder) {
+  const m = String(holder || '').match(/-(\d+)$/);
+  return m ? Number(m[1]) : null;
+}
+
+export function createLeases(db) {
+  const get = db.prepare('SELECT * FROM leases WHERE name = ?');
+
+  function acquire(name, holder, { ttlMs = DEFAULT_TTL_MS, now = Date.now(), force = false } = {}) {
+    const token = crypto.randomBytes(12).toString('hex');
+    const until = now + Math.max(2000, ttlMs);
+    return withTx(db, () => {
+      const row = get.get(name);
+      if (!force && row && row.until > now && row.holder !== holder) {
+        const pid = holderPid(row.holder);
+        if (pid == null || pidAlive(pid)) return { error: 'lease held', holder: row.holder, until: row.until };
+      }
+      db.prepare(`INSERT INTO leases (name, holder, token, until) VALUES (?, ?, ?, ?)
+        ON CONFLICT(name) DO UPDATE SET holder = excluded.holder, token = excluded.token, until = excluded.until`)
+        .run(name, holder, token, until);
+      return { ok: true, token, until, holder };
+    }, `lease ${name}`);
+  }
+
+  function renew(name, token, { ttlMs = DEFAULT_TTL_MS, now = Date.now() } = {}) {
+    const until = now + Math.max(2000, ttlMs);
+    const r = db.prepare('UPDATE leases SET until = ? WHERE name = ? AND token = ?').run(until, name, token);
+    if (!r.changes) return { error: 'not holder' };
+    return { ok: true, until };
+  }
+
+  function release(name, token) {
+    db.prepare('DELETE FROM leases WHERE name = ? AND token = ?').run(name, token);
+  }
+
+  function heldBy(name, now = Date.now()) {
+    const row = get.get(name);
+    if (!row || row.until <= now) return null;
+    return row;
+  }
+
+  return { acquire, renew, release, heldBy };
+}

package/src/hub/core/messaging.mjs

@@ -0,0 +1,322 @@
+// agents-hub core/messaging.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Transactional publish, leased claims, idempotent ack/reply, expiry. One write, all recipients, or none.
+import crypto from 'node:crypto';
+import { ADDRESS, BODY_MAX, DEFAULT_TTL_MS, LEASE_MS, MESSAGE_ID, TOPIC, TYPE } from './ids.mjs';
+import { jsonCol, parseJson, withTx } from './db.mjs';
+import { edgeId } from './edgeIds.mjs';
+
+function newId(at = Date.now()) {
+  return `m-${at.toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+}
+
+function envRow(r, status = null) {
+  if (!r) return null;
+  return {
+    id: r.id, at: r.created_at, from: r.sender, fromName: r.from_name, topic: r.topic, type: r.type,
+    body: r.body, text: r.body, needsAck: !!r.needs_reply, expiresAt: r.expires_at, replyTo: r.reply_to,
+    reaction: r.reaction, meta: parseJson(r.meta, {}), to: status ? status.map((s) => s.to) : parseJson(r.recipients, []),
+    status,
+  };
+}
+
+export function createMessaging(db, registry) {
+  const getMsg = db.prepare('SELECT * FROM messages WHERE id = ?');
+  const getDel = db.prepare('SELECT * FROM deliveries WHERE message_id = ? AND recipient = ?');
+  const delsOf = db.prepare('SELECT * FROM deliveries WHERE message_id = ?');
+  const byReply = db.prepare('SELECT * FROM messages WHERE reply_to = ? ORDER BY created_at ASC LIMIT 1');
+
+  /** A message published again under its edge-chosen id: the envelope as first published. */
+  function storedEnvelope(r) {
+    const to = db.prepare('SELECT recipient FROM deliveries WHERE message_id = ? ORDER BY rowid').all(r.id).map((d) => d.recipient);
+    return {
+      id: r.id, at: r.created_at, from: r.sender, fromName: r.from_name, topic: r.topic, type: r.type, body: r.body,
+      needsAck: !!r.needs_reply, expiresAt: r.expires_at, replyTo: r.reply_to, reaction: r.reaction, to, meta: parseJson(r.meta, {}),
+    };
+  }
+
+  function publish({ id: given = null, from, topic, type = 'MESSAGE', body, needsAck = false, ttlMs = DEFAULT_TTL_MS, replyTo = null, fromName = null, reaction = null, meta = {} } = {}, directory) {
+    if (!ADDRESS.test(String(from || ''))) return { error: 'bad sender' };
+    if (!TOPIC.test(String(topic || ''))) return { error: 'bad topic' };
+    if (!TYPE.test(String(type || ''))) return { error: 'bad type' };
+    if (typeof body !== 'string' || !body.trim()) return { error: 'empty body' };
+    if (given != null && !MESSAGE_ID.test(String(given))) return { error: 'bad id' };
+    const prior = given ? getMsg.get(given) : null;
+    if (prior) return prior.sender === from ? storedEnvelope(prior) : { error: 'id taken' };
+    const at = Date.now();
+    const to = directory ? resolveFromDirectory(topic, directory, from) : registry.resolveTopic(topic, from, at);
+    const id = given || newId(at);
+    const expiresAt = at + Math.max(60e3, Math.min(Number(ttlMs) || DEFAULT_TTL_MS, 7 * DEFAULT_TTL_MS));
+    const reply = typeof replyTo === 'string' && MESSAGE_ID.test(replyTo) ? replyTo : null;
+    const env = {
+      id, at, from, fromName: typeof fromName === 'string' ? fromName.slice(0, 80) : null,
+      topic, type, body: body.slice(0, BODY_MAX), needsAck: !!needsAck, expiresAt, replyTo: reply,
+      reaction: typeof reaction === 'string' ? reaction.slice(0, 16) : null, to, meta,
+    };
+    withTx(db, () => {
+      db.prepare(`INSERT INTO messages (id, sender, topic, type, body, needs_reply, expires_at, reply_to, reaction, from_name, created_at, meta)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, from, topic, type, env.body, env.needsAck ? 1 : 0, expiresAt, reply, env.reaction, env.fromName, at, jsonCol(meta));
+      const insDel = db.prepare(`INSERT INTO deliveries (message_id, recipient, state, queued_at, attempts) VALUES (?, ?, 'queued', ?, 0)`);
+      for (const r of to) insDel.run(id, r, at);
+    }, 'publish');
+    return env;
+  }
+
+  function resolveFromDirectory(topic, directory, from) {
+    const live = directory.filter((a) => a.status !== 'done' && ADDRESS.test(a.id));
+    let ids = [];
+    if (topic === 'manager' || topic === 'agent/manager') ids = ['manager'];
+    else if (topic === 'user' || topic === 'agent/user') ids = ['user'];
+    else if (topic.startsWith('agent/')) ids = [topic.slice(6)];
+    else if (topic.startsWith('stream/')) {
+      const key = topic.slice(7);
+      const crew = live.filter((a) => a.streamKey === key);
+      const owner = directory.find((a) => a.isArchitect && a.streams && a.streams.includes(key));
+      ids = [...crew.map((a) => a.id), ...(owner ? [owner.id] : [])];
+    } else if (topic.startsWith('delivery/')) {
+      const id = topic.slice(9);
+      ids = directory.filter((a) => a.isArchitect && a.deliveryId === id).map((a) => a.id);
+    } else if (topic.startsWith('role/')) {
+      const role = topic.slice(5);
+      ids = live.filter((a) => (role === 'ARCHITECT' ? a.isArchitect : a.role === role)).map((a) => a.id);
+    } else if (topic === 'broadcast') ids = live.map((a) => a.id);
+    ids.push(...live.filter((a) => Array.isArray(a.topics) && a.topics.includes(topic)).map((a) => a.id));
+    return [...new Set(ids)].filter((id) => id !== from && ADDRESS.test(id));
+  }
+
+  // Pending deliveries are few and found by index, their messages by primary key. Scanning `messages` instead, under the
+  // write lock, on every claim, peek and pendingCount of every connection starved the hub server past busy_timeout.
+  const PAST_DUE = `(SELECT expires_at FROM messages WHERE id = deliveries.message_id) <= ?`;
+  const expiredDue = db.prepare(`SELECT 1 FROM deliveries WHERE state IN ('queued','leased') AND ${PAST_DUE} LIMIT 1`);
+  const lapsedDue = db.prepare(`SELECT 1 FROM deliveries WHERE state = 'leased' AND lease_until IS NOT NULL AND lease_until < ? LIMIT 1`);
+
+  /** Marks expired mail and lapsed leases. Reads first: with nothing due it never takes the write lock. */
+  function expire(now = Date.now()) {
+    if (expiredDue.get(now)) {
+      db.prepare(`UPDATE deliveries SET state = 'expired', lease_token = NULL, lease_until = NULL
+        WHERE state IN ('queued','leased') AND ${PAST_DUE}`).run(now);
+    }
+    if (lapsedDue.get(now)) {
+      db.prepare(`UPDATE deliveries SET state = 'queued', lease_token = NULL, lease_until = NULL
+        WHERE state = 'leased' AND lease_until IS NOT NULL AND lease_until < ?`).run(now);
+    }
+  }
+
+  /** A reply, ack, done or status, or a reply that asks for nothing: the SQL twin of isFyi (core/ids.mjs). */
+  const FYI_SQL = `(UPPER(m.type) IN ('REPLY','ACK','DONE','STATUS') OR (m.reply_to IS NOT NULL AND m.needs_reply = 0))`;
+
+  /**
+   * Claim up to `limit` queued (or expired-lease) deliveries for `as`. Marks them leased in one transaction. With
+   * `fyiOnly`, only mail that needs no answer, so a busy worker can settle it without taking questions it cannot run.
+   */
+  function claim(as, { via = 'listen', leaseMs = LEASE_MS, limit = 1, now = Date.now(), fyiOnly = false } = {}) {
+    if (!ADDRESS.test(as)) return [];
+    expire(now);
+    return withTx(db, () => {
+      const rows = db.prepare(`SELECT d.message_id, d.recipient, d.attempts, m.*
+        FROM deliveries d JOIN messages m ON m.id = d.message_id
+        WHERE d.recipient = ? AND (
+          d.state = 'queued'
+          OR (d.state = 'leased' AND d.lease_until < ?)
+        ) AND m.expires_at > ?${fyiOnly ? ` AND ${FYI_SQL}` : ''}
+        ORDER BY d.queued_at ASC LIMIT ?`).all(as, now, now, Math.max(1, Math.min(limit, 20)));
+      const token = crypto.randomBytes(8).toString('hex');
+      const until = now + Math.max(1, leaseMs);
+      const out = [];
+      for (const r of rows) {
+        const got = db.prepare(`UPDATE deliveries SET state = 'leased', lease_token = ?, lease_until = ?,
+          leased_at = ?, attempts = attempts + 1, delivered_via = ?
+          WHERE message_id = ? AND recipient = ? AND (state = 'queued' OR (state = 'leased' AND lease_until < ?))`)
+          .run(token, until, now, via, r.message_id, as, now);
+        if (!got || !got.changes) continue;
+        out.push({
+          id: r.id, at: r.created_at, from: r.sender, fromName: r.from_name, topic: r.topic, type: r.type,
+          text: r.body, body: r.body, needsAck: !!r.needs_reply, expiresAt: r.expires_at, replyTo: r.reply_to,
+          reaction: r.reaction, leaseToken: token, leaseUntil: until, attempts: (Number(r.attempts) || 0) + 1,
+          meta: parseJson(r.meta, {}),
+        });
+      }
+      return out;
+    }, `claim ${as}`);
+  }
+
+  /** Look at queued mail without claiming it (postToolUse mid-turn context). */
+  function peek(as, { now = Date.now(), limit = 20 } = {}) {
+    if (!ADDRESS.test(as)) return [];
+    expire(now);
+    return db.prepare(`SELECT m.* FROM deliveries d JOIN messages m ON m.id = d.message_id
+      WHERE d.recipient = ? AND d.state = 'queued' AND m.expires_at > ?
+      ORDER BY d.queued_at ASC LIMIT ?`).all(as, now, limit).map((r) => ({
+      id: r.id, at: r.created_at, from: r.sender, fromName: r.from_name, topic: r.topic, type: r.type,
+      text: r.body, body: r.body, needsAck: !!r.needs_reply, expiresAt: r.expires_at, replyTo: r.reply_to,
+      reaction: r.reaction, meta: parseJson(r.meta, {}),
+    }));
+  }
+
+  /**
+   * Back to the queue at once: everything still leased to `as`, whose holder is gone (a restart). The cut-off run does
+   * not count as an attempt. Returns the released envelopes.
+   */
+  function releaseLeases(as, { now = Date.now() } = {}) {
+    if (!ADDRESS.test(as)) return [];
+    return withTx(db, () => {
+      const rows = db.prepare(`SELECT m.* FROM deliveries d JOIN messages m ON m.id = d.message_id
+        WHERE d.recipient = ? AND d.state = 'leased' AND m.expires_at > ? ORDER BY d.queued_at ASC`).all(as, now);
+      db.prepare(`UPDATE deliveries SET state = 'queued', lease_token = NULL, lease_until = NULL, attempts = MAX(attempts - 1, 0)
+        WHERE recipient = ? AND state = 'leased'`).run(as);
+      return rows.map((r) => envRow({ ...r, recipients: jsonCol([as]) }));
+    }, 'releaseLeases');
+  }
+
+  /** What waits for `as`: all pending (`depth`), not yet taken (`waiting`), and when the oldest was sent. Read-only. */
+  function queueStats(as, now = Date.now()) {
+    if (!ADDRESS.test(as)) return { depth: 0, waiting: 0, oldestAt: null };
+    const row = db.prepare(`SELECT COUNT(*) AS depth, SUM(d.state = 'queued' OR d.lease_until < ?) AS waiting, MIN(m.created_at) AS oldest
+      FROM deliveries d JOIN messages m ON m.id = d.message_id
+      WHERE d.recipient = ? AND d.state IN ('queued','leased') AND m.expires_at > ?`).get(now, as, now);
+    return { depth: Number(row.depth) || 0, waiting: Number(row.waiting) || 0, oldestAt: row.oldest == null ? null : Number(row.oldest) };
+  }
+
+  function renewClaim(as, id, token, { leaseMs = LEASE_MS, now = Date.now() } = {}) {
+    if (!ADDRESS.test(as) || !MESSAGE_ID.test(String(id || '')) || !token) return false;
+    const r = db.prepare(`UPDATE deliveries SET lease_until = ?
+      WHERE message_id = ? AND recipient = ? AND lease_token = ? AND state = 'leased'`).run(now + Math.max(1, leaseMs), id, as, token);
+    return !!(r && r.changes);
+  }
+
+  function markDelivered(as, ids, { via = 'hook', awaitingReply = false, now = Date.now() } = {}) {
+    const list = (Array.isArray(ids) ? ids : [ids]).filter((id) => MESSAGE_ID.test(id));
+    if (!ADDRESS.test(as) || !list.length) return 0;
+    return withTx(db, () => {
+      let n = 0;
+      for (const id of list) {
+        const r = db.prepare(`UPDATE deliveries SET state = 'delivered', delivered_at = ?, delivered_via = ?,
+          awaiting_reply = ?, lease_token = NULL, lease_until = NULL
+          WHERE message_id = ? AND recipient = ? AND state IN ('queued','leased','delivered')`).run(
+          now, via, awaitingReply ? 1 : 0, id, as);
+        if (r && r.changes) n++;
+      }
+      return n;
+    }, 'markDelivered');
+  }
+
+  /** Your messages shown mid-turn as a side chat that the agent has not answered yet. */
+  function sideUnanswered(as) {
+    if (!ADDRESS.test(as)) return [];
+    return db.prepare(`SELECT m.* FROM deliveries d JOIN messages m ON m.id = d.message_id
+      WHERE d.recipient = ? AND d.state = 'delivered' AND d.delivered_via = 'side' AND m.sender = 'user' AND m.expires_at > ?
+      ORDER BY d.queued_at ASC`).all(as, Date.now()).map((r) => ({
+      id: r.id, at: r.created_at, from: r.sender, fromName: r.from_name, topic: r.topic, type: r.type,
+      text: r.body, body: r.body, needsAck: !!r.needs_reply, expiresAt: r.expires_at, replyTo: r.reply_to,
+      reaction: r.reaction, meta: parseJson(r.meta, {}),
+    }));
+  }
+
+  function awaiting(as) {
+    if (!ADDRESS.test(as)) return [];
+    return db.prepare(`SELECT d.message_id AS id, m.sender AS sender FROM deliveries d JOIN messages m ON m.id = d.message_id
+      WHERE d.recipient = ? AND d.awaiting_reply = 1 AND d.state = 'delivered' AND m.expires_at > ?
+      ORDER BY d.queued_at ASC`).all(as, Date.now());
+  }
+
+  /**
+   * A reply was expected for these, but the turn that should have answered them is over. They stop waiting, so a later,
+   * unrelated answer is never captured, and are not offered again (they stay delivered, unanswered).
+   */
+  function releaseAwaiting(as) {
+    if (!ADDRESS.test(as)) return 0;
+    const r = db.prepare(`UPDATE deliveries SET awaiting_reply = 0, delivered_via = 'retried'
+      WHERE recipient = ? AND awaiting_reply = 1 AND state = 'delivered'`).run(as);
+    return Number(r && r.changes) || 0;
+  }
+
+  function ack(as, id, { reply = null, fromName = null, reaction = null } = {}, directory) {
+    if (!ADDRESS.test(as) || !MESSAGE_ID.test(String(id || ''))) return { error: 'bad ack' };
+    return withTx(db, () => {
+      const del = getDel.get(id, as);
+      if (!del) return { error: 'no such message for you' };
+      const orig = getMsg.get(id);
+      if (!orig) return { error: 'no such message for you' };
+      if (del.state !== 'acked') {
+        db.prepare(`UPDATE deliveries SET state = 'acked', acked_at = ?, awaiting_reply = 0, lease_token = NULL, lease_until = NULL
+          WHERE message_id = ? AND recipient = ?`).run(Date.now(), id, as);
+      }
+      let answer = null;
+      const wantReply = (typeof reply === 'string' && reply.trim()) || reaction;
+      if (wantReply && del.state !== 'acked') {
+        const topic = orig.sender === 'user' ? 'user' : orig.sender === 'manager' ? 'manager' : `agent/${orig.sender}`;
+        const inner = publish({
+          id: edgeId('r', id, as), from: as, fromName, topic, type: 'REPLY',
+          body: typeof reply === 'string' && reply.trim() ? reply : 'Reacted',
+          reaction, replyTo: id,
+        }, directory);
+        answer = inner;
+      } else if (wantReply && del.state === 'acked') {
+        const existing = byReply.get(id);
+        if (existing) answer = { id: existing.id };
+        else {
+          const topic = orig.sender === 'user' ? 'user' : orig.sender === 'manager' ? 'manager' : `agent/${orig.sender}`;
+          answer = publish({
+            id: edgeId('r', id, as), from: as, fromName, topic, type: 'REPLY',
+            body: typeof reply === 'string' && reply.trim() ? reply : 'Reacted',
+            reaction, replyTo: id,
+          }, directory);
+        }
+      }
+      return { ok: true, reply: answer && !answer.error ? answer.id : null };
+    }, 'ack');
+  }
+
+  function replyTo(id) {
+    const r = byReply.get(id);
+    if (!r) return null;
+    const status = statusOf(r.id);
+    return envRow({ ...r, recipients: jsonCol(status.map((s) => s.to)) }, status);
+  }
+
+  function statusOf(idOrEnv, now = Date.now()) {
+    const id = typeof idOrEnv === 'string' ? idOrEnv : idOrEnv && idOrEnv.id;
+    const orig = getMsg.get(id);
+    if (!orig) return [];
+    return delsOf.all(id).map((d) => {
+      let state = d.state;
+      if (state === 'queued' && now > orig.expires_at) state = 'expired';
+      if (state === 'delivered' && orig.needs_reply && now > orig.expires_at) state = 'unacked';
+      if (state === 'leased' && d.lease_until && d.lease_until < now) state = 'queued';
+      return { to: d.recipient, state, deliveredAt: d.delivered_at, via: d.delivered_via, ackedAt: d.acked_at, attempts: d.attempts };
+    });
+  }
+
+  const withStatus = (rows, now = Date.now()) => rows.map((m) => {
+    const status = statusOf(m.id, now);
+    return envRow({ ...m, recipients: jsonCol(status.map((s) => s.to)) }, status);
+  });
+
+  /** The newest `limit` messages since `since`, oldest first. */
+  function messages({ since = 0, limit = 200 } = {}) {
+    const n = Math.max(1, Math.min(Number(limit) || 200, 5000));
+    return withStatus(db.prepare('SELECT * FROM messages WHERE created_at >= ? ORDER BY created_at DESC LIMIT ?').all(since, n).reverse());
+  }
+
+  /** Messages sent by or delivered to one address, newest 5000, oldest first. */
+  function involving(address, since = 0) {
+    return withStatus(db.prepare(`SELECT * FROM messages WHERE created_at >= ? AND (sender = ? OR id IN (SELECT message_id FROM deliveries WHERE recipient = ?))
+      ORDER BY created_at DESC LIMIT 5000`).all(since, address, address).reverse());
+  }
+
+  function pendingCount(as) {
+    if (!ADDRESS.test(as)) return 0;
+    expire();
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM deliveries d JOIN messages m ON m.id = d.message_id
+      WHERE d.recipient = ? AND d.state IN ('queued','leased') AND m.expires_at > ?`).get(as, Date.now());
+    return Number(row && row.n) || 0;
+  }
+
+  /** Compatibility: claim then mark delivered (listen/CLI). */
+  function take(as, via = 'listen') {
+    const got = claim(as, { via, limit: 50 });
+    if (got.length) markDelivered(as, got.map((m) => m.id), { via, awaitingReply: false });
+    return got;
+  }
+
+  return { publish, claim, peek, releaseLeases, queueStats, renewClaim, markDelivered, sideUnanswered, awaiting, releaseAwaiting, ack, replyTo, statusOf, messages, involving, pendingCount, take, expire };
+}