byollm 0.1.0-alpha.39 → 0.1.0-alpha.40

package/README.md

@@ -1,5 +1,5 @@
 > [!WARNING]
-> **Alpha (`0.1.0-alpha.39`) — under active development. Don't use this yet.**
+> **Alpha (`0.1.0-alpha.40`) — under active development. Don't use this yet.**
 >
 > Install it deliberately: `npx byollm@alpha`, or `npm install byollm@alpha`.
 >
@@ -85,12 +85,25 @@
 > packages published and `@byollm/server` did not: a Sigstore
 > transparency-log 409 on its provenance attestation. The workflow's
 > "already published" guard correctly refuses to resume a partial publish,
-> so `0.1.0-alpha.39` is that release, whole.
+> so `0.1.0-alpha.40` is that release, whole.
 >
 > If you run the Supabase adapter, `alpha.21` needs
 > `20260819010000_completed_by_lease_id.sql`: alpha.19 shipped §3.6's
 > ordering without the column it stores the grant in.
 
+<!-- release-note 0.1.0-alpha.40 -->
+**`byollm install` — stop keeping a terminal open.** The daemon can now run
+under your machine's own supervisor and restart itself if it stops: a launchd
+agent on macOS, a `systemd --user` unit on Linux, a logon task on Windows. All
+user-level — no root, no system directories, and `byollm uninstall` takes it
+away. `byollm status` gained a line saying whether it is actually supervised
+right now, including the state that matters most: installed but not running,
+which looks fine from an app's dashboard and serves nothing.
+
+If you are running via `npx`, install properly first (`npm install -g
+byollm@alpha`) — `install` refuses to supervise a copy in npx's cache, because
+npm deletes that directory and the service would fail at some later boot.
+
 # `byollm`
 
 What end users run. Connects **outbound** to an app you trust, claims only the
@@ -158,6 +171,39 @@ URL, a path or a flag — there is no field on the wire for any of them.
 therefore advertised. A backend that is down is never advertised, so you never
 get work you cannot run.
 
+## Keep it running
+
+By default `byollm connect` and `byollm run` hold a terminal — close the
+window and the machine stops serving. Nothing breaks (your pairings live in
+`~/.byollm/pairings.json` and survive), but the machine goes quiet without
+telling anyone, and if it is on a team's roster, the first person to notice is
+a teammate whose job did not run.
+
+```bash
+byollm install     # keep running in the background, and restart if it stops
+byollm status      # says whether it is actually supervised right now
+byollm uninstall
+```
+
+It installs at the user level on every platform — a launchd `LaunchAgent` on
+macOS, a `systemd --user` unit on Linux, a logon task on Windows. No root, no
+system directories: it runs as you, it stops when you say so, and you can read
+every file it wrote. Output goes to `~/.byollm/service.log` on all three.
+
+Two things worth knowing:
+
+- **Install `byollm` properly first.** `byollm install` refuses to supervise a
+  copy running from `npx`'s cache, because npm deletes that directory without
+  warning and the service would stop working at some later boot with nothing
+  to show for it. `npm install -g byollm@alpha` first.
+- **On Linux, `systemd --user` stops when you log out** unless lingering is
+  enabled. `byollm install` prints the one command for that rather than
+  running it — it changes something outside your session, so it is your call.
+
+`byollm status` reports three states, not two: running under supervision,
+*installed but not running* (the one that looks fine from an app's dashboard
+and serves nothing), and not installed at all.
+
 ## The trust surface
 
 The meter is the product, and it gets the same care as the loop.

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   main
-} from "./chunk-GBQBJAT7.js";
+} from "./chunk-RYUKSHXG.js";
 
 // src/bin.ts
 process.exitCode = await main(process.argv.slice(2));

package/dist/{chunk-GBQBJAT7.js → chunk-RYUKSHXG.js}

@@ -96,9 +96,9 @@ function normalizeOrigin(input) {
 }
 
 // src/cli.ts
