pi-onlyne 2.2.0 → 2.3.0

package/src/index.ts

@@ -8,7 +8,12 @@
 // a plain pi session and the extension stays silent rather than failing.
 //
 //   session_start      -> bind the env session id, read env + .pi/onlyne.json,
-//                         connect, register tools
+//                         connect, register tools; a resident plugin that is
+//                         already connected only follows the switch
+//   session_switch     -> /new, /resume and /fork on a host that names them;
+//   session_branch       the same re-point a resident plugin does when current
+//   session_tree         pi reports the switch through session_start, and
+//                        after tree navigation
 //   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}
@@ -40,8 +45,9 @@ import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-
 import { Type } from "typebox";
 
 import { OnlyneAgent } from "./agent.mjs";
-import { loadConfig, sessionIdentity } from "./config.mjs";
-import { resolveSocketPath } from "./socket.mjs";
+import { ASSIGN_MESSAGE_TYPE, createAssignMessageComponent } from "./activity.mjs";
+import { loadConfig, residentIdentity, sessionIdentity } from "./config.mjs";
+import { resolveResidentSocketPath, resolveSocketPath } from "./socket.mjs";
 import { createSurface } from "./pi-surface.mjs";
 import { foreignSessionRefusal, mountsSession, ownsSession, sessionIdOf } from "./session-scope.mjs";
 
@@ -82,11 +88,11 @@ interface PiSurface {
     registerTool: boolean;
     registerCommand: boolean;
   };
-  wakeUser(text: string, parts?: ImagePartInput[]): boolean;
+  wakeUser(text: string, parts?: ImagePartInput[], meta?: unknown): boolean;
   roleProse(text: string): boolean;
   applyRoleProse(event: { systemPromptOptions?: { sections?: Record<string, string> } }): boolean;
   customEntry(customType: string, data: unknown): boolean;
-  widget(lines: string[] | undefined): void;
+  widget(lines: string[] | undefined, activity?: unknown): void;
   status(text: string): void;
   welcome(welcome: WelcomeLike): void;
   isIdle(): boolean;
