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

package/README.md

@@ -2,11 +2,11 @@
 
 `@subshell-ai/plugin-oh-my-pi` launches the `omp` CLI from Subshell. It provides
 model, provider, and thinking settings, automatic per-launch MCP
-configuration, and sidebar subagent monitoring. Install and authenticate Oh My
+configuration, and sidebar subagent monitoring with view switching. 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.
+and supported behavior. The integration is verified with Oh My Pi 18.18.7.
 Automatic conversation resumption and attention hooks aren't supported.
 
 Licensed under Apache-2.0.

package/dist/index.d.ts

@@ -1,8 +1,104 @@
-//#region ../../plugin-api/dist/types-DPriUYLa.d.ts
+//#region ../../plugin-api/dist/types-D2qRfuN_.d.ts
+//#region src/previews.d.ts
+/**
+ * How a harness reports loopback ports its own tooling started, for the
+ * preview picker.
+ *
+ * Port discovery attributes sockets by walking the pane's process tree. A
+ * harness that brokers its tool shells through a shared daemon (oh-my-pi
+ * does) leaves that tree, so a server its tools start is reachable but
+ * invisible. A plugin that declares the `previews` capability ships a
+ * reporter the control plane can list those ports from.
+ *
+ * The report carries ports only, never a host: the node dials loopback, so a
+ * report cannot point the proxy at another machine.
+ */
+type HarnessPreviewReporting = "extension" | "hooks";
+/**
+ * What a harness declares about its preview reporting. The rules mirror
+ * {@link HarnessSubagentSupport}: `reporting` is checked against the union at
+ * load, and `setup` is the copy the preset editor shows when a human act is
+ * needed before reports start.
+ */
+interface HarnessPreviews {
+  /** How reports reach the plane: a per-launch extension, or harness lifecycle hooks. */
+  reporting: HarnessPreviewReporting;
+  /** One-time human action required for reporting to work, if any. */
+  setup?: string;
+}
+//#endregion
+//#region src/subagents.d.ts
+/** What a reported agent is doing, as the harness itself says. */
+type HarnessSubagentStatus = "running" | "waiting" | "idle";
+/** A harness agent belongs to an existing terminal, never to a new subshell. */
+interface HarnessSubagent {
+  /** Harness-side identifier; unique among this parent's current children */
+  id: string;
+  /** Parent agent within the harness, when the harness nests */
+  parentId?: string;
+  /** Display name as the harness reports it; generic ones render numbered */
+  name: string;
+  /** What the harness says this agent is doing */
+  status: HarnessSubagentStatus;
+  /**
+   * The harness's own one-line label for what this child was asked to do,
+   * when the harness has one to give. The host bounds it and normalizes it
+   * like a name; it is the harness's summary of the task, never the prompt
+   * text or anything read from the child's transcript.
+   */
+  activity?: string;
+}
+/**
+ * A reported child as the control plane SERVES it: what the harness said, plus
+ * the server's own observation of when the child appeared. Viewers derive
+ * elapsed time from that stamp against their own clock, so a roster that
+ * stopped being polled ages honestly instead of freezing at its last read.
+ */
+interface HarnessSubagentView extends HarnessSubagent {
+  /** Epoch milliseconds of when the server first saw this child; never sent by a harness */
+  startedAt: number;
+}
 /** How the plugin learns about children: harness lifecycle hooks, or a loaded extension. */
 type HarnessSubagentDiscovery = "hooks" | "extension";
 /** Whether the sidebar can move the parent's own view to a child, or the harness keeps that in-app. */
 type HarnessSubagentNavigation = "native" | "unavailable";
