@openape/nest 0.2.2 → 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# @openape/nest
+
+Local control-plane daemon. Manages OpenApe agents on a single machine — provisions macOS users, hands the bridge lifecycle off to launchd, exposes a localhost HTTP API gated by DDISA grant tokens.
+
+## What it does
+
+- Runs as a long-lived launchd-managed daemon under your user account (`~/Library/LaunchAgents/ai.openape.nest.plist`)
+- Accepts API calls on `127.0.0.1:9091` for agent lifecycle ops (`spawn`, `destroy`, `list`, `status`)
+- Every API call requires a DDISA-signed grant token in the `Authorization: Bearer …` header
+- Bridge processes (`openape-chat-bridge` per agent) are NOT supervised in-daemon — they run as system-domain LaunchDaemons (one plist per agent in `/Library/LaunchDaemons/eco.hofmann.apes.bridge.<agent>.plist`) installed by `apes agents spawn --bridge`. launchd is the right OS-level supervisor on macOS; trying to duplicate that in the daemon crashloops without adding value.
+
+## Setup (one-time)
+
+```bash
+apes nest install      # install + load the launchd plist
+apes nest enroll       # daemon gets its own DDISA agent identity
+apes nest authorize    # set the YOLO policy — covers the inner
+                       # `apes agents spawn` calls the daemon makes
+```
+
+Set the bridge default model at install time so every spawn uses the
+same one without `--bridge-model` repetition:
+
+```bash
+apes nest install --bridge-model gpt-5.4    # ChatGPT-only LiteLLM proxy
+apes nest install --bridge-model claude-haiku-4-5  # Anthropic
+```
+
+This writes `APE_CHAT_BRIDGE_MODEL=<value>` to `~/litellm/.env`,
+which `resolveBridgeConfig()` reads at every `apes [nest|agents] spawn
+--bridge`. Re-run with a different value to overwrite.
+
+### Optional: privilege isolation with a dedicated service user
+
+By default, `apes nest install` configures the daemon as a user-domain
+`LaunchAgent` running under your own Mac user account, with state at
+`~/.openape/nest`. That works fine for personal use. For a more
+hardened setup the daemon can be promoted to a system-domain
+`LaunchDaemon` running under a dedicated `_openape_nest` macOS service
+user (uid 481, hidden, no shell, no GUI session) with state under
+`/var/openape/nest`.
+
+To migrate an existing user-domain install:
+
+```bash
+apes run --as root --wait -- bash apps/openape-nest/scripts/migrate-to-service-user.sh
+```
+
+The script creates the user/group, copies your data dir to
+`/var/openape/nest`, and swaps the plist. The Nest's IdP identity is
+bound to its ssh keypair (which moves with the data dir), so the same
+`nest-…@id.openape.ai` identity continues to work — no re-enroll
+needed, all existing approved delegations / grants stay valid.
+
+After migration you may want a fresh `apes login --key` for the Nest
+to refresh the access token (the migrated `auth.json` carries the
+old token; `cli-auth`'s challenge-response refresh handles it on
+expiry, but a manual login also works).
+
+After that, day-to-day lifecycle goes through `apes nest`:
+
+```bash
+apes nest spawn igor18           # provision a new agent
+apes nest list                   # show agents this nest knows about
+apes nest status                 # health-check
+apes nest destroy igor18         # tear down
+apes nest uninstall              # remove the launchd plist
+```
+
+## Why every API call needs a grant token
+
+Without auth the API is gated only by "process running as the logged-in human can reach localhost:9091" — a compromised local process inherits everything. The grant-token requirement closes that gap and gives every call an audit record at the IdP. The flow:
+
+1. `apes nest <op>` looks for an existing approved `'always'`/`'timed'` grant matching the operation.
+2. If none, requests a fresh grant from the IdP. **First-time** grants for human callers wait for human approval (one approval covers the lifetime of the grant — `'always'` is the default for nest-CLI calls).
+3. Token (RFC-7519 JWT signed by the IdP) is fetched and presented as `Authorization: Bearer …`.
+4. The Nest verifies signature against the IdP's JWKS, checks `aud=nest`, `iss=<IdP URL>`, `target_host=<local hostname>`, and exact-matches the embedded `command` claim against the route. Fails: `401` (auth) or `403` (command mismatch).
+
+### Grant-scope conventions
+
+| CLI | Grant `command` | Reuse semantics |
+|---|---|---|
+| `apes nest list` | `["nest","list"]` | One approval, reused forever. |
+| `apes nest status` | `["nest","status"]` | One approval, reused forever. |
+| `apes nest spawn <name>` | `["nest","spawn"]` (no name baked in) | One approval, any future spawn. Trade-off: a compromised local process running as the human can spawn arbitrary agents under that grant. Acceptable because spawn is reversible and audited. |
+| `apes nest destroy <name>` | `["nest","destroy","<name>"]` | Per-name. Destroying each agent is its own approval. Destructive ops keep tighter scoping by design. |
+
+Direct `curl` to the API is supported but you must fetch a grant token yourself. See `tests/auth-negative.sh` for an example token-fetch.
+
+## Negative-test smoke
+
+```bash
+bash apps/openape-nest/tests/auth-negative.sh
+```
+
+Verifies: no-bearer → 401, garbage-bearer → 401, wrong-audience → 401, command-mismatch → 403.
+
+## Why no in-daemon bridge supervisor
+
+Earlier versions ran a per-agent process supervisor inside the Nest daemon to keep `openape-chat-bridge` instances alive. It was removed because:
+
+- `apes agents spawn --bridge` already installs a system-domain `LaunchDaemon` per agent. launchd KeepAlive's it as the agent UID with the right PATH (the bridge binary is at `/Users/<agent>/.bun/bin/openape-chat-bridge`).
+- The supervisor's children inherited the daemon's PATH (the human user's PATH, which doesn't include any agent's `~/.bun/bin`), so they crashlooped on `Command not found: openape-chat-bridge` while the launchd-domain bridge ran fine.
+- Each crashloop produced an auto-approved YOLO grant — pushing one notification per cycle.
+
+Single-source-of-truth on launchd. The Nest is now an API surface in front of `apes agents spawn|destroy`, nothing more.

package/dist/index.mjs

@@ -1,8 +1,12 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { createServer } from "http";
-import process from "process";
+import process3 from "process";
+
+// src/lib/intent-channel.ts
+import { readdirSync, readFileSync as readFileSync2, renameSync, statSync, unlinkSync, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2, chmodSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
 
 // src/api/agents.ts
 import { execFile } from "child_process";
@@ -12,7 +16,7 @@ import { promisify } from "util";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
-var REGISTRY_DIR = join(homedir(), ".openape", "nest");
+var REGISTRY_DIR = homedir();
 var REGISTRY_PATH = join(REGISTRY_DIR, "agents.json");
 function emptyRegistry() {
   return { version: 1, agents: [] };
@@ -57,15 +61,6 @@ function removeAgent(name) {
 // src/api/agents.ts
 var execFileAsync = promisify(execFile);
 var NAME_REGEX = /^[a-z][a-z0-9-]{0,23}$/;
-function handleNestStatus(ctx) {
-  return {
-    agents: listAgents().length,
-    processes: ctx.supervisor.status()
-  };
-}
-function handleAgentsList(_ctx) {
-  return { agents: listAgents() };
-}
 async function handleAgentSpawn(ctx) {
   const body = ctx.body;
   const name = typeof body?.name === "string" ? body.name : "";
@@ -76,7 +71,7 @@ async function handleAgentSpawn(ctx) {
     throw new Error(`agent "${name}" is already registered with this nest`);
   }
   const args = ["run", "--as", "root", "--wait", "--", "apes", "agents", "spawn", name];
-  const includeBridge = body?.bridge === true;
+  const includeBridge = body?.bridge !== false;
   if (includeBridge) {
     args.push("--bridge");
     if (typeof body?.bridgeKey === "string") args.push("--bridge-key", body.bridgeKey);
@@ -125,34 +120,144 @@ async function readUidFromDscl(name) {
   return -1;
 }
 
+// src/lib/intent-channel.ts
+var POLL_MS = 1e3;
+var INTENTS_DIR = join2(homedir2(), "intents");
+var IntentChannel = class {
+  constructor(deps) {
+    this.deps = deps;
+    mkdirSync2(INTENTS_DIR, { recursive: true });
+    chmodSync(INTENTS_DIR, 504);
+  }
+  timer;
+  inflight = /* @__PURE__ */ new Set();
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => void this.tick(), POLL_MS);
+    this.deps.log(`intent-channel: polling ${INTENTS_DIR}`);
+  }
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = void 0;
+  }
+  async tick() {
+    let entries;
+    try {
+      entries = readdirSync(INTENTS_DIR);
+    } catch {
+      return;
+    }
+    for (const f of entries) {
+      if (!f.endsWith(".json")) continue;
+      if (this.inflight.has(f)) continue;
+      this.inflight.add(f);
+      void this.process(f).finally(() => this.inflight.delete(f));
+    }
+  }
+  async process(filename) {
+    const path = join2(INTENTS_DIR, filename);
+    let intent;
+    try {
+      const raw = readFileSync2(path, "utf8");
+      intent = JSON.parse(raw);
+    } catch (err) {
+      this.deps.log(`intent-channel: failed to read ${filename}: ${err instanceof Error ? err.message : String(err)}`);
+      try {
+        unlinkSync(path);
+      } catch {
+      }
+      return;
+    }
+    this.deps.log(`intent-channel: processing ${intent.action} (id=${intent.id})`);
+    let response;
+    try {
+      const ctx = {
+        url: new URL("intent:/"),
+        body: intent,
+        log: this.deps.log,
+        apesBin: this.deps.apesBin,
+        caller: "<intent-channel>",
+        grantId: intent.id,
+        supervisor: this.deps.supervisor
+      };
+      let result;
+      switch (intent.action) {
+        case "spawn":
+          result = await handleAgentSpawn(ctx);
+          break;
+        case "destroy":
+          result = await handleAgentDestroy(ctx, intent.name);
+          break;
+        case "list":
+          result = { agents: listAgents() };
+          break;
+        default:
+          throw new Error(`unknown action: ${intent.action ?? "<undefined>"}`);
+      }
+      response = { ok: true, result };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      this.deps.log(`intent-channel: ${intent.action} failed: ${msg}`);
+      response = { ok: false, error: msg };
+    }
+    const respTmp = `${path.replace(/\.json$/, "")}.response.tmp`;
+    const respFinal = `${path.replace(/\.json$/, "")}.response`;
+    writeFileSync2(respTmp, `${JSON.stringify(response)}
+`, { mode: 432 });
+    renameSync(respTmp, respFinal);
+    try {
+      unlinkSync(path);
+    } catch {
+    }
+  }
+};
+function reapStaleResponses(log2) {
+  let entries;
+  try {
+    entries = readdirSync(INTENTS_DIR);
+  } catch {
+    return;
+  }
+  const now = Date.now();
+  for (const f of entries) {
+    if (!f.endsWith(".response")) continue;
+    const path = join2(INTENTS_DIR, f);
+    try {
+      const st = statSync(path);
+      if (now - st.mtimeMs > 60 * 60 * 1e3) {
+        unlinkSync(path);
+        log2(`intent-channel: reaped stale ${f}`);
+      }
+    } catch {
+    }
+  }
+}
+
 // src/lib/supervisor.ts
 import { spawn } from "child_process";
-var MIN_BACKOFF_MS = 1e3;
+import process from "process";
+var MIN_BACKOFF_MS = 2e3;
 var MAX_BACKOFF_MS = 6e4;
+var STABLE_RUNTIME_MS = 3e4;
 var Supervisor = class {
   constructor(deps) {
     this.deps = deps;
   }
   children = /* @__PURE__ */ new Map();
-  /**
-   * Bring the supervised set in line with the desired set. Spawns
-   * agents that aren't running, kills agents that are no longer in
-   * the registry. Idempotent — call after every registry mutation.
-   */
+  /** Bring the supervised set in line with the desired set. */
   reconcile(desired) {
-    const desiredNames = new Set(desired.map((a) => a.name));
+    const desiredNames = new Set(desired.filter((a) => a.bridge != null).map((a) => a.name));
     for (const [name] of this.children) {
       if (!desiredNames.has(name)) this.stop(name);
     }
     for (const agent of desired) {
+      if (agent.bridge == null) continue;
       if (!this.children.has(agent.name)) this.start(agent);
     }
   }
-  /** Number of currently-running supervised processes. */
   size() {
     return this.children.size;
   }
-  /** Snapshot of supervised state — useful for /agents GET. */
   status() {
     const now = Date.now();
     return Array.from(this.children.entries()).map(([name, s]) => ({
@@ -164,13 +269,13 @@ var Supervisor = class {
   }
   start(agent) {
     if (this.children.has(agent.name)) return;
-    this.deps.log(`supervisor: starting ${agent.name}`);
+    this.deps.log(`supervisor: starting bridge for ${agent.name}`);
     this.spawnChild(agent, 0);
   }
   stop(name) {
     const s = this.children.get(name);
     if (!s) return;
-    this.deps.log(`supervisor: stopping ${name}`);
+    this.deps.log(`supervisor: stopping bridge for ${name}`);
     if (s.restartTimer) clearTimeout(s.restartTimer);
     this.children.delete(name);
     try {
@@ -178,15 +283,19 @@ var Supervisor = class {
     } catch {
     }
   }
-  /** Kill all children — called on daemon shutdown. */
   stopAll() {
     for (const name of Array.from(this.children.keys())) this.stop(name);
   }
   spawnChild(agent, prevCrashes) {
-    const args = ["run", "--as", agent.name, "--", "openape-chat-bridge"];
+    const args = ["run", "--as", agent.name, "--wait", "--", "openape-chat-bridge"];
     const child = spawn(this.deps.apesBin, args, {
       stdio: ["ignore", "pipe", "pipe"],
-      detached: false
+      detached: false,
+      // Inherit env — most importantly PATH (host bin dirs from
+      // captureHostBinDirs at install time) and HOME (the Nest's
+      // data dir, where its own auth.json lives so apes-cli reads
+      // the nest identity for the YOLO grant).
+      env: process.env
     });
     child.stdout?.on("data", (chunk) => this.forwardLog(agent.name, "stdout", chunk));
     child.stderr?.on("data", (chunk) => this.forwardLog(agent.name, "stderr", chunk));
@@ -199,11 +308,11 @@ var Supervisor = class {
     child.on("exit", (code, signal) => {
       const stillManaged = this.children.get(agent.name) === supervised;
       if (!stillManaged) return;
-      const ranLongEnough = Date.now() - supervised.startedAt > 3e4;
+      const ranLongEnough = Date.now() - supervised.startedAt > STABLE_RUNTIME_MS;
       const nextCrashes = ranLongEnough ? 1 : prevCrashes + 1;
       const backoff = Math.min(MAX_BACKOFF_MS, MIN_BACKOFF_MS * 2 ** Math.max(0, nextCrashes - 1));
       this.deps.log(
-        `supervisor: ${agent.name} exited code=${code} signal=${signal ?? "none"} consecutive=${nextCrashes} \u2192 respawn in ${backoff}ms`
+        `supervisor: ${agent.name} bridge exited code=${code} signal=${signal ?? "none"} consecutive=${nextCrashes} \u2192 respawn in ${backoff}ms`
       );
       supervised.restartTimer = setTimeout(() => {
         if (this.children.get(agent.name) !== supervised) return;
@@ -222,73 +331,82 @@ var Supervisor = class {
   }
 };
 
+// src/lib/troop-sync.ts
+import { execFile as execFile2 } from "child_process";
+import process2 from "process";
+import { promisify as promisify2 } from "util";
+var execFileAsync2 = promisify2(execFile2);
+var TICK_MS = 5 * 60 * 1e3;
+var TroopSync = class {
+  constructor(deps) {
+    this.deps = deps;
+  }
+  timer;
+  inflight = false;
+  start() {
+    if (this.timer) return;
+    setTimeout(() => this.tick(), 3e4).unref();
+    this.timer = setInterval(() => this.tick(), TICK_MS);
+    this.deps.log("troop-sync: loop started (interval=5min)");
+  }
+  stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = void 0;
+  }
+  async tick() {
+    if (this.inflight) return;
+    this.inflight = true;
+    try {
+      const agents = listAgents();
+      if (agents.length === 0) return;
+      this.deps.log(`troop-sync: reconciling ${agents.length} agent(s)`);
+      for (const agent of agents) {
+        await this.syncOne(agent.name);
+      }
+    } finally {
+      this.inflight = false;
+    }
+  }
+  async syncOne(name) {
+    try {
+      await execFileAsync2(
+        this.deps.apesBin,
+        ["run", "--as", name, "--wait", "--", "apes", "agents", "sync"],
+        { maxBuffer: 1024 * 1024, env: process2.env, timeout: 6e4 }
+      );
+    } catch (err) {
+      this.deps.log(`troop-sync: ${name} failed: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`);
+    }
+  }
+};
+
 // src/index.ts
-var HOST = "127.0.0.1";
-var PORT = Number(process.env.OPENAPE_NEST_PORT ?? 9091);
-var APES_BIN = process.env.OPENAPE_APES_BIN ?? "apes";
+var APES_BIN = process3.env.OPENAPE_APES_BIN ?? "apes";
 function log(line) {
-  process.stderr.write(`${(/* @__PURE__ */ new Date()).toISOString()}  ${line}
+  process3.stderr.write(`${(/* @__PURE__ */ new Date()).toISOString()}  ${line}
 `);
 }
 var supervisor = new Supervisor({ apesBin: APES_BIN, log });
+var troopSync = new TroopSync({ apesBin: APES_BIN, log });
+var intentChannel = new IntentChannel({ apesBin: APES_BIN, supervisor, log });
 supervisor.reconcile(listAgents());
-log(`nest: supervisor reconciled, ${supervisor.size()} agent process(es) running`);
-async function readJsonBody(req) {
-  const chunks = [];
-  for await (const chunk of req) chunks.push(chunk);
-  if (chunks.length === 0) return {};
-  const text = Buffer.concat(chunks).toString("utf8");
-  if (!text.trim()) return {};
-  try {
-    return JSON.parse(text);
-  } catch {
-    throw new Error("invalid JSON body");
-  }
-}
-function send(res, status, body) {
-  res.writeHead(status, { "content-type": "application/json" });
-  res.end(JSON.stringify(body));
-}
-var server = createServer((req, res) => {
-  ;
-  (async () => {
-    try {
-      const url = new URL(req.url ?? "/", `http://${HOST}:${PORT}`);
-      const body = req.method && ["POST", "PUT", "PATCH"].includes(req.method) ? await readJsonBody(req) : {};
-      const ctx = { url, body, log, apesBin: APES_BIN, supervisor };
-      if (req.method === "GET" && url.pathname === "/status") {
-        return send(res, 200, handleNestStatus(ctx));
-      }
-      if (req.method === "GET" && url.pathname === "/agents") {
-        return send(res, 200, handleAgentsList(ctx));
-      }
-      if (req.method === "POST" && url.pathname === "/agents") {
-        const result = await handleAgentSpawn(ctx);
-        return send(res, 201, result);
-      }
-      const destroyMatch = req.method === "DELETE" && url.pathname.match(/^\/agents\/([^/]+)$/);
-      if (destroyMatch) {
-        const result = await handleAgentDestroy(ctx, destroyMatch[1]);
-        return send(res, 200, result);
-      }
-      send(res, 404, { error: "not found" });
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      log(`nest: request failed: ${msg}`);
-      send(res, 500, { error: msg });
-    }
-  })();
-});
-server.listen(PORT, HOST, () => {
-  log(`nest: listening on http://${HOST}:${PORT}`);
-});
-process.on("SIGTERM", () => {
-  log("nest: SIGTERM \u2014 stopping supervisor");
+log(`nest: supervisor reconciled, ${supervisor.size()} bridge process(es) starting`);
+troopSync.start();
+intentChannel.start();
+var reaperTimer = setInterval(reapStaleResponses, 60 * 60 * 1e3, log);
+process3.on("SIGTERM", () => {
+  log("nest: SIGTERM \u2014 stopping");
   supervisor.stopAll();
-  server.close(() => process.exit(0));
+  troopSync.stop();
+  intentChannel.stop();
+  clearInterval(reaperTimer);
+  process3.exit(0);
 });
-process.on("SIGINT", () => {
-  log("nest: SIGINT \u2014 stopping supervisor");
+process3.on("SIGINT", () => {
+  log("nest: SIGINT \u2014 stopping");
   supervisor.stopAll();
-  server.close(() => process.exit(0));
+  troopSync.stop();
+  intentChannel.stop();
+  clearInterval(reaperTimer);
+  process3.exit(0);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openape/nest",
-  "version": "0.2.2",
+  "version": "1.0.0",
   "description": "OpenApe Nest — local control-plane daemon that supervises agent processes on this computer. Talks to troop SP for ownership state, spawns/destroys agents via DDISA always-grants, supervises chat-bridge children (replacing per-agent launchd plists).",
   "type": "module",
   "license": "MIT",
@@ -17,7 +17,8 @@
   },
   "dependencies": {
     "ofetch": "^1.4.1",
-    "@openape/cli-auth": "0.3.0"
+    "@openape/core": "0.16.0",
+    "@openape/cli-auth": "0.4.0"
   },
   "devDependencies": {
     "@antfu/eslint-config": "^7.6.1",