pi-onlyne 1.2.0 → 1.2.1

package/src/background-work.mjs

@@ -0,0 +1,176 @@
+// The one question a background-task extension makes necessary: is this
+// session's work still running somewhere the agent loop cannot see?
+//
+// `pi-background-tasks` and its relatives take a long command off the loop — the
+// tool call returns a task id at once and the child process carries on. pi then
+// waits for input while the work runs, so `ctx.isIdle()` alone would report a
+// session as idle with a task in flight. This probe reads the extension's own
+// live task list over the pi EventBus, and only when the extension is installed:
+// without one of its tools there is nothing to recognise, nothing to query, and
+// nothing to wait for.
+//
+// The contract is that package's documented `eventbus-v1` surface
+// (`pi-background-tasks/docs/api/eventbus-v1.md`): one request frame in, one
+// response frame out, both closed objects carrying a schema id. A response that
+// never arrives, a frame that does not parse, an error response, and a host with
+// no EventBus all read as "no background work known" and leave the plugin's own
+// judgement untouched.
+
+/** The tools that mark the extension as installed. */
+export const BACKGROUND_TOOL_NAMES = Object.freeze([
+  "bg_run",
+  "bg_run_pi_attested",
+  "bg_status",
+  "bg_logs",
+  "bg_kill",
+  "bg_delegate",
+  "bg_result",
+  "fusion_reason",
+  "fusion_investigate",
+  "fusion_research",
+  "fusion_validate",
+  "fusion_web_fetch",
+]);
+
+const REQUEST_CHANNEL = "pi-background-tasks:request:v1";
+const RESPONSE_CHANNEL = "pi-background-tasks:response:v1";
+const REQUEST_SCHEMA = "pi-background-tasks.extension-request.v1";
+const RESPONSE_SCHEMA = "pi-background-tasks.extension-response.v1";
+
+/** Task statuses that mean the work is still going. */
+const LIVE_TASK_STATUS = "running";
+
+/** How long one status query waits for its answer. */
+export const DEFAULT_STATUS_TIMEOUT_MS = 500;
+
+/** @param {string} name */
+export function isBackgroundTool(name) {
+  return BACKGROUND_TOOL_NAMES.includes(name);
+}
+
+let requestCounter = 0;
+
+function nextRequestId() {
+  requestCounter += 1;
+  return `onlyne-bg-status-${requestCounter}`;
+}
+
+function isResponseFor(frame, requestId) {
+  return frame
+    && typeof frame === "object"
+    && frame.schema_version === RESPONSE_SCHEMA
+    && frame.request_id === requestId;
+}
+
+/**
+ * One live-task question, asked of the EventBus and answered by whatever is
+ * listening. Every failure mode is inert: the probe reports `false` and says why
+ * once, then lets the caller's own judgement stand.
+ *
+ * @param {{
+ *   events?: { emit: (channel: string, data: unknown) => void, on: (channel: string, handler: (data: unknown) => void) => () => void } | null,
+ *   getToolNames?: () => string[] | null,
+ *   log?: (line: string) => void,
+ *   timeoutMs?: number,
+ * }} options
+ */
+export function createBackgroundProbe({
+  events = null,
+  getToolNames = null,
+  log = () => {},
+  timeoutMs = DEFAULT_STATUS_TIMEOUT_MS,
+} = {}) {
+  let installed = null;
+  const warned = new Set();
+  let unsubscribe = null;
+
+  const warnOnce = (reason) => {
+    if (warned.has(reason)) return;
+    warned.add(reason);
+    log(`background work: ${reason}`);
+  };
+
+  /** True once one of the extension's tools is registered; cached either way. */
+  function isInstalled() {
+    if (installed !== null) return installed;
+    let names = null;
+    try {
+      names = typeof getToolNames === "function" ? getToolNames() : null;
+    } catch (error) {
+      warnOnce(`tool list unreadable: ${error.message}`);
+      return false;
+    }
+    const list = Array.isArray(names) ? names : [];
+    installed = list.some(isBackgroundTool);
+    if (!installed) log("background work: no background-task extension in this session");
+    return installed;
+  }
+
+  /**
+   * One status round trip. The answer arrives on the response channel, so the
+   * listener lives exactly as long as the wait and the timer bounds it.
+   * @returns {Promise<boolean>}
+   */
+  function running() {
+    if (!isInstalled()) return Promise.resolve(false);
+    const bus = events;
+    if (!bus || typeof bus.emit !== "function" || typeof bus.on !== "function") {
+      warnOnce("event bus unavailable");
+      return Promise.resolve(false);
+    }
+    return new Promise((resolve) => {
+      const requestId = nextRequestId();
+      let settled = false;
+      let timer = null;
+      const finish = (answer) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (typeof unsubscribe === "function") unsubscribe();
+        unsubscribe = null;
+        resolve(answer);
+      };
+      try {
+        unsubscribe = bus.on(RESPONSE_CHANNEL, (frame) => {
+          if (!isResponseFor(frame, requestId)) return;
+          if (frame.ok !== true) {
+            warnOnce(`status query refused: ${String(frame.error ?? "unknown")}`);
+            finish(false);
+            return;
+          }
+          const tasks = frame.result?.tasks;
+          if (!Array.isArray(tasks)) {
+            warnOnce("status answer carried no task list");
+            finish(false);
+            return;
+          }
+          finish(tasks.some((task) => task?.status === LIVE_TASK_STATUS));
+        });
+        bus.emit(REQUEST_CHANNEL, {
+          schema_version: REQUEST_SCHEMA,
+          request_id: requestId,
+          operation: "status",
+          payload: {},
+        });
+      } catch (error) {
+        warnOnce(`status query failed: ${error.message}`);
+        finish(false);
+        return;
+      }
+      timer = setTimeout(() => {
+        warnOnce("status query timed out");
+        finish(false);
+      }, timeoutMs);
+      if (typeof timer?.unref === "function") timer.unref();
+    });
+  }
+
+  return {
+    installed: isInstalled,
+    running,
+    close() {
+      if (typeof unsubscribe === "function") unsubscribe();
+      unsubscribe = null;
+    },
+  };
+}

