@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.1.2

package/src/hub/workers/runner.mjs

@@ -0,0 +1,145 @@
+// agents-hub workers/runner.mjs at 6b2fb0b. Ported verbatim; every change is a declared seam (test/hub-verbatim.test.js).
+// Hub-owned agents. The hub starts them, owns their sessions, and delivers every message by running one turn of that
+// session with the message as the prompt; the turn's final answer is the reply. No parent chat has to stay alive, and
+// any provider with a driver can run them.
+import { execFile as execFileCb } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { isFyi } from '../core/ids.mjs';
+import { withTx } from '../core/db.mjs';
+import { RETRY_MS, guardTick, retryBusy } from '../core/ticks.mjs';
+import { CHANNEL_POST_RULE, DECISION_RULE, WRITING_GUIDE } from '../lib/writing.mjs';
+import { hubHome } from '../home.mjs';
+
+const execFile = promisify(execFileCb);
+const TICK_MS = 1500;
+const LEASE_MS = 60e3;
+const MAX_PARALLEL = 2;
+const MAX_ATTEMPTS = 3;
+const ROLE = /^[A-Z][A-Z -]{1,30}$/;
+const HUB_CLI = path.join(hubHome(), 'hub.mjs');
+
+/** What every hub-owned agent is told on its first turn, whatever its provider. */
+export function briefPrompt(run, brief) {
+  return [
+    `You are the ${run.role} on a delivery run by the Agent Hub. Your hub address is ${run.id}.`,
+    `Work only inside ${run.workspace}. Never push, release or touch production; never request extra permissions.`,
+    run.stream ? `Your task channel is ${run.workspace}/.agents/${run.stream.split('/').pop()}/channel.md: append posts to it (never rewrite), each starting with a header line \`## [${run.role}] HH:MM:SS TYPE — summary\`.` : null,
+    `To message another agent: node "${HUB_CLI}" bus publish --as ${run.id} --topic agent/<id> --type MESSAGE --body "<text>".`,
+    'Each message to you arrives as a new turn; your final answer in that turn is sent back to the sender as your reply.',
+    `${WRITING_GUIDE} ${CHANNEL_POST_RULE} ${DECISION_RULE}`,
+    '',
+    '## Your brief',
+    brief,
+  ].filter((x) => x !== null).join('\n');
+}
+
+export function messagePrompt(m) {
+  return [`Message from ${m.fromName || m.from} (${m.type}, id ${m.id}):`, '', m.text,
+    '', 'Answer it now; your final answer is sent back as your reply. Then carry on with your task if work remains.'].join('\n');
+}
+
+export function createRunner({ hub, drivers, run = execFile, workspaceRoot, onChange = () => {}, now = Date.now, log = console.error, retryMs = RETRY_MS }) {
+  const { registry, messaging } = hub;
+  const busy = new Map();
+  const aborts = new Map();
+  let timer = null;
+  const save = (r) => { registry.setFact('run', r.id, { ...r, updatedAt: Date.now() }); onChange(); return r; };
+  const runs = () => registry.facts('run').filter((r) => r.state !== 'stopped');
+
+  function inWorkspace(dir) {
+    try {
+      const real = fs.realpathSync(dir);
+      const root = fs.realpathSync(workspaceRoot);
+      return (real === root || real.startsWith(root + path.sep)) && fs.statSync(real).isDirectory() ? real : null;
+    } catch { return null; }
+  }
+
+  /** Start a hub-owned agent: create its session, register it, and queue its brief as its first message. */
+  async function start({ driver, role, workspace, brief, stream = null, parent = 'manager', name = null, mode = 'write' }) {
+    const d = drivers.get(driver);
+    if (!d) return { error: `unknown driver ${driver}` };
+    if (!ROLE.test(String(role || ''))) return { error: 'bad role' };
+    const ws = inWorkspace(workspace);
+    if (!ws) return { error: 'workspace must be a folder inside the hub workspace' };
+    if (typeof brief !== 'string' || !brief.trim()) return { error: 'empty brief' };
+    if (mode === 'write' && !d.can.edit) return { error: `${d.label} cannot edit; give it a read-only role` };
+    const id = (await d.newSession({ run, workspace: ws })) || crypto.randomUUID();
+    const rec = { id, driver, role, workspace: ws, stream, parent, name, mode, state: 'queued', sessionId: d.id === 'cursor' ? id : null, createdAt: Date.now(), turns: 0, costUsd: 0, lastError: null };
+    registry.upsertInferred({ id, node_type: 'agent', role, parent_id: parent, delivery_id: parent, stream_key: stream, persona_name: name, source: 'registered', repo: path.basename(ws), channel: stream ? stream.split('/').pop() : null, started_at: rec.createdAt, last_at: rec.createdAt });
+    save(rec);
+    messaging.publish({ from: 'user', fromName: 'You', topic: `agent/${id}`, type: 'BRIEF', body: brief.slice(0, 4000), needsAck: true, meta: { briefFull: brief.length > 4000 } }, registry.directory());
+    rec.brief = brief;
+    save(rec);
+    return { id, driver, state: rec.state };
+  }
+
+  async function turn(r, m) {
+    const d = drivers.get(r.driver);
+    const prompt = m.type === 'BRIEF' ? briefPrompt(r, r.brief || m.text) : messagePrompt(m);
+    save({ ...r, state: 'working', current: m.id, lastError: null });
+    registry.heartbeat(r.id, { event: 'runner', tool: d.id });
+    const keep = setInterval(() => {
+      try {
+        messaging.renewClaim(r.id, m.id, m.leaseToken, { leaseMs: LEASE_MS });
+        registry.heartbeat(r.id, { event: 'runner', tool: d.id });
+      } catch (e) { log(`runner keepalive for ${r.id} failed: ${e.message}`); }
+    }, 20e3);
+    const abort = new AbortController();
+    aborts.set(r.id, abort);
+    try {
+      const out = await d.turn({ run, sessionId: r.sessionId, workspace: r.workspace, prompt, mode: r.mode, signal: abort.signal });
+      if (abort.signal.aborted) return;
+      // The answer is delivered, acked and recorded together; a busy database retries that, never the turn.
+      await retryBusy(() => withTx(hub.db, () => {
+        const fresh = registry.fact('run', r.id) || r;
+        messaging.markDelivered(r.id, [m.id], { via: 'runner' });
+        messaging.ack(r.id, m.id, { reply: out.text || '(no answer)', fromName: fresh.name || fresh.role }, registry.directory());
+        save({ ...fresh, sessionId: out.sessionId || fresh.sessionId, state: 'idle', current: null, turns: (fresh.turns || 0) + 1, lastAt: Date.now(), costUsd: (fresh.costUsd || 0) + ((out.usage && out.usage.costUsd) || 0) });
+        registry.heartbeat(r.id, { event: 'stop', tool: d.id });
+      }, 'runner answer'), { delaysMs: retryMs, label: `runner answer for ${r.id}`, log });
+    } catch (e) {
+      if (abort.signal.aborted) return;
+      const failed = String(e && e.message ? e.message : e).slice(0, 500);
+      try {
+        const fresh = registry.fact('run', r.id) || r;
+        save({ ...fresh, state: 'error', current: null, lastError: failed, lastAt: Date.now() });
+      } catch (e2) { log(`runner ${r.id}: turn failed (${failed}) and recording it failed too: ${e2.message}`); }
+    } finally { clearInterval(keep); aborts.delete(r.id); }
+  }
+
+  const tick = guardTick('runner', () => {
+    for (const r of runs()) {
+      if (busy.has(r.id) || busy.size >= MAX_PARALLEL) continue;
+      const [m] = messaging.claim(r.id, { via: 'runner', limit: 1, leaseMs: LEASE_MS });
+      if (!m) continue;
+      if (isFyi(m) && m.type !== 'BRIEF') { messaging.ack(r.id, m.id, {}, registry.directory()); continue; }
+      if (m.attempts > MAX_ATTEMPTS) {
+        messaging.ack(r.id, m.id, { reply: `I could not run this after ${MAX_ATTEMPTS} tries. Last error: ${r.lastError || 'unknown'}` }, registry.directory());
+        continue;
+      }
+      busy.set(r.id, turn(r, m).catch((e) => log(`runner turn for ${r.id} failed: ${e.message}`)).finally(() => busy.delete(r.id)));
+    }
+  }, { now, log });
+
+  return {
+    start,
+    /** Stop a run: kill a turn in progress (its process) and take no more messages. */
+    stop(id) {
+      const r = registry.fact('run', id);
+      if (!r) return { error: 'no such run' };
+      const a = aborts.get(id);
+      if (a) a.abort();
+      save({ ...r, state: 'stopped', current: null });
+      return { ok: true, killed: !!a };
+    },
+    list() { return registry.facts('run').map(({ brief, ...r }) => ({ ...r, briefChars: brief ? brief.length : 0 })); },
+    drivers() { return [...drivers.values()].map((d) => ({ id: d.id, label: d.label, can: d.can })); },
+    tick,
+    begin() { if (!timer) { timer = setInterval(tick, TICK_MS); timer.unref(); } },
+    end() { if (timer) clearInterval(timer); timer = null; },
+    idle: () => Promise.all([...busy.values()]),
+  };
+}

