@agentpulselabs/cli-plugin-pulse 0.1.0 → 1.0.0

package/src/lib/transport.js

@@ -0,0 +1,286 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { fullJitterDelay } from './backoff.js';
+import { loginRequired } from './cloudAuth.js';
+import { HubError } from './errors.js';
+import { cleanOrigin, fetchJson } from './http.js';
+import { CONTRACT_HEADER, CONTRACT_VERSION, MIRROR_LIMITS, MIRROR_PATH, parseAccepts } from './mirrorContract.js';
+import { PriorityLane } from './priorityLane.js';
+import {
+  CONNECTOR_API_BASE,
+  CONNECTOR_RESPONSE_MAX_BYTES,
+  MACHINE_ID_HEADER,
+  POLICY_VERSION_HEADER,
+  SESSION_ID_HEADER,
+} from './transportContract.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 CLAIMED_INTEGERS = ['attempt_no', 'fence_token', 'policy_version', 'attemptNo', 'fenceToken', 'policyVersion'];
+const REQUEST_TIMEOUT_MS = 15_000;
+const MIRROR_TIMEOUT_MS = 30_000;
+// The platform's JSON parser inflates gzip bodies; the contract's bodyBytes limit still applies to the JSON.
+const MIRROR_GZIP_ABOVE_BYTES = 8 * 1024;
+// The cloud holds a claim up to waitSeconds before answering; the request waits that long plus this much.
+const CLAIM_TIMEOUT_MARGIN_MS = 10_000;
+
+/**
+ * A claimed job with its integers as numbers. The cloud returns agent_hub_jobs rows as node-pg serialises them, so the
+ * bigint fence_token arrives as a decimal string; anything that is not a plain integer stays as sent for the ledger to
+ * refuse.
+ */
+function claimedJob(job) {
+  if (!job || typeof job !== 'object') return job;
+  const out = { ...job };
+  for (const key of CLAIMED_INTEGERS) {
+    if (typeof out[key] === 'string' && /^[0-9]{1,15}$/.test(out[key])) out[key] = Number(out[key]);
+  }
+  return out;
+}
+
+const SERVER_TIMING_NAMES = { lock: 'lockMs', db: 'dbMs', total: 'totalMs' };
+
+/** `lock;dur=2.5, db;dur=31, total;dur=48` as { lockMs, dbMs, totalMs }; metrics without a duration are left out. */
+export function parseServerTiming(header) {
+  const out = {};
+  for (const metric of String(header || '').split(',')) {
+    const [name, ...params] = metric.trim().split(';');
+    const dur = params.map((param) => param.trim().match(/^dur=([0-9.]+)$/)).find(Boolean);
+    if (SERVER_TIMING_NAMES[name] && dur) out[SERVER_TIMING_NAMES[name]] = Number(dur[1]);
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+/** The range this connector's contract version is outside of, as a contract_unsupported error. */
+export function contractUnsupported(accepts, message) {
+  return new HubError('contract_unsupported', message || `Pulse accepts ${accepts}; this connector speaks mirror/${CONTRACT_VERSION}`, {
+    details: { status: 409, accepts },
+  });
+}
+
+function requestBytes(payload, maxBodyBytes) {
+  if (Buffer.byteLength(JSON.stringify(payload), 'utf8') > maxBodyBytes) {
+    throw new HubError('HUB_TRANSPORT_PAYLOAD_TOO_LARGE', `Request exceeds ${maxBodyBytes} bytes`);
+  }
+}
+
+export class ConnectorTransport {
+  constructor({
+    baseUrl,
+    machine,
+    auth,
+    fetch: fetchImplementation = globalThis.fetch,
+    random = Math.random,
+    delay = sleep,
+    maxAttempts = 8,
+    onAttempt = () => {},
+    now = Date.now,
+    laneMaxWaitMs,
+  }) {
+    this.onAttempt = onAttempt;
+    this.now = now;
+    this.baseUrl = cleanOrigin(baseUrl, 'Connector base URL');
+    this.machine = machine;
+    this.auth = auth;
+    this.fetch = fetchImplementation;
+    this.random = random;
+    this.delay = delay;
+    this.maxAttempts = maxAttempts;
+    this.pollOutstanding = false;
+    // The cloud's handshake range from the last answer that named one (null until then, and from a v1 cloud).
+    this.contractAccepts = null;
+    this.lane = new PriorityLane({ now, ...(laneMaxWaitMs !== undefined ? { maxWaitMs: laneMaxWaitMs } : {}) });
+  }
+
+  #identityHeaders() {
+    return {
+      [MACHINE_ID_HEADER]: this.machine.machineId,
+      [SESSION_ID_HEADER]: this.machine.sessionId,
+      [POLICY_VERSION_HEADER]: String(this.machine.policyVersion),
+      [CONTRACT_HEADER]: `mirror/${CONTRACT_VERSION}`,
+    };
+  }
+
+  /**
+   * onAttempt({ path, phase }) marks each credentials read, request and backoff, so a watchdog can see retries progress.
+   * trace, when given, gathers where the time went: attempts and their statuses ('error' for a failed fetch), backoff,
+   * reading credentials (a token refresh or dev-org mint), the JSON and wire bytes, and the cloud's Server-Timing of
+   * the attempt that answered.
+   */
+  async #request(path, payload, { retry = false, maxBodyBytes, timeoutMs = REQUEST_TIMEOUT_MS, gzipAboveBytes, trace = {} }) {
+    requestBytes(payload, maxBodyBytes);
+    trace.attempts = 0;
+    trace.statuses = [];
+    trace.backoffMs = 0;
+    trace.credentialsMs = 0;
+    const backoff = async (ms) => {
+      this.onAttempt({ path, phase: 'backoff' });
+      const started = this.now();
+      await this.delay(ms);
+      trace.backoffMs += this.now() - started;
+    };
+    let lastError;
+    let reauthenticated = false;
+    for (let attempt = 0; attempt < this.maxAttempts; attempt += 1) {
+      this.onAttempt({ path, phase: 'credentials' });
+      const credentialsFrom = this.now();
+      const credentials = await this.auth.credentials();
+      trace.credentialsMs += this.now() - credentialsFrom;
+      this.onAttempt({ path, phase: 'request' });
+      trace.attempts += 1;
+      let response;
+      try {
+        response = await fetchJson({
+          fetch: this.fetch,
+          url: `${this.baseUrl}${path}`,
+          headers: { ...credentials, ...this.#identityHeaders() },
+          body: payload,
+          maxBytes: CONNECTOR_RESPONSE_MAX_BYTES,
+          timeoutMs,
+          gzipAboveBytes,
+        });
+      } catch (error) {
+        trace.statuses.push('error');
+        if (error instanceof HubError || !retry) throw error;
+        lastError = error;
+        if (attempt + 1 >= this.maxAttempts) break;
+        await backoff(fullJitterDelay(attempt, { random: this.random }));
+        continue;
+      }
+      trace.statuses.push(response.status);
+      trace.bytes = response.bytes;
+      trace.sentBytes = response.sentBytes;
+      trace.server = parseServerTiming(response.serverTiming);
+      const accepts = response.contractAccepts || response.body.contractAccepts || response.body.accepts;
+      if (parseAccepts(accepts)) this.contractAccepts = accepts;
+      if (response.ok) return response.body;
+      if (response.status === 409 && response.body.error === 'contract_unsupported') {
+        throw contractUnsupported(parseAccepts(accepts) ? accepts : null, response.body.message);
+      }
+      if (response.status === 401) {
+        if (reauthenticated) throw loginRequired('the cloud refused the refreshed credentials');
+        reauthenticated = true;
+        this.auth.invalidate();
+        continue;
+      }
+      if (response.status === 403 && response.body.error === 'FORBIDDEN') {
+        throw new HubError('HUB_SCOPE_DENIED', 'Your Pulse tier does not grant the connector scopes for this operation', {
+          details: { status: 403 },
+        });
+      }
+      if (retry && (response.status === 429 || response.status >= 500)) {
+        const wait = Number.isFinite(response.retryAfter)
+          ? Math.max(0, Math.min(60_000, response.retryAfter * 1_000))
+          : fullJitterDelay(attempt, { random: this.random });
+        await backoff(wait);
+        continue;
+      }
+      throw new HubError(
+        response.body.error || `HTTP_${response.status}`,
+        response.body.message || `Connector request failed with ${response.status}`,
+        { details: { status: response.status } },
+      );
+    }
+    throw new HubError('HUB_TRANSPORT_UNAVAILABLE', 'Connector transport unavailable', { cause: lastError });
+  }
+
+  reconnect(payload) {
+    if (Array.isArray(payload.activeAttempts) && payload.activeAttempts.length > 100) {
+      throw new HubError('HUB_TRANSPORT_PAYLOAD_TOO_LARGE', 'Reconnect exceeds 100 active attempts');
+    }
+    return this.lane.priority(async (trace) => {
+      const opened = await this.#request(`${CONNECTOR_API_BASE}/session`, payload, { retry: true, maxBodyBytes: 32 * 1024, trace });
+      const range = parseAccepts(this.contractAccepts);
+      if (range && (CONTRACT_VERSION < range.min || CONTRACT_VERSION > range.max)) throw contractUnsupported(this.contractAccepts);
+      return opened;
+    }, { path: '/session' });
+  }
+
+  heartbeat(payload) {
+    if (Array.isArray(payload.activeAttempts) && payload.activeAttempts.length > 100) {
+      throw new HubError('HUB_TRANSPORT_PAYLOAD_TOO_LARGE', 'Heartbeat exceeds 100 active attempts');
+    }
+    return this.lane.priority((trace) => this.#request(`${CONNECTOR_API_BASE}/heartbeat`, payload, { retry: true, maxBodyBytes: 64 * 1024, trace }), { path: '/heartbeat' });
+  }
+
+  async poll(payload) {
+    if (this.pollOutstanding) {
+      throw new HubError('HUB_POLL_ALREADY_OUTSTANDING', 'Only one claim poll may be outstanding');
+    }
+    this.pollOutstanding = true;
+    try {
+      const claimed = await this.#request(`${CONNECTOR_API_BASE}/jobs/claim`, payload, {
+        retry: true,
+        maxBodyBytes: 16 * 1024,
+        timeoutMs: (Number(payload?.waitSeconds) || 0) * 1_000 + CLAIM_TIMEOUT_MARGIN_MS,
+      });
+      return Array.isArray(claimed?.jobs) ? { ...claimed, jobs: claimed.jobs.map(claimedJob) } : claimed;
+    } finally {
+      this.pollOutstanding = false;
+    }
+  }
+
+  acknowledge(jobId, payload) {
+    if (!UUID.test(jobId)) throw new HubError('HUB_JOB_ID_INVALID', 'jobId must be a UUID');
+    return this.lane.priority((trace) => this.#request(`${CONNECTOR_API_BASE}/jobs/${encodeURIComponent(jobId)}/ack`, payload, {
+      maxBodyBytes: 64 * 1024,
+      trace,
+    }), { path: '/jobs/:id/ack' });
+  }
+
+  renew(jobId, payload) {
+    if (!UUID.test(jobId)) throw new HubError('HUB_JOB_ID_INVALID', 'jobId must be a UUID');
+    return this.lane.priority((trace) => this.#request(`${CONNECTOR_API_BASE}/jobs/${encodeURIComponent(jobId)}/renew`, payload, {
+      retry: true,
+      maxBodyBytes: 8 * 1024,
+      trace,
+    }), { path: '/jobs/:id/renew' });
+  }
+
+  uploadEvents(payload) {
+    if (!Array.isArray(payload.events) || payload.events.length < 1 || payload.events.length > 100) {
+      throw new HubError('HUB_EVENT_BATCH_INVALID', 'Event batch must contain 1 to 100 events');
+    }
+    for (const event of payload.events) {
+      if (Buffer.byteLength(JSON.stringify(event), 'utf8') > 32 * 1024) {
+        throw new HubError('HUB_EVENT_TOO_LARGE', 'Event exceeds 32 KiB');
+      }
+    }
+    return this.lane.priority((trace) => this.#request(`${CONNECTOR_API_BASE}/events`, payload, {
+      retry: true,
+      maxBodyBytes: CONNECTOR_RESPONSE_MAX_BYTES,
+      trace,
+    }), { path: '/events' });
+  }
+
+  /** The heartbeat, session, renew, ack and events calls in flight at any time since `since`, for a pass record. */
+  priorityCalls({ since } = {}) {
+    return this.lane.calls({ since });
+  }
+
+  /**
+   * trace, when given, also gets laneWaitMs (behind priority calls, 1 s at most), laneCapped, heldBy (those calls) and
+   * ms, the whole call.
+   */
+  mirror(payload, { trace = {} } = {}) {
+    const items = payload.items;
+    if (!Array.isArray(items) || items.length > MIRROR_LIMITS.maxItems || (items.length === 0 && payload.reset !== true)) {
+      throw new HubError('HUB_MIRROR_BATCH_INVALID', `Mirror batch must contain 1 to ${MIRROR_LIMITS.maxItems} items, or reset`);
+    }
+    const queuedAt = this.now();
+    return this.lane.background(() => this.#request(MIRROR_PATH, payload, {
+        retry: true,
+        maxBodyBytes: MIRROR_LIMITS.bodyBytes,
+        timeoutMs: MIRROR_TIMEOUT_MS,
+        gzipAboveBytes: MIRROR_GZIP_ABOVE_BYTES,
+        trace,
+      }), { trace }).finally(() => {
+      trace.ms = this.now() - queuedAt;
+    }).catch((error) => {
+      if (error.details?.status !== 403 || String(error.code).startsWith('machine_')) throw error;
+      throw new HubError('HUB_MIRROR_SCOPE_MISSING', 'Pulse refused mirroring for this machine: the seat or plan lacks the mirror scope', {
+        cause: error,
+        details: { status: 403, code: error.code },
+      });
+    });
+  }
+}

