@agent-compose/sdk 0.8.2 → 0.8.4

package/src/agent/services-manifest.ts

@@ -0,0 +1,356 @@
+/**
+ * The durable services manifest — `.ac/services.yml` on the session's drive
+ * branch.
+ *
+ * Sessions run on cattle machines: a VM recycle (resize, eviction, failed
+ * reconnect) discards every process and every byte off the drive. The manifest
+ * is the pet — a small, versioned description of the long-running services a
+ * session depends on (dev servers, docker compose stacks, built dashboards) so
+ * the platform can rebuild the stack on a fresh machine without being asked.
+ *
+ * This module is pure string/data work: a parser for a deliberately RESTRICTED
+ * YAML subset (no yaml dependency — the schema is small and fixed, and a
+ * hand-rolled parser matches house style, cf. parseRecorderStatus /
+ * parsePerfToken), a serializer the CLI uses for `agentc services add/remove`,
+ * and the shared types. Script generation lives in ./services-restore.ts.
+ *
+ * Supported YAML subset (anything else is a loud parse error, never a guess):
+ *
+ *   version: 1
+ *   services:
+ *     - name: postgres
+ *       command: docker compose up postgres     # required, foreground shell
+ *       cwd: myapp                              # optional, relative to drive root
+ *       port: 5432                              # optional, informational + docs
+ *       env: reads DATABASE_URL from .env       # optional free-text note
+ *       setup: docker compose pull postgres     # optional one-time prep per machine
+ *       health:                                 # optional, at most one of:
+ *         cmd: pg_isready -h localhost          #   shell probe (exit 0 = healthy)
+ *         http: http://localhost:5432/          #   or an HTTP 2xx probe
+ *       data:                                   # optional data hooks
+ *         dump: pg_dump app > .ac/seeds/dev.sql     # before a DELIBERATE recycle
+ *         restore: psql app < .ac/seeds/dev.sql     # after setup on a fresh boot
+ *
+ * Scalars only, one nesting level (`health:` / `data:`), full-line `#` comments
+ * only (an inline ` # ...` would be ambiguous inside shell commands and is kept
+ * as part of the value), no multi-line block scalars (`|` / `>`), no anchors,
+ * no flow collections.
+ */
+
+export const SERVICES_MANIFEST_RELPATH = ".ac/services.yml";
+
+/** Hard cap on manifest entries — a manifest is a stack, not a fleet. */
+export const SERVICES_MAX = 16;
+
+export const SERVICE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,31}$/;
+
+export interface ServiceHealth {
+  /** Shell probe; exit 0 means healthy. Mutually exclusive with `http`. */
+  cmd?: string;
+  /** HTTP probe; any 2xx means healthy. Mutually exclusive with `cmd`. */
+  http?: string;
+}
+
+export interface ServiceDataHooks {
+  /**
+   * Run before a DELIBERATE recycle (resize). Evictions and dead-VM
+   * fresh-acquires cannot run it — the machine is already gone — so dumps are
+   * a courtesy, not a guarantee; durable data belongs on the drive.
+   */
+  dump?: string;
+  /** Run after `setup` on a fresh boot, before the service launches. */
+  restore?: string;
+}
+
+export interface ServiceEntry {
+  name: string;
+  /** Foreground shell command; launched detached with durable log + pidfile. */
+  command: string;
+  /** Working directory, relative to the drive root (absolute rejected). */
+  cwd?: string;
+  /** Informational — surfaced in `agentc services list` and the restore line. */
+  port?: number;
+  /** Free-text note about env the service expects (documentation only). */
+  env?: string;
+  /** One-time per-machine prep (e.g. `docker compose up -d`). */
+  setup?: string;
+  health?: ServiceHealth;
+  data?: ServiceDataHooks;
+}
+
+export interface ServicesManifest {
+  version: 1;
+  services: ServiceEntry[];
+}
+
+export interface ParseServicesManifestResult {
+  /** Present iff `errors` is empty. All-or-nothing: a broken manifest restores nothing, loudly. */
+  manifest: ServicesManifest | null;
+  errors: string[];
+}
+
+const TOP_KEYS = new Set(["version", "services"]);
+const ENTRY_KEYS = new Set(["name", "command", "cwd", "port", "env", "setup", "health", "data"]);
+const HEALTH_KEYS = new Set(["cmd", "http"]);
+const DATA_KEYS = new Set(["dump", "restore"]);
+
+interface Line {
+  no: number;
+  indent: number;
+  /** True when the content starts with `- ` (a sequence item). */
+  dash: boolean;
+  /** Content with indentation (and any leading `- `) stripped. */
+  text: string;
+}
+
+function lex(text: string): Line[] {
+  const out: Line[] = [];
+  const raw = text.split(/\r?\n/);
+  for (let i = 0; i < raw.length; i++) {
+    const line = raw[i];
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const indent = line.length - line.trimStart().length;
+    const dash = trimmed.startsWith("- ") || trimmed === "-";
+    out.push({
+      no: i + 1,
+      indent,
+      dash,
+      text: dash ? trimmed.slice(1).trim() : trimmed,
+    });
+  }
+  return out;
+}
+
+/** Split `key: value` (value may be empty for map openers). Null when the line is not a mapping. */
+function splitKey(text: string): { key: string; value: string } | null {
+  if (text.endsWith(":") && !text.includes(": ")) {
+    const key = text.slice(0, -1).trim();
+    return /^[A-Za-z_][\w-]*$/.test(key) ? { key, value: "" } : null;
+  }
+  const idx = text.indexOf(": ");
+  if (idx === -1) return null;
+  const key = text.slice(0, idx).trim();
+  if (!/^[A-Za-z_][\w-]*$/.test(key)) return null;
+  return { key, value: text.slice(idx + 2).trim() };
+}
+
+/** Unquote a scalar. Only full single/double quoting is recognized. */
+function scalar(value: string, no: number, errors: string[]): string {
+  if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+    return value.slice(1, -1).replace(/\\(["\\])/g, "$1");
+  }
+  if (value.length >= 2 && value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1).replace(/''/g, "'");
+  }
+  if (value === "|" || value === ">" || value.startsWith("| ") || value.startsWith("> ")) {
+    errors.push(`line ${no}: block scalars (| / >) are not supported — keep commands single-line`);
+    return "";
+  }
+  return value;
+}
+
+export function parseServicesManifest(text: string): ParseServicesManifestResult {
+  const errors: string[] = [];
+  if (text.length > 64 * 1024) {
+    return { manifest: null, errors: ["manifest exceeds 64KB — this file is a service list, not a data store"] };
+  }
+  const lines = lex(text);
+  if (lines.length === 0) return { manifest: null, errors: ["manifest is empty"] };
+
+  let version: number | null = null;
+  const services: ServiceEntry[] = [];
+  let current: ServiceEntry | null = null;
+  let currentIndent = -1;
+  /** "health" | "data" while inside a nested map, else null. */
+  let nested: "health" | "data" | null = null;
+  let nestedIndent = -1;
+  let inServices = false;
+
+  const finish = (entry: ServiceEntry | null) => {
+    if (!entry) return;
+    services.push(entry);
+  };
+
+  for (const line of lines) {
+    const kv = splitKey(line.text);
+    if (!kv) {
+      errors.push(`line ${line.no}: not a \`key: value\` mapping — flow collections and bare scalars are not supported`);
+      continue;
+    }
+
+    // Top-level keys.
+    if (line.indent === 0 && !line.dash) {
+      inServices = false;
+      nested = null;
+      finish(current);
+      current = null;
+      if (!TOP_KEYS.has(kv.key)) {
+        errors.push(`line ${line.no}: unknown top-level key \`${kv.key}\` (allowed: version, services)`);
+        continue;
+      }
+      if (kv.key === "version") {
+        const v = Number(scalar(kv.value, line.no, errors));
+        if (v !== 1) errors.push(`line ${line.no}: unsupported manifest version \`${kv.value}\` (this build understands version 1)`);
+        else version = 1;
+      } else {
+        if (kv.value !== "") errors.push(`line ${line.no}: \`services:\` must open a list, not carry a value`);
+        inServices = true;
+      }
+      continue;
+    }
+
+    if (!inServices) {
+      errors.push(`line ${line.no}: unexpected indented line outside \`services:\``);
+      continue;
+    }
+
+    // New sequence item.
+    if (line.dash) {
+      finish(current);
+      current = { name: "", command: "" };
+      currentIndent = line.indent;
+      nested = null;
+      if (kv.key !== "name") {
+        errors.push(`line ${line.no}: each service entry must start with \`- name: <name>\``);
+        continue;
+      }
+      current.name = scalar(kv.value, line.no, errors);
+      continue;
+    }
+
+    if (!current) {
+      errors.push(`line ${line.no}: expected \`- name: <name>\` to open a service entry`);
+      continue;
+    }
+
+    // Nested map keys (health/data), recognized by deeper indentation.
+    if (nested && line.indent > nestedIndent) {
+      const allowed = nested === "health" ? HEALTH_KEYS : DATA_KEYS;
+      if (!allowed.has(kv.key)) {
+        errors.push(`line ${line.no}: unknown \`${nested}\` key \`${kv.key}\` (allowed: ${[...allowed].join(", ")})`);
+        continue;
+      }
+      const value = scalar(kv.value, line.no, errors);
+      if (value === "") {
+        errors.push(`line ${line.no}: \`${nested}.${kv.key}\` needs a value`);
+        continue;
+      }
+      const bucket = (current[nested] ??= {});
+      (bucket as Record<string, string>)[kv.key] = value;
+      continue;
+    }
+    nested = null;
+
+    if (line.indent <= currentIndent) {
+      errors.push(`line ${line.no}: bad indentation — service fields must be indented under their \`- name:\` line`);
+      continue;
+    }
+
+    if (!ENTRY_KEYS.has(kv.key)) {
+      errors.push(`line ${line.no}: unknown service key \`${kv.key}\` (allowed: ${[...ENTRY_KEYS].join(", ")})`);
+      continue;
+    }
+
+    if (kv.key === "health" || kv.key === "data") {
+      if (kv.value !== "") {
+        errors.push(`line ${line.no}: \`${kv.key}:\` opens a nested map — put cmd/http (or dump/restore) on indented lines below`);
+        continue;
+      }
+      nested = kv.key;
+      nestedIndent = line.indent;
+      continue;
+    }
+
+    const value = scalar(kv.value, line.no, errors);
+    if (kv.key === "port") {
+      const port = Number(value);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        errors.push(`line ${line.no}: port must be an integer 1-65535, got \`${kv.value}\``);
+      } else {
+        current.port = port;
+      }
+      continue;
+    }
+    if (value === "") {
+      errors.push(`line ${line.no}: \`${kv.key}\` needs a value`);
+      continue;
+    }
+    if (kv.key === "cwd" && (value.startsWith("/") || value.includes(".."))) {
+      errors.push(`line ${line.no}: cwd must be a relative path under the drive root (no leading / and no ..)`);
+      continue;
+    }
+    (current as unknown as Record<string, string>)[kv.key] = value;
+  }
+  finish(current);
+
+  // Semantic validation.
+  if (version === null) errors.push("missing `version: 1`");
+  if (services.length === 0 && errors.length === 0) errors.push("`services:` lists no entries");
+  if (services.length > SERVICES_MAX) errors.push(`too many services (${services.length}) — the cap is ${SERVICES_MAX}`);
+  const seen = new Set<string>();
+  for (const svc of services) {
+    const label = svc.name || "<unnamed>";
+    if (!SERVICE_NAME_RE.test(svc.name)) {
+      errors.push(`service \`${label}\`: name must match ${SERVICE_NAME_RE} (alphanumeric start, then [A-Za-z0-9._-], max 32)`);
+    } else if (seen.has(svc.name)) {
+      errors.push(`service \`${label}\`: duplicate name`);
+    }
+    seen.add(svc.name);
+    if (!svc.command) errors.push(`service \`${label}\`: missing \`command\``);
+    if (svc.health?.cmd && svc.health.http) {
+      errors.push(`service \`${label}\`: health takes \`cmd\` OR \`http\`, not both`);
+    }
+    if (svc.health?.http && !/^https?:\/\//.test(svc.health.http)) {
+      errors.push(`service \`${label}\`: health.http must be an http(s):// URL`);
+    }
+  }
+
+  return errors.length > 0 ? { manifest: null, errors } : { manifest: { version: 1, services }, errors: [] };
+}
+
+/** Quote a scalar for emission iff the parser would otherwise mangle it. */
+function emitScalar(value: string): string {
+  const needsQuote =
+    value !== value.trim() ||
+    value.startsWith("'") ||
+    value.startsWith('"') ||
+    value === "|" ||
+    value === ">" ||
+    value.startsWith("| ") ||
+    value.startsWith("> ");
+  if (!needsQuote) return value;
+  return `"${value.replace(/([\\"])/g, "\\$1")}"`;
+}
+
+/**
+ * Serialize a manifest in the canonical shape the parser reads back.
+ * Values containing newlines are a caller bug (the CLI rejects them first).
+ */
+export function renderServicesManifest(manifest: ServicesManifest): string {
+  const out: string[] = [
+    "# Durable services manifest — restored automatically after a machine recycle.",
+    "# Docs: agentc services --help",
+    "version: 1",
+    "services:",
+  ];
+  for (const svc of manifest.services) {
+    out.push(`  - name: ${emitScalar(svc.name)}`);
+    out.push(`    command: ${emitScalar(svc.command)}`);
+    if (svc.cwd) out.push(`    cwd: ${emitScalar(svc.cwd)}`);
+    if (svc.port !== undefined) out.push(`    port: ${svc.port}`);
+    if (svc.env) out.push(`    env: ${emitScalar(svc.env)}`);
+    if (svc.setup) out.push(`    setup: ${emitScalar(svc.setup)}`);
+    if (svc.health && (svc.health.cmd || svc.health.http)) {
+      out.push("    health:");
+      if (svc.health.cmd) out.push(`      cmd: ${emitScalar(svc.health.cmd)}`);
+      if (svc.health.http) out.push(`      http: ${emitScalar(svc.health.http)}`);
+    }
+    if (svc.data && (svc.data.dump || svc.data.restore)) {
+      out.push("    data:");
+      if (svc.data.dump) out.push(`      dump: ${emitScalar(svc.data.dump)}`);
+      if (svc.data.restore) out.push(`      restore: ${emitScalar(svc.data.restore)}`);
+    }
+  }
+  return out.join("\n") + "\n";
+}

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(" ");
+}