thursday-agent 0.17.2 → 0.19.0

package/bin/lock.mjs

@@ -3,8 +3,11 @@
 // the phone a second time, so every message was answered twice. The second is refused, and
 // told where the first one is.
 
+import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { backgroundJob } from "./background.mjs";
+import { thursdayCommand } from "./tools.mjs";
 
 /** Beside the database, and named so a checkout never commits it (`*.local.*`). */
 const LOCK_FILE = "server.local.lock";
@@ -18,14 +21,110 @@ export function runningOn(home) {
     return null;
   }
   if (!Number.isInteger(held?.pid) || held.pid === process.pid) return null;
+  if (!stillRuns(held)) return null;
+  return {
+    pid: held.pid,
+    url: String(held.url ?? ""),
+    // Null from `pnpm dev`, and from a server started before the lock said
+    version: typeof held.version === "string" ? held.version : null,
+    background: held.background === true,
+  };
+}
+
+/**
+ * Whether the process a lock names is still the one that wrote it. A lock left by a process
+ * that died without its exit (a kill -9, a power cut) names a pid another process may hold
+ * after a restart, which would refuse every start until the file was deleted by hand: the pid
+ * is the writer only if it started when the lock says. Where `ps` cannot say (Windows), or the
+ * lock predates its start time, the live pid is all there is.
+ */
+export function stillRuns(held) {
   try {
     // Signal 0 asks whether the process exists and sends nothing
     process.kill(held.pid, 0);
   } catch (error) {
     // Someone else's process by that id is still a live one
-    if (error?.code !== "EPERM") return null;
+    if (error?.code !== "EPERM") return false;
   }
-  return { pid: held.pid, url: String(held.url ?? "") };
+  // Compared in UTC: `ps` writes the reader's zone, and a server under launchd (no TZ), a
+  // terminal that exports one, or a Mac that moved zones since it started spelled one start
+  // two ways — the server read as gone, and a second one opened the same database. A lock
+  // written before `startedUtc` has `started` alone, in its writer's zone.
+  const [said, zone] =
+    typeof held.startedUtc === "string"
+      ? [held.startedUtc, "UTC"]
+      : [held.started, undefined];
+  if (typeof said !== "string") return true;
+  const started = startedAt(held.pid, zone);
+  return !started || started === said;
+}
+
+/**
+ * Whether the server holding this folder is `pid`, or runs under it: launchd knows a job by the
+ * process it started, and a version manager's shim (Volta's) starts node as its child rather
+ * than becoming it.
+ */
+export function heldBy(running, pid) {
+  if (!running || !pid) return false;
+  return (
+    running.pid === pid ||
+    Number(ps(["-o", "ppid=", "-p", String(running.pid)])) === pid
+  );
+}
+
+// LC_ALL=C: a start time is compared as `ps` wrote it, so both reads spell it alike
+const ps = (args, zone) =>
+  spawnSync("ps", args, {
+    encoding: "utf8",
+    env: { ...process.env, LC_ALL: "C", ...(zone ? { TZ: zone } : {}) },
+  }).stdout?.trim() ?? "";
+
+/**
+ * When a process started, to the second, as `ps` has it in `zone` (the reader's own when none).
+ * Empty where it cannot say.
+ */
+export const startedAt = (pid, zone) =>
+  ps(["-o", "lstart=", "-p", String(pid)], zone);
+
+/**
+ * Where a process runs, as `ps` has it: the terminal it is attached to (null when none), when
+ * it started, and what was typed there — the leader of its process group, `pnpm dev` or
+ * `npx thursday-agent`, not the Node process under it. Null where `ps` cannot say (Windows).
+ */
+function whereRuns(pid) {
+  const [tty, group, ...started] = ps([
+    "-o",
+    "tty=,pgid=,lstart=",
+    "-p",
+    String(pid),
+  ]).split(/\s+/);
+  if (!tty || !group) return null;
+  return {
+    terminal: tty === "??" || tty === "?" ? null : tty,
+    group,
+    // "Fri Sep 25 20:55:51 2026" to the minute, in the reader's zone: it is read, not compared
+    since: started.join(" ").replace(/:\d\d \d{4}$/, ""),
+    typed: ps(["-o", "command=", "-p", group]),
+  };
+}
+
+/**
+ * How to stop the server with this pid, said where it can be done. A person told only "stop
+ * it" looked for a terminal they could not find: the one it runs in is named, with a command
+ * that does the same from any terminal. One that runs in the background is started again by
+ * launchd, so it is stopped by stopping that. Lines to print, without indent.
+ */
+export function stopLines(pid, home) {
+  const where = whereRuns(pid);
+  if (where?.terminal)
+    return [
+      `It runs in a terminal (${where.terminal}${where.typed ? `, ${where.typed}` : ""}, since ${where.since}).`,
+      `Ctrl+C there, or from any terminal: kill -INT -${where.group}`,
+    ];
+  if (backgroundJob()?.home === home)
+    return [`It runs in the background. To stop it: ${thursdayCommand()} stop`];
+  if (where) return [`It runs in the background. To stop it: kill ${pid}`];
+  return ["Ctrl+C where it runs."];
 }
 
 /** Exits with where the running one is, when this folder already has a server. */
