pi-onlyne 0.9.1 → 1.0.0

package/src/config.mjs

@@ -0,0 +1,74 @@
+// `.pi/onlyne.json`, the plugin's own switch file.
+//
+// The workspace layout keeps the old key shape (`watch.autoStart`) because that
+// is what the generated role templates and operator habits carry; the client
+// does not read this file at all (§11 line 399 downgraded the readiness gates to
+// generate-time template advice), so the only consumer is this extension. A
+// malformed or missing file falls back to the defaults and reports a warning
+// instead of disabling the session: the extension's own `enabled` key is the one
+// deliberate off switch.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Where the switch file lives, relative to the pi working directory. */
+export const CONFIG_RELATIVE_PATH = join(".pi", "onlyne.json");
+
+/** Defaults: on, and connecting as soon as a session starts. */
+export const DEFAULT_CONFIG = Object.freeze({ enabled: true, autoStart: true });
+
+/**
+ * Read `.pi/onlyne.json`.
+ *
+ * @param {string} cwd
+ * @param {{ readFile?: (path: string) => string }} [options]
+ * @returns {{ enabled: boolean, autoStart: boolean, path: string, warning: string | null, present: boolean }}
+ */
+export function loadConfig(cwd, options = {}) {
+  const readFile = options.readFile ?? ((path) => readFileSync(path, "utf8"));
+  const path = join(cwd, CONFIG_RELATIVE_PATH);
+  let raw;
+  try {
+    raw = readFile(path);
+  } catch {
+    return { ...DEFAULT_CONFIG, path, warning: null, present: false };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return {
+      ...DEFAULT_CONFIG,
+      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 };
+  }
+  const watch = parsed.watch && typeof parsed.watch === "object" ? parsed.watch : {};
+  return {
+    enabled: typeof parsed.enabled === "boolean" ? parsed.enabled : DEFAULT_CONFIG.enabled,
+    autoStart: typeof watch.autoStart === "boolean" ? watch.autoStart : DEFAULT_CONFIG.autoStart,
+    path,
+    warning: null,
+    present: true,
+  };
+}
+
+/**
+ * The session identity the client injects into a spawned agent process
+ * (`crates/onlyne-client/src/dispatch.rs`). All three are required: with any one
+ * missing this is a plain pi session and the extension stays out of the way.
+ *
+ * @param {Record<string, string | undefined>} env
+ * @returns {{ role: string, sessionId: string, taskId: string } | null}
+ */
+export function sessionIdentity(env) {
+  const role = env.ONLYNE_ROLE;
+  const sessionId = env.ONLYNE_SESSION_ID;
+  const taskId = env.ONLYNE_TASK_ID;
+  if (!role || !sessionId || !taskId) return null;
+  return { role, sessionId, taskId };
+}

package/src/config.test.mjs

