pi-onlyne 0.9.1 → 1.1.0

package/src/agent.mjs

@@ -0,0 +1,963 @@
+// 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.
+//
+// Everything pi-specific lives behind `surface` (see pi-surface.mjs): this
+// module decides *what* the protocol says and hands the *effects* to the
+// surface, which is why the whole state machine is testable against a plain
+// Node unix socket.
+//
+// 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
+// refused report, a socket error, a timeout, a framing fault — because those
+// matter to a host with no panel at all.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createConnection } from "node:net";
+import { basename, join } from "node:path";
+import { createFrameDecoder, encodeFrame } from "./frame.mjs";
+import { createActivity } from "./activity.mjs";
+import {
+  DEFAULT_HEARTBEAT_MS,
+  assignAckArgs,
+  completeReport,
+  describePrincipal,
+  detachArgs,
+  heartbeatReport,
+  helloArgs,
+  headOf,
+  hostBinding,
+  imagePart,
+  injectionText,
+  normalizeOutcome,
+  readyReport,
+  sendEnvelope,
+  sessionRegisterArgs,
+  SEQ_BASE,
+  settledReport,
+  stdinTaskText,
+  welcomeFrom,
+} from "./protocol.mjs";
+import { DEFAULT_RELAY, FORCED_PREFIX, relayEnabled, relayRefusal } from "./relay.mjs";
+
+/** Reconnect ladder in milliseconds, capped like the client's own. */
+export const RECONNECT_LADDER_MS = [1_000, 2_000, 4_000, 8_000, 16_000, 30_000];
+/** How long the socket gets to answer the hello before it is torn down. */
+export const HELLO_TIMEOUT_MS = 5_000;
+/** Default bound on one request round trip. */
+export const REQUEST_TIMEOUT_MS = 30_000;
+/** How long after a turn end the plugin waits for `agent_settled` before it acts. */
+export const SETTLE_FALLBACK_MS = 2_000;
+
+/** Capabilities this plugin implements on the wire. */
+export const CAPABILITIES = ["register", "report", "inject", "recycle"];
+
+/** Mime guess for an attachment the host did not name. */
+function extensionForMime(mime) {
+  switch (mime) {
+    case "image/png":
+      return "png";
+    case "image/jpeg":
+      return "jpg";
+    case "image/gif":
+      return "gif";
+    case "image/webp":
+      return "webp";
+    default:
+      return "bin";
+  }
+}
+
+/** Ids the host mints are uuids; anything else is flattened before it names a file. */
+function safeSegment(value) {
+  return String(value ?? "unknown").replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 80);
+}
+
+export class OnlyneAgent {
+  /**
+   * @param {{
+   *   socketPath: string,
+   *   cwd: string,
+   *   role: string,
+   *   sessionId: string,
+   *   taskId: string,
+   *   surface: any,
+   *   log?: (line: string, data?: unknown) => void,
+   *   activity?: { note: (kind: string, text: string) => any, set: (patch: any) => any, lines: () => string[], events: any[] },
+   *   relay?: { required?: string[], count?: number | null },
+   *   capabilities?: string[],
+   *   heartbeatMs?: number,
+   *   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.cwd = options.cwd;
+    this.role = options.role;
+    this.sessionId = options.sessionId;
+    this.envTaskId = options.taskId;
+    this.surface = options.surface;
+    /** The widget panel's model (`activity.mjs`); seeded with the local role. */
+    this.activity = options.activity ?? createActivity();
+    this.activity.set({ role: options.role });
+    this.log = options.log ?? (() => {});
+    /** The relay guard's policy; the default guards nothing (`relay.mjs`). */
+    this.relay = options.relay ?? DEFAULT_RELAY;
+    this.capabilities = options.capabilities ?? CAPABILITIES;
+    this.heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+    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
+    // once: the environment of a process never changes. Injected by the tests,
+    // which must not depend on the pane they run in.
+    this.host = options.host !== undefined ? options.host : hostBinding(process.env);
+    this.timer = options.timer ?? {
+      set: (fn, ms) => setTimeout(fn, ms),
+      clear: (handle) => clearTimeout(handle),
+    };
+
+    this.closed = false;
+    this.connected = false;
+    this.socket = null;
+    this.welcome = null;
+    this.generation = 1;
+    this.seq = SEQ_BASE;
+    this.nextId = 1;
+    /** @type {Map<number, { resolve: (value: any) => void, timer: any }>} */
+    this.pending = new Map();
+    this.attempt = 0;
+    this.reconnectHandle = null;
+    this.heartbeatHandle = null;
+    this.settleHandle = null;
+    /** @type {Map<string, any>} */
+    this.tasks = new Map();
+    /**
+     * Every role this session handed something to through a `send` the client
+     * accepted: the relay guard's only evidence (`relay.mjs`).
+     *
+     * Process memory, scoped to this session because the agent is: a reconnect
+     * keeps it (the same process re-dials the same client), and a session that
+     * starts fresh starts empty rather than guessing at what an earlier process
+     * sent — the guard judges this session's own deliveries, not history.
+     */
+    this.deliveredTo = new Set();
+    this.injectedTasks = new Set();
+    this.deliveredProse = new Set();
+    /** Pushes that arrived before the handshake finished; see `onFrame`. */
+    this.handshaking = false;
+    this.deferredPushes = [];
+    this.agentState = "ready";
+    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 };
+  }
+
+  // ---------------------------------------------------------------- lifecycle
+
+  /** Open the connection and keep it open until `stop`. */
+  start() {
+    this.closed = false;
+    this.connect();
+  }
+
+  /**
+   * Leave: tell the host this plugin is going away, then stop reconnecting.
+   * @param {string} reason
+   */
+  stop(reason = "quit") {
+    if (this.closed) return;
+    this.closed = true;
+    this.clearTimers();
+    const socket = this.socket;
+    if (this.connected && socket && !socket.destroyed) {
+      // Best effort: the detach frame is queued and the socket is ended so the
+      // bytes leave before the FIN. pi does not wait for the host's answer.
+      this.write({ id: this.nextId++, op: "detach", args: detachArgs(reason) });
+      socket.end();
+    } else if (socket && !socket.destroyed) {
+      socket.destroy();
+    }
+    this.connected = false;
+    this.socket = null;
+    this.activity.set({ connection: "detached", taskId: null });
+    this.notice("state", `detached (${reason})`);
+  }
+
+  /** One line for `/onlyne status`. */
+  status() {
+    return {
+      connected: this.connected,
+      socket: this.socketPath,
+      role: this.role,
+      sessionId: this.sessionId,
+      generation: this.generation,
+      agentState: this.agentState,
+      tasks: this.activeTasks().map((task) => task.taskId),
+      pendingCompletion: this.pendingCompletion?.taskId ?? null,
+      lastError: this.lastError ? String(this.lastError.message ?? this.lastError) : null,
+      activity: this.activity.events.slice(0, 5),
+      stats: { ...this.stats },
+    };
+  }
+
+  // ------------------------------------------------------------- transport
+
+  connect() {
+    if (this.closed || this.socket) return;
+    let socket;
+    try {
+      socket = this.createConnection(this.socketPath);
+    } catch (error) {
+      this.noteFailure(error);
+      this.scheduleReconnect();
+      return;
+    }
+    this.socket = socket;
+    // The error listener goes on before anything else can throw: an `error` event
+    // with no handler takes the whole pi process down, and a plugin bug must
+    // never do that to its host.
+    socket.on("error", (error) => this.noteFailure(error));
+    socket.on("close", () => this.onClose(socket));
+    let decoder;
+    try {
+      decoder = createFrameDecoder({
+        onFrame: (frame) => this.onFrame(frame),
+        onError: (error) => {
+          this.log(`framing fault: ${error.message}`);
+          this.noteFailure(error);
+          this.dropSocket();
+        },
+      });
+    } catch (error) {
+      this.noteFailure(error);
+      this.dropSocket();
+      return;
+    }
+    socket.on("connect", () => {
+      void this.onConnect();
+    });
+    socket.on("data", (chunk) => decoder.push(chunk));
+  }
+
+  onClose(socket) {
+    if (this.socket !== socket) return;
+    this.dropSocket();
+  }
+
+  /** Tear the current socket down and schedule the next attempt. */
+  dropSocket() {
+    const socket = this.socket;
+    this.socket = null;
+    this.connected = false;
+    this.handshaking = false;
+    this.deferredPushes = [];
+    this.rejectAll("connection lost");
+    this.stopHeartbeat();
+    this.activity.set({ connection: this.closed ? "detached" : "reconnecting" });
+    this.notice("state", this.closed ? "detached" : "reconnecting");
+    if (socket && !socket.destroyed) socket.destroy();
+    this.scheduleReconnect();
+  }
+
+  scheduleReconnect() {
+    if (this.closed || this.reconnectHandle) return;
+    const delay = this.ladder[Math.min(this.attempt, this.ladder.length - 1)];
+    this.attempt += 1;
+    this.stats.reconnects += 1;
+    this.reconnectHandle = this.timer.set(() => {
+      this.reconnectHandle = null;
+      if (!this.closed) this.connect();
+    }, delay);
+  }
+
+  async onConnect() {
+    this.attempt = 0;
+    // From here until the welcome is adopted, pushes queue instead of running.
+    this.handshaking = true;
+    const args = helloArgs({
+      role: this.role,
+      session: this.sessionId,
+      taskId: this.envTaskId,
+      pid: process.pid,
+      capabilities: this.capabilities,
+    });
+    let body;
+    try {
+      body = await this.request("hello", args, { timeoutMs: this.helloTimeoutMs });
+    } catch (error) {
+      this.noteFailure(error);
+      this.dropSocket();
+      return;
+    }
+    const welcome = welcomeFrom(body);
+    if (!welcome) {
+      this.noteFailure(new Error("hello answered without a welcome"));
+      this.dropSocket();
+      return;
+    }
+    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";
+    this.activity.set({
+      role: welcome.role,
+      connection: "connected",
+      generation: welcome.generation,
+      // A reconnect inherits the task this process serves: the panel says so
+      // from the first beat, with the assignment still queued behind the hello.
+      taskId: this.activeTaskId() ?? null,
+      phase: this.agentState,
+    });
+    this.notice("state", `connected role=${welcome.role} gen=${welcome.generation} host=${welcome.hostCapabilities.join(",")}`);
+    const prose = welcome.prose.trim();
+    if (prose && !this.deliveredProse.has(prose)) {
+      this.deliveredProse.add(prose);
+      this.surface.proseContext?.(prose, welcome);
+    }
+
+    if (this.envTaskId) {
+      await this.request("session_register", sessionRegisterArgs({
+        sessionId: this.sessionId,
+        taskId: this.envTaskId,
+        generation: this.generation,
+        pid: process.pid,
+        title: `onlyne:${this.role}:${this.sessionId}`,
+      })).catch((error) => this.log(`session_register refused: ${error.message}`));
+    }
+    await this.reportReady();
+    if (this.pendingCompletion) await this.flushPendingCompletion();
+    // The frames that waited for the handshake: the welcome is adopted by now,
+    // so the role prose is context before any assignment opens a turn.
+    this.handshaking = false;
+    this.drainDeferred();
+    if (this.tasks.size > 0) await this.heartbeat().catch(() => {});
+    this.startHeartbeat();
+  }
+
+  /**
+   * Run the pushes that arrived during the handshake, in arrival order. Called
+   * once the welcome has been adopted; a socket that died first already
+   * discarded the queue.
+   */
+  drainDeferred() {
+    const queued = this.deferredPushes;
+    this.deferredPushes = [];
+    for (const frame of queued) this.onFrame(frame);
+  }
+
+  /**
+   * Write one frame. Never throws: a dead socket is a reconnect, not a crash.
+   * @param {any} frame
+   */
+  write(frame) {
+    const socket = this.socket;
+    if (!socket || socket.destroyed || !socket.writable) return false;
+    try {
+      socket.write(encodeFrame(frame));
+      return true;
+    } catch (error) {
+      this.noteFailure(error);
+      this.dropSocket();
+      return false;
+    }
+  }
+
+  /**
+   * Send one request and wait for its response body.
+   * @param {string} op
+   * @param {any} args
+   * @param {{ timeoutMs?: number }} [options]
+   */
+  request(op, args, options = {}) {
+    const id = this.nextId++;
+    const timeoutMs = options.timeoutMs ?? this.requestTimeoutMs;
+    return new Promise((resolve, reject) => {
+      const timer = this.timer.set(() => {
+        this.pending.delete(id);
+        reject(new Error(`${op} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      if (!this.write({ id, op, args })) {
+        this.pending.delete(id);
+        this.timer.clear(timer);
+        reject(new Error(`${op} not delivered: socket is down`));
+      }
+    });
+  }
+
+  onFrame(frame) {
+    if (!frame || typeof frame !== "object") return;
+    if (frame.reply_to !== undefined && frame.reply_to !== null) {
+      const entry = this.pending.get(frame.reply_to);
+      if (!entry) return;
+      this.pending.delete(frame.reply_to);
+      this.timer.clear(entry.timer);
+      if (frame.ok) entry.resolve(frame.data ?? null);
+      else entry.reject(new Error(`${frame.error?.code ?? "error"}: ${frame.error?.message ?? "refused"}`));
+      return;
+    }
+    // A push can share one TCP chunk with the hello reply, and the decoder
+    // hands frames over in arrival order: without this gate an `assign` would
+    // be injected before the welcome that carries the role prose and the
+    // generation, which is the order the host's ready barrier (§6) assumes.
+    // Pushes wait for the handshake; replies never do, or waiting would
+    // deadlock the very request the handshake is waiting on.
+    if (this.handshaking) {
+      this.deferredPushes.push(frame);
+      return;
+    }
+    const op = frame.op;
+    const args = frame.args ?? {};
+    if (op === "assign") void this.onAssign(args);
+    else if (op === "probe") void this.probe();
+    else if (op === "recycle") void this.onRecycle(args);
+    else if (op === "config_get") void this.onConfigGet(args);
+    else if (op === "bye") {
+      this.notice("state", `host bye: ${args.reason ?? "unspecified"}`);
+      this.dropSocket();
+    } else if (op) this.log(`ignoring host op ${op}`);
+  }
+
+  rejectAll(reason) {
+    for (const [id, entry] of this.pending) {
+      this.pending.delete(id);
+      this.timer.clear(entry.timer);
+      entry.reject(new Error(reason));
+    }
+  }
+
+  noteFailure(error) {
+    this.lastError = error;
+    this.log(`socket error: ${error?.message ?? error}`);
+  }
+
+  /**
+   * One human-facing event: record it, then draw the best host surface.
+   * Hosts with `ctx.ui.setWidget` redraw the panel. Other hosts keep a footer
+   * line and a `[pi-onlyne]` stderr line.
+   *
+   * @param {"in" | "dup" | "out" | "warn" | "state"} kind
+   * @param {string} text
+   */
+  notice(kind, text) {
+    this.activity.note(kind, text);
+    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]);
+    this.log(`${kind}: ${text}`);
+  }
+
+  // --------------------------------------------------------------- reports
+
+  async reportReady() {
+    const taskId = this.envTaskId;
+    if (!taskId || !this.connected) return;
+    this.seq += 1;
+    try {
+      await this.request("report", readyReport({
+        taskId,
+        sessionId: this.sessionId,
+        generation: this.generation,
+        seq: this.seq,
+      }));
+      this.stats.reports += 1;
+      this.notice("state", `ready ${taskId.slice(0, 8)}`);
+    } catch (error) {
+      this.log(`ready refused: ${error.message}`);
+    }
+  }
+
+  /**
+   * One heartbeat for the task this connection serves.
+   *
+   * 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.
+   */
+  async heartbeat(agent = this.agentState) {
+    if (!this.connected) return;
+    const taskId = this.activeTaskId();
+    if (!taskId) return;
+    if (this.tasks.get(taskId)?.completed) return;
+    this.agentState = agent;
+    this.seq += 1;
+    await this.request("report", heartbeatReport({
+      taskId,
+      generation: this.generation,
+      seq: this.seq,
+      agent,
+      host: this.host,
+    }));
+    this.stats.reports += 1;
+    this.lastPhase = agent;
+  }
+
+  /** Tasks still owing a completion; a finished task keeps its record. */
+  activeTasks() {
+    return [...this.tasks.values()].filter((task) => !task.completed);
+  }
+
+  /** The task this connection is working on right now, if any. */
+  activeTaskId() {
+    return this.activeTasks()[0]?.taskId ?? this.envTaskId;
+  }
+
+  startHeartbeat() {
+    if (this.heartbeatHandle) return;
+    this.heartbeatHandle = this.timer.set(() => {
+      this.heartbeatHandle = null;
+      if (!this.closed && this.connected) {
+        void this.heartbeat().catch((error) => this.log(`heartbeat refused: ${error.message}`));
+      }
+      this.startHeartbeat();
+    }, this.heartbeatMs);
+  }
+
+  stopHeartbeat() {
+    if (!this.heartbeatHandle) return;
+    this.timer.clear(this.heartbeatHandle);
+    this.heartbeatHandle = null;
+  }
+
+  clearTimers() {
+    this.stopHeartbeat();
+    if (this.reconnectHandle) {
+      this.timer.clear(this.reconnectHandle);
+      this.reconnectHandle = null;
+    }
+    if (this.settleHandle) {
+      this.timer.clear(this.settleHandle);
+      this.settleHandle = null;
+    }
+    this.rejectAll("agent stopped");
+  }
+
+  // ------------------------------------------------------------ host → plugin
+
+  async onAssign(args) {
+    const envelope = args.envelope ?? {};
+    const taskId = args.task_id ?? envelope.causality?.task ?? null;
+    if (!taskId) {
+      this.log("assign carried no task id; ignored");
+      return;
+    }
+    if (this.injectedTasks.has(taskId)) {
+      this.stats.duplicates += 1;
+      this.notice("dup", `task ${taskId.slice(0, 8)} already injected`);
+      await this.ack(taskId, true, "duplicate");
+      return;
+    }
+    this.injectedTasks.add(taskId);
+    this.stats.assigns += 1;
+    if (typeof args.generation === "number") this.generation = args.generation;
+
+    const attachments = this.writeAttachments(taskId, envelope);
+    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) });
+
+    this.tasks.set(taskId, {
+      taskId,
+      envelopeId: envelope.id ?? null,
+      // Who handed this task over: the relay guard's count mode does not count
+      // a send straight back to it (`relay.mjs`).
+      upstream: envelope.from?.role?.role ?? null,
+      turnsSinceAssign: 0,
+      turns: 0,
+      errored: false,
+      head: "",
+      failed: false,
+    });
+    this.agentState = "running";
+    this.surface.wakeUser?.(text, attachments.map((item) => item.part));
+    this.surface.customEntry?.("onlyne-assign", {
+      taskId,
+      envelopeId: envelope.id ?? null,
+      kind: envelope.kind ?? "task",
+      proseInjected: proseIsNew,
+      prose,
+      attachments: attachments.map((item) => item.path),
+    });
+    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.startHeartbeat();
+    await this.ack(taskId, true, null);
+  }
+
+  async ack(taskId, accepted, reason) {
+    try {
+      await this.request("assign_ack", assignAckArgs({ taskId, accepted, reason }));
+    } catch (error) {
+      this.log(`assign_ack refused: ${error.message}`);
+    }
+  }
+
+  /** The host asked for a fresh observation: one heartbeat is the answer. */
+  async probe() {
+    try {
+      await this.heartbeat();
+      this.notice("state", "probe answered with a heartbeat");
+    } catch (error) {
+      this.log(`probe heartbeat refused: ${error.message}`);
+    }
+  }
+
+  async onConfigGet(args) {
+    const task = stdinTaskText(args);
+    if (task) {
+      // The no-`inject` route: the host hands the payload over as a config key.
+      this.notice("in", `stdin task: ${headOf(task.text)}`);
+      this.surface.wakeUser?.(`[onlyne] task body (delivered as stdin):\n\n${task.text}`, []);
+      return;
+    }
+    this.log(`config_get ${args?.key ?? "?"} is not implemented by this plugin`);
+  }
+
+  async onRecycle(args) {
+    this.stats.recycles += 1;
+    const taskId = args.task_id ?? this.activeTaskId();
+    this.notice("state", `recycled: ${args.reason ?? "operator"}`);
+    if (taskId && args.outcome && this.tasks.get(taskId) && !this.tasks.get(taskId).completed) {
+      await this.complete(taskId, args.outcome, `recycled: ${args.reason ?? "operator"}`, {
+        exitProcess: false,
+      }).catch((error) => this.log(`recycle completion refused: ${error.message}`));
+    }
+    this.stop(`recycle:${args.reason ?? "operator"}`);
+    this.exitSession(args.reason ?? "recycle");
+  }
+
+  // ------------------------------------------------------------ pi → plugin
+
+  /** A turn started: the plugin's own agent fact is `running`. */
+  onTurnStart() {
+    const task = [...this.tasks.values()].find((item) => !item.completed);
+    if (task) task.turns += 1;
+    void this.heartbeat("running").catch((error) => this.log(`heartbeat refused: ${error.message}`));
+  }
+
+  /** A turn ended: the agent is idle, and the settle window starts. */
+  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}`));
+    this.armSettleFallback();
+  }
+
+  /** pi will not continue on its own: run the completion exit. */
+  onSettled() {
+    this.clearSettleFallback();
+    this.trySettle();
+  }
+
+  /**
+   * 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.
+   */
+  trySettle() {
+    if (this.closed || this.activeTasks().length === 0) return;
+    if (this.surface.isIdle?.() === false) {
+      this.armSettleFallback();
+      return;
+    }
+    void this.settleNow().catch((error) => this.log(`completion failed: ${error.message}`));
+  }
+
+  /** A failed turn: the task's outcome is `failed` unless it already ended. */
+  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();
+  }
+
+  /**
+   * The last assistant text seen, kept as the completion summary for a task the
+   * model never handed an explicit argument over for.
+   *
+   * 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.
+   */
+  noteAssistantText(text) {
+    const flat = headOf(text);
+    if (!flat) return;
+    for (const task of this.tasks.values()) {
+      if (!task.completed) task.head = flat;
+    }
+  }
+
+  armSettleFallback() {
+    this.clearSettleFallback();
+    if (this.closed || this.activeTasks().length === 0) return;
+    this.settleHandle = this.timer.set(() => {
+      this.settleHandle = null;
+      this.trySettle();
+    }, this.settleFallbackMs);
+  }
+
+  clearSettleFallback() {
+    if (!this.settleHandle) return;
+    this.timer.clear(this.settleHandle);
+    this.settleHandle = null;
+  }
+
+  /**
+   * 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.
+   */
+  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);
+    }
+  }
+
+  /**
+   * `onlyne_complete`: an explicit outcome from the model, which wins over the
+   * auto rule.
+   *
+   * 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
+   * assistant text never stands in for it. An absent or blank `text` carries no
+   * deliverable at all and falls back to that assistant text.
+   *
+   * The relay guard runs first, for every outcome, when the workspace's
+   * `relay.toml` names a minimum downstream handoff: a session that still owes
+   * one cannot report a terminal fact. A refusal throws before anything is
+   * written, queued or detached — no completion report, no exit, no state on
+   * the task — so the session stays live and the same call lands once the
+   * handoff has gone out. `force: true` with a non-empty `reason` waives the
+   * guard and stamps the head with `relay-guard-forced: <reason>`, which is the
+   * ledger's audit trail for a completion that skipped the guard.
+   *
+   * @param {{ outcome?: string, text?: string, force?: boolean, reason?: string }} input
+   */
+  async completeFromTool(input = {}) {
+    const task = [...this.tasks.values()].find((item) => !item.completed);
+    const taskId = task?.taskId ?? this.envTaskId;
+    if (!taskId) throw new Error("onlyne: no task is assigned to this session");
+    const explicit = headOf(input.text);
+    let head = explicit || task?.head || "";
+    if (relayEnabled(this.relay)) {
+      const refusal = relayRefusal(this.relay, this.deliveredTo, {
+        role: this.role,
+        upstream: task?.upstream ?? null,
+      });
+      if (refusal) {
+        const reason = headOf(input.reason);
+        if (input.force !== true || !reason) {
+          this.log(refusal);
+          this.notice("warn", refusal);
+          throw new Error(`onlyne: ${refusal}`);
+        }
+        head = headOf(`${FORCED_PREFIX}${reason}${explicit ? ` | ${explicit}` : ""}`);
+        this.notice("warn", `relay guard waived: ${reason}`);
+      }
+    }
+    return this.complete(taskId, normalizeOutcome(input.outcome), head);
+  }
+
+  /**
+   * Report the terminal fact. If the socket is down the report is remembered and
+   * flushed on the next hello, so a completion survives a client restart.
+   *
+   * The `report` request is the durable handover, and it is the reason the exit
+   * waits for its answer: the client replies from `serve_connection`
+   * (`crates/onlyne-client/src/adapter_socket.rs`) only after `on_out` settled
+   * the session row, acked the delivery and wrote the `Completion` envelope —
+   * onto the server link, or into `client.db` intents when that link is down
+   * (`crates/onlyne-client/src/dispatch.rs` `on_out`). A returned response
+   * therefore means this process can leave without losing the outcome, and a
+   * rejected or queued report must never exit.
+   *
+   * @param {{ exitProcess?: boolean }} [options] `false` for the recycle path,
+   * which ends the process after its own detach frame instead.
+   */
+  async complete(taskId, outcome, head, options = {}) {
+    const exitProcess = options.exitProcess ?? true;
+    const normalized = normalizeOutcome(outcome);
+    const summary = headOf(head);
+    const task = this.tasks.get(taskId);
+    if (task?.completed) return { taskId, outcome: normalized, head: summary, duplicate: true };
+    if (task) task.completed = true;
+    const report = completeReport({ taskId, outcome: normalized, head: summary });
+    if (!this.connected) {
+      this.pendingCompletion = { taskId, report, outcome: normalized, exitProcess };
+      this.activity.set({ taskId, phase: `${normalized} queued` });
+      this.notice("warn", `complete ${taskId.slice(0, 8)} ${normalized} queued: socket down`);
+      return { taskId, outcome: normalized, head: summary, queued: true };
+    }
+    await this.request("report", report);
+    this.stats.completions += 1;
+    this.surface.customEntry?.("onlyne-complete", { taskId, outcome: normalized, head: summary });
+    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);
+    }
+    return { taskId, outcome: normalized, head: summary };
+  }
+
+  /**
+   * Ask pi to end the process this session runs in.
+   *
+   * One `ctx.shutdown()` per process: pi marks the request and runs its
+   * teardown at `agent_settled` (`modes/interactive/interactive-mode.js`,
+   * `modes/rpc/rpc-mode.js` in pi 0.85.1), which then emits `session_shutdown`
+   * and that hook detaches this connection. The client daemon is unaffected:
+   * the role runtime outlives every session it spawns.
+   */
+  exitSession(reason) {
+    if (this.exitRequested) return;
+    this.exitRequested = true;
+    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;
+    this.pendingCompletion = null;
+    try {
+      await this.request("report", pending.report);
+      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`);
+      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) {
+      this.pendingCompletion = pending;
+      this.log(`queued completion still refused: ${error.message}`);
+    }
+  }
+
+  /**
+   * `onlyne_send`: submit one envelope.
+   * @param {{ to: string, text?: string, kind?: string, imagePath?: string | null }} input
+   */
+  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 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
+    // never a handoff, and the relay guard must not read one as delivered. Any
+    // kind counts — `note` and `task` are both the session reaching that role.
+    this.deliveredTo.add(String(input.to));
+    return { queued: true, op_id: envelope.op_id ?? null, kind, to: input.to, data };
+  }
+
+  // ------------------------------------------------------------ attachments
+
+  /**
+   * Write one inbound image to the workspace and return the path plus the pi
+   * image part, so the model both sees the picture and can address the file.
+   */
+  writeAttachments(taskId, envelope) {
+    const image = envelope?.body?.image;
+    if (!image || typeof image.data_base64 !== "string") return [];
+    const mime = typeof image.mime === "string" && image.mime ? image.mime : "image/png";
+    const name = safeSegment(image.name ?? `image.${extensionForMime(mime)}`);
+    const dir = join(this.cwd, ".onlyne", "tmp", "attachments");
+    const path = join(dir, `${safeSegment(taskId)}-${safeSegment(envelope.id)}-${name}`);
+    try {
+      const bytes = Buffer.from(image.data_base64, "base64");
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      writeFileSync(path, bytes, { mode: 0o600 });
+      this.notice("state", `attachment ${basename(path)}`);
+      return [{ path, part: { type: "image", mime, data: image.data_base64, name } }];
+    } catch (error) {
+      this.log(`attachment write failed: ${error.message}`);
+      return [];
+    }
+  }
+}
+
+/** Mime type for one attachment path the model asked to send. */
+export function mimeForPath(path) {
+  const lower = String(path).toLowerCase();
+  if (lower.endsWith(".png")) return "image/png";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+  if (lower.endsWith(".gif")) return "image/gif";
+  if (lower.endsWith(".webp")) return "image/webp";
+  throw new Error(`onlyne: unsupported image type for ${path}`);
+}