@@ -33,17 +132,34 @@ export function refuseSecond(home) {
   const running = runningOn(home);
   if (!running) return;
   console.error(
-    `\n  Thursday is already running on this data folder${running.url ? `: ${running.url}` : ""}\n  Open that one, or stop it first (Ctrl+C where it runs; one that starts with the\n  computer stops with: thursday autostart --off).\n`,
+    `\n  Thursday is already running on this data folder${running.url ? `: ${running.url}` : ""}\n  Open that one, or stop it first.\n${stopLines(
+      running.pid,
+      home,
+    )
+      .map((line) => `  ${line}\n`)
+      .join("")}`,
   );
   process.exit(1);
 }
 
 /** Marks this folder as served from here until this process ends. */
-export function holdFolder(home, url) {
+export function holdFolder(home, url, version) {
   const file = join(home, LOCK_FILE);
   try {
     mkdirSync(home, { recursive: true });
-    writeFileSync(file, `${JSON.stringify({ pid: process.pid, url })}\n`);
+    writeFileSync(
+      file,
+      `${JSON.stringify({
+        pid: process.pid,
+        startedUtc: startedAt(process.pid, "UTC") || undefined,
+        // What a starter from before `startedUtc` reads, in this process's zone
+        started: startedAt(process.pid) || undefined,
+        url,
+        version,
+        // Which one launchd started, so a stop can end it when launchd did not (background.mjs)
+        background: process.env.THURSDAY_BACKGROUND ? true : undefined,
+      })}\n`,
+    );
   } catch {
     // A folder that cannot be written is not a reason not to serve
     return;

package/bin/thursday.mjs

@@ -14,12 +14,19 @@ import {
   symlinkSync,
 } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import { backgroundJob, keepLogShort, offerBackground } from "./background.mjs";
 import { askToSetDatabaseAside, MIGRATION_FAILED_EXIT } from "./database.mjs";
-import { holdFolder, refuseSecond } from "./lock.mjs";
+import { holdFolder, runningOn, stopLines } from "./lock.mjs";
 import { freePort } from "./port.mjs";
-import { ROOT, toolPath } from "./tools.mjs";
+import {
+  commandFor,
+  DEFAULT_HOME,
+  openBrowser,
+  ROOT,
+  thursdayCommand,
+  toolPath,
+} from "./tools.mjs";
 
 const { version, name } = JSON.parse(
   await readFile(join(ROOT, "package.json"), "utf8"),
@@ -34,12 +41,16 @@ const flag = (name) => {
 };
 
 if (has("-h", "--help")) {
+  const command = thursdayCommand();
   console.log(`
   ${name} ${version}
 
   Usage
-    $ thursday [options]
-    $ thursday autostart [--off]   Start with the computer, macOS only
+    $ ${command} [options]          Start it here, in this terminal
+    $ ${command} start [options]    Keep it running in the background, and start it
+                                    when you log in (macOS)
+    $ ${command} stop               Stop it in the background
+    $ ${command} status             Whether it runs, where, and how to reach it
 
   Options
     --port <n>     Port to serve on (default 4747, or the next free one)
@@ -71,30 +82,112 @@ if (!APP) {
   process.exit(1);
 }
 
+// An exported `PORT=` with nothing in it asks for no port
+const asked = flag("port") ?? (process.env.PORT?.trim() || undefined);
+const home = resolve(flag("home") || process.env.THURSDAY_HOME || DEFAULT_HOME);
+
+// The background (background.mjs): each is the whole command, and never goes on to serve.
+// `autostart` and `autostart --off` are what earlier versions called start and stop.
+const said =
+  argv[0] === "autostart" ? (has("--off") ? "stop" : "start") : argv[0];
+const background = ["start", "stop", "status"].includes(said) ? said : null;
+/** A start that could not run it in the background, and serves in this terminal instead. */
+let fellBack = false;
+if (background) {
+  const { printStatus, startInBackground, stopBackground } = await import(
+    "./background.mjs"
+  );
+  if (background === "status") {
+    printStatus({ home });
+    process.exit(0);
+  }
+  if (background === "stop")
+    process.exit((await stopBackground({ home })) ? 0 : 1);
+  const started = await startInBackground({
+    root: ROOT,
+    home,
+    port: asked,
+    open: !has("--no-open"),
+    version,
+  });
+  if (started === true) process.exit(0);
+  // A person at a terminal still gets it running, there, for as long as it stays open, as the
+  // first run's question does. "held" is a folder something else serves already; a script
+  // gets the failure
+  if (started === "held" || !process.stdin.isTTY || !process.stdout.isTTY)
+    process.exit(1);
+  fellBack = true;
+}
+
 /**
- * The user's files: database, workspace, installed skills. An installed package
- * keeps them in the home folder, never inside the package — an upgrade replaces
- * that. A checkout keeps them in the checkout, which is where `pnpm dev` already
- * writes them (config.ts DATA_DIR): a build started here opens the data it was
- * developed against, not a second, empty one beside it.
+ * Leaves when this folder already has a server: a second one would take the next port, and
+ * serve the same calls, jobs and phone twice (lock.mjs). Run again, it is usually the app they
+ * came for — a second `npx` once its tab is closed — so that one opens instead. One of another
+ * version does not: they ran this one to have this one.
  */
-const DEFAULT_HOME = APP === ROOT ? join(homedir(), ".thursday") : ROOT;
+function leaveToRunning() {
+  const running = runningOn(home);
+  if (!running) return;
+  const other =
+    running.version && running.version !== version ? running.version : null;
+  const opens = Boolean(running.url) && !other && !has("--no-open");
+  // The copy in the background moves to this version by starting it from this one: through
+  // npx pinned, since a bare `npx thursday-agent` is whichever version npm resolves that day
+  const command = thursdayCommand();
+  const moves =
+    other && backgroundJob()?.home === home
+      ? `  To move it to ${version}: ${commandFor(
+          "start",
+          home,
+          command === "npx thursday-agent"
+            ? `npx thursday-agent@${version}`
+            : command,
+        )}\n`
+      : null;
+  console.log(
+    `\n  Thursday${other ? ` ${other}` : ""} is already running on this data folder${running.url ? `: ${running.url}` : ""}\n${
+      opens
+        ? "  Opened it in your browser.\n"
+        : (moves ??
+          (other
+            ? `  To run ${version} instead, stop that one and run this again.\n`
+            : ""))
+    }${
+      moves
+        ? ""
+        : stopLines(running.pid, home)
+            .map((line) => `  ${line}\n`)
+            .join("")
+    }`,
+  );
+  if (opens) openBrowser(running.url);
+  process.exit(other ? 1 : 0);
+}
 
-const asked = flag("port") ?? process.env.PORT;
-const home = resolve(flag("home") || process.env.THURSDAY_HOME || DEFAULT_HOME);
+// Before a port is picked
+leaveToRunning();
 
-// Turning it on or off is the whole command; it never goes on to serve.
-if (argv[0] === "autostart") {
-  const { autostart } = await import("./autostart.mjs");
-  await autostart({ root: ROOT, home, off: has("--off") });
-  process.exit(0);
+if (fellBack) console.log("  Running it in this terminal instead.");
+else {
+  // A first run in a terminal asks once whether to keep it running in the background; said
+  // yes, the background serves and this run is done
+  const chose = await offerBackground({
+    root: ROOT,
+    home,
+    port: asked,
+    open: !has("--no-open"),
+    version,
+  });
+  if (chose !== "terminal") process.exit(chose === "background" ? 0 : 1);
 }
-
-// Before a port is picked: a second server on this folder would take the next one
-refuseSecond(home);
+// The question waits as long as the person does, and a start takes a minute: a server another
+// terminal started on this folder meanwhile is the one to use, not a second beside it
+leaveToRunning();
 const port = String(await freePort(asked, home));
 const url = `http://localhost:${port}`;
-holdFolder(home, url);
+holdFolder(home, url, version);
+// launchd writes the background's output to a log that nothing else trims
+if (process.env.THURSDAY_BACKGROUND) keepLogShort(home);
 /** Where config.ts DB_PATH puts the database under the home. */
 const database = join(home, "local.db");
 
@@ -140,6 +233,15 @@ function start() {
       THURSDAY_URL: url,
       // Where a bot's shell finds playwright-cli (workspace.ts TOOL_PATH)
       THURSDAY_TOOL_PATH: toolPath().join(":"),
+      // How it was started and what the person types to run it, for Settings to say where it
+      // runs and how to stop or keep it (features/settings/running.ts)
+      THURSDAY_RUNS: process.env.THURSDAY_BACKGROUND
+        ? "background"
+        : process.stdin.isTTY
+          ? "terminal"
+          : "elsewhere",
+      THURSDAY_COMMAND: thursdayCommand(),
+      THURSDAY_START: commandFor("start", home),
       PORT: port,
       // This machine only. A voice agent with a shell is not a thing to expose.
       // Never inherited: Docker exports HOSTNAME as the container and some
@@ -162,18 +264,12 @@ function start() {
   });
 
   if (opened) return;
-  const open =
-    process.platform === "darwin"
-      ? ["open", [url]]
-      : process.platform === "win32"
-        ? ["cmd", ["/c", "start", "", url]]
-        : ["xdg-open", [url]];
   // After the port is listening, and only on a server still up: one that could
-  // not migrate is asking in the terminal. A browser that will not open is not a failure
+  // not migrate is asking in the terminal
   setTimeout(() => {
     if (opened || server.exitCode !== null) return;
     opened = true;
-    spawn(open[0], open[1], { stdio: "ignore" }).on("error", () => {});
+    openBrowser(url);
   }, 1500).unref();
 }
 start();

package/bin/tools.mjs

@@ -2,14 +2,85 @@
 // imports: this runs from the published `bin`, on a machine that has neither a
 // build nor a TypeScript loader.
 
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
 
 const require = createRequire(import.meta.url);
 
 /** The checkout, or the installed package. */
 export const ROOT = resolve(import.meta.dirname, "..");
 
+/**
+ * Where the copy that runs in the background is installed (background.mjs). Beside the
+ * default data folder, so everything the app keeps on the computer is under one folder.
+ */
+export const PROGRAM = join(homedir(), ".thursday", "app");
+
+/** The one copy with the dev script beside it; the package ships no `scripts`. */
+export const isCheckout = (root) =>
+  existsSync(join(root, "scripts", "dev.mts"));
+
+/**
+ * The user's files when no `--home` is given: database, workspace, installed skills. An
+ * installed package keeps them in the home folder, never inside the package — an upgrade
+ * replaces that. A checkout keeps them in the checkout, which is where `pnpm dev` already
+ * writes them (config.ts DATA_DIR): a build started here opens the data it was developed
+ * against, not a second, empty one beside it.
+ */
+export const DEFAULT_HOME = isCheckout(ROOT)
+  ? ROOT
+  : join(homedir(), ".thursday");
+
+/**
+ * What this person types to run the app, for a line that tells them to run it again. Only a
+ * global install puts `thursday` on the PATH: said to someone who ran `npx`, it is a command
+ * they do not have. npx names itself in npm_lifecycle_event and unpacks into its `_npx` cache,
+ * and the copy that runs in the background was put there from one.
+ */
+export function thursdayCommand() {
+  // Written into the background job by the command that started it, which knew
+  if (process.env.THURSDAY_COMMAND?.trim())
+    return process.env.THURSDAY_COMMAND.trim();
+  if (
+    process.env.npm_lifecycle_event === "npx" ||
+    ROOT.includes(`${sep}_npx${sep}`) ||
+    ROOT.startsWith(`${PROGRAM}${sep}`)
+  )
+    return "npx thursday-agent";
+  if (isCheckout(ROOT)) return "pnpm start";
+  return "thursday";
+}
+
+/**
+ * The line to type for `sub` — start, stop, status, or "" to run it in a terminal — on this
+ * data folder: `--home` is said when it is not the one the command finds by itself. Followed
+ * as printed without it, a line served another folder, an empty app or a checkout's own data.
+ */
+export function commandFor(sub, home, command = thursdayCommand()) {
+  const line = sub ? `${command} ${sub}` : command;
+  return home && resolve(home) !== DEFAULT_HOME
+    ? `${line} --home ${shellWord(home)}`
+    : line;
+}
+
+/** A path a shell reads back as it is: quoted once it holds more than plain characters. */
+const shellWord = (path) =>
+  /^[\w@%+=:,./-]+$/.test(path) ? path : `'${path.replaceAll("'", `'\\''`)}'`;
+
+/** A browser that will not open is not a failure. */
+export function openBrowser(url) {
+  const [command, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  spawn(command, args, { stdio: "ignore" }).on("error", () => {});
+}
+
 /**
  * The `playwright-cli` entry, resolved rather than guessed: pnpm keeps it under
  * `.pnpm`, npm hoists it, npx puts it in a temp tree. Null when it is not

package/database/migrations/20260926021847_thread_cache_tokens/migration.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `thread` ADD `cache_read_tokens` integer DEFAULT 0 NOT NULL;--> statement-breakpoint
+ALTER TABLE `thread` ADD `cache_write_tokens` integer DEFAULT 0 NOT NULL;