pi-onlyne 2.1.0 → 2.3.0

package/src/agent.test.mjs

@@ -117,6 +117,9 @@ async function waitFor(predicate, { timeoutMs = 2_000, stepMs = 5 } = {}) {
  * reports before answering the rest, the way a client whose settle failed would.
  * `request` sends a host frame carrying an id, which is how the plugin is asked
  * for an answer (`nudge`); `answers` reads what came back.
+ * `alreadySettled` answers every `complete` report with the client's
+ * already-settled shape in `data`, the way a client that had settled the task
+ * before the report arrived does.
  */
 class FakeHost {
   constructor({
@@ -125,6 +128,7 @@ class FakeHost {
     failSend = false,
     handoffError = null,
     failCompletions = 0,
+    alreadySettled = null,
   } = {}) {
     this.server = createServer((socket) => this.onConnection(socket));
     this.frames = [];
@@ -135,6 +139,7 @@ class FakeHost {
     this.failSend = failSend;
     this.handoffError = handoffError;
     this.failCompletions = failCompletions;
+    this.alreadySettled = alreadySettled;
     this.held = [];
   }
 
@@ -189,6 +194,9 @@ class FakeHost {
       }));
       return;
     }
+    if (this.alreadySettled && frame.op === "report" && frame.args?.kind === "complete") {
+      body = { ok: true, data: { already_settled: this.alreadySettled } };
+    }
     if (this.failSend && frame.op === "send") {
       socket.write(encodeFrame({
         reply_to: frame.id,
@@ -293,10 +301,11 @@ async function startAgent({
   failSend = false,
   handoffError = null,
   failCompletions = 0,
+  alreadySettled = null,
 } = {}) {
   const dir = mkdtempSync(join(tmpdir(), "pi-onlyne-agent-"));
   const socketPath = join(dir, "s");
-  const host = new FakeHost({ coalesceAssign, holdCompletion, failSend, handoffError, failCompletions });
+  const host = new FakeHost({ coalesceAssign, holdCompletion, failSend, handoffError, failCompletions, alreadySettled });
   await host.listen(socketPath);
   const logs = [];
   const agent = new OnlyneAgent({
@@ -308,9 +317,6 @@ async function startAgent({
     surface,
     log: (line) => logs.push(line),
     ladder: [20, 40, 80],
-    // The fallback is the agent_settled-less path; a test that wants it asks for
-    // a short window, and every other test drives the exit explicitly.
-    settleFallbackMs: options.settleFallbackMs ?? 30_000,
     heartbeatMs: options.heartbeatMs ?? 60_000,
     ...(capabilities ? { capabilities } : {}),
     ...(options.host !== undefined ? { host: options.host } : {}),
@@ -484,7 +490,7 @@ test("a fresh agent opens with hello, registers and reports ready", async () =>
     plugin: "pi-onlyne",
     version: PACKAGE_VERSION,
     kind: "agent",
-    capabilities: ["register", "report", "inject", "recycle"],
+    capabilities: ["register", "report", "inject", "recycle", "resume"],
     mount: { role: "planner", session: SESSION_ID, task_id: TASK_ID, pid: process.pid },
   });
 
@@ -534,6 +540,27 @@ test("an assign is injected once, acked, and a redelivery changes nothing", asyn
   assert.deepEqual(second[1], { task_id: TASK_ID, accepted: true, reason: "duplicate" });
 });
 
+// A note is communication, not work: the session is woken and the delivery is
+// acknowledged, and no task record opens, so nothing beats for it and no turn
+// end can demand a completion.
+test("a note is injected, acked, and opens no task", async () => {
+  const { agent, host, surface } = await startAgent();
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+
+  const args = structuredClone(assignArgs());
+  args.envelope.kind = "note";
+  args.text = "From planner:\n\nwhich way is the flag?";
+  host.notify("assign", args);
+  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+
+  assert.equal(surface.calls.wakeUser[0].text, args.text, "the frame's text is injected unchanged");
+  assert.equal(surface.calls.entries[0].data.kind, "note");
+  const acks = await waitFor(() => (host.of("assign_ack").length >= 1 ? host.of("assign_ack") : null));
+  assert.deepEqual(acks[0], { task_id: TASK_ID, accepted: true });
+  assert.deepEqual(agent.status().tasks, []);
+});
+
 // A follow-up arrives as its own envelope under the task id the session is
 // already running. Keying the injection guard on the task swallowed it: the
 // panel said `already injected`, nothing reached the model, and the row the
@@ -688,30 +715,37 @@ test("a turn-end heartbeat after the completion never leaves the plugin", async
   assert.deepEqual(host.of("report").slice(reports), [], "the completion is the last report");
 });
 
-// The plugin still owes one report at a turn end: the failure it witnessed
-// itself. That report waits for the idle it is about, exactly as the phase-based
-// signal always did.
-test("a busy pi holds the failed-turn report until it is waiting for input", async () => {
-  let waiting = false;
-  const surface = fakeSurface({ waiting: () => waiting });
-  const { agent, host } = await startAgent({ surface, options: { settleFallbackMs: 40 } });
+// A turn that ends with an error is not a verdict. 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 from here would
+// race work that is still going. The client's own turn-end rule (§3c) owns the
+// ending, and its sweeps own a session whose agent died; the plugin states its
+// phase and nothing else.
+test("a turn error sends no completion, even after a settle and a wait", async () => {
+  const { agent, host, surface } = await startAgent();
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
   host.notify("assign", assignArgs());
   await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+
+  agent.onTurnStart();
   agent.onTurnError("provider exploded");
-  await new Promise((resolve) => setTimeout(resolve, 80));
-  assert.deepEqual(completions(host), [], "a busy pi is not reported on yet");
+  await waitFor(() => heartbeats(host).some((observed) => observed.agent === "running"));
+  agent.onSettled();
+  // Past the window the deleted fallback used to fire in (40 ms in the harness
+  // that pinned it), so a plugin that still armed one would have reported here.
+  await new Promise((resolve) => setTimeout(resolve, 150));
 
-  waiting = true;
-  const complete = await waitFor(() => completions(host)[0] ?? null);
-  assert.deepEqual(complete.data, { task_id: TASK_ID, outcome: "failed", head: "provider exploded" });
+  assert.deepEqual(completions(host), [], "a failed turn reports no outcome nobody claimed");
+  assert.deepEqual(agent.status().tasks, [TASK_ID], "the task is still open");
+  assert.deepEqual(surface.calls.exits, [], "and the session stays mounted");
 });
 
-test("a live background task holds the failed-turn report until its task is terminal", async () => {
-  let backgroundWork = true;
-  const surface = fakeSurface({ backgroundWork: () => backgroundWork });
-  const { agent, host } = await startAgent({ surface, options: { settleFallbackMs: 40 } });
+// What the error does supply is the head fallback: a completion whose summary
+// carries nothing still has a display line, and it is the sentence the failed
+// turn left behind.
+test("an explicit completion after a turn error uses the error as its head", async () => {
+  const { agent, host, surface } = await startAgent();
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
   host.notify("assign", assignArgs());
@@ -719,14 +753,11 @@ test("a live background task holds the failed-turn report until its task is term
 
   agent.onTurnStart();
   agent.onTurnError("provider exploded");
-  await waitFor(() => heartbeats(host).at(-1)?.agent === "running");
-  await new Promise((resolve) => setTimeout(resolve, 80));
-  assert.deepEqual(completions(host), [], "work off the agent loop keeps the report off");
+  const result = await agent.completeFromTool({ outcome: "done" });
 
-  backgroundWork = false;
-  agent.onSettled();
-  const complete = await waitFor(() => completions(host)[0] ?? null);
-  assert.deepEqual(complete.data, { task_id: TASK_ID, outcome: "failed", head: "provider exploded" });
+  assert.equal(result.head, "provider exploded", "the error text is the head fallback");
+  const [complete] = completions(host);
+  assert.deepEqual(complete.data, { task_id: TASK_ID, outcome: "done", head: "provider exploded" });
 });
 
 // The turn-end rule has one owner, the client (`docs/v2-CONTRACT.md` §3c): a
@@ -735,15 +766,15 @@ test("a live background task holds the failed-turn report until its task is term
 // plugin's answer to a clean turn end is its beat and nothing else — no
 // injection, no count, and no outcome nobody claimed.
 test("a turn that ends without a completion settles nothing and says nothing", async () => {
-  const { agent, host, surface } = await startAgent({ options: { settleFallbackMs: 40 } });
+  const { agent, host, surface } = await startAgent();
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
   host.notify("assign", assignArgs());
   await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
   agent.noteAssistantText("OK");
 
-  // Two clean turns and a settle after each: the fallback window and the
-  // settled signal both land, and neither has anything to decide.
+  // Two clean turns and a settle after each: the settled signal lands, and it
+  // has nothing to decide.
   agent.onTurnStart();
   agent.onTurnEnd();
   agent.onSettled();
@@ -772,18 +803,6 @@ test("an assigned task that never ran is not completed", async () => {
   assert.deepEqual(agent.status().tasks, [TASK_ID]);
 });
 
-test("a failed turn settles the task as failed with the error as head", async () => {
-  const { agent, host, surface } = await startAgent();
-  agent.start();
-  await waitFor(() => host.of("report").length >= 1);
-  host.notify("assign", assignArgs());
-  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
-  agent.onTurnStart();
-  agent.onTurnError("provider exploded");
-  const complete = await waitFor(() => host.of("report").find((report) => report.kind === "complete"));
-  assert.deepEqual(complete.data, { task_id: TASK_ID, outcome: "failed", head: "provider exploded" });
-});
-
 test("an explicit tool outcome wins and a second completion is refused", async () => {
   const { agent, host, surface } = await startAgent();
   agent.start();
@@ -1277,7 +1296,6 @@ test("a host that never answers the hello is dropped and retried", async () => {
     log: (line) => logs.push(line),
     ladder: [20],
     helloTimeoutMs: 40,
-    settleFallbackMs: 30,
   });
   cleanups.push(async () => {
     agent.stop("test");
@@ -1314,6 +1332,40 @@ test("a completion sends the summary as the head and adds nothing else", async (
   assert.equal(JSON.stringify(completions(host)[0]), COMPLETE_VECTOR);
 });
 
+// A client that had already settled this task answers the report with its own
+// record instead of `data: null`. The completion still leaves the task settled —
+// the client's row is the authority — but the caller hands the record on, so the
+// tool result can say the call changed nothing rather than claim the outcome.
+test("a report the client answers as already settled comes back as the client's record", async () => {
+  const settled = {
+    state: "failed",
+    settled_at: "2026-10-11T05:15:47Z",
+    head: "provider exploded",
+  };
+  const { agent, host } = await startAgent({ alreadySettled: settled });
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+
+  const result = await agent.completeFromTool({ outcome: "done", summary: "finished it" });
+  assert.deepEqual(result, {
+    taskId: TASK_ID,
+    outcome: "done",
+    head: "finished it",
+    alreadySettled: settled,
+  });
+  assert.equal(completions(host).length, 1, "the report still went out");
+  assert.deepEqual(agent.status().tasks, [], "the client's row is the authority");
+});
+
+test("a normal accepted completion carries no already-settled record", async () => {
+  const { agent, host } = await startAgent();
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+
+  const result = await agent.completeFromTool({ outcome: "done", summary: "finished it" });
+  assert.deepEqual(result, { taskId: TASK_ID, outcome: "done", head: "finished it" });
+});
+
 test("details and files ride the completion unchanged", async () => {
   const { agent, host } = await startAgent();
   agent.start();
@@ -1374,7 +1426,7 @@ test("a nudge hands the client's sentence over as it stands and answers ok", asy
   // A nudge is not a delivery and not a report: the task stays open, its record
   // is untouched, and no frame of the plugin's own follows.
   assert.equal(agent.tasks.get(TASK_ID), record);
-  assert.equal(record.errored, false);
+  assert.equal(record.head, "", "the nudge leaves the head fallback alone");
   assert.deepEqual(host.of("report").slice(reportsBefore), []);
 });
 

package/src/config.mjs

@@ -9,11 +9,14 @@
 // deliberate off switch.
 
 import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 
 /** Where the switch file lives, relative to the pi working directory. */
 export const CONFIG_RELATIVE_PATH = join(".pi", "onlyne.json");
 
+/** Where the workspace's own client configuration lives. */
+export const WORKSPACE_CONFIG_RELATIVE_PATH = join(".onlyne", "config.toml");
+
 /** Defaults: on, and connecting as soon as a session starts. */
 export const DEFAULT_CONFIG = Object.freeze({
   enabled: true,
@@ -34,7 +37,16 @@ export function loadConfig(cwd, options = {}) {
   try {
     raw = readFile(path);
   } catch {
-    return { ...DEFAULT_CONFIG, path, warning: null, present: false };
+    return {
+      ...DEFAULT_CONFIG,
+      role: null,
+      sessionId: null,
+      workspace: null,
+      resident: false,
+      path,
+      warning: null,
+      present: false,
+    };
   }
   let parsed;
   try {
@@ -42,18 +54,36 @@ export function loadConfig(cwd, options = {}) {
   } catch (error) {
     return {
       ...DEFAULT_CONFIG,
+      role: null,
+      sessionId: null,
+      workspace: null,
+      resident: false,
       path,
       warning: `${path} is not valid JSON (${error instanceof Error ? error.message : String(error)}); using defaults`,
       present: true,
     };
   }
   if (!parsed || typeof parsed !== "object") {
-    return { ...DEFAULT_CONFIG, path, warning: `${path} must hold a JSON object; using defaults`, present: true };
+    return {
+      ...DEFAULT_CONFIG,
+      role: null,
+      sessionId: null,
+      workspace: null,
+      resident: false,
+      path,
+      warning: `${path} must hold a JSON object; using defaults`,
+      present: true,
+    };
   }
   const watch = parsed.watch && typeof parsed.watch === "object" ? parsed.watch : {};
+  const rawSessionId = parsed.sessionId ?? parsed.session_id ?? parsed.session_alias;
   return {
     enabled: typeof parsed.enabled === "boolean" ? parsed.enabled : DEFAULT_CONFIG.enabled,
     autoStart: typeof watch.autoStart === "boolean" ? watch.autoStart : DEFAULT_CONFIG.autoStart,
+    role: typeof parsed.role === "string" && parsed.role.trim() !== "" ? parsed.role.trim() : null,
+    sessionId: typeof rawSessionId === "string" && rawSessionId.trim() !== "" ? rawSessionId.trim() : null,
+    workspace: typeof parsed.workspace === "string" && parsed.workspace.trim() !== "" ? parsed.workspace.trim() : null,
+    resident: typeof parsed.resident === "boolean" ? parsed.resident : false,
     path,
     warning: null,
     present: true,
@@ -75,3 +105,143 @@ export function sessionIdentity(env) {
   if (!role || !sessionId || !taskId) return null;
   return { role, sessionId, taskId };
 }
+
+/**
+ * Parse the subset of `<workspace>/.onlyne/config.toml` relevant to a
+ * pre-started resident agent (`role`, `placement`, `[client.session]`).
+ *
+ * @param {string} raw
+ * @returns {{ role: string | null, placement: string | null, scope: string | null, sessionId: string | null }}
+ */
+export function parseWorkspaceConfigToml(raw) {
+  let section = "";
+  let role = null;
+  let placement = null;
+  let scope = null;
+  let sessionId = null;
+  for (const rawLine of String(raw).split(/\r?\n/)) {
+    const line = rawLine.replace(/#.*$/, "").trim();
+    if (!line) continue;
+    const secMatch = line.match(/^\[([^\]]+)\]$/);
+    if (secMatch) {
+      section = secMatch[1].trim();
+      continue;
+    }
+    const kvMatch = line.match(/^([A-Za-z0-9_.-]+)\s*=\s*"([^"]*)"/);
+    if (!kvMatch) continue;
+    const [, key, val] = kvMatch;
+    const trimmed = val.trim();
+    if (!trimmed) continue;
+    if (section === "" && key === "role") role = trimmed;
+    else if (section === "" && key === "placement") placement = trimmed.toLowerCase();
+    else if (section === "client.session" && key === "scope") scope = trimmed.toLowerCase();
+    else if (section === "client.session" && (key === "session_id" || key === "session_alias")) {
+      sessionId = sessionId ?? trimmed;
+    }
+  }
+  return { role, placement, scope, sessionId };
+}
+
+/**
+ * Discover a resident / pre-started session identity when the agent is launched
+ * before `onlyne-client` (no `ONLYNE_TASK_ID` in `env`).
+ *
+ * Activates when any of the following holds:
+ * 1. `ONLYNE_ROLE` is set in `env` (with optional `ONLYNE_SESSION_ID` / `ONLYNE_WORKSPACE`),
+ * 2. `.pi/onlyne.json` sets `"role"`, `"sessionId"`, or `"resident": true`, or
+ * 3. `<workspace>/.onlyne/config.toml` declares `placement = "external"`,
+ *    `[client.session] scope = "role"`, or `[client.session] session_id` / `session_alias`.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @param {string} cwd
+ * @param {{ readFile?: (path: string) => string }} [options]
+ * @returns {{ role: string, sessionId: string | null, taskId: string | null, resident: true, workspaceRoot: string } | null}
+ */
+export function residentIdentity(env, cwd, options = {}) {
+  const readFile = options.readFile ?? ((path) => readFileSync(path, "utf8"));
+  const config = loadConfig(cwd, options);
+  const envRole = typeof env.ONLYNE_ROLE === "string" && env.ONLYNE_ROLE.trim() !== "" ? env.ONLYNE_ROLE.trim() : null;
+  const envSessionId =
+    typeof (env.ONLYNE_SESSION_ID ?? env.ONLYNE_SESSION_ALIAS) === "string" &&
+    (env.ONLYNE_SESSION_ID ?? env.ONLYNE_SESSION_ALIAS).trim() !== ""
+      ? (env.ONLYNE_SESSION_ID ?? env.ONLYNE_SESSION_ALIAS).trim()
+      : null;
+  const envTaskId =
+    typeof env.ONLYNE_TASK_ID === "string" && env.ONLYNE_TASK_ID.trim() !== "" ? env.ONLYNE_TASK_ID.trim() : null;
+  const envWorkspace =
+    typeof env.ONLYNE_WORKSPACE === "string" && env.ONLYNE_WORKSPACE.trim() !== ""
+      ? env.ONLYNE_WORKSPACE.trim()
+      : null;
+  const envResident =
+    typeof env.ONLYNE_RESIDENT === "string" &&
+    ["1", "true", "yes", "on"].includes(env.ONLYNE_RESIDENT.trim().toLowerCase());
+
+  const hintRole = envRole ?? config.role;
+  const explicitWorkspace = envWorkspace ?? config.workspace;
+  let workspaceRoot = explicitWorkspace
+    ? isAbsolute(explicitWorkspace)
+      ? explicitWorkspace
+      : resolve(cwd, explicitWorkspace)
+    : cwd;
+
+  let toml = { role: null, placement: null, scope: null, sessionId: null };
+  const candidateRoots = [];
+  if (explicitWorkspace) {
+    candidateRoots.push(workspaceRoot);
+  } else {
+    let cur = resolve(cwd);
+    for (let depth = 0; depth < 4; depth++) {
+      candidateRoots.push(cur);
+      if (hintRole) candidateRoots.push(join(cur, hintRole));
+      const parent = dirname(cur);
+      if (parent === cur) break;
+      cur = parent;
+    }
+  }
+  for (const candidate of candidateRoots) {
+    try {
+      const raw = readFile(join(candidate, WORKSPACE_CONFIG_RELATIVE_PATH));
+      const parsed = parseWorkspaceConfigToml(raw);
+      if (parsed.role && (!hintRole || parsed.role === hintRole)) {
+        toml = parsed;
+        workspaceRoot = candidate;
+        break;
+      }
+    } catch {
+      /* try next candidate */
+    }
+  }
+  if (!explicitWorkspace && !toml.role && hintRole && workspaceRoot === cwd) {
+    // If started in a cluster root (`<root>/.onlyne/spec.toml` exists), the
+    // role workspace will live at `<root>/<role>`.
+    try {
+      readFile(join(cwd, ".onlyne", "spec.toml"));
+      workspaceRoot = join(cwd, hintRole);
+    } catch {
+      /* cwd itself is the workspace root */
+    }
+  }
+
+  const role = envRole ?? config.role ?? toml.role;
+  if (!role) return null;
+
+  const optedIn = Boolean(
+    envRole ||
+      envResident ||
+      config.resident ||
+      config.role ||
+      config.sessionId ||
+      toml.placement === "external" ||
+      toml.scope === "role" ||
+      toml.sessionId,
+  );
+  if (!optedIn) return null;
+
+  return {
+    role,
+    sessionId: envSessionId ?? config.sessionId ?? toml.sessionId ?? null,
+    taskId: envTaskId,
+    resident: true,
+    workspaceRoot,
+  };
+}

package/src/config.test.mjs

@@ -10,7 +10,14 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, test } from "node:test";
 
-import { CONFIG_RELATIVE_PATH, DEFAULT_CONFIG, loadConfig, sessionIdentity } from "./config.mjs";
+import {
+  CONFIG_RELATIVE_PATH,
+  DEFAULT_CONFIG,
+  WORKSPACE_CONFIG_RELATIVE_PATH,
+  loadConfig,
+  residentIdentity,
+  sessionIdentity,
+} from "./config.mjs";
 
 const cleanups = [];
 afterEach(() => {
@@ -78,3 +85,32 @@ 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("residentIdentity resolves pre-started sessions from env, .pi/onlyne.json, or .onlyne/config.toml", () => {
+  const dir = workspace();
+  // Plain workspace with no role or resident opt-in stays inert.
+  assert.equal(residentIdentity({}, dir), null);
+
+  // ONLYNE_ROLE alone activates resident mode for pre-started supervisor/agent.
+  assert.deepEqual(residentIdentity({ ONLYNE_ROLE: "supervisor" }, dir), {
+    role: "supervisor",
+    sessionId: null,
+    taskId: null,
+    resident: true,
+    workspaceRoot: dir,
+  });
+
+  // .onlyne/config.toml with placement = "external" and session_id activates resident mode.
+  mkdirSync(join(dir, ".onlyne"), { recursive: true });
+  writeFileSync(
+    join(dir, WORKSPACE_CONFIG_RELATIVE_PATH),
+    'role = "planner"\nplacement = "external"\n\n[client.session]\nscope = "role"\nsession_id = "planner-main"\n',
+  );
+  assert.deepEqual(residentIdentity({}, dir), {
+    role: "planner",
+    sessionId: "planner-main",
+    taskId: null,
+    resident: true,
+    workspaceRoot: dir,
+  });
+});