@agentpulselabs/cli-plugin-pulse 0.1.0 → 1.0.0

package/src/lib/localHub.js

@@ -0,0 +1,217 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { HubError } from './errors.js';
+
+const DEFAULT_PORT = 8890;
+const HUB_PLIST = 'com.agentpulse.agents-hub.plist';
+const TOKEN = /^[a-f0-9]{32,}$/i;
+const QUERY_KEYS = Object.freeze({
+  '/api/deliveries': [],
+  '/api/graph': ['hours'],
+  '/api/chat/channels': [],
+  '/api/chat/messages': ['ch'],
+  '/api/inbox': ['since'],
+  '/api/task/brief': ['key'],
+  '/api/stream': [],
+});
+
+export const LOCAL_HUB_ENDPOINTS = Object.freeze(Object.keys(QUERY_KEYS));
+
+function notFound(message) {
+  return new HubError('HUB_LOCAL_HUB_NOT_FOUND', message);
+}
+
+function validPort(port) {
+  return Number.isInteger(port) && port > 0 && port < 65536;
+}
+
+function unxml(value) {
+  return value
+    .replaceAll('&apos;', "'")
+    .replaceAll('&quot;', '"')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&amp;', '&');
+}
+
+export async function discoverLocalHub({
+  config = {},
+  home = os.homedir(),
+  platform = process.platform,
+  readText = (file) => readFile(file, 'utf8'),
+} = {}) {
+  const configured = config?.mirror?.hub;
+  if (configured?.dir) {
+    const port = configured.port === undefined ? DEFAULT_PORT : configured.port;
+    if (!path.isAbsolute(configured.dir) || !validPort(port)) {
+      throw notFound('mirror.hub in the daemon config needs an absolute dir and a valid port');
+    }
+    return { dir: configured.dir, port };
+  }
+  if (platform !== 'darwin') {
+    throw notFound('Set mirror.hub.dir (and mirror.hub.port) in the daemon config to locate the local Agent Hub');
+  }
+  let plist;
+  try {
+    plist = await readText(path.join(home, 'Library', 'LaunchAgents', HUB_PLIST));
+  } catch {
+    throw notFound(`The local Agent Hub service (${HUB_PLIST}) is not installed`);
+  }
+  const array = plist.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/)?.[1] || '';
+  const argv = [...array.matchAll(/<string>([^<]*)<\/string>/g)].map((match) => unxml(match[1]));
+  const script = argv.find((arg) => path.isAbsolute(arg) && path.basename(arg) === 'hub.mjs');
+  if (!script) throw notFound(`${HUB_PLIST} does not start hub.mjs`);
+  const portIndex = argv.indexOf('--port');
+  const port = portIndex === -1 ? DEFAULT_PORT : Number(argv[portIndex + 1]);
+  if (!validPort(port)) throw notFound(`${HUB_PLIST} has an invalid --port`);
+  return { dir: path.dirname(script), port };
+}
+
+function parseEvents(buffer, onChange) {
+  const blocks = buffer.split(/\r?\n\r?\n/);
+  const rest = blocks.pop();
+  for (const block of blocks) {
+    let event = 'message';
+    const data = [];
+    for (const line of block.split(/\r?\n/)) {
+      if (line.startsWith('event:')) event = line.slice(6).trim();
+      else if (line.startsWith('data:')) data.push(line.slice(5).trimStart());
+    }
+    if (event !== 'change' || data.length === 0) continue;
+    try {
+      const kinds = JSON.parse(data.join('\n')).kinds;
+      if (Array.isArray(kinds)) onChange(kinds.filter((kind) => typeof kind === 'string'));
+    } catch {
+      // A malformed event is ignored; the periodic reconcile still catches the change.
+    }
+  }
+  return rest;
+}
+
+export class LocalHubReader {
+  constructor({
+    dir, port, fetch = globalThis.fetch, readText = (file) => readFile(file, 'utf8'), timeoutMs = 30_000, maxBytes = 32 * 1024 * 1024,
+    onRead = () => {},
+  }) {
+    if (!validPort(port)) throw notFound('Invalid local Agent Hub port');
+    this.onRead = onRead;
+    this.dir = dir;
+    this.origin = `http://127.0.0.1:${port}`;
+    this.fetch = fetch;
+    this.readText = readText;
+    this.timeoutMs = timeoutMs;
+    this.maxBytes = maxBytes;
+    this.graphReadsInFlight = 0;
+    this.lastGraphReadAt = -Infinity;
+  }
+
+  /** The hub writes hub.db on every graph read, so the change feed echoes each one; these say when ours ran. */
+  graphReadRecently(withinMs, now = Date.now()) {
+    return this.graphReadsInFlight > 0 || now - this.lastGraphReadAt < withinMs;
+  }
+
+  async get(pathname, params = {}) {
+    if (pathname !== '/api/graph') return this.#get(pathname, params);
+    this.graphReadsInFlight += 1;
+    try {
+      return await this.#get(pathname, params);
+    } finally {
+      this.graphReadsInFlight -= 1;
+      this.lastGraphReadAt = Date.now();
+    }
+  }
+
+  async tokenValue() {
+    let token;
+    try {
+      token = (await this.readText(path.join(this.dir, 'state', 'hub.token'))).trim();
+    } catch {
+      token = '';
+    }
+    if (!TOKEN.test(token)) {
+      throw new HubError('HUB_LOCAL_HUB_TOKEN_MISSING', 'The local Agent Hub token (state/hub.token) is missing or malformed');
+    }
+    return token;
+  }
+
+  async #headers() {
+    return { authorization: `Bearer ${await this.tokenValue()}`, accept: 'application/json' };
+  }
+
+  #url(pathname, params) {
+    if (!Object.hasOwn(QUERY_KEYS, pathname)) {
+      throw new HubError('HUB_LOCAL_HUB_ENDPOINT_DENIED', `Local Agent Hub endpoint is not allowed: ${pathname}`);
+    }
+    const url = new URL(pathname, this.origin);
+    for (const [key, value] of Object.entries(params)) {
+      if (!QUERY_KEYS[pathname].includes(key)) {
+        throw new HubError('HUB_LOCAL_HUB_ENDPOINT_DENIED', `Query parameter ${key} is not allowed on ${pathname}`);
+      }
+      url.searchParams.set(key, String(value));
+    }
+    return url;
+  }
+
+  async #get(pathname, params) {
+    const url = this.#url(pathname, params);
+    this.onRead(pathname);
+    const response = await this.fetch(url, {
+      method: 'GET',
+      headers: await this.#headers(),
+      redirect: 'error',
+      signal: AbortSignal.timeout(this.timeoutMs),
+    });
+    if (!response.ok) {
+      throw new HubError(`HUB_LOCAL_HUB_HTTP_${response.status}`, `Local Agent Hub returned ${response.status} for ${pathname}`);
+    }
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > this.maxBytes) {
+      throw new HubError('HUB_LOCAL_HUB_RESPONSE_TOO_LARGE', `Local Agent Hub response for ${pathname} is too large`);
+    }
+    const text = await response.text();
+    if (Buffer.byteLength(text, 'utf8') > this.maxBytes) {
+      throw new HubError('HUB_LOCAL_HUB_RESPONSE_TOO_LARGE', `Local Agent Hub response for ${pathname} is too large`);
+    }
+    return JSON.parse(text);
+  }
+
+  async subscribe({ onChange, onOpen = () => {}, signal, idleMs = 75_000 } = {}) {
+    const idle = new AbortController();
+    const forward = () => idle.abort(signal.reason);
+    if (signal?.aborted) forward();
+    signal?.addEventListener('abort', forward, { once: true });
+    let timer = null;
+    const arm = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => idle.abort(new HubError('HUB_LOCAL_HUB_STREAM_IDLE', 'The local Agent Hub stream went silent')), idleMs);
+      timer.unref?.();
+    };
+    arm();
+    try {
+      const response = await this.fetch(this.#url('/api/stream', {}), {
+        method: 'GET',
+        headers: { ...(await this.#headers()), accept: 'text/event-stream' },
+        redirect: 'error',
+        signal: idle.signal,
+      });
+      if (!response.ok || !response.body) {
+        throw new HubError(`HUB_LOCAL_HUB_HTTP_${response.status}`, `Local Agent Hub stream returned ${response.status}`);
+      }
+      onOpen();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      for await (const chunk of response.body) {
+        arm();
+        buffer = parseEvents(buffer + decoder.decode(chunk, { stream: true }), onChange);
+        if (buffer.length > 1024 * 1024) buffer = '';
+      }
+    } catch (error) {
+      if (idle.signal.aborted && !signal?.aborted) throw idle.signal.reason;
+      throw error;
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', forward);
+    }
+  }
+}

