@agentpulselabs/cli-plugin-pulse 0.1.0 → 1.0.0

package/src/lib/pairingLifecycle.js

@@ -0,0 +1,179 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { CloudAuth, loginRequired } from './cloudAuth.js';
+import { HubError } from './errors.js';
+import { cleanOrigin, fetchJson } from './http.js';
+import { captureRootGrant } from './rootPolicy.js';
+import { writeOwnerOnlyJson } from './storage.js';
+import { MACHINE_REGISTRATION_PATH } from './transportContract.js';
+
+export const CONNECTOR_VERSION = JSON.parse(
+  readFileSync(new URL('../../package.json', import.meta.url), 'utf8')
+).version;
+const SESSION_SKEW_MS = 60_000;
+
+async function freezeRoots({ roots, configDir }) {
+  const requested = new Map();
+  for (const entry of roots) {
+    const separator = entry.indexOf('=');
+    if (separator < 1 || separator === entry.length - 1) {
+      throw new HubError('HUB_ROOT_ARGUMENT_INVALID', 'Roots must use <rootId>=<path>');
+    }
+    requested.set(entry.slice(0, separator), entry.slice(separator + 1));
+  }
+  if (requested.size < 1 || requested.size > 32) {
+    throw new HubError('HUB_ROOT_GRANT_MISMATCH', 'Pairing requires 1 to 32 explicitly approved roots');
+  }
+  const localRoots = [];
+  const grantRoots = [];
+  for (const [rootId, localPath] of requested) {
+    const local = await captureRootGrant({
+      rootId,
+      root: localPath,
+      repoWrite: false,
+      worktreeBase: path.join(configDir, 'worktrees', rootId),
+    });
+    const canonicalPathHash = createHash('sha256').update(local.canonicalRoot, 'utf8').digest('hex');
+    localRoots.push({ ...local, grantCanonicalPathHash: canonicalPathHash });
+    grantRoots.push({ rootId, label: rootId, canonicalPathHash, displayPath: rootId, repoWrite: false });
+  }
+  return { localRoots, grantRoots };
+}
+
+async function signedInSession({ tokenStore, platformUrl, login, now }) {
+  const stored = await tokenStore.load();
+  const fresh = stored?.platformUrl === platformUrl && Date.parse(stored.expiresAt || '') - now() > SESSION_SKEW_MS;
+  if (fresh) return stored;
+  if (!login) throw loginRequired('no valid sign-in for this platform');
+  const session = await login({ platformUrl });
+  await tokenStore.save(session);
+  return session;
+}
+
+async function resolveDevOrg({ fetch, platformUrl, session, slug }) {
+  const listed = await fetchJson({
+    fetch,
+    url: `${platformUrl}/api/team/dev-orgs`,
+    method: 'GET',
+    headers: { authorization: `Bearer ${session.accessToken}` },
+  });
+  if ([401, 403].includes(listed.status)) throw loginRequired(`the platform refused to list dev-orgs (HTTP ${listed.status})`);
+  if (!listed.ok) throw new HubError('HUB_TARGET_UNAVAILABLE', `Could not list dev-orgs (HTTP ${listed.status})`);
+  const devOrg = (listed.body.devOrgs || []).find((candidate) => candidate.slug === slug);
+  if (!devOrg) throw new HubError('HUB_DEV_ORG_UNKNOWN', `Dev-org "${slug}" is not in your team. Run \`agentpulse org list\`.`);
+  return { id: devOrg.id, slug: devOrg.slug };
+}
+
+function registeredMachine(response, { machineId, session, registration }) {
+  const machine = response?.machine;
+  const grant = machine?.activeGrant;
+  if (
+    machine?.id !== machineId ||
+    machine?.paired_by_user_id !== session.userId ||
+    machine?.team_id !== session.teamId ||
+    !Number.isInteger(grant?.version) ||
+    grant.version < 1 ||
+    !isDeepStrictEqual(grant.roots, registration.roots) ||
+    !isDeepStrictEqual(grant.capabilities, registration.capabilities) ||
+    !isDeepStrictEqual(grant.providerPolicy, registration.providerPolicy)
+  ) {
+    throw new HubError('HUB_PAIR_RESPONSE_INVALID', 'Cloud registration response does not match this request');
+  }
+  return { machineId: machine.id, policyVersion: grant.version };
+}
+
+export async function pairConnector({
+  config,
+  configDir,
+  configFile,
+  tokenStore,
+  fetch = globalThis.fetch,
+  login = null,
+  cliDefaults,
+  now = Date.now,
+  pairingPolicy = {
+    capabilities: ['workspace.read', 'git.read'],
+    providerPolicy: { providers: {}, maxConcurrency: 1, maxTokensPerRun: 1, maxCostUsd: 0 },
+  },
+  platformUrl,
+  org,
+  displayName,
+  roots = [],
+}) {
+  if (config.paired) {
+    throw new HubError('HUB_ALREADY_PAIRED', 'This connector is already paired. Revoke it before pairing again.');
+  }
+  const defaults = (!platformUrl || org === undefined) ? await cliDefaults() : {};
+  const stored = platformUrl ? null : await tokenStore.load();
+  const platform = platformUrl || stored?.platformUrl || defaults.platformUrl;
+  if (!platform) {
+    throw new HubError('HUB_PLATFORM_REQUIRED', 'Pass --platform <url> or run `agentpulse login` first');
+  }
+  const origin = cleanOrigin(platform, 'Platform URL');
+  const devOrgSlug = org === undefined ? defaults.devOrgSlug || null : org;
+  const session = await signedInSession({ tokenStore, platformUrl: origin, login, now });
+  const devOrg = devOrgSlug ? await resolveDevOrg({ fetch, platformUrl: origin, session, slug: devOrgSlug }) : null;
+  const auth = new CloudAuth({
+    tokenStore,
+    fetch,
+    now,
+    target: { platformUrl: origin, devOrg, instanceUrl: null, userId: session.userId, teamId: session.teamId },
+  });
+  const credentials = await auth.credentials();
+  const { localRoots, grantRoots } = await freezeRoots({ roots, configDir });
+  const machineId = config.pairing?.state === 'registering' ? config.pairing.machineId : randomUUID();
+  const registration = {
+    machineId,
+    displayName,
+    platform: process.platform,
+    connectorVersion: CONNECTOR_VERSION,
+    protocolVersion: 1,
+    roots: grantRoots,
+    capabilities: structuredClone(pairingPolicy.capabilities),
+    providerPolicy: structuredClone(pairingPolicy.providerPolicy),
+  };
+  const pendingConfig = {
+    ...config,
+    pairing: { state: 'registering', machineId, startedAt: config.pairing?.startedAt || new Date(now()).toISOString() },
+  };
+  await writeOwnerOnlyJson(configFile, pendingConfig);
+  const registered = await fetchJson({
+    fetch,
+    url: `${auth.instanceUrl}${MACHINE_REGISTRATION_PATH}`,
+    headers: credentials,
+    body: registration,
+  });
+  if (registered.status === 401) throw loginRequired('the dev-org refused the sign-in');
+  if (registered.status === 403 && registered.body.error === 'FORBIDDEN') {
+    throw new HubError('HUB_SCOPE_DENIED', 'Your Pulse tier does not allow registering machines');
+  }
+  if (!registered.ok) {
+    throw new HubError(registered.body.error || `HTTP_${registered.status}`, registered.body.message || 'Machine registration failed');
+  }
+  const { policyVersion } = registeredMachine(registered.body, { machineId, session, registration });
+  await writeOwnerOnlyJson(configFile, {
+    ...pendingConfig,
+    pairing: null,
+    capabilities: registration.capabilities,
+    localRoots,
+    paired: {
+      machineId,
+      policyVersion,
+      state: 'active',
+      baseUrl: auth.instanceUrl,
+      target: { platformUrl: origin, devOrg },
+      userId: session.userId,
+      teamId: session.teamId,
+      pairedAt: new Date(now()).toISOString(),
+    },
+  });
+  return {
+    command: 'pair',
+    state: 'paired',
+    machineId,
+    target: devOrg ? devOrg.slug : origin,
+    message: `Pulse connector paired with ${devOrg ? `dev-org ${devOrg.slug}` : origin}.`,
+  };
+}

