@subshell-ai/plugin-oh-my-pi 0.3.0 → 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,4 +1,4 @@
-//#region ../../plugin-api/dist/types-DPLl6DHG.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
@@ -26,10 +26,79 @@ interface HarnessPreviews {
   /** 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
@@ -43,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
@@ -737,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-DgWWfiH-.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",
@@ -481,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);
@@ -511,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;
@@ -528,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
@@ -595,6 +683,8 @@ export default function (pi) {
 
   const reset = () => {
     agents.clear();
+    acknowledged = undefined;
+    declined = undefined;
     if (timer !== null) {
       clearTimeout(timer);
       timer = null;
@@ -609,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();
   });
 
@@ -638,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.3.0",
+	version: "0.3.1",
 	license: "Apache-2.0",
 	type: "module",
 	main: "dist/index.js",
@@ -913,13 +1004,16 @@ 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: () => [

package/package.json

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