@@ -0,0 +1,88 @@
+// `.pi/onlyne.json` and the session-identity gate.
+//
+// The identity gate is the hard requirement that lets one pi installation serve
+// both onlyne sessions and ordinary ones: with any of the three variables
+// missing the extension must stay inert.
+
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { afterEach, test } from "node:test";
+
+import { CONFIG_RELATIVE_PATH, DEFAULT_CONFIG, loadConfig, sessionIdentity } from "./config.mjs";
+
+const cleanups = [];
+afterEach(() => {
+  while (cleanups.length > 0) cleanups.pop()();
+});
+
+/** One temp workspace, optionally carrying a `.pi/onlyne.json` body. */
+function workspace(body) {
+  const dir = mkdtempSync(join(tmpdir(), "pi-onlyne-config-"));
+  cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+  if (body !== undefined) {
+    mkdirSync(join(dir, ".pi"), { recursive: true });
+    writeFileSync(join(dir, CONFIG_RELATIVE_PATH), body);
+  }
+  return dir;
+}
+
+test("a missing switch file means enabled and autoStart", () => {
+  const dir = workspace();
+  const config = loadConfig(dir);
+  assert.deepEqual(
+    { enabled: config.enabled, autoStart: config.autoStart },
+    { enabled: DEFAULT_CONFIG.enabled, autoStart: DEFAULT_CONFIG.autoStart },
+  );
+  assert.equal(config.present, false);
+  assert.equal(config.warning, null);
+  assert.equal(config.path, join(dir, ".pi", "onlyne.json"));
+});
+
+test("the switch file's two keys are honoured", () => {
+  const dir = workspace(JSON.stringify({ enabled: false, watch: { autoStart: false } }));
+  const config = loadConfig(dir);
+  assert.equal(config.enabled, false);
+  assert.equal(config.autoStart, false);
+  assert.equal(config.present, true);
+
+  const partial = workspace(JSON.stringify({ watch: { autoStart: false } }));
+  assert.deepEqual(
+    { enabled: loadConfig(partial).enabled, autoStart: loadConfig(partial).autoStart },
+    { enabled: true, autoStart: false },
+  );
+});
+
+test("a malformed switch file warns and falls back instead of disabling the session", () => {
+  const broken = workspace("{not json");
+  const brokenConfig = loadConfig(broken);
+  assert.equal(brokenConfig.enabled, true);
+  assert.equal(brokenConfig.autoStart, true);
+  assert.match(brokenConfig.warning, /not valid JSON/);
+
+  const scalar = workspace('"on"');
+  const scalarConfig = loadConfig(scalar);
+  assert.equal(scalarConfig.enabled, true);
+  assert.match(scalarConfig.warning, /must hold a JSON object/);
+});
+
+test("the session identity gate needs all three variables", () => {
+  const full = { ONLYNE_ROLE: "planner", ONLYNE_SESSION_ID: "s1", ONLYNE_TASK_ID: "t1" };
+  assert.deepEqual(sessionIdentity(full), { role: "planner", sessionId: "s1", taskId: "t1" });
+  for (const missing of ["ONLYNE_ROLE", "ONLYNE_SESSION_ID", "ONLYNE_TASK_ID"]) {
+    const partial = { ...full };
+    delete partial[missing];
+    assert.equal(sessionIdentity(partial), null, `${missing} alone must disable the plugin`);
+  }
+  assert.equal(sessionIdentity({}), null);
+  assert.equal(sessionIdentity({ ONLYNE_ROLE: "", ONLYNE_SESSION_ID: "s", ONLYNE_TASK_ID: "t" }), null);
+});
+
+test("the shipped switch file documents only the keys the plugin reads", () => {
+  const path = fileURLToPath(new URL("../onlyne.json.example", import.meta.url));
+  const example = JSON.parse(readFileSync(path, "utf8"));
+  assert.deepEqual(example, { enabled: true, watch: { autoStart: true } });
+});

package/src/frame.mjs

