@openape/nest 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Hofmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { createServer } from "http";
+import process from "process";
+
+// src/api/agents.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+
+// src/lib/registry.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var REGISTRY_DIR = join(homedir(), ".openape", "nest");
+var REGISTRY_PATH = join(REGISTRY_DIR, "agents.json");
+function emptyRegistry() {
+  return { version: 1, agents: [] };
+}
+function readRegistry() {
+  if (!existsSync(REGISTRY_PATH)) return emptyRegistry();
+  try {
+    const parsed = JSON.parse(readFileSync(REGISTRY_PATH, "utf8"));
+    if (parsed?.version !== 1 || !Array.isArray(parsed.agents)) return emptyRegistry();
+    return parsed;
+  } catch {
+    return emptyRegistry();
+  }
+}
+function writeRegistry(reg) {
+  mkdirSync(REGISTRY_DIR, { recursive: true });
+  writeFileSync(REGISTRY_PATH, `${JSON.stringify(reg, null, 2)}
+`, { mode: 384 });
+}
+function listAgents() {
+  return readRegistry().agents;
+}
+function findAgent(name) {
+  return readRegistry().agents.find((a) => a.name === name);
+}
+function upsertAgent(entry) {
+  const reg = readRegistry();
+  const existing = reg.agents.findIndex((a) => a.name === entry.name);
+  if (existing >= 0) reg.agents[existing] = entry;
+  else reg.agents.push(entry);
+  writeRegistry(reg);
+}
+function removeAgent(name) {
+  const reg = readRegistry();
+  const before = reg.agents.length;
+  reg.agents = reg.agents.filter((a) => a.name !== name);
+  if (reg.agents.length === before) return false;
+  writeRegistry(reg);
+  return true;
+}
+
+// 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 : "";
+  if (!NAME_REGEX.test(name)) {
+    throw new Error(`name must match ${NAME_REGEX} (got "${name}")`);
+  }
+  if (findAgent(name)) {
+    throw new Error(`agent "${name}" is already registered with this nest`);
+  }
+  const args = ["run", "--as", "root", "--", "apes", "agents", "spawn", name];
+  const includeBridge = body?.bridge === true;
+  if (includeBridge) {
+    args.push("--bridge");
+    if (typeof body?.bridgeKey === "string") args.push("--bridge-key", body.bridgeKey);
+    if (typeof body?.bridgeBaseUrl === "string") args.push("--bridge-base-url", body.bridgeBaseUrl);
+    if (typeof body?.bridgeModel === "string") args.push("--bridge-model", body.bridgeModel);
+  }
+  ctx.log(`nest: spawning agent "${name}" via apes...`);
+  const { stdout: _stdout } = await execFileAsync(ctx.apesBin, args, { maxBuffer: 4 * 1024 * 1024 });
+  const uid = await readUidFromDscl(name);
+  const entry = {
+    name,
+    uid,
+    home: `/Users/${name}`,
+    email: "",
+    // filled in on first sync — we don't know it locally
+    registeredAt: Math.floor(Date.now() / 1e3),
+    bridge: includeBridge ? {
+      baseUrl: typeof body?.bridgeBaseUrl === "string" ? body.bridgeBaseUrl : void 0,
+      apiKey: typeof body?.bridgeKey === "string" ? body.bridgeKey : void 0,
+      model: typeof body?.bridgeModel === "string" ? body.bridgeModel : void 0
+    } : void 0
+  };
+  upsertAgent(entry);
+  ctx.supervisor.reconcile(listAgents());
+  return { name, email: entry.email, uid, home: entry.home };
+}
+async function handleAgentDestroy(ctx, name) {
+  if (!NAME_REGEX.test(name)) throw new Error(`invalid agent name "${name}"`);
+  const entry = findAgent(name);
+  if (!entry) throw new Error(`agent "${name}" not registered with this nest`);
+  ctx.supervisor.stop(name);
+  ctx.log(`nest: destroying agent "${name}"...`);
+  const args = ["run", "--as", "root", "--", "apes", "agents", "destroy", name, "--force"];
+  await execFileAsync(ctx.apesBin, args, { maxBuffer: 4 * 1024 * 1024 });
+  removeAgent(name);
+  ctx.supervisor.reconcile(listAgents());
+  return { name, removed: true };
+}
+async function readUidFromDscl(name) {
+  try {
+    const { stdout } = await execFileAsync("/usr/bin/dscl", [".", "-read", `/Users/${name}`, "UniqueID"]);
+    const match = stdout.match(/UniqueID:\s*(\d+)/);
+    if (match) return Number(match[1]);
+  } catch {
+  }
+  return -1;
+}
+
+// src/lib/supervisor.ts
+import { spawn } from "child_process";
+var MIN_BACKOFF_MS = 1e3;
+var MAX_BACKOFF_MS = 6e4;
+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.
+   */
+  reconcile(desired) {
+    const desiredNames = new Set(desired.map((a) => a.name));
+    for (const [name] of this.children) {
+      if (!desiredNames.has(name)) this.stop(name);
+    }
+    for (const agent of desired) {
+      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]) => ({
+      name,
+      pid: s.child.pid ?? -1,
+      uptimeSec: Math.floor((now - s.startedAt) / 1e3),
+      consecutiveCrashes: s.consecutiveCrashes
+    }));
+  }
+  start(agent) {
+    if (this.children.has(agent.name)) return;
+    this.deps.log(`supervisor: starting ${agent.name}`);
+    this.spawnChild(agent, 0);
+  }
+  stop(name) {
+    const s = this.children.get(name);
+    if (!s) return;
+    this.deps.log(`supervisor: stopping ${name}`);
+    if (s.restartTimer) clearTimeout(s.restartTimer);
+    this.children.delete(name);
+    try {
+      s.child.kill("SIGTERM");
+    } 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 child = spawn(this.deps.apesBin, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false
+    });
+    child.stdout?.on("data", (chunk) => this.forwardLog(agent.name, "stdout", chunk));
+    child.stderr?.on("data", (chunk) => this.forwardLog(agent.name, "stderr", chunk));
+    const supervised = {
+      child,
+      consecutiveCrashes: prevCrashes,
+      startedAt: Date.now()
+    };
+    this.children.set(agent.name, supervised);
+    child.on("exit", (code, signal) => {
+      const stillManaged = this.children.get(agent.name) === supervised;
+      if (!stillManaged) return;
+      const ranLongEnough = Date.now() - supervised.startedAt > 3e4;
+      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`
+      );
+      supervised.restartTimer = setTimeout(() => {
+        if (this.children.get(agent.name) !== supervised) return;
+        this.children.delete(agent.name);
+        this.spawnChild(agent, nextCrashes);
+      }, backoff);
+    });
+  }
+  forwardLog(name, stream, chunk) {
+    const text = chunk.toString("utf8");
+    for (const line of text.split("\n")) {
+      const trimmed = line.trimEnd();
+      if (!trimmed) continue;
+      this.deps.log(`[${name}/${stream}] ${trimmed}`);
+    }
+  }
+};
+
+// 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";
+function log(line) {
+  process.stderr.write(`${(/* @__PURE__ */ new Date()).toISOString()}  ${line}
+`);
+}
+var supervisor = new Supervisor({ apesBin: APES_BIN, 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");
+  supervisor.stopAll();
+  server.close(() => process.exit(0));
+});
+process.on("SIGINT", () => {
+  log("nest: SIGINT \u2014 stopping supervisor");
+  supervisor.stopAll();
+  server.close(() => process.exit(0));
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@openape/nest",
+  "version": "0.2.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",
+  "private": false,
+  "bin": {
+    "openape-nest": "./dist/index.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ofetch": "^1.4.1",
+    "@openape/cli-auth": "0.3.0"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^7.6.1",
+    "@types/node": "^22.19.13",
+    "eslint": "^9.35.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "openape",
+    "nest",
+    "agent",
+    "control-plane",
+    "supervisor"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run"
+  }
+}