package/src/background-work.test.mjs

@@ -0,0 +1,128 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { createBackgroundProbe } from "./background-work.mjs";
+
+const RESPONSE_CHANNEL = "pi-background-tasks:response:v1";
+const RESPONSE_SCHEMA = "pi-background-tasks.extension-response.v1";
+
+class FakeEventBus {
+  constructor(answer) {
+    this.answer = answer;
+    this.emits = [];
+    this.listeners = new Map();
+    this.drops = 0;
+  }
+
+  on(channel, handler) {
+    const handlers = this.listeners.get(channel) ?? new Set();
+    handlers.add(handler);
+    this.listeners.set(channel, handlers);
+    let active = true;
+    return () => {
+      if (!active) return;
+      active = false;
+      this.drops += 1;
+      handlers.delete(handler);
+    };
+  }
+
+  emit(channel, data) {
+    this.emits.push({ channel, data });
+    if (channel !== "pi-background-tasks:request:v1") return;
+    this.answer?.(data, (frame) => {
+      for (const handler of [...(this.listeners.get(RESPONSE_CHANNEL) ?? [])]) {
+        handler(frame);
+      }
+    });
+  }
+
+  listenerCount() {
+    return [...this.listeners.values()].reduce((total, handlers) => total + handlers.size, 0);
+  }
+}
+
+function response(request, body) {
+  return {
+    schema_version: RESPONSE_SCHEMA,
+    request_id: request.request_id,
+    ...body,
+  };
+}
+
+function probeFor(answer, timeoutMs = 20) {
+  const events = new FakeEventBus(answer);
+  const probe = createBackgroundProbe({
+    events,
+    getToolNames: () => ["bg_run"],
+    timeoutMs,
+  });
+  return { events, probe };
+}
+
+test("a session without a background-task tool makes no EventBus query", async () => {
+  const events = new FakeEventBus(() => {
+    assert.fail("an uninstalled background-task extension must not be queried");
+  });
+  const probe = createBackgroundProbe({
+    events,
+    getToolNames: () => ["read_file"],
+  });
+
+  assert.equal(await probe.running(), false);
+  assert.deepEqual(events.emits, []);
+  assert.equal(events.listenerCount(), 0);
+});
+
+test("a live background task answers true and drops the response listener", async () => {
+  const { events, probe } = probeFor((request, respond) => {
+    respond(response(request, { ok: true, result: { tasks: [{ status: "running" }] } }));
+  });
+
+  assert.equal(await probe.running(), true);
+  assert.equal(events.emits.length, 1);
+  assert.equal(events.listenerCount(), 0);
+  assert.equal(events.drops, 1);
+});
+
+test("a terminal background task list answers false and drops the response listener", async () => {
+  const { events, probe } = probeFor((request, respond) => {
+    respond(response(request, {
+      ok: true,
+      result: { tasks: [{ status: "completed" }, { status: "failed" }] },
+    }));
+  });
+
+  assert.equal(await probe.running(), false);
+  assert.equal(events.listenerCount(), 0);
+  assert.equal(events.drops, 1);
+});
+
+test("a refused status query answers false and drops the response listener", async () => {
+  const { events, probe } = probeFor((request, respond) => {
+    respond(response(request, { ok: false, error: "status unavailable" }));
+  });
+
+  assert.equal(await probe.running(), false);
+  assert.equal(events.listenerCount(), 0);
+  assert.equal(events.drops, 1);
+});
+
+test("a malformed status answer reads false and drops the response listener", async () => {
+  const { events, probe } = probeFor((request, respond) => {
+    respond(response(request, { ok: true, result: { tasks: "running" } }));
+  });
+
+  assert.equal(await probe.running(), false);
+  assert.equal(events.listenerCount(), 0);
+  assert.equal(events.drops, 1);
+});
+
+test("a background-task service that never answers reads false and drops the response listener", async () => {
+  const { events, probe } = probeFor(null, 10);
+
+  assert.equal(await probe.running(), false);
+  assert.equal(events.emits.length, 1);
+  assert.equal(events.listenerCount(), 0);
+  assert.equal(events.drops, 1);
+});

