@agent-link/agent 0.1.295 → 0.1.297

package/worker/worker.cjs

@@ -0,0 +1,612 @@
+#!/usr/bin/env node
+'use strict';
+
+const childProcess = require('child_process');
+const crypto = require('crypto');
+const fs = require('fs');
+const http = require('http');
+const path = require('path');
+
+const PROTOCOL_VERSION = 1;
+const PHASES = {
+  'worker-starting': ['worker-ready', 'failed'],
+  'worker-ready': ['shutdown-requested', 'failed'],
+  'shutdown-requested': ['old-agent-stopped', 'failed'],
+  'old-agent-stopped': ['switching', 'failed'],
+  switching: ['target-starting', 'failed'],
+  'target-starting': ['target-started', 'failed'],
+};
+
+function fail(message) {
+  process.stderr.write(`[AgentLink Worker] ${message}\n`);
+}
+
+function atomicJson(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  const fd = fs.openSync(temporary, 'wx', 0o600);
+  try {
+    fs.writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  let lastError;
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      fs.renameSync(temporary, file);
+      if (process.platform !== 'win32') fs.chmodSync(file, 0o600);
+      return;
+    } catch (error) {
+      lastError = error;
+      if (!['EACCES', 'EBUSY', 'EPERM'].includes(error.code) || attempt === 4) break;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20 * (attempt + 1));
+    }
+  }
+  fs.rmSync(temporary, { force: true });
+  throw lastError;
+}
+
+function loadJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function loadJob(jobPath) {
+  const job = loadJson(jobPath);
+  if (
+    !job
+    || job.schemaVersion !== 2
+    || typeof job.jobId !== 'string'
+    || job.restartOwner !== 'worker'
+    || path.resolve(job.dataRoot) !== path.resolve(process.env.AGENTLINK_HOME || '')
+  ) {
+    throw new Error('job schema or data root is invalid');
+  }
+  return job;
+}
+
+function appendEvent(jobPath, job, code, detail) {
+  const event = {
+    timestamp: new Date().toISOString(),
+    jobId: job.jobId,
+    phase: job.phase,
+    code,
+    ...(detail ? { detail: String(detail).slice(0, 512) } : {}),
+    oldRuntime: {
+      pid: job.oldRuntime.pid,
+      processStartIdentity: job.oldRuntime.processStartIdentity,
+    },
+    ...(job.worker ? {
+      worker: {
+        pid: job.worker.pid,
+        processStartIdentity: job.worker.processStartIdentity,
+      },
+    } : {}),
+  };
+  fs.appendFileSync(path.join(path.dirname(jobPath), 'events.jsonl'), `${JSON.stringify(event)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600,
+  });
+}
+
+function transition(jobPath, expectedJobId, phase, extra) {
+  const current = loadJob(jobPath);
+  if (current.jobId !== expectedJobId) throw new Error('job identity changed');
+  if (current.phase !== phase && !(PHASES[current.phase] || []).includes(phase)) {
+    throw new Error(`invalid worker transition ${current.phase} -> ${phase}`);
+  }
+  const updated = {
+    ...current,
+    ...extra,
+    phase,
+    updatedAt: new Date().toISOString(),
+  };
+  atomicJson(jobPath, updated);
+  atomicJson(path.join(updated.dataRoot, 'upgrades', 'latest.json'), updated);
+  appendEvent(jobPath, updated, `phase-${phase}`);
+  return updated;
+}
+
+function identityError(error) {
+  return error && error.message ? error.message : String(error);
+}
+
+function processIdentity(pid) {
+  if (process.platform === 'linux') {
+  let stat;
+  try {
+    stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8').trim();
+  } catch (error) {
+    return error.code === 'ENOENT' || error.code === 'ESRCH'
+      ? { status: 'absent' }
+      : { status: 'error', error: identityError(error) };
+  }
+  try {
+    const commandEnd = stat.lastIndexOf(')');
+    if (commandEnd < 0) return { status: 'error', error: 'malformed Linux process stat' };
+    const fields = stat.slice(commandEnd + 2).split(/\s+/);
+    const bootId = fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+    return fields[19] && bootId
+      ? { status: 'found', identity: `linux:${bootId}:${fields[19]}` }
+      : { status: 'error', error: 'incomplete Linux process identity' };
+  } catch (error) {
+    return { status: 'error', error: identityError(error) };
+  }
+  }
+  if (process.platform === 'darwin') {
+  try {
+    const started = childProcess.execFileSync(
+        '/bin/ps',
+        ['-o', 'lstart=', '-p', String(pid)],
+        { encoding: 'utf8', timeout: 3000 },
+      ).trim();
+      return started
+        ? { status: 'found', identity: `darwin:${started}` }
+        : { status: 'absent' };
+    } catch (error) {
+      return error.status === 1 || error.code === 'ESRCH'
+        ? { status: 'absent' }
+        : { status: 'error', error: identityError(error) };
+    }
+  }
+  if (process.platform === 'win32') {
+    try {
+      const script = '& { param([int]$ProcessId) $p=Get-CimInstance Win32_Process -Filter ("ProcessId="+$ProcessId);if($p){$p.CreationDate.ToUniversalTime().ToString("O",[Globalization.CultureInfo]::InvariantCulture)} }';
+      const started = childProcess.execFileSync('powershell.exe', [
+        '-NoLogo',
+        '-NoProfile',
+        '-NonInteractive',
+        '-Command',
+        script,
+        '-ProcessId',
+        String(pid),
+      ], {
+        encoding: 'utf8',
+        windowsHide: true,
+        timeout: 3000,
+      }).trim();
+      return started
+        ? { status: 'found', identity: `win32:${started}` }
+        : { status: 'absent' };
+    } catch (error) {
+      return { status: 'error', error: identityError(error) };
+    }
+  }
+  return { status: 'error', error: `unsupported process identity platform: ${process.platform}` };
+}
+
+function matchProcessIdentity(pid, expected) {
+  const result = processIdentity(pid);
+  if (result.status !== 'found') return result;
+  return result.identity === expected
+    ? { status: 'match', identity: result.identity }
+    : { status: 'mismatch', identity: result.identity };
+}
+
+function assignLockWorker(job, worker) {
+  const lockDirectory = path.join(job.dataRoot, 'upgrades', 'active.lock');
+  const lockPath = path.join(lockDirectory, 'owner.json');
+  let owner = loadJson(lockPath);
+  if (
+    owner.jobId !== job.jobId
+    || owner.nonce !== job.lockNonce
+    || path.resolve(owner.dataRoot) !== path.resolve(job.dataRoot)
+  ) {
+    throw new Error('active upgrade lock does not belong to this job');
+  }
+  const claimPath = path.join(lockDirectory, 'handoff.claim');
+  const claimFd = fs.openSync(claimPath, 'wx', 0o600);
+  try {
+    fs.writeFileSync(claimFd, `${JSON.stringify({
+      schemaVersion: 1,
+      role: 'worker',
+      jobId: job.jobId,
+      nonce: job.lockNonce,
+      worker,
+    }, null, 2)}\n`, 'utf8');
+    fs.fsyncSync(claimFd);
+  } finally {
+    fs.closeSync(claimFd);
+  }
+  owner = loadJson(lockPath);
+  if (
+    owner.jobId !== job.jobId
+    || owner.nonce !== job.lockNonce
+    || path.resolve(owner.dataRoot) !== path.resolve(job.dataRoot)
+  ) {
+    throw new Error('active upgrade lock changed during worker handoff');
+  }
+  atomicJson(lockPath, { ...owner, worker });
+}
+
+function requestShutdown(runtime, job) {
+  const discovery = runtime.controlPlane;
+  if (
+    !discovery
+    || discovery.apiVersion !== 1
+    || discovery.host !== '127.0.0.1'
+    || !Array.isArray(discovery.capabilities)
+    || !discovery.capabilities.includes('upgrade.worker-shutdown')
+  ) {
+    return Promise.reject(new Error('old Agent does not advertise worker shutdown capability'));
+  }
+  const requestId = crypto.randomUUID();
+  const payload = JSON.stringify({
+    reason: 'worker-upgrade',
+    requestId,
+    expectedPid: job.oldRuntime.pid,
+    expectedProcessInstanceId: job.oldRuntime.processInstanceId,
+    jobId: job.jobId,
+    targetVersion: job.targetVersion,
+    lockNonce: job.lockNonce,
+    workerPid: job.worker.pid,
+    workerProcessStartIdentity: job.worker.processStartIdentity,
+  });
+  return new Promise((resolve, reject) => {
+    const request = http.request({
+      host: '127.0.0.1',
+      port: discovery.port,
+      path: '/v1/lifecycle/shutdown',
+      method: 'POST',
+      headers: {
+        Host: `127.0.0.1:${discovery.port}`,
+        Authorization: `Bearer ${discovery.token}`,
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload),
+        'X-Request-Id': requestId,
+        'Idempotency-Key': requestId,
+      },
+    }, response => {
+      const chunks = [];
+      response.on('data', chunk => chunks.push(Buffer.from(chunk)));
+      response.on('end', () => {
+        const body = Buffer.concat(chunks).toString('utf8');
+        if (response.statusCode !== 202) {
+          reject(new Error(`old Agent rejected worker shutdown (${response.statusCode}): ${body.slice(0, 256)}`));
+          return;
+        }
+        resolve();
+      });
+    });
+    request.setTimeout(5000, () => request.destroy(new Error('worker shutdown request timed out')));
+    request.on('error', reject);
+    request.end(payload);
+  });
+}
+
+async function waitForOldRuntime(job, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  let lastLookupError = null;
+  while (Date.now() < deadline) {
+    const identity = matchProcessIdentity(
+      job.oldRuntime.pid,
+      job.oldRuntime.processStartIdentity,
+    );
+    if (identity.status === 'absent' || identity.status === 'mismatch') return;
+    if (identity.status === 'error') lastLookupError = identity.error;
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  if (lastLookupError) {
+    throw new Error(`could not verify old Agent exit: ${lastLookupError}`);
+  }
+  throw new Error('old Agent exact process identity did not exit before the handoff deadline');
+}
+
+function isInside(root, candidate) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function validateSelection(job) {
+  const pointer = job.targetSelection;
+  const encoded = pointer.integrity.startsWith('sha512-')
+    ? pointer.integrity.slice('sha512-'.length)
+    : '';
+  const digest = Buffer.from(encoded, 'base64');
+  if (digest.length !== 64 || digest.toString('base64') !== encoded) {
+    throw new Error('target selection integrity is invalid');
+  }
+  const versionRoot = path.join(
+    job.dataRoot,
+    'versions',
+    `${pointer.version}-${digest.toString('hex').slice(0, 16)}`,
+  );
+  const entry = fs.realpathSync(pointer.entry);
+  const canonicalRoot = fs.realpathSync(versionRoot);
+  if (!isInside(canonicalRoot, entry) || !fs.statSync(entry).isFile()) {
+    throw new Error('target selection entry escapes its immutable version directory');
+  }
+  const marker = loadJson(path.join(canonicalRoot, '.agentlink-version.json'));
+  if (
+    marker.schemaVersion !== 1
+    || marker.version !== pointer.version
+    || marker.integrity !== pointer.integrity
+    || path.resolve(canonicalRoot, marker.entry || '') !== entry
+  ) {
+    throw new Error('target selection marker does not match');
+  }
+}
+
+function isStrictlyNewerVersion(current, target) {
+  if (!/^\d+\.\d+\.\d+$/.test(current) || !/^\d+\.\d+\.\d+$/.test(target)) {
+    throw new Error('upgrade versions must use stable major.minor.patch');
+  }
+  const currentParts = current.split('.').map(Number);
+  const targetParts = target.split('.').map(Number);
+  for (let index = 0; index < 3; index++) {
+    if (targetParts[index] !== currentParts[index]) {
+      return targetParts[index] > currentParts[index];
+    }
+  }
+  return false;
+}
+
+function selectTarget(job) {
+  const current = loadJson(path.join(job.dataRoot, 'current-version.json'));
+  if (
+    current.version !== job.sourceSelection.version
+    || current.integrity !== job.sourceSelection.integrity
+    || path.resolve(current.entry) !== path.resolve(job.sourceSelection.entry)
+  ) {
+    throw new Error('current selection changed after worker handoff');
+  }
+  if (!isStrictlyNewerVersion(current.version, job.targetSelection.version)) {
+    throw new Error(
+      `target ${job.targetSelection.version} is not newer than current ${current.version}`,
+    );
+  }
+  validateSelection(job);
+  atomicJson(path.join(job.dataRoot, 'current-version.json'), job.targetSelection);
+}
+
+function waitForSpawn(child) {
+  return new Promise((resolve, reject) => {
+    const onError = error => reject(new Error(`target launcher spawn failed: ${error.message}`));
+    child.once('error', onError);
+    child.once('spawn', () => {
+      child.removeListener('error', onError);
+      resolve();
+    });
+  });
+}
+
+async function waitForTargetRuntime(job, child, timeoutMs = 15000) {
+  const runtimePath = path.join(job.dataRoot, 'agent.json');
+  const deadline = Date.now() + timeoutMs;
+  let earlyExit = null;
+  if (child) {
+    if (child.exitCode !== null || child.signalCode) {
+      earlyExit = { code: child.exitCode, signal: child.signalCode };
+    }
+    child.once('exit', (code, signal) => {
+      earlyExit = { code, signal };
+    });
+  }
+  while (Date.now() < deadline) {
+    if (!earlyExit && child && (child.exitCode !== null || child.signalCode)) {
+      earlyExit = { code: child.exitCode, signal: child.signalCode };
+    }
+    try {
+      const runtime = loadJson(runtimePath);
+      if (
+        runtime.upgradeJobId === job.jobId
+        && Number.isSafeInteger(runtime.pid)
+        && runtime.pid > 0
+        && runtime.pid !== job.oldRuntime.pid
+      ) {
+        const lookup = processIdentity(runtime.pid);
+        if (lookup.status === 'found') return;
+        if (lookup.status === 'error') {
+          fail(`target acknowledgement identity lookup delayed: ${lookup.error}`);
+        }
+      }
+    } catch (error) {
+      if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error;
+    }
+    if (earlyExit?.signal || (earlyExit && earlyExit.code !== 0)) {
+      const status = earlyExit.signal ? `signal ${earlyExit.signal}` : `code ${earlyExit.code}`;
+      throw new Error(`target launcher exited before acknowledgement (${status})`);
+    }
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error('target runtime did not acknowledge the upgrade job before the deadline');
+}
+
+async function startTarget(job) {
+  const launcher = path.join(job.dataRoot, 'launcher', 'launcher.cjs');
+  if (!fs.statSync(launcher).isFile()) throw new Error('stable launcher is not installed');
+  const hostType = loadJson(job.launchSpecPath).host.type;
+  const env = {
+    ...process.env,
+    AGENTLINK_HOME: job.dataRoot,
+    AGENTLINK_UPGRADE_JOB: job.jobId,
+  };
+  if (hostType === 'systemd') {
+    childProcess.execFileSync('systemctl', [
+      '--user',
+      'set-environment',
+      `AGENTLINK_UPGRADE_JOB=${job.jobId}`,
+    ], { stdio: 'ignore', timeout: 5000 });
+    try {
+      childProcess.execFileSync('systemctl', ['--user', 'restart', 'agentlink.service'], {
+        stdio: 'ignore',
+        timeout: 10000,
+      });
+    } finally {
+      try {
+        childProcess.execFileSync('systemctl', [
+          '--user',
+          'unset-environment',
+          'AGENTLINK_UPGRADE_JOB',
+        ], { stdio: 'ignore', timeout: 5000 });
+      } catch (error) {
+        fail(`could not clear systemd upgrade environment: ${error.message}`);
+      }
+    }
+    await waitForTargetRuntime(job, null);
+    return;
+  }
+  if (hostType === 'launchd') {
+    const uid = process.getuid();
+    childProcess.execFileSync('launchctl', ['setenv', 'AGENTLINK_UPGRADE_JOB', job.jobId], {
+      stdio: 'ignore',
+      timeout: 5000,
+    });
+    try {
+      childProcess.execFileSync('launchctl', [
+        'kickstart',
+        '-k',
+        `gui/${uid}/com.agentlink.agent`,
+      ], { stdio: 'ignore', timeout: 10000 });
+    } finally {
+      try {
+        childProcess.execFileSync('launchctl', ['unsetenv', 'AGENTLINK_UPGRADE_JOB'], {
+          stdio: 'ignore',
+          timeout: 5000,
+        });
+      } catch (error) {
+        fail(`could not clear launchd upgrade environment: ${error.message}`);
+      }
+    }
+    await waitForTargetRuntime(job, null);
+    return;
+  }
+  const targetLog = path.join(path.dirname(job.launchSpecPath), '..', 'logs', 'upgrade-target.log');
+  fs.mkdirSync(path.dirname(targetLog), { recursive: true, mode: 0o700 });
+  const output = fs.openSync(targetLog, 'a', 0o600);
+  let child;
+  try {
+    child = childProcess.spawn(process.execPath, [
+      launcher,
+      'start',
+      '--launch-spec',
+      job.launchSpecPath,
+      '--upgrade-job',
+      job.jobId,
+    ], {
+      cwd: path.dirname(job.launchSpecPath),
+      env,
+      detached: true,
+      stdio: ['ignore', output, output],
+      windowsHide: true,
+    });
+    await waitForSpawn(child);
+  } finally {
+    fs.closeSync(output);
+  }
+  await waitForTargetRuntime(job, child);
+  child.unref();
+}
+
+function releaseLock(job, worker) {
+  const lockDirectory = path.join(job.dataRoot, 'upgrades', 'active.lock');
+  const owner = loadJson(path.join(lockDirectory, 'owner.json'));
+  const claim = loadJson(path.join(lockDirectory, 'handoff.claim'));
+  if (
+    owner.jobId !== job.jobId
+    || owner.nonce !== job.lockNonce
+    || owner.worker?.pid !== worker.pid
+    || owner.worker?.processStartIdentity !== worker.processStartIdentity
+    || claim.role !== 'worker'
+    || claim.jobId !== job.jobId
+    || claim.nonce !== job.lockNonce
+    || claim.worker?.pid !== worker.pid
+    || claim.worker?.processStartIdentity !== worker.processStartIdentity
+  ) {
+    throw new Error('cannot release an upgrade lock owned by another job');
+  }
+  const released = `${lockDirectory}.released-${job.lockNonce}`;
+  fs.renameSync(lockDirectory, released);
+  fs.rmSync(released, { recursive: true, force: true });
+}
+
+function cleanupLaunchdWorker(job) {
+  let hostType;
+  try {
+    hostType = loadJson(job.launchSpecPath).host.type;
+  } catch (error) {
+    fail(`could not determine worker host for cleanup: ${error.message}`);
+    return;
+  }
+  if (hostType !== 'launchd' || process.platform !== 'darwin') return;
+  const plistPath = path.join(path.dirname(job.launchSpecPath), '..', 'upgrades', job.jobId, 'worker.plist');
+  fs.rmSync(plistPath, { force: true });
+  const label = `com.agentlink.upgrade.${job.jobId}`;
+  try {
+    childProcess.execFileSync('launchctl', [
+      'bootout',
+      `gui/${process.getuid()}/${label}`,
+    ], { stdio: 'ignore', timeout: 5000 });
+  } catch (error) {
+    fail(`could not bootout temporary launchd worker job: ${error.message}`);
+  }
+}
+
+async function main() {
+  const jobIndex = process.argv.indexOf('--job');
+  if (jobIndex < 0 || !process.argv[jobIndex + 1]) throw new Error('missing --job path');
+  const jobPath = path.resolve(process.argv[jobIndex + 1]);
+  let job = loadJob(jobPath);
+  if (job.phase !== 'worker-starting') throw new Error(`job is not worker-starting: ${job.phase}`);
+  const identityLookup = processIdentity(process.pid);
+  if (identityLookup.status !== 'found') {
+    throw new Error(
+      `cannot determine exact updater worker process identity: `
+      + (identityLookup.error || identityLookup.status),
+    );
+  }
+  const worker = {
+    pid: process.pid,
+    processStartIdentity: identityLookup.identity,
+    protocolVersion: PROTOCOL_VERSION,
+  };
+  assignLockWorker(job, worker);
+  job = transition(jobPath, job.jobId, 'worker-ready', { worker, error: null });
+  const runtimePath = path.join(job.dataRoot, 'agent.json');
+  const runtime = loadJson(runtimePath);
+  if (
+    runtime.pid !== job.oldRuntime.pid
+    || runtime.processInstanceId !== job.oldRuntime.processInstanceId
+  ) {
+    throw new Error('runtime state no longer identifies the expected old Agent');
+  }
+  await requestShutdown(runtime, job);
+  job = transition(jobPath, job.jobId, 'shutdown-requested');
+  await waitForOldRuntime(job);
+  job = transition(jobPath, job.jobId, 'old-agent-stopped');
+  job = transition(jobPath, job.jobId, 'switching');
+  selectTarget(job);
+  job = transition(jobPath, job.jobId, 'target-starting');
+  await startTarget(job);
+  job = transition(jobPath, job.jobId, 'target-started');
+  releaseLock(job, worker);
+  cleanupLaunchdWorker(job);
+}
+
+main().catch(error => {
+  fail(error.stack || error.message || String(error));
+  let failedJob = null;
+  try {
+    const jobIndex = process.argv.indexOf('--job');
+    const jobPath = jobIndex >= 0 ? path.resolve(process.argv[jobIndex + 1]) : null;
+    if (jobPath) {
+      failedJob = loadJob(jobPath);
+      if (failedJob.phase !== 'target-started' && failedJob.phase !== 'failed') {
+        failedJob = transition(jobPath, failedJob.jobId, 'failed', {
+          error: String(error.message || error).slice(0, 512),
+        });
+      }
+    }
+  } catch (recordError) {
+    fail(`could not persist worker failure: ${recordError.message}`);
+  }
+  if (failedJob?.worker) {
+    try {
+      releaseLock(failedJob, failedJob.worker);
+    } catch (releaseError) {
+      fail(`could not release failed worker lock: ${releaseError.message}`);
+    }
+  }
+  if (failedJob) cleanupLaunchdWorker(failedJob);
+  process.exitCode = 1;
+});