package/src/lib/transportContract.js

@@ -0,0 +1,37 @@
+export const CONNECTOR_CONTRACT_VERSION = 2;
+export const OAUTH_CLIENT_ID = 'agentpulse-cli';
+export const USER_API_BASE = '/api/agent-hub/user';
+export const CONNECTOR_API_BASE = '/api/agent-hub/connector';
+export const MACHINE_REGISTRATION_PATH = `${USER_API_BASE}/machines`;
+export const MACHINE_ID_HEADER = 'x-agent-hub-machine-id';
+export const SESSION_ID_HEADER = 'x-agent-hub-session-id';
+export const POLICY_VERSION_HEADER = 'x-agent-hub-policy-version';
+export const DEV_ORG_INGRESS_HEADER = 'x-serverless-authorization';
+export const CONNECTOR_RESPONSE_MAX_BYTES = 512 * 1024;
+
+export const CONNECTOR_SCOPES = Object.freeze([
+  'agent-hub:connector:session',
+  'agent-hub:connector:heartbeat',
+  'agent-hub:connector:claim',
+  'agent-hub:connector:ack',
+  'agent-hub:connector:renew',
+  'agent-hub:connector:event',
+  'agent-hub:connector:mirror',
+]);
+
+export const CONNECTOR_AUTH_CONTRACT = Object.freeze({
+  scheme: 'Bearer',
+  machineIdHeader: MACHINE_ID_HEADER,
+  sessionIdHeader: SESSION_ID_HEADER,
+  policyVersionHeader: POLICY_VERSION_HEADER,
+  devOrgIngressHeader: DEV_ORG_INGRESS_HEADER,
+  connectorScopes: CONNECTOR_SCOPES,
+});
+
+export const LOGIN_SCOPE = [
+  'team-setup:dev-orgs:read',
+  'agent-hub:machines:read',
+  'agent-hub:machines:write',
+  ...CONNECTOR_SCOPES,
+  'offline_access',
+].join(' ');

