pi-onlyne 2.1.0 → 2.3.0

package/src/agent.mjs

@@ -10,6 +10,16 @@
 // surface, which is why the whole state machine is testable against a plain
 // Node unix socket.
 //
+// One completion path, and it is the model's: an explicit `onlyne_complete`
+// (`completeFromTool`) or the host's `recycle{outcome}`. A turn that ends
+// without one — cleanly or with a provider error — decides nothing here: the
+// client's own turn-end rule owns the ending (`docs/v2-CONTRACT.md` §3c: one
+// nudge, then the delivery settles `blocked`) and its own sweeps own a session
+// whose agent died. A failed turn only supplies the head fallback, because pi
+// retries a retryable provider error inside the same run and the client's nudge
+// can restart a session a moment after it settles — a report sent on the error
+// would race work that is still going.
+//
 // What the human sees travels through one funnel, `notice` below: the pi widget
 // panel when the host has `ctx.ui.setWidget`, the footer status line plus a
 // `[pi-onlyne]` stderr line when it has not. `log` keeps the diagnostics — a
@@ -46,14 +56,24 @@ export const RECONNECT_LADDER_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000];
 export const HELLO_TIMEOUT_MS = 5_000;
 /** Default bound on one request round trip. */
 export const REQUEST_TIMEOUT_MS = 30_000;
+
 /**
- * How long after an errored turn the plugin waits for `agent_settled` before it
- * reports the failure it witnessed itself.
+ * Capabilities this plugin implements on the wire.
+ *
+ * `resume` is the one that changes what a `task` scope does with this runtime.
+ * Pi keeps its conversation in its own store (`--session-dir`), so a session the
+ * client releases is one it can bring back by starting the role's `resume` argv
+ * — `pi --session <id>` — over the same store. Without the declaration the
+ * client keeps the process instead and the scope degrades to "process alive,
+ * session alive"; with it, an idle `task` session has its process released and
+ * the family's next delivery lands in the same conversation.
+ *
+ * The release is this plugin's own exit, not a kill: `onRecycle` stops and calls
+ * `exitSession`, and pi flushes its session file at `agent_settled`. The client
+ * asks first and closes the container only after a grace, which is what makes
+ * the ordering safe (`AGENTS.md` §10).
  */
