pi-onlyne 1.2.2 → 2.0.0

package/src/pi-surface.mjs

@@ -4,7 +4,9 @@
 //
 // Probed members (measured against pi 0.87.1):
 //   wakeUser      pi.sendUserMessage(content, { deliverAs: "followUp" })
-//   proseContext  pi.sendMessage({customType,...}, { deliverAs:"followUp", triggerTurn:false })
+//   roleProse     pi.on("before_agent_start") -> event.systemPromptOptions.sections
+//                 (index.ts owns the subscription; this module holds the prose and
+//                  writes the section it becomes)
 //   customEntry   pi.appendEntry(customType, data)
 //   widget        ctx.ui.setWidget("onlyne", lines) / ctx.ui.setWidget("onlyne", undefined)
 //   status        ctx.ui.setStatus("onlyne", text)
@@ -13,15 +15,25 @@
 //   pending       ctx.hasPendingMessages()
 //   toolNames     pi.getAllTools()          (background-work.mjs)
 //   eventBus      pi.events                 (background-work.mjs)
+//   subagentRegistry  ~/.pi/subagents/missions  (background-subagents.mjs)
 //   registerTool / registerCommand are probed by index.ts itself.
 
 import { WIDGET_KEY } from "./activity.mjs";
+import { createSubagentProbe } from "./background-subagents.mjs";
 import { createBackgroundProbe } from "./background-work.mjs";
 
 /**
- * @param {{ pi: any, log: (line: string) => void, context: () => any }} options
+ * The system-prompt section the role prose occupies. pi wraps a section in a tag
+ * of the same name and records it under that name in the transcript, which is
+ * also where the live case reads the prose back from
+ * (`crates/onlyne-testkit/e2e/pi-live.sh`), so the name is stable.
  */
