agentglow 0.2.5 → 0.2.7

package/cli/agentglow.mjs

@@ -14,6 +14,7 @@ import {
   startBackground, stopServer,
 } from "./lib/server.mjs";
 import { which } from "./lib/uv.mjs";
+import { hasAutostart, installAutostart, launchdLogPath, loginPath, removeAutostart, stopLoginItem } from "./lib/autostart.mjs";
 
 const SELF = fileURLToPath(import.meta.url);
 const here = path.dirname(SELF);
@@ -31,6 +32,7 @@ const HELP = `agentglow ${VERSION}: watch Claude Code agents in 3D
   npx agentglow remove                undo setup: remove the hooks and stop the server
   npx agentglow claude [-- <args>]    try it without installing: one claude session with AgentGlow
 
+
 More: npx agentglow start [--background] [--port N]   (serve = start in the foreground)
 Env:  AGENTGLOW_URL (remote server), AGENTGLOW_API_KEY (ingest key), AGENTGLOW_CACHE_DIR
 `;
@@ -57,6 +59,8 @@ function parseArgs(argv) {
     else if (a === "--no-open") o.open = false;
     else if (a === "--install") o.install = true;
     else if (a === "--uninstall") o.uninstall = true;
+    else if (a === "--remove") o.remove = true;
+    else if (a === "--no-autostart") o.autostart = false;
     else if (a === "--background" || a === "-b") o.background = true;
     else if (a === "--quiet" || a === "-q") o.quiet = true;
     else if (a === "-h" || a === "--help") o.help = true;
@@ -154,9 +158,19 @@ async function cmdSetup(o) {
   if (remote) {
     if ((await probe(remote, 4000)) !== "agentglow") console.error(`agentglow: warning: ${remote}/live/health did not answer like AgentGlow.`);
   } else {
+    // Default: the OS owns the server (login item: launchd / systemd --user / Task Scheduler), so it is already
+    // running for every claude session, survives reboots and restarts on crash. The SessionStart hook installed
+    // above stays as a cheap safety net. If the login item can't be installed, the hook alone covers it.
+    // Login item by default on macOS/Linux only; Windows keeps per-session auto-start via the SessionStart hook
+    // (explicit `npx agentglow autostart` still registers one there).
+    const wantLogin = o.autostart === true || (o.autostart !== false && process.platform !== "win32");
+    const login = wantLogin ? installLoginItem(port) : null;
     try {
-      const s = await startLocal(port);
-      console.log(s.started ? `Started the AgentGlow server on port ${port}.` : `AgentGlow server already running on port ${port}.`);
+      if (login?.startsNow && (await waitHealthy(port, 120000))) console.log(`AgentGlow server is running on port ${port} (managed by ${login.method}).`);
+      else {
+        const s2 = await startLocal(port);
+        console.log(s2.started ? `Started the AgentGlow server on port ${port}.` : `AgentGlow server already running on port ${port}.`);
+      }
     } catch (e) {
       console.error(`agentglow: ${e.message}`);
       console.error(`The hooks are installed; start the server with: npx agentglow start --background${portFlag(port)}`);
@@ -168,6 +182,50 @@ async function cmdSetup(o) {
   return 0;
 }
 
+/** Register the server as a login item (launchd / systemd --user / Task Scheduler or Startup folder).
+ * Returns { method, path, startsNow } or null if it could not be installed (setup then relies on the hook). */
+function installLoginItem(port) {
+  const script = installCliCopy({ srcCliDir: here, version: VERSION });
+  const node = nodeForHook() || process.execPath;
+  const command = startHookCommand({ port, version: VERSION, node, script, cacheDir: process.env.AGENTGLOW_CACHE_DIR });
+  // macOS/Linux: the supervisor runs the server in the foreground (argv, no shell); Windows keeps the shell command
+  const argv = [node, script, "start", "--port", String(port)];
+  const env = { PATH: loginPath({ node }), HOME: os.homedir() };
+  for (const k of ["AGENTGLOW_CACHE_DIR", "AGENTGLOW_API_KEY", "AGENTGLOW_INGEST_KEY", "AGENTGLOW_SECRET", "AGENTGLOW_PY_SPEC"]) {
+    if (process.env[k]) env[k] = process.env[k];
+  }
+  try {
+    const r = installAutostart({ command, argv, env });
+    const logs = process.platform === "darwin" ? launchdLogPath() : process.platform === "win32" ? null : "journalctl --user -u agentglow";
+    console.log(`Server starts at login via ${r.method}${logs ? ` (logs: ${logs})` : ""}.`);
+    return { ...r, startsNow: process.platform !== "win32" };
+  } catch (e) {
+    console.error(`agentglow: note: could not register a login item (${e.message}); the server will start with each claude session instead.`);
+    return null;
+  }
+}
+
+async function waitHealthy(port, ms) {
+  const until = Date.now() + ms;
+  let said = false;
+  while (Date.now() < until) {
+    if ((await probe(localBase(port), 1500)) === "agentglow") return true;
+    if (!said && Date.now() > until - ms + 4000) { console.log("First start downloads Python + the server (~30-60s) ..."); said = true; }
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+  return false;
+}
+
+/** `autostart` = setup (which now includes the login item); `autostart --remove` = drop just the login item. */
+async function cmdAutostart(o) {
+  if (o.remove) {
+    removeAutostart();
+    console.log(`Removed the AgentGlow login item. The hooks stay; the server now starts with each claude session.`);
+    return 0;
+  }
+  return cmdSetup({ ...o, autostart: true });
+}
+
 async function cmdRemove(o) {
   const file = settingsFile();
   const r = uninstallSettingsFile(file);
@@ -178,11 +236,17 @@ async function cmdRemove(o) {
     if (st?.backup) console.log(`  Settings from before setup:     ${st.backup}  (restore: cp "${st.backup}" "${file}")`);
   } else console.log(`No AgentGlow entries in ${file}.`);
   const port = o.portSet ? o.port : st?.port || o.port;
-  if (!remoteUrl() && (st?.startHook || !st)) {
+  const login = hasAutostart();
+  if (!remoteUrl() && !login && (st?.startHook || !st)) {
     const s = await stopServer(port);
     if (s === "stopped") console.log(`Stopped the AgentGlow server on port ${port}.`);
     else if (s === "not-ours") console.log(`An AgentGlow server on port ${port} was not started by this CLI; left it running.`);
   }
+  if (login) {  // `remove` undoes everything, incl. the login item (it points at the CLI copy removed below)
+    removeAutostart();
+    await stopServer(port);  // in case a session-started server is also running
+    console.log(`Removed the AgentGlow login item and stopped its server.`);
+  }
   try { removeCliCopies(); } catch { /* ignore */ }
   return 0;
 }
@@ -254,6 +318,7 @@ async function cmdStatus(o) {
   console.log(`server:  ${health?.ok ? `healthy at ${base} (server ${health.version || "?"})` : starting ? `starting on port ${port}` : `not running at ${base}`}`);
   if (!remote) console.log(`port:    ${port}${pid ? `  pid ${pid} (started by this CLI)` : ""}`);
   console.log(`hooks:   ${installed ? `installed in ${file}${startHook ? " (server auto-starts with claude)" : ""}` : "not installed (run: npx agentglow setup)"}`);
+  if (hasAutostart()) console.log(`login:   server starts at login and restarts on crash`);
   if (health?.ok) console.log(`view:    ${base}/neural`);
   return 0;
 }
@@ -314,6 +379,8 @@ async function main() {
   switch (o.cmd) {
     case "setup":
       return cmdSetup(o);
+    case "autostart":
+      return cmdAutostart(o);
     case "remove":
     case "uninstall":
       return cmdRemove(o);
@@ -328,6 +395,10 @@ async function main() {
     case "stop": {
       const port = effectivePort(o);
       const r = await stopServer(port);
+      if (r === "not-ours" && hasAutostart() && stopLoginItem()) {
+        console.log(`Stopped the AgentGlow server on port ${port} (it starts again at next login or with the next claude session).`);
+        return 0;
+      }
       if (r === "stopped") console.log(`Stopped the AgentGlow server on port ${port}.`);
       else if (r === "not-ours") console.log(`The AgentGlow server on port ${port} was not started by this CLI; stop it where it runs.`);
       else console.log(`No AgentGlow server on port ${port}.`);

package/cli/lib/autostart.mjs

@@ -0,0 +1,159 @@
+// OS-native "start AgentGlow at login" (installed by `agentglow setup`): the server is always already running for
+// every claude session, survives reboots and is restarted on crash. macOS/Linux run it in the foreground under
+// launchd/systemd (argv); Windows uses Task Scheduler (or the Startup folder) with the hook's shell command.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const TASK_NAME = "AgentGlow";
+const LABEL = "com.agentglow.server";
+
+export const plistPath = (home = os.homedir()) => path.join(home, "Library", "LaunchAgents", `${LABEL}.plist`);
+export const systemdUnitPath = (home = os.homedir()) =>
+  path.join(home, ".config", "systemd", "user", "agentglow.service");
+export const startupScriptPath = (home = os.homedir()) =>
+  path.join(home, "AppData", "Roaming", "Microsoft", "Windows", "Start Menu", "Programs", "Startup", "AgentGlow.vbs");
+
+function winTaskCommand(command) {
+  // schtasks runs /tr through cmd.exe already; keep it a single quoted string, inner quotes escaped.
+  return `cmd /c "${command.replace(/"/g, '\\"')}"`;
+}
+
+// Runs hidden (no console flash) at login - no special privilege needed, just write access to the user's own
+// Startup folder, which (unlike Task Scheduler) corporate Group Policy essentially never locks down. Wrapped in
+// cmd /c like the Task Scheduler path (not run as a bare program) since `command` may use shell syntax (the "||
+// fallback to npx" from startHookCommand), which WshShell.Run can't interpret on its own.
+function startupVbs(command) {
+  const esc = winTaskCommand(command).replace(/"/g, '""');
+  return `Set WshShell = CreateObject("WScript.Shell")\r\nWshShell.Run "${esc}", 0, False\r\n`;
+}
+
+const xml = (v) => String(v).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+export const launchdLogPath = (home = os.homedir()) => path.join(home, "Library", "Logs", "agentglow.log");
+
+/** PATH for login-time jobs: launchd/systemd start with a bare PATH, so add where uv/uvx/node usually live. */
+export function loginPath({ home = os.homedir(), node = process.execPath, base = process.env.PATH || "" } = {}) {
+  const dirs = [path.dirname(node), path.join(home, ".local", "bin"), path.join(home, ".cargo", "bin"),
+    "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin", ...base.split(path.delimiter)];
+  return [...new Set(dirs.filter(Boolean))].join(path.delimiter);
+}
+
+// The server runs in the FOREGROUND under launchd/systemd (not `start --background`): a job whose process exits
+// right away gets its spawned children reaped, and a supervised foreground process can be restarted on crash.
+// `start` exits 0 when a server is already up on the port, so KeepAlive {SuccessfulExit: false} never loops.
+export function launchdPlist({ argv, env = {}, home = os.homedir() }) {
+  const args = argv.map((a) => `<string>${xml(a)}</string>`).join("");
+  const envs = Object.entries(env).map(([k, v]) => `<key>${xml(k)}</key><string>${xml(v)}</string>`).join("");
+  const log = xml(launchdLogPath(home));
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key><array>${args}</array>
+  <key>EnvironmentVariables</key><dict>${envs}</dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>ProcessType</key><string>Background</string>
+  <key>StandardOutPath</key><string>${log}</string>
+  <key>StandardErrorPath</key><string>${log}</string>
+</dict></plist>
+`;
+}
+
+export function systemdUnit({ argv, env = {} }) {
+  const q = (a) => (/[\s"\\]/.test(a) ? JSON.stringify(a) : a);
+  const envLines = Object.entries(env).map(([k, v]) => `Environment=${q(`${k}=${v}`)}`).join("\n");
+  return `[Unit]
+Description=AgentGlow server
+
+[Service]
+ExecStart=${argv.map(q).join(" ")}
+${envLines}
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/** Install an OS-level "run this command at login" entry. Returns { method, path? }. Throws on failure. */
+export function installAutostart({ command, argv, env = {}, platform = process.platform, home = os.homedir() } = {}) {
+  if (platform === "win32") {
+    try {
+      execFileSync("schtasks", ["/create", "/tn", TASK_NAME, "/tr", winTaskCommand(command), "/sc", "onlogon", "/rl", "limited", "/f"],
+        { stdio: "pipe" });
+      return { method: "Task Scheduler", name: TASK_NAME };
+    } catch (e) {
+      // Task Scheduler creation is commonly blocked by corporate Group Policy even for a user's own tasks;
+      // fall back to a Startup-folder launcher, which only needs normal write access to the user's own profile.
+      const file = startupScriptPath(home);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, startupVbs(command));
+      return { method: "Startup folder (Task Scheduler was blocked)", path: file };
+    }
+  }
+  if (platform === "darwin") {
+    const file = plistPath(home);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.mkdirSync(path.dirname(launchdLogPath(home)), { recursive: true });
+    fs.writeFileSync(file, launchdPlist({ argv, env, home }));
+    try { execFileSync("launchctl", ["unload", file], { stdio: "pipe" }); } catch { /* wasn't loaded */ }
+    execFileSync("launchctl", ["load", "-w", file], { stdio: "pipe" });  // RunAtLoad: starts it right now too
+    return { method: "launchd", path: file };
+  }
+  // linux and other unix: systemd --user
+  const file = systemdUnitPath(home);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, systemdUnit({ argv, env }));
+  execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "pipe" });
+  execFileSync("systemctl", ["--user", "enable", "--now", "agentglow"], { stdio: "pipe" });
+  return { method: "systemd --user", path: file };
+}
+
+/** Undo installAutostart(). Best-effort: never throws, so `remove` always completes. */
+export function removeAutostart({ platform = process.platform, home = os.homedir() } = {}) {
+  if (platform === "win32") {
+    try { execFileSync("schtasks", ["/delete", "/tn", TASK_NAME, "/f"], { stdio: "pipe" }); } catch { /* not installed */ }
+    try { fs.rmSync(startupScriptPath(home), { force: true }); } catch { /* ignore */ }
+    return;
+  }
+  if (platform === "darwin") {
+    const file = plistPath(home);
+    try { execFileSync("launchctl", ["unload", file], { stdio: "pipe" }); } catch { /* wasn't loaded */ }
+    try { fs.rmSync(file, { force: true }); } catch { /* ignore */ }
+    return;
+  }
+  try { execFileSync("systemctl", ["--user", "disable", "--now", "agentglow"], { stdio: "pipe" }); } catch { /* not installed */ }
+  try { fs.rmSync(systemdUnitPath(home), { force: true }); } catch { /* ignore */ }
+}
+
+/** Stop the login-item server for now (it starts again at next login / next claude session). Never throws. */
+export function stopLoginItem({ platform = process.platform } = {}) {
+  try {
+    if (platform === "darwin") execFileSync("launchctl", ["stop", LABEL], { stdio: "pipe" });
+    else if (platform === "win32") execFileSync("schtasks", ["/end", "/tn", TASK_NAME], { stdio: "pipe" });
+    else execFileSync("systemctl", ["--user", "stop", "agentglow"], { stdio: "pipe" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Best-effort check: is the autostart entry currently installed? Never throws. */
+export function hasAutostart({ platform = process.platform, home = os.homedir() } = {}) {
+  try {
+    if (platform === "win32") {
+      if (fs.existsSync(startupScriptPath(home))) return true;
+      execFileSync("schtasks", ["/query", "/tn", TASK_NAME], { stdio: "pipe" });
+      return true;
+    }
+    if (platform === "darwin") return fs.existsSync(plistPath(home));
+    return fs.existsSync(systemdUnitPath(home));
+  } catch {
+    return false;
+  }
+}

package/cli/lib/server.mjs

@@ -20,7 +20,10 @@ export function pySpecs(version, env = process.env) {
 }
 
 export function serveArgv(runner, spec, port) {
-  return [...runner.args, "--from", spec, "agentglow", "serve", "--host", "127.0.0.1", "--port", String(port)];
+  // a local checkout (AGENTGLOW_PY_SPEC=/path/to/backend): run it editable, uvx otherwise serves a stale cached build
+  const local = /^(\/|\.|~|[A-Za-z]:[\\/])/.test(spec);
+  return [...runner.args, ...(local ? ["--with-editable", spec] : []), "--from", spec,
+    "agentglow", "serve", "--host", "127.0.0.1", "--port", String(port)];
 }
 
 export function alive(pid) {
@@ -164,21 +167,25 @@ export function removeCliCopies() {
 export async function serveForeground({ port, version, log = console.error }) {
   const runner = await findRunner({ log });
   const specs = pySpecs(version);
+  let stopping = false;
   for (const [i, spec] of specs.entries()) {
     const t0 = Date.now();
     const code = await new Promise((resolve) => {
       const child = spawn(runner.cmd, serveArgv(runner, spec, port), { stdio: "inherit" });
-      const fwd = (sig) => () => child.kill(sig);
+      // A requested stop (Ctrl-C, `launchctl stop`, `systemctl stop`) must exit 0, or a supervisor with
+      // "restart unless it exited successfully" (launchd KeepAlive/SuccessfulExit) would bring it right back.
+      const fwd = (sig) => () => { stopping = true; child.kill(sig); };
       const onInt = fwd("SIGINT"), onTerm = fwd("SIGTERM");
       process.on("SIGINT", onInt);
       process.on("SIGTERM", onTerm);
       child.on("exit", (c, sig) => {
         process.off("SIGINT", onInt);
         process.off("SIGTERM", onTerm);
-        resolve(c ?? (sig ? 130 : 1));
+        resolve(stopping ? 0 : (c ?? (sig ? 130 : 1)));
       });
     });
     // a pinned version missing on PyPI fails fast; fall back to latest once
+    if (stopping) return 0;
     if (code !== 0 && i < specs.length - 1 && Date.now() - t0 < 30000) {
       log(`${spec} failed, retrying with the latest agentglow ...`);
       continue;