pi-onlyne 1.2.0 → 1.2.2

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/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 } });
-});

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

@@ -2,7 +2,7 @@
 // through the pi extension API, with a probe for each optional member so an
 // older pi degrades instead of throwing.
 //
-// Probed members (measured against pi 0.85.1):
+// Probed members (measured against pi 0.87.1):
 //   wakeUser      pi.sendUserMessage(content, { deliverAs: "followUp" })
 //   proseContext  pi.sendMessage({customType,...}, { deliverAs:"followUp", triggerTurn:false })
 //   customEntry   pi.appendEntry(customType, data)
@@ -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),
@@ -55,19 +83,35 @@ export function createSurface({ pi, log, context }) {
     }
   };
 
-  /** One pi user message; images ride along as pi image content parts. */
+  /**
+   * One pi user message; images ride along as pi image content parts.
+   *
+   * pi reads an image part as the flat `ImageContent` of its message types —
+   * `data` plus `mimeType` — and normalizes every part before the message is
+   * built, so a part missing either string stops the whole delivery inside pi.
+   * pi reports that failure in its own pane and hands nothing back to this
+   * plugin, so an unusable part is dropped here and the assignment still
+   * travels: the injection text already names the file that was written.
+   */
   const wakeUser = (text, parts = []) => {
     if (!available.wakeUser) {
       log("pi has no sendUserMessage; the assignment reached the session log only");
       return false;
     }
-    const content = parts.length === 0
+    const images = parts.filter(
+      (part) => typeof part?.data === "string" && typeof part?.mime === "string" && part.mime,
+    );
+    if (images.length !== parts.length) {
+      log(`attachment carried no base64 data or no media type; ${parts.length - images.length} dropped, the task text still went`);
+    }
+    const content = images.length === 0
       ? text
       : [
           { type: "text", text },
-          ...parts.map((part) => ({
+          ...images.map((part) => ({
             type: "image",
-            source: { type: "base64", mediaType: part.mime, data: part.data },
+            data: part.data,
+            mimeType: part.mime,
           })),
         ];
     try {
@@ -139,6 +183,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 {

package/src/pi-surface.test.mjs

@@ -0,0 +1,160 @@
+// The pi-facing half of the surface: exactly what `wakeUser` hands
+// `pi.sendUserMessage`. Every shape asserted here is pi's own declaration —
+// `sendUserMessage(content: string | (TextContent | ImageContent)[])`, with
+// `ImageContent` the flat `{ type: "image", data, mimeType }` of
+// `@earendil-works/pi-ai` (measured against pi 0.87.1). pi normalizes each part
+// before it builds the message, so a part in any other shape — the nested
+// Anthropic `source: { type, media_type, data }` this plugin once sent — stops
+// the whole delivery inside pi, and pi reports that in its own pane without
+// handing anything back to the plugin.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { createSurface } from "./pi-surface.mjs";
+
+/** The injection text `agent.mjs` builds for one assignment. */
+const TASK_TEXT = "[onlyne] task 11111111-1111-4111-8111-111111111111 from role:planner";
+
+/** One inline image part in the shape the agent hands the surface. */
+const PNG_PART = { type: "image", mime: "image/png", data: "iVBORw0KGgoAAAANSUhEUg==", name: "shot.png" };
+
+/** pi's own `UserMessage.content` for that text and that part, key for key. */
+const PNG_CONTENT = [
+  { type: "text", text: TASK_TEXT },
+  { type: "image", data: "iVBORw0KGgoAAAANSUhEUg==", mimeType: "image/png" },
+];
+
+/**
+ * A surface over a hand-written fake pi: every `sendUserMessage` arrives with
+ * the arguments it was given, recorded whole, and every surface log line with
+ * it. `refuse` makes one call throw synchronously, the way a pi that does not
+ * know an option does.
+ * @param {{ refuse?: (content: unknown, options: unknown) => boolean }} [options]
+ */
+function fakeSurface({ refuse = null } = {}) {
+  const calls = [];
+  const lines = [];
+  const surface = createSurface({
+    pi: {
+      sendUserMessage(content, options) {
+        calls.push({ content, options });
+        if (refuse?.(content, options)) throw new Error("this pi does not take that option");
+      },
+    },
+    log: (line) => lines.push(line),
+    context: () => null,
+  });
+  return { calls, lines, surface };
+}
+
+test("an image attachment reaches pi as one flat image content part beside the task text", () => {
+  const { calls, lines, surface } = fakeSurface();
+
+  assert.equal(surface.wakeUser(TASK_TEXT, [PNG_PART]), true);
+  assert.equal(calls.length, 1, "one message, not one call per part");
+  // The whole array, key for key: a nested `source` / `mediaType` part carries
+  // keys pi does not declare and lacks the two it does, so it cannot pass this.
+  assert.deepEqual(calls[0].content, PNG_CONTENT);
+  assert.deepEqual(lines, [], "a readable attachment is delivered, not reported");
+});
+
+test("task text with no attachments reaches pi as a bare string", () => {
+  const { calls, surface } = fakeSurface();
+
+  assert.equal(surface.wakeUser(TASK_TEXT, []), true);
+  assert.equal(calls.length, 1);
+  // pi takes the string path of `content`; a one-element array of text parts is
+  // a different message and a needless normalization round trip.
+  assert.equal(calls[0].content, TASK_TEXT);
+});
+
+test("an attachment pi cannot read is dropped, logged, and the task text still travels", () => {
+  const { calls, lines, surface } = fakeSurface();
+
+  // Each part below fails one clause of what pi needs: no base64 data, no media
+  // type, an empty media type. Sending any of them stops the whole delivery
+  // inside pi, so all three go and the text goes alone.
+  assert.equal(
+    surface.wakeUser(TASK_TEXT, [
+      { type: "image", mime: "image/png", name: "no-data.png" },
+      { type: "image", data: "iVBORw0KGgoAAAANSUhEUg==", name: "no-mime.png" },
+      { type: "image", data: "iVBORw0KGgoAAAANSUhEUg==", mime: "" },
+    ]),
+    true,
+  );
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].content, TASK_TEXT);
+  assert.equal(lines.length, 1);
+  assert.match(lines[0], /3 dropped/);
+  assert.match(lines[0], /the task text still went/);
+
+  // Dropping is per part: a usable image beside an unusable one still rides.
+  assert.equal(surface.wakeUser(TASK_TEXT, [{ type: "image", mime: "image/png" }, PNG_PART]), true);
+  assert.deepEqual(calls[1].content, PNG_CONTENT);
+  assert.equal(lines.length, 2);
+  assert.match(lines[1], /1 dropped/);
+});
+
+test("delivery asks for followUp and a refusal of that option retries with the same content", () => {
+  const asked = fakeSurface();
+
+  assert.equal(asked.surface.wakeUser(TASK_TEXT, [PNG_PART]), true);
+  assert.deepEqual(asked.calls, [{ content: PNG_CONTENT, options: { deliverAs: "followUp" } }]);
+
+  // An older pi throws on the option it does not know. The message itself is
+  // fine, so the retry drops the option and keeps the content.
+  const refusing = fakeSurface({ refuse: (_content, options) => Boolean(options) });
+
+  assert.equal(refusing.surface.wakeUser(TASK_TEXT, [PNG_PART]), true);
+  assert.equal(refusing.calls.length, 2);
+  assert.deepEqual(refusing.calls[0].options, { deliverAs: "followUp" });
+  assert.equal(refusing.calls[1].options, undefined);
+  assert.deepEqual(refusing.calls[1].content, PNG_CONTENT);
+  assert.deepEqual(refusing.lines, [], "a delivery that landed on the retry is not a failure");
+});
+
+/**
+ * A surface over a fake pi that answers the two questions the phase is read
+ * from, plus the cases where pi answers neither.
+ * @param {{ isIdle?: () => boolean, hasPendingMessages?: () => boolean, throwOn?: "idle" | "pending" }} [pi]
+ */
+function idleSurface(pi = {}) {
+  const lines = [];
+  return {
+    lines,
+    surface: createSurface({ pi, log: (line) => lines.push(line), context: () => pi }),
+  };
+}
+
+test("only a session waiting on its next message reads as idle", async () => {
+  const waiting = idleSurface({ isIdle: () => true, hasPendingMessages: () => false });
+  assert.equal(await waiting.surface.waitingForInput(), true);
+
+  // A queued continuation is input already on its way, so the session is not
+  // waiting for the user even though no turn is running.
+  const queued = idleSurface({ isIdle: () => true, hasPendingMessages: () => true });
+  assert.equal(await queued.surface.waitingForInput(), false);
+
+  // A turn in flight, a retry, and a compaction all read as not idle here.
+  const busy = idleSurface({ isIdle: () => false, hasPendingMessages: () => false });
+  assert.equal(await busy.surface.waitingForInput(), false);
+});
+
+test("a phase pi was never asked about reads as running, not idle", async () => {
+  // The probes are optional members of an older pi, and a session with no
+  // context yet has witnessed nothing: both answer `false` rather than guess.
+  const noProbes = idleSurface({});
+  assert.equal(await noProbes.surface.waitingForInput(), false);
+
+  const noContext = createSurface({ pi: { isIdle: () => true }, log: () => {}, context: () => null });
+  assert.equal(await noContext.waitingForInput(), false);
+
+  const throwing = idleSurface({
+    isIdle: () => true,
+    hasPendingMessages: () => {
+      throw new Error("pi is mid-replay");
+    },
+  });
+  assert.equal(await throwing.surface.waitingForInput(), false);
+});

package/src/protocol.test.mjs

@@ -219,16 +219,6 @@ test("observationFor attaches the host only when there is one", () => {
   assert.deepEqual(dimensions, bare);
 });
 
-test("heartbeatReport carries the host inside observed", () => {
-  const report = heartbeatReport({ taskId: "t1", generation: 1, seq: SEQ_BASE + 1, agent: "idle", host: hostBinding(PANE_ENV) });
-  assert.equal(report.data.observed.host.orca.pane_key, PANE_KEY);
-  assert.equal(report.data.observed.agent, "idle");
-  assert.equal(
-    "host" in heartbeatReport({ taskId: "t1", generation: 1, seq: SEQ_BASE + 2, agent: "idle" }).data.observed,
-    false
-  );
-});
-
 test("a completion names an outcome and a single-line head", () => {
   assert.deepEqual(completeReport({ taskId: "t1", outcome: "failed", head: "broke\non line two" }), {
     kind: "complete",