@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.1.2

package/src/lib/backoff.js

@@ -0,0 +1,8 @@
+export function fullJitterDelay(
+  attempt,
+  { baseMs = 1_000, capMs = 60_000, random = Math.random } = {}
+) {
+  const exponent = Math.max(0, Math.min(30, Number(attempt) || 0));
+  const ceiling = Math.min(capMs, baseMs * 2 ** exponent);
+  return Math.floor(Math.max(0, Math.min(1, random())) * ceiling);
+}

package/src/lib/budgets.js

@@ -0,0 +1,85 @@
+import { randomUUID } from 'node:crypto';
+import { HubError } from './errors.js';
+
+function assertLimit(value, limit, code, label) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new HubError(code, `${label} usage must be a finite non-negative number`);
+  }
+  if (value > limit) {
+    throw new HubError(code, `${label} budget exceeded (${value} > ${limit})`);
+  }
+}
+
+export class BudgetGuard {
+  #active = new Map();
+
+  constructor({
+    maxTokens,
+    maxCostUsd,
+    maxWallMs,
+    maxOutputBytes,
+    maxConcurrency,
+    now = Date.now,
+  }) {
+    for (const [name, value] of Object.entries({
+      maxTokens,
+      maxCostUsd,
+      maxWallMs,
+      maxOutputBytes,
+      maxConcurrency,
+    })) {
+      if (!Number.isFinite(value) || value <= 0 || (name === 'maxConcurrency' && !Number.isInteger(value))) {
+        throw new HubError('HUB_BUDGET_INVALID', `${name} must be an explicit positive finite limit`);
+      }
+    }
+    this.limits = { maxTokens, maxCostUsd, maxWallMs, maxOutputBytes, maxConcurrency };
+    this.now = now;
+  }
+
+  acquire() {
+    assertLimit(
+      this.#active.size + 1,
+      this.limits.maxConcurrency,
+      'HUB_BUDGET_CONCURRENCY',
+      'Concurrency'
+    );
+    const startedAt = this.now();
+    if (!Number.isFinite(startedAt) || startedAt < 0) {
+      throw new HubError('HUB_BUDGET_TIME', 'Monotonic clock returned an invalid value');
+    }
+    const lease = { id: randomUUID(), startedAt };
+    this.#active.set(lease.id, { ...lease, tokens: 0, costUsd: 0, outputBytes: 0 });
+    return { ...lease };
+  }
+
+  assertWithin({ id, tokens, costUsd, outputBytes }) {
+    const lease = this.#active.get(id);
+    if (!lease) throw new HubError('HUB_BUDGET_LEASE_INVALID', 'Budget lease is not active');
+    assertLimit(tokens, this.limits.maxTokens, 'HUB_BUDGET_TOKENS', 'Token');
+    assertLimit(costUsd, this.limits.maxCostUsd, 'HUB_BUDGET_COST', 'Cost');
+    assertLimit(outputBytes, this.limits.maxOutputBytes, 'HUB_BUDGET_OUTPUT', 'Output');
+    assertLimit(this.now() - lease.startedAt, this.limits.maxWallMs, 'HUB_BUDGET_TIME', 'Wall time');
+  }
+
+  consume(lease, delta) {
+    const current = this.#active.get(lease.id);
+    if (!current) throw new HubError('HUB_BUDGET_LEASE_INVALID', 'Budget lease is not active');
+    const next = {
+      id: current.id,
+      tokens: current.tokens + delta.tokens,
+      costUsd: current.costUsd + delta.costUsd,
+      outputBytes: current.outputBytes + delta.outputBytes,
+    };
+    this.assertWithin(next);
+    Object.assign(current, next);
+    return { ...current };
+  }
+
+  release(lease) {
+    this.#active.delete(lease.id);
+  }
+
+  get active() {
+    return this.#active.size;
+  }
+}

package/src/lib/channelScanner.js

