@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.3

package/src/commands/pulse/import.js

@@ -0,0 +1,62 @@
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { defaultConfigDirectory } from '../../lib/application.js';
+import { CloudFirstCommands } from '../../lib/cloudFirstCommands.js';
+
+export default class PulseImport extends BaseCommand {
+  static description = 'Import the local Agent Hub into the Pulse log from a snapshot of its sources (idempotent: a re-run on the same snapshot writes nothing). --dry-run reads only and prints what it would send; --reconcile rescans the snapshot and compares it with Pulse, exiting 1 on any mismatch.';
+  static examples = ['<%= config.bin %> pulse import --dry-run', '<%= config.bin %> pulse import', '<%= config.bin %> pulse import --reconcile', '<%= config.bin %> pulse import --reuse-snapshot'];
+  static flags = {
+    'dry-run': Flags.boolean({ description: 'Read the local hub and report per source; send and write nothing', default: false }),
+    wait: Flags.boolean({ description: 'Follow the import until it has fully drained', default: true, allowNo: true }),
+    reconcile: Flags.boolean({ description: 'Rescan the last import\'s snapshot and compare every family, channel and conversation with Pulse', default: false }),
+    'reuse-snapshot': Flags.boolean({ description: 'Import the last snapshot again instead of taking a new one', default: false }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulseImport);
+    const commands = this.cloudFirst || new CloudFirstCommands({ configDir: defaultConfigDirectory() });
+    if (flags['dry-run']) {
+      const result = await commands.dryRun();
+      for (const row of result.sources) {
+        const detail = [...Object.entries(row.skipped).map(([k, v]) => `skipped ${k} ${v}`), ...Object.entries(row.refused).map(([k, v]) => `refused ${k} ${v}`)];
+        this.log(`${row.source.padEnd(9)} read ${row.read}  planned ${row.planned}  unchanged ${row.unchanged}  redactions ${row.redactions}${row.cut ? `  cut ${row.cut}` : ''}${detail.length ? `  (${detail.join(', ')})` : ''}`);
+        if (Object.keys(row.events).length) this.log(`          events ${Object.entries(row.events).map(([type, n]) => `${type} ${n}`).join(', ')}`);
+      }
+      this.log(result.message);
+      if (!result.totals.balanced) process.exitCode = 1;
+      return result;
+    }
+    let last = '';
+    if (flags.reconcile) {
+      const result = await commands.reconcile({
+        onProgress: (progress) => {
+          const line = `Reconcile: ${progress.state}${progress.code ? ` (${progress.code})` : ''}`;
+          if (line !== last) this.log(line);
+          last = line;
+        },
+      });
+      for (const [family, row] of Object.entries(result.families || {})) {
+        this.log(`${family.padEnd(18)} local ${String(row.local).padStart(6)}  pulse ${String(row.cloud).padStart(6)}  ${row.equal ? 'equal' : 'DIFFERS'}`);
+      }
+      for (const [source, row] of Object.entries(result.sources || {})) {
+        this.log(`source ${source.padEnd(9)} rows ${row.counted ?? '—'}  read ${row.read}  accounted ${row.accounted}`);
+      }
+      for (const item of (result.mismatches || []).slice(0, 20)) this.log(`MISMATCH ${item.family}${item.item ? ` ${item.item}` : ''}${item.note ? `: ${item.note}` : ''}`);
+      this.log(result.message);
+      process.exitCode = result.exitCode;
+      return result;
+    }
+    const result = await commands.import({
+      wait: flags.wait,
+      reuseSnapshot: flags['reuse-snapshot'],
+      onProgress: (progress) => {
+        const line = `Import: ${progress.state}${progress.code ? ` (${progress.code})` : ''}${progress.pending !== null && progress.pending !== undefined ? `, ${progress.pending} commands waiting` : ''}`;
+        if (line !== last) this.log(line);
+        last = line;
+      },
+    });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/log-write.js

@@ -0,0 +1,26 @@
+import { Args } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { getDefaultApplication } from '../../lib/application.js';
+
+export default class PulseLogWrite extends BaseCommand {
+  static description = 'Let this machine read and write your Pulse log (hub.sync and log.write), stop it writing, or show whether it can.';
+  static examples = [
+    '<%= config.bin %> pulse log-write status',
+    '<%= config.bin %> pulse log-write on',
+    '<%= config.bin %> pulse log-write off',
+  ];
+  static args = {
+    action: Args.string({
+      description: 'on, off or status',
+      options: ['on', 'off', 'status'],
+      default: 'status',
+    }),
+  };
+
+  async run() {
+    const { args } = await this.parse(PulseLogWrite);
+    const result = await (this.runtime || getDefaultApplication()).logWrite({ action: args.action });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/parity.js

@@ -0,0 +1,20 @@
+import { Flags } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { defaultConfigDirectory } from '../../lib/application.js';
+import { CloudFirstCommands } from '../../lib/cloudFirstCommands.js';
+
+export default class PulseParity extends BaseCommand {
+  static description = 'Show how this machine\'s Pulse mirror and the Pulse log agree: the last parity check and its history, or a fresh one.';
+  static examples = ['<%= config.bin %> pulse parity', '<%= config.bin %> pulse parity --now --hours 6'];
+  static flags = {
+    hours: Flags.integer({ description: 'Window in hours (1 to 168)', default: 6, min: 1, max: 168 }),
+    now: Flags.boolean({ description: 'Ask the daemon for a fresh check and wait for it', default: false }),
+  };
+
+  async run() {
+    const { flags } = await this.parse(PulseParity);
+    const result = await (this.cloudFirst || new CloudFirstCommands({ configDir: defaultConfigDirectory() })).parity({ hours: flags.hours, now: flags.now });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/commands/pulse/shadow.js

@@ -0,0 +1,19 @@
+import { Args } from '@oclif/core';
+import BaseCommand from '../../lib/BaseCommand.js';
+import { defaultConfigDirectory } from '../../lib/application.js';
+import { CloudFirstCommands } from '../../lib/cloudFirstCommands.js';
+
+export default class PulseShadow extends BaseCommand {
+  static description = 'Turn the Pulse shadow feed (the local hub, tailed into the Pulse log) on or off, or show its status.';
+  static examples = ['<%= config.bin %> pulse shadow status', '<%= config.bin %> pulse shadow on', '<%= config.bin %> pulse shadow off'];
+  static args = {
+    action: Args.string({ description: 'on, off or status', options: ['on', 'off', 'status'], default: 'status' }),
+  };
+
+  async run() {
+    const { args } = await this.parse(PulseShadow);
+    const result = await (this.cloudFirst || new CloudFirstCommands({ configDir: defaultConfigDirectory() })).shadow({ action: args.action });
+    this.log(result.message);
+    return result;
+  }
+}

package/src/daemon/main.js

@@ -3,12 +3,14 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defaultConfigDirectory } from '../lib/application.js';
 import { runDaemon } from '../lib/daemonProcess.js';
+import { nodeFloor } from '../lib/nodeFloor.js';
 import { ServiceManager } from '../lib/serviceManager.js';
 
 const MIRROR_FAILURES = new Set(['mirror_failed', 'mirror_blocked', 'mirror_stream_failed']);
 const ERROR_EVENTS = new Set([
   'job_failed', 'job_refused', 'job_settle_failed', 'cycle_stalled', 'drain_timed_out', 'daemon_start_failed',
   'daemon_shutdown_failed', 'source_watch_refused', 'source_watch_failed',
+  'cutover_failed', 'cutover_request_failed', 'cutover_request_refused', 'cutover_interrupted', 'cutover_service_failed',
 ]);
 
 /** One redacted line per job, local hub or restart event; failures go to daemon-error.log, the rest to daemon.log. */
@@ -22,15 +24,21 @@ function configDirectory(argv) {
   return index === -1 ? defaultConfigDirectory() : path.resolve(argv[index + 1]);
 }
 
-runDaemon({
-  directory: configDirectory(process.argv.slice(2)),
-  pluginRoot: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..'),
-  logDir: new ServiceManager({}).logDir,
-  log: logEvent,
-  mirrorLog: (event, details) => {
-    if (MIRROR_FAILURES.has(event)) process.stderr.write(`Pulse ${event}: ${details.code}\n`);
-  },
-}).catch((error) => {
-  process.stderr.write(`Pulse daemon failed: ${error.code || 'HUB_DAEMON_FAILED'}: ${error.message}\n`);
-  process.exitCode = 1;
-});
+const floor = nodeFloor();
+if (!floor.ok) {
+  // Exit 0: launchd (SuccessfulExit false) and systemd (on-failure) would otherwise restart it in a loop.
+  process.stderr.write(`Pulse daemon refused: ${floor.code}: ${floor.message}\n`);
+} else {
+  runDaemon({
+    directory: configDirectory(process.argv.slice(2)),
+    pluginRoot: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..'),
+    logDir: new ServiceManager({}).logDir,
+    log: logEvent,
+    mirrorLog: (event, details) => {
+      if (MIRROR_FAILURES.has(event)) process.stderr.write(`Pulse ${event}: ${details.code}\n`);
+    },
+  }).catch((error) => {
+    process.stderr.write(`Pulse daemon failed: ${error.code || 'HUB_DAEMON_FAILED'}: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/src/hub/core/auth.mjs

@@ -0,0 +1,80 @@
+// agents-hub core/auth.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Local hub auth: a 0600 token file for CLI/hook, an HttpOnly SameSite=Strict cookie for the browser.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const COOKIE = 'hub_auth';
+
+export function tokenPath(stateDir) {
+  return path.join(stateDir, 'hub.token');
+}
+
+export function loadOrCreateToken(stateDir) {
+  const file = tokenPath(stateDir);
+  try {
+    const existing = fs.readFileSync(file, 'utf8').trim();
+    if (/^[a-f0-9]{32,}$/i.test(existing)) return existing;
+  } catch { /* create */ }
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const token = crypto.randomBytes(32).toString('hex');
+  const fd = fs.openSync(file, 'w', 0o600);
+  try { fs.writeSync(fd, token); } finally { fs.closeSync(fd); }
+  try { fs.chmodSync(file, 0o600); } catch { /* ignore */ }
+  return token;
+}
+
+export function sessionCookie(token) {
+  return crypto.createHmac('sha256', String(token)).update('hub-browser-user').digest('hex');
+}
+
+export function parseCookie(header) {
+  const out = {};
+  for (const part of String(header || '').split(';')) {
+    const i = part.indexOf('=');
+    if (i < 0) continue;
+    let value = part.slice(i + 1).trim();
+    try { value = decodeURIComponent(value); } catch { /* leave encoded */ }
+    out[part.slice(0, i).trim()] = value;
+  }
+  return out;
+}
+
+function bearer(req) {
+  const h = String(req.headers.authorization || '');
+  const m = /^Bearer\s+(\S+)/i.exec(h);
+  if (m) return m[1];
+  return req.headers['x-hub-token'] || null;
+}
+
+/**
+ * Authenticate a request. Returns { principal, via } or null.
+ * cookie → principal `user` (the browser may only act as you)
+ * bearer matching hub.token → principal from X-Hub-As, default `user`
+ */
+export function authenticate(req, token, { asHint = null } = {}) {
+  if (!token) return null;
+  const cookie = parseCookie(req.headers.cookie)[COOKIE];
+  if (cookie && cookie === sessionCookie(token)) return { principal: 'user', via: 'cookie' };
+  const hdr = bearer(req);
+  if (hdr && hdr === token) {
+    const as = asHint || req.headers['x-hub-as'] || null;
+    return { principal: typeof as === 'string' && as ? as : 'user', via: 'token' };
+  }
+  return null;
+}
+
+export function setAuthCookie(res, token) {
+  const cookie = `${COOKIE}=${sessionCookie(token)}; HttpOnly; SameSite=Strict; Path=/; Max-Age=2592000`;
+  if (typeof res.setHeader === 'function') res.setHeader('Set-Cookie', cookie);
+  return cookie;
+}
+
+export function bindPrincipal(auth, requestedAs) {
+  if (!auth) return { error: 'unauthorized' };
+  if (auth.via === 'cookie') {
+    if (requestedAs && requestedAs !== 'user') return { error: 'forbidden principal' };
+    return { principal: 'user' };
+  }
+  return { principal: requestedAs || auth.principal };
+}

package/src/hub/core/changes.mjs

@@ -0,0 +1,38 @@
+// agents-hub core/changes.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// What counts as news in hub.db for the live change feed. Discovery rewrites the rows it owns on graph reads and the
+// server renews its lease every 10 s; waking the feed for those makes every client read the graph again, which runs
+// discovery again.
+
+/** Fact kinds owned by discovery (workers/collector.mjs persistDiscovery); each pass replaces them. */
+export const DISCOVERY_FACTS = ['delivery', 'stream', 'agent-row', 'request', 'totals'];
+
+/**
+ * Returns `changed()`: what news hub.db holds since the last call. `false` for none; `'presence'` when only presence
+ * moved (hook heartbeats: projections must refresh, discovery's inputs did not change); `'hub'` for anything else:
+ * bus mail and its delivery states, registrations, new actors, events and non-discovery facts. Discovery's inferred
+ * actor fields and facts, and lease renewals, are not news.
+ */
+export function changeTracker(db) {
+  // Sums, not maxima, so a second update in the same millisecond still moves the signature; cast to text because a
+  // sum of epoch milliseconds passes 2^53 and would lose its low digits as a JS number.
+  const messages = db.prepare('SELECT COUNT(*) AS n, MAX(rowid) AS last FROM messages');
+  const deliveries = db.prepare(`SELECT COUNT(*) AS n, SUM(attempts) AS attempts, SUM(awaiting_reply) AS awaiting,
+    CAST(SUM(IFNULL(leased_at, 0) + IFNULL(delivered_at, 0) + IFNULL(acked_at, 0)) AS TEXT) AS at FROM deliveries`);
+  const states = db.prepare('SELECT state, COUNT(*) AS n FROM deliveries GROUP BY state ORDER BY state');
+  const presence = db.prepare('SELECT COUNT(*) AS n, CAST(SUM(last_seen) AS TEXT) AS seen FROM presence');
+  const actors = db.prepare('SELECT COUNT(*) AS n FROM actors');
+  const events = db.prepare('SELECT COUNT(*) AS n, MAX(id) AS last FROM events');
+  const facts = db.prepare(`SELECT COUNT(*) AS n, CAST(SUM(updated_at) AS TEXT) AS at, SUM(LENGTH(payload)) AS size
+    FROM facts WHERE kind NOT IN (${DISCOVERY_FACTS.map(() => '?').join(', ')})`);
+  const signature = () => ({
+    presence: JSON.stringify(presence.get()),
+    rest: JSON.stringify([messages.get(), deliveries.get(), states.all(), actors.get(), events.get(), facts.get(...DISCOVERY_FACTS)]),
+  });
+  let last = signature();
+  return function changed() {
+    const next = signature();
+    const kind = next.rest !== last.rest ? 'hub' : next.presence !== last.presence ? 'presence' : false;
+    last = next;
+    return kind;
+  };
+}

package/src/hub/core/conversations.mjs

@@ -0,0 +1,121 @@
+// agents-hub core/conversations.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// One-to-one threads: only messages between you and one actor. Top-level Cursor chats also include transcript
+// prompts and final replies, de-duplicated by message id and turn id.
+import { ADDRESS } from './ids.mjs';
+import { parseJson } from './db.mjs';
+
+const MAX = 300;
+
+function shape(m, actorId) {
+  const fromUser = m.sender === 'user';
+  return {
+    id: m.id,
+    at: m.created_at,
+    from: fromUser ? 'USER' : (m.sender === 'manager' ? 'MANAGER' : 'AGENT'),
+    fromId: m.sender,
+    type: m.type,
+    head: '',
+    body: m.body,
+    replyTo: m.reply_to,
+    reaction: m.reaction,
+    via: parseJson(m.meta, {}).source === 'transcript' ? 'transcript' : 'bus',
+    turnId: parseJson(m.meta, {}).turnId || null,
+  };
+}
+
+export function createConversations(db, messaging, registry) {
+  function thread(actorId, { since = 0, limit = MAX } = {}) {
+    if (!ADDRESS.test(actorId) && actorId !== 'hub') return null;
+    const rows = db.prepare(`SELECT * FROM messages WHERE created_at >= ? AND (
+      (sender = 'user' AND id IN (SELECT message_id FROM deliveries WHERE recipient = ?))
+      OR (sender = ? AND id IN (SELECT message_id FROM deliveries WHERE recipient = 'user'))
+      OR (sender = 'user' AND topic = ? )
+      OR (sender = ? AND (topic = 'user' OR topic = 'agent/user'))
+    ) ORDER BY created_at ASC`).all(since, actorId, actorId, `agent/${actorId}`, actorId);
+    const seen = new Set();
+    const out = [];
+    for (const m of rows) {
+      if (parseJson(m.meta, {}).source !== 'transcript') continue;
+      const turnId = parseJson(m.meta, {}).turnId;
+      const key = turnId ? `turn:${turnId}` : m.id;
+      if (seen.has(m.id) || seen.has(key)) continue;
+      seen.add(m.id);
+      if (turnId) seen.add(key);
+      out.push(shape(m, actorId));
+    }
+    const wire = messaging.involving(actorId, since)
+      .filter((m) => (m.from === 'user' && m.to.includes(actorId)) || (m.from === actorId && m.to.includes('user')));
+    const replyOf = new Map(wire.filter((r) => r.replyTo && r.from === actorId).map((r) => [r.replyTo, r]));
+    for (const m of wire) {
+      if (seen.has(m.id) || (m.meta && m.meta.source === 'transcript')) continue;
+      seen.add(m.id);
+      const fromUser = m.from === 'user';
+      const reply = fromUser ? replyOf.get(m.id) || null : null;
+      const receipt = messaging.statusOf(m.id).find((s) => s.to === (fromUser ? actorId : 'user'));
+      const wake = fromUser && receipt && receipt.state === 'queued' ? registry.fact('wake', actorId) : null;
+      const wakeReceipt = wake && wake.at >= m.at - 1000 ? messaging.statusOf(wake.messageId).find((s) => s.to === wake.parent) : null;
+      out.push({
+        id: m.id, at: m.at, from: fromUser ? 'USER' : (m.from === 'manager' ? 'MANAGER' : 'AGENT'),
+        fromId: m.from, type: m.type, head: '', body: m.body, replyTo: m.replyTo, reaction: m.reaction, via: 'bus',
+        delivery: {
+          intoChatAt: receipt ? receipt.deliveredAt : null,
+          repliedAt: reply ? reply.at : null,
+          busState: receipt ? receipt.state : 'queued',
+          wakeVia: wakeReceipt ? wake.parent : null,
+          wokenAt: wakeReceipt ? wakeReceipt.deliveredAt : null,
+        },
+        reactions: [
+          receipt && ['delivered', 'acked', 'unacked'].includes(receipt.state) ? { emoji: '👀', at: receipt.deliveredAt, auto: true } : null,
+          m.reaction ? { emoji: m.reaction, at: m.at } : null,
+          reply && reply.reaction ? { emoji: reply.reaction, at: reply.at } : null,
+        ].filter(Boolean),
+      });
+    }
+    out.sort((a, b) => a.at - b.at);
+    const actor = registry.get(actorId);
+    const awaiting = messaging.awaiting(actorId);
+    const pres = registry.presence(actorId);
+    const typing = awaiting.length && pres && pres.last_event !== 'stop' && Date.now() - pres.last_seen < 5 * 60e3
+      ? { since: awaiting[0] ? Date.now() : pres.last_seen, at: pres.last_seen, tool: pres.last_tool }
+      : null;
+    return { messages: out.slice(-limit), actor, typing };
+  }
+
+  function importTranscriptTurn({ sessionId, turnId, at, prompt, reply }) {
+    if (!sessionId || !turnId) return;
+    const meta = JSON.stringify({ source: 'transcript', turnId });
+    const promptId = `t-${String(turnId).slice(0, 40)}-p`;
+    const replyId = `t-${String(turnId).slice(0, 40)}-r`;
+    const ins = db.prepare(`INSERT OR IGNORE INTO messages (id, sender, topic, type, body, needs_reply, expires_at, reply_to, reaction, from_name, created_at, meta)
+      VALUES (?, ?, ?, ?, ?, 0, ?, ?, NULL, ?, ?, ?)`);
+    const del = db.prepare(`INSERT OR IGNORE INTO deliveries (message_id, recipient, state, queued_at, delivered_at, delivered_via) VALUES (?, ?, 'acked', ?, ?, 'transcript')`);
+    if (prompt) {
+      ins.run(promptId, 'user', `agent/${sessionId}`, 'PROMPT', String(prompt).slice(0, 4000), at + 365 * 24 * 3600e3, null, 'You', at, meta);
+      del.run(promptId, sessionId, at, at);
+    }
+    if (reply) {
+      ins.run(replyId, sessionId, 'user', 'REPLY', String(reply).slice(0, 4000), at + 365 * 24 * 3600e3, prompt ? promptId : null, null, at + 1, meta);
+      del.run(replyId, 'user', at + 1, at + 1);
+    }
+  }
+
+  /** Remove the opening prompt imported for a chat that turned out to be a subagent (its brief is not your prompt). */
+  function forgetOpening(sessionId) {
+    const base = `t-${`${sessionId}-open`.slice(0, 40)}`;
+    for (const id of [`${base}-p`, `${base}-r`]) {
+      db.prepare('DELETE FROM deliveries WHERE message_id = ?').run(id);
+      db.prepare('DELETE FROM messages WHERE id = ?').run(id);
+    }
+  }
+
+  function dmPartners(since = Date.now() - 30 * 24 * 3600e3) {
+    const map = new Map();
+    for (const m of messaging.involving('user', since)) {
+      const other = m.from === 'user' ? m.to.find((x) => x !== 'user') : m.from;
+      if (other && other !== 'user') map.set(other, Math.max(map.get(other) || 0, m.at));
+    }
+    return [...map].map(([id, lastAt]) => ({ id, lastAt })).sort((a, b) => b.lastAt - a.lastAt);
+  }
+
+  return { thread, importTranscriptTurn, forgetOpening, dmPartners };
+}