-export const SETTLE_FALLBACK_MS = 2_000;
-
-/** Capabilities this plugin implements on the wire. */
-export const CAPABILITIES = ["register", "report", "inject", "recycle"];
+export const CAPABILITIES = ["register", "report", "inject", "recycle", "resume"];
 
 export class OnlyneAgent {
   /**
@@ -71,17 +91,18 @@ export class OnlyneAgent {
    *   ladder?: number[],
    *   requestTimeoutMs?: number,
    *   helloTimeoutMs?: number,
-   *   settleFallbackMs?: number,
    *   createConnection?: (path: string) => any,
    *   timer?: { set: (fn: () => void, ms: number) => any, clear: (handle: any) => void },
    * }} options
    */
   constructor(options) {
     this.socketPath = options.socketPath;
+    this.resolveSocket = typeof options.resolveSocket === "function" ? options.resolveSocket : null;
     this.cwd = options.cwd;
     this.role = options.role;
     this.sessionId = options.sessionId;
     this.envTaskId = options.taskId;
+    this.resident = Boolean(options.resident);
     this.surface = options.surface;
     /** The widget panel's model (`activity.mjs`); seeded with the local role. */
     this.activity = options.activity ?? createActivity();
@@ -92,7 +113,6 @@ export class OnlyneAgent {
     this.ladder = options.ladder ?? RECONNECT_LADDER_MS;
     this.requestTimeoutMs = options.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
     this.helloTimeoutMs = options.helloTimeoutMs ?? HELLO_TIMEOUT_MS;
-    this.settleFallbackMs = options.settleFallbackMs ?? SETTLE_FALLBACK_MS;
     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
@@ -122,7 +142,6 @@ export class OnlyneAgent {
     this.attempt = 0;
     this.reconnectHandle = null;
     this.heartbeatHandle = null;
-    this.settleHandle = null;
     /**
      * The heartbeat round in flight, and what the next pass of it should say.
      * `heartbeat` never lets two rounds overlap, so `beatRound` doubles as the
@@ -226,6 +245,16 @@ export class OnlyneAgent {
 
   connect() {
     if (this.closed || this.socket) return;
+    if (this.resolveSocket) {
+      try {
+        const refreshed = this.resolveSocket();
+        if (typeof refreshed === "string" && refreshed.length > 0) {
+          this.socketPath = refreshed;
+        }
+      } catch {
+        /* keep previous socketPath */
+      }
+    }
     let socket;
     try {
       socket = this.createConnection(this.socketPath);
@@ -269,6 +298,7 @@ export class OnlyneAgent {
   /** Tear the current socket down and schedule the next attempt. */
   dropSocket() {
     const socket = this.socket;
+    const wasConnected = this.connected;
     this.socket = null;
     this.connected = false;
     this.handshaking = false;
@@ -276,7 +306,13 @@ export class OnlyneAgent {
     this.rejectAll("connection lost");
     this.stopHeartbeat();
     this.activity.set({ connection: this.closed ? "detached" : "reconnecting" });
-    this.notice("state", this.closed ? "detached" : "reconnecting");
+    if (!this.closed && (!this.resident || wasConnected)) {
+      this.notice("state", "reconnecting");
+    } else if (this.closed) {
+      this.notice("state", "detached");
+    } else {
+      this.redraw();
+    }
     if (socket && !socket.destroyed) socket.destroy();
     this.scheduleReconnect();
   }
@@ -319,6 +355,11 @@ export class OnlyneAgent {
     }
     this.welcome = welcome;
     this.connected = true;
+    const hadConnectFailure = this.lastError !== null;
+    this.lastError = null;
+    if (this.resident && hadConnectFailure) {
+      this.log(`connected role=${welcome.role} session=${this.sessionId ?? "resident"} socket=${this.socketPath}`);
+    }
     // The client names every delivery it already handed to this session, so a
     // process that restarts under a live client does not re-inject work its
     // predecessor read: the delivery guard is process memory, and this is how it
@@ -465,7 +506,15 @@ export class OnlyneAgent {
   }
 
   noteFailure(error) {
+    const prevCode = this.lastError?.code ?? null;
     this.lastError = error;
+    if (
+      this.resident &&
+      (error?.code === "ENOENT" || error?.code === "ECONNREFUSED") &&
+      prevCode === error.code
+    ) {
+      return;
+    }
     this.log(`socket error: ${error?.message ?? error}`);
   }
 
@@ -477,14 +526,20 @@ export class OnlyneAgent {
    * @param {"in" | "dup" | "out" | "warn" | "state"} kind
    * @param {string} text
    */
+  redraw() {
+    this.surface.status?.(this.activity.lines()[0]);
+    if (this.surface.available?.widget) {
+      this.surface.widget?.(this.activity.lines(), this.activity);
+    }
+  }
+
   notice(kind, text) {
     this.activity.note(kind, text);
+    this.redraw();
     if (this.surface.available?.widget) {
-      this.surface.widget?.(this.activity.lines());
       return;
     }
-    // No panel: the footer carries the steady header line, stderr the event.
-    this.surface.status?.(this.activity.lines()[0]);
+    // No panel: stderr carries the event.
     this.log(`${kind}: ${text}`);
   }
 
@@ -710,10 +765,6 @@ export class OnlyneAgent {
       this.timer.clear(this.reconnectHandle);
       this.reconnectHandle = null;
     }
-    if (this.settleHandle) {
-      this.timer.clear(this.settleHandle);
-      this.settleHandle = null;
-    }
     this.rejectAll("agent stopped");
   }
 
@@ -732,11 +783,14 @@ export class OnlyneAgent {
    * that is what every such frame meant.
    */
   keepsSession() {
-    return this.scope === "task" || this.scope === "role";
+    return this.resident || this.scope === "task" || this.scope === "role";
   }
 
   async onAssign(args) {
     if (typeof args.scope === "string" && args.scope) this.scope = args.scope;
+    if (this.resident && typeof args.session_id === "string" && args.session_id) {
+      this.sessionId = args.session_id;
+    }
     const envelope = args.envelope ?? {};
     const taskId = args.task_id ?? envelope.causality?.task ?? null;
     if (!taskId) {
@@ -769,15 +823,42 @@ export class OnlyneAgent {
       this.surface.roleProse?.(prose);
     }
 
+    const kind = envelope.kind ?? "task";
     const held = this.tasks.get(taskId);
+    const fromLabel = describePrincipal(envelope.from);
+    const wakeMeta = {
+      role: this.role,
+      taskId,
+      kind,
+      from: fromLabel,
+      envelopeId: envelope.id ?? null,
+      bodyText: envelope.body?.text ?? text,
+    };
+    // A note is a message, not work: it is injected and acknowledged, and it
+    // opens no task record, so nothing beats for it, no turn end owes it an
+    // outcome and `onlyne_complete` is never required of it. A note naming a
+    // task this session is still working on lands mid-task, below.
+    if (kind === "note" && (!held || held.completed)) {
+      if (this.tasks.size > 0) this.agentState = "running";
+      this.surface.wakeUser?.(text, this.imageParts(envelope), wakeMeta);
+      this.surface.customEntry?.("onlyne-assign", {
+        taskId,
+        envelopeId: envelope.id ?? null,
+        kind: "note",
+        proseInjected: proseIsNew,
+        prose,
+        attachments: attachmentPaths,
+      });
+      this.notice("in", `note ${taskId.slice(0, 8)} from ${fromLabel}: ${headOf(envelope.body?.text)}`);
+      await this.ack(taskId, true, null);
+      return;
+    }
     // A completed record is not a live one: a new envelope for a task that
     // already settled is fresh work under an old id, so it gets a fresh record.
     if (held && !held.completed) {
       // A new envelope for a task this session already holds — a follow-up, a
       // redirect, a bounce back through a handoff. The work record stays where
-      // it is, and the failure an errored turn proved belonged to the
-      // instruction being replaced, so it is cleared with that instruction.
-      held.errored = false;
+      // it is; the newest instruction re-points it at the newest envelope.
       held.envelopeId = envelope.id ?? held.envelopeId;
       // `lastSeq` deliberately does not reset here. It is the floor the next
       // allocation for this task must clear, and the host's row for the task
@@ -800,22 +881,21 @@ export class OnlyneAgent {
          * share the plugin's counter. Null until the first report.
          */
         lastSeq: null,
-        errored: false,
         head: "",
       });
     }
     this.agentState = "running";
-    this.surface.wakeUser?.(text, this.imageParts(envelope));
+    this.surface.wakeUser?.(text, this.imageParts(envelope), wakeMeta);
     this.surface.customEntry?.("onlyne-assign", {
       taskId,
       envelopeId: envelope.id ?? null,
-      kind: envelope.kind ?? "task",
+      kind,
       proseInjected: proseIsNew,
       prose,
       attachments: attachmentPaths,
     });
     this.activity.set({ taskId, phase: "running" });
-    this.notice("in", `task ${taskId.slice(0, 8)} from ${describePrincipal(envelope.from)} (${envelope.kind ?? "task"}): ${headOf(envelope.body?.text)}`);
+    this.notice("in", `task ${taskId.slice(0, 8)} from ${fromLabel} (${kind}): ${headOf(envelope.body?.text)}`);
     this.startHeartbeat();
     await this.ack(taskId, true, null);
   }
@@ -848,7 +928,13 @@ export class OnlyneAgent {
   onNudge(frame, args) {
     const text = typeof args.text === "string" ? args.text : "";
     const taskId = typeof args.task_id === "string" && args.task_id ? args.task_id.slice(0, 8) : "?";
-    const handedOver = text.length > 0 && this.surface.wakeUser?.(text, []) === true;
+    const handedOver = text.length > 0 && this.surface.wakeUser?.(text, [], {
+      role: this.role,
+      taskId: args.task_id ?? null,
+      kind: "nudge",
+      from: "host",
+      bodyText: text,
+    }) === true;
     if (handedOver) this.notice("in", `nudge for task ${taskId}`);
     else this.notice("warn", `nudge for task ${taskId} was not handed to the model`);
     if (frame?.id === undefined || frame?.id === null) return;
@@ -906,8 +992,10 @@ export class OnlyneAgent {
    *
    * How a turn end settles the work is the client's rule
    * (`docs/v2-CONTRACT.md` §3c): the plugin counts nothing, bounds nothing, and
-   * reports only the facts it alone can see — its own phase, and an errored
-   * turn.
+   * reports only its own phase and the completion the model asked for. A turn
+   * that ended without a completion is the client's case — its own one-nudge
+   * rule, and its own sweeps for a session whose agent died — so nothing here
+   * decides an outcome.
    */
   onTurnStart() {
     void this.heartbeat("running").catch((error) => this.log(`heartbeat refused: ${error.message}`));
@@ -925,40 +1013,29 @@ export class OnlyneAgent {
   }
 
   /**
-   * pi has settled: the session is waiting for input, which is the moment an
-   * errored turn is reported from.
+   * pi has settled: the session is waiting for input. The phase is the whole of
+   * what this hook says — a settle is not a verdict, because the client's own
+   * nudge can restart a session a moment later and pi can still be inside a
+   * retry that settles it again.
    */
   onSettled() {
-    this.clearSettleFallback();
     void this.heartbeat().catch((error) => this.log(`heartbeat refused: ${error.message}`));
-    void this.trySettle().catch((error) => this.log(`failed-turn report refused: ${error.message}`));
   }
 
   /**
-   * Report a turn that failed, once pi is quiet. 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
-   * signal that arrives during any of those waits re-arms instead of reporting
-   * from a session that is still busy. The fallback timer and `agent_settled`
-   * both land here, and a task is reported once because the report completes it.
+   * A turn ended with an error (`stopReason: "error"`). The plugin sends
+   * nothing: an error is not proof of a terminal outcome, because pi retries a
+   * retryable provider error and stays inside the same run, and the client's
+   * nudge can restart a session a moment after it settles — so a report sent
+   * here would race work that is still going. What the error does supply is the
+   * head fallback for a later `onlyne_complete` whose `summary` carries nothing.
    */
-  async trySettle() {
-    if (this.closed || this.activeTasks().length === 0) return;
-    if (await this.derivedPhase() !== "idle") {
-      this.armSettleFallback();
-      return;
-    }
-    await this.reportFailedTurns().catch((error) => this.log(`failed-turn report refused: ${error.message}`));
-  }
-
-  /** 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.errored = true;
       if (text) task.head = headOf(text);
     }
-    void this.trySettle().catch((error) => this.log(`failed-turn report refused: ${error.message}`));
+    this.notice("warn", `turn ended with an error: ${headOf(text) || "no reason given"}`);
   }
 
   /**
@@ -979,38 +1056,6 @@ export class OnlyneAgent {
     }
   }
 
-  armSettleFallback() {
-    this.clearSettleFallback();
-    if (this.closed || this.activeTasks().length === 0) return;
-    this.settleHandle = this.timer.set(() => {
-      this.settleHandle = null;
-      void this.trySettle().catch((error) => this.log(`failed-turn report refused: ${error.message}`));
-    }, this.settleFallbackMs);
-  }
-
-  clearSettleFallback() {
-    if (!this.settleHandle) return;
-    this.timer.clear(this.settleHandle);
-    this.settleHandle = null;
-  }
-
-  /**
-   * Report the failures this session witnessed itself, for every task it still
-   * holds.
-   *
-   * 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. Nothing
-   * else is decided here: a turn that ends without a completion is the client's
-   * case, and it reaches the session as the host's nudge (`onNudge`), so a
-   * plugin that also decided it would be the second owner of the rule.
-   */
-  async reportFailedTurns() {
-    for (const task of [...this.tasks.values()]) {
-      if (task.completed || !task.errored) continue;
-      await this.complete(task.taskId, "failed", task.head);
-    }
-  }
-
   /**
    * `onlyne_complete`: the model's explicit outcome, and the only path to
    * `done`.
@@ -1100,8 +1145,9 @@ export class OnlyneAgent {
     // flight. A refused or broken request handed nothing over, so the task
     // goes back to open and the caller sees why: a retry reports again, and
     // `completeFromTool` still finds the task.
+    let answer = null;
     try {
-      await this.request("report", report);
+      answer = await this.request("report", report);
     } catch (error) {
       if (task) task.completed = false;
       throw error;
@@ -1114,6 +1160,14 @@ export class OnlyneAgent {
       this.stopHeartbeat();
       if (exitProcess) this.exitSession(normalized);
     }
+    // A client that had already settled this task says so with its own record
+    // of the terminal fact, and the caller hands that on rather than claiming
+    // the completion it just sent. The task is still left settled here: the
+    // client's row is the authority, and re-opening it would only ask the
+    // model to report an outcome nobody is waiting for.
+    if (isAlreadySettled(answer)) {
+      return { taskId, outcome: normalized, head: summary, alreadySettled: answer.already_settled };
+    }
     return { taskId, outcome: normalized, head: summary };
   }
 
@@ -1143,7 +1197,15 @@ export class OnlyneAgent {
       if (!this.connected) return;
       const pending = this.pendingCompletions.shift();
       try {
-        await this.request("report", pending.report);
+        const answer = await this.request("report", pending.report);
+        // A queued completion has no tool result to carry the client's record
+        // back through, so the one thing worth saying is that the client had
+        // already settled the task and this report changed nothing.
+        if (isAlreadySettled(answer)) {
+          this.log(
+            `queued completion for ${pending.taskId.slice(0, 8)} was already settled by the client as ${answer.already_settled.state}`
+          );
+        }
         this.stats.completions += 1;
         this.activity.set({ taskId: this.activeTaskId() ?? null, phase: pending.outcome });
         this.notice("out", `complete ${pending.taskId.slice(0, 8)} ${pending.outcome} flushed after reconnect`);
@@ -1233,6 +1295,17 @@ export class OnlyneAgent {
   }
 }
 
+/**
+ * Whether a client's answer to a `report.complete` says the task had already
+ * settled. The shape is the client's (`{"already_settled": {state, settled_at,
+ * head}}`); a normal accepted completion answers `data = null`, which is not an
+ * object and reads as no.
+ */
+function isAlreadySettled(answer) {
+  return Boolean(answer) && typeof answer === "object" && answer.already_settled !== null
+    && typeof answer.already_settled === "object";
+}
+
 /** Mime type for one attachment path the model asked to send. */
 export function mimeForPath(path) {
   const lower = String(path).toLowerCase();