pi-onlyne 1.1.2 → 1.2.1

package/src/agent.mjs

@@ -1,7 +1,8 @@
 // The agent side of the onlyne adapter protocol: one connection to
 // `<role workspace>/.onlyne/run/s`, the hello/welcome handshake, assign
-// delivery, turn-state reports, the completion exit, probe, recycle and
-// detach — plus reconnect when the client restarts under it.
+// delivery, turn-state reports, the completion exit and the idle reminder
+// ladder that leads to it, probe, recycle and detach — plus reconnect when the
+// client restarts under it.
 //
 // Everything pi-specific lives behind `surface` (see pi-surface.mjs): this
 // module decides *what* the protocol says and hands the *effects* to the
@@ -19,6 +20,7 @@ import { createConnection } from "node:net";
 import { basename, join } from "node:path";
 import { createFrameDecoder, encodeFrame } from "./frame.mjs";
 import { createActivity } from "./activity.mjs";
+import { DEFAULT_IDLE_REMINDERS } from "./config.mjs";
 import {
   DEFAULT_HEARTBEAT_MS,
   assignAckArgs,
@@ -36,7 +38,6 @@ import {
   sendEnvelope,
   sessionRegisterArgs,
   SEQ_BASE,
-  settledReport,
   stdinTaskText,
   welcomeFrom,
 } from "./protocol.mjs";
@@ -93,6 +94,7 @@ export class OnlyneAgent {
    *   requestTimeoutMs?: number,
    *   helloTimeoutMs?: number,
    *   settleFallbackMs?: number,
+   *   idleReminders?: number,
    *   createConnection?: (path: string) => any,
    *   timer?: { set: (fn: () => void, ms: number) => any, clear: (handle: any) => void },
    * }} options