@@ -0,0 +1,99 @@
+// Length-prefixed JSON framing, the onlyne-frame codec: a four-byte big-endian
+// u32 body length followed by one UTF-8 JSON object. Zero dependencies: Node's
+// Buffer is the whole implementation.
+//
+// Failure modes mirror `crates/onlyne-frame/src/lib.rs` so the plugin's log
+// speaks the same vocabulary the host does: an oversize length prefix is
+// `frame_too_large`, undecodable JSON is `bad_frame`.
+
+/** Hard ceiling for one frame body, byte-for-byte `MAX_FRAME_BYTES`. */
+export const MAX_FRAME_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Encode one frame. Throws before any byte leaves the writer, so an oversize
+ * payload never puts a partial frame on the wire.
+ * @param {unknown} value
+ * @returns {Buffer}
+ */
+export function encodeFrame(value) {
+  const body = Buffer.from(JSON.stringify(value), "utf8");
+  if (body.length > MAX_FRAME_BYTES) {
+    throw new Error(`frame_too_large: ${body.length} > ${MAX_FRAME_BYTES}`);
+  }
+  const header = Buffer.allocUnsafe(4);
+  header.writeUInt32BE(body.length, 0);
+  return Buffer.concat([header, body]);
+}
+
+/**
+ * Decode one framed body. Throws the same two error shapes `encodeFrame` and
+ * the streaming decoder raise, for tests and for callers holding a whole frame.
+ * @param {Buffer} frame
+ * @returns {unknown}
+ */
+export function decodeFrame(frame) {
+  if (frame.length < 4) throw new Error("bad_frame: truncated length prefix");
+  const length = frame.readUInt32BE(0);
+  if (length > MAX_FRAME_BYTES) throw new Error(`frame_too_large: ${length} > ${MAX_FRAME_BYTES}`);
+  if (frame.length !== 4 + length) throw new Error("bad_frame: truncated body");
+  try {
+    return JSON.parse(frame.subarray(4).toString("utf8"));
+  } catch (error) {
+    throw new Error(`bad_frame: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * A streaming decoder. `push` accepts whatever the socket delivered — half a
+ * frame, several frames, or both — and calls `onFrame` once per complete body,
+ * in order.
+ *
+ * The decoder dies on the first framing fault (oversize, undecodable body) the
+ * way the connection must: framing cannot resynchronise after a corrupt body,
+ * so `onError` is called once and every later `push` is a no-op.
+ *
+ * @param {{ maxBytes?: number, onFrame: (value: unknown) => void, onError?: (error: Error) => void }} options
+ */
+export function createFrameDecoder({ maxBytes = MAX_FRAME_BYTES, onFrame, onError }) {
+  let buffer = Buffer.alloc(0);
+  let dead = false;
+  const fail = (error) => {
+    dead = true;
+    buffer = Buffer.alloc(0);
+    onError?.(error);
+  };
+  return {
+    /** @param {Buffer} chunk */
+    push(chunk) {
+      if (dead || chunk.length === 0) return;
+      buffer = buffer.length === 0 ? chunk : Buffer.concat([buffer, chunk]);
+      for (;;) {
+        if (buffer.length < 4) return;
+        const length = buffer.readUInt32BE(0);
+        if (length > maxBytes) {
+          fail(new Error(`frame_too_large: ${length} > ${maxBytes}`));
+          return;
+        }
+        if (buffer.length < 4 + length) return;
+        const body = buffer.subarray(4, 4 + length);
+        buffer = buffer.subarray(4 + length);
+        let value;
+        try {
+          value = JSON.parse(body.toString("utf8"));
+        } catch (error) {
+          fail(new Error(`bad_frame: ${error instanceof Error ? error.message : String(error)}`));
+          return;
+        }
+        onFrame(value);
+      }
+    },
+    /** Bytes held back waiting for the rest of a frame. */
+    buffered() {
+      return buffer.length;
+    },
+    /** Whether a framing fault has closed this decoder. */
+    dead() {
+      return dead;
+    },
+  };
+}

package/src/frame.test.mjs

@@ -0,0 +1,97 @@
+// Framing tests against the Rust encoder's own wire vectors.
+
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+
+import { MAX_FRAME_BYTES, createFrameDecoder, decodeFrame, encodeFrame } from "./frame.mjs";
+
+const VECTOR_DIR = fileURLToPath(new URL("../../../crates/onlyne-proto/tests/wire_vectors/", import.meta.url));
+const hasVectors = existsSync(VECTOR_DIR);
+const vector = (name) => JSON.parse(readFileSync(`${VECTOR_DIR}${name}`, "utf8"));
+
+/** Collect every frame one decoder yields from a sequence of chunks. */
+function decodeAll(chunks, options = {}) {
+  const frames = [];
+  const errors = [];
+  const decoder = createFrameDecoder({
+    onFrame: (value) => frames.push(value),
+    onError: (error) => errors.push(error),
+    ...options,
+  });
+  for (const chunk of chunks) decoder.push(chunk);
+  return { frames, errors, decoder };
+}
+
+test("a frame round trips through encode and decode", () => {
+  const value = { id: 1, op: "hello", args: { protocol: 1, capabilities: ["register", "report"] } };
+  const frame = encodeFrame(value);
+  assert.equal(frame.readUInt32BE(0), frame.length - 4);
+  assert.deepEqual(decodeFrame(frame), value);
+  assert.deepEqual(decodeAll([frame]).frames, [value]);
+});
+
+test("a half frame is held until its remainder arrives", () => {
+  const frame = encodeFrame({ op: "assign", args: { task_id: "t1" } });
+  const first = decodeAll([frame.subarray(0, 4)]);
+  assert.deepEqual(first.frames, []);
+  assert.equal(first.decoder.buffered(), 4);
+  const rest = decodeAll([frame.subarray(0, 6), frame.subarray(6)]);
+  assert.deepEqual(rest.frames, [{ op: "assign", args: { task_id: "t1" } }]);
+});
+
+test("several frames in one chunk are emitted in order", () => {
+  const frames = [encodeFrame({ id: 1 }), encodeFrame({ id: 2 }), encodeFrame({ id: 3 })];
+  const { frames: decoded } = decodeAll([Buffer.concat(frames)]);
+  assert.deepEqual(decoded, [{ id: 1 }, { id: 2 }, { id: 3 }]);
+});
+
+test("a frame split across many chunks still decodes once", () => {
+  const frame = encodeFrame({ op: "report", args: { kind: "heartbeat", data: { seq: 1001 } } });
+  const chunks = [...frame].map((byte) => Buffer.from([byte]));
+  const { frames, errors } = decodeAll(chunks);
+  assert.deepEqual(errors, []);
+  assert.deepEqual(frames, [{ op: "report", args: { kind: "heartbeat", data: { seq: 1001 } } }]);
+});
+
+test("an oversize length prefix kills the decoder without emitting a frame", () => {
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(MAX_FRAME_BYTES + 1, 0);
+  const { frames, errors, decoder } = decodeAll([header]);
+  assert.deepEqual(frames, []);
+  assert.equal(errors.length, 1);
+  assert.match(errors[0].message, /^frame_too_large: /);
+  // A dead decoder stays dead: framing cannot resynchronise after a corrupt length.
+  assert.equal(decoder.dead(), true);
+  assert.equal(decoder.buffered(), 0);
+});
+
+test("undecodable JSON is a bad_frame fault", () => {
+  const body = Buffer.from("{not json", "utf8");
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(body.length, 0);
+  const { frames, errors } = decodeAll([Buffer.concat([header, body])]);
+  assert.deepEqual(frames, []);
+  assert.match(errors[0].message, /^bad_frame: /);
+});
+
+test("the encoder refuses a body above the ceiling before writing anything", () => {
+  assert.throws(
+    () => encodeFrame({ text: "x".repeat(MAX_FRAME_BYTES + 1) }),
+    /frame_too_large/,
+  );
+});
+
+test("the Rust encoder's own vectors decode through this decoder", { skip: !hasVectors }, () => {
+  const names = ["adapter_plugin_hello.json", "adapter_plugin_report.json", "adapter_host_assign.json"];
+  for (const name of names) {
+    const entry = vector(name);
+    assert.equal(entry.encoding, "u32_be_length_prefix_plus_utf8_json");
+    const body = Buffer.from(entry.frame, "utf8");
+    const framed = encodeFrame(JSON.parse(entry.frame));
+    assert.equal(framed.readUInt32BE(0), body.length, `${name}: length prefix must be the body byte count`);
+    assert.deepEqual(decodeFrame(framed), JSON.parse(entry.frame), `${name}: round trip`);
+    assert.deepEqual(decodeAll([framed]).frames, [JSON.parse(entry.frame)], `${name}: streamed decode`);
+  }
+});

package/src/index.ts

@@ -0,0 +1,300 @@
+// pi-onlyne — the onlyne agent adapter for pi.
+//
+// The factory registers event handlers and starts nothing: pi loads extensions
+// in invocations that never open a session, and this plugin must stay inert
+// outside an onlyne-spawned session anyway. The session identity arrives in the
+// environment (`ONLYNE_ROLE`, `ONLYNE_SESSION_ID`, `ONLYNE_TASK_ID`, injected by
+// `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         -> heartbeat{idle}
+//   message_end      -> keep the last assistant text; a failed turn is `failed`
+//   agent_settled    -> completion exit: done|failed
+//   session_shutdown -> detach{reason}
+
+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 { createSurface } from "./pi-surface.mjs";
+
+/**
+ * Node's process globals, declared here so the package needs no `@types/node`
+ * and no unchecked cast to reach them.
+ */
+declare const process: {
+  env: Record<string, string | undefined>;
+  pid: number;
+  stderr: { write(chunk: string): void };
+};
+
+/** Socket every role workspace serves; `crates/onlyne-client/src/adapter_socket.rs`. */
+const SOCKET_RELATIVE_PATH = ".onlyne/run/s";
+
+/** One image part handed to the pi message surface. */
+interface ImagePartInput {
+  mime: string;
+  data: string;
+  name?: string | null;
+}
+
+/** What a `welcome` carries, as the surface needs it. */
+interface WelcomeLike {
+  role: string;
+}
+
+/**
+ * The effect surface the agent drives (`pi-surface.mjs`): the contract between
+ * the protocol core and pi's API.
+ */
+interface PiSurface {
+  available: {
+    wakeUser: boolean;
+    proseContext: boolean;
+    customEntry: boolean;
+    status: boolean;
+    exit: boolean;
+    isIdle: boolean;
+    registerTool: boolean;
+    registerCommand: boolean;
+  };
+  wakeUser(text: string, parts?: ImagePartInput[]): boolean;
+  proseContext(text: string, welcome: WelcomeLike): boolean;
+  customEntry(customType: string, data: unknown): boolean;
+  status(text: string): void;
+  welcome(welcome: WelcomeLike): void;
+  isIdle(): boolean;
+  exit(reason: string): void;
+}
+
+/**
+ * Last assistant text inside one message.
+ *
+ * Read field by field rather than by type assertion: pi's `AgentMessage` union
+ * also admits extension-defined custom messages, so nothing about the shape is
+ * guaranteed until `role` says `assistant`.
+ */
+function assistantTextOf(message: unknown): string {
+  if (!message || typeof message !== "object") return "";
+  if (!("role" in message) || message.role !== "assistant") return "";
+  if (!("content" in message)) return "";
+  const content = message.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const part of content) {
+    if (!part || typeof part !== "object") continue;
+    if (!("type" in part) || part.type !== "text") continue;
+    if (!("text" in part) || typeof part.text !== "string") continue;
+    parts.push(part.text);
+  }
+  return parts.join("\n");
+}
+
+/** One line of a failed assistant message, when it carries one. */
+function failureOf(message: unknown): string | null {
+  if (!message || typeof message !== "object") return null;
+  if (!("stopReason" in message) || message.stopReason !== "error") return null;
+  if ("errorMessage" in message && typeof message.errorMessage === "string" && message.errorMessage) {
+    return message.errorMessage;
+  }
+  return "turn failed";
+}
+
+/**
+ * Result shape every tool returns to pi. A named helper because three call
+ * sites must produce the identical envelope.
+ */
+const textResult = (text: string, details?: unknown) => ({
+  content: [{ type: "text" as const, text }],
+  details,
+});
+
+export default function onlyne(pi: ExtensionAPI) {
+  const env: Record<string, string | undefined> = typeof process === "undefined" ? {} : process.env;
+  let context: ExtensionContext | null = null;
+  let agent: OnlyneAgent | null = null;
+  let surface: PiSurface | null = null;
+  let registered = false;
+
+  const log = (line: string, data?: unknown) => {
+    const detail = data === undefined ? "" : ` ${JSON.stringify(data)}`;
+    process?.stderr?.write(`[pi-onlyne] ${line}${detail}\n`);
+  };
+
+  /** Tools and the `/onlyne` command exist only inside an onlyne session. */
+  const registerSurface = () => {
+    if (registered || !surface) return;
+    registered = true;
+    try {
+      pi.registerTool(defineTool({
+        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",
+        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.",
+        ],
+        parameters: Type.Object({
+          to: Type.String({ description: "target role name, e.g. builder" }),
+          text: Type.String({ description: "message body" }),
+          kind: Type.Optional(Type.String({ description: '"note" (default) or "task"' })),
+          image: Type.Optional(Type.String({ description: "absolute path to a png/jpeg/gif/webp image to attach" })),
+        }),
+        async execute(_toolCallId, params) {
+          if (!agent) throw new Error("onlyne: session is not connected");
+          const result = await agent.sendFromTool({
+            to: params.to,
+            text: params.text,
+            kind: params.kind,
+            imagePath: params.image ?? null,
+          });
+          return textResult(`queued ${result.kind} to ${result.to}`, result);
+        },
+      }));
+    } catch (error) {
+      log(`registerTool(onlyne_send) refused: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+      pi.registerTool(defineTool({
+        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). Without this call the session still completes on its own: done, or failed when the turn errored. 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",
+        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 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.",
+        ],
+        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: `" })),
+        }),
+        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.
+          const result = await agent.completeFromTool({
+            outcome: params.outcome,
+            text: params.text,
+            force: params.force,
+            reason: params.reason,
+          });
+          return textResult(`onlyne task ${result.taskId} -> ${result.outcome}`, result);
+        },
+      }));
+    } catch (error) {
+      log(`registerTool(onlyne_complete) refused: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+      pi.registerCommand("onlyne", {
+        description: "Onlyne session status: connection, task, reports",
+        handler: async (argLine, commandContext) => {
+          if (!agent) {
+            commandContext.ui.notify("onlyne: no session (ONLYNE_* env is absent)", "info");
+            return;
+          }
+          const verb = String(argLine ?? "").trim();
+          if (verb === "disconnect") {
+            agent.stop("operator");
+            commandContext.ui.notify("onlyne: detached", "info");
+            return;
+          }
+          if (verb === "connect") {
+            agent.start();
+            commandContext.ui.notify(`onlyne: connecting to ${agent.status().socket}`, "info");
+            return;
+          }
+          commandContext.ui.notify(`onlyne ${JSON.stringify(agent.status())}`, "info");
+        },
+      });
+    } catch (error) {
+      log(`registerCommand refused: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    context = ctx;
+    const identity = sessionIdentity(env);
+    if (!identity) return; // not an onlyne session: stay out of the way
+    const config = loadConfig(ctx.cwd);
+    if (config.warning) log(config.warning);
+    if (!config.enabled) {
+      log(`disabled by ${config.path}`);
+      return;
+    }
+    const socketPath = env.ONLYNE_SOCKET || `${ctx.cwd}/${SOCKET_RELATIVE_PATH}`;
+    // 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 ?? "-"}`,
+      );
+    }
+    surface = createSurface({ pi, log, context: () => context });
+    agent = new OnlyneAgent({
+      socketPath,
+      cwd: ctx.cwd,
+      role: identity.role,
+      sessionId: identity.sessionId,
+      taskId: identity.taskId,
+      surface,
+      relay,
+      log,
+    });
+    log(`session ${identity.sessionId} role=${identity.role} socket=${socketPath}`);
+    registerSurface();
+    if (!surface.available.wakeUser) {
+      // Without an injection surface the payload travels through config_get,
+      // and the hello capability list has to say so.
+      log("no wakeUser surface: dropping the inject capability");
+      agent.capabilities = agent.capabilities.filter((name) => name !== "inject");
+    }
+    if (config.autoStart) agent.start();
+  });
+
+  pi.on("turn_start", async () => {
+    agent?.onTurnStart();
+  });
+
+  pi.on("turn_end", async (event) => {
+    const failure = failureOf(event.message);
+    if (failure) agent?.onTurnError(failure);
+    else agent?.onTurnEnd();
+  });
+
+  pi.on("message_end", async (event) => {
+    const failure = failureOf(event.message);
+    if (failure) {
+      agent?.onTurnError(failure);
+      return;
+    }
+    agent?.noteAssistantText(assistantTextOf(event.message));
+  });
+
+  pi.on("agent_settled", async () => {
+    agent?.onSettled();
+  });
+
+  pi.on("session_shutdown", async (event) => {
+    agent?.stop(`pi:${event.reason ?? "quit"}`);
+    agent = null;
+    surface = null;
+    registered = false;
+    context = null;
+  });
+}