@@ -0,0 +1,99 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+// Ported from agents-hub lib/channels.mjs at 37a0b2f: the post header, role aliases, the header type and the walk that
+// dates headers (which carry a time but no date) backwards from the file's modified time.
+export const HEADER = /^## \[([A-Z][A-Z0-9 -]*?)\] (\d{1,2}):(\d{2})(?::(\d{2}))?(?: (IST|UTC|GMT))? ([^\n]*)$/;
+const ROLE_ALIASES = { 'PLATFORM-AUDITOR': 'PLATFORM AUDITOR', AUDITOR: 'PLATFORM AUDITOR' };
+export const normRole = (role) => {
+  const upper = String(role || '').toUpperCase().trim();
+  return ROLE_ALIASES[upper] || upper;
+};
+const DAY_S = 86400;
+const DAY_JUMP_S = 2 * 3600;
+const NAME = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Every task channel the local hub shows: <root>/<repo>/.agents/<task>/channel.md, roots in the hub's order. A
+ * `<repo>/<task>` present under two roots is the first root's (as the hub resolves it); the others are returned in
+ * `collisions`. Names outside the channel key charset are returned in `unnamed`.
+ */
+export async function channelFiles(roots) {
+  const files = [];
+  const collisions = [];
+  const unnamed = [];
+  const seen = new Map();
+  for (const root of roots) {
+    let repos = [];
+    try {
+      repos = (await readdir(root)).sort();
+    } catch {
+      continue;
+    }
+    for (const repo of repos) {
+      const dir = path.join(root, repo, '.agents');
+      let tasks = [];
+      try {
+        tasks = (await readdir(dir)).sort();
+      } catch {
+        continue;
+      }
+      for (const task of tasks) {
+        const file = path.join(dir, task, 'channel.md');
+        let info;
+        try {
+          info = await stat(file);
+        } catch {
+          continue;
+        }
+        if (!info.isFile()) continue;
+        const key = `${repo}/${task}`;
+        if (!NAME.test(repo) || !NAME.test(task)) {
+          unnamed.push({ key, file });
+          continue;
+        }
+        if (seen.has(key)) {
+          collisions.push({ key, file, kept: seen.get(key) });
+          continue;
+        }
+        seen.set(key, file);
+        files.push({ key, repo, task, file, mtimeMs: info.mtimeMs, size: info.size });
+      }
+    }
+  }
+  return { files, collisions, unnamed };
+}
+
+export const readChannel = (file) => readFile(file, 'utf8');
+
+/**
+ * The posts of a channel file as whole blocks: each header line and every line up to the next header, with no line or
+ * character cap (the hub's parsePosts caps a body; an import must not). Text before the first header is not a post.
+ * `at` is each header's time on the date the backwards walk gives it.
+ */
+export function splitPosts(text, mtimeMs, utcOffsetS = -new Date(mtimeMs).getTimezoneOffset() * 60) {
+  const lines = String(text).replace(/\r/g, '').split('\n');
+  const raw = [];
+  let current = null;
+  for (const line of lines) {
+    const match = line.match(HEADER);
+    if (match) {
+      const head = match[6].trim();
+      let sec = Number(match[2]) * 3600 + Number(match[3]) * 60 + Number(match[4] || 0) + (match[5] === 'UTC' || match[5] === 'GMT' ? utcOffsetS : 0);
+      sec -= Math.floor(sec / DAY_S) * DAY_S;
+      current = { role: normRole(match[1]), head, type: head.split(/ [—(-] | — /)[0].trim().slice(0, 40), sec, lines: [line] };
+      raw.push(current);
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  const mt = new Date(mtimeMs);
+  const day = new Date(mt.getFullYear(), mt.getMonth(), mt.getDate());
+  let later = mt.getHours() * 3600 + mt.getMinutes() * 60 + mt.getSeconds() + 600;
+  for (let k = raw.length - 1; k >= 0; k -= 1) {
+    if (raw[k].sec > later + DAY_JUMP_S) day.setDate(day.getDate() - 1);
+    later = raw[k].sec;
+    raw[k].at = day.getTime() + raw[k].sec * 1000;
+  }
+  return raw.map(({ role, head, type, at, lines: block }) => ({ role, head, type, at, text: block.join('\n').trimEnd() }));
+}

package/src/lib/cliDefaults.js

@@ -0,0 +1,20 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export async function readCliDefaults({ env = process.env, home = os.homedir() } = {}) {
+  const file = path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'agentpulse', 'config.json');
+  let config;
+  try {
+    config = JSON.parse(await readFile(file, 'utf8'));
+  } catch {
+    return {};
+  }
+  const aliases = Object.keys(config?.profiles || {});
+  const alias = config?.profiles?.[config.defaultProfile] ? config.defaultProfile : aliases.length === 1 ? aliases[0] : null;
+  const profile = alias ? config.profiles[alias] : null;
+  return {
+    platformUrl: profile?.baseUrl || profile?.url || null,
+    devOrgSlug: profile?.devOrgSlug || null,
+  };
+}

package/src/lib/clientInstaller.js

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto';
+import { chmod, copyFile, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { HubError } from './errors.js';
+
+const CLIENTS = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'clients');
+const MARKER = '/*PULSE_CLIENT_CONFIG*/ null';
+
+/**
+ * The agents-hub entry points every agent and hook already calls, with their git blob at the frozen 6b2fb0b. Cutover
+ * replaces each with the Pulse thin client, keeping the original beside it; rollback puts the original back.
+ */
+export const ENTRY_POINTS = Object.freeze([
+  { name: 'hub.mjs', client: 'hub.mjs', relative: 'hub.mjs', blob: 'f83f19a2bb6ed6236c48ed219e33a54998358731' },
+  { name: 'hook', client: 'hub-bridge.mjs', relative: path.join('hooks', 'hub-bridge.mjs'), blob: '3caacb1771e5efa0f354f9a0757c3c6f3561acae' },
+]);
+export const ORIGINAL_SUFFIX = '.pre-cutover';
+
+export const gitBlobSha = (bytes) => createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+
+/** A thin client with its configuration written in: `{ port, tokenFile, spoolDir, cliPath, offline }`. */
+export async function renderClient(client, config) {
+  const source = await readFile(path.join(CLIENTS, client), 'utf8');
+  if (source.split(MARKER).length !== 2) throw new HubError('HUB_CLIENT_TEMPLATE', `${client} has no configuration marker`);
+  return source.replace(MARKER, () => JSON.stringify(config));
+}
+
+export function clientConfig({ hubHome, port = 8890, offline = false }) {
+  return {
+    port,
+    tokenFile: path.join(hubHome, 'state', 'hub.token'),
+    spoolDir: path.join(hubHome, 'state', 'spool'),
+    cliPath: path.join(hubHome, 'hub.mjs'),
+    offline,
+  };
+}
+
+async function atomicWrite(file, text, mode) {
+  const temp = `${file}.pulse-${process.pid}.tmp`;
+  await writeFile(temp, text, { mode });
+  await chmod(temp, mode);
+  await rename(temp, file);
+}
+
+async function readOrNull(file) {
+  try {
+    return await readFile(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+/**
+ * Install the thin clients over the entry points, online or offline. The first install keeps each original as
+ * `<file>.pre-cutover` and refuses unless it is exactly the 6b2fb0b blob; a later call only switches the client.
+ */
+export async function installClients({ hubHome, port = 8890, offline = false }) {
+  const config = clientConfig({ hubHome, port, offline });
+  const installed = [];
+  for (const entry of ENTRY_POINTS) {
+    const file = path.join(hubHome, entry.relative);
+    const original = `${file}${ORIGINAL_SUFFIX}`;
+    if (!(await readOrNull(original))) {
+      const current = await readOrNull(file);
+      if (!current) throw new HubError('HUB_ENTRY_POINT_MISSING', `${file} is missing`);
+      if (gitBlobSha(current) !== entry.blob) {
+        throw new HubError('HUB_ENTRY_POINT_CHANGED', `${file} is not agents-hub 6b2fb0b; cutover will not replace it`, { details: { file, blob: gitBlobSha(current) } });
+      }
+      await copyFile(file, original);
+      await chmod(original, 0o444);
+    }
+    await atomicWrite(file, await renderClient(entry.client, config), 0o755);
+    installed.push({ name: entry.name, file, offline });
+  }
+  return installed;
+}
+
+/** Put the 6b2fb0b entry points back, byte for byte, and drop the kept copies. */
+export async function restoreClients({ hubHome }) {
+  const restored = [];
+  for (const entry of ENTRY_POINTS) {
+    const file = path.join(hubHome, entry.relative);
+    const original = `${file}${ORIGINAL_SUFFIX}`;
+    const kept = await readOrNull(original);
+    if (!kept) {
+      const current = await readOrNull(file);
+      if (current && gitBlobSha(current) === entry.blob) { restored.push({ name: entry.name, file, already: true }); continue; }
+      throw new HubError('HUB_ENTRY_POINT_LOST', `${original} is missing, and ${file} is not the original`);
+    }
+    if (gitBlobSha(kept) !== entry.blob) throw new HubError('HUB_ENTRY_POINT_CHANGED', `${original} is not agents-hub 6b2fb0b`);
+    await chmod(original, 0o644);
+    await rename(original, file);
+    restored.push({ name: entry.name, file });
+  }
+  return restored;
+}
+
+/** Which entry points are the thin client now, and whether it is offline. */
+export async function clientState({ hubHome }) {
+  const out = {};
+  for (const entry of ENTRY_POINTS) {
+    const current = await readOrNull(path.join(hubHome, entry.relative));
+    const text = current ? current.toString('utf8') : '';
+    out[entry.name] = !current ? 'missing'
+      : gitBlobSha(current) === entry.blob ? 'original'
+        : /"offline":true/.test(text) ? 'client-offline' : /"offline":false/.test(text) ? 'client-online' : 'changed';
+  }
+  return out;
+}

package/src/lib/cloudAuth.js

@@ -0,0 +1,189 @@
+import { HubError } from './errors.js';
+import { cleanOrigin, decodeJwtClaims, fetchJson } from './http.js';
+import { DEV_ORG_INGRESS_HEADER, OAUTH_CLIENT_ID } from './transportContract.js';
+
+const SKEW_MS = 60_000;
+const TOKEN_TIMEOUT_MS = 15_000;
+
+export function loginRequired(reason) {
+  return new HubError(
+    'HUB_LOGIN_REQUIRED',
+    `Pulse connector sign-in is missing or expired (${reason}). Run \`agentpulse pulse login\`, then \`agentpulse pulse start\`.`,
+  );
+}
+
+function refreshUnavailable(reason, cause) {
+  return new HubError(
+    'HUB_REFRESH_UNAVAILABLE',
+    `Could not refresh the Pulse sign-in (${reason}); the connector will retry and claims no work until it succeeds`,
+    cause ? { cause } : {},
+  );
+}
+
+function expiresSoon(expiresAt, now) {
+  const expiry = Date.parse(expiresAt || '');
+  return !Number.isFinite(expiry) || expiry - now() <= SKEW_MS;
+}
+
+export class CloudAuth {
+  constructor({ tokenStore, target, fetch = globalThis.fetch, now = Date.now }) {
+    this.tokenStore = tokenStore;
+    this.target = {
+      ...target,
+      platformUrl: cleanOrigin(target.platformUrl, 'Platform URL'),
+      instanceUrl: target.instanceUrl ? cleanOrigin(target.instanceUrl, 'Instance URL') : null,
+    };
+    this.fetch = fetch;
+    this.now = now;
+    this.devOrgSession = null;
+    this.platformSession = null;
+    this.forceRefresh = false;
+  }
+
+  get instanceUrl() {
+    return this.target.devOrg ? this.target.instanceUrl : this.target.platformUrl;
+  }
+
+  invalidate() {
+    this.devOrgSession = null;
+    this.platformSession = null;
+    if (!this.target.devOrg) this.forceRefresh = true;
+  }
+
+  async #refresh(session) {
+    if (!session.refreshToken) throw loginRequired('access token expired and no refresh token is stored');
+    let refreshed;
+    try {
+      refreshed = await fetchJson({
+        fetch: this.fetch,
+        url: `${this.target.platformUrl}/api/oauth/token`,
+        body: { grant_type: 'refresh_token', client_id: OAUTH_CLIENT_ID, refresh_token: session.refreshToken },
+        timeoutMs: TOKEN_TIMEOUT_MS,
+      });
+    } catch (error) {
+      throw refreshUnavailable('the platform did not answer', error);
+    }
+    if (refreshed.status >= 500 || refreshed.status === 429) {
+      throw refreshUnavailable(`the platform answered HTTP ${refreshed.status}`);
+    }
+    if (refreshed.body?.error === 'invalid_grant') {
+      throw loginRequired('the platform rejected or revoked the refresh token (invalid_grant)');
+    }
+    const claims = decodeJwtClaims(refreshed.body?.access_token);
+    if (
+      !refreshed.ok ||
+      claims?.type !== 'user_delegated' ||
+      claims.sub !== session.userId ||
+      claims.team_id !== session.teamId
+    ) {
+      throw loginRequired('token refresh did not return this user\'s delegated token');
+    }
+    const expiresIn = Number(refreshed.body.expires_in);
+    const next = {
+      ...session,
+      accessToken: refreshed.body.access_token,
+      refreshToken: typeof refreshed.body.refresh_token === 'string' ? refreshed.body.refresh_token : session.refreshToken,
+      expiresAt: new Date(this.now() + (Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : 3600) * 1000).toISOString(),
+    };
+    await this.tokenStore.save(next);
+    return next;
+  }
+
+  async #storedSession() {
+    const session = await this.tokenStore.load();
+    if (!session?.accessToken) throw loginRequired('no stored sign-in');
+    if (
+      session.platformUrl !== this.target.platformUrl ||
+      session.userId !== this.target.userId ||
+      session.teamId !== this.target.teamId
+    ) {
+      throw loginRequired('the stored sign-in belongs to a different platform, team or user');
+    }
+    return session;
+  }
+
+  // The stored session is in the OS secret store (a Keychain read is 0.5-2 s), so it is read once and kept until 60 s
+  // before expiry or until invalidate().
+  async #platformSession() {
+    if (!this.forceRefresh && this.platformSession && !expiresSoon(this.platformSession.expiresAt, this.now)) {
+      return this.platformSession;
+    }
+    this.platformSession = await this.#loadPlatformSession();
+    return this.platformSession;
+  }
+
+  async #loadPlatformSession() {
+    const session = await this.#storedSession();
+    if (!this.forceRefresh && !expiresSoon(session.expiresAt, this.now)) return session;
+    const rejectedAccessToken = this.forceRefresh ? session.accessToken : null;
+    const current = await this.tokenStore.withRefreshLock(async () => {
+      const latest = await this.#storedSession();
+      const refreshedElsewhere = rejectedAccessToken && latest.accessToken !== rejectedAccessToken;
+      if (refreshedElsewhere || (!rejectedAccessToken && !expiresSoon(latest.expiresAt, this.now))) return latest;
+      return this.#refresh(latest);
+    });
+    this.forceRefresh = false;
+    return current;
+  }
+
+  async #mintDevOrgSession(platformSession) {
+    let minted;
+    try {
+      minted = await fetchJson({
+        fetch: this.fetch,
+        url: `${this.target.platformUrl}/api/team/dev-orgs/${encodeURIComponent(this.target.devOrg.id)}/cli-token`,
+        headers: { authorization: `Bearer ${platformSession.accessToken}` },
+        body: {},
+        timeoutMs: TOKEN_TIMEOUT_MS,
+      });
+    } catch (error) {
+      throw new HubError('HUB_TARGET_UNAVAILABLE', 'Could not reach the platform to connect to the dev-org', { cause: error });
+    }
+    if ([401, 403].includes(minted.status) || minted.body?.code === 'NO_USER_IDENTITY') {
+      throw loginRequired(`the platform refused the dev-org connection (HTTP ${minted.status})`);
+    }
+    if (!minted.ok) {
+      throw new HubError(
+        'HUB_TARGET_UNAVAILABLE',
+        `Dev-org ${this.target.devOrg.slug} is not reachable (HTTP ${minted.status}${minted.body?.code ? ` ${minted.body.code}` : ''})`,
+      );
+    }
+    const claims = decodeJwtClaims(minted.body.token);
+    if (claims?.userId !== this.target.userId || claims?.teamId !== this.target.teamId) {
+      throw loginRequired('the dev-org token was minted for a different user');
+    }
+    const instanceUrl = cleanOrigin(minted.body.instanceUrl, 'Dev-org instance URL');
+    if (this.target.instanceUrl && instanceUrl !== this.target.instanceUrl) {
+      throw new HubError(
+        'HUB_TARGET_CHANGED',
+        `Dev-org ${this.target.devOrg.slug} moved to a new address; pair this machine again`,
+      );
+    }
+    this.target.instanceUrl = instanceUrl;
+    return {
+      token: minted.body.token,
+      identityToken: typeof minted.body.identityToken === 'string' ? minted.body.identityToken : null,
+      expiresAt: minted.body.expiresAt,
+    };
+  }
+
+  /** The credentials held in memory now, so the mirror can redact them by identity; it never reads the secret store. */
+  heldSecrets() {
+    return [this.platformSession?.accessToken, this.platformSession?.refreshToken, this.devOrgSession?.token, this.devOrgSession?.identityToken]
+      .filter((value) => typeof value === 'string' && value.length >= 16);
+  }
+
+  async credentials() {
+    const platformSession = await this.#platformSession();
+    if (!this.target.devOrg) return { authorization: `Bearer ${platformSession.accessToken}` };
+    if (!this.devOrgSession || expiresSoon(this.devOrgSession.expiresAt, this.now)) {
+      this.devOrgSession = await this.#mintDevOrgSession(platformSession);
+    }
+    return {
+      authorization: `Bearer ${this.devOrgSession.token}`,
+      ...(this.devOrgSession.identityToken
+        ? { [DEV_ORG_INGRESS_HEADER]: `Bearer ${this.devOrgSession.identityToken}` }
+        : {}),
+    };
+  }
+}