@@ -116,6 +118,12 @@ export class OnlyneAgent {
     this.requestTimeoutMs = options.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
     this.helloTimeoutMs = options.helloTimeoutMs ?? HELLO_TIMEOUT_MS;
     this.settleFallbackMs = options.settleFallbackMs ?? SETTLE_FALLBACK_MS;
+    /**
+     * How many idle reminders one task may collect: the bound that turns the
+     * third idle without a completion into a failure (`settleNow`). It comes
+     * from the workspace's `.pi/onlyne.json` (`config.mjs`).
+     */
+    this.idleReminders = options.idleReminders ?? DEFAULT_IDLE_REMINDERS;
     this.createConnection = options.createConnection ?? ((path) => createConnection(path));
     // The pane this process was spawned in, reported on every heartbeat so the
     // supervisor board can attribute the tab (protocol.mjs `hostBinding`). Read
@@ -167,8 +175,6 @@ export class OnlyneAgent {
     this.lastError = null;
     /** Whether pi has already been asked to end this process (`exitSession`). */
     this.exitRequested = false;
-    /** Agent phase of the last heartbeat this connection sent, if any. */
-    this.lastPhase = null;
     this.stats = { assigns: 0, duplicates: 0, injections: 0, completions: 0, reports: 0, reconnects: 0, recycles: 0 };
   }
 
@@ -317,9 +323,10 @@ export class OnlyneAgent {
     }
     this.welcome = welcome;
     this.connected = true;
-    // A fresh connection has reported nothing: the next beat is news.
-    this.lastPhase = null;
-    this.agentState = this.tasks.size > 0 ? "idle" : "ready";
+    // A fresh connection has reported nothing, so the phase is a question, not
+    // an answer: the first beat below re-derives it from pi. A taskless session
+    // is the ready pool, and ready is its own state.
+    this.agentState = this.tasks.size > 0 ? await this.derivedPhase() : "ready";
     this.activity.set({
       role: welcome.role,
       connection: "connected",
@@ -492,33 +499,55 @@ export class OnlyneAgent {
   }
 
   /**
-   * One heartbeat for the task this connection serves.
+   * One heartbeat for the task this connection serves. The phase is the one the
+   * rule names: `idle` only while the session waits for user input, `running`
+   * for everything else, re-derived from pi on every beat so a phase that went
+   * stale when a run started again cannot survive a tick.
    *
-   * A task this plugin already completed gets none. `observed` is a full
-   * snapshot, so a heartbeat sent after the completion report would put
-   * `delivery: none` and `outcome: pending` back over the terminal tuple the
-   * host derived from it, and the reducer accepts that snapshot: the session
-   * would read `idle` again after having read `exited`. The e2e case
-   * `crates/onlyne-testkit/e2e/pi-live.sh` caught exactly this race, where a
-   * turn-end heartbeat left over from the finishing turn landed three
-   * milliseconds behind the completion.
+   * A task this plugin already completed gets none: the beat is a full
+   * snapshot of what the plugin can see, and after the completion the agent's
+   * remaining turns are not this session's business — the row belongs to the
+   * settlement the completion earned. The client rewrites the tuple's `delivery`
+   * and `recovery` from its own records, so a late beat could no longer undo
+   * the drain even if it sent one. The e2e case
+   * `crates/onlyne-testkit/e2e/pi-live.sh` caught this race, where a turn-end
+   * heartbeat left over from the finishing turn landed three milliseconds
+   * behind the completion.
    */
-  async heartbeat(agent = this.agentState) {
+  async heartbeat(agent = null) {
     if (!this.connected) return;
     const taskId = this.activeTaskId();
     if (!taskId) return;
     if (this.tasks.get(taskId)?.completed) return;
-    this.agentState = agent;
+    const phase = agent ?? (await this.derivedPhase());
+    this.agentState = phase;
     this.seq += 1;
     await this.request("report", heartbeatReport({
       taskId,
       generation: this.generation,
       seq: this.seq,
-      agent,
+      agent: phase,
       host: this.host,
     }));
     this.stats.reports += 1;
-    this.lastPhase = agent;
+  }
+
+  /**
+   * Where the session actually is, in the only two words the wire has for it.
+   * The surface asks pi, and adds the one case pi cannot see: work a
+   * background-task extension took off the agent loop.
+   * @returns {Promise<"idle"|"running">}
+   */
+  async derivedPhase() {
+    try {
+      const waiting = await this.surface.waitingForInput?.();
+      return waiting === true ? "idle" : "running";
+    } catch (error) {
+      // A surface that cannot answer has not witnessed a session waiting for
+      // input, and the rule reads that as running.
+      this.log(`input-waiting probe failed: ${error.message}`);
+      return "running";
+    }
   }
 
   /** Tasks still owing a completion; a finished task keeps its record. */
@@ -584,10 +613,16 @@ export class OnlyneAgent {
     if (typeof args.generation === "number") this.generation = args.generation;
 
     const attachments = this.writeAttachments(taskId, envelope);
+    const attachmentPaths = attachments.map((item) => item.path);
     const prose = typeof args.prose === "string" ? args.prose.trim() : "";
     const proseIsNew = prose.length > 0 && !this.deliveredProse.has(prose);
     if (proseIsNew) this.deliveredProse.add(prose);
-    const text = injectionText({ assign: { ...args, task_id: taskId }, proseIsNew, attachmentPaths: attachments.map((item) => item.path) });
+    // The assignment as the injection saw it, retained so the idle ladder can
+    // re-send it (`remind`): the task identity, its source, its kind, the task
+    // text with whatever handoff lines a relay put inside it, and the paths of
+    // the attachments this call already wrote.
+    const assignment = { ...args, task_id: taskId };
+    const text = injectionText({ assign: assignment, proseIsNew, attachmentPaths });
 
     const held = this.tasks.get(taskId);
     // A completed record is not a live one: a new envelope for a task that
@@ -598,9 +633,17 @@ export class OnlyneAgent {
       // is: its delivered set keeps the relay guard's count, and its completion
       // state still settles the task. Only the "since this instruction" counter
       // moves, so the settled-without-completing watchdog measures the newest one.
+      // The ladder restarts with it: the reminder count, the idle episode it was
+      // charged to (`remindedAt`), and the failure an errored turn proved all
+      // belong to the instruction being replaced.
       held.turnsSinceAssign = 0;
+      held.reminders = 0;
+      held.remindedAt = 0;
+      held.reminderWokeTurn = false;
+      held.errored = false;
       held.envelopeId = envelope.id ?? held.envelopeId;
-      if (held.failed) held.failed = false;
+      held.assignment = assignment;
+      held.attachmentPaths = attachmentPaths;
     } else {
       this.tasks.set(taskId, {
         taskId,
@@ -612,7 +655,14 @@ export class OnlyneAgent {
         turns: 0,
         errored: false,
         head: "",
-        failed: false,
+        assignment,
+        attachmentPaths,
+        /** Idle reminders sent for this task; the bound is `idleReminders`. */
+        reminders: 0,
+        /** The `turnsSinceAssign` the last reminder was charged to. */
+        remindedAt: 0,
+        /** Whether the next turn is the one this plugin's own reminder woke. */
+        reminderWokeTurn: false,
       });
     }
     this.agentState = "running";
@@ -675,62 +725,87 @@ export class OnlyneAgent {
 
   // ------------------------------------------------------------ pi → plugin
 
-  /** A turn started: the plugin's own agent fact is `running`. */
+  /**
+   * A turn started: the plugin's own agent fact is `running`, and the idle
+   * ladder starts over. The count belongs to one idle episode, so a session
+   * that ran again owns a fresh bound; the one turn this plugin's own reminder
+   * woke belongs to the episode that reminder belongs to, and keeps it.
+   */
   onTurnStart() {
-    const task = [...this.tasks.values()].find((item) => !item.completed);
-    if (task) task.turns += 1;
+    for (const task of this.tasks.values()) {
+      if (task.completed) continue;
+      task.turns += 1;
+      if (task.reminderWokeTurn) {
+        task.reminderWokeTurn = false;
+        continue;
+      }
+      task.turnsSinceAssign = 0;
+      task.reminders = 0;
+      task.remindedAt = 0;
+    }
     void this.heartbeat("running").catch((error) => this.log(`heartbeat refused: ${error.message}`));
   }
 
-  /** A turn ended: the agent is idle, and the settle window starts. */
+  /**
+   * A turn ended: one turn of a run that may still have more, and the settle
+   * window starts. The phase is re-derived, so the beat says `running` while pi
+   * keeps working and says `idle` only once the session waits for input.
+   */
   onTurnEnd() {
     for (const task of this.tasks.values()) {
       if (!task.completed) task.turnsSinceAssign += 1;
     }
-    void this.heartbeat("idle").catch((error) => this.log(`heartbeat refused: ${error.message}`));
+    void this.heartbeat().catch((error) => this.log(`heartbeat refused: ${error.message}`));
     this.armSettleFallback();
   }
 
-  /** pi will not continue on its own: run the completion exit. */
+  /**
+   * pi has settled: this is the moment the rule names as waiting for input, and
+   * the settle decision belongs to it.
+   */
   onSettled() {
     this.clearSettleFallback();
-    this.trySettle();
+    void this.heartbeat().catch((error) => this.log(`heartbeat refused: ${error.message}`));
+    void this.trySettle().catch((error) => this.log(`settle decision failed: ${error.message}`));
   }
 
   /**
-   * The one completion trigger. pi keeps `isIdle()` false while it is running,
-   * retrying, compacting, or holding a queued continuation, so a settle signal
-   * that arrives during any of those waits instead of reporting a premature
-   * outcome.
+   * The one settle decision. pi keeps `isIdle()` false while it is running,
+   * retrying, compacting, or holding a queued continuation, and a background task
+   * keeps work running after pi itself has settled, so a settle signal that
+   * arrives during any of those waits re-arms instead of deciding on a session
+   * that is still busy. The fallback timer and `agent_settled` both land here,
+   * and `settleNow` makes the decision idempotent for one idle episode.
    */
-  trySettle() {
+  async trySettle() {
     if (this.closed || this.activeTasks().length === 0) return;
-    if (this.surface.isIdle?.() === false) {
+    if (await this.derivedPhase() !== "idle") {
       this.armSettleFallback();
       return;
     }
-    void this.settleNow().catch((error) => this.log(`completion failed: ${error.message}`));
+    await this.settleNow().catch((error) => this.log(`settle decision failed: ${error.message}`));
   }
 
-  /** A failed turn: the task's outcome is `failed` unless it already ended. */
+  /** A failed turn: the task's outcome is `failed`, with the error as its head. */
   onTurnError(text) {
     for (const task of this.tasks.values()) {
       if (task.completed) continue;
-      task.failed = true;
       task.errored = true;
       if (text) task.head = headOf(text);
     }
-    this.trySettle();
+    void this.trySettle().catch((error) => this.log(`settle decision failed: ${error.message}`));
   }
 
   /**
-   * The last assistant text seen, kept as the completion summary for a task the
-   * model never handed an explicit argument over for.
+   * The last assistant text seen, kept as the completion summary for a task
+   * whose `onlyne_complete` call hands no argument over.
    *
    * This is the fallback, never the deliverable: `onlyne_complete`'s `text` is
    * reported byte for byte by `completeFromTool` and is never written back
    * here, so the sentence a turn happened to end on cannot stand in for a
-   * payload the tool call carried.
+   * payload the tool call carried. Nothing else reads it: an idle that runs out
+   * of reminders fails the task and says why, rather than reporting the text of
+   * a turn nobody completed.
    */
   noteAssistantText(text) {
     const flat = headOf(text);
@@ -745,7 +820,7 @@ export class OnlyneAgent {
     if (this.closed || this.activeTasks().length === 0) return;
     this.settleHandle = this.timer.set(() => {
       this.settleHandle = null;
-      this.trySettle();
+      void this.trySettle().catch((error) => this.log(`settle decision failed: ${error.message}`));
     }, this.settleFallbackMs);
   }
 
@@ -756,26 +831,81 @@ export class OnlyneAgent {
   }
 
   /**
-   * The auto outcome rule: every active task whose turn produced output ends
-   * `done` (or `failed` when the turn errored), with the last assistant text as
-   * its head. That fallback is the only head this path may report — an explicit
-   * `onlyne_complete` argument is the tool path's, and this rule runs after it,
-   * for the tasks it left unsettled. A task assigned but not yet turned is left
-   * alone: the injected message has not run yet, and completing now would lie.
+   * The idle ladder's decision, taken for every task this session still holds
+   * when a settle signal finds the agent idle.
+   *
+   * An errored turn is proof on its own — pi may skip the clean turn end — so
+   * its task is reported `failed` at once, with the error as its head. Every
+   * other open task gets one rung of the ladder: the plugin re-sends the
+   * assignment (`remind`) and counts it, and the idle that finds the bound
+   * already spent reports `failed` and leaves the session.
+   *
+   * `onlyne_complete` is the only path to `done`. A turn that ends without it
+   * leaves the task `idle_waiting` (the design's own word for it), and the
+   * answer is the reinforcing prompt the model gets instead of a completion it
+   * never claimed.
+   *
+   * A task whose injected message has not run a turn is left alone at every
+   * rung: the reminder would re-send an assignment the model may not have read
+   * yet, and failing now would claim work that never happened.
+   *
+   * A rung belongs to an idle episode, not to a settle signal: `remindedAt`
+   * records the `turnsSinceAssign` the last reminder was charged to, so the
+   * fallback timer and an `agent_settled` answering the same turn end spend one
+   * rung between them.
    */
   async settleNow() {
     for (const task of [...this.tasks.values()]) {
       if (task.completed) continue;
-      // A turn has to have run: a full turn end is the ordinary proof, and an
-      // errored turn is proof enough on its own (pi may skip the clean turn_end).
-      if (task.turnsSinceAssign === 0 && !task.errored) continue;
-      await this.complete(task.taskId, task.failed ? "failed" : "done", task.head);
+      if (task.errored) {
+        await this.complete(task.taskId, "failed", task.head);
+        continue;
+      }
+      if (task.turnsSinceAssign === 0 || task.remindedAt === task.turnsSinceAssign) continue;
+      task.remindedAt = task.turnsSinceAssign;
+      if (task.reminders < this.idleReminders) {
+        this.remind(task);
+        continue;
+      }
+      const rungs = `${task.reminders} idle reminder${task.reminders === 1 ? "" : "s"}`;
+      await this.complete(task.taskId, "failed", `no completion after ${rungs}`);
     }
   }
 
   /**
-   * `onlyne_complete`: an explicit outcome from the model, which wins over the
-   * auto rule.
+   * One rung of the idle ladder: hand the assignment back to the model.
+   *
+   * The reminder is the injection's own text — `injectionText` with the prose
+   * flag off, so the role prose already in the session's context is not
+   * repeated — under one line saying why it is back. The task text is where a
+   * relay carries its handoff lines, so a handoff the model still owes comes
+   * back with it.
+   *
+   * The attachments travel as the paths the injection wrote, never as parts:
+   * the images were handed to pi once, and re-attaching them would put the same
+   * bytes into the context a second time.
+   *
+   * @param {any} task a record with `assignment` and `attachmentPaths` retained
+   * from `onAssign`
+   */
+  remind(task) {
+    task.reminders += 1;
+    // The turn this reminder is about to wake belongs to the same episode, so
+    // `onTurnStart` spends no reset on it and the bound stays reachable.
+    task.reminderWokeTurn = true;
+    const rung = `reminder ${task.reminders} of ${this.idleReminders}`;
+    const text = [
+      `[onlyne] your turn ended without a completion exit; this task is still open (${rung}). Call onlyne_complete when it is finished.`,
+      "",
+      injectionText({ assign: task.assignment, proseIsNew: false, attachmentPaths: task.attachmentPaths }),
+    ].join("\n");
+    this.surface.wakeUser?.(text, []);
+    this.notice("out", `${rung} for task ${task.taskId.slice(0, 8)}`);
+  }
+
+  /**
+   * `onlyne_complete`: the model's explicit outcome, and the only path to
+   * `done`.
    *
    * A non-empty `text` is the completion body: it is what the model handed
    * over, reported verbatim as the ledger's one-line `head`, so the last
@@ -854,11 +984,6 @@ export class OnlyneAgent {
     this.activity.set({ taskId: this.activeTaskId() ?? null, phase: normalized });
     this.notice("out", `complete ${taskId.slice(0, 8)} ${normalized}${summary ? `: ${summary}` : ""}`);
     if (this.activeTasks().length === 0) {
-      if (exitProcess) {
-        await this.reportSettled(taskId, normalized).catch((error) =>
-          this.log(`settled observation refused: ${error.message}`),
-        );
-      }
       this.stopHeartbeat();
       if (exitProcess) this.exitSession(normalized);
     }
@@ -880,33 +1005,6 @@ export class OnlyneAgent {
     this.surface.exit?.(reason);
   }
 
-  /**
-   * One last observation before the process leaves: the tuple the host settled
-   * plus `agent: idle`.
-   *
-   * The completion settles the row from the tuple the client holds, which still
-   * says `running` when the turn that finished was the last report sent, and
-   * nothing observes the process afterwards. This report is what makes an
-   * exited session read idle. It is skipped when the last beat was already
-   * idle — the settled tuple is then already right — and it is a request for
-   * the same reason the completion is: the answer is the handover, and a
-   * failure here must not stop the exit that the durable completion earned.
-   */
-  async reportSettled(taskId, outcome) {
-    if (!this.connected || this.lastPhase === "idle") return false;
-    this.seq += 1;
-    await this.request("report", settledReport({
-      taskId,
-      outcome,
-      generation: this.generation,
-      seq: this.seq,
-      host: this.host,
-    }));
-    this.stats.reports += 1;
-    this.lastPhase = "idle";
-    return true;
-  }
-
   async flushPendingCompletion() {
     const pending = this.pendingCompletion;
     if (!pending || !this.connected) return;
@@ -917,9 +1015,6 @@ export class OnlyneAgent {
       this.activity.set({ taskId: this.activeTaskId() ?? null, phase: pending.outcome });
       this.notice("out", `complete ${pending.taskId.slice(0, 8)} ${pending.outcome} flushed after reconnect`);
       if (pending.exitProcess && this.activeTasks().length === 0) {
-        await this.reportSettled(pending.taskId, pending.outcome).catch((error) =>
-          this.log(`settled observation refused: ${error.message}`),
-        );
         this.exitSession(pending.outcome);
       }
     } catch (error) {
@@ -928,6 +1023,21 @@ export class OnlyneAgent {
     }
   }
 
+  /**
+   * One inline image read off the path the model named, in the wire's
+   * `ImagePart` shape. `mimeForPath` refuses an extension outside the core's
+   * four mime types, and `imagePart` refuses a payload above the byte ceiling.
+   * @param {string | null | undefined} path
+   */
+  imageFromPath(path) {
+    if (!path) return null;
+    return imagePart({
+      data: readFileSync(path),
+      mime: mimeForPath(path),
+      name: path.split("/").pop() ?? null,
+    });
+  }
+
   /**
    * `onlyne_send`: submit one envelope.
    * @param {{ to: string, text?: string, kind?: string, imagePath?: string | null }} input
@@ -935,11 +1045,7 @@ export class OnlyneAgent {
   async sendFromTool(input) {
     if (!this.connected) throw new Error("onlyne: client socket is not connected");
     const kind = input.kind === "task" ? "task" : "note";
-    let image = null;
-    if (input.imagePath) {
-      const bytes = readFileSync(input.imagePath);
-      image = imagePart({ data: bytes, mime, name: input.imagePath.split("/").pop() ?? null });
-    }
+    const image = this.imageFromPath(input.imagePath);
     const envelope = sendEnvelope({ from: this.role, to: input.to, kind, text: input.text ?? "", image });
     const data = await this.request("send", envelope);
     // Recorded only after the client answered the `send`: a refused envelope was
@@ -949,6 +1055,36 @@ export class OnlyneAgent {
     return { queued: true, op_id: envelope.op_id ?? null, kind, to: input.to, data };
   }
 
+  /**
+   * `onlyne_handoff`: hand this session's task on to the next hop of its family.
+   *
+   * The task named in the request is the session's own current one, so the child
+   * the host mints under it is a continuation of the family this session serves:
+   * the host reads the parent's causality, derives the child through
+   * `Causality::child_of`, and answers the child's task id and hop. The client's
+   * own refusal is raised out of here as it arrived.
+   * @param {{ to: string, text?: string, imagePath?: string | null }} input
+   */
+  async handoffFromTool(input) {
+    if (!this.connected) throw new Error("onlyne: client socket is not connected");
+    const taskId = this.activeTaskId();
+    if (!taskId) throw new Error("onlyne: no task is assigned to this session");
+    const data = await this.request("handoff", {
+      task_id: taskId,
+      to: input.to,
+      text: input.text ?? "",
+      image: this.imageFromPath(input.imagePath),
+    });
+    const answer = data ?? {};
+    return {
+      taskId: answer.task_id ?? null,
+      hop: answer.hop ?? null,
+      queued: answer.queued ?? false,
+      opId: answer.op_id ?? null,
+      to: input.to,
+    };
+  }
+
   // ------------------------------------------------------------ attachments
 
   /**