package/src/lib/localHubWriter.js

@@ -0,0 +1,69 @@
+import { HubError } from './errors.js';
+import { LocalHubReader } from './localHub.js';
+
+/** The only local hub writes a Pulse action may make. No /bus/publish: a bus reply goes through /bus/ack. */
+export const LOCAL_HUB_WRITE_PATHS = Object.freeze(['/api/chat/post', '/api/message', '/api/decision', '/api/accept', '/api/status', '/bus/ack']);
+const MAX_RESPONSE_BYTES = 64 * 1024;
+// Refused before any byte reached the hub: the write certainly did not happen.
+const NOT_CONNECTED = new Set(['ECONNREFUSED', 'EHOSTUNREACH', 'ENETUNREACH', 'ENOTFOUND']);
+
+const unreachable = (message) => new HubError('hub_unreachable', message);
+
+/**
+ * POSTs one Pulse action to the local Agent Hub on 127.0.0.1 with the hub token, always as the principal `user`: the
+ * person who paired this machine, never an agent.
+ */
+export class LocalHubWriter {
+  constructor({ dir, port, fetch = globalThis.fetch, readText, timeoutMs = 10_000, log = () => {} }) {
+    this.log = log;
+    this.reader = new LocalHubReader({ dir, port, fetch, ...(readText ? { readText } : {}) });
+    this.origin = this.reader.origin;
+    this.fetch = fetch;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async post(pathname, body) {
+    if (!LOCAL_HUB_WRITE_PATHS.includes(pathname)) {
+      throw new HubError('HUB_LOCAL_HUB_ENDPOINT_DENIED', `Local Agent Hub write is not allowed: ${pathname}`);
+    }
+    let token;
+    try {
+      token = await this.reader.tokenValue();
+    } catch (error) {
+      throw unreachable(error.message);
+    }
+    let response;
+    try {
+      response = await this.fetch(new URL(pathname, this.origin), {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${token}`,
+          'x-hub-as': 'user',
+          'content-type': 'application/json',
+          accept: 'application/json',
+        },
+        body: JSON.stringify(body),
+        redirect: 'error',
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (error) {
+      const code = error?.cause?.code || error?.code;
+      this.log('hub_response', { path: pathname, error: error?.name === 'TimeoutError' ? 'timeout' : code || 'connection_lost' });
+      if (NOT_CONNECTED.has(code)) throw unreachable(`The local Agent Hub is not running on ${this.origin}`);
+      throw new HubError('hub_write_unconfirmed', `The local Agent Hub did not answer (${error?.name === 'TimeoutError' ? 'timed out' : code || 'connection lost'}); the write may or may not have landed`);
+    }
+    this.log('hub_response', { path: pathname, status: response.status });
+    const text = await response.text().catch(() => '');
+    let parsed = {};
+    if (Buffer.byteLength(text, 'utf8') <= MAX_RESPONSE_BYTES) {
+      try { parsed = JSON.parse(text || '{}'); } catch { parsed = {}; }
+    }
+    const reason = typeof parsed.error === 'string' ? parsed.error.slice(0, 200) : `HTTP ${response.status}`;
+    // A 5xx can follow a write the hub already appended, so only a 4xx proves nothing landed.
+    if (response.status >= 500) {
+      throw new HubError('hub_write_unconfirmed', `The local Agent Hub failed while handling it (${reason}); the write may or may not have landed`);
+    }
+    if (!response.ok) throw new HubError('hub_refused', `The hub refused it: ${reason}`);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  }
+}