+/**
+ * Pane operations the host hands an integration that drives its harness's
+ * own agent picker. The plugin runs in the control plane, so it cannot open a
+ * terminal itself; these are the only two acts it needs, and neither submits
+ * a prompt on its own.
+ */
+interface HarnessSubagentPane {
+  /** The parent pane's current screen with ANSI stripped, exactly as painted. */
+  read(): Promise<string>;
+  /**
+   * Type raw bytes into the pane's own input. Nothing is appended or
+   * translated: send `\r` for Enter, `\u001b[1;3D` for Alt+Left, and so on.
+   */
+  type(text: string): Promise<void>;
+}
+/** What the host hands an integration's {@link HarnessSubagentSupport.select}. */
+interface HarnessSubagentSelectInput {
+  /** The child to show, or null to return the parent itself */
+  agentId: string | null;
+  /** The roster the child came from, server-stamped and bounded */
+  agents: readonly HarnessSubagentView[];
+  /** The parent terminal this selection must happen in */
+  pane: HarnessSubagentPane;
+}
+/** What the integration must report back after the harness actually switched. */
+interface HarnessSubagentSelectResult {
+  /** The view the harness showed when the act finished; null for the parent */
+  selectedId: string | null;
+}
+/**
+ * An integration's own way to move its terminal's view. This is for harnesses
+ * whose picker or inspector exists only inside their TUI (Codex's `/subagents`,
+ * Claude's agent panel, pi's fleet inspector): the integration reads the pane,
+ * sends the harness's own keys, and reports the view it verified. Extensions
+ * without a pane driver keep using the report-loop command.
+ */
+type HarnessSubagentSelect = (input: HarnessSubagentSelectInput) => Promise<HarnessSubagentSelectResult>;
 /**
  * What a plugin declares about its harness's child agents. The host uses
  * `discovery`/`navigation` to decide what the sidebar may offer; `setup`, when
@@ -16,6 +112,13 @@ interface HarnessSubagentSupport {
   navigation: HarnessSubagentNavigation;
   /** One-time user action required for reporting to work, if any */
   setup?: string;
+  /**
+   * The integration's own pane driver, when it has one. Requires
+   * `navigation: "native"`; the host uses it instead of queueing a command.
+   * Works for hook and extension discovery alike: the host only needs the
+   * pane's read/type, and the edit gate is the same.
+   */
+  select?: HarnessSubagentSelect;
 }
 //#endregion
 //#region src/types.d.ts
@@ -43,7 +146,7 @@ type PluginType = "agent-harness" | "terminal" | "network";
  * and a network plugin claiming `resume` are both refused at load, for the
  * same reason a claimed-but-unimplemented capability is.
  */