package/src/commands/pulse/gate.js

@@ -1,23 +0,0 @@
-import { Command, Flags } from '@oclif/core';
-import { runPulse } from '../../runPulse.js';
-
-/** `agentpulse pulse gate` — the human-in-the-loop barrier. Advance only with --approved. */
-export default class PulseGate extends Command {
-  static description = 'The human gate. Advance the phase ONLY with --approved. Lock product decisions here.';
-  static examples = ['<%= config.bin %> pulse gate --approved --decisions-file decisions.json'];
-  static flags = {
-    approved: Flags.boolean({ description: 'Approve this phase (silence/omission = not approved).', default: false }),
-    'decisions-file': Flags.string({ description: 'Path to a JSON file of human product decisions to lock: [{ title, decision, rationale }].' }),
-  };
-
-  async run() {
-    const { flags } = await this.parse(PulseGate);
-    let decisions = [];
-    if (flags['decisions-file']) {
-      const fs = await import('node:fs');
-      decisions = JSON.parse(fs.readFileSync(flags['decisions-file'], 'utf8'));
-    }
-    const result = await runPulse('gate', { approved: flags.approved, decisions });
-    this.log(JSON.stringify(result, null, 2));
-  }
-}

package/src/commands/pulse/next.js

@@ -1,13 +0,0 @@
-import { Command } from '@oclif/core';
-import { runPulse } from '../../runPulse.js';
-
-/** `agentpulse pulse next` — emit the current phase work-list (prompts + schema, contract injected). */
-export default class PulseNext extends Command {
-  static description = 'Emit the current phase work-list: tasks (prompt + JSON schema) your model must run.';
-  static examples = ['<%= config.bin %> pulse next'];
-
-  async run() {
-    const result = await runPulse('next', {});
-    this.log(JSON.stringify(result, null, 2));
-  }
-}

