pi-onlyne 1.2.1 → 2.0.0

package/src/index.ts

@@ -7,21 +7,26 @@
 // `crates/onlyne-client/src/dispatch.rs`); with any of the three missing this is
 // a plain pi session and the extension stays silent rather than failing.
 //
-//   session_start    -> read env + .pi/onlyne.json, connect, register tools
-//   turn_start       -> heartbeat{running}
-//   turn_end         -> one turn of a run ended; the phase is re-derived from pi
-//                       and the settle window opens
-//   message_end      -> keep the last assistant text; a failed turn is `failed`
-//   agent_settled    -> heartbeat{idle} when the session waits for input, then
-//                       the settle decision: the idle ladder, or `failed` at once
-//   session_shutdown -> detach{reason}
+//   session_start      -> read env + .pi/onlyne.json, connect, register tools
+//   before_agent_start -> the role prose becomes one section of the system
+//                         prompt the run is about to send (the instruction layer)
+//   turn_start         -> heartbeat{running}
+//   turn_end           -> one turn of a run ended; the phase is re-derived from pi
+//                         and the fallback window for a witnessed failure opens
+//   message_end        -> keep the last assistant text; a failed turn is `failed`
+//   agent_settled      -> heartbeat{idle} when the session waits for input, and the
+//                         report a failed turn owes is sent from here
+//   session_shutdown   -> detach{reason}
+//
+// Host frames are dispatched in `agent.mjs`, not here: `assign` and `nudge` are
+// injected as user messages, `probe` is answered with a heartbeat, and `recycle`
+// settles the task and stops the plugin.
 
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 
 import { OnlyneAgent } from "./agent.mjs";
 import { loadConfig, sessionIdentity } from "./config.mjs";
-import { loadRelay, relayEnabled } from "./relay.mjs";
 import { resolveSocketPath } from "./socket.mjs";
 import { createSurface } from "./pi-surface.mjs";
 
