@forgezero/agent 0.1.25 → 0.1.27

package/README.md

@@ -130,7 +130,8 @@ pipeline result; no polling service or persistent queue is required.
 The daemon owns source checkout and command execution. Bootstrap explicitly
 awaits release one because the API does not exist yet, then the Agent consumes a
 one-use platform enrolment capability. There is no branch watcher. Every normal
-platform or tenant release is a durable API row bound to one exact compute:
+platform or tenant release is one durable API delivery atomically expanded to
+one row for every explicit compute binding:
 `pending` is written before dispatch, `running` and a fenced lease before project
 code, and only an awaited successful pipeline writes `deployed`. An expired
 claim can be recovered; its stale token cannot renew or finish.

package/dist/agent-heartbeat.d.ts

@@ -0,0 +1,45 @@
+import type { NodeKeyPair } from '@forgezero/runtime/identity';
+import { type AgentRelease } from './agent-update';
+import { type AgentUpdateResponse } from './agent-update-helper';
+export interface AgentObservation {
+    version: string;
+    os: {
+        id: string;
+        versionId: string;
+    };
+    architecture: string;
+    mode: 'attested' | 'enrolled';
+}
+export interface AgentHeartbeatResponse {
+    ok: true;
+    nodeKey: string;
+    intervalSeconds: number;
+    desiredAgentRelease?: AgentRelease;
+}
+export interface AgentHeartbeatOptions {
+    apiUrl: string;
+    nodeKey: string;
+    keys: NodeKeyPair;
+    mode: AgentObservation['mode'];
+    updateTarget?: 'compute' | 'metal';
+    version?: string;
+    fetch?: (input: URL, init: RequestInit) => Promise<Response>;
+    requestTimeoutMs?: number;
+    observation?: () => AgentObservation;
+    /** Stop new lifecycle/deploy claims and await current jobs before replacement. */
+    prepareUpdate?: (release: AgentRelease) => Promise<void>;
+    /** Restart the drained current process if staging is refused before activation. */
+    recoverUpdate?: (cause: unknown) => Promise<void> | void;
+    applyUpdate?: (release: AgentRelease, currentVersion: string) => Promise<AgentUpdateResponse>;
+    setTimer?: (callback: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+    onEvent?: (event: string, detail?: unknown) => void;
+}
+export declare function observeAgentHost(version?: string, mode?: AgentObservation['mode'], osRelease?: string, architecture?: NodeJS.Architecture): AgentObservation;
+/** One PQ-authenticated observation and optional supervised update decision. */
+export declare function heartbeatAgentOnce(options: AgentHeartbeatOptions): Promise<AgentHeartbeatResponse>;
+/** Server-paced heartbeat; stopping waits for the active PQ request/update handoff. */
+export declare function startAgentHeartbeat(options: AgentHeartbeatOptions): {
+    stop(): Promise<void>;
+    readonly active: boolean;
+};

package/dist/agent-heartbeat.js

@@ -0,0 +1,498 @@
+// src/agent-update.ts
+import { createHash, timingSafeEqual, randomUUID } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+var DEFAULT_AGENT_RELEASE_ROOT = "/opt/forgezero/agent";
+var DEFAULT_AGENT_UPDATE_SOCKET = "/run/forgezero-update/helper.sock";
+var MAX_AGENT_TARBALL_BYTES = 32 * 1024 * 1024;
+var VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+var REGISTRY = "registry.npmjs.org";
+function validateAgentRelease(release) {
+  if (release?.package !== "@forgezero/agent")
+    throw new Error("agent update package is fixed");
+  if (!VERSION.test(release.version))
+    throw new Error("agent update version must be exact semver");
+  const expectedTarball = `/@forgezero/agent/-/agent-${release.version}.tgz`;
+  let url;
+  try {
+    url = new URL(release.tarball);
+  } catch {
+    throw new Error("agent update tarball URL is malformed");
+  }
+  if (url.protocol !== "https:" || url.hostname !== REGISTRY || url.port || url.username || url.password || url.search || url.hash || url.pathname !== expectedTarball)
+    throw new Error("agent update tarball must be the exact official npm artifact");
+  const match = /^sha512-([A-Za-z0-9+/]+={0,2})$/.exec(release.integrity);
+  if (!match || Buffer.from(match[1], "base64").length !== 64) {
+    throw new Error("agent update requires one sha512 npm integrity");
+  }
+  return release;
+}
+function compareVersions(left, right) {
+  if (!VERSION.test(left) || !VERSION.test(right))
+    throw new Error("agent version must be exact semver");
+  const a = left.split(".").map(Number);
+  const b = right.split(".").map(Number);
+  for (let index = 0;index < 3; index += 1) {
+    if (a[index] > b[index])
+      return 1;
+    if (a[index] < b[index])
+      return -1;
+  }
+  return 0;
+}
+var command = async (input) => {
+  const child = Bun.spawn([input.command, ...input.args], {
+    cwd: input.cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  return { exitCode, output: `${stdout}${stderr}` };
+};
+var checked = async (run, input, label) => {
+  const result = await run(input);
+  if (result.exitCode !== 0)
+    throw new Error(`${label} failed: ${result.output.trim()}`);
+  return result;
+};
+async function validateReleaseDirectory(directory, release, run) {
+  const manifest = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+  if (manifest.name !== release.package || manifest.version !== release.version) {
+    throw new Error("agent update manifest does not match the selected release");
+  }
+  const agent = join(directory, "dist", "fz-agent.js");
+  const cli = join(directory, "dist", "fz.js");
+  for (const binary of [agent, cli]) {
+    if (!readFileSync(binary, "utf8").startsWith(`#!/usr/bin/env bun
+`)) {
+      throw new Error("agent update artifact is not a self-contained Bun executable");
+    }
+    chmodSync(binary, 493);
+  }
+  const version = (await checked(run, { command: agent, args: ["--version"] }, "agent update smoke test")).output.trim();
+  if (version !== release.version)
+    throw new Error(`agent update binary reports ${version}`);
+}
+async function stageAgentRelease(releaseInput, options) {
+  const release = validateAgentRelease(releaseInput);
+  if (compareVersions(release.version, options.currentVersion) <= 0) {
+    throw new Error(`agent update ${release.version} is not newer than ${options.currentVersion}`);
+  }
+  const root = resolve(options.root ?? DEFAULT_AGENT_RELEASE_ROOT);
+  const versions = join(root, "versions");
+  const finalDirectory = join(versions, release.version);
+  const currentLink = join(root, "current");
+  const stage = join(versions, `.${release.version}.${randomUUID()}.staging`);
+  const archive = join(stage, "agent.tgz");
+  const unpacked = join(stage, "unpacked");
+  const run = options.run ?? command;
+  mkdirSync(unpacked, { recursive: true, mode: 448 });
+  try {
+    const response = await (options.fetch ?? globalThis.fetch)(release.tarball, {
+      redirect: "error",
+      signal: AbortSignal.timeout(30000)
+    });
+    if (!response.ok)
+      throw new Error(`npm returned HTTP ${response.status}`);
+    const declared = Number(response.headers.get("content-length") ?? "0");
+    if (declared > MAX_AGENT_TARBALL_BYTES)
+      throw new Error("agent update tarball exceeds the size limit");
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.length === 0 || bytes.length > MAX_AGENT_TARBALL_BYTES) {
+      throw new Error("agent update tarball is empty or exceeds the size limit");
+    }
+    const expected = Buffer.from(release.integrity.slice("sha512-".length), "base64");
+    const actual = createHash("sha512").update(bytes).digest();
+    if (!timingSafeEqual(actual, expected))
+      throw new Error("agent update integrity mismatch");
+    writeFileSync(archive, bytes, { mode: 384, flag: "wx" });
+    await checked(run, {
+      command: "/usr/bin/tar",
+      args: [
+        "-xzf",
+        archive,
+        "-C",
+        unpacked,
+        "--strip-components=1",
+        "package/package.json",
+        "package/dist/fz-agent.js",
+        "package/dist/fz.js"
+      ]
+    }, "agent update extraction");
+    await validateReleaseDirectory(unpacked, release, run);
+    if (!existsSync(finalDirectory))
+      renameSync(unpacked, finalDirectory);
+    else
+      await validateReleaseDirectory(finalDirectory, release, run);
+    if (!existsSync(currentLink)) {
+      throw new Error("agent update requires an active immutable release to roll back to");
+    }
+    const previousTarget = readlinkSync(currentLink);
+    return {
+      version: release.version,
+      directory: finalDirectory,
+      previousTarget,
+      nextTarget: join("versions", release.version),
+      currentLink
+    };
+  } finally {
+    rmSync(stage, { recursive: true, force: true });
+  }
+}
+function selectAgentRelease(staged) {
+  const next = join(dirname(staged.currentLink), `.current.${randomUUID()}.next`);
+  try {
+    symlinkSync(staged.nextTarget, next);
+    renameSync(next, staged.currentLink);
+  } finally {
+    rmSync(next, { force: true });
+  }
+}
+function restoreAgentRelease(staged) {
+  const next = join(dirname(staged.currentLink), `.current.${randomUUID()}.rollback`);
+  try {
+    symlinkSync(staged.previousTarget, next);
+    renameSync(next, staged.currentLink);
+  } finally {
+    rmSync(next, { force: true });
+  }
+}
+
+// src/agent-update-helper.ts
+import { chmodSync as chmodSync2, existsSync as existsSync2, mkdirSync as mkdirSync2, renameSync as renameSync2, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { connect, createServer } from "node:net";
+import { dirname as dirname2 } from "node:path";
+import { DEFAULT_SOCKET } from "@forgezero/vault";
+var AGENT_UPDATE_GROUP = "forgezero-update";
+var AGENT_UPDATE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-agent-update-helper.service";
+var AGENT_UPDATE_RECEIPT = "/var/lib/forgezero/agent-update.json";
+var MAX_REQUEST_BYTES = 8 * 1024;
+var COMPUTE_HELPER_UNITS = [
+  "forgezero-deploy-runner.service",
+  "forgezero-lifecycle-helper.service",
+  "forgezero-software-helper.service"
+];
+var runCommand = async (input) => {
+  const child = Bun.spawn([input.command, ...input.args], {
+    cwd: input.cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" }
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]);
+  return { exitCode, output: `${stdout}${stderr}` };
+};
+var runOk = async (run, command2, args) => (await run({ command: command2, args })).exitCode === 0;
+function probeAgentSocket(socketPath = DEFAULT_SOCKET, timeoutMs = 5000) {
+  return new Promise((resolve2) => {
+    const socket = connect(socketPath);
+    let settled = false;
+    let buffer = "";
+    const finish = (value) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve2(value);
+    };
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    socket.on("connect", () => socket.write(`{"op":"identity"}
+`));
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      try {
+        const response = JSON.parse(buffer.slice(0, newline));
+        finish(response.ok === false && response.error?.code === "APP_OPERATION_REFUSED");
+      } catch {
+        finish(false);
+      }
+    });
+    socket.on("error", () => finish(false));
+  });
+}
+async function activateAgentRelease(staged, options = {}) {
+  const run = options.run ?? runCommand;
+  const target = options.target ?? "compute";
+  const probe = options.probe ?? (target === "compute" ? () => probeAgentSocket() : async () => await runOk(run, "/usr/bin/systemctl", ["is-active", "--quiet", "forgezero-metal-agent.service"]) && await runOk(run, "/usr/bin/systemctl", ["is-active", "--quiet", "forgezero-metal-helper.service"]));
+  const restart = async () => {
+    const helpers = target === "compute" ? COMPUTE_HELPER_UNITS : ["forgezero-metal-helper.service"];
+    for (const unit of helpers) {
+      await run({ command: "/usr/bin/systemctl", args: ["try-restart", unit] });
+    }
+    const service = target === "compute" ? "forgezero-agent.service" : "forgezero-metal-agent.service";
+    const restarted = await runOk(run, "/usr/bin/systemctl", ["restart", service]);
+    if (!restarted)
+      throw new Error(`systemd could not restart ${service}`);
+  };
+  let selected = false;
+  try {
+    selectAgentRelease(staged);
+    selected = true;
+    await restart();
+    if (!await probe())
+      throw new Error("the replacement Agent did not answer its retained Vault socket");
+    const receipt = options.receiptPath ?? AGENT_UPDATE_RECEIPT;
+    mkdirSync2(dirname2(receipt), { recursive: true, mode: 493 });
+    const next = `${receipt}.next`;
+    writeFileSync2(next, JSON.stringify({
+      version: staged.version,
+      outcome: "active",
+      updatedAtTs: (options.now ?? Date.now)()
+    }) + `
+`, { mode: 420 });
+    renameSync2(next, receipt);
+    run({
+      command: "/usr/bin/systemctl",
+      args: ["try-restart", "--no-block", "forgezero-agent-update-helper.service"]
+    });
+    return { ok: true, version: staged.version };
+  } catch (cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    if (selected) {
+      restoreAgentRelease(staged);
+      await restart();
+    }
+    return { ok: false, rolledBack: selected, reason };
+  }
+}
+function startAgentUpdateHelper(options = {}) {
+  const socketPath = options.socketPath ?? DEFAULT_AGENT_UPDATE_SOCKET;
+  if (existsSync2(socketPath))
+    unlinkSync(socketPath);
+  mkdirSync2(dirname2(socketPath), { recursive: true, mode: 488 });
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const activate = options.activate ?? ((staged, target) => activateAgentRelease(staged, { target }));
+  const server = createServer((socket) => {
+    let buffer = "";
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      if (Buffer.byteLength(buffer) > MAX_REQUEST_BYTES) {
+        socket.end(`${JSON.stringify({ ok: false, error: { code: "TOO_LARGE", message: "update request too large" } })}
+`);
+        return;
+      }
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      const line = buffer.slice(0, newline);
+      buffer = "";
+      Promise.resolve().then(() => JSON.parse(line)).then(async (request) => {
+        if (request.op !== "apply")
+          throw new Error("unknown update operation");
+        if (request.target !== "compute" && request.target !== "metal") {
+          throw new Error("agent update target is invalid");
+        }
+        const staged = await stageAgentRelease(request.release, {
+          currentVersion: request.currentVersion,
+          root: options.root ?? DEFAULT_AGENT_RELEASE_ROOT
+        });
+        const response = { ok: true, status: "staged", version: staged.version };
+        socket.end(`${JSON.stringify(response)}
+`, () => {
+          setTimer(() => void activate(staged, request.target), 100);
+        });
+      }).catch((cause) => {
+        const response = {
+          ok: false,
+          error: { code: "UPDATE_REFUSED", message: cause instanceof Error ? cause.message : String(cause) }
+        };
+        socket.end(`${JSON.stringify(response)}
+`);
+      });
+    });
+    socket.on("error", () => socket.destroy());
+  });
+  server.listen(socketPath, () => chmodSync2(socketPath, 432));
+  return server;
+}
+function requestAgentUpdate(request, socketPath = DEFAULT_AGENT_UPDATE_SOCKET, timeoutMs = 90000) {
+  return new Promise((resolve2, reject) => {
+    const socket = connect(socketPath, () => socket.write(`${JSON.stringify(request)}
+`));
+    let buffer = "";
+    socket.setTimeout(timeoutMs, () => {
+      socket.destroy();
+      reject(new Error("agent update helper did not answer before its deadline"));
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const newline = buffer.indexOf(`
+`);
+      if (newline < 0)
+        return;
+      socket.end();
+      try {
+        resolve2(JSON.parse(buffer.slice(0, newline)));
+      } catch (cause) {
+        reject(cause);
+      }
+    });
+    socket.on("error", reject);
+  });
+}
+
+// src/agent-heartbeat.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+
+// src/signed-node-http.ts
+import {
+  encodeSignatureHeader,
+  generateResponseRecipient,
+  openResponse,
+  RESPONSE_KEY_HEADER,
+  signRequest
+} from "@forgezero/runtime/identity";
+
+class SignedNodeHttpError extends Error {
+  status;
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "SignedNodeHttpError";
+  }
+}
+async function postSignedNode(options, path, body) {
+  const url = new URL(options.apiUrl);
+  url.pathname = `${url.pathname.replace(/\/$/, "")}/${path.replace(/^\//, "")}`.replace(/\/+/g, "/");
+  url.search = "";
+  url.hash = "";
+  const raw = JSON.stringify(body);
+  const recipient = generateResponseRecipient();
+  const envelope = signRequest(options.keys, options.nodeKey, {
+    method: "POST",
+    path: url.pathname,
+    query: "",
+    body: raw,
+    responseKey: recipient.publicKey
+  });
+  const signature = encodeSignatureHeader(envelope);
+  const response = await (options.fetch ?? globalThis.fetch)(url, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-fz-node": options.nodeKey,
+      "x-fz-signature": signature,
+      [RESPONSE_KEY_HEADER]: recipient.publicKey
+    },
+    body: raw,
+    signal: AbortSignal.timeout(options.requestTimeoutMs ?? 15000)
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) {
+    const failure = payload;
+    const reason = failure ? failure.error?.message ?? failure.message : undefined;
+    throw new SignedNodeHttpError(response.status, reason || `signed node request returned HTTP ${response.status}`);
+  }
+  try {
+    return await openResponse(recipient.secretKey, signature, payload);
+  } catch {
+    throw new SignedNodeHttpError(502, "The node response was not sealed to this request.");
+  }
+}
+
+// src/version.ts
+var VERSION2 = "0.1.27";
+
+// src/agent-heartbeat.ts
+var unquote = (value) => value.replace(/^['"]|['"]$/g, "");
+function observeAgentHost(version = VERSION2, mode = "enrolled", osRelease = readFileSync2("/etc/os-release", "utf8"), architecture = process.arch) {
+  const values = Object.fromEntries(osRelease.split(`
+`).flatMap((line) => {
+    const separator = line.indexOf("=");
+    return separator > 0 ? [[line.slice(0, separator), unquote(line.slice(separator + 1))]] : [];
+  }));
+  return {
+    version,
+    os: { id: (values.ID ?? "unknown").toLowerCase(), versionId: values.VERSION_ID ?? "unknown" },
+    architecture,
+    mode
+  };
+}
+async function heartbeatAgentOnce(options) {
+  const observation = (options.observation ?? (() => observeAgentHost(options.version ?? VERSION2, options.mode)))();
+  const response = await postSignedNode(options, "v1/node/heartbeat", observation);
+  if (response.desiredAgentRelease) {
+    const release = validateAgentRelease(response.desiredAgentRelease);
+    if (compareVersions(release.version, observation.version) > 0) {
+      let prepared = false;
+      try {
+        await options.prepareUpdate?.(release);
+        prepared = true;
+        const applied = await (options.applyUpdate ?? ((next, current) => requestAgentUpdate({
+          op: "apply",
+          target: options.updateTarget ?? "compute",
+          release: next,
+          currentVersion: current
+        })))(release, observation.version);
+        if (!applied.ok)
+          throw new Error(`agent update refused: ${applied.error.message}`);
+        options.onEvent?.("update-staged", { from: observation.version, to: release.version });
+      } catch (cause) {
+        if (prepared)
+          await options.recoverUpdate?.(cause);
+        throw cause;
+      }
+    }
+  }
+  return response;
+}
+function startAgentHeartbeat(options) {
+  const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+  const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+  let stopped = false;
+  let timer;
+  let active = null;
+  const tick = () => {
+    if (stopped || active)
+      return;
+    let nextSeconds = 30;
+    active = heartbeatAgentOnce(options).then((response) => {
+      nextSeconds = Math.max(5, Math.min(response.intervalSeconds, 300));
+    }).catch((cause) => options.onEvent?.("heartbeat-failed", cause)).finally(() => {
+      active = null;
+      if (!stopped)
+        timer = setTimer(tick, nextSeconds * 1000);
+    });
+  };
+  tick();
+  return {
+    async stop() {
+      stopped = true;
+      clearTimer(timer);
+      await active;
+    },
+    get active() {
+      return !stopped;
+    }
+  };
+}
+export {
+  startAgentHeartbeat,
+  observeAgentHost,
+  heartbeatAgentOnce
+};

package/dist/agent-update-helper.d.ts

@@ -0,0 +1,45 @@
+import { type Server } from 'node:net';
+import { type AgentRelease, type StagedAgentRelease, type UpdateCommand, type UpdateCommandResult } from './agent-update';
+export declare const AGENT_UPDATE_GROUP = "forgezero-update";
+export declare const AGENT_UPDATE_HELPER_UNIT_PATH = "/etc/systemd/system/forgezero-agent-update-helper.service";
+export declare const AGENT_UPDATE_RECEIPT = "/var/lib/forgezero/agent-update.json";
+export type AgentUpdateRequest = {
+    op: 'apply';
+    target: 'compute' | 'metal';
+    currentVersion: string;
+    release: AgentRelease;
+};
+export type AgentUpdateResponse = {
+    ok: true;
+    status: 'staged';
+    version: string;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/** Prove a newly started Agent process answers, not merely that PID 1 holds its socket. */
+export declare function probeAgentSocket(socketPath?: string, timeoutMs?: number): Promise<boolean>;
+export declare function activateAgentRelease(staged: StagedAgentRelease, options?: {
+    target?: AgentUpdateRequest['target'];
+    run?: (input: UpdateCommand) => Promise<UpdateCommandResult>;
+    probe?: () => Promise<boolean>;
+    receiptPath?: string;
+    now?: () => number;
+}): Promise<{
+    ok: true;
+    version: string;
+} | {
+    ok: false;
+    rolledBack: boolean;
+    reason: string;
+}>;
+export declare function startAgentUpdateHelper(options?: {
+    socketPath?: string;
+    root?: string;
+    activate?: (staged: StagedAgentRelease, target: AgentUpdateRequest['target']) => Promise<unknown>;
+    setTimer?: (callback: () => void, ms: number) => unknown;
+}): Server;
+export declare function requestAgentUpdate(request: AgentUpdateRequest, socketPath?: string, timeoutMs?: number): Promise<AgentUpdateResponse>;