@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/src/lib/doctorWarnings.js

@@ -0,0 +1,53 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileBounded } from './subprocess.js';
+
+/**
+ * `pulse doctor` warnings (Pulse 1.1.1): facts about this machine worth knowing that never make it unhealthy. Each
+ * probe answers `{ ok: true, warn, message, ... }`, or `{ ok: true, skipped }` when there is nothing to look at.
+ */
+
+/** In use at or above this share of max_connections, the local Postgres is close to refusing new connections. */
+export const POSTGRES_HEADROOM_WARN = 0.8;
+/** The hook events the Pulse hook needs beyond postToolUse, stop and afterAgentResponse: failed Shell calls bind aliases, the rest say whether a session is in a tool call or gone. */
+export const HUB_HOOK_EVENTS = ['postToolUseFailure', 'preToolUse', 'sessionEnd'];
+const QUERY = "SELECT count(*), current_setting('max_connections') FROM pg_stat_activity";
+
+/** Connections in use against max_connections on the local Postgres (PULSE_PG_URL, else localhost), through psql. */
+export async function postgresHeadroom({ url = process.env.PULSE_PG_URL || 'postgres://localhost/postgres', run = execFileBounded } = {}) {
+  let stdout;
+  try {
+    ({ stdout } = await run('psql', [url, '-X', '-A', '-t', '-F', ',', '-c', QUERY], { timeout: 5_000 }));
+  } catch (error) {
+    return { ok: true, skipped: error && error.code === 'ENOENT' ? 'psql is not installed' : 'no local Postgres answered' };
+  }
+  const [used, max] = String(stdout).trim().split(',').map(Number);
+  if (!Number.isFinite(used) || !Number.isFinite(max) || max <= 0) return { ok: true, skipped: 'unreadable answer from psql' };
+  const warn = used / max >= POSTGRES_HEADROOM_WARN;
+  return {
+    ok: true, used, max, warn,
+    message: `Local Postgres: ${used} of ${max} connections in use${warn ? `; past ${Math.round(POSTGRES_HEADROOM_WARN * 100)}%, new connections may soon be refused` : ''}.`,
+  };
+}
+
+/** Which of HUB_HOOK_EVENTS ~/.cursor/hooks.json sends to the hub hook (hub-bridge.mjs). Read-only. */
+export async function hubHooks({ file = path.join(os.homedir(), '.cursor', 'hooks.json') } = {}) {
+  let hooks;
+  try {
+    hooks = JSON.parse(await readFile(file, 'utf8')).hooks || {};
+  } catch {
+    return { ok: true, skipped: 'no readable ~/.cursor/hooks.json' };
+  }
+  const wired = Object.entries(hooks)
+    .filter(([, entries]) => Array.isArray(entries) && entries.some((e) => e && typeof e.command === 'string' && e.command.includes('hub-bridge.mjs')))
+    .map(([event]) => event);
+  if (!wired.length) return { ok: true, skipped: 'the hub hook is not in ~/.cursor/hooks.json' };
+  const missing = HUB_HOOK_EVENTS.filter((event) => !wired.includes(event));
+  return {
+    ok: true, wired, missing, warn: missing.length > 0,
+    message: missing.length
+      ? `~/.cursor/hooks.json does not send ${missing.join(', ')} to the hub hook: a bus register chained to a failing command does not bind, and a session in a long tool call can look gone. Add them with the same command as postToolUse.`
+      : 'The hub hook gets every event it uses.',
+  };
+}

package/src/lib/errors.js

@@ -8,6 +8,20 @@ export class HubError extends Error {
   }
 }
 
