@agentpulselabs/cli-plugin-pulse 1.0.0 → 1.1.2

package/src/hub/lib/status.mjs

@@ -0,0 +1,147 @@
+// agents-hub lib/status.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// A status you set by hand on a delivery or an agent: stored once as the registry fact `status_override`, applied over
+// the derived status when the hub projects its rows, and recorded in the task channels as a USER post. Pure.
+
+export const USER_STATUSES = ['done', 'blocked', 'stopped', 'handed-over', 'working'];
+export const STATUS_LIMITS = Object.freeze({ id: 100, reason: 500, to: 120, key: 240 });
+/** The Board's step columns (channels.STEPS), and the ids a move names them by. */
+const STEP_NAMES = ['Research', 'Design', 'Mockup', 'Build', 'Review', 'Checks', 'Proof'];
+export const STEP_IDS = STEP_NAMES.map((name) => name.toLowerCase());
+const STREAM_KEY = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+/** Done and Stopped hold until you change them; the others give way to the next agent header in the channel. */
+const STICKY = new Set(['done', 'stopped']);
+const HEADER_TYPE = { done: 'DONE', blocked: 'BLOCKER', stopped: 'STOPPED', 'handed-over': 'HANDED OVER', working: 'STATUS' };
+const LABEL = { done: 'Done', blocked: 'Blocked', stopped: 'Stopped', 'handed-over': 'Handed over', working: 'Working' };
+const DELIVERY_STATUS = { done: 'done', stopped: 'done', blocked: 'blocked', 'handed-over': 'on-track', working: 'on-track' };
+const AGENT_STATUS = { done: 'done', stopped: 'done', blocked: 'stuck', 'handed-over': 'waiting', working: 'working' };
+const LOCAL_ID = /^[^\0-\x1f\x7f]+$/;
+
+/** One line, no control or bidi characters: the reason goes into a channel header that editors also render. */
+const oneLine = (s) => s.replace(/[\0-\x1f\x7f-\x9f\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]+/g, ' ').replace(/\s+/g, ' ').trim();
+
+function text(v, name, max, required) {
+  if (v === undefined || v === null) return required ? { error: `${name} is required` } : { value: null };
+  if (typeof v !== 'string') return { error: `${name} must be text` };
+  const value = oneLine(v);
+  if (!value) return required ? { error: `${name} is required` } : { value: null };
+  if (value.length > max) return { error: `${name} must be at most ${max} characters` };
+  return { value };
+}
+
+/**
+ * A POST /api/status body → { target, status, reason, to }, or for a stream (a card moved to a step column)
+ * { target, step }; or { error }. The hub works out the rest of a move itself, so a move carries nothing else.
+ */
+export function statusRequest(body) {
+  const t = body && body.target;
+  if (!t || typeof t !== 'object' || !['delivery', 'agent', 'stream'].includes(t.kind)) return { error: 'target must be a delivery, an agent or a stream' };
+  if (t.kind === 'stream') {
+    if (typeof t.id !== 'string' || t.id.length > STATUS_LIMITS.key || !STREAM_KEY.test(t.id)) return { error: 'target id must be a <repo>/<channel> stream key' };
+    if (!STEP_IDS.includes(body.step)) return { error: `step must be one of ${STEP_IDS.join(', ')}` };
+    const extra = Object.keys(body).find((k) => !['target', 'step'].includes(k));
+    if (extra) return { error: `${extra} is not part of a move` };
+    return { target: { kind: 'stream', id: t.id }, step: body.step };
+  }
+  if (body.step !== undefined) return { error: 'step is only for a stream' };
+  if (typeof t.id !== 'string' || !t.id || t.id.length > STATUS_LIMITS.id || !LOCAL_ID.test(t.id)) return { error: 'invalid target id' };
+  if (!USER_STATUSES.includes(body.status)) return { error: `status must be one of ${USER_STATUSES.join(', ')}` };
+  const reason = text(body.reason, 'reason', STATUS_LIMITS.reason, body.status === 'blocked');
+  if (reason.error) return { error: reason.error };
+  if (body.status !== 'handed-over' && body.to !== undefined && body.to !== null) return { error: 'to is only for handed-over' };
+  const to = body.status === 'handed-over' ? text(body.to, 'to', STATUS_LIMITS.to, true) : { value: null };
+  if (to.error) return { error: to.error };
+  return { target: { kind: t.kind, id: t.id }, status: body.status, reason: reason.value, to: to.value };
+}
+
+export const overrideKey = (target) => `${target.kind}:${target.id}`;
+
+/** Header text without `#`: the parser reads "#12" in any header as a finding id that a closing word would close. */
+const headerSafe = (s) => oneLine(s.replace(/#/g, ''));
+
+/** The channel record of a status you set: one USER header, in the time format decisionPost writes. */
+const clock = (at) => [at.getHours(), at.getMinutes(), at.getSeconds()].map((n) => String(n).padStart(2, '0')).join(':');
+
+export function auditPost({ status, reason = null, to = null }, { at = new Date(), who = null } = {}) {
+  const hhmmss = clock(at);
+  const what = [to ? `to ${headerSafe(to)}` : null, reason ? headerSafe(reason) : null].filter(Boolean).join(': ');
+  return `\n## [USER] ${hhmmss} ${HEADER_TYPE[status]} — set from the Board${who ? ` for ${headerSafe(who)}` : ''}${what ? `: ${what}` : ''}\n`;
+}
+
+/** "Blocked, set by you: org down" — the words a row shows for a status you set. */
+export function overrideText(o) {
+  const by = !o.by || o.by === 'user' ? 'you' : o.by;
+  return `${LABEL[o.status]}${o.to ? ` to ${o.to}` : ''}, set by ${by}${o.reason ? `: ${o.reason}` : ''}`;
+}
+
+/**
+ * Whether an agent has posted a header that moves the work (channels.movesWork: not USER posts, so not the audit post,
+ * and not check-ins) since status `o` was set. Headers carry agents' clocks, not the hub's, so this goes by place in
+ * the channel: `o.seqs` holds the audit post's position in each stream it went to, `seqOf(key)` the newest moving
+ * header's. A status set before the hub recorded positions falls back to `agentAt`, the newest such header's time.
+ */
+export function movedSince(o, { agentAt = 0, seqOf = () => 0 } = {}) {
+  const seqs = Object.entries(o.seqs || {});
+  return seqs.length ? seqs.some(([key, seq]) => seqOf(key) > seq) : agentAt > o.at;
+}
+
+/** For movedSince: where the work under a delivery fact (its streams) or an agent-row fact (its own stream) last moved. */
+export function workMoved(kind, row) {
+  if (kind === 'delivery') {
+    const streams = row.streams || [];
+    const at = new Map(streams.map((s) => [s.key, s.agentSeq || 0]));
+    return { agentAt: Math.max(0, ...streams.map((s) => s.agentAt || 0)), seqOf: (key) => at.get(key) || 0 };
+  }
+  return { agentAt: row.movedAt || 0, seqOf: (key) => (key === row.streamKey ? row.movedSeq || 0 : 0) };
+}
+
+/** Whether a status you set still holds: Done and Stopped stick, the soft ones last until the work moves. */
+export const overrideHolds = (o, moved = {}) => !!o && USER_STATUSES.includes(o.status) && (STICKY.has(o.status) || !movedSince(o, moved));
+
+/**
+ * A delivery or agent row with the status you set over its derived one. An open ask stays in front: only Stopped, or
+ * Done on anything but a result waiting for your Accept, takes a delivery out of needs-you.
+ */
+export function withOverride(row, o, { kind, ...moved }) {
+  if (!overrideHolds(o, moved)) return row;
+  const override = { status: o.status, reason: o.reason || null, to: o.to || null, by: o.by || 'user', at: o.at };
+  const asking = kind === 'delivery' && row.status === 'needs-you';
+  if (asking && !(o.status === 'stopped' || (o.status === 'done' && !(row.ask && row.ask.kind === 'result')))) return { ...row, override };
+  if (kind === 'agent') {
+    return { ...row, status: AGENT_STATUS[o.status], waitingOn: o.status === 'handed-over' ? override.to : row.waitingOn, override };
+  }
+  return { ...row, status: DELIVERY_STATUS[o.status], reason: overrideText(override), override };
+}
+
+/** The channel record of a card you moved: a USER NOTE, which is chatter, so it never moves the derived step itself. */
+export const movePost = ({ step }, { at = new Date() } = {}) => `\n## [USER] ${clock(at)} NOTE — moved to ${STEP_NAMES[STEP_IDS.indexOf(step)]} from the Board\n`;
+
+/**
+ * Whether a step you moved a card to still holds on stream `s` (a streamView). It ends at the first header that moves
+ * the work, comes after the move's NOTE in the channel (`o.seq`, its position), and either leaves the derived step
+ * where it was not when you moved the card (`fromStep`) or implies on its own a step beyond yours (`stepSeq[i]`: the
+ * position of the newest such header implying step i or later). So commits in Build keep a move to Review, and the
+ * next findings end a move back to Build.
+ */
+export function stepHolds(o, s) {
+  if (!o || !STEP_IDS.includes(o.step) || !Number.isInteger(o.seq) || s.done) return false;
+  const mine = STEP_IDS.indexOf(o.step);
+  if ((s.agentSeq || 0) > o.seq && s.step !== o.fromStep) return false;
+  return !(((s.stepSeq || [])[mine + 1] || 0) > o.seq);
+}
+
+/** A stream row in the column you moved it to, with `override` saying who moved it and when. */
+export function withStep(s, o) {
+  if (!stepHolds(o, s)) return s;
+  const step = STEP_IDS.indexOf(o.step);
+  return { ...s, step, stepName: STEP_NAMES[step], override: { step: o.step, by: o.by || 'user', at: o.at } };
+}
+
+/** A delivery row with its streams' moves applied; its own step and counts follow them, as buildDeliveries counts. */
+export function withSteps(d, overrideOf) {
+  const streams = (d.streams || []).map((s) => withStep(s, overrideOf(s.key)));
+  if (streams.every((s, i) => s === d.streams[i])) return d;
+  const open = streams.filter((s) => !s.done);
+  const stepCounts = STEP_NAMES.map((_, i) => open.filter((s) => s.step === i).length);
+  const step = open.length ? stepCounts.lastIndexOf(Math.max(...stepCounts)) : d.step;
+  return { ...d, streams, stepCounts, step, stepName: step == null ? null : STEP_NAMES[step] };
+}

package/src/hub/lib/store.mjs

@@ -0,0 +1,106 @@
+// agents-hub lib/store.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// The hub's files. Everything is append-only JSONL or one small JSON file, so any sandboxed session can write it;
+// for the same reason everything read back is shape-checked before use.
+import fs from 'node:fs';
+import path from 'node:path';
+import { hubHome } from '../home.mjs';
+
+export const HUB = hubHome();
+const STATE = path.join(HUB, 'state');
+const EVENTS = path.join(STATE, 'events.jsonl');
+const REQUESTS = path.join(STATE, 'requests');
+const SETTINGS = path.join(STATE, 'settings.json');
+export const KEEPAWAKE_STATUS = path.join(STATE, 'keepawake-status.json');
+const EVENTS_TAIL_BYTES = 1024 * 1024;
+const NUDGE_CHOICES = [0, 5, 10, 15, 30];
+const KEEP_AWAKE_MODES = ['off', 'agents', 'always'];
+
+const DEFAULT_SETTINGS = { keepAwake: { mode: 'off' }, wake: { nudgeEveryMin: 0, macWakeAt: null } };
+
+fs.mkdirSync(REQUESTS, { recursive: true });
+
+const readJson = (f, fallback) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return fallback; } };
+const str = (v, max) => (typeof v === 'string' ? v.slice(0, max) : '');
+const isEvent = (e) => e && typeof e === 'object' && Number.isFinite(e.at) && typeof e.from === 'string' && typeof e.type === 'string';
+
+export function appendEvent(e) {
+  const event = { at: Date.now(), ...e };
+  fs.appendFileSync(EVENTS, JSON.stringify(event) + '\n');
+  return event;
+}
+
+/** Events since sinceMs, from the last megabyte of the log (older ones are history the views never show). */
+export function readEvents(sinceMs = 0) {
+  let text = '';
+  try {
+    const st = fs.statSync(EVENTS);
+    const len = Math.min(EVENTS_TAIL_BYTES, st.size);
+    const fd = fs.openSync(EVENTS, 'r');
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, st.size - len);
+    fs.closeSync(fd);
+    text = buf.toString('utf8');
+    if (len < st.size) text = text.slice(text.indexOf('\n') + 1);
+  } catch { return []; }
+  return text.split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } })
+    .filter((e) => isEvent(e) && e.at >= sinceMs)
+    .map((e) => ({ ...e, to: typeof e.to === 'string' ? e.to : '*', text: str(e.text, 500) }));
+}
+
+export function addRequest({ from, kind, title, files = [] }) {
+  const id = `r-${Date.now().toString(36)}`;
+  const req = { id, from: [String(from)], kind: String(kind), title: String(title), files, status: 'queued', at: Date.now() };
+  fs.writeFileSync(path.join(REQUESTS, `${id}.json`), JSON.stringify(req, null, 2));
+  appendEvent({ from: String(from), to: 'manager', type: 'REQUEST', text: `${kind}: ${title}`, ref: id });
+  return req;
+}
+
+export function readRequests() {
+  let files = [];
+  try { files = fs.readdirSync(REQUESTS).filter((f) => f.endsWith('.json')); } catch { return []; }
+  return files.map((f) => readJson(path.join(REQUESTS, f), null))
+    .filter((r) => r && typeof r === 'object' && Number.isFinite(r.at) && typeof r.title === 'string')
+    .map((r) => ({ id: str(r.id, 60), title: str(r.title, 200), kind: str(r.kind, 30), status: str(r.status, 20) || 'queued', at: r.at,
+      from: (Array.isArray(r.from) ? r.from : [r.from]).filter((x) => typeof x === 'string').slice(0, 10) }));
+}
+
+const ACCEPTED = path.join(STATE, 'accepted.json');
+
+/** Deliveries whose result you accepted, by delivery id → when. Kept in its own file so it never rolls off a log. */
+export function readAccepted() {
+  const a = readJson(ACCEPTED, {}) || {};
+  return new Map(Object.entries(a).filter(([k, v]) => typeof k === 'string' && Number.isFinite(v)));
+}
+
+export function acceptDelivery(id) {
+  const a = Object.fromEntries(readAccepted());
+  a[id] = Date.now();
+  fs.writeFileSync(ACCEPTED, JSON.stringify(a, null, 2));
+}
+
+export function readSettings() {
+  const s = readJson(SETTINGS, {}) || {};
+  return validSettings({ keepAwake: { ...DEFAULT_SETTINGS.keepAwake, ...(s.keepAwake || {}) }, wake: { ...DEFAULT_SETTINGS.wake, ...(s.wake || {}) } });
+}
+
+/** Only known keys and values survive: a nudge interval from the list, a keep-awake mode, a wake time as HH:MM. */
+export function validSettings(s) {
+  const mode = KEEP_AWAKE_MODES.includes(s.keepAwake && s.keepAwake.mode) ? s.keepAwake.mode : 'off';
+  const every = NUDGE_CHOICES.includes(Number(s.wake && s.wake.nudgeEveryMin)) ? Number(s.wake.nudgeEveryMin) : 0;
+  const at = s.wake && typeof s.wake.macWakeAt === 'string' && /^([01]\d|2[0-3]):[0-5]\d$/.test(s.wake.macWakeAt) ? s.wake.macWakeAt : null;
+  return { keepAwake: { mode }, wake: { nudgeEveryMin: every, macWakeAt: at } };
+}
+
+export function writeSettings(patch) {
+  const cur = readSettings();
+  const next = validSettings({ keepAwake: { ...cur.keepAwake, ...((patch && patch.keepAwake) || {}) }, wake: { ...cur.wake, ...((patch && patch.wake) || {}) } });
+  fs.writeFileSync(SETTINGS, JSON.stringify(next, null, 2));
+  return next;
+}
+
+/** What the keep-awake helper last reported; `installed` is false when it has not checked in for 90 s. */
+export function keepAwakeStatus() {
+  const s = readJson(KEEPAWAKE_STATUS, null);
+  if (!s || !Number.isFinite(s.heartbeat)) return { installed: false, running: false };
+  return { running: !!s.running, since: Number.isFinite(s.since) ? s.since : null, installed: Date.now() - s.heartbeat < 90e3 };
+}