-export function createSurface({ pi, log, context }) {
+export const PROSE_SECTION = "onlyne-role-prose";
+
+/**
+ * @param {{ pi: any, log: (line: string) => void, context: () => any, sessionId?: string | null }} options
+ */
+export function createSurface({ pi, log, context, sessionId = null }) {
   const has = (value) => typeof value === "function";
   const ctx = () => {
     try {
@@ -55,9 +67,33 @@ export function createSurface({ pi, log, context }) {
     log,
   });
 
+  // The second family of off-loop work: `Agent` calls, which return a handle and
+  // leave a subagent running with no tool event to bracket it. Scoped to this
+  // session's own missions when the plugin knows its id.
+  const subagents = createSubagentProbe({
+    getSessionId: () => sessionId,
+    log,
+  });
+
+  /**
+   * Live work in either extension holds the turn open. Both probes fail safe on
+   * their own, and a throw from either is caught here, so a broken probe still
+   * resolves to "not running" and the session proceeds.
+   * @returns {Promise<boolean>}
+   */
+  const backgroundRunning = async () => {
+    try {
+      const answers = await Promise.all([background.running(), subagents.running()]);
+      return answers.some(Boolean);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      log(`background work probe failed: ${message}`);
+      return false;
+    }
+  };
+
   const available = {
     wakeUser: has(pi.sendUserMessage),
-    proseContext: has(pi.sendMessage),
     customEntry: has(pi.appendEntry),
     widget: has(ctx()?.ui?.setWidget),
     status: true,
@@ -91,7 +127,7 @@ export function createSurface({ pi, log, context }) {
    * built, so a part missing either string stops the whole delivery inside pi.
    * pi reports that failure in its own pane and hands nothing back to this
    * plugin, so an unusable part is dropped here and the assignment still
-   * travels: the injection text already names the file that was written.
+   * travels: the delivery text already names the path the client wrote.
    */
   const wakeUser = (text, parts = []) => {
     if (!available.wakeUser) {
@@ -130,26 +166,53 @@ export function createSurface({ pi, log, context }) {
   };
 
   /**
-   * The role prose, once, as a custom message that joins the LLM context
-   * without starting a turn of its own.
+   * The role prose this session was handed, held for the instruction layer.
+   *
+   * The client rendered it and this module adds nothing to it: no prefix, no
+   * label, no formatting. It reaches the model as a system-prompt section and
+   * never as a conversation message: a message would file the spec's prose in
+   * the transcript's message stream beside the delivery the model was asked to
+   * act on, and the model would read both as the same kind of thing.
    */
-  const proseContext = (text, welcome) => {
-    if (!available.proseContext) return false;
-    try {
-      pi.sendMessage(
-        {
-          customType: "onlyne-role-prose",
-          content: `[onlyne] role prose for ${welcome.role} (from the cluster spec, delivered with welcome):\n\n${text}`,
-          display: true,
-        },
-        { deliverAs: "followUp", triggerTurn: false },
-      );
-      return true;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      log(`role prose injection refused: ${message}`);
+  let roleProseText = "";
+
+  /** One line for a pi without sectioned prompts, not one per run. */
+  let warnedNoSections = false;
+
+  /**
+   * Hand the role prose over once.
+   * @param {string} text
+   * @returns {boolean} whether there is prose to carry
+   */
+  const roleProse = (text) => {
+    roleProseText = typeof text === "string" ? text : "";
+    return roleProseText.length > 0;
+  };
+
+  /**
+   * Put that prose into the run that is starting: one section of pi's system
+   * prompt, whose value is the client's bytes exactly.
+   *
+   * `before_agent_start` is pi's only instruction-layer point, and it hands the
+   * handler the prompt options it is about to render (`prompt-customizer.ts` in
+   * pi's own examples does this). pi rebuilds those options for every run, so the
+   * section is written again rather than once — the write is idempotent, and the
+   * first run records it in the transcript's system message.
+   * @param {{ systemPromptOptions?: { sections?: Record<string, string> } } | null} event
+   * @returns {boolean} whether a section was written
+   */
+  const applyRoleProse = (event) => {
+    if (roleProseText.length === 0) return false;
+    const sections = event?.systemPromptOptions?.sections;
+    if (!sections) {
+      if (!warnedNoSections) {
+        warnedNoSections = true;
+        log("before_agent_start carries no prompt sections; the role prose reached no instruction layer");
+      }
       return false;
     }
+    sections[PROSE_SECTION] = roleProseText;
+    return true;
   };
 
   const customEntry = (customType, data) => {
@@ -167,7 +230,8 @@ export function createSurface({ pi, log, context }) {
   return {
     available,
     wakeUser,
-    proseContext,
+    roleProse,
+    applyRoleProse,
     customEntry,
     widget,
     status,
@@ -185,12 +249,12 @@ export function createSurface({ pi, log, context }) {
     },
     /**
      * The phase rule in one place: idle means waiting for user input, and a
-     * background-task extension holding live work keeps the session running
-     * even while pi itself waits.
+     * background extension holding live work — a `bg_*` task or a subagent
+     * mission — keeps the session running even while pi itself waits.
      */
     async waitingForInput() {
       if (!piWaitsForInput()) return false;
-      return !(await background.running());
+      return !(await backgroundRunning());
     },
     closeBackground() {
       background.close();

package/src/pi-surface.test.mjs

@@ -7,14 +7,22 @@
 // Anthropic `source: { type, media_type, data }` this plugin once sent — stops
 // the whole delivery inside pi, and pi reports that in its own pane without
 // handing anything back to the plugin.
+//
+// The role prose is the other half: it becomes one section of pi's system prompt
+// at `before_agent_start` (`event.systemPromptOptions.sections`, the mutable
+// prompt options pi hands the handler) and never a message. The section's value
+// is the client's own text, byte for byte.
 
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
-import { createSurface } from "./pi-surface.mjs";
+import { PROSE_SECTION, createSurface } from "./pi-surface.mjs";
 
-/** The injection text `agent.mjs` builds for one assignment. */
-const TASK_TEXT = "[onlyne] task 11111111-1111-4111-8111-111111111111 from role:planner";
+/**
+ * One delivery text in the shape the client renders and `agent.mjs` injects.
+ * The surface carries it verbatim; it composes no part of it.
+ */
+const TASK_TEXT = "From planner:\n\nbuild it";
 
 /** One inline image part in the shape the agent hands the surface. */
 const PNG_PART = { type: "image", mime: "image/png", data: "iVBORw0KGgoAAAANSUhEUg==", name: "shot.png" };
@@ -34,6 +42,7 @@ const PNG_CONTENT = [
  */
 function fakeSurface({ refuse = null } = {}) {
   const calls = [];
+  const messages = [];
   const lines = [];
   const surface = createSurface({
     pi: {
@@ -41,11 +50,16 @@ function fakeSurface({ refuse = null } = {}) {
         calls.push({ content, options });
         if (refuse?.(content, options)) throw new Error("this pi does not take that option");
       },
+      // Recorded, never expected: no part of this plugin is a conversation
+      // message any more, and the prose is the one that could creep back.
+      sendMessage(message, options) {
+        messages.push({ message, options });
+      },
     },
     log: (line) => lines.push(line),
     context: () => null,
   });
-  return { calls, lines, surface };
+  return { calls, messages, lines, surface };
 }
 
 test("an image attachment reaches pi as one flat image content part beside the task text", () => {
@@ -114,6 +128,64 @@ test("delivery asks for followUp and a refusal of that option retries with the s
   assert.deepEqual(refusing.lines, [], "a delivery that landed on the retry is not a failure");
 });
 
+/** One role prose, in the shape the client renders and `agent.mjs` hands over. */
+const PROSE_TEXT = "Read the incoming task.\n\nAnswer in the house style.\n";
+
+/** The shift `before_agent_start` hands a handler: the prompt options it is about to render. */
+const promptEvent = () => ({ systemPromptOptions: { sections: {} } });
+
+test("the role prose becomes one system-prompt section, byte for byte", () => {
+  const { surface, calls, messages } = fakeSurface();
+  assert.equal(surface.roleProse(PROSE_TEXT), true);
+
+  const event = promptEvent();
+  assert.equal(surface.applyRoleProse(event), true);
+  assert.deepEqual(event.systemPromptOptions.sections, { [PROSE_SECTION]: PROSE_TEXT });
+  // The client's bytes exactly: no prefix naming the role, no label, no newline
+  // of this plugin's own.
+  assert.equal(event.systemPromptOptions.sections[PROSE_SECTION], PROSE_TEXT);
+  // And it travelled as no message at all: the injection that used to put the
+  // prose in the transcript's message stream is gone.
+  assert.deepEqual(messages, [], "the role prose is not a conversation message");
+  assert.deepEqual(calls, [], "and not a user message either");
+});
+
+test("no prose arrived is no section written", () => {
+  const { surface } = fakeSurface();
+  const event = promptEvent();
+
+  assert.equal(surface.applyRoleProse(event), false);
+  assert.deepEqual(event.systemPromptOptions.sections, {});
+});
+
+test("every run writes the section again, because pi rebuilds the prompt options per run", () => {
+  const { surface } = fakeSurface();
+  surface.roleProse(PROSE_TEXT);
+
+  const first = promptEvent();
+  const second = promptEvent();
+  assert.equal(surface.applyRoleProse(first), true);
+  assert.equal(surface.applyRoleProse(second), true);
+  assert.deepEqual(second.systemPromptOptions.sections, first.systemPromptOptions.sections);
+
+  // A later prose — the spec edited between two runs of one session — takes the
+  // section over rather than being masked by the text that was written first.
+  surface.roleProse("Answer in the log style.");
+  const third = promptEvent();
+  surface.applyRoleProse(third);
+  assert.deepEqual(third.systemPromptOptions.sections, { [PROSE_SECTION]: "Answer in the log style." });
+});
+
+test("a pi whose prompt options carry no sections reports it once and carries no prose", () => {
+  const { surface, lines } = fakeSurface();
+  surface.roleProse(PROSE_TEXT);
+
+  assert.equal(surface.applyRoleProse({ systemPromptOptions: {} }), false);
+  assert.equal(surface.applyRoleProse({}), false);
+  assert.equal(lines.length, 1, "one line, not one per run");
+  assert.match(lines[0], /no instruction layer/);
+});
+
 /**
  * A surface over a fake pi that answers the two questions the phase is read
  * from, plus the cases where pi answers neither.

package/src/protocol.mjs

@@ -36,8 +36,12 @@ export const SEQ_BASE = 1000;
 /** Heartbeat cadence while a task is active (`heartbeat_timeout_ms` is 30s). */
 export const DEFAULT_HEARTBEAT_MS = 10_000;
 
-/** Outcomes the wire accepts for one completion. */
-export const OUTCOMES = ["done", "failed", "cancelled"];
+/**
+ * Outcomes the wire accepts for one completion. The proto's own `Outcome`
+ * (`crates/onlyne-proto/src/envelope.rs`), so the two drives that mount these
+ * tools refuse the same spellings rather than each keeping a list.
+ */
+export const OUTCOMES = ["done", "failed", "cancelled", "blocked"];
 
 /** Mime types `ImagePart` accepts, in the core's stable order. */
 export const IMAGE_MIMES = ["image/png", "image/jpeg", "image/gif", "image/webp"];
@@ -102,6 +106,11 @@ export function welcomeFrom(data) {
     prose: typeof args.prose === "string" ? args.prose : "",
     server: args.server ?? null,
     hostCapabilities: Array.isArray(args.host_capabilities) ? args.host_capabilities : [],
+    // The tasks whose delivery the host already handed this session: a plugin
+    // that restarts under a live client seeds its injection guard from it, so
+    // the work its predecessor read is not injected a second time. Null when the
+    // host says nothing.
+    deliveredTasks: Array.isArray(args.delivered_tasks) ? args.delivered_tasks : null,
   };
 }
 
@@ -131,11 +140,21 @@ export function heartbeatReport({ taskId, generation, seq, agent, host = null })
   };
 }
 
-/** `report.complete` — the terminal fact the ledger keeps. */
-export function completeReport({ taskId, outcome, head }) {
+/**
+ * `report.complete` — the terminal fact the ledger keeps.
+ *
+ * `head` is the display line the ledger holds; `details` is the full result,
+ * carried verbatim for the next hop and the originator, and `files` are the
+ * absolute paths that result names. The client owns the `details` ceiling and
+ * refuses an oversize body, so this builds the frame and adds no rule of its
+ * own (`docs/v2-CONTRACT.md` §3c).
+ */
+export function completeReport({ taskId, outcome, head, details = null, files = [] }) {
   const report = { kind: "complete", data: { task_id: taskId, outcome: normalizeOutcome(outcome) } };
   const text = headOf(head);
   if (text) report.data.head = text;
+  if (typeof details === "string" && details.length > 0) report.data.details = details;
+  if (Array.isArray(files) && files.length > 0) report.data.files = files;
   return report;
 }
 
@@ -277,7 +296,7 @@ export function sendEnvelope({ from, to, kind = "note", text = "", image = null,
   return envelope;
 }
 
-/** A human-readable principal, for injection headers. */
+/** A human-readable principal, for the plugin's own operator log line. */
 export function describePrincipal(principal) {
   if (!principal || typeof principal !== "object") return "unknown";
   if (principal.role) {
@@ -305,48 +324,10 @@ export function normalizeOutcome(value) {
 }
 
 /**
- * The user message one `assign` becomes.
- *
- * The task text is quoted verbatim under a header naming its origin, so a
- * session transcript shows where the instruction came from; the role prose
- * (identical in `welcome` and `assign`) is folded in only when it has not
- * already been delivered.
- *
- * The header also carries the family's own figures — the hop this assignment
- * sits at and the hops the family may spend — so a role reads its position off
- * the instruction. Both appear only when the causality names a hop budget: the
- * budget is what marks a payload as a member of a bounded family, and a payload
- * that names none injects exactly the bytes it produced before this header
- * carried them.
- * @param {{ assign: any, proseIsNew: boolean, attachmentPaths?: string[] }} options
- */
-export function injectionText({ assign, proseIsNew, attachmentPaths = [] }) {
-  const envelope = assign.envelope ?? {};
-  const causality = envelope.causality ?? {};
-  const taskId = assign.task_id ?? envelope.causality?.task ?? "unknown";
-  const position =
-    typeof causality.hop_budget === "number"
-      ? `, hop ${causality.hop ?? 0}, hop budget ${causality.hop_budget}`
-      : "";
-  const lines = [
-    `[onlyne] task ${taskId} from ${describePrincipal(envelope.from)} (kind ${envelope.kind ?? "task"}${position})`,
-  ];
-  const prose = typeof assign.prose === "string" ? assign.prose.trim() : "";
-  if (prose && proseIsNew) {
-    lines.push("", "[onlyne] role prose from the spec:", prose);
-  }
-  const text = typeof envelope.body?.text === "string" ? envelope.body.text.trim() : "";
-  lines.push("", text || "(the task carried no text; the image attachment is the payload)");
-  if (attachmentPaths.length > 0) {
-    lines.push("", `[onlyne] attachment saved to: ${attachmentPaths.join(", ")}`);
-  }
-  return lines.join("\n");
-}
-
-/**
- * Task body for the `config_get` route: when a plugin does not declare `inject`
- * the host hands the payload over as `config_get{key:"stdin:<task text>"}`
- * (PROTOCOL.md, "Mounts and capabilities").
+ * Delivery text for the `config_get` route: when a plugin does not declare
+ * `inject` the host hands the payload over as
+ * `config_get{key:"stdin:<delivery text>"}`, the same bytes an `assign` carries
+ * in its `text` (PROTOCOL.md, "Mounts and capabilities").
  * @returns {{ text: string } | null}
  */
 export function stdinTaskText(args) {

package/src/protocol.test.mjs

@@ -18,7 +18,6 @@ import {
   helloArgs,
   hostBinding,
   imagePart,
-  injectionText,
   normalizeOutcome,
   observationFor,
   readPluginVersion,
@@ -31,7 +30,6 @@ import {
 const VECTOR_DIR = fileURLToPath(new URL("../../../crates/onlyne-proto/tests/wire_vectors/", import.meta.url));
 const hasVectors = existsSync(VECTOR_DIR);
 const vectorFrame = (name) => JSON.parse(JSON.parse(readFileSync(`${VECTOR_DIR}${name}`, "utf8")).frame);
-const ASSIGN = () => vectorFrame("adapter_host_assign.json");
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
@@ -89,6 +87,7 @@ test("welcome parses the host's response body and rejects junk", () => {
     prose: "Read the incoming task",
     server: { connected: true, cluster: "local", name: "server" },
     hostCapabilities: ["probe", "recycle"],
+    deliveredTasks: null,
   });
   assert.deepEqual(welcomeFrom(args)?.role, "planner");
   assert.equal(welcomeFrom(null), null);
@@ -101,7 +100,14 @@ test("welcome parses the host's response body and rejects junk", () => {
     prose: "",
     server: null,
     hostCapabilities: [],
+    deliveredTasks: null,
   });
+  // The host's restart-recovery list travels under its own wire name.
+  assert.deepEqual(
+    welcomeFrom({ op: "welcome", args: { ...args, delivered_tasks: ["task-1"] } }).deliveredTasks,
+    ["task-1"],
+  );
+  assert.equal(welcomeFrom({ op: "welcome", args: { ...args, delivered_tasks: "task-1" } }).deliveredTasks, null);
 });
 
 test("ready matches the host's ready vector, which relays a cluster this plugin never speaks for", { skip: !hasVectors }, () => {
@@ -229,9 +235,24 @@ test("a completion names an outcome and a single-line head", () => {
     kind: "complete",
     data: { task_id: "t1", outcome: "done" },
   });
+  // The full result and the paths it names ride the same report, and only when
+  // there is something to carry: an empty body adds no key at all.
+  assert.deepEqual(
+    completeReport({ taskId: "t1", outcome: "done", head: "done", details: "all of it", files: ["/ws/a.md"] }),
+    {
+      kind: "complete",
+      data: { task_id: "t1", outcome: "done", head: "done", details: "all of it", files: ["/ws/a.md"] },
+    },
+  );
+  assert.deepEqual(completeReport({ taskId: "t1", outcome: "done", details: "", files: [] }), {
+    kind: "complete",
+    data: { task_id: "t1", outcome: "done" },
+  });
   assert.equal(completeReport({ taskId: "t1", outcome: "weird" }).data.outcome, "done");
   assert.equal(normalizeOutcome(undefined), "done");
   assert.equal(normalizeOutcome("cancelled"), "cancelled");
+  // `blocked` is the proto's own outcome (slice 1), so it travels as itself.
+  assert.equal(normalizeOutcome("blocked"), "blocked");
 });
 
 test("the ledger head is capped at the plan's 200 characters", () => {
@@ -241,63 +262,6 @@ test("the ledger head is capped at the plan's 200 characters", () => {
   assert.equal(headOf(undefined), "");
 });
 
-test("an assignment becomes one message naming its origin and payload", { skip: !hasVectors }, () => {
-  const assign = ASSIGN().args;
-  const text = injectionText({ assign, proseIsNew: true });
-  // The vector's causality names no hop budget, and the header is byte for byte
-  // the line this plugin has always injected.
-  assert.equal(
-    text.split("\n")[0],
-    "[onlyne] task 11111111-1111-4111-8111-111111111111 from role:planner (kind task)",
-  );
-  assert.match(text, /\[onlyne\] role prose from the spec:\nRead the incoming task/);
-  assert.match(text, /\nbuild it\n?$/);
-
-  const repeat = injectionText({ assign, proseIsNew: false });
-  assert.doesNotMatch(repeat, /role prose from the spec/);
-  assert.match(repeat, /build it/);
-});
-
-test("the header names the hop and the budget once the family names a budget", () => {
-  const header = (causality) =>
-    injectionText({
-      assign: {
-        task_id: "t9",
-        envelope: {
-          id: "e9",
-          kind: "task",
-          from: { role: { role: "planner" } },
-          causality,
-          body: { text: "pass it on" },
-        },
-      },
-      proseIsNew: false,
-    }).split("\n")[0];
-
-  assert.equal(
-    header({ task: "t9", hop: 2, attempt: 0, family: "t1", hop_budget: 5 }),
-    "[onlyne] task t9 from role:planner (kind task, hop 2, hop budget 5)",
-  );
-  // A family may spend no further hop: zero is a figure the header carries.
-  assert.equal(
-    header({ task: "t9", hop: 0, attempt: 0, family: "t1", hop_budget: 0 }),
-    "[onlyne] task t9 from role:planner (kind task, hop 0, hop budget 0)",
-  );
-  // No budget named: the compat rule holds, hop or no hop.
-  assert.equal(header({ task: "t9", hop: 2, attempt: 0 }), "[onlyne] task t9 from role:planner (kind task)");
-});
-
-test("an empty-bodied assignment still produces an instruction", () => {
-  const text = injectionText({
-    assign: { task_id: "t9", envelope: { id: "e9", kind: "note", from: { gateway: { gateway: "fg1", channel: "fake", conversation: "c1" } }, body: {} } },
-    proseIsNew: false,
-    attachmentPaths: ["/ws/.onlyne/tmp/attachments/a.png"],
-  });
-  assert.match(text, /from gateway:fg1:fake:c1/);
-  assert.match(text, /the task carried no text/);
-  assert.match(text, /\/ws\/\.onlyne\/tmp\/attachments\/a\.png/);
-});
-
 test("a note carries no idempotency key and a task carries both", { skip: !hasVectors }, () => {
   const note = sendEnvelope({ from: "planner", to: "builder", kind: "note", text: "ping" });
   assert.deepEqual(Object.keys(note).sort(), ["admin", "body", "from", "id", "kind", "protocol", "to", "ts"].sort());