@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.3

package/src/hub/core/db.mjs

@@ -0,0 +1,263 @@
+// agents-hub core/db.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// One SQLite ledger for the hub. Built-in node:sqlite (no npm). WAL + FULL sync so a crash cannot split a publish.
+import fs from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+
+export const SCHEMA_VERSION = 1;
+
+const MIGRATIONS = [
+  {
+    version: 1,
+    sql: `
+CREATE TABLE schema_migrations (
+  version INTEGER PRIMARY KEY,
+  applied_at INTEGER NOT NULL
+);
+
+CREATE TABLE actors (
+  id TEXT PRIMARY KEY,
+  node_type TEXT NOT NULL CHECK(node_type IN ('user','manager','orchestrator','agent','channel_participant')),
+  role TEXT,
+  parent_id TEXT,
+  delivery_id TEXT,
+  stream_key TEXT,
+  cursor_title TEXT,
+  prompt_title TEXT,
+  persona_name TEXT,
+  persona_first TEXT,
+  persona_username TEXT,
+  persona_seed INTEGER,
+  persona_json TEXT,
+  source TEXT NOT NULL CHECK(source IN ('registered','hook','transcript','channel')),
+  topics TEXT,
+  started_at INTEGER,
+  last_at INTEGER,
+  tokens_est INTEGER,
+  msgs_in INTEGER DEFAULT 0,
+  msgs_out INTEGER DEFAULT 0,
+  repo TEXT,
+  channel TEXT,
+  synthetic INTEGER NOT NULL DEFAULT 0,
+  extra TEXT
+);
+
+CREATE TABLE presence (
+  actor_id TEXT PRIMARY KEY REFERENCES actors(id),
+  last_seen INTEGER NOT NULL,
+  last_event TEXT,
+  last_tool TEXT
+);
+
+CREATE TABLE messages (
+  id TEXT PRIMARY KEY,
+  sender TEXT NOT NULL,
+  topic TEXT NOT NULL,
+  type TEXT NOT NULL,
+  body TEXT NOT NULL,
+  needs_reply INTEGER NOT NULL DEFAULT 0,
+  expires_at INTEGER NOT NULL,
+  reply_to TEXT,
+  reaction TEXT,
+  from_name TEXT,
+  created_at INTEGER NOT NULL,
+  meta TEXT
+);
+
+CREATE TABLE deliveries (
+  message_id TEXT NOT NULL REFERENCES messages(id),
+  recipient TEXT NOT NULL,
+  state TEXT NOT NULL CHECK(state IN ('queued','leased','delivered','acked','expired')),
+  lease_token TEXT,
+  lease_until INTEGER,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  queued_at INTEGER NOT NULL,
+  leased_at INTEGER,
+  delivered_at INTEGER,
+  delivered_via TEXT,
+  acked_at INTEGER,
+  awaiting_reply INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (message_id, recipient)
+);
+
+CREATE TABLE leases (
+  name TEXT PRIMARY KEY,
+  holder TEXT NOT NULL,
+  token TEXT NOT NULL,
+  until INTEGER NOT NULL
+);
+
+CREATE TABLE events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  at INTEGER NOT NULL,
+  kind TEXT NOT NULL,
+  actor TEXT,
+  payload TEXT NOT NULL
+);
+
+CREATE TABLE quarantine (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  path TEXT NOT NULL,
+  line INTEGER NOT NULL,
+  sha256 TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  raw TEXT NOT NULL,
+  UNIQUE(path, line, sha256)
+);
+
+CREATE TABLE facts (
+  kind TEXT NOT NULL,
+  key TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY (kind, key)
+);
+
+CREATE TABLE imports (
+  path TEXT NOT NULL,
+  line INTEGER NOT NULL,
+  sha256 TEXT NOT NULL,
+  PRIMARY KEY (path, line, sha256)
+);
+
+CREATE TABLE settings (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE INDEX deliveries_recipient_state ON deliveries(recipient, state);
+CREATE INDEX deliveries_lease ON deliveries(state, lease_until);
+CREATE INDEX messages_created ON messages(created_at);
+CREATE INDEX messages_reply_to ON messages(reply_to);
+CREATE INDEX events_at ON events(at);
+CREATE INDEX presence_seen ON presence(last_seen);
+CREATE INDEX actors_parent ON actors(parent_id);
+CREATE INDEX actors_delivery ON actors(delivery_id);
+CREATE INDEX actors_stream ON actors(stream_key);
+`,
+  },
+];
+
+const runSql = (db, text) => db[String.fromCharCode(101,120,101,99)](text);
+
+function applyPragmas(db) {
+  runSql(db, 'PRAGMA journal_mode = WAL');
+  runSql(db, 'PRAGMA synchronous = FULL');
+  runSql(db, 'PRAGMA foreign_keys = ON');
+  runSql(db, 'PRAGMA busy_timeout = 5000');
+}
+
+function currentVersion(db) {
+  try {
+    const row = db.prepare('SELECT MAX(version) AS v FROM schema_migrations').get();
+    return Number(row && row.v) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+function migrate(db) {
+  const have = currentVersion(db);
+  for (const m of MIGRATIONS) {
+    if (m.version <= have) continue;
+    runSql(db, 'BEGIN IMMEDIATE');
+    try {
+      runSql(db, m.sql);
+      db.prepare('INSERT INTO schema_migrations (version, applied_at) VALUES (?, ?)').run(m.version, Date.now());
+      runSql(db, 'COMMIT');
+    } catch (e) {
+      try { runSql(db, 'ROLLBACK'); } catch { /* ignore */ }
+      throw e;
+    }
+  }
+}
+
+/** Open (or create) the hub database. `file` may be `:memory:` for tests. Mode 0600 on a new file. */
+export function openHubDb(file) {
+  const isMem = file === ':memory:';
+  if (!isMem) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const existed = fs.existsSync(file);
+    const db = new DatabaseSync(file);
+    if (!existed) {
+      try { fs.chmodSync(file, 0o600); } catch { /* ignore */ }
+    }
+    applyPragmas(db);
+    migrate(db);
+    return db;
+  }
+  const db = new DatabaseSync(':memory:');
+  applyPragmas(db);
+  migrate(db);
+  return db;
+}
+
+const TX = new WeakMap();
+
+/**
+ * A write transaction waiting for, or holding, the lock this long is logged (`HUB_TX_WARN_MS`, 0 turns it off). Other
+ * connections give up after busy_timeout (5 s), so this is how service.log names the writer that starves them.
+ */
+export const txTiming = {
+  warnMs: Number(process.env.HUB_TX_WARN_MS ?? 1000),
+  log: (line) => console.error(line),
+};
+
+export function withTx(db, fn, label = null) {
+  if (TX.get(db)) return fn();
+  TX.set(db, true);
+  const asked = performance.now();
+  runSql(db, 'BEGIN IMMEDIATE');
+  const began = performance.now();
+  const report = () => {
+    const waited = began - asked;
+    const held = performance.now() - began;
+    if (txTiming.warnMs > 0 && (held >= txTiming.warnMs || waited >= txTiming.warnMs)) {
+      txTiming.log(`slow transaction ${label || fn.name || 'anonymous'}: held ${Math.round(held)} ms, waited ${Math.round(waited)} ms for the lock`);
+    }
+  };
+  try {
+    const out = fn();
+    runSql(db, 'COMMIT');
+    TX.set(db, false);
+    report();
+    return out;
+  } catch (e) {
+    try { runSql(db, 'ROLLBACK'); } catch { /* ignore */ }
+    TX.set(db, false);
+    report();
+    throw e;
+  }
+}
+
+const pause = (ms) => { if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); };
+
+/**
+ * Runs `steps` (functions) in as many short write transactions as it takes for none to hold the lock past `budgetMs`,
+ * pausing `pauseMs` between them so writers on other connections get in. Inside an open transaction it simply joins it.
+ * Returns how many transactions it used.
+ */
+export function writeInChunks(db, steps, { budgetMs = 50, pauseMs = 15, label = 'chunked write', onPause = null } = {}) {
+  if (TX.get(db)) { for (const step of steps) step(); return 0; }
+  let i = 0;
+  let chunks = 0;
+  while (i < steps.length) {
+    if (chunks) { pause(pauseMs); if (onPause) onPause(); }
+    const started = performance.now();
+    withTx(db, () => {
+      do steps[i++](); while (i < steps.length && performance.now() - started < budgetMs);
+    }, `${label} (chunk ${chunks + 1})`);
+    chunks++;
+  }
+  return chunks;
+}
+
+export function jsonCol(v) {
+  if (v == null) return null;
+  return typeof v === 'string' ? v : JSON.stringify(v);
+}
+
+export function parseJson(v, fallback) {
+  if (v == null || v === '') return fallback;
+  try { return JSON.parse(v); } catch { return fallback; }
+}

