pi-onlyne 1.2.1 → 2.0.0

package/src/background-subagents.mjs

@@ -0,0 +1,192 @@
+// The other question a background extension makes necessary: is work this
+// session dispatched through the `Agent` tool still running where the agent loop
+// cannot see it?
+//
+// The subagents extension is not one of the `pi-background-tasks` family, and
+// its `Agent` call is not one of those tools. A field test on one session showed
+// all five `Agent` calls issued in a single assistant message, each returning at
+// once with `Agent started in background` and an output file under
+// `/tmp/pi-subagents-<uid>/` — so the tool hands back a handle and the child
+// carries on, and no `tool_execution_start` / `tool_execution_end` pair brackets
+// it. The tool is not pi's own either: the string does not appear in pi's dist,
+// and pi's extension API exposes no subagent or background-task query at all,
+// only `getActiveTools` / `getAllTools` / `setActiveTools`. So there is no event
+// to subscribe to and no frame to ask for; what the extension leaves behind is
+// an on-disk registry at `~/.pi/subagents/missions/<uuid>.json`, and this probe
+// reads that.
+//
+// Every failure mode is inert, exactly as in `background-work.mjs`: no
+// directory, an unreadable file, a missing field, malformed JSON, or a read that
+// throws all read as "no subagent work known" and leave the plugin's own
+// judgement untouched. A probe that throws is worse than one that answers
+// nothing.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Mission statuses that mean the work is over.
+ *
+ * The live spelling was never observed. The machine this was measured on had
+ * four missions, all of them terminal (`completed`, `failed`, `cancelled` for
+ * missions; `completed`, `failed` for `workflowChildren`; `stopped`, `complete`,
+ * `failed` for `runs[].status`), so the running value is unenumerated. The safe
+ * direction is therefore "anything not on this list is live": guessing the other
+ * way would read a genuinely running session as idle, which is the exact bug
+ * this probe exists to fix. The cost of being wrong this way is a session that
+ * waits a little longer than it had to — a new terminal spelling delays the
+ * phase, it does not lose work.
+ */
+export const TERMINAL_MISSION_STATUSES = Object.freeze([
+  "cancelled",
+  "complete",
+  "completed",
+  "failed",
+  "stopped",
+]);
+
+/**
+ * How many mission files one call will open. The registry is one JSON object per
+ * mission and grows without bound over a machine's life, so an uncapped scan
+ * would make the probe cost a function of history while the caller only ever
+ * cares about the present. The cap trades that for a bounded read: a session
+ * whose live work sits past the cap is reported as not running, the same fail-safe
+ * direction as every other answer here, and the newest files are read first
+ * because those are the ones just dispatched.
+ */
+export const DEFAULT_MAX_MISSION_FILES = 200;
+
+/**
+ * How many bytes one mission file may be before it is skipped. A mission
+ * transcript, not a mission, is the large artefact; anything past this is not
+ * the status record this probe reads.
+ */
+export const DEFAULT_MAX_MISSION_BYTES = 256 * 1024;
+
+/** @param {unknown} status */
+export function isTerminalMissionStatus(status) {
+  return typeof status === "string" && TERMINAL_MISSION_STATUSES.includes(status);
+}
+
+/**
+ * @param {unknown} mission
+ * @param {string | null} sessionId this session's id, or `null` when unknown
+ */
+export function isLiveMission(mission, sessionId = null) {
+  if (!mission || typeof mission !== "object") return false;
+  // A mission with no status is not live: absence of evidence is absence of
+  // work, the same direction `background-work.mjs` fails safe in.
+  if (typeof mission.status !== "string" || !mission.status) return false;
+  if (isTerminalMissionStatus(mission.status)) return false;
+  const owner = mission.ownerSessionId;
+  if (typeof sessionId === "string" && sessionId) {
+    // Scope by owner so the answer is "is *this* session's work still running",
+    // not "is anything on this machine running".
+    return typeof owner === "string" && owner === sessionId;
+  }
+  // The caller cannot name its own session, so a mission naming no session still
+  // counts: watching a silent subset would be worse than watching too much.
+  return true;
+}
+
+/** Newest first, so a capped scan spends its budget on the missions just dispatched. */
+function byNewestFirst(left, right) {
+  const a = right.mtimeMs ?? 0;
+  const b = left.mtimeMs ?? 0;
+  if (a !== b) return a - b;
+  return String(right.name).localeCompare(String(left.name));
+}
+
+/** @returns {string[]} the `.json` mission files, newest first and already capped. */
+function missionFiles(directory, maxFiles) {
+  const entries = fs.readdirSync(directory, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => {
+      let mtimeMs = 0;
+      try {
+        mtimeMs = fs.statSync(path.join(directory, entry.name)).mtimeMs;
+      } catch {
+        /* an entry that will not stat sorts as oldest and may be cut by the cap */
+      }
+      return { name: entry.name, mtimeMs };
+    })
+    .sort(byNewestFirst)
+    .slice(0, maxFiles)
+    .map((entry) => path.join(directory, entry.name));
+}
+
+function readMission(file, maxBytes) {
+  if (fs.statSync(file).size > maxBytes) return null;
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+/**
+ * One live-mission question, asked of the on-disk registry and answered by
+ * whatever the subagents extension left there. Inert by construction: a throw
+ * anywhere inside resolves to `false`.
+ *
+ * @param {{
+ *   homeDir?: string,
+ *   getSessionId?: () => string | null,
+ *   log?: (line: string) => void,
+ *   maxFiles?: number,
+ *   maxBytes?: number,
+ * }} options
+ */
+export function createSubagentProbe({
+  homeDir = os.homedir(),
+  getSessionId = null,
+  log = () => {},
+  maxFiles = DEFAULT_MAX_MISSION_FILES,
+  maxBytes = DEFAULT_MAX_MISSION_BYTES,
+} = {}) {
+  const warned = new Set();
+
+  const warnOnce = (reason) => {
+    if (warned.has(reason)) return;
+    warned.add(reason);
+    log(`subagent work: ${reason}`);
+  };
+
+  const sessionId = () => {
+    if (typeof getSessionId !== "function") return null;
+    return getSessionId() ?? null;
+  };
+
+  /**
+   * @returns {Promise<boolean>}
+   */
+  function running() {
+    try {
+      const directory = path.join(homeDir, ".pi", "subagents", "missions");
+      if (!fs.existsSync(directory)) {
+        // No registry at all means the extension has never run here; that is a
+        // steady state rather than a fault, so it is recorded once.
+        warnOnce("no subagent registry in this home");
+        return false;
+      }
+      for (const file of missionFiles(directory, maxFiles)) {
+        let mission = null;
+        try {
+          mission = readMission(file, maxBytes);
+        } catch (error) {
+          warnOnce(`mission unreadable: ${error.message}`);
+          continue;
+        }
+        if (mission === null) {
+          warnOnce("mission record too large to be a status record");
+          continue;
+        }
+        if (isLiveMission(mission, sessionId())) return true;
+      }
+      return false;
+    } catch (error) {
+      warnOnce(`registry unreadable: ${error.message}`);
+      return false;
+    }
+  }
+
+  return { running };
+}

package/src/background-subagents.test.mjs

@@ -0,0 +1,166 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { test } from "node:test";
+
+import { createSubagentProbe } from "./background-subagents.mjs";
+
+const SESSION = "s-ours";
+const OTHER = "s-theirs";
+
+/** A throwaway home with a missions registry, as the extension leaves it. */
+function homeWith(files) {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "onlyne-subagents-"));
+  const missions = path.join(homeDir, ".pi", "subagents", "missions");
+  fs.mkdirSync(missions, { recursive: true });
+  for (const [name, body] of Object.entries(files)) {
+    fs.writeFileSync(path.join(missions, name), typeof body === "string" ? body : JSON.stringify(body));
+  }
+  return { homeDir, missions };
+}
+
+function probeFor(homeDir, sessionId = SESSION) {
+  const logs = [];
+  const probe = createSubagentProbe({
+    homeDir,
+    getSessionId: () => sessionId,
+    log: (line) => logs.push(line),
+  });
+  return { logs, probe };
+}
+
+test("a registry of terminal missions reads as not running", async () => {
+  const { homeDir } = homeWith({
+    "a.json": { id: "a", status: "completed", ownerSessionId: SESSION },
+    "b.json": { id: "b", status: "failed", ownerSessionId: SESSION },
+    "c.json": { id: "c", status: "cancelled", ownerSessionId: SESSION },
+  });
+  const { probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), false);
+});
+
+test("a mission whose status is not terminal reads as running", async () => {
+  // The live spelling was never observed, so any unrecognised value is treated as
+  // live; that is the safe direction, and this is what it looks like in a test.
+  const { homeDir } = homeWith({
+    "a.json": { id: "a", status: "running", ownerSessionId: SESSION },
+    "b.json": { id: "b", status: "something-new", ownerSessionId: SESSION },
+  });
+  const { probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), true);
+});
+
+test("a mission owned by this session reads as running and another session's does not", async () => {
+  const theirs = homeWith({ "a.json": { id: "a", status: "running", ownerSessionId: OTHER } });
+  const { probe: other } = probeFor(theirs.homeDir, SESSION);
+  assert.equal(await other.running(), false, "another session's live mission is not this session's work");
+
+  const ours = homeWith({ "a.json": { id: "a", status: "running", ownerSessionId: SESSION } });
+  const { probe: mine } = probeFor(ours.homeDir, SESSION);
+  assert.equal(await mine.running(), true);
+});
+
+test("a caller that cannot name its own session counts a mission naming none", async () => {
+  const { homeDir } = homeWith({ "a.json": { id: "a", status: "running" } });
+  const { probe } = probeFor(homeDir, null);
+
+  assert.equal(await probe.running(), true, "watching a silent subset is worse than watching too much");
+});
+
+test("a missing registry reads as not running and does not throw", async () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "onlyne-subagents-empty-"));
+  const { logs, probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), false);
+  assert.equal(logs.length, 1, "the missing registry is said once");
+  assert.equal(await probe.running(), false);
+  assert.equal(logs.length, 1, "and not repeated on the next call");
+});
+
+test("a missions path that is a file rather than a directory reads as not running", async () => {
+  const homeDir = fs.mkdtempSync(path.join(os.tmpdir(), "onlyne-subagents-file-"));
+  const missions = path.join(homeDir, ".pi", "subagents");
+  fs.mkdirSync(missions, { recursive: true });
+  fs.writeFileSync(path.join(missions, "missions"), "not a directory");
+  const { probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), false);
+});
+
+test("an unreadable mission file reads as not running and does not throw", async () => {
+  const { homeDir, missions } = homeWith({ "a.json": { id: "a", status: "completed" } });
+  fs.writeFileSync(path.join(missions, "b.json"), "{ not json");
+  fs.mkdirSync(path.join(missions, "c.json")); // a directory where a file is expected
+  fs.chmodSync(missions, 0o000);
+  const { probe } = probeFor(homeDir);
+  try {
+    assert.equal(await probe.running(), false);
+  } finally {
+    fs.chmodSync(missions, 0o755);
+  }
+});
+
+test("a mission with no status reads as not running", async () => {
+  const { homeDir } = homeWith({
+    "a.json": { id: "a", ownerSessionId: SESSION },
+    "b.json": { id: "b", status: null, ownerSessionId: SESSION },
+    "c.json": { id: "c", status: 42, ownerSessionId: SESSION },
+  });
+  const { probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), false);
+});
+
+test("malformed JSON in a live-looking registry still answers", async () => {
+  const { homeDir, missions } = homeWith({ "a.json": "<<<not json>>>" });
+  fs.writeFileSync(path.join(missions, "b.json"), JSON.stringify({ status: "running", ownerSessionId: SESSION }));
+  const { probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), true, "one bad file does not hide a live mission");
+});
+
+test("a mission larger than the byte bound is skipped, and the rest of the registry still answers", async () => {
+  const { homeDir, missions } = homeWith({
+    "a.json": { id: "a", status: "completed", ownerSessionId: SESSION, summary: "x".repeat(4096) },
+  });
+  fs.writeFileSync(path.join(missions, "huge.json"), JSON.stringify({
+    status: "running",
+    ownerSessionId: SESSION,
+    transcript: "x".repeat(300 * 1024),
+  }));
+  const { logs, probe } = probeFor(homeDir);
+
+  assert.equal(await probe.running(), false);
+  assert.equal(logs.some((line) => line.includes("too large")), true);
+});
+
+test("a capped read spends its budget on the newest missions", async () => {
+  // The cap is asserted by which file the probe read, so each case puts the live
+  // mission on one side of the cap and the terminal one on the other.
+  const registry = {
+    "old.json": { id: "old", status: "running", ownerSessionId: SESSION },
+    "new.json": { id: "new", status: "completed", ownerSessionId: SESSION },
+  };
+  const { homeDir, missions } = homeWith(registry);
+  const old = new Date(Date.now() - 60_000);
+  fs.utimesSync(path.join(missions, "old.json"), old, old);
+  const capped = createSubagentProbe({ homeDir, getSessionId: () => SESSION, maxFiles: 1 });
+
+  // Only the newer file is inside the cap, and it is terminal.
+  assert.equal(await capped.running(), false);
+
+  // The same cap, the same two files, with the newer one now live: the answer
+  // flips only because the newer file is the one that got read.
+  fs.writeFileSync(
+    path.join(missions, "new.json"),
+    JSON.stringify({ id: "new", status: "running", ownerSessionId: SESSION }),
+  );
+  assert.equal(await createSubagentProbe({
+    homeDir,
+    getSessionId: () => SESSION,
+    maxFiles: 1,
+  }).running(), true);
+});