+/** Pulse 1.1.2 (SCOPE-02): what fixes a refusal no retry can fix: a sign-in missing scopes, or a machine grant missing a capability. */
+export const SCOPE_FIX = 'agentpulse pulse login';
+export const GRANT_FIX = 'agentpulse pulse log-write on';
+
+/** A refusal for scopes or grant as health shows it (`{ code, missingScopes, fix }`), or null for any other error. */
+export function scopeBlock(error) {
+  const code = error?.code;
+  if (code === 'HUB_SCOPE_DENIED' || code === 'HUB_SCOPE_MISSING') {
+    return { code, missingScopes: Array.isArray(error.details?.missingScopes) ? error.details.missingScopes : [], fix: SCOPE_FIX };
+  }
+  if (code === 'capability_denied') return { code, missingScopes: [], fix: GRANT_FIX };
+  return null;
+}
+
 export function assertNever(value, label = 'value') {
   throw new HubError('HUB_INTERNAL_UNHANDLED_VARIANT', `Unhandled ${label}: ${String(value)}`);
 }

package/src/lib/hubDbReader.js

@@ -0,0 +1,132 @@
+import path from 'node:path';
+import { openDatabase } from './sqlite.js';
+
+const parseJson = (text, fallback) => {
+  if (text === null || text === undefined || text === '') return fallback;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return fallback;
+  }
+};
+
+/** An actor row in the local registry's shape (agents-hub core/registry.mjs rowActor at 37a0b2f, without `title`). */
+export function rowActor(r) {
+  return {
+    id: r.id,
+    node_type: r.node_type,
+    role: r.role,
+    parent_id: r.parent_id,
+    delivery_id: r.delivery_id,
+    stream_key: r.stream_key,
+    cursor_title: r.cursor_title,
+    prompt_title: r.prompt_title,
+    persona_name: r.persona_name,
+    persona_first: r.persona_first,
+    persona_username: r.persona_username,
+    persona_seed: r.persona_seed,
+    persona: parseJson(r.persona_json, null),
+    source: r.source,
+    topics: parseJson(r.topics, []),
+    started_at: r.started_at,
+    last_at: r.last_at,
+    tokens_est: r.tokens_est,
+    msgs_in: r.msgs_in,
+    msgs_out: r.msgs_out,
+    repo: r.repo,
+    channel: r.channel,
+    synthetic: !!r.synthetic,
+    extra: parseJson(r.extra, null),
+  };
+}
+
+const plain = (row) => ({ ...row });
+
+/**
+ * Read-only access to the local hub's `state/hub.db`. Each `read(fn)` opens the file read-only (no `immutable`, no
+ * pragma that writes), runs every query of one pass inside a single short read transaction so recipients and their
+ * messages come from the same snapshot, and closes the handle, so the hub's writers and WAL checkpoints never wait on
+ * a reader across an await. `fn` must be synchronous.
+ */
+export class HubDbReader {
+  constructor({ hubDir, file = path.join(hubDir, 'state', 'hub.db'), busyMs = 2_000 }) {
+    this.file = file;
+    this.busyMs = busyMs;
+  }
+
+  read(fn) {
+    const db = openDatabase(this.file, { readOnly: true });
+    try {
+      db.prepare(`PRAGMA busy_timeout = ${Number(this.busyMs)}`).run();
+      db.prepare('BEGIN').run();
+      try {
+        return fn(new HubSnapshot(db));
+      } finally {
+        db.prepare('COMMIT').run();
+      }
+    } finally {
+      db.close();
+    }
+  }
+}
+
+/** The queries of one read transaction. */
+export class HubSnapshot {
+  constructor(db) {
+    this.db = db;
+  }
+
+  /** Every actor in table order (the order the local registry lists them). */
+  actors() {
+    return this.db.prepare('SELECT * FROM actors ORDER BY rowid').all().map(rowActor);
+  }
+
+  presence() {
+    return this.db.prepare('SELECT actor_id, last_seen, last_event FROM presence ORDER BY rowid').all().map(plain);
+  }
+
+  /** Messages created at or after `sinceMs`, in (created_at, rowid) order: rowid breaks ties the way the hub inserted them. */
+  messagesSince(sinceMs) {
+    return this.db.prepare('SELECT rowid AS _rowid, * FROM messages WHERE created_at >= ? ORDER BY created_at, rowid').all(sinceMs)
+      .map((row) => ({ ...row, meta: parseJson(row.meta, {}) }));
+  }
+
+  messageIdsSince(sinceMs) {
+    return new Set(this.db.prepare('SELECT id FROM messages WHERE created_at >= ?').all(sinceMs).map((row) => row.id));
+  }
+
+  messageExists(id) {
+    return Boolean(this.db.prepare('SELECT 1 AS found FROM messages WHERE id = ?').get(id));
+  }
+
+  /** Recipient rows of these messages, in table order. */
+  recipients(messageIds) {
+    const out = new Map();
+    const statement = this.db.prepare(
+      'SELECT message_id, recipient, state, attempts, delivered_at, delivered_via, acked_at FROM deliveries WHERE message_id = ? ORDER BY rowid',
+    );
+    for (const id of messageIds) out.set(id, statement.all(id).map(plain));
+    return out;
+  }
+
+  /** One recipient row with its message's expiry, or null when either is gone. */
+  receipt(messageId, recipient) {
+    const row = this.db.prepare(
+      `SELECT d.message_id, d.recipient, d.state, d.attempts, d.delivered_at, d.delivered_via, d.acked_at, m.expires_at, m.topic
+         FROM deliveries d JOIN messages m ON m.id = d.message_id
+        WHERE d.message_id = ? AND d.recipient = ?`,
+    ).get(messageId, recipient);
+    return row ? plain(row) : null;
+  }
+
+  eventsAfter(id) {
+    return this.db.prepare('SELECT id, at, kind, actor, payload FROM events WHERE id > ? ORDER BY id').all(id)
+      .map((row) => ({ ...row, payload: parseJson(row.payload, {}) }));
+  }
+
+  /** Facts of these kinds with their payload text as stored (parsed by the caller only when it changed). */
+  facts(kinds) {
+    const statement = this.db.prepare('SELECT kind, key, payload, updated_at FROM facts WHERE kind = ? ORDER BY key');
+    return kinds.flatMap((kind) => statement.all(kind).map(plain));
+  }
+}

