@agent-compose/sdk 0.8.1 → 0.8.3

package/src/agent/services-restore.ts

@@ -0,0 +1,195 @@
+/**
+ * Restore-script generation for the durable services manifest.
+ *
+ * Pure string composition — nothing here touches a sandbox (the desktop-open
+ * posture). The server's fresh-boot ensure and `agentc services restore` both
+ * feed a parsed manifest through these generators, so the launch semantics are
+ * one implementation:
+ *
+ *   - every service is launched DETACHED (`setsid sh -c … </dev/null &`) with a
+ *     durable log and pidfile under /tmp/ac-services/ — the same contract the
+ *     background-work doctrine teaches, so a restored service freezes while the
+ *     machine parks and resumes on wake exactly like an agent-launched job;
+ *   - `setup` and `data.restore` run first, sequentially, in the service's cwd;
+ *   - health is gated with a bounded poll, never an unbounded wait;
+ *   - every outcome is reported as a machine-readable status line
+ *     (`##ac-service <name> <ok|unchecked|failed|dumped|dump-failed> [detail]`)
+ *     — per-service honesty, never a fatal abort of the whole restore.
+ *
+ * The generated script is POSIX sh, installed via base64 + `sh -n` (the
+ * desktop-open install idiom) so a syntax regression fails loudly at install
+ * time, not silently at boot.
+ */
+
+import type { ServiceEntry, ServicesManifest } from "./services-manifest.js";
+
+/** Durable per-service logs + pidfiles live here (machine-local, recreated each boot). */
+export const SERVICES_STATE_DIR = "/tmp/ac-services";
+
+/** Marker prefix for machine-readable per-service outcome lines. */
+export const SERVICE_STATUS_PREFIX = "##ac-service";
+
+/** Bound on each service's health poll (1s beats). */
+export const SERVICE_HEALTH_TIMEOUT_S = 45;
+
+export type ServiceRestoreStatus = "ok" | "unchecked" | "failed" | "dumped" | "dump-failed";
+
+export interface ServiceRestoreOutcome {
+  name: string;
+  status: ServiceRestoreStatus;
+  detail?: string;
+}
+
+/** POSIX single-quote escaping: ' → '\'' */
+function shq(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+/** `sh -c <cmd>` fragment with the command safely single-quoted. */
+function shc(cmd: string): string {
+  return `sh -c ${shq(cmd)}`;
+}
+
+function serviceCwd(driveRoot: string, svc: ServiceEntry): string {
+  return svc.cwd ? `${driveRoot.replace(/\/+$/, "")}/${svc.cwd}` : driveRoot;
+}
+
+function restoreOneService(driveRoot: string, svc: ServiceEntry): string[] {
+  const n = svc.name;
+  const cwd = serviceCwd(driveRoot, svc);
+  const lines: string[] = [
+    ``,
+    `# --- ${n} ---`,
+    `(`,
+    `  cd ${shq(cwd)} || { status ${shq(n)} failed cwd-missing; exit 0; }`,
+  ];
+  if (svc.setup) {
+    lines.push(
+      `  if ! ${shc(svc.setup)} >> "$D/${n}.setup.log" 2>&1; then`,
+      `    status ${shq(n)} failed setup; exit 0`,
+      `  fi`,
+    );
+  }
+  if (svc.data?.restore) {
+    lines.push(
+      `  if ! ${shc(svc.data.restore)} >> "$D/${n}.setup.log" 2>&1; then`,
+      `    status ${shq(n)} failed data-restore; exit 0`,
+      `  fi`,
+    );
+  }
+  lines.push(
+    `  $SETSID ${shc(svc.command)} >> "$D/${n}.log" 2>&1 < /dev/null &`,
+    `  echo $! > "$D/${n}.pid"`,
+  );
+  const health = svc.health?.cmd
+    ? shc(svc.health.cmd)
+    : svc.health?.http
+      ? `curl -fsS -m 2 -o /dev/null ${shq(svc.health.http)}`
+      : null;
+  if (health) {
+    lines.push(
+      `  i=0`,
+      `  while [ "$i" -lt ${SERVICE_HEALTH_TIMEOUT_S} ]; do`,
+      `    if ${health} >/dev/null 2>&1; then status ${shq(n)} ok ''; exit 0; fi`,
+      `    kill -0 "$(cat "$D/${n}.pid")" 2>/dev/null || { status ${shq(n)} failed exited; exit 0; }`,
+      `    i=$((i+1)); sleep 1`,
+      `  done`,
+      `  status ${shq(n)} failed health-timeout`,
+    );
+  } else {
+    lines.push(
+      `  sleep 1`,
+      `  if kill -0 "$(cat "$D/${n}.pid")" 2>/dev/null; then status ${shq(n)} unchecked ''; else status ${shq(n)} failed exited; fi`,
+    );
+  }
+  lines.push(`)`);
+  return lines;
+}
+
+/**
+ * The auto-restore script: sequential, per-service honest, never exits nonzero
+ * because one service failed (the caller reads status lines, not the exit code).
+ *
+ * @param driveRoot absolute session working dir (the drive root, e.g. /factory/files)
+ */
+export function servicesRestoreScript(manifest: ServicesManifest, driveRoot: string): string {
+  const head = [
+    `#!/bin/sh`,
+    `# generated by agent-compose — restores services from ${driveRoot}/.ac/services.yml`,
+    `# logs + pidfiles: ${SERVICES_STATE_DIR}/<name>.{log,pid}`,
+    `D=${shq(SERVICES_STATE_DIR)}`,
+    `mkdir -p "$D"`,
+    `status() { printf '%s %s %s %s\\n' ${shq(SERVICE_STATUS_PREFIX)} "$1" "$2" "$3"; }`,
+    `# setsid detaches from the boot shell's session (Linux guests); on hosts`,
+    `# without it (macOS running \`agentc services restore\`) plain & still works.`,
+    `SETSID=""`,
+    `command -v setsid >/dev/null 2>&1 && SETSID=setsid`,
+  ];
+  const body = manifest.services.flatMap((svc) => restoreOneService(driveRoot, svc));
+  return [...head, ...body, ``].join("\n");
+}
+
+/**
+ * The pre-recycle dump script: runs each service's `data.dump` hook in its cwd,
+ * bounded by the caller's command timeout. Only DELIBERATE recycles (resize)
+ * get to run this — an evicted or dead machine cannot.
+ */
+export function servicesDumpScript(manifest: ServicesManifest, driveRoot: string): string | null {
+  const withDump = manifest.services.filter((svc) => svc.data?.dump);
+  if (withDump.length === 0) return null;
+  const lines = [
+    `#!/bin/sh`,
+    `# generated by agent-compose — pre-recycle data dumps from .ac/services.yml`,
+    `status() { printf '%s %s %s %s\\n' ${shq(SERVICE_STATUS_PREFIX)} "$1" "$2" "$3"; }`,
+  ];
+  for (const svc of withDump) {
+    const cwd = serviceCwd(driveRoot, svc);
+    lines.push(
+      ``,
+      `# --- ${svc.name} ---`,
+      `(`,
+      `  cd ${shq(cwd)} || { status ${shq(svc.name)} dump-failed cwd-missing; exit 0; }`,
+      `  if ${shc(svc.data!.dump!)} > /dev/null 2>&1; then`,
+      `    status ${shq(svc.name)} dumped ''`,
+      `  else`,
+      `    status ${shq(svc.name)} dump-failed ''`,
+      `  fi`,
+      `)`,
+    );
+  }
+  lines.push(``);
+  return lines.join("\n");
+}
+
+/**
+ * Parse the status lines out of a restore/dump run's stdout. Non-status lines
+ * are ignored; malformed status lines are dropped rather than guessed at.
+ */
+export function parseServicesRestoreOutput(stdout: string): ServiceRestoreOutcome[] {
+  const out: ServiceRestoreOutcome[] = [];
+  for (const raw of stdout.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line.startsWith(`${SERVICE_STATUS_PREFIX} `)) continue;
+    const rest = line.slice(SERVICE_STATUS_PREFIX.length + 1).trim();
+    const [name, status, ...detail] = rest.split(/\s+/);
+    if (!name || !status) continue;
+    if (!["ok", "unchecked", "failed", "dumped", "dump-failed"].includes(status)) continue;
+    const d = detail.join(" ").trim();
+    out.push({ name, status: status as ServiceRestoreStatus, ...(d ? { detail: d } : {}) });
+  }
+  return out;
+}
+
+/**
+ * One human line for the conversation notice, e.g.
+ * `postgres ✓ redis ✓ web ✗ (health-timeout — see /tmp/ac-services/web.log)`.
+ */
+export function formatServicesRestoreSummary(outcomes: ServiceRestoreOutcome[]): string {
+  return outcomes
+    .map((o) => {
+      if (o.status === "ok" || o.status === "unchecked" || o.status === "dumped") return `${o.name} ✓`;
+      const why = o.detail ? `${o.detail} — see ${SERVICES_STATE_DIR}/${o.name}.log` : `see ${SERVICES_STATE_DIR}/${o.name}.log`;
+      return `${o.name} ✗ (${why})`;
+    })
+    .join(" ");
+}