package/src/lib/pathRedaction.js

@@ -0,0 +1,89 @@
+import os from 'node:os';
+
+const PATH_ONLY_FIELDS = new Set(['file', 'worktreePath', 'mainRepo', 'channelCheckout', 'cwd', 'path', 'transcriptPath']);
+const PATH_TAIL = String.raw`[^\s"'\`<>()\[\]{},;]*`;
+const PATH_START = String.raw`(?:~/|/(?:Users|Volumes|home|private|tmp|var|opt|mnt|root|etc|Library|Applications)/|[A-Za-z]:\\)`;
+const ABSOLUTE = new RegExp(String.raw`(?<![\w./~\\-])${PATH_START}${PATH_TAIL}`, 'g');
+const ABSOLUTE_PROBE = new RegExp(ABSOLUTE.source);
+const DELIMITED = new RegExp(String.raw`(\`|\]\()(${PATH_START}[^\`)\n]*)(?=[\`)])`, 'g');
+const FILE_URL = /file:\/\/(?=\/|[A-Za-z]:\\)/g;
+const HOME_PARENTS = /^(?:Users|home)$/i;
+const SEEN_MAX = 100_000;
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function lastSegment(value) {
+  const parts = value.split(/[\\/]+/).filter((part) => part && part !== '~' && !/^[A-Za-z]:$/.test(part));
+  if (parts.length === 0 || (parts.length <= 2 && HOME_PARENTS.test(parts[0]))) return '~';
+  return parts.at(-1);
+}
+
+function rootPattern(root) {
+  return new RegExp(`${escapeRegExp(root.replace(/\/+$/, ''))}(?=$|[^\\w.-])(/${PATH_TAIL})?`, 'g');
+}
+
+export function createPathRedactor({ repos = [], workspace = null, home = os.homedir() } = {}) {
+  const replacements = [
+    ...repos
+      .filter((repo) => repo?.root && repo?.name)
+      .map((repo) => ({ root: repo.root, render: (rest) => (rest ? `${repo.name}${rest}` : repo.name) })),
+    ...(workspace ? [{ root: workspace, render: (rest) => (rest ? rest.slice(1) : 'workspace') }] : []),
+    ...(home ? [{ root: home, render: (rest) => (rest ? rest.slice(1) : '~') }] : []),
+  ]
+    .sort((left, right) => right.root.length - left.root.length)
+    .map((entry) => ({ pattern: rootPattern(entry.root), render: entry.render }));
+
+  // Every pattern needs a slash or a backslash, and the graph windows repeat the same strings many times over.
+  const seen = new Map();
+  const redactString = (input) => {
+    const original = String(input ?? '');
+    if (!/[/\\]/.test(original)) return original;
+    const cached = seen.get(original);
+    if (cached !== undefined) return cached;
+    let text = original.replace(FILE_URL, '');
+    for (const { pattern, render } of replacements) {
+      text = text.replace(pattern, (_match, rest) => render(rest?.replace(/\/+$/, '') || ''));
+    }
+    text = text.replace(DELIMITED, (_match, open, value) => `${open}${lastSegment(value)}`);
+    text = text.replace(ABSOLUTE, (match) => lastSegment(match));
+    if (seen.size >= SEEN_MAX) seen.clear();
+    seen.set(original, text);
+    return text;
+  };
+
+  // `text` replaces redactString for callers that redact more than paths (the mirror's secret table) in one walk;
+  // `entry(key, value)` may return a whole replacement for a value (a secret-named key), or null to walk it.
+  const redactValue = (value, { keep = [], redactString: text = redactString, entry: replaceEntry = () => null } = {}) => {
+    const kept = new Set(keep);
+    const walk = (entry) => {
+      if (typeof entry === 'string') return text(entry);
+      if (Array.isArray(entry)) return entry.map(walk);
+      if (entry && typeof entry === 'object') {
+        const out = {};
+        for (const [key, item] of Object.entries(entry)) {
+          if (PATH_ONLY_FIELDS.has(key) && !kept.has(key)) continue;
+          out[text(key)] = replaceEntry(key, item) ?? walk(item);
+        }
+        return out;
+      }
+      return entry;
+    };
+    return walk(value);
+  };
+
+  return { redactString, redactValue };
+}
+
+export function containsPath(value, { home = os.homedir(), workspace = null } = {}) {
+  const roots = [home, workspace].filter(Boolean);
+  const check = (text) => ABSOLUTE_PROBE.test(text) || roots.some((root) => text.includes(root));
+  const walk = (entry) => {
+    if (typeof entry === 'string') return check(entry);
+    if (Array.isArray(entry)) return entry.some(walk);
+    if (entry && typeof entry === 'object') return Object.entries(entry).some(([key, item]) => check(key) || walk(item));
+    return false;
+  };
+  return walk(value);
+}