package/src/lib/hubMapping.js

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto';
+import { pathRejected } from './mirrorContract.js';
+import { canonicalJson } from './planContract.js';
+
+/**
+ * The local hub's rows as Pulse commands (design §11 table, cf-phase2 PLAN v2), as pure functions: the import, the
+ * shadow feed and anything that captures the same rows later (Phase 3) produce the same keys and payloads. Redaction
+ * is not done here: callers pass rows through the UploadRedactor, and content keys are taken from redacted payloads.
+ */
+const KEY_PART = /^[A-Za-z0-9._:/@-]{1,200}$/;
+const PERSONA_FIELDS = ['name', 'first', 'username', 'seed', 'personality'];
+
+const sha = (text) => createHash('sha256').update(text).digest('hex');
+export const without = (object, ...keys) => Object.fromEntries(Object.entries(object).filter(([key]) => !keys.includes(key)));
+
+/** `<label>:<part>` when the part is key-safe, else `<label>:h:<sha40>`, so a key never carries a space, path or secret. */
+export function keyPart(label, part) {
+  return KEY_PART.test(String(part)) && !pathRejected(String(part)) ? `${label}:${part}` : `${label}:h:${sha(String(part)).slice(0, 40)}`;
+}
+
+/** The content key of a state entity: the redacted payload without its `at`, digested. */
+export function contentSha(redactedPayload) {
+  return sha(canonicalJson(without(redactedPayload, 'at'))).slice(0, 12);
+}
+
+export function actorPayload(actor) {
+  return { id: actor.id, actor, at: Math.floor(Number(actor.last_at) || 0) };
+}
+
+export function messagePayload(message, recipients) {
+  return {
+    id: message.id, from: message.sender, fromName: message.from_name ?? null, topic: message.topic, type: message.type,
+    body: message.body, to: [...new Set(recipients.map((row) => row.recipient))], needsAck: Boolean(message.needs_reply),
+    expiresAt: Number(message.expires_at), replyTo: message.reply_to ?? null, reaction: message.reaction ?? null,
+    meta: message.meta ?? {}, at: Number(message.created_at),
+  };
+}
+
+/** The receipts a recipient row's current state implies (`leased` is `queued`: leases stay on the machine). */
+export function receiptEvents(row, topic, expiresAt) {
+  const base = { messageId: row.message_id, recipient: row.recipient };
+  const events = [];
+  const state = row.state === 'leased' ? 'queued' : row.state;
+  if (row.delivered_at !== null && row.delivered_at !== undefined) {
+    events.push({ type: 'receipt.delivered', key: `rcpt:${row.message_id}:${row.recipient}:delivered`, payload: { ...base, at: Number(row.delivered_at), ...(row.delivered_via ? { via: row.delivered_via } : {}) } });
+  }
+  if (state === 'acked') {
+    events.push({ type: 'receipt.acked', key: `rcpt:${row.message_id}:${row.recipient}:acked`, payload: { ...base, at: Number(row.acked_at ?? row.delivered_at ?? row.queued_at ?? expiresAt) } });
+  }
+  if (state === 'expired') {
+    events.push({ type: 'receipt.expired', key: `rcpt:${row.message_id}:${row.recipient}:expired`, payload: { ...base, at: Number(expiresAt) } });
+  }
+  return { state, events: events.map((event) => ({ ...event, group: `bus:${topic}` })) };
+}
+
+export function eventPayload(event) {
+  return { kind: event.kind, actor: event.actor ?? null, data: event.payload ?? {}, at: Number(event.at) };
+}
+
+export function personaPayload(id, persona) {
+  const value = Object.fromEntries(PERSONA_FIELDS.filter((field) => persona?.[field] !== undefined && persona?.[field] !== null).map((field) => [field, persona[field]]));
+  return { actorId: id, persona: value };
+}
+
+/**
+ * The commands of one fact row, each with its entity and key prefix (content keyed): a delivery travels without its
+ * streams, which go as stream facts of their own so a large delivery fits a command.
+ */
+export function factDescriptors(row, fact) {
+  const entity = `fact:${row.kind}:${row.key}`;
+  const prefix = keyPart(`fact:${row.kind}`, row.key);
+  const at = Number.isFinite(fact.at) ? fact.at : Number(row.updated_at);
+  const one = (type, payload) => ({ type, entity, prefix, group: entity, payload });
+  switch (row.kind) {
+    case 'delivery': {
+      const streams = Array.isArray(fact.streams) ? fact.streams : [];
+      const delivery = { ...without(fact, 'streams'), streamKeys: streams.map((stream) => stream.key) };
+      return [
+        one('delivery.updated', { id: row.key, delivery, at: Number(row.updated_at) }),
+        ...streams.map((stream) => ({
+          type: 'stream.updated', entity: `fact:stream:${stream.key}`, prefix: keyPart('fact:stream', stream.key), group: `fact:stream:${stream.key}`,
+          payload: { key: stream.key, deliveryId: row.key, stream: without(stream, 'deliveryId'), at: Number(row.updated_at) },
+        })),
+      ];
+    }
+    case 'agent-row':
+      return [one('actor.row_updated', { id: row.key, row: fact, at: Number(row.updated_at) })];
+    case 'request':
+      return [one('request.created', { id: row.key, request: fact, at })];
+    case 'accepted':
+      return [one('delivery.accepted', { id: row.key, at })];
+    case 'settings':
+      return [one('settings.changed', { key: row.key, value: fact, at: Number(row.updated_at) })];
+    case 'status_override':
+      return [one('status.overridden', { key: row.key, override: fact, at })];
+    default:
+      throw new TypeError(`hub mapping: fact kind ${row.kind} has no command`);
+  }
+}
+
+/** A task-channel post: its key from its own block's digest and occurrence, never from its inferred time. */
+export function postKey(channelKey, digestId) {
+  return `post:${channelKey}:${digestId}`;
+}
+
+export function postPayload(channel, post, body, truncated) {
+  return { channel, author: post.role, role: post.role, type: post.type, body, at: post.at, ...(truncated ? { truncated } : {}) };
+}