package/src/index.ts

@@ -9,9 +9,11 @@
 //
 //   session_start    -> read env + .pi/onlyne.json, connect, register tools
 //   turn_start       -> heartbeat{running}
-//   turn_end         -> heartbeat{idle}; the settle window opens
+//   turn_end         -> one turn of a run ended; the phase is re-derived from pi
+//                       and the settle window opens
 //   message_end      -> keep the last assistant text; a failed turn is `failed`
-//   agent_settled    -> settle decision: the idle ladder, or `failed` at once
+//   agent_settled    -> heartbeat{idle} when the session waits for input, then
+//                       the settle decision: the idle ladder, or `failed` at once
 //   session_shutdown -> detach{reason}
 
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -68,6 +70,10 @@ interface PiSurface {
   status(text: string): void;
   welcome(welcome: WelcomeLike): void;
   isIdle(): boolean;
+  /** The phase rule: true only while the session waits for user input. */
+  waitingForInput(): Promise<boolean>;
+  /** Drops the background-task probe's EventBus subscription. */
+  closeBackground?(): void;
   exit(reason: string): void;
 }
 
@@ -326,6 +332,7 @@ export default function onlyne(pi: ExtensionAPI) {
 
   pi.on("session_shutdown", async (event) => {
     agent?.stop(`pi:${event.reason ?? "quit"}`);
+    surface?.closeBackground?.();
     surface?.widget?.(undefined);
     agent = null;
     surface = null;

package/src/pi-surface.mjs

@@ -10,9 +10,13 @@
 //   status        ctx.ui.setStatus("onlyne", text)
 //   exit          ctx.shutdown()
 //   isIdle        ctx.isIdle()
+//   pending       ctx.hasPendingMessages()
+//   toolNames     pi.getAllTools()          (background-work.mjs)
+//   eventBus      pi.events                 (background-work.mjs)
 //   registerTool / registerCommand are probed by index.ts itself.
 
 import { WIDGET_KEY } from "./activity.mjs";
+import { createBackgroundProbe } from "./background-work.mjs";
 
 /**
  * @param {{ pi: any, log: (line: string) => void, context: () => any }} options
@@ -27,6 +31,30 @@ export function createSurface({ pi, log, context }) {
     }
   };
 
+  /**
+   * The one question behind every phase the plugin reports. pi answers it; a
+   * probe that is missing, throws, or arrives without a context answers `false`
+   * because an unwitnessed session is a running one as far as this plugin can
+   * prove (`background-work.mjs` carries the second half of the question).
+   */
+  const piWaitsForInput = () => {
+    const current = ctx();
+    if (!current) return false;
+    try {
+      if (!has(current.isIdle) || !current.isIdle()) return false;
+      if (has(current.hasPendingMessages) && current.hasPendingMessages()) return false;
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const background = createBackgroundProbe({
+    events: pi.events ?? null,
+    getToolNames: has(pi.getAllTools) ? () => (pi.getAllTools() ?? []).map((tool) => tool?.name) : null,
+    log,
+  });
+
   const available = {
     wakeUser: has(pi.sendUserMessage),
     proseContext: has(pi.sendMessage),
@@ -139,6 +167,18 @@ export function createSurface({ pi, log, context }) {
         return true;
       }
     },
+    /**
+     * The phase rule in one place: idle means waiting for user input, and a
+     * background-task extension holding live work keeps the session running
+     * even while pi itself waits.
+     */
+    async waitingForInput() {
+      if (!piWaitsForInput()) return false;
+      return !(await background.running());
+    },
+    closeBackground() {
+      background.close();
+    },
     exit(reason) {
       log(`exiting pi: ${reason}`);
       try {