package/src/lib/planContract.js

@@ -0,0 +1,141 @@
+import { HubError } from './errors.js';
+
+const ROLES = new Set(['architect', 'coder', 'reviewer', 'auditor']);
+const CHECKS = new Set(['unit', 'typecheck', 'lint', 'schema', 'api', 'browser']);
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$/;
+
+function planError(message) {
+  return new HubError('invalid_delivery_plan', message);
+}
+
+function requireText(value, name, maximum) {
+  if (typeof value !== 'string' || !value.trim() || value.length > maximum) {
+    throw planError(`${name} must be a bounded non-empty string`);
+  }
+}
+
+function assertOnlyKeys(value, allowed, name) {
+  const extra = Object.keys(value || {}).find((key) => !allowed.includes(key));
+  if (extra) throw planError(`${name} contains unsupported field "${extra}"`);
+}
+
+function assertAcyclic(streams) {
+  const dependencies = new Map(streams.map((stream) => [stream.name, stream.dependencies]));
+  const visiting = new Set();
+  const visited = new Set();
+  const visit = (name) => {
+    if (visiting.has(name)) throw planError(`dependency cycle includes "${name}"`);
+    if (visited.has(name)) return;
+    visiting.add(name);
+    for (const dependency of dependencies.get(name) || []) visit(dependency);
+    visiting.delete(name);
+    visited.add(name);
+  };
+  for (const name of dependencies.keys()) visit(name);
+}
+
+export function canonicalJson(value) {
+  const normalize = (entry, seen) => {
+    if (entry === null || typeof entry === 'string' || typeof entry === 'boolean') return entry;
+    if (typeof entry === 'number') {
+      if (!Number.isFinite(entry)) throw new TypeError('canonical JSON rejects non-finite numbers');
+      return entry;
+    }
+    if (typeof entry !== 'object') throw new TypeError(`canonical JSON rejects ${typeof entry}`);
+    if (seen.has(entry)) throw new TypeError('canonical JSON rejects cyclic values');
+    seen.add(entry);
+    const output = Array.isArray(entry)
+      ? entry.map((item) => normalize(item, seen))
+      : Object.fromEntries(
+          Object.keys(entry)
+            .sort()
+            .map((key) => [key, normalize(entry[key], seen)])
+        );
+    seen.delete(entry);
+    return output;
+  };
+  return JSON.stringify(normalize(value, new WeakSet()));
+}
+
+export function validateDeliveryPlan(plan, grant) {
+  if (
+    !plan ||
+    typeof plan !== 'object' ||
+    Array.isArray(plan) ||
+    Buffer.byteLength(JSON.stringify(plan), 'utf8') > 32 * 1024
+  ) {
+    throw planError('plan must be a JSON object no larger than 32 KiB');
+  }
+  assertOnlyKeys(plan, ['streams', 'risks', 'estimate'], 'plan');
+  if (!Array.isArray(plan.streams) || plan.streams.length < 1 || plan.streams.length > 50) {
+    throw planError('streams must contain 1 to 50 entries');
+  }
+  const roots = new Map((grant.roots || []).map((root) => [root.rootId, root]));
+  const capabilities = new Set(grant.capabilities || []);
+  if (!capabilities.has('workspace.read') || !capabilities.has('worktree.create')) {
+    throw planError('grant lacks planning capabilities');
+  }
+  const names = new Set();
+  let agentCount = 0;
+  const streams = plan.streams.map((stream) => {
+    assertOnlyKeys(stream, ['name', 'rootId', 'repoDisplay', 'dependencies', 'agents', 'checks'], 'stream');
+    if (!NAME.test(String(stream.name || '')) || names.has(stream.name)) {
+      throw planError('stream name is invalid or duplicated');
+    }
+    names.add(stream.name);
+    const root = roots.get(stream.rootId);
+    if (!root?.repoWrite) throw planError(`root "${stream.rootId}" is not approved for worktrees`);
+    requireText(stream.repoDisplay, 'repoDisplay', 240);
+    if (!Array.isArray(stream.dependencies) || stream.dependencies.length > 50) {
+      throw planError('stream dependencies are invalid');
+    }
+    if (!Array.isArray(stream.agents) || stream.agents.length < 1 || stream.agents.length > 8) {
+      throw planError('stream agents are invalid');
+    }
+    agentCount += stream.agents.length;
+    const agents = stream.agents.map((agent) => {
+      assertOnlyKeys(agent, ['role', 'provider', 'model', 'displayName'], 'agent');
+      if (!ROLES.has(agent.role)) throw planError('agent role is invalid');
+      requireText(agent.provider, 'provider', 40);
+      requireText(agent.model, 'model', 100);
+      if (!grant.providerPolicy?.providers?.[agent.provider]?.includes(agent.model)) {
+        throw planError('provider/model is not allowed');
+      }
+      if (!capabilities.has(`agent.${agent.provider}.invoke`)) {
+        throw planError('provider capability is not granted');
+      }
+      if (agent.role === 'coder' && !capabilities.has('workspace.write')) {
+        throw planError('coder lacks workspace.write');
+      }
+      if (agent.displayName !== undefined) requireText(agent.displayName, 'displayName', 120);
+      return { ...agent };
+    });
+    if (!Array.isArray(stream.checks) || stream.checks.some((check) => !CHECKS.has(check))) {
+      throw planError('stream contains an unregistered check');
+    }
+    return { ...stream, dependencies: [...stream.dependencies], agents, checks: [...stream.checks] };
+  });
+  for (const stream of streams) {
+    for (const dependency of stream.dependencies) {
+      if (!names.has(dependency) || dependency === stream.name) {
+        throw planError('stream dependency is invalid');
+      }
+    }
+  }
+  assertAcyclic(streams);
+  if (agentCount > Math.max(1, grant.providerPolicy.maxConcurrency) * streams.length) {
+    throw planError('plan agent count exceeds provider concurrency');
+  }
+  if (plan.risks !== undefined) {
+    if (!Array.isArray(plan.risks) || plan.risks.length > 50) throw planError('risks are invalid');
+    plan.risks.forEach((risk) => requireText(risk, 'risk', 1_000));
+  }
+  if (!plan.estimate || typeof plan.estimate !== 'object' || Array.isArray(plan.estimate)) {
+    throw planError('estimate is required');
+  }
+  assertOnlyKeys(plan.estimate, ['tokens', 'costUsd', 'wallClockMinutes'], 'estimate');
+  for (const [key, value] of Object.entries(plan.estimate)) {
+    if (!Number.isFinite(value) || value < 0) throw planError(`estimate.${key} is invalid`);
+  }
+  return { streams, risks: [...(plan.risks || [])], estimate: { ...plan.estimate } };
+}