package/src/hub/lib/titles.mjs

@@ -0,0 +1,29 @@
+// agents-hub lib/titles.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// The title Cursor gives each chat (the one in its chat list), read from Cursor's own store so a delivery is named
+// the way you already know it. Read-only; any failure just means no title, and the caller falls back to the prompt.
+import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+
+const DB = path.join(os.homedir(), 'Library', 'Application Support', 'Cursor', 'User', 'globalStorage', 'state.vscdb');
+const SQLITE = '/usr/bin/sqlite3';
+const ID = /^[0-9a-f-]{36}$/;
+const TTL_MS = 60e3;
+const cache = new Map();
+
+/** Cursor's chat titles for these conversation ids, as a Map id → title (ids it has no title for are left out). */
+export function chatTitles(ids) {
+  const now = Date.now();
+  const want = [...new Set(ids)].filter((id) => ID.test(id) && !(cache.has(id) && now - cache.get(id).at < TTL_MS));
+  if (want.length) {
+    let rows = [];
+    try {
+      const sql = `SELECT substr(key, 14) AS id, json_extract(value, '$.name') AS name FROM cursorDiskKV WHERE key IN (${want.map((id) => `'composerData:${id}'`).join(',')});`;
+      const out = execFileSync(SQLITE, ['-readonly', '-json', `file:${DB}?mode=ro`, sql], { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] });
+      rows = out.trim() ? JSON.parse(out) : [];
+    } catch { rows = []; }
+    const got = new Map(rows.filter((r) => typeof r.name === 'string' && r.name.trim()).map((r) => [r.id, r.name.trim().slice(0, 80)]));
+    for (const id of want) cache.set(id, { at: now, name: got.get(id) || null });
+  }
+  return new Map(ids.map((id) => [id, cache.get(id) && cache.get(id).name]).filter(([, name]) => name));
+}