@@ -173,6 +179,16 @@ export default function onlyne(pi: ExtensionAPI) {
   const registerSurface = () => {
     if (registered || !surface) return;
     registered = true;
+    if ("registerMessageRenderer" in pi && typeof pi.registerMessageRenderer === "function") {
+      try {
+        pi.registerMessageRenderer(ASSIGN_MESSAGE_TYPE, (message, options, theme) => {
+          if (!message?.details || typeof message.details !== "object") return undefined;
+          return createAssignMessageComponent(message.details, message.content, theme, !options?.expanded);
+        });
+      } catch (error) {
+        log(`registerMessageRenderer(${ASSIGN_MESSAGE_TYPE}) refused: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
     try {
       pi.registerTool(defineTool({
         name: "onlyne_send",
@@ -329,8 +345,29 @@ export default function onlyne(pi: ExtensionAPI) {
     }
   };
 
-  pi.on("session_start", async (_event, ctx) => {
-    const identity = sessionIdentity(env);
+  /**
+   * Re-point the plugin at the session pi made current. The socket belongs to
+   * the role, not to the session file that mounted it: /new, /resume, /fork and
+   * a tree jump replace the live session in this process, and the tools must
+   * follow it instead of refusing every call as foreign.
+   */
+  const syncSessionContext = (_event: unknown, ctx: ExtensionContext) => {
+    if (!agent) return;
+    context = ctx;
+    const currentId = sessionIdOf(ctx?.sessionManager);
+    if (currentId) {
+      boundSessionId = currentId;
+    }
+    if (surface?.available.widget) {
+      surface.widget(agent.activity.lines(), agent.activity);
+    }
+    surface?.status(agent.activity.lines()[0]);
+  };
+
+  pi.on("session_start", async (event, ctx) => {
+    const spawned = sessionIdentity(env);
+    const resident = spawned ? null : residentIdentity(env, ctx.cwd);
+    const identity = spawned ?? resident;
     if (!identity) return; // not an onlyne session: stay out of the way
     // Only the session the client names may mount. A pi process runs more than
     // one session — a `task` subagent's sidechain, `/new` — and each of them
@@ -340,12 +377,27 @@ export default function onlyne(pi: ExtensionAPI) {
     // expose one; the env-bound mount is then the only candidate and stays the
     // behaviour, with no line to explain.
     const starting = sessionIdOf(ctx.sessionManager);
-    if (!mountsSession(identity.sessionId, starting)) {
-      log(`session ${starting} is not the onlyne session ${identity.sessionId}; staying inert`);
+    // A resident plugin already holds its connection, so another session_start
+    // in this process is a re-point, not a mount: /new, /resume and /fork
+    // replace the live session, and pi can re-bind this same session's
+    // extensions. The sidechain a `task` subagent runs re-binds every extension
+    // with reason "startup" and a different id, and stays inert.
+    if (!spawned && agent !== null && (event.reason !== "startup" || starting === boundSessionId)) {
+      syncSessionContext(event, ctx);
+      return;
+    }
+    if (spawned) {
+      if (!mountsSession(spawned.sessionId, starting)) {
+        log(`session ${starting} is not the onlyne session ${spawned.sessionId}; staying inert`);
+        return;
+      }
+    } else if (boundSessionId !== null && starting !== null && starting !== boundSessionId) {
+      log(`session ${starting} is not the resident onlyne session ${boundSessionId}; staying inert`);
       return;
     }
+    const wireSessionId = identity.sessionId ?? starting;
     context = ctx;
-    boundSessionId = identity.sessionId;
+    boundSessionId = spawned ? spawned.sessionId : (starting ?? wireSessionId);
     const config = loadConfig(ctx.cwd);
     if (config.warning) log(config.warning);
     if (!config.enabled) {
@@ -357,23 +409,30 @@ export default function onlyne(pi: ExtensionAPI) {
     // 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;
+    const targetWorkspace = resident ? resident.workspaceRoot : ctx.cwd;
     try {
-      socketPath = resolveSocketPath(env, ctx.cwd);
+      socketPath = resident
+        ? resolveResidentSocketPath(env, targetWorkspace, identity.role)
+        : resolveSocketPath(env, ctx.cwd);
     } catch (error) {
       log(`socket unresolved: ${error instanceof Error ? error.message : String(error)}`);
     }
     if (socketPath === null) return;
-    surface = createSurface({ pi, log, context: () => context, sessionId: identity.sessionId });
+    surface = createSurface({ pi, log, context: () => context, sessionId: () => boundSessionId });
     agent = new OnlyneAgent({
       socketPath,
+      resolveSocket: resident
+        ? () => resolveResidentSocketPath(env, targetWorkspace, identity.role)
+        : undefined,
       cwd: ctx.cwd,
       role: identity.role,
-      sessionId: identity.sessionId,
+      sessionId: wireSessionId,
       taskId: identity.taskId,
+      resident: Boolean(resident),
       surface,
       log,
     });
-    log(`session ${identity.sessionId} role=${identity.role} socket=${socketPath}`);
+    log(`session ${wireSessionId ?? "resident"} role=${identity.role} socket=${socketPath}`);
     registerSurface();
     if (!surface.available.wakeUser) {
       // Without an injection surface the payload travels through config_get,
@@ -384,6 +443,18 @@ export default function onlyne(pi: ExtensionAPI) {
     if (config.autoStart) agent.start();
   });
 
+  // `session_switch` and `session_branch` name the same transitions in the omp
+  // lineage of this API; current pi reports them as `session_start` with a
+  // reason and keeps `session_tree` for navigation, so one helper serves all.
+  // The installed typings no longer declare the first two, but the host stores
+  // handlers by name, which this narrow cast is the whole boundary of.
+  const legacySessionEvents = pi as unknown as {
+    on(event: "session_switch" | "session_branch", handler: (event: unknown, ctx: ExtensionContext) => void): void;
+  };
+  legacySessionEvents.on("session_switch", syncSessionContext);
+  legacySessionEvents.on("session_branch", syncSessionContext);
+  pi.on("session_tree", async (event, ctx) => syncSessionContext(event, ctx));
+
   // 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

package/src/pi-surface.mjs

@@ -18,7 +18,7 @@
 //   subagentRegistry  ~/.pi/subagents/missions  (background-subagents.mjs)
 //   registerTool / registerCommand are probed by index.ts itself.
 
-import { WIDGET_KEY } from "./activity.mjs";
+import { ASSIGN_MESSAGE_TYPE, WIDGET_KEY } from "./activity.mjs";
 import { createSubagentProbe } from "./background-subagents.mjs";
 import { createBackgroundProbe } from "./background-work.mjs";
 
@@ -34,6 +34,7 @@ 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 }) {
+  let currentSessionId = typeof sessionId === "function" ? sessionId : () => sessionId;
   const has = (value) => typeof value === "function";
   const ctx = () => {
     try {
@@ -71,7 +72,7 @@ export function createSurface({ pi, log, context, sessionId = null }) {
   // 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,
+    getSessionId: () => currentSessionId(),
     log,
   });
 
@@ -95,7 +96,9 @@ export function createSurface({ pi, log, context, sessionId = null }) {
   const available = {
     wakeUser: has(pi.sendUserMessage),
     customEntry: has(pi.appendEntry),
-    widget: has(ctx()?.ui?.setWidget),
+    get widget() {
+      return has(ctx()?.ui?.setWidget);
+    },
     status: true,
     exit: true,
     isIdle: true,
@@ -103,9 +106,19 @@ export function createSurface({ pi, log, context, sessionId = null }) {
     registerCommand: has(pi.registerCommand),
   };
 
-  const widget = (lines) => {
+  const widget = (lines, activity = null) => {
     try {
-      ctx()?.ui?.setWidget?.(WIDGET_KEY, lines);
+      const ui = ctx()?.ui;
+      if (!has(ui?.setWidget)) return;
+      if (lines === undefined) {
+        ui.setWidget(WIDGET_KEY, undefined);
+        return;
+      }
+      if (activity && typeof activity.component === "function") {
+        ui.setWidget(WIDGET_KEY, (tui, theme) => activity.component(theme, tui));
+        return;
+      }
+      ui.setWidget(WIDGET_KEY, lines);
     } catch {
       /* widget is decoration; never let it break the protocol */
     }
@@ -120,7 +133,7 @@ export function createSurface({ pi, log, context, sessionId = null }) {
   };
 
   /**
-   * One pi user message; images ride along as pi image content parts.
+   * One delivery, one 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
@@ -128,8 +141,21 @@ export function createSurface({ pi, log, context, sessionId = null }) {
    * 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.
+   *
+   * With `meta` and `pi.sendMessage`, the `onlyne_assign` card IS the delivery:
+   * a custom message reaches the model, and it is what the transcript draws, so
+   * a delivery does not also arrive as a second user message. `triggerTurn` is
+   * what an idle session owes it (a `display: true` custom message renders
+   * without starting a turn of its own); while a turn is running the card queues
+   * behind it as a follow-up instead of interrupting tool execution.
+   *
+   * A pi without `sendMessage` takes the plain `sendUserMessage` below — idle
+   * without `deliverAs` so the delivery starts the turn it owes, `followUp` when
+   * busy (`deliverAs: "followUp"` only enqueues and requires a prior
+   * assistant/toolResult tail to auto-continue). That path is the pre-card
+   * shape, kept so an older pi still receives a delivery.
    */
-  const wakeUser = (text, parts = []) => {
+  const wakeUser = (text, parts = [], meta = null) => {
     if (!available.wakeUser) {
       log("pi has no sendUserMessage; the assignment reached the session log only");
       return false;
@@ -150,8 +176,43 @@ export function createSurface({ pi, log, context, sessionId = null }) {
             mimeType: part.mime,
           })),
         ];
+    const current = ctx();
+    let idle = false;
     try {
-      pi.sendUserMessage(content, { deliverAs: "followUp" });
+      if (has(current?.isIdle)) idle = current.isIdle() === true;
+    } catch {
+      idle = false;
+    }
+    if (meta && typeof meta === "object" && has(pi.sendMessage)) {
+      try {
+        pi.sendMessage(
+          {
+            customType: ASSIGN_MESSAGE_TYPE,
+            content,
+            display: true,
+            details: {
+              role: meta.role ?? null,
+              taskId: meta.taskId ?? null,
+              kind: meta.kind ?? "task",
+              from: meta.from ?? null,
+              envelopeId: meta.envelopeId ?? null,
+              bodyText: meta.bodyText ?? text,
+            },
+          },
+          idle ? { triggerTurn: true } : { deliverAs: "followUp" },
+        );
+        return true;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        log(`sendMessage refused: ${message}; the delivery takes the user-message route`);
+      }
+    }
+    try {
+      if (idle) {
+        pi.sendUserMessage(content);
+      } else {
+        pi.sendUserMessage(content, { deliverAs: "followUp" });
+      }
       return true;
     } catch (error) {
       try {

package/src/pi-surface.test.mjs

@@ -16,6 +16,7 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
+import { ASSIGN_MESSAGE_TYPE } from "./activity.mjs";
 import { PROSE_SECTION, createSurface } from "./pi-surface.mjs";
 
 /**
@@ -40,7 +41,7 @@ const PNG_CONTENT = [
  * know an option does.
  * @param {{ refuse?: (content: unknown, options: unknown) => boolean }} [options]
  */
-function fakeSurface({ refuse = null } = {}) {
+function fakeSurface({ refuse = null, ctx = null } = {}) {
   const calls = [];
   const messages = [];
   const lines = [];
@@ -50,14 +51,12 @@ 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,
+    context: () => ctx,
   });
   return { calls, messages, lines, surface };
 }
@@ -128,6 +127,81 @@ 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");
 });
 
+test("a card delivery is one message: it starts the idle turn and queues while busy", () => {
+  // One delivery, one message. omp's rule for a custom message decides the
+  // option: with no `deliverAs` a `display: true` message renders without
+  // starting a turn, `triggerTurn` starts one when the session is idle, and
+  // `deliverAs: "followUp"` only queues behind a running turn.
+  const turns = [];
+  const queued = [];
+  const userMessages = [];
+  const cards = [];
+  let idle = true;
+  const surface = createSurface({
+    pi: {
+      sendMessage(message, options) {
+        cards.push({ message, options });
+        if (options?.triggerTurn === true && idle) {
+          turns.push(message.content);
+          return;
+        }
+        if (options?.deliverAs === "followUp") queued.push(message.content);
+      },
+      sendUserMessage(content, options) {
+        userMessages.push({ content, options });
+      },
+    },
+    log: () => {},
+    context: () => ({ isIdle: () => idle }),
+  });
+
+  const meta = {
+    role: "caerulea",
+    taskId: "97971b93-0000-4000-8000-000000000000",
+    kind: "note",
+    from: "role:_supervisor",
+    envelopeId: "env-1",
+    bodyText: "ping from supervisor",
+  };
+  const text = "From _supervisor:\n\nping from supervisor";
+  assert.equal(surface.wakeUser(text, [], meta), true);
+  assert.equal(cards.length, 1);
+  assert.equal(cards[0].message.customType, ASSIGN_MESSAGE_TYPE);
+  assert.equal(cards[0].message.display, true);
+  assert.equal(cards[0].message.details.kind, "note");
+  assert.equal(cards[0].message.details.from, "role:_supervisor");
+  assert.deepEqual(cards[0].options, { triggerTurn: true });
+  assert.deepEqual(turns, [text], "an idle session starts its turn from the card");
+  assert.deepEqual(userMessages, [], "the delivery is one message, never a card plus a prompt");
+
+  // While busy (`isIdle() === false`), the next card queues as followUp instead
+  // of interrupting the running turn.
+  idle = false;
+  const second = "From _supervisor:\n\nsecond note while busy";
+  assert.equal(surface.wakeUser(second, [], meta), true);
+  assert.equal(cards.length, 2);
+  assert.deepEqual(cards[1].options, { deliverAs: "followUp" });
+  assert.deepEqual(queued, [second]);
+  assert.deepEqual(turns, [text], "a busy session queues rather than starting a second turn");
+  assert.deepEqual(userMessages, []);
+});
+
+test("a pi without sendMessage takes the delivery as a plain user message", () => {
+  const calls = [];
+  const surface = createSurface({
+    pi: {
+      sendUserMessage(content, options) {
+        calls.push({ content, options });
+      },
+    },
+    log: () => {},
+    context: () => ({ isIdle: () => true }),
+  });
+
+  assert.equal(surface.wakeUser(TASK_TEXT, [], { kind: "note" }), true);
+  assert.deepEqual(calls, [{ content: TASK_TEXT, options: undefined }]);
+});
+
 /** 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";
 

package/src/socket.mjs

@@ -210,12 +210,57 @@ export function listClientRegistrations(env, options = {}) {
       path: join(dir, name),
       root: canonicalRoot(parsed.root, options),
       kind: parsed.kind,
+      role: typeof parsed.role === "string" && parsed.role !== "" ? parsed.role : null,
       runtime: typeof parsed.runtime === "string" && parsed.runtime !== "" ? parsed.runtime : null,
     });
   }
   return found;
 }
 
+/**
+ * Resolve the socket path for a resident or pre-started pi session.
+ *
+ * Unlike [`resolveSocketPath`], when `onlyne-client` has not been started yet
+ * (so `<runtime_dir>/<digest>.json` does not exist), this falls back to the
+ * deterministic `<runtime_dir>/<workspaceDigest(workspaceRoot)>.sock` path so
+ * the agent can enter its background reconnect loop and handshake automatically
+ * the moment `onlyne-client` binds the socket. When a client registration for
+ * `role` appears in `<runtime_dir>`, it prefers that registration's socket.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @param {string} workspaceRoot
+ * @param {string} role
+ * @param {{ readFile?: (path: string) => string, readDir?: (path: string) => string[], realpath?: (path: string) => string, uid?: number | null, runtime?: string }} [options]
+ * @returns {string}
+ */
+export function resolveResidentSocketPath(env, workspaceRoot, role, options = {}) {
+  const injected = typeof env[SOCKET_ENV] === "string" ? env[SOCKET_ENV].trim() : "";
+  if (injected) return injected;
+
+  const dir = runtimeDir(env, options);
+  const here = canonicalRoot(workspaceRoot, options);
+  const candidates = listClientRegistrations(env, options);
+
+  const coveringRole = candidates.filter((entry) => covers(entry.root, here) && (!role || !entry.role || entry.role === role));
+  if (coveringRole.length > 0) {
+    const nearest = coveringRole.reduce((best, entry) => (entry.root.length > best.root.length ? entry : best));
+    return join(dir, `${workspaceDigest(nearest.root, options)}${SOCKET_SUFFIX}`);
+  }
+
+  if (role) {
+    const byRole = candidates.filter((entry) => entry.role === role);
+    if (byRole.length === 1) {
+      return join(dir, `${workspaceDigest(byRole[0].root, options)}${SOCKET_SUFFIX}`);
+    }
+  }
+
+  try {
+    return resolveSocketPath(env, workspaceRoot, options);
+  } catch {
+    return socketPath(workspaceRoot, env, options);
+  }
+}
+
 /**
  * The socket path to dial for the pi working directory `cwd`.
  *

package/src/socket.test.mjs

@@ -17,6 +17,7 @@ import {
   canonicalRoot,
   listClientRegistrations,
   registrationPath,
+  resolveResidentSocketPath,
   resolveSocketPath,
   runtimeDir,
   socketPath,
@@ -235,3 +236,29 @@ test("a registration read through the injected filesystem names the same socket"
   // The env is what names the socket a client injected, and it is still first.
   assert.equal(resolveSocketPath({ ONLYNE_RUNTIME_DIR: dir, [SOCKET_ENV]: "/tmp/served" }, workspace, options), "/tmp/served");
 });
+
+test("resolveResidentSocketPath falls back to deterministic socket before client starts, then adopts registered role socket", () => {
+  const clusterRoot = scratch("pi-onlyne-cluster-");
+  const roleWs = join(clusterRoot, "supervisor");
+  mkdirSync(roleWs, { recursive: true });
+  const emptyDir = runtime([]);
+
+  // Before onlyne-client starts, no registration exists; returns deterministic socket path.
+  assert.equal(
+    resolveResidentSocketPath(envFor(emptyDir), roleWs, "supervisor"),
+    socketPath(roleWs, envFor(emptyDir)),
+  );
+
+  // Once onlyne-client starts and registers the role in the runtime directory, even if
+  // omp was started in the parent clusterRoot, it resolves the registered role's socket.
+  const liveDir = runtime([
+    {
+      name: registrationName(roleWs),
+      body: { kind: "client", role: "supervisor", root: canonicalRoot(roleWs), pid: 9001, version: "2.3.0", runtime: "pi" },
+    },
+  ]);
+  assert.equal(
+    resolveResidentSocketPath(envFor(liveDir), clusterRoot, "supervisor"),
+    socketPath(roleWs, envFor(liveDir)),
+  );
+});