package/src/lib/priorityLane.js

@@ -0,0 +1,80 @@
+/** How long a background request waits for priority requests before it goes out alongside them. */
+export const BACKGROUND_MAX_WAIT_MS = 1_000;
+const RECENT_CALLS = 50;
+
+/**
+ * Requests that keep the machine and its jobs alive go first: a background request (a mirror batch) waits while a
+ * priority request (heartbeat, session, renew, ack, events) is in flight, but for maxWaitMs at most; then it runs
+ * alongside, so priority orders requests and never holds the mirror behind a slow or retrying call. A priority
+ * request never waits. Every priority call is kept (path, attempts, statuses, backoff, time) for the mirror's pass
+ * record.
+ */
+export class PriorityLane {
+  constructor({ maxWaitMs = BACKGROUND_MAX_WAIT_MS, now = Date.now } = {}) {
+    this.maxWaitMs = maxWaitMs;
+    this.now = now;
+    this.inFlight = new Set();
+    this.recent = [];
+    this.idle = Promise.resolve();
+    this.release = () => {};
+  }
+
+  /** action(trace) runs at once; trace gathers its attempts, statuses and backoff. */
+  async priority(action, { path = 'unknown' } = {}) {
+    if (this.inFlight.size === 0) this.idle = new Promise((resolve) => { this.release = resolve; });
+    const call = { path, at: this.now(), trace: {}, end: null, code: null };
+    this.inFlight.add(call);
+    try {
+      return await action(call.trace);
+    } catch (error) {
+      call.code = error.code || 'HUB_REQUEST_FAILED';
+      throw error;
+    } finally {
+      call.end = this.now();
+      this.inFlight.delete(call);
+      this.recent = [...this.recent, call].slice(-RECENT_CALLS);
+      if (this.inFlight.size === 0) this.release();
+    }
+  }
+
+  /**
+   * trace gets laneWaitMs, laneCapped (the wait hit maxWaitMs and the request went out alongside a priority call) and
+   * heldBy, the priority calls it waited behind.
+   */
+  async background(action, { trace = {} } = {}) {
+    const queuedAt = this.now();
+    let capped = false;
+    if (this.inFlight.size > 0) {
+      let timer;
+      let expired = false;
+      const deadline = new Promise((resolve) => { timer = setTimeout(() => { expired = true; resolve(); }, this.maxWaitMs); });
+      try {
+        while (this.inFlight.size > 0 && !expired) await Promise.race([this.idle, deadline]);
+      } finally {
+        clearTimeout(timer);
+      }
+      capped = this.inFlight.size > 0;
+    }
+    const startedAt = this.now();
+    trace.laneWaitMs = startedAt - queuedAt;
+    trace.laneCapped = capped;
+    trace.heldBy = trace.laneWaitMs > 0 || capped ? this.calls({ since: queuedAt, until: startedAt }) : [];
+    return action();
+  }
+
+  /** The priority calls in flight at any time between since and until (now by default), oldest first. */
+  calls({ since = -Infinity, until = Infinity } = {}) {
+    return [...this.recent, ...this.inFlight]
+      .filter((call) => (call.end ?? Infinity) >= since && call.at <= until)
+      .map((call) => ({
+        path: call.path,
+        at: call.at,
+        ms: (call.end ?? this.now()) - call.at,
+        attempts: call.trace.attempts ?? 0,
+        statuses: [...(call.trace.statuses ?? [])],
+        backoffMs: call.trace.backoffMs ?? 0,
+        done: call.end !== null,
+        code: call.code,
+      }));
+  }
+}