package/src/hub/lib/transcript-feed.mjs

@@ -0,0 +1,72 @@
+// agents-hub lib/transcript-feed.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Notices Cursor transcript writes within about a second without fs.watch: a recursive watch over ~/.cursor/projects
+ * (hundreds of folders) runs out of file handles and then dies silently. Instead, stat the recently active session
+ * files every second, and rescan every session every 30 s so a resumed old session or a new project is picked up.
+ */
+const FAST_MS = 1000;
+const FULL_MS = 30e3;
+const ACTIVE_MS = 6 * 3600e3;
+
+const safe = (fn, fallback) => { try { return fn(); } catch { return fallback; } };
+const dirs = (dir) => safe(() => fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name), []);
+const jsonl = (dir) => safe(() => fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl')).map((f) => path.join(dir, f)), []);
+const sig = (file) => safe(() => { const s = fs.statSync(file); return { m: s.mtimeMs, z: s.size }; }, null);
+
+function sessionFiles(sessionDir) {
+  return [...jsonl(sessionDir), ...jsonl(path.join(sessionDir, 'subagents'))];
+}
+
+export function watchTranscripts(projectsDir, onChange) {
+  const seen = new Map();
+  const activeSessions = new Set();
+  const activeRoots = new Set();
+
+  const check = (file, now, notify) => {
+    const s = sig(file);
+    if (!s) return false;
+    const was = seen.get(file);
+    seen.set(file, s);
+    if (notify && (!was || was.m !== s.m || was.z !== s.z)) onChange(file);
+    return now - s.m < ACTIVE_MS;
+  };
+
+  const full = (notify) => {
+    const now = Date.now();
+    activeSessions.clear();
+    activeRoots.clear();
+    for (const project of dirs(projectsDir)) {
+      const root = path.join(projectsDir, project, 'agent-transcripts');
+      const sessions = dirs(root);
+      if (!sessions.length) continue;
+      const rootRecent = now - (sig(root)?.m || 0) < ACTIVE_MS;
+      let any = false;
+      for (const id of sessions) {
+        const dir = path.join(root, id);
+        let live = false;
+        for (const f of sessionFiles(dir)) live = check(f, now, notify) || live;
+        if (live) { activeSessions.add(dir); any = true; }
+      }
+      if (any || rootRecent) activeRoots.add(root);
+    }
+  };
+
+  const fast = () => {
+    const now = Date.now();
+    for (const root of activeRoots) {
+      for (const id of dirs(root)) {
+        const dir = path.join(root, id);
+        if (!activeSessions.has(dir) && sessionFiles(dir).some((f) => !seen.has(f))) activeSessions.add(dir);
+      }
+    }
+    for (const dir of activeSessions) for (const f of sessionFiles(dir)) check(f, now, true);
+  };
+
+  full(false);
+  setInterval(() => safe(fast), FAST_MS).unref();
+  setInterval(() => safe(() => full(true)), FULL_MS).unref();
+  return { watching: () => ({ sessions: activeSessions.size, projects: activeRoots.size }) };
+}