@@ -54,7 +59,6 @@ interface WelcomeLike {
 interface PiSurface {
   available: {
     wakeUser: boolean;
-    proseContext: boolean;
     customEntry: boolean;
     widget: boolean;
     status: boolean;
@@ -64,7 +68,8 @@ interface PiSurface {
     registerCommand: boolean;
   };
   wakeUser(text: string, parts?: ImagePartInput[]): boolean;
-  proseContext(text: string, welcome: WelcomeLike): boolean;
+  roleProse(text: string): boolean;
+  applyRoleProse(event: { systemPromptOptions?: { sections?: Record<string, string> } }): boolean;
   customEntry(customType: string, data: unknown): boolean;
   widget(lines: string[] | undefined): void;
   status(text: string): void;
@@ -141,10 +146,10 @@ export default function onlyne(pi: ExtensionAPI) {
         name: "onlyne_send",
         label: "Onlyne send",
         description:
-          "Send one message to another role in this onlyne cluster. kind=note (default) is free text; kind=task hands work to the role and creates a session for it.",
-        promptSnippet: "Send a note or a task to another onlyne role",
+          "Send one message to another role. kind=note (default) is free text; kind=task hands work to that role and opens a task for it.",
+        promptSnippet: "Send a note or a task to another role",
         promptGuidelines: [
-          "Use onlyne_send when a task needs another onlyne role's work; it submits the envelope to the cluster and returns once the router has queued it.",
+          "Use onlyne_send when something has to reach another role; the call returns once the message is queued.",
         ],
         parameters: Type.Object({
           to: Type.String({ description: "target role name, e.g. builder" }),
@@ -160,7 +165,9 @@ export default function onlyne(pi: ExtensionAPI) {
             kind: params.kind,
             imagePath: params.image ?? null,
           });
-          return textResult(`queued ${result.kind} to ${result.to}`, result);
+          // The recipient and nothing else: a tool result is model-visible, and
+          // there is no fact about this send the model needs beyond where it went.
+          return textResult(`sent to ${result.to}`, { to: result.to });
         },
       }));
     } catch (error) {
@@ -171,33 +178,34 @@ export default function onlyne(pi: ExtensionAPI) {
         name: "onlyne_complete",
         label: "Onlyne complete",
         description:
-          "End this onlyne task with an explicit outcome. Call it once, when the assigned work is finished (outcome=done), provably impossible (outcome=failed), or withdrawn (outcome=cancelled). This call is the only way the task reaches done: a turn that ends without it leaves the task open, the session re-sends you the assignment up to the workspace's idle-reminder bound, and the idle that finds the bound spent fails the task and ends the session. In a workspace whose relay policy (relay.toml) names the handoffs this session owes, the call is refused until each one has gone out.",
-        promptSnippet: "Finish the current onlyne task with an outcome and a one-line summary",
+          "End the current task with an explicit outcome: done (the work is finished), failed (it is provably impossible), cancelled (it was withdrawn), or blocked (something outside this session stops it). summary is the one-line result and details is the full one; files names the paths the result rests on. If the workspace requires a handoff before the task may end, the call is refused until that handoff has gone out.",
+        promptSnippet: "Finish the current task with an outcome and a one-line summary",
         promptGuidelines: [
-          "Use onlyne_complete at the end of an onlyne task, naming the outcome and the result in one line; the summary becomes the ledger head.",
-          "If the assignment is sent to you again while it is still open, the previous turn ended without a completion: finish the work and call onlyne_complete.",
-          "If onlyne_complete answers 'relay guard', the session still owes a downstream handoff: make it with onlyne_send and call onlyne_complete again. Close the session anyway only when the handoff is genuinely impossible, with force: true and a reason.",
+          "Use onlyne_complete at the end of the current task, naming the outcome and the result in one line.",
         ],
         parameters: Type.Object({
-          outcome: Type.Optional(Type.String({ description: '"done" (default), "failed", or "cancelled"' })),
-          text: Type.Optional(Type.String({ description: "one-line result summary" })),
-          force: Type.Optional(Type.Boolean({ description: "waive the relay guard; requires a non-empty reason" })),
-          reason: Type.Optional(Type.String({ description: "why the relay guard is waived; stamped into the ledger head after `relay-guard-forced: `" })),
+          outcome: Type.String({ description: '"done", "failed", "cancelled", or "blocked"' }),
+          summary: Type.String({ description: "one-line result summary" }),
+          details: Type.Optional(Type.String({ description: "the full result, delivered as it stands" })),
+          files: Type.Optional(Type.Array(Type.String(), { description: "absolute paths of the files the result names" })),
         }),
         async execute(_toolCallId, params) {
           if (!agent) throw new Error("onlyne: session is not connected");
           // The exit is not a tool-result flag: pi 0.85.1 has no tool-result
           // `terminate` handling. `agent.complete` asks the surface to shut the
-          // process down once the client has acknowledged the report. A relay
-          // refusal throws out of here as a tool error, which leaves the session
-          // mounted for the handoff that clears it.
+          // process down once the client has acknowledged the report. A refusal
+          // from the client throws out of here as a tool error, so the model
+          // reads the host's own sentence.
           const result = await agent.completeFromTool({
             outcome: params.outcome,
-            text: params.text,
-            force: params.force,
-            reason: params.reason,
+            summary: params.summary,
+            details: params.details,
+            files: params.files,
           });
-          return textResult(`onlyne task ${result.taskId} -> ${result.outcome}`, result);
+          // The outcome and nothing else: the ledger's head stays a display
+          // field (docs/v2-CONTRACT.md §3c), and the task's identity is not a
+          // fact the model is meant to hold.
+          return textResult(`reported ${result.outcome}`, { outcome: result.outcome });
         },
       }));
     } catch (error) {
@@ -208,16 +216,14 @@ export default function onlyne(pi: ExtensionAPI) {
         name: "onlyne_handoff",
         label: "Onlyne handoff",
         description:
-          "Hand this session's task on to the next hop of its family. The host mints one child task for the named role, names this task as the child's parent_task, raises the hop by one, and lets the family's budget, labels, origin and deadline ride along, so the child continues the run this session serves. Use it for the next slot of a ring or a chain; onlyne_send{kind:\"task\"} starts a new family at hop 0, and onlyne_send{kind:\"note\"} is free text.",
-        promptSnippet: "Hand this task on to the next role of its family",
+          "Hand the current task on to another role, which continues it. Call it when this task's work goes on to another role.",
+        promptSnippet: "Hand the current task on to another role",
         promptGuidelines: [
-          "Use onlyne_handoff when the work goes on to the next role of the run this session serves: the child the host mints carries the same family id, hop budget, labels, origin and deadline, and this task becomes its parent_task.",
-          "Use onlyne_send with kind=\"task\" when a role should get work of its own: that child is hop 0 of a family this session starts.",
-          "Use onlyne_send with kind=\"note\" for free text to a role, which carries no task and no hop.",
+          "Use onlyne_handoff when this task's work goes on to another role; the receiving role continues it.",
         ],
         parameters: Type.Object({
           to: Type.String({ description: "target role name, e.g. builder" }),
-          text: Type.String({ description: "handoff text for the next role of the run" }),
+          text: Type.String({ description: "handoff text for the receiving role" }),
           image: Type.Optional(Type.String({ description: "absolute path to a png/jpeg/gif/webp image to attach" })),
         }),
         async execute(_toolCallId, params) {
@@ -227,7 +233,10 @@ export default function onlyne(pi: ExtensionAPI) {
             text: params.text,
             imagePath: params.image ?? null,
           });
-          return textResult(`handed on to ${result.to} as ${result.taskId} at hop ${result.hop}`, result);
+          // The recipient and nothing else: the child's id and the hop are the
+          // host's bookkeeping, and a result naming them would teach the model
+          // to read itself as one node of a numbered chain.
+          return textResult(`handed on to ${result.to}`, { to: result.to });
         },
       }));
     } catch (error) {
@@ -270,21 +279,18 @@ export default function onlyne(pi: ExtensionAPI) {
       log(`disabled by ${config.path}`);
       return;
     }
-    // Environment first (the client injects the path it serves), then the
-    // marker the daemon publishes, then the canonical `run/s` (socket.mjs).
-    const socketPath = resolveSocketPath(env, ctx.cwd);
-    // The guard's policy comes from the spec through the client's environment;
-    // a hand-written `relay.toml` beside the package is the fallback a manual
-    // installation still has (relay.mjs).
-    const relay = loadRelay();
-    if (relay.warning) log(relay.warning);
-    if (relayEnabled(relay)) {
-      const origin = relay.source === "env" ? "the client's environment" : relay.path;
-      log(
-        `relay guard from ${origin}: required=${JSON.stringify(relay.required)} count=${relay.count ?? "-"}`,
-      );
+    // The path the client injected, or the client the runtime directory's
+    // registration files name for this workspace (socket.mjs). A session with
+    // neither has no socket to dial, and saying so is the whole answer: this
+    // stays a plain pi session instead of retrying a path nothing serves.
+    let socketPath: string | null = null;
+    try {
+      socketPath = resolveSocketPath(env, ctx.cwd);
+    } catch (error) {
+      log(`socket unresolved: ${error instanceof Error ? error.message : String(error)}`);
     }
-    surface = createSurface({ pi, log, context: () => context });
+    if (socketPath === null) return;
+    surface = createSurface({ pi, log, context: () => context, sessionId: identity.sessionId });
     agent = new OnlyneAgent({
       socketPath,
       cwd: ctx.cwd,
@@ -292,8 +298,6 @@ export default function onlyne(pi: ExtensionAPI) {
       sessionId: identity.sessionId,
       taskId: identity.taskId,
       surface,
-      relay,
-      idleReminders: config.idleReminders,
       log,
     });
     log(`session ${identity.sessionId} role=${identity.role} socket=${socketPath}`);
@@ -307,6 +311,15 @@ export default function onlyne(pi: ExtensionAPI) {
     if (config.autoStart) agent.start();
   });
 
+  // The role prose is instruction-layer text: `before_agent_start` hands the
+  // handler the prompt options the run is about to render, and a section written
+  // there is part of the system prompt rather than one more message the model has
+  // to read as an utterance. Outside an onlyne session there is no surface and
+  // nothing to add.
+  pi.on("before_agent_start", async (event) => {
+    surface?.applyRoleProse(event);
+  });
+
   pi.on("turn_start", async () => {
     agent?.onTurnStart();
   });

package/src/pi-surface.mjs

@@ -2,9 +2,11 @@
 // through the pi extension API, with a probe for each optional member so an
 // older pi degrades instead of throwing.
 //
-// Probed members (measured against pi 0.85.1):
+// 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,
@@ -83,19 +119,35 @@ export function createSurface({ pi, log, context }) {
     }
   };
 
-  /** One pi user message; images ride along as pi image content parts. */
+  /**
+   * One pi user message; images ride along as pi image content parts.
+   *
+   * pi reads an image part as the flat `ImageContent` of its message types —
+   * `data` plus `mimeType` — and normalizes every part before the message is
+   * 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 delivery text already names the path the client wrote.
+   */
   const wakeUser = (text, parts = []) => {
     if (!available.wakeUser) {
       log("pi has no sendUserMessage; the assignment reached the session log only");
       return false;
     }
-    const content = parts.length === 0
+    const images = parts.filter(
+      (part) => typeof part?.data === "string" && typeof part?.mime === "string" && part.mime,
+    );
+    if (images.length !== parts.length) {
+      log(`attachment carried no base64 data or no media type; ${parts.length - images.length} dropped, the task text still went`);
+    }
+    const content = images.length === 0
       ? text
       : [
           { type: "text", text },
-          ...parts.map((part) => ({
+          ...images.map((part) => ({
             type: "image",
-            source: { type: "base64", mediaType: part.mime, data: part.data },
+            data: part.data,
+            mimeType: part.mime,
           })),
         ];
     try {
@@ -114,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) => {
@@ -151,7 +230,8 @@ export function createSurface({ pi, log, context }) {
   return {
     available,
     wakeUser,
-    proseContext,
+    roleProse,
+    applyRoleProse,
     customEntry,
     widget,
     status,
@@ -169,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();