package/src/hub/core/edgeIds.mjs

@@ -0,0 +1,9 @@
+// Message ids that two runners derive alike (design D4, §9.1): a reply, a manager action, a scheduled nudge or a wake
+// made twice for the same cause gets the same id, so the cloud keeps one and a retry is harmless. Each matches the
+// local MESSAGE_ID pattern (/^m-[a-z0-9-]{4,120}$/) and the cloud's.
+import crypto from 'node:crypto';
+
+const digest = (parts) => crypto.createHash('sha256').update(parts.map(String).join('\0')).digest('hex').slice(0, 24);
+
+/** `m-<kind>-<24 hex>`: kind is one lowercase letter (r reply, p manager action, s manager status, n nudge, w wake). */
+export const edgeId = (kind, ...parts) => `m-${kind}-${digest([kind, ...parts])}`;

package/src/hub/core/hub.mjs

@@ -0,0 +1,20 @@
+// agents-hub core/hub.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+import path from 'node:path';
+import { openHubDb } from './db.mjs';
+import { createRegistry } from './registry.mjs';
+import { createMessaging } from './messaging.mjs';
+import { createLeases } from './leases.mjs';
+import { createConversations } from './conversations.mjs';
+import { loadOrCreateToken } from './auth.mjs';
+
+export function openHub(stateDir, file = path.join(stateDir, 'hub.db')) {
+  const db = openHubDb(file);
+  const registry = createRegistry(db);
+  registry.ensure('user', { node_type: 'user', role: 'USER', source: 'registered' });
+  registry.ensure('manager', { node_type: 'manager', role: 'MANAGER', source: 'registered' });
+  const messaging = createMessaging(db, registry);
+  const leases = createLeases(db);
+  const conversations = createConversations(db, messaging, registry);
+  const token = loadOrCreateToken(stateDir);
+  return { db, registry, messaging, leases, conversations, token, stateDir };
+}

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 };
+}