package/src/commands/pulse/submit.js

@@ -1,19 +0,0 @@
-import { Command, Flags } from '@oclif/core';
-import { runPulse } from '../../runPulse.js';
-
-/** `agentpulse pulse submit` — validate the model's structured results against schema + contract. */
-export default class PulseSubmit extends Command {
-  static description = "Submit your model's structured results (JSON). Pulse validates them vs schema + contract.";
-  static examples = ['<%= config.bin %> pulse submit --results-file discovery-results.json'];
-  static flags = {
-    'results-file': Flags.string({ description: 'Path to a JSON file: [{ id, data }, …] (one per work-list task).', required: true }),
-  };
-
-  async run() {
-    const { flags } = await this.parse(PulseSubmit);
-    const fs = await import('node:fs');
-    const results = JSON.parse(fs.readFileSync(flags['results-file'], 'utf8'));
-    const result = await runPulse('submit', { results });
-    this.log(JSON.stringify(result, null, 2));
-  }
-}

package/src/commands/pulse/verify.js

@@ -1,18 +0,0 @@
-import { Command, Flags } from '@oclif/core';
-import { runPulse } from '../../runPulse.js';
-
-/** `agentpulse pulse verify` — run the contract's deterministic gate command. "Done" is this exit code. */
-export default class PulseVerify extends Command {
-  static description = "Run the contract's gate command (e.g. `npm run check`) and report pass/fail. Never an LLM opinion.";
-  static examples = ['<%= config.bin %> pulse verify'];
-  static flags = {
-    cwd: Flags.string({ description: 'Directory to run the gate in (default: current repo).' }),
-  };
-
-  async run() {
-    const { flags } = await this.parse(PulseVerify);
-    const result = await runPulse('verify', { cwd: flags.cwd });
-    this.log(JSON.stringify(result, null, 2));
-    if (!result.green) this.exit(1); // non-zero so CI / scripts can gate on it
-  }
-}

