@agentpulselabs/cli-plugin-pulse 0.2.0 → 1.1.2

package/src/lib/tokenStore.js

@@ -0,0 +1,136 @@
+import { createHash } from 'node:crypto';
+import { rm } from 'node:fs/promises';
+import path from 'node:path';
+import { HubError } from './errors.js';
+import { acquireOwnerLock } from './ownerLock.js';
+import { ProcessIdentityProvider } from './processOwnership.js';
+import { readOwnerOnlyJson, writeOwnerOnlyJson } from './storage.js';
+
+/** The one name every config used before sign-ins were named per config dir; a config without `secretRef` still uses it. */
+export const LEGACY_SECRET_REFERENCE = 'oauth-session';
+/** This config dir's own sign-in item, so a second config (another XDG_CONFIG_HOME or profile) never overwrites it. */
+export const sessionSecretReference = (configDir) => `oauth-session-${createHash('sha256').update(path.resolve(configDir)).digest('hex').slice(0, 16)}`;
+const METADATA_FILE = 'oauth-session.json';
+const LOCK_FILE = 'oauth-refresh.lock';
+const inProcessLocks = new Map();
+
+export class TokenStore {
+  constructor({ secretStore, configDir, lockTimeoutMs = 10_000, identityProvider = new ProcessIdentityProvider() }) {
+    this.secretStore = secretStore;
+    this.ownReference = sessionSecretReference(configDir);
+    this.metadataFile = path.join(configDir, METADATA_FILE);
+    this.lockFile = path.join(configDir, LOCK_FILE);
+    this.lockTimeoutMs = lockTimeoutMs;
+    this.identityProvider = identityProvider;
+  }
+
+  /** The item a config's sign-in lives in: its recorded one, the legacy one for a config signed in before, else its own. */
+  #reference(metadata) {
+    if (!metadata) return this.ownReference;
+    return metadata.secretRef || LEGACY_SECRET_REFERENCE;
+  }
+
+  async load() {
+    const metadata = await readOwnerOnlyJson(this.metadataFile);
+    if (!metadata) return null;
+    const secret = await this.secretStore.get(this.#reference(metadata));
+    if (!secret) return null;
+    let tokens;
+    try {
+      tokens = JSON.parse(secret);
+    } catch (error) {
+      throw new HubError('HUB_TOKEN_STORE_CORRUPT', 'Stored Pulse sign-in is unreadable; run `agentpulse pulse login`', {
+        cause: error,
+      });
+    }
+    return {
+      platformUrl: metadata.platformUrl,
+      userId: metadata.userId,
+      teamId: metadata.teamId,
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken ?? null,
+      expiresAt: metadata.expiresAt,
+      scopes: metadata.scopes || [],
+    };
+  }
+
+  async scopes() {
+    const metadata = await readOwnerOnlyJson(this.metadataFile);
+    return Array.isArray(metadata?.scopes) ? metadata.scopes : [];
+  }
+
+  async save(session) {
+    if (typeof session?.accessToken !== 'string' || !session.userId || !session.teamId || !session.platformUrl) {
+      throw new HubError('HUB_TOKEN_STORE_INVALID', 'Refusing to store an incomplete Pulse sign-in');
+    }
+    const reference = this.#reference(await readOwnerOnlyJson(this.metadataFile));
+    await this.secretStore.set(reference, JSON.stringify({
+      accessToken: session.accessToken,
+      refreshToken: session.refreshToken ?? null,
+    }));
+    await writeOwnerOnlyJson(this.metadataFile, {
+      ...(reference === LEGACY_SECRET_REFERENCE ? {} : { secretRef: reference }),
+      platformUrl: session.platformUrl,
+      userId: session.userId,
+      teamId: session.teamId,
+      expiresAt: session.expiresAt,
+      scopes: session.scopes || [],
+    });
+  }
+
+  async clear() {
+    await this.secretStore.delete(this.#reference(await readOwnerOnlyJson(this.metadataFile)));
+    await rm(this.metadataFile, { force: true });
+  }
+
+  /** What `migrateSecret` would do, read-only: `{ from, to }` for a legacy sign-in, else null. */
+  async secretPlan() {
+    const metadata = await readOwnerOnlyJson(this.metadataFile);
+    return metadata && !metadata.secretRef ? { from: LEGACY_SECRET_REFERENCE, to: this.ownReference } : null;
+  }
+
+  /**
+   * Move a legacy sign-in to this config's own item (at cutover): copy, read it back, record it, and only then remove
+   * the legacy item. Runs under the refresh lock, so a refresh can't write the legacy item in between.
+   */
+  async migrateSecret() {
+    return this.withRefreshLock(async () => {
+      const metadata = await readOwnerOnlyJson(this.metadataFile);
+      if (!metadata || metadata.secretRef) return { moved: false, reference: metadata?.secretRef ?? null };
+      const secret = await this.secretStore.get(LEGACY_SECRET_REFERENCE);
+      if (!secret) return { moved: false, reference: null };
+      await this.secretStore.set(this.ownReference, secret);
+      if ((await this.secretStore.get(this.ownReference)) !== secret) {
+        throw new HubError('HUB_TOKEN_MIGRATION_FAILED', 'The sign-in did not read back from its new Keychain item; the old item is kept');
+      }
+      await writeOwnerOnlyJson(this.metadataFile, { secretRef: this.ownReference, ...metadata });
+      await this.secretStore.delete(LEGACY_SECRET_REFERENCE);
+      return { moved: true, from: LEGACY_SECRET_REFERENCE, to: this.ownReference };
+    });
+  }
+
+  async withRefreshLock(action) {
+    const previous = inProcessLocks.get(this.lockFile) || Promise.resolve();
+    let release;
+    const current = previous.then(() => new Promise((resolve) => { release = resolve; }));
+    inProcessLocks.set(this.lockFile, current);
+    await previous;
+    try {
+      const releaseFile = await acquireOwnerLock({
+        file: this.lockFile,
+        identity: await this.identityProvider.capture(process.pid),
+        identityProvider: this.identityProvider,
+        timeoutMs: this.lockTimeoutMs,
+        heldError: () => new HubError('HUB_REFRESH_LOCKED', 'Another Pulse process is refreshing the sign-in; retry shortly'),
+      });
+      try {
+        return await action();
+      } finally {
+        await releaseFile();
+      }
+    } finally {
+      release();
+      if (inProcessLocks.get(this.lockFile) === current) inProcessLocks.delete(this.lockFile);
+    }
+  }
+}

package/src/lib/transport.js

@@ -0,0 +1,334 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { fullJitterDelay } from './backoff.js';
+import { loginRequired } from './cloudAuth.js';
+import { HubError, SCOPE_FIX } 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;
+// The cloud's PULSE_LIMITS: a command batch holds at most 100 commands in 512 KB.
+const PULSE_MAX_BATCH = 100;
+const PULSE_BODY_BYTES = 512 * 1024;
+
+/**
+ * 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 (payload !== undefined && 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 = {}, method = 'POST' }) {
+    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}`,
+          method,
+          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') {
+        const missingScopes = (Array.isArray(response.body.required) ? response.body.required : []).filter((s) => typeof s === 'string').slice(0, 10).map((s) => s.slice(0, 80));
+        throw new HubError('HUB_SCOPE_DENIED', missingScopes.length
+          ? `The Pulse sign-in lacks ${missingScopes.join(', ')}; run \`${SCOPE_FIX}\``
+          : 'Your Pulse tier does not grant the connector scopes for this operation', {
+          details: { status: 403, missingScopes, fix: SCOPE_FIX },
+        });
+      }
+      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' });
+  }
+
+  /**
+   * One batch of Pulse log commands (`[{ type, idempotencyKey, payload, group? }]`, at most 100), answered per item.
+   * It waits behind heartbeats like a mirror batch. 429 and 5xx are retried with Retry-After; a refusal of the whole
+   * batch (the team's cloud-first flag is off, a missing capability) is thrown with the cloud's code.
+   */
+  commands(payload) {
+    if (!Array.isArray(payload?.commands) || payload.commands.length < 1 || payload.commands.length > PULSE_MAX_BATCH) {
+      throw new HubError('HUB_COMMAND_BATCH_INVALID', `A command batch holds 1 to ${PULSE_MAX_BATCH} commands`);
+    }
+    return this.lane.background(() => this.#request(`${CONNECTOR_API_BASE}/commands`, payload, {
+      retry: true,
+      maxBodyBytes: PULSE_BODY_BYTES,
+      timeoutMs: MIRROR_TIMEOUT_MS,
+      gzipAboveBytes: MIRROR_GZIP_ABOVE_BYTES,
+    }));
+  }
+
+  /**
+   * One page of this machine's Pulse log after `since` (design §5.4), held up to `wait` seconds when nothing is new:
+   * `{ events, next, head, floor, presence, presenceNext }`. `presence` is the last answer's `presenceNext`, an opaque
+   * keyset, so beats already sent never come back and a held wait holds. Behind the retention floor the cloud answers 410.
+   */
+  sync({ since, wait = 20, presence = null } = {}) {
+    const query = new URLSearchParams({ since: String(since), wait: String(wait), ...(presence ? { presence } : {}) });
+    return this.#request(`${CONNECTOR_API_BASE}/sync?${query}`, undefined, {
+      retry: true, maxBodyBytes: 0, method: 'GET', timeoutMs: (Number(wait) + 10) * 1000,
+    });
+  }
+
+  /** Whether this team has Pulse cloud-first turned on: `{ enabled, since }`. */
+  cloudFirst() {
+    return this.#request(`${CONNECTOR_API_BASE}/cloud-first`, undefined, { retry: true, maxBodyBytes: 0, method: 'GET' });
+  }
+
+  /** The parity report of this machine's mirror against the Pulse log, for the last `hours`; `view: 'reconcile'` asks for
+   * the import reconciliation view of this machine's log instead (ADR-4). */
+  parity({ hours = 6, view = null } = {}) {
+    const query = new URLSearchParams(view ? { view } : { hours: String(hours) });
+    return this.#request(`${CONNECTOR_API_BASE}/parity?${query}`, undefined, { retry: true, maxBodyBytes: 0, method: 'GET', timeoutMs: MIRROR_TIMEOUT_MS });
+  }
+
+  /** 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,40 @@
+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',
+  // The Pulse log (cloud-first Phase 2): the shadow feed writes commands and reads the cloud-first flag and parity.
+  'agent-hub:connector:sync',
+  'agent-hub:connector:commands',
+]);
+
+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/lib/uploadRedactor.js

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import { redactSecretSubtree, secretKeyReplacement } from './mirrorContract.js';
+import { createPathRedactor } from './pathRedaction.js';
+import { redactSecrets } from './redaction.js';
+
+const SEEN_MAX = 100_000;
+// The line net can fire again on text a first pass redacted (a marker earlier on the line); a stable redaction repeats
+// the passes until nothing changes, so the cloud's own pass over it changes nothing either.
+const STABLE_PASSES = 4;
+
+/**
+ * What leaves this machine for Pulse passes through here, for the mirror and the Pulse log alike: the contract's
+ * secret passes first, then path redaction, on every string and key, so a secret inside a path is never cut down to
+ * a last segment that still holds it, and nothing is projected, truncated or hashed before both have run. Repository
+ * roots are learned from the deliveries the hub reports; the redacted form of a value depends on those roots, the
+ * workspace, the home folder and the held secrets, and on nothing else.
+ */
+export class UploadRedactor {
+  constructor({ workspace, home, approvedRoots = [] }) {
+    this.workspace = workspace;
+    this.home = home;
+    this.repoRoots = new Map(approvedRoots.map((root) => [root, path.basename(root)]));
+    this.worktreeRoots = new Map();
+  }
+
+  learnRepos(deliveries) {
+    for (const stream of deliveries.flatMap((delivery) => delivery.streams || [])) {
+      const git = stream.git || {};
+      if (typeof git.mainRepo === 'string' && path.isAbsolute(git.mainRepo)) this.repoRoots.set(git.mainRepo, path.basename(git.mainRepo));
+      for (const extra of [git.worktreePath, git.channelCheckout]) {
+        if (typeof extra === 'string' && path.isAbsolute(extra) && !this.repoRoots.has(extra)) this.worktreeRoots.set(extra, path.basename(extra));
+      }
+    }
+  }
+
+  /**
+   * The learned roots, to persist: a worktree whose delivery is gone must keep redacting as it did, or a rescan of the
+   * same text gives another body than the one already sent (CUT-02).
+   */
+  roots() {
+    return { repo: [...this.repoRoots], worktree: [...this.worktreeRoots] };
+  }
+
+  /** Roots persisted by an earlier scan, added to what this one learns. */
+  seed(roots) {
+    for (const [root, name] of Array.isArray(roots?.repo) ? roots.repo : []) {
+      if (typeof root === 'string' && path.isAbsolute(root) && typeof name === 'string') this.repoRoots.set(root, name);
+    }
+    for (const [root, name] of Array.isArray(roots?.worktree) ? roots.worktree : []) {
+      if (typeof root === 'string' && path.isAbsolute(root) && typeof name === 'string' && !this.repoRoots.has(root)) this.worktreeRoots.set(root, name);
+    }
+  }
+
+  /** Everything the redacted form depends on besides the input, as one string (for memo keys and digests). */
+  basis(secrets) {
+    return JSON.stringify([[...this.repoRoots], [...this.worktreeRoots], this.workspace, this.home, secrets]);
+  }
+
+  /** `stable` (the Pulse log) repeats the secret passes until a pass changes nothing; the mirror keeps one pass. */
+  redactor(secrets, { stable = false } = {}) {
+    const repos = [...this.repoRoots, ...this.worktreeRoots].map(([root, name]) => ({ root, name }));
+    const paths = createPathRedactor({ repos, workspace: this.workspace, home: this.home });
+    const seen = new Map();
+    let redactions = 0;
+    const redactString = (input) => {
+      const original = String(input ?? '');
+      let done = seen.get(original);
+      if (done === undefined) {
+        let secret = redactSecrets(original, { secrets });
+        let count = secret.redactions;
+        for (let pass = 1; stable && pass < STABLE_PASSES; pass += 1) {
+          const again = redactSecrets(secret.text, { secrets });
+          if (again.text === secret.text) break;
+          count += again.redactions;
+          secret = again;
+        }
+        done = { text: paths.redactString(secret.text), redactions: count };
+        if (seen.size >= SEEN_MAX) seen.clear();
+        seen.set(original, done);
+      }
+      redactions += done.redactions;
+      return done.text;
+    };
+    const entry = (key, item) => {
+      const replaced = secretKeyReplacement(key, item);
+      if (replaced === undefined || replaced === null) return redactSecretSubtree(key, item, redactString);
+      redactions += 1;
+      return replaced;
+    };
+    const redactValue = (value, { keep = [] } = {}) => paths.redactValue(value, { keep, redactString, entry });
+    return {
+      redactString,
+      redactValue,
+      /** Secret replacements made since the last call (memoised strings count each time they are used). */
+      takeRedactions: () => {
+        const count = redactions;
+        redactions = 0;
+        return count;
+      },
+    };
+  }
+}