package/src/lib/BaseCommand.js

@@ -1,37 +1,37 @@
 import { Command } from '@oclif/core';
 
-/**
- * BaseCommand — the pulse plugin's half of the machine-readable CLI contract (docs/PLAN.md M0), matching the host
- * CLI's BaseCommand so `agentpulse pulse <verb> --json` yields the SAME standard envelope as first-party commands:
- *
- *   success:  { tool:'agentpulse', command:'pulse status', version, ok:true,  result }
- *   error:    { tool:'agentpulse', command:'pulse status', version, ok:false, error:{ code, message } }
- *
- * Behavior note (deliberate, back-compat): pulse output is machine-oriented (work-lists with prompts + JSON
- * schemas an agent consumes), so the DEFAULT (no --json) still prints the raw engine result as pretty JSON —
- * exactly as before. `--json` layers the standard envelope on top. Both are JSON; --json is the stable contract.
- */
 export default class BaseCommand extends Command {
   static enableJsonFlag = true;
 
   toSuccessJson(result) {
-    const marked = result && typeof result === 'object' && result.__ap === true;
-    const ok = marked ? result.ok : true;
-    const payload = marked ? result.result : result;
-    return { tool: 'agentpulse', command: this.commandName(), version: this.config?.version, ok, result: payload };
+    return {
+      tool: 'agentpulse',
+      command: this.commandName(),
+      version: this.config?.version,
+      ok: true,
+      result,
+    };
   }
 
-  toErrorJson(err) {
+  toErrorJson(error) {
     return {
-      tool: 'agentpulse', command: this.commandName(), version: this.config?.version, ok: false,
-      error: { code: (err && err.code) || 'E_ERROR', message: (err && err.message) || String(err) },
+      tool: 'agentpulse',
+      command: this.commandName(),
+      version: this.config?.version,
+      ok: false,
+      error: {
+        code: error?.code || 'HUB_ERROR',
+        message: error?.message || String(error),
+      },
     };
   }
 
-  commandName() { return String(this.id || this.ctor?.id || '').replace(/:/g, ' '); }
-
-  fail(code, message, exit = 1) { process.exitCode = exit; this.error(message, { code, exit }); }
+  commandName() {
+    return String(this.id || this.ctor?.id || '').replace(/:/g, ' ');
+  }
 
-  /** A successful run that reports ok:false and exits non-zero, carrying its full payload (e.g. `verify` red). */
-  problem(payload, exit = 1) { process.exitCode = exit; return { __ap: true, ok: false, result: payload }; }
+  fail(code, message, exit = 1) {
+    process.exitCode = exit;
+    this.error(message, { code, exit });
+  }
 }

package/src/lib/agentSessions.js

@@ -0,0 +1,279 @@
+import path from 'node:path';
+import { HubError } from './errors.js';
+import { ensureOwnerOnlyDirectory, readOwnerOnlyJson, writeOwnerOnlyJson } from './storage.js';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PROVIDERS = new Set(['cursor', 'claude']);
+const BINDING_FIELDS = [
+  'agentSessionId',
+  'agentId',
+  'deliveryId',
+  'streamId',
+  'rootId',
+  'provider',
+];
+
+function invalid(message = 'Agent session binding is invalid') {
+  return new HubError('HUB_AGENT_SESSION_INVALID', message);
+}
+
+function bindingMismatch() {
+  return new HubError(
+    'HUB_AGENT_SESSION_BINDING_MISMATCH',
+    'Continuation does not exactly match its durable cloud and local session binding'
+  );
+}
+
+function sameFields(left, right, fields) {
+  return fields.every((field) => left?.[field] === right?.[field]);
+}
+
+function assertBinding(value) {
+  if (
+    !value ||
+    Object.keys(value).length !== BINDING_FIELDS.length ||
+    !BINDING_FIELDS.every((field) => Object.hasOwn(value, field)) ||
+    !UUID.test(String(value.agentSessionId || '')) ||
+    !UUID.test(String(value.agentId || '')) ||
+    !UUID.test(String(value.deliveryId || '')) ||
+    !UUID.test(String(value.streamId || '')) ||
+    typeof value.rootId !== 'string' ||
+    value.rootId.length < 1 ||
+    value.rootId.length > 80 ||
+    !PROVIDERS.has(value.provider)
+  ) {
+    throw invalid();
+  }
+  return value;
+}
+
+function assertLocalSession(value) {
+  if (
+    !value ||
+    !UUID.test(String(value.agentId || '')) ||
+    !UUID.test(String(value.deliveryId || '')) ||
+    !UUID.test(String(value.streamId || '')) ||
+    typeof value.rootId !== 'string' ||
+    value.rootId.length < 1 ||
+    value.rootId.length > 80 ||
+    !PROVIDERS.has(value.provider) ||
+    typeof value.providerSessionId !== 'string' ||
+    value.providerSessionId.length < 1 ||
+    value.providerSessionId.length > 180 ||
+    typeof value.model !== 'string' ||
+    value.model.length < 1 ||
+    value.model.length > 100 ||
+    !['read', 'write'].includes(value.mode) ||
+    !['architect', 'coder', 'reviewer', 'auditor'].includes(value.role) ||
+    !['active', 'stopped'].includes(value.state) ||
+    (value.worktreeId !== null &&
+      (typeof value.worktreeId !== 'string' ||
+        value.worktreeId.length < 1 ||
+        value.worktreeId.length > 180)) ||
+    (value.mode === 'write' && typeof value.worktreeId !== 'string') ||
+    (value.processIdentity !== undefined &&
+      value.processIdentity !== null &&
+      (typeof value.processIdentity !== 'object' ||
+        typeof value.processIdentity.processRef !== 'string' ||
+        !Number.isInteger(value.processIdentity.pid) ||
+        !Number.isInteger(value.processIdentity.pgid) ||
+        typeof value.processIdentity.bootId !== 'string' ||
+        typeof value.processIdentity.startToken !== 'string'))
+  ) {
+    throw invalid();
+  }
+}
+
+export class AgentSessionStore {
+  #queue = Promise.resolve();
+
+  static async open(directory) {
+    await ensureOwnerOnlyDirectory(directory);
+    const file = path.join(directory, 'agent-sessions.json');
+    const data = await readOwnerOnlyJson(file, {
+      schemaVersion: 2,
+      pendingStarts: {},
+      sessions: {},
+      startBindings: {},
+    });
+    if (
+      data.schemaVersion !== 2 ||
+      !data.pendingStarts ||
+      typeof data.pendingStarts !== 'object' ||
+      !data.sessions ||
+      typeof data.sessions !== 'object' ||
+      !data.startBindings ||
+      typeof data.startBindings !== 'object'
+    ) {
+      throw new HubError('HUB_AGENT_SESSION_STORE_INVALID', 'Agent session store is invalid');
+    }
+    if (
+      Object.keys(data.sessions).length > 1_000 ||
+      Object.keys(data.pendingStarts).length > 100 ||
+      Object.keys(data.startBindings).length > 1_000 ||
+      Buffer.byteLength(JSON.stringify(data), 'utf8') > 2 * 1024 * 1024
+    ) {
+      throw new HubError('HUB_AGENT_SESSION_STORE_INVALID', 'Agent session store exceeds safety bounds');
+    }
+    for (const [id, session] of Object.entries(data.sessions)) {
+      assertBinding({
+        agentSessionId: id,
+        agentId: session.agentId,
+        deliveryId: session.deliveryId,
+        streamId: session.streamId,
+        rootId: session.rootId,
+        provider: session.provider,
+      });
+      assertLocalSession(session);
+    }
+    for (const [jobId, session] of Object.entries(data.pendingStarts)) {
+      if (!UUID.test(jobId)) throw invalid();
+      assertLocalSession(session);
+    }
+    for (const [jobId, binding] of Object.entries(data.startBindings)) {
+      if (!UUID.test(jobId)) throw invalid();
+      assertBinding(binding);
+    }
+    return new AgentSessionStore(file, data);
+  }
+
+  constructor(file, data) {
+    this.file = file;
+    this.data = data;
+  }
+
+  get(id) {
+    const value = Object.hasOwn(this.data.sessions, id) ? this.data.sessions[id] : null;
+    return value ? structuredClone(value) : null;
+  }
+
+  list() {
+    return Object.entries(this.data.sessions).map(([id, value]) => ({
+      id,
+      ...structuredClone(value),
+    }));
+  }
+
+  async #mutate(operation) {
+    const pending = this.#queue.then(async () => {
+      const draft = structuredClone(this.data);
+      const result = operation(draft);
+      if (Buffer.byteLength(JSON.stringify(draft), 'utf8') > 2 * 1024 * 1024) {
+        throw new HubError('HUB_AGENT_SESSION_STORE_FULL', 'Agent session store exceeds safety bounds');
+      }
+      await writeOwnerOnlyJson(this.file, draft);
+      this.data = draft;
+      return structuredClone(result);
+    });
+    this.#queue = pending.catch(() => {});
+    return pending;
+  }
+
+  async recordPendingStart(jobId, value) {
+    if (!UUID.test(String(jobId || ''))) throw invalid('Start job id is invalid');
+    assertLocalSession(value);
+    return this.#mutate((draft) => {
+      const existing = draft.pendingStarts[jobId];
+      if (existing && JSON.stringify(existing) !== JSON.stringify(value)) throw bindingMismatch();
+      if (!existing && Object.keys(draft.pendingStarts).length >= 100) {
+        throw new HubError('HUB_AGENT_SESSION_STORE_FULL', 'Pending start store is full');
+      }
+      draft.pendingStarts[jobId] = structuredClone(value);
+      return value;
+    });
+  }
+
+  async applyStartAcknowledgement(jobId, acknowledgement) {
+    if (
+      !UUID.test(String(jobId || '')) ||
+      acknowledgement?.job?.id !== jobId ||
+      acknowledgement.job.type !== 'agent.start' ||
+      !['succeeded', 'failed', 'cancelled'].includes(acknowledgement.job.state)
+    ) {
+      throw invalid('Agent start acknowledgement is invalid');
+    }
+    return this.#mutate((draft) => {
+      const pending = draft.pendingStarts[jobId];
+      if (acknowledgement.job.state !== 'succeeded') {
+        if (acknowledgement.sessionBinding !== undefined) throw bindingMismatch();
+        delete draft.pendingStarts[jobId];
+        return null;
+      }
+      const binding = assertBinding(acknowledgement.sessionBinding);
+      const priorBinding = draft.startBindings[jobId];
+      if (priorBinding) {
+        if (!sameFields(priorBinding, binding, BINDING_FIELDS)) throw bindingMismatch();
+        const priorSession = draft.sessions[binding.agentSessionId];
+        if (!priorSession) throw bindingMismatch();
+        return priorSession;
+      }
+      if (!pending || !sameFields(pending, binding, BINDING_FIELDS.slice(1))) {
+        throw bindingMismatch();
+      }
+      const existing = draft.sessions[binding.agentSessionId];
+      const session = {
+        ...structuredClone(pending),
+        agentId: binding.agentId,
+        deliveryId: binding.deliveryId,
+        streamId: binding.streamId,
+        rootId: binding.rootId,
+        provider: binding.provider,
+      };
+      if (existing && JSON.stringify(existing) !== JSON.stringify(session)) throw bindingMismatch();
+      if (!existing && Object.keys(draft.sessions).length >= 1_000) {
+        throw new HubError('HUB_AGENT_SESSION_STORE_FULL', 'Agent session store is full');
+      }
+      draft.sessions[binding.agentSessionId] = session;
+      draft.startBindings[jobId] = structuredClone(binding);
+      delete draft.pendingStarts[jobId];
+      return session;
+    });
+  }
+
+  async rejectStartSettlement(jobId) {
+    if (!UUID.test(String(jobId || ''))) throw invalid('Start job id is invalid');
+    return this.#mutate((draft) => {
+      if (!Object.hasOwn(draft.pendingStarts, jobId)) return null;
+      delete draft.pendingStarts[jobId];
+      return null;
+    });
+  }
+
+  resolveContinuation(job) {
+    if (!['agent.turn', 'agent.stop'].includes(job?.type)) return null;
+    const binding = assertBinding(job.sessionBinding);
+    const session = this.get(binding.agentSessionId);
+    const expectedCapability = `agent.${binding.provider}.invoke`;
+    if (
+      !session ||
+      job.arguments?.agentSessionId !== binding.agentSessionId ||
+      job.arguments?.rootId !== binding.rootId ||
+      job.delivery_id !== binding.deliveryId ||
+      job.stream_id !== binding.streamId ||
+      job.root_id !== binding.rootId ||
+      job.capability !== expectedCapability ||
+      (session.state !== 'active' && !(job.type === 'agent.stop' && session.state === 'stopped')) ||
+      !sameFields(session, binding, BINDING_FIELDS.slice(1))
+    ) {
+      throw bindingMismatch();
+    }
+    return {
+      provider: binding.provider,
+      cloudSessionId: binding.agentSessionId,
+      session,
+    };
+  }
+
+  async put(id, value) {
+    if (!UUID.test(String(id || ''))) throw invalid();
+    assertLocalSession(value);
+    return this.#mutate((draft) => {
+      const existing = draft.sessions[id];
+      if (!existing || !sameFields(existing, value, BINDING_FIELDS.slice(1))) {
+        throw bindingMismatch();
+      }
+      draft.sessions[id] = structuredClone(value);
+      return value;
+    });
+  }
+}