package/src/config.mjs

@@ -6,8 +6,7 @@
 // generate-time template advice), so the only consumer is this extension. A
 // malformed or missing file falls back to the defaults and reports a warning
 // instead of disabling the session: the extension's own `enabled` key is the one
-// deliberate off switch. A key whose value is unusable — the idle bound below,
-// say — keeps the one default it names and leaves the rest of the file alone.
+// deliberate off switch.
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -15,18 +14,10 @@ import { join } from "node:path";
 /** Where the switch file lives, relative to the pi working directory. */
 export const CONFIG_RELATIVE_PATH = join(".pi", "onlyne.json");
 
-/**
- * How many idle reminders one task may collect before the ladder fails it
- * (`agent.mjs` `settleNow`): two, so the third idle without a completion is the
- * failure.
- */
-export const DEFAULT_IDLE_REMINDERS = 2;
-
-/** Defaults: on, connecting as soon as a session starts, and the idle bound. */
+/** Defaults: on, and connecting as soon as a session starts. */
 export const DEFAULT_CONFIG = Object.freeze({
   enabled: true,
   autoStart: true,
-  idleReminders: DEFAULT_IDLE_REMINDERS,
 });
 
 /**
@@ -34,7 +25,7 @@ export const DEFAULT_CONFIG = Object.freeze({
  *
  * @param {string} cwd
  * @param {{ readFile?: (path: string) => string }} [options]
- * @returns {{ enabled: boolean, autoStart: boolean, idleReminders: number, path: string, warning: string | null, present: boolean }}
+ * @returns {{ enabled: boolean, autoStart: boolean, path: string, warning: string | null, present: boolean }}
  */
 export function loadConfig(cwd, options = {}) {
   const readFile = options.readFile ?? ((path) => readFileSync(path, "utf8"));
@@ -60,21 +51,11 @@ export function loadConfig(cwd, options = {}) {
     return { ...DEFAULT_CONFIG, path, warning: `${path} must hold a JSON object; using defaults`, present: true };
   }
   const watch = parsed.watch && typeof parsed.watch === "object" ? parsed.watch : {};
-  // The bound is a count, so only a non-negative integer is a value: a string,
-  // a fraction or a negative would either count nothing or count forever.
-  // Zero is a value — it says the first idle without a completion is already
-  // the failure — and it is the operator's call to make.
-  const idleReminders = parsed.idleReminders;
-  const usable = Number.isInteger(idleReminders) && idleReminders >= 0;
   return {
     enabled: typeof parsed.enabled === "boolean" ? parsed.enabled : DEFAULT_CONFIG.enabled,
     autoStart: typeof watch.autoStart === "boolean" ? watch.autoStart : DEFAULT_CONFIG.autoStart,
-    idleReminders: usable ? idleReminders : DEFAULT_CONFIG.idleReminders,
     path,
-    warning:
-      idleReminders !== undefined && !usable
-        ? `${path} idleReminders must be a non-negative integer; using ${DEFAULT_CONFIG.idleReminders}`
-        : null,
+    warning: null,
     present: true,
   };
 }

package/src/config.test.mjs

@@ -8,8 +8,6 @@ import assert from "node:assert/strict";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
 import { afterEach, test } from "node:test";
 
 import { CONFIG_RELATIVE_PATH, DEFAULT_CONFIG, loadConfig, sessionIdentity } from "./config.mjs";
@@ -80,9 +78,3 @@ test("the session identity gate needs all three variables", () => {
   assert.equal(sessionIdentity({}), null);
   assert.equal(sessionIdentity({ ONLYNE_ROLE: "", ONLYNE_SESSION_ID: "s", ONLYNE_TASK_ID: "t" }), null);
 });
-
-test("the shipped switch file documents only the keys the plugin reads", () => {
-  const path = fileURLToPath(new URL("../onlyne.json.example", import.meta.url));
-  const example = JSON.parse(readFileSync(path, "utf8"));
-  assert.deepEqual(example, { enabled: true, watch: { autoStart: true } });
-});