-import { mkdir as mkdir7, readFile as readFile8, rm as rm4, stat as stat2, writeFile as writeFile7 } from "fs/promises";
+import { mkdir as mkdir8, readFile as readFile8, rm as rm5, stat as stat2, writeFile as writeFile8 } from "fs/promises";
 import { hostname, userInfo } from "os";
-import { dirname as dirname7 } from "path";
+import { dirname as dirname8 } from "path";
 import { createInterface } from "readline/promises";
 import { backendDescriptor as backendDescriptor3, resolveCost as resolveCost2 } from "@byollm/protocol";
 
@@ -3023,6 +3023,273 @@ function sleep(ms, signal) {
   });
 }
 
+// src/install.ts
+import { mkdir as mkdir7, rm as rm4, writeFile as writeFile7 } from "fs/promises";
+import { dirname as dirname7 } from "path";
+
+// src/service.ts
+import { homedir as homedir2 } from "os";
+import { join as join3 } from "path";
+var SERVICE_LABEL = "cloud.byollm.daemon";
+function xml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+function servicePlan(target) {
+  const home = target.home ?? homedir2();
+  const root = target.root ?? join3(home, ".byollm");
+  const logPath = join3(root, "service.log");
+  const { execPath, scriptPath } = target;
+  if (target.platform === "darwin") {
+    const unitPath2 = join3(
+      home,
+      "Library",
+      "LaunchAgents",
+      `${SERVICE_LABEL}.plist`
+    );
+    const unitContents2 = `<?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>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(execPath)}</string>
+    <string>${xml(scriptPath)}</string>
+    <string>run</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>StandardOutPath</key><string>${xml(logPath)}</string>
+  <key>StandardErrorPath</key><string>${xml(logPath)}</string>
+  <key>ProcessType</key><string>Background</string>
+</dict>
+</plist>
+`;
+    const domain = `gui/${String(target.uid ?? 0)}`;
+    return {
+      platform: "darwin",
+      unitPath: unitPath2,
+      unitContents: unitContents2,
+      activate: [
+        ["launchctl", "bootout", domain, unitPath2],
+        ["launchctl", "bootstrap", domain, unitPath2],
+        ["launchctl", "enable", `${domain}/${SERVICE_LABEL}`]
+      ],
+      deactivate: [["launchctl", "bootout", domain, unitPath2]],
+      query: ["launchctl", "print", `${domain}/${SERVICE_LABEL}`],
+      logPath,
+      supervisor: "launchd"
+    };
+  }
+  if (target.platform === "linux") {
+    const unitPath2 = join3(
+      home,
+      ".config",
+      "systemd",
+      "user",
+      `${SERVICE_LABEL}.service`
+    );
+    const unitContents2 = `[Unit]
+Description=byollm \u2014 run an app's LLM jobs on your own models
+Documentation=https://byo-llm.com/docs
+After=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${execPath} ${scriptPath} run
+Restart=always
+RestartSec=10
+# Output goes to the journal *and* to the same file the other platforms use,
+# so "where are the logs" has one answer in the docs.
+StandardOutput=append:${logPath}
+StandardError=append:${logPath}
+
+[Install]
+WantedBy=default.target
+`;
+    return {
+      platform: "linux",
+      unitPath: unitPath2,
+      unitContents: unitContents2,
+      activate: [
+        ["systemctl", "--user", "daemon-reload"],
+        ["systemctl", "--user", "enable", "--now", `${SERVICE_LABEL}.service`]
+      ],
+      deactivate: [
+        ["systemctl", "--user", "disable", "--now", `${SERVICE_LABEL}.service`],
+        ["systemctl", "--user", "daemon-reload"]
+      ],
+      query: ["systemctl", "--user", "is-active", `${SERVICE_LABEL}.service`],
+      logPath,
+      supervisor: "systemd (user)"
+    };
+  }
+  const unitPath = join3(root, "byollm-task.xml");
+  const unitContents = `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>byollm \u2014 run an app's LLM jobs on your own models</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger><Enabled>true</Enabled></LogonTrigger>
+  </Triggers>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>999</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions>
+    <Exec>
+      <Command>${xml(execPath)}</Command>
+      <Arguments>"${xml(scriptPath)}" run</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+`;
+  return {
+    platform: "win32",
+    unitPath,
+    unitContents,
+    activate: [
+      ["schtasks", "/create", "/tn", SERVICE_LABEL, "/xml", unitPath, "/f"],
+      ["schtasks", "/run", "/tn", SERVICE_LABEL]
+    ],
+    deactivate: [["schtasks", "/delete", "/tn", SERVICE_LABEL, "/f"]],
+    query: ["schtasks", "/query", "/tn", SERVICE_LABEL],
+    logPath,
+    supervisor: "Task Scheduler"
+  };
+}
+function refuseToSupervise(scriptPath) {
+  const ephemeral = /[/\\]_npx[/\\]|[/\\]\.npm[/\\]_cacache[/\\]|[/\\]npm-cache[/\\]_npx[/\\]/;
+  if (ephemeral.test(scriptPath)) {
+    return `this copy of byollm lives in npx's cache (${scriptPath}), which npm deletes without warning \u2014 a service pointing at it would stop working at some later boot, silently.
+
+  Install it properly first:  npm install -g byollm@alpha
+  Then:                       byollm install`;
+  }
+  return null;
+}
+
+// src/install.ts
+async function serviceState(plan, run2) {
+  const result = await run2(plan.query).catch(() => ({
+    code: 127,
+    output: ""
+  }));
+  if (result.code !== 0) return { state: "absent" };
+  if (plan.platform === "darwin") {
+    if (/\bstate = running\b/.test(result.output) || /\n\s*pid = \d+/.test(result.output)) {
+      return { state: "running" };
+    }
+    const last = /last exit (?:code|status) = (-?\d+)/.exec(result.output);
+    return {
+      state: "installed",
+      detail: last === null ? "loaded but not running" : `not running (last exit ${last[1] ?? "?"})`
+    };
+  }
+  if (plan.platform === "linux") {
+    const word = result.output.trim();
+    return word === "active" ? { state: "running" } : { state: "installed", detail: word === "" ? "not running" : word };
+  }
+  if (/\bRunning\b/.test(result.output)) return { state: "running" };
+  return { state: "installed", detail: "registered, not running" };
+}
+async function installService(target, run2) {
+  const plan = servicePlan(target);
+  const refusal = refuseToSupervise(target.scriptPath);
+  if (refusal !== null) {
+    return { ok: false, lines: [refusal], plan };
+  }
+  await mkdir7(dirname7(plan.unitPath), { recursive: true });
+  await writeFile7(plan.unitPath, plan.unitContents, "utf8");
+  for (const [index, command] of plan.activate.entries()) {
+    const result = await run2(command);
+    const mayFail = plan.platform === "darwin" && index === 0;
+    if (result.code !== 0 && !mayFail) {
+      return {
+        ok: false,
+        plan,
+        lines: [
+          `wrote ${plan.unitPath}, but ${plan.supervisor} refused it:`,
+          "",
+          `  ${command.join(" ")}`,
+          `  exit ${String(result.code)}${result.output.trim() === "" ? "" : `: ${result.output.trim()}`}`,
+          "",
+          `The daemon is not supervised. \`byollm run\` still works in a terminal.`
+        ]
+      };
+    }
+  }
+  const lines = [
+    `Installed. ${plan.supervisor} will keep byollm running and restart it if it stops.`,
+    "",
+    `  service:  ${plan.unitPath}`,
+    `  log:      ${plan.logPath}`,
+    `  check:    byollm status`,
+    `  remove:   byollm uninstall`
+  ];
+  if (plan.platform === "linux") {
+    lines.push(
+      "",
+      "To keep serving after you log out:",
+      "",
+      "  sudo loginctl enable-linger $USER"
+    );
+  }
+  return { ok: true, plan, lines };
+}
+async function uninstallService(target, run2) {
+  const plan = servicePlan(target);
+  const failures = [];
+  for (const command of plan.deactivate) {
+    const result = await run2(command).catch(() => ({ code: 127, output: "" }));
+    if (result.code !== 0 && result.output.trim() !== "") {
+      failures.push(`  ${command.join(" ")} \u2014 ${result.output.trim()}`);
+    }
+  }
+  await rm4(plan.unitPath, { force: true });
+  return {
+    ok: true,
+    plan,
+    lines: [
+      `Removed. ${plan.supervisor} is no longer running byollm.`,
+      `Your pairings, allowlist and logs are untouched in ~/.byollm.`,
+      ...failures.length === 0 ? [] : [
+        "",
+        "The supervisor had something to say (usually harmless):",
+        ...failures
+      ]
+    ]
+  };
+}
+var spawnCommand = async (command) => {
+  const { spawn: spawn2 } = await import("child_process");
+  const [file, ...args] = command;
+  return new Promise((resolve) => {
+    const child = spawn2(file ?? "", args);
+    let output = "";
+    child.stdout.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    child.on("error", () => {
+      resolve({ code: 127, output });
+    });
+    child.on("close", (code) => {
+      resolve({ code: code ?? 0, output });
+    });
+  });
+};
+
 // src/cli.ts
 var USAGE = `byollm \u2014 run an app's LLM jobs on your own models.
 
@@ -3041,6 +3308,8 @@ var USAGE = `byollm \u2014 run an app's LLM jobs on your own models.
   byollm approve <site>       serve a site that asked (or --all)
   byollm forget <url>         drop a pairing
   byollm backends             what is installed, healthy, and advertised
