@subshell-ai/plugin-oh-my-pi 0.2.1 → 0.2.2

package/README.md

@@ -1,13 +1,12 @@
 # Oh My Pi plugin for Subshell
 
 `@subshell-ai/plugin-oh-my-pi` launches the `omp` CLI from Subshell. It provides
-model, provider, and thinking settings, plus automatic per-launch MCP
-configuration. Install and authenticate Oh My Pi separately on each node
-where you want to run it.
+model, provider, and thinking settings, automatic per-launch MCP
+configuration, and sidebar subagent monitoring. Install and authenticate Oh My
+Pi separately on each node where you want to run it.
 
 See the [Oh My Pi guide](https://docs.subshell.sh/agents/oh-my-pi) for setup
 and supported behavior. The integration is verified with Oh My Pi 18.12.6.
-Automatic conversation resumption, attention hooks, and sidebar subagent
-monitoring aren't supported.
+Automatic conversation resumption and attention hooks aren't supported.
 
 Licensed under Apache-2.0.

package/dist/index.d.ts

@@ -500,6 +500,24 @@ interface InstallSpec {
    */
   docsUrl: string;
 }
+/**
+ * How this plugin's harness CLI updates itself in place.
+ *
+ * The installer doubles as the updater for every built-in today (`curl … | sh`
+ * and `npm i -g` lines are idempotent), so this is OPTIONAL and falls back to
+ * {@link InstallSpec}. Declare it where the vendor ships a dedicated verb or a
+ * different channel — `claude update`, say — so pressing Update runs the
+ * vendor's own update path rather than reinstalling.
+ *
+ * Like `install.command`, this is a SHELL LINE the host runs through `sh -c`,
+ * on the node that holds the harness, and it may not need privileges.
+ */
+interface UpdateSpec {
+  /** Shell line that updates the CLI in place. */
+  command: string;
+  /** Where the vendor documents it; http(s) only, when present. */
+  docsUrl?: string;
+}
 /** One step an operator must run themselves, because the host may not. */
 interface PrivilegedStep {
   /** What it does, in a few words: "Install the daemon" */
@@ -643,6 +661,11 @@ interface SubshellManifest {
   detect?: DetectSpec;
   /** Install guidance shown when the binary is missing */
   install?: InstallSpec;
+  /**
+   * How the CLI updates itself, when the installer is not the updater.
+   * Absent means `install.command` is the update path too.
+   */
+  update?: UpdateSpec;
   /**
    * Environment variables this plugin computes against (spec 2026-09-10 §5).
    *
@@ -677,6 +700,11 @@ declare const manifest: SubshellManifest;
  * Oh My Pi uses its own executable and native MCP discovery, independently of
  * pi. An explicit extension directory contributes mcp.json without redirecting
  * the user's config or credentials. Verified against omp 18.12.6.
+ *
+ * The same directory carries the subagent bridge. omp keeps its child roster
+ * on the session event bus; the extension reports it so the sidebar can hang
+ * those children under the parent subshell. omp offers no extension API for
+ * moving the parent's terminal onto a child, so navigation stays unavailable.
  */
 declare const createPlugin: HarnessPluginFactory;
 //#endregion

package/dist/index.js

@@ -1,4 +1,4 @@
-//#region ../../plugin-api/dist/manifest-XGvw0ugx.js
+//#region ../../plugin-api/dist/manifest-Cdy9tSLl.js
 /** Every {@link PluginType}, for anything that has to iterate or validate them. */
 const PLUGIN_TYPES = [
 	"agent-harness",
@@ -158,6 +158,19 @@ function parseManifest(pkgJson) {
 			docsUrl: i.docsUrl
 		};
 	}
+	let update;
+	if (block.update !== void 0) {
+		const u = block.update;
+		if (!isRecord(u) || typeof u.command !== "string" || u.command.trim() === "") return { error: "`subshell.update` needs a non-empty command" };
+		if (needsPrivileges(u.command)) return { error: "`subshell.update.command` must not need sudo, doas or pkexec — the host runs it through a shell and has no terminal for a password prompt" };
+		if (u.docsUrl !== void 0) {
+			if (typeof u.docsUrl !== "string" || !isDocsUrl(u.docsUrl)) return { error: "`subshell.update.docsUrl` must be an http(s) URL — it is rendered as a link on an admin page" };
+			update = {
+				command: u.command,
+				docsUrl: u.docsUrl
+			};
+		} else update = { command: u.command };
+	}
 	let hostEnv;
 	if (block.hostEnv !== void 0) {
 		if (!Array.isArray(block.hostEnv) || !block.hostEnv.every((k) => typeof k === "string" && k.trim() !== "")) return { error: "`subshell.hostEnv` must be an array of environment variable names" };
@@ -176,6 +189,7 @@ function parseManifest(pkgJson) {
 		entry: block.entry,
 		...detect ? { detect } : {},
 		...install ? { install } : {},
+		...update ? { update } : {},
 		...hostEnv ? { hostEnv } : {},
 		...parsedNetwork ? { network: parsedNetwork } : {},
 		...block.pickable === false ? { pickable: false } : {}
@@ -273,6 +287,193 @@ function validateGenericPreset(preset) {
 	};
 }
 //#endregion
+//#region src/subagents.ts
+/**
+* omp's session event bus already carries the roster the task tool is running:
+* `task:subagent:lifecycle` announces a child's start and settlement, and
+* `task:subagent:progress` streams its status, generated one-line label, and
+* latest intent. The extension below turns those frames into the snapshot
+* reports the control plane reads, so the sidebar shows the children under the
+* subshell that asked for them.
+*
+* Every frame is already bounded by omp; this module bounds again because the
+* report is rendered in the sidebar of the owner and every viewer, and it is
+* the pane's own porcelain that names them (160 characters, like the server).
+* Progress frames arrive at the coalescing rate omp emits (about 150 ms), so
+* they queue one snapshot per second; lifecycle changes report at once.
+*
+* A child session rebinds every extension factory, so this factory runs once
+* per session. Each binding keeps its own roster, and `session_start` tells a
+* child binding apart from the pane's main agent: only the main agent's roster
+* is the set of children the sidebar should hang under the subshell.
+*
+* The roster repeats every two seconds while it is non-empty: the control
+* plane keeps it in memory, so a restart has nothing until the harness reports
+* again, and an idle child produces no other frames.
+*/
+const SUBAGENT_BRIDGE = `
+export default function (pi) {
+  const LIFECYCLE = 'task:subagent:lifecycle';
+  const PROGRESS = 'task:subagent:progress';
+  const MAX_AGENTS = 256;
+  const MAX_TEXT = 160;
+  const REPORT_DELAY_MS = 1000;
+  // A live child keeps reporting, so a control-plane restart (which forgets
+  // every roster) gets the set back without waiting for the next tool event.
+  const HEARTBEAT_MS = 2000;
+
+  const agents = new Map();
+  let role = 'main';
+  let timer = null;
+  let reporting = false;
+  let queued = false;
+  let heartbeat = null;
+  let warned = false;
+  const label = value => {
+    if (typeof value !== 'string') return undefined;
+    const trimmed = value.trim().slice(0, MAX_TEXT);
+    return trimmed || undefined;
+  };
+  const validId = id => (typeof id === 'string' && id.length > 0 && id.length <= 256 ? id : null);
+  const statusFor = status =>
+    status === 'pending' ? 'waiting' : status === 'running' ? 'running' : null;
+
+  const put = (id, status, activity) => {
+    const key = validId(id);
+    if (!key || role !== 'main') return false;
+    if (!agents.has(key) && agents.size >= MAX_AGENTS) return false;
+    const previous = agents.get(key);
+    // The report schema caps the name field at 160 while the id may run to
+    // 256; an over-long name would fail validation for the whole snapshot.
+    const next = { id: key, name: key.slice(0, MAX_TEXT), status };
+    const words = activity || previous?.activity;
+    if (words) next.activity = words;
+    agents.set(key, next);
+    if (heartbeat === null) heartbeat = setInterval(beat, HEARTBEAT_MS);
+    return true;
+  };
+
+  const drop = id => {
+    if (role !== 'main') return false;
+    const key = validId(id);
+    return key ? agents.delete(key) : false;
+  };
+
+  const report = async () => {
+    if (reporting) {
+      queued = true;
+      return;
+    }
+    const base = process.env.SUBSHELL_BASE_URL;
+    const token = process.env.SUBSHELL_API_KEY;
+    const id = process.env.SUBSHELL_ID;
+    if (!base || !token || !id) {
+      if (!warned) {
+        warned = true;
+        pi.logger?.debug?.('subshell subagent report skipped: the pane identity environment is missing');
+      }
+      return;
+    }
+    reporting = true;
+    try {
+      const response = await fetch(base + '/api/subshells/' + encodeURIComponent(id) + '/subagents/report', {
+        method: 'POST',
+        headers: { authorization: 'Bearer ' + token, 'content-type': 'application/json' },
+        body: JSON.stringify({
+          event: 'snapshot',
+          agents: [...agents.values()].slice(0, MAX_AGENTS),
+          selectedId: null,
+          canSelect: false,
+        }),
+        signal: AbortSignal.timeout(2000),
+      });
+      if (!response.ok && !warned) {
+        warned = true;
+        pi.logger?.debug?.('subshell subagent report failed', { status: response.status });
+      }
+    } catch {
+      // A failed report is not fatal: the next frame reports again, and a pane
+      // without the identity variables above has no endpoint to reach.
+    } finally {
+      reporting = false;
+      if (queued) {
+        queued = false;
+        void report();
+      }
+    }
+  };
+
+  const schedule = () => {
+    if (timer !== null) return;
+    timer = setTimeout(() => {
+      timer = null;
+      void report();
+    }, REPORT_DELAY_MS);
+  };
+
+  const beat = () => {
+    if (role !== 'main' || agents.size === 0) {
+      if (heartbeat !== null) {
+        clearInterval(heartbeat);
+        heartbeat = null;
+      }
+      return;
+    }
+    void report();
+  };
+
+  pi.events.on(LIFECYCLE, frame => {
+    if (!frame || typeof frame !== 'object' || typeof frame.status !== 'string') return;
+    if (frame.status === 'started') {
+      if (put(frame.id, 'running', label(frame.description) || label(frame.agent))) schedule();
+    } else if (drop(frame.id)) schedule();
+  });
+
+  pi.events.on(PROGRESS, frame => {
+    if (!frame || typeof frame !== 'object') return;
+    const progress = frame.progress;
+    if (!progress || typeof progress !== 'object') return;
+    const status = statusFor(progress.status);
+    if (status) {
+      if (put(progress.id ?? frame.id, status, label(progress.description) || label(progress.lastIntent))) schedule();
+    } else if (progress.status === 'completed' || progress.status === 'failed' || progress.status === 'aborted') {
+      if (drop(progress.id ?? frame.id)) schedule();
+    }
+  });
+
+  const reset = () => {
+    agents.clear();
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (heartbeat !== null) {
+      clearInterval(heartbeat);
+      heartbeat = null;
+    }
+    return report();
+  };
+
+  pi.on('session_start', (_event, ctx) => {
+    role = ctx && ctx.agent && ctx.agent.kind === 'sub' ? 'sub' : 'main';
+    if (role !== 'main') return;
+    return reset();
+  });
+
+  // A switch (resume, fork, new) replaces the conversation the roster belonged
+  // to; its children are no longer this session's children.
+  pi.on('session_switch', () => {
+    if (role !== 'main') return;
+    return reset();
+  });
+
+  pi.on('session_shutdown', () => {
+    if (role !== 'main') return;
+    return reset();
+  });
+}
+`;
+//#endregion
 //#region src/manifest.ts
 /**
 * This package's own `subshell` block, read from its package.json so the
@@ -285,7 +486,7 @@ function validateGenericPreset(preset) {
 const parsed = parseManifest({
 	name: "@subshell-ai/plugin-oh-my-pi",
 	description: "Oh My Pi harness plugin for Subshell",
-	version: "0.2.1",
+	version: "0.2.2",
 	license: "Apache-2.0",
 	type: "module",
 	main: "dist/index.js",
@@ -400,9 +601,22 @@ const TITLE_PREFIX = /^π(?:$|\s+(?:[>!:]|[⠁-⣿]|[◔◑◕○●]|[-\\/|])|:
 * Oh My Pi uses its own executable and native MCP discovery, independently of
 * pi. An explicit extension directory contributes mcp.json without redirecting
 * the user's config or credentials. Verified against omp 18.12.6.
+*
+* The same directory carries the subagent bridge. omp keeps its child roster
+* on the session event bus; the extension reports it so the sidebar can hang
+* those children under the parent subshell. omp offers no extension API for
+* moving the parent's terminal onto a child, so navigation stays unavailable.
 */
 const createPlugin = () => ({
-	capabilities: () => ["mcp", "settings"],
+	subagents: {
+		discovery: "extension",
+		navigation: "unavailable"
+	},
+	capabilities: () => [
+		"subagents",
+		"mcp",
+		"settings"
+	],
 	/** `π <state> <label>`: the label behind the brand and run state is the name. */
 	parsePaneTitle: (raw) => raw.replace(TITLE_PREFIX, "").trim(),
 	buildCommand({ binary, preset, extraFlags, mcp }) {
@@ -432,9 +646,10 @@ const createPlugin = () => ({
 					name: "subshell-mcp",
 					private: true,
 					type: "module",
-					omp: { extensions: ["bridge.mjs"] }
+					omp: { extensions: ["bridge.mjs", "subagents.mjs"] }
 				}),
 				"bridge.mjs": "export default function () {}\n",
+				"subagents.mjs": SUBAGENT_BRIDGE,
 				"mcp.json": fileContent
 			},
 			args: ["--extension", `${configPath}.d`]
@@ -443,7 +658,7 @@ const createPlugin = () => ({
 	mcpSetup() {
 		return {
 			mode: "auto",
-			summary: "Subshell registers its MCP server through a per-launch Oh My Pi extension. Your existing configuration stays in place."
+			summary: "Subshell registers its MCP server and reports the pane's subagents through a per-launch Oh My Pi extension. Your existing configuration stays in place."
 		};
 	},
 	validatePreset: validateGenericPreset,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@subshell-ai/plugin-oh-my-pi",
   "description": "Oh My Pi harness plugin for Subshell",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",