package/src/runPulse.js

@@ -1,58 +0,0 @@
-/**
- * runPulse.js — the PURE command core for the pulse CLI topic. Maps a verb + args → an engine call → a
- * JSON-serializable result. No oclif, no I/O of its own (the engine's state.js owns fs). This is what makes
- * the plugin testable without installing @oclif/core, and keeps the seam thin: the oclif command classes
- * (src/commands/pulse/*.js) are ~5-line wrappers that parse flags and call this.
- *
- * Mirror of the MCP seam's tools.js: one verb == one engine method. All discipline lives in @agentpulselabs/pulse.
- */
-
-import { createEngine } from '@agentpulselabs/pulse';
-
-/** The verbs this topic exposes, each → an engine method. Kept in sync with the MCP tool surface. */
-export const ACTIONS = ['start', 'next', 'submit', 'gate', 'verify', 'status', 'board', 'claim', 'sync'];
-
-/**
- * @param {string} action - one of ACTIONS
- * @param {Object} args   - parsed flags/inputs for the action
- * @param {Object} [opts] - { cwd, createEngine } (createEngine injectable for tests)
- * @returns {Promise<Object>} JSON-serializable result
- */
-export async function runPulse(action, args = {}, opts = {}) {
-  const make = opts.createEngine || createEngine;
-  const engine = make({ cwd: opts.cwd || process.cwd() });
-
-  switch (action) {
-    case 'start':
-      return engine.start({ requirements: args.requirements, grounding: args.grounding, name: args.name });
-    case 'next':
-      return engine.next();
-    case 'submit':
-      return engine.submit({ results: parseResults(args.results) });
-    case 'gate':
-      return engine.gate({ approved: !!args.approved, decisions: parseJson(args.decisions, []) });
-    case 'verify':
-      return await engine.verify({ cwd: args.cwd });
-    case 'status':
-      return engine.status();
-    case 'board':
-      return engine.boardUpdate({ id: args.id, status: args.status });
-    case 'claim':
-      return engine.claim({ id: args.id, agentId: args.agentId });
-    case 'sync':
-      return engine.sync({ ids: parseJson(args.ids, undefined) });
-    default:
-      throw new Error(`unknown pulse action "${action}" — expected one of ${ACTIONS.join(', ')}`);
-  }
-}
-
-// results may arrive as a JSON string (from --results-file content) or already-parsed array.
-function parseResults(r) {
-  if (Array.isArray(r)) return r;
-  return parseJson(r, []);
-}
-function parseJson(v, fallback) {
-  if (v == null) return fallback;
-  if (typeof v !== 'string') return v;
-  try { return JSON.parse(v); } catch { return fallback; }
-}