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

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.3",
 	license: "Apache-2.0",
 	type: "module",
 	main: "dist/index.js",
@@ -397,12 +598,182 @@ const SETTINGS = [
 */
 const TITLE_PREFIX = /^π(?:$|\s+(?:[>!:]|[⠁-⣿]|[◔◑◕○●]|[-\\/|])|:(?=\s|$))\s*/u;
 /**
+* Loads that provider from the environment. The source is fixed: it names the
+* variable and never interpolates its value, so no preset data (and no
+* credential) is written to a node. A launch without the variable loads
+* nothing, which keeps the module inert for every other omp preset.
+*
+* The value is preset-controlled, so malformed or incomplete JSON leaves the
+* module inert too. It must match what `model-cli omp` generates and nothing
+* else: the provider keeps model-cli's namespace, so a preset cannot override
+* a built-in provider; the apiKey is the env-var name rather than a literal
+* secret; and no field may carry omp's `!command` config syntax, which would
+* run shell commands as the pane user. Registration is queued outside the
+* extension factory's error guard, so a value omp would reject there would
+* take the pane down at startup instead of warning. One debug line names the
+* problem, never the value.
+*
+* A preset built from `model-cli omp` used to name its provider by an
+* `--extension` path in the generating host's cache, so it only worked on
+* machines where model-cli had run. This module rides the per-launch
+* extension directory the host already ships to every node instead.
+*/
+const MODEL_CLI_PROVIDER_SHIM = `export default function(pi) {
+  const raw = process.env.MODEL_CLI_OMP_CONFIG;
+  if (!raw) return;
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch {
+    pi.logger?.debug?.("model-cli provider config ignored: MODEL_CLI_OMP_CONFIG is not JSON");
+    return;
+  }
+
+  const CONNECTION_KEYS = ["baseUrl", "api", "apiKey", "models"];
+  const MODEL_KEYS = [
+    "id",
+    "name",
+    "contextWindow",
+    "maxTokens",
+    "reasoning",
+    "input",
+    "cost",
+    "compat",
+    "thinking",
+  ];
+  const COST_KEYS = ["input", "output", "cacheRead", "cacheWrite"];
+  const COMPAT_KEYS = [
+    "maxTokensField",
+    "reasoningContentField",
+    "replayReasoningContent",
+    "requiresReasoningContentForAllAssistantTurns",
+    "supportsDeveloperRole",
+    "supportsStore",
+    "supportsStrictMode",
+    "thinkingFormat",
+  ];
+  const THINKING_KEYS = ["mode", "efforts", "effortMap"];
+
+  const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+  const only = (value, keys) => Object.keys(value).every((key) => keys.includes(key));
+  const text = (value) => typeof value === "string" && value !== "";
+  const amount = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
+  const positive = (value) => amount(value) && value > 0;
+  const command = (value) => {
+    if (typeof value === "string") return value.startsWith("!");
+    if (Array.isArray(value)) return value.some(command);
+    if (isObject(value)) return Object.values(value).some(command);
+    return false;
+  };
+  const cost = (value) => isObject(value) && only(value, COST_KEYS) && Object.values(value).every(amount);
+  const compat = (value) =>
+    isObject(value) &&
+    only(value, COMPAT_KEYS) &&
+    Object.values(value).every((item) => typeof item === "string" || typeof item === "boolean");
+  const thinking = (value) =>
+    isObject(value) &&
+    only(value, THINKING_KEYS) &&
+    (value.mode === "anthropic-adaptive" || value.mode === "effort") &&
+    Array.isArray(value.efforts) &&
+    value.efforts.every(text) &&
+    isObject(value.effortMap) &&
+    Object.values(value.effortMap).every(text);
+  const model = (value) =>
+    isObject(value) &&
+    only(value, MODEL_KEYS) &&
+    text(value.id) &&
+    (value.name === undefined || text(value.name)) &&
+    (value.contextWindow === undefined || positive(value.contextWindow)) &&
+    (value.maxTokens === undefined || positive(value.maxTokens)) &&
+    (value.reasoning === undefined || typeof value.reasoning === "boolean") &&
+    (value.input === undefined ||
+      (Array.isArray(value.input) && value.input.every((item) => item === "text" || item === "image"))) &&
+    (value.cost === undefined || cost(value.cost)) &&
+    (value.compat === undefined || compat(value.compat)) &&
+    (value.thinking === undefined || thinking(value.thinking));
+
+  const connection = config?.connection;
+  const models = connection?.models;
+  const usable =
+    typeof config?.provider === "string" &&
+    /^model-cli-omp-(?:litellm|direct)-\\S+$/.test(config.provider) &&
+    isObject(connection) &&
+    only(connection, CONNECTION_KEYS) &&
+    typeof connection.baseUrl === "string" &&
+    /^https?:\\/\\/.+/.test(connection.baseUrl) &&
+    (connection.api === "anthropic-messages" || connection.api === "openai-completions") &&
+    connection.apiKey === "MODEL_CLI_OMP_API_KEY" &&
+    Array.isArray(models) &&
+    models.length > 0 &&
+    models.every(model) &&
+    !command(config);
+  if (!usable) {
+    pi.logger?.debug?.("model-cli provider config ignored: MODEL_CLI_OMP_CONFIG is not the model-cli shape");
+    return;
+  }
+  pi.registerProvider(config.provider, connection);
+}
+`;
+/**
+* A preset built from `model-cli omp` used to prove its provider with an
+* extension path in the generating host's cache. That file is writable by
+* anything running as the pane user and persists between launches, so the
+* provider module below is a replacement, not a companion: the legacy flag is
+* dropped when this launch writes its own module. omp accepts the path as
+* `--extension`, `--trusted-extension`, `-e` or `--hook`, so every spelling is
+* matched, and the path is normalized first because `./` and doubled
+* separators name the same file.
+*/
+const LEGACY_PROVIDER_FLAGS = [
+	"--extension",
+	"--trusted-extension",
+	"-e",
+	"--hook"
+];
+const LEGACY_PROVIDER_INLINE = [
+	"--extension=",
+	"--trusted-extension=",
+	"-e=",
+	"--hook="
+];
+function isLegacyProviderPath(value) {
+	const segments = value.trim().replace(/\\/g, "/").split("/").filter((segment) => segment !== "" && segment !== ".");
+	return /(?:^|\/)model-cli\/omp-provider\.mjs$/.test(segments.join("/"));
+}
+function withoutLegacyProviderExtension(flags) {
+	const kept = [];
+	for (let i = 0; i < flags.length; i++) {
+		const flag = flags[i];
+		if (LEGACY_PROVIDER_FLAGS.includes(flag) && isLegacyProviderPath(flags[i + 1] ?? "")) {
+			i += 1;
+			continue;
+		}
+		const inline = LEGACY_PROVIDER_INLINE.find((prefix) => flag.startsWith(prefix));
+		if (inline && isLegacyProviderPath(flag.slice(inline.length))) continue;
+		kept.push(flag);
+	}
+	return kept;
+}
+/**
 * 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 }) {
@@ -416,7 +787,7 @@ const createPlugin = () => ({
 			const value = settings[key];
 			if (typeof value === "string" && value) args.push(`--${key}`, value);
 		}
-		args.push(...preset.flags, ...extraFlags ?? []);
+		args.push(...mcp ? withoutLegacyProviderExtension(preset.flags) : preset.flags, ...extraFlags ?? []);
 		return args;
 	},
 	mcpRegistration(launch, configPath) {
@@ -432,9 +803,15 @@ const createPlugin = () => ({
 					name: "subshell-mcp",
 					private: true,
 					type: "module",
-					omp: { extensions: ["bridge.mjs"] }
+					omp: { extensions: [
+						"bridge.mjs",
+						"subagents.mjs",
+						"provider.mjs"
+					] }
 				}),
 				"bridge.mjs": "export default function () {}\n",
+				"subagents.mjs": SUBAGENT_BRIDGE,
+				"provider.mjs": MODEL_CLI_PROVIDER_SHIM,
 				"mcp.json": fileContent
 			},
 			args: ["--extension", `${configPath}.d`]
@@ -443,7 +820,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.3",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",