-type PluginCapability = "mcp" | "resume" | "attention" | "subagents" | "publish" | "supervise" | "guard" | "settings";
+type PluginCapability = "mcp" | "resume" | "attention" | "subagents" | "previews" | "publish" | "supervise" | "guard" | "settings";
 /** A harness preset as defined by the user (decoded JSON blobs). */
 interface PresetDefinition {
   /** Human-friendly preset name */
@@ -380,6 +483,13 @@ interface PluginSecrets {
 interface SubshellPlugin {
   /** Native child-agent reporting and optional in-place navigation. */
   subagents?: HarnessSubagentSupport;
+  /**
+   * Native preview-port reporting: the harness tells the plane which loopback
+   * ports its tooling serves, so the picker lists servers discovery cannot
+   * attribute to the pane's process tree. Declare the `previews` capability
+   * with it.
+   */
+  previews?: HarnessPreviews;
   /** Builds the argv (no shell) used to launch a subshell. */
   buildCommand(input: BuildCommandInput): string[];
   /** Validates a preset definition before saving. */
@@ -703,8 +813,11 @@ declare const manifest: SubshellManifest;
  *
  * 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.
+ * those children under the parent subshell. omp has no extension hook for
+ * moving the parent's terminal onto a child yet, so the bridge reaches the
+ * TUI's own public focus method through the class omp exposes as
+ * pi.pi.InteractiveMode (verified against 18.18.7). If that surface goes
+ * away, the bridge falls back to status-only reporting.
  */
 declare const createPlugin: HarnessPluginFactory;
 //#endregion

package/dist/index.js

@@ -1,4 +1,4 @@
-//#region ../../plugin-api/dist/manifest-Cdy9tSLl.js
+//#region ../../plugin-api/dist/manifest-CrULrf80.js
 /** Every {@link PluginType}, for anything that has to iterate or validate them. */
 const PLUGIN_TYPES = [
 	"agent-harness",
@@ -287,6 +287,158 @@ function validateGenericPreset(preset) {
 	};
 }
 //#endregion
+//#region src/previews.ts
+/**
+* omp brokers tool shells through its own daemon, so servers those tools
+* start live outside the pane's process tree and port discovery cannot see
+* them. This extension watches tool results for loopback URLs and reports
+* the ports to the control plane, where the preview picker lists them.
+*
+* It deliberately reports what the output says, not a scan: a tool result
+* from something that executes (bash or a custom tool) is the harness's own
+* evidence that it started something, so file-reading tools are skipped. The
+* report is port-only (the node dials loopback), bounded, and coalesced. A
+* port the harness has not mentioned for ten minutes stops being refreshed,
+* and the server's TTL retires it. A pane without the identity environment
+* has no endpoint and stays quiet.
+*/
+const PREVIEW_BRIDGE = `
+export default function (pi) {
+  const REPORT_DELAY_MS = 750;
+  const HEARTBEAT_MS = 60_000;
+  const FRESH_MS = 10 * 60_000;
+  const MAX_PORTS = 32;
+  const MAX_TITLE = 120;
+  const MAX_SCAN = 64 * 1024;
+  const SKIP_TOOLS = { read: true, edit: true, write: true, grep: true, glob: true };
+  const URL_RE = /(?:https?:\\/\\/)?(?:localhost|127\\.0\\.0\\.1|0\\.0\\.0\\.0|\\[::1\\]):(\\d{1,5})(?!\\d)/gi;
+
+  const ports = new Map();
+  let timer = null;
+  let heartbeat = null;
+  let reporting = false;
+  let queued = false;
+  let warned = false;
+  let disabled = false;
+  const prune = now => {
+    for (const [port, entry] of ports) {
+      if (now - entry.seenAt > FRESH_MS) ports.delete(port);
+    }
+    if (ports.size === 0 && heartbeat !== null) {
+      clearInterval(heartbeat);
+      heartbeat = null;
+    }
+  };
+  const remember = (port, title) => {
+    if (!Number.isInteger(port) || port < 1 || port > 65535) return;
+    const now = Date.now();
+    prune(now);
+    const previous = ports.get(port);
+    if (previous) {
+      previous.seenAt = now;
+      if (title && !previous.title) previous.title = title;
+    } else {
+      if (ports.size >= MAX_PORTS) return;
+      ports.set(port, { title, seenAt: now });
+    }
+    if (heartbeat === null) heartbeat = setInterval(beat, HEARTBEAT_MS);
+    schedule();
+  };
+
+  const scan = text => {
+    const bounded = text.slice(0, MAX_SCAN);
+    URL_RE.lastIndex = 0;
+    let match;
+    while ((match = URL_RE.exec(bounded))) {
+      const port = Number(match[1]);
+      const start = bounded.lastIndexOf('\\n', match.index) + 1;
+      const end = bounded.indexOf('\\n', match.index);
+      const line = bounded.slice(start, end === -1 ? bounded.length : end).trim();
+      remember(port, line ? line.slice(0, MAX_TITLE) : undefined);
+    }
+  };
+
+  const report = async () => {
+    if (disabled || ports.size === 0) return;
+    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 preview report skipped: the pane identity environment is missing');
+      }
+      return;
+    }
+    prune(Date.now());
+    if (ports.size === 0) return;
+    reporting = true;
+    try {
+      const response = await fetch(base + '/api/subshells/' + encodeURIComponent(id) + '/views/report', {
+        method: 'POST',
+        headers: { authorization: 'Bearer ' + token, 'content-type': 'application/json' },
+        body: JSON.stringify({
+          ports: [...ports.entries()].map(([port, entry]) => ({
+            port,
+            ...(entry.title ? { title: entry.title } : {}),
+          })),
+        }),
+        signal: AbortSignal.timeout(2000),
+      });
+      if (response.status === 404 || response.status === 401) {
+        // The server either predates the route or no longer accepts this
+        // pane's key. Retrying every heartbeat cannot fix either, so stop
+        // until a restart hands the extension a new process.
+        disabled = true;
+        if (heartbeat !== null) {
+          clearInterval(heartbeat);
+          heartbeat = null;
+        }
+      }
+      if (!response.ok && !warned) {
+        warned = true;
+        pi.logger?.debug?.('subshell preview report failed', { status: response.status });
+      }
+    } catch {
+      // A failed report is not fatal: the next tool result reports again.
+    } 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 = () => {
+    prune(Date.now());
+    if (ports.size > 0) void report();
+  };
+
+  pi.on('tool_result', event => {
+    if (!event || event.isError) return;
+    const name = typeof event.toolName === 'string' ? event.toolName : '';
+    if (SKIP_TOOLS[name] === true) return;
+    const content = Array.isArray(event.content) ? event.content : [];
+    for (const block of content) {
+      if (block && block.type === 'text' && typeof block.text === 'string') scan(block.text);
+    }
+  });
+}
+`;
+//#endregion
 //#region src/subagents.ts
 /**
 * omp's session event bus already carries the roster the task tool is running:
@@ -329,6 +481,19 @@ export default function (pi) {
   let queued = false;
   let heartbeat = null;
   let warned = false;
+  // omp has no extension hook for moving the TUI's view to a child. The class
+  // that owns the move is exposed to extensions as pi.pi.InteractiveMode, so
+  // capture the live instance through a property it reads while rendering and
+  // call its public focusAgentSession/unfocusSession. Restoring the getter on
+  // first read leaves the host untouched afterwards. Verified against omp
+  // 18.18.7; if the class or property disappears, the rows stay status-only
+  // instead of failing the report.
+  let mode = null;
+  let probing = false;
+  let switchWarned = false;
+  let focusing = false;
+  let acknowledged;
+  let declined;
   const label = value => {
     if (typeof value !== 'string') return undefined;
     const trimmed = value.trim().slice(0, MAX_TEXT);
@@ -359,6 +524,35 @@ export default function (pi) {
     return key ? agents.delete(key) : false;
   };
 
+  const captureMode = () => {
+    if (probing || mode) return;
+    const type = pi.pi && pi.pi.InteractiveMode;
+    const proto = typeof type === 'function' ? type.prototype : undefined;
+    const descriptor = proto && Object.getOwnPropertyDescriptor(proto, 'viewSession');
+    if (!descriptor || typeof descriptor.get !== 'function') return;
+    probing = true;
+    Object.defineProperty(proto, 'viewSession', {
+      configurable: true,
+      get() {
+        mode = this;
+        Object.defineProperty(proto, 'viewSession', descriptor);
+        return descriptor.get.call(this);
+      },
+    });
+  };
+
+  const canSelect = () =>
+    role === 'main' &&
+    mode !== null &&
+    typeof mode.focusAgentSession === 'function' &&
+    typeof mode.unfocusSession === 'function' &&
+    !mode.collabGuest;
+  const selectedId = () => {
+    if (!mode) return null;
+    const id = mode.focusedAgentId;
+    return typeof id === 'string' && agents.has(id) ? id : null;
+  };
+
   const report = async () => {
     if (reporting) {
       queued = true;
@@ -376,20 +570,66 @@ export default function (pi) {
     }
     reporting = true;
     try {
+      const selectable = canSelect();
+      const payload = {
+        event: 'snapshot',
+        agents: [...agents.values()].slice(0, MAX_AGENTS),
+        selectedId: selectedId(),
+        canSelect: selectable,
+      };
+      if (acknowledged !== undefined) payload.acknowledged = acknowledged;
+      if (!selectable) {
+        payload.unavailableReason =
+          mode && mode.collabGuest
+            ? 'Viewing agents is unavailable in a collab session.'
+            : 'This Oh My Pi build has no agent view to switch. Use its own agent selector.';
+      }
       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,
-        }),
+        body: JSON.stringify(payload),
         signal: AbortSignal.timeout(2000),
       });
-      if (!response.ok && !warned) {
-        warned = true;
-        pi.logger?.debug?.('subshell subagent report failed', { status: response.status });
+      if (!response.ok) {
+        if (!warned) {
+          warned = true;
+          pi.logger?.debug?.('subshell subagent report failed', { status: response.status });
+        }
+        return;
+      }
+      const data = await response.json().catch(() => null);
+      const command = data && data.command;
+      // The same command comes back until it is acknowledged, and a refused
+      // one is skipped rather than retried every heartbeat until it expires.
+      if (!command || !selectable || focusing || command.id === acknowledged || command.id === declined) return;
+      // The server can still list a child this binding has already dropped:
+      // it can settle between the click and the command arriving here.
+      // Decline an id this binding no longer tracks rather than asking the
+      // host to focus a finished child.
+      if (command.agentId !== null && !agents.has(command.agentId)) {
+        declined = command.id;
+        return;
+      }
+      const target = mode;
+      focusing = true;
+      try {
+        if (command.agentId === null) await target.unfocusSession();
+        else await target.focusAgentSession(command.agentId);
+        acknowledged = command.id;
+        declined = undefined;
+        // Fold the confirmed view and the acknowledgement into a trailing
+        // report; the running one already carried the old state.
+        void report();
+      } catch (error) {
+        declined = command.id;
+        if (!switchWarned) {
+          switchWarned = true;
+          pi.logger?.debug?.('subshell subagent view switch failed', {
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      } finally {
+        focusing = false;
       }
     } catch {
       // A failed report is not fatal: the next frame reports again, and a pane
@@ -443,6 +683,8 @@ export default function (pi) {
 
   const reset = () => {
     agents.clear();
+    acknowledged = undefined;
+    declined = undefined;
     if (timer !== null) {
       clearTimeout(timer);
       timer = null;
@@ -457,6 +699,7 @@ export default function (pi) {
   pi.on('session_start', (_event, ctx) => {
     role = ctx && ctx.agent && ctx.agent.kind === 'sub' ? 'sub' : 'main';
     if (role !== 'main') return;
+    captureMode();
     return reset();
   });
 
@@ -486,7 +729,7 @@ export default function (pi) {
 const parsed = parseManifest({
 	name: "@subshell-ai/plugin-oh-my-pi",
 	description: "Oh My Pi harness plugin for Subshell",
-	version: "0.2.3",
+	version: "0.3.1",
 	license: "Apache-2.0",
 	type: "module",
 	main: "dist/index.js",
@@ -761,16 +1004,21 @@ function withoutLegacyProviderExtension(flags) {
 *
 * 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.
+* those children under the parent subshell. omp has no extension hook for
+* moving the parent's terminal onto a child yet, so the bridge reaches the
+* TUI's own public focus method through the class omp exposes as
+* pi.pi.InteractiveMode (verified against 18.18.7). If that surface goes
+* away, the bridge falls back to status-only reporting.
 */
 const createPlugin = () => ({
 	subagents: {
 		discovery: "extension",
-		navigation: "unavailable"
+		navigation: "native"
 	},
+	previews: { reporting: "extension" },
 	capabilities: () => [
 		"subagents",
+		"previews",
 		"mcp",
 		"settings"
 	],
@@ -806,11 +1054,13 @@ const createPlugin = () => ({
 					omp: { extensions: [
 						"bridge.mjs",
 						"subagents.mjs",
+						"previews.mjs",
 						"provider.mjs"
 					] }
 				}),
 				"bridge.mjs": "export default function () {}\n",
 				"subagents.mjs": SUBAGENT_BRIDGE,
+				"previews.mjs": PREVIEW_BRIDGE,
 				"provider.mjs": MODEL_CLI_PROVIDER_SHIM,
 				"mcp.json": fileContent
 			},

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.3",
+  "version": "0.3.1",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",