@love-moon/conductor-cli 0.10.0 → 0.11.0

package/src/guest-daemon.js

@@ -0,0 +1,268 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * RFC 0035 — guest daemon supervision.
+ *
+ * The owner's daemon keeps one child `conductor daemon` process per accepted
+ * share. Each child authenticates as the *grantee*, so the backend sees an
+ * ordinary daemon belonging to that user and every existing ownership check
+ * keeps working. Nothing in the backend's hot path knows sharing exists.
+ *
+ * This module is deliberately pure-ish: path/config/env construction and the
+ * reconcile decision are exported as plain functions so they can be tested
+ * without spawning anything.
+ */
+
+/** One node process per guest; this bounds the owner's machine, not the product. */
+export const MAX_GUEST_DAEMONS = 3;
+
+export const GUEST_RESTART_BASE_MS = 10_000;
+export const GUEST_RESTART_MAX_MS = 5 * 60_000;
+
+const expandHome = (value, homeDir) => {
+  if (typeof value !== "string" || !value.trim()) return "";
+  const trimmed = value.trim();
+  if (trimmed === "~") return homeDir;
+  if (trimmed.startsWith("~/")) return path.join(homeDir, trimmed.slice(2));
+  return path.resolve(trimmed);
+};
+
+/**
+ * Every path a guest instance must NOT share with its host daemon.
+ *
+ * This is the part that is easy to get wrong and expensive when you do:
+ * `--config-file` does *not* derive `CONDUCTOR_HOME` (`conductor-paths.js`
+ * resolves it from the environment only), and the daemon PID lock lives under
+ * `CONDUCTOR_WS`, not under `CONDUCTOR_HOME`. Two daemons sharing a workspace
+ * root contend for one `daemon.pid`, and `--force` on the second one will
+ * SIGKILL the first -- across accounts. Verified live before this was written.
+ */
+export function resolveGuestPaths(shareId, workspaceRoot, homeDir = os.homedir()) {
+  const home = homeDir || "/tmp";
+  const conductorHome = path.join(home, ".conductor-guests", shareId);
+  const ws = workspaceRoot
+    ? path.join(expandHome(workspaceRoot, home), "ws")
+    : path.join(home, "conductor-guests", shareId, "ws");
+  return {
+    conductorHome,
+    configDir: path.join(home, ".conductor", "shares", shareId),
+    configPath: path.join(home, ".conductor", "shares", shareId, "config.yaml"),
+    workspace: ws,
+    fireStateDir: path.join(conductorHome, "state"),
+    // The root a guest's project paths must stay under. Its parent, not `ws`,
+    // so the guest can also see sibling dirs the owner deliberately placed.
+    guestRoot: workspaceRoot
+      ? expandHome(workspaceRoot, home)
+      : path.join(home, "conductor-guests", shareId),
+  };
+}
+
+const yamlQuote = (value) => `"${String(value).replace(/(["\\])/g, "\\$1")}"`;
+
+/**
+ * The guest's config.yaml.
+ *
+ * Note what is NOT here: `envs:`. Leaving it out is the whole point of the
+ * feature -- the guest inherits the machine's already-logged-in AI CLIs
+ * (`~/.claude`, `~/.codex`). Setting per-instance `CODEX_HOME` /
+ * `CLAUDE_CONFIG_DIR` here would isolate credentials and defeat the purpose.
+ */
+export function buildGuestConfigYaml({
+  agentToken,
+  backendUrl,
+  guestHost,
+  workspace,
+  allowCliList,
+}) {
+  const lines = [
+    "# Generated by conductor daemon (RFC 0035 daemon sharing). Do not edit.",
+    "# Regenerated from the backend on every supervisor reconcile.",
+    `agent_token: ${yamlQuote(agentToken)}`,
+    `backend_url: ${yamlQuote(backendUrl)}`,
+    `daemon_name: ${yamlQuote(guestHost)}`,
+    `workspace: ${yamlQuote(workspace)}`,
+    "conductor_guest: true",
+  ];
+
+  // Inherited from the owner, and load-bearing: `conductor-fire` refuses a
+  // backend that has no `allow_cli_list` entry unless it is one of the
+  // command-optional SDK backends (copilot, dsh). Omitting this leaves a guest
+  // able to start a task and then die with
+  // `Unsupported backend "claude". Supported backends: copilot, dsh.` --
+  // i.e. unable to run the very CLIs the machine was shared for.
+  //
+  // Copying the owner's list is the right semantics, not a shortcut: the guest
+  // runs on the owner's machine against the owner's installed, already
+  // logged-in tools, so the command lines that work for the owner are exactly
+  // the ones that work here.
+  const entries = Object.entries(allowCliList || {}).filter(
+    ([backend, command]) => backend && typeof command === "string" && command.trim(),
+  );
+  if (entries.length > 0) {
+    lines.push("allow_cli_list:");
+    for (const [backend, command] of entries) {
+      lines.push(`  ${backend}: ${yamlQuote(command.trim())}`);
+    }
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Environment for the guest child.
+ *
+ * `CONDUCTOR_AGENT_TOKEN` is deliberately deleted rather than overwritten: the
+ * child inherits the owner's environment, and the daemon only ignores an
+ * inherited token because `--config-file` was passed explicitly
+ * (`daemon.js` `allowEnvConfigOverrides`). Removing it means a future change to
+ * that precedence cannot silently make the guest run as the owner.
+ */
+export function buildGuestEnv(baseEnv, paths, extra = {}) {
+  const env = { ...baseEnv };
+  delete env.CONDUCTOR_AGENT_TOKEN;
+  delete env.CONDUCTOR_BACKEND_URL;
+  delete env.CONDUCTOR_WS_URL;
+  delete env.CONDUCTOR_BACKEND_WS_URL;
+  delete env.CONDUCTOR_DAEMON_NAME;
+  delete env.CONDUCTOR_TASK_ID;
+  delete env.CONDUCTOR_PROJECT_ID;
+  return {
+    ...env,
+    CONDUCTOR_HOME: paths.conductorHome,
+    CONDUCTOR_WS: paths.workspace,
+    CONDUCTOR_FIRE_STATE_DIR: paths.fireStateDir,
+    CONDUCTOR_GUEST_SHARE_ID: extra.shareId || "",
+    // Only propagated when the owner actually picked a workspace root. An
+    // auto-generated one must not turn into a confinement the owner never
+    // chose -- see the note on GUEST_ROOT in daemon.js.
+    ...(extra.explicitRoot ? { CONDUCTOR_GUEST_ROOT: paths.guestRoot } : {}),
+  };
+}
+
+export function writeGuestConfig(paths, contents, deps = {}) {
+  const mkdirSync = deps.mkdirSync || fs.mkdirSync;
+  const writeFileSync = deps.writeFileSync || fs.writeFileSync;
+  mkdirSync(paths.configDir, { recursive: true, mode: 0o700 });
+  mkdirSync(paths.conductorHome, { recursive: true, mode: 0o700 });
+  mkdirSync(paths.workspace, { recursive: true });
+  // 0600: the file holds the grantee's credential in plaintext.
+  writeFileSync(paths.configPath, contents, { encoding: "utf8", mode: 0o600 });
+  return paths.configPath;
+}
+
+/**
+ * Decide what the supervisor should do, given the desired shares from the
+ * backend and what is currently running. Pure, so the interesting cases are
+ * testable without processes.
+ */
+export function reconcileGuests(desiredShares, runningIds, max = MAX_GUEST_DAEMONS) {
+  const usable = (desiredShares || []).filter(
+    (share) => share && share.id && share.guestHost && share.agentToken,
+  );
+  const start = [];
+  const keep = [];
+  for (const share of usable) {
+    if (runningIds.has(share.id)) keep.push(share.id);
+    else if (keep.length + start.length < max) start.push(share);
+  }
+  const desiredIds = new Set(usable.map((share) => share.id));
+  // Anything running that the backend no longer lists as active: revoked,
+  // or the share moved to another daemon.
+  const stop = [...runningIds].filter((id) => !desiredIds.has(id));
+  const skipped = usable.length > max ? usable.length - max : 0;
+  return { start, stop, keep, skipped };
+}
+
+export function nextRestartDelayMs(failureCount) {
+  const exponent = Math.max(0, failureCount - 1);
+  return Math.min(GUEST_RESTART_BASE_MS * 2 ** exponent, GUEST_RESTART_MAX_MS);
+}
+
+/**
+ * A guest daemon offers the SAME capabilities as any other daemon.
+ *
+ * The dividing line is not "can the grantee execute code here" -- they always
+ * can, because an AI task is an arbitrary prompt handed to a CLI with a shell,
+ * and `pty_task`'s `custom` entrypoint takes caller-supplied command/args/cwd/env
+ * (`daemon.js` `entrypointType === "custom"`). Blocking the scriptable door
+ * while leaving the interactive one open stops no attacker and only breaks
+ * legitimate use.
+ *
+ * `remote_exec` was on this list for exactly that bad reason. RFC 0034 had
+ * already made the argument: it "adds no reach" beyond `create_pty_task`,
+ * except on a host whose node-pty probe failed -- which is not the case a
+ * blanket guest rule addresses.
+ *
+ * What a guest genuinely must not do is mutate state the OWNER depends on.
+ * That is a different axis, handled per-action below, not by withholding
+ * capabilities.
+ */
+export const GUEST_BLOCKED_CAPABILITIES = new Set();
+
+export function filterGuestCapabilities(capabilities) {
+  return (capabilities || []).filter((cap) => !GUEST_BLOCKED_CAPABILITIES.has(cap));
+}
+
+/**
+ * The two actions a guest must still refuse. Neither restricts what the grantee
+ * can do with their own account -- both would reconfigure the owner's machine:
+ *  - a versioned restart runs a global `npm install -g`, swapping the CLI
+ *    binary out from under the owner's own daemon and every one of their fires;
+ *  - `switch_account` renames over `~/.codex/auth.json`, changing the owner's
+ *    active Codex identity everywhere on the box.
+ * Reads (`status`, `quota`, `list_accounts`) stay allowed: the grantee needs to
+ * see how much quota is left before running something heavy.
+ */
+export function isGuestRestartAllowed(payload) {
+  const target = payload && typeof payload.target_version === "string"
+    ? payload.target_version.trim()
+    : "";
+  return !target;
+}
+
+export function isGuestAiManagerActionAllowed(action) {
+  return action !== "switch_account";
+}
+
+/**
+ * Confine a guest's project paths to its root.
+ *
+ * `validate_project_path` resolves any absolute path the caller sends and will
+ * `mkdirSync(recursive)` when asked; `get_project_agents` reads arbitrary
+ * paths too. Neither is bounded by the workspace today. This is a
+ * misuse-prevention boundary, not a security boundary -- the guest's AI agent
+ * runs a shell and can reach anything the OS user can.
+ */
+export function isPathInsideGuestRoot(candidate, guestRoot) {
+  if (!guestRoot) return true;
+  const resolvedRoot = path.resolve(guestRoot);
+  const resolved = path.resolve(candidate || "");
+  if (resolved === resolvedRoot) return true;
+  return resolved.startsWith(`${resolvedRoot}${path.sep}`);
+}
+
+/**
+ * Guests are spawned as ordinary children, which means a `SIGKILL` or a hard
+ * crash of the host daemon leaves them running with live credentials, serving
+ * a share the owner believes is stopped. `detached: false` does not help --
+ * on POSIX it only shares the process group; nothing reaps the child.
+ *
+ * So the guest watches its own parent instead. `process.ppid` becomes 1 (or
+ * the reaper) once the host daemon is gone.
+ */
+export function startOrphanWatchdog(options = {}) {
+  const intervalMs = options.intervalMs || 15_000;
+  const initialPpid = options.ppid ?? process.ppid;
+  const onOrphaned = options.onOrphaned || (() => process.exit(0));
+  const readPpid = options.readPpid || (() => process.ppid);
+
+  const timer = setInterval(() => {
+    const current = readPpid();
+    if (current !== initialPpid) onOrphaned(current, initialPpid);
+  }, intervalMs);
+  if (typeof timer.unref === "function") timer.unref();
+  return () => clearInterval(timer);
+}