+  byollm install              keep running in the background, across restarts
+  byollm uninstall            stop running in the background
 
 Config lives in ~/.byollm/config.json. Everything this daemon has ever run is
 in ~/.byollm/ingress.log \u2014 it is yours to read and yours to delete.
@@ -3055,6 +3324,7 @@ async function runCli(argv, options = {}) {
   const paths = options.paths ?? daemonPaths();
   const io = { ...defaultIo, ...options.io };
   const signal = options.signal;
+  const service = options.service ?? defaultServiceIo();
   switch (command) {
     case void 0:
     case "help":
@@ -3073,7 +3343,7 @@ async function runCli(argv, options = {}) {
     case "run":
       return commandRun(paths, rest, io, signal);
     case "status":
-      return commandStatus(paths, io);
+      return commandStatus(paths, io, service);
     case "log":
       return commandLog(paths, rest, io);
     case "pause":
@@ -3094,6 +3364,10 @@ async function runCli(argv, options = {}) {
       return commandForget(paths, rest, io);
     case "backends":
       return commandBackends(paths, io);
+    case "install":
+      return commandInstall(paths, io, service);
+    case "uninstall":
+      return commandUninstall(paths, io, service);
     default:
       io.err(`unknown command: ${command}
 
@@ -3101,6 +3375,59 @@ ${USAGE}`);
       return 2;
   }
 }
+function defaultServiceIo() {
+  return {
+    platform: process.platform === "win32" ? "win32" : process.platform === "darwin" ? "darwin" : "linux",
+    execPath: process.execPath,
+    scriptPath: process.argv[1] ?? "",
+    run: spawnCommand,
+    // `getuid` is absent on Windows, where nothing reads it.
+    uid: process.getuid?.() ?? 0
+  };
+}
+function serviceTarget(paths, service) {
+  return {
+    platform: service.platform,
+    execPath: service.execPath,
+    scriptPath: service.scriptPath,
+    ...service.home === void 0 ? {} : { home: service.home },
+    ...service.uid === void 0 ? {} : { uid: service.uid },
+    root: paths.root
+  };
+}
+async function commandInstall(paths, io, service) {
+  const result = await installService(
+    serviceTarget(paths, service),
+    service.run
+  );
+  for (const line of result.lines) (result.ok ? io.out : io.err)(`${line}
+`);
+  return result.ok ? 0 : 1;
+}
+async function commandUninstall(paths, io, service) {
+  const result = await uninstallService(
+    serviceTarget(paths, service),
+    service.run
+  );
+  for (const line of result.lines) io.out(`${line}
+`);
+  return 0;
+}
+async function supervisionLine(paths, service) {
+  const plan = servicePlan(serviceTarget(paths, service));
+  const state = await serviceState(plan, service.run);
+  switch (state.state) {
+    case "running":
+      return `service: running under ${plan.supervisor}
+`;
+    case "installed":
+      return `service: installed but NOT running (${state.detail}) \u2014 this machine is on rosters and serving nothing. See ${plan.logPath}
+`;
+    case "absent":
+      return `service: not installed \u2014 jobs only run while \`byollm run\` is open (\`byollm install\` fixes that)
+`;
+  }
+}
 async function commandName(paths, args, io) {
   const next = args[0];
   if (next === void 0) {
@@ -3108,8 +3435,8 @@ async function commandName(paths, args, io) {
 `);
     return 0;
   }
-  await mkdir7(dirname7(paths.label), { recursive: true });
-  await writeFile7(paths.label, `${next.slice(0, 120)}
+  await mkdir8(dirname8(paths.label), { recursive: true });
+  await writeFile8(paths.label, `${next.slice(0, 120)}
 `, { mode: 384 });
   io.out(
     `This machine will pair as ${next.slice(0, 120)}.
@@ -3446,7 +3773,7 @@ function report(origin, event, io) {
       break;
   }
 }
-async function commandStatus(paths, io) {
+async function commandStatus(paths, io, service) {
   const { loaded, ingress, allowlist, budgets, spend } = await context(paths);
   const pairings = new Pairings(paths.pairings);
   await pairings.load();
@@ -3459,8 +3786,9 @@ async function commandStatus(paths, io) {
 `
   );
   io.out(`state: ${paused ? "PAUSED" : "running"}
-
 `);
+  io.out(await supervisionLine(paths, service));
+  io.out("\n");
   io.out("paired apps\n");
   const list = pairings.list();
   if (list.length === 0) {
@@ -3585,15 +3913,15 @@ function indent(text) {
   return text.split("\n").map((line) => `           ${line}`).join("\n");
 }
 async function commandPause(paths, pause, io) {
-  await mkdir7(paths.root, { recursive: true });
+  await mkdir8(paths.root, { recursive: true });
   if (pause) {
-    await writeFile7(paths.pauseFlag, `${(/* @__PURE__ */ new Date()).toISOString()}
+    await writeFile8(paths.pauseFlag, `${(/* @__PURE__ */ new Date()).toISOString()}
 `);
     io.out(
       "paused \u2014 no new work will be claimed. `byollm resume` to start again.\n"
     );
   } else {
-    await rm4(paths.pauseFlag, { force: true });
+    await rm5(paths.pauseFlag, { force: true });
     io.out("resumed\n");
   }
   return 0;
@@ -3769,8 +4097,8 @@ Offer ${backendKey} to ${scope === "public" ? "anyone" : "people you have allowe
       ...cost === "metered" && !widening && backend.spend !== void 0 ? { spend: { ...backend.spend, acknowledged: false } } : {}
     };
   }
-  await mkdir7(dirname7(paths.config), { recursive: true });
-  await writeFile7(paths.config, `${JSON.stringify(result.data, null, 2)}
+  await mkdir8(dirname8(paths.config), { recursive: true });
+  await writeFile8(paths.config, `${JSON.stringify(result.data, null, 2)}
 `);
   const written = result.data.backends[backendKey].spend?.dailyCapCents;
   io.out(
@@ -3999,7 +4327,7 @@ async function main(argv) {
 }
 
 // src/index.ts
-var DAEMON_VERSION = "0.1.0-alpha.39";
+var DAEMON_VERSION = "0.1.0-alpha.40";
 function daemonVersion() {
   return {
     daemon: DAEMON_VERSION,
@@ -4051,4 +4379,4 @@ export {
   runCli,
   main
 };
-//# sourceMappingURL=chunk-GBQBJAT7.js.map
+//# sourceMappingURL=chunk-RYUKSHXG.js.map