@subshell-ai/plugin-codex 1.0.2 → 1.0.3

package/dist/index.d.ts

@@ -1,8 +1,104 @@
-//#region ../../plugin-api/dist/types-CW2dMAMW.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. */
@@ -397,6 +507,19 @@ interface SubshellPlugin {
    * used as-is, which is right for every harness that prints just a version.
    */
   parseVersion?(raw: string): string | null;
+  /**
+   * Turns the harness's own terminal title into the subshell name the rail
+   * shows.
+   *
+   * The host removes escape sequences and control bytes and trims the result
+   * before calling this, so `raw` is safe text. Interpret what the title adds
+   * around the session name — a brand, a run-state separator, a cycling
+   * status glyph — and return the name behind it. Return "" when the title
+   * names nothing, and the caller keeps the name the pane already had. Omit
+   * the member when the harness titles its pane with the name the host
+   * supplied, which needs no interpretation.
+   */
+  parsePaneTitle?(raw: string): string;
   /** Overrides manifest-driven detection. Almost no plugin needs this. */
   detect?(): Promise<DetectionResult>;
   /** Restart-resume support. Declare the `resume` capability with it. */
@@ -487,6 +610,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" */
@@ -630,6 +771,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).
    *

package/dist/index.js

@@ -1,4 +1,4 @@
-//#region ../../plugin-api/dist/manifest-XGvw0ugx.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",
@@ -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 } : {}
@@ -285,7 +299,7 @@ function validateGenericPreset(preset) {
 const parsed = parseManifest({
 	name: "@subshell-ai/plugin-codex",
 	description: "Codex harness plugin for Subshell",
-	version: "1.0.2",
+	version: "1.0.3",
 	license: "Apache-2.0",
 	type: "module",
 	main: "dist/index.js",
@@ -315,7 +329,7 @@ const parsed = parseManifest({
 		"@internal/tsconfig": "workspace:*",
 		"@subshell-ai/plugin-api": "workspace:*",
 		"@types/bun": "1.3.14",
-		"hash-runner": "4.0.0",
+		"hash-runner": "5.0.0",
 		"tsdown": "0.22.14",
 		"typescript": "7.0.2"
 	},
@@ -409,6 +423,166 @@ function tomlString(value) {
 function tomlStringArray(values) {
 	return `[${values.map(tomlString).join(", ")}]`;
 }
+const OVERLAY_MARKER = "Select an agent to watch.";
+const EMPTY_COMPOSER = "Ask Codex to do anything";
+/** ESC [ 1 ; 3 D — Codex's Alt+Left, which returns a subagent view to Main. */
+const ALT_LEFT = "\x1B[1;3D";
+/**
+* The text sitting in Codex's composer, if any. The placeholder is not input;
+* the overlay's numbered lines are not the composer either. Returning a
+* non-empty string means typing `/subagents` would append to a real prompt,
+* so the picker act refuses instead of clobbering it.
+*/
+function composerText(screen) {
+	const text = screen.split("\n").reverse().find((row) => /^\s*›\s*/.test(row))?.replace(/^\s*›\s*/, "").trim() ?? "";
+	return text === EMPTY_COMPOSER ? "" : text;
+}
+/** One keystroke batch's settle; Codex can fold an Enter sent in the same burst into the paste. */
+const COMMAND_SETTLE_MS = 120;
+/** Main's status line, not a transcript mention of it. */
+function isMainView(screen) {
+	const tail = screen.split("\n").filter((line) => line.trim() !== "").slice(-4).join(" ").replace(/\s+/g, " ");
+	return tail.includes("Main [default]") && !tail.includes("Viewing sub-agent");
+}
+/**
+* A real picker, not the marker text appearing in transcript history. The
+* footer and the first numbered row are what distinguish the overlay.
+*/
+function hasPicker(screen) {
+	const overlay = screen.lastIndexOf(OVERLAY_MARKER);
+	if (overlay === -1) return false;
+	const block = screen.slice(overlay);
+	const tail = screen.split("\n").filter((line) => line.trim() !== "").slice(-2).join(" ");
+	return /enter select\s*·\s*esc back/.test(tail) && block.includes("enter select") && /^\s*(?:›\s*)?1\.\s+•\s+/m.test(block);
+}
+async function typeCommand(pane, text) {
+	await pane.type(text);
+	if (await waitForScreen(pane, (screen) => composerText(screen) === text, 1500).catch(() => void 0).then(async (value) => value ?? (composerText(await pane.read()) === text ? "" : void 0)) === void 0) throw new Error("Codex didn't render the command in its composer.");
+	await pane.type("\r");
+}
+async function waitForScreen(pane, predicate, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	let screen = await pane.read();
+	while (!predicate(screen)) {
+		if (Date.now() >= deadline) throw new Error("Timed out waiting for Codex's agent picker.");
+		await new Promise((resolve) => setTimeout(resolve, 75));
+		screen = await pane.read();
+	}
+	return screen;
+}
+/** A closed picker must survive two consecutive reads; a half-painted frame doesn't. */
+async function waitForPickerClosed(pane, timeoutMs) {
+	const deadline = Date.now() + timeoutMs;
+	let previous;
+	while (Date.now() < deadline) {
+		const screen = await pane.read();
+		if (!hasPicker(screen) && previous !== void 0 && !hasPicker(previous)) return screen;
+		previous = screen;
+		await new Promise((resolve) => setTimeout(resolve, 75));
+	}
+	throw new Error("Timed out waiting for Codex's agent picker to close.");
+}
+/**
+* The picker's 1-based row for this id, read from the ids it prints. A narrow
+* pane wraps a long id onto the next line, so each numbered row is assembled
+* from its own lines before the id is matched. Reading the ids matters:
+* completed children stay listed in Codex's picker, so a roster position
+* would pick the wrong row as soon as a child finishes.
+*/
+const PICKER_ROW = /^\s*(?:›\s*)?(\d+)\.\s+•\s+(.*)$/;
+const HIGHLIGHTED_ROW = /^\s*›\s*(\d+)\.\s+•\s+(.*)$/;
+const PICKER_ID = /([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/i;
+function pickerLines(screen) {
+	const overlay = screen.lastIndexOf(OVERLAY_MARKER);
+	return overlay === -1 ? void 0 : screen.slice(overlay).split("\n");
+}
+/** A row plus up to three indented id fragments; labels and descriptions don't join. */
+function pickerRowText(lines, start, match) {
+	let text = match[2] ?? "";
+	for (let j = start + 1; j < Math.min(lines.length, start + 4); j++) {
+		const next = lines[j] ?? "";
+		if (!/^\s+[0-9a-f-]+\s*$/i.test(next)) break;
+		text += next;
+	}
+	return text;
+}
+function pickerRowId(text) {
+	return text.replace(/\s+/g, "").match(new RegExp(PICKER_ID.source, "ig"))?.at(-1);
+}
+function pickerIndex(screen, agentId) {
+	if (!hasPicker(screen)) return void 0;
+	const lines = pickerLines(screen) ?? [];
+	let expected = 1;
+	let main;
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i]?.match(PICKER_ROW);
+		if (!match) continue;
+		const index = Number(match[1]);
+		if (index !== expected) continue;
+		expected = index + 1;
+		const text = pickerRowText(lines, i, match);
+		if (agentId === null) {
+			if (/^\s*Main\s*\[default\]/.test(match[2] ?? "")) main = index;
+			continue;
+		}
+		if (pickerRowId(text)?.toLowerCase() === agentId.toLowerCase()) return index;
+	}
+	return agentId === null ? main : void 0;
+}
+/** The row Codex marks with `›` after a picker keypress, plus its printed id. */
+function highlightedPickerRow(screen) {
+	const lines = pickerLines(screen);
+	if (!lines) return void 0;
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i]?.match(HIGHLIGHTED_ROW);
+		if (match) return {
+			index: Number(match[1]),
+			text: pickerRowText(lines, i, match),
+			label: match[2] ?? ""
+		};
+	}
+}
+/**
+* Codex keeps its agent picker entirely inside the TUI. Read the pane, send
+* the picker's own keys, then read it back to confirm the view actually moved.
+* Completed children remain in the list, so the target is chosen by the id
+* printed on its row, never by the server roster's position.
+*/
+async function selectCodexSubagent(input) {
+	const { agentId, pane } = input;
+	const deadline = Date.now() + 2e4;
+	const wait = (ms) => Math.max(0, Math.min(ms, deadline - Date.now()));
+	let screen = await pane.read();
+	for (let i = 0; i < 64 && Date.now() < deadline && !hasPicker(screen) && !isMainView(screen); i++) {
+		await pane.type(ALT_LEFT);
+		await new Promise((resolve) => setTimeout(resolve, COMMAND_SETTLE_MS));
+		screen = await pane.read();
+	}
+	if (!hasPicker(screen) && !isMainView(screen)) throw new Error("Codex is showing a subagent and didn't return to Main.");
+	if (agentId === null && !hasPicker(screen) && isMainView(screen)) return { selectedId: null };
+	if (!hasPicker(screen)) {
+		if (composerText(screen)) throw new Error("Finish or clear the prompt before switching agents.");
+		await typeCommand(pane, "/subagents");
+		screen = await waitForScreen(pane, hasPicker, wait(3e3));
+	}
+	const index = pickerIndex(screen, agentId);
+	if (index === void 0) throw new Error("Codex didn't list that subagent in its picker.");
+	await pane.type(String(index));
+	screen = await waitForScreen(pane, (next) => !hasPicker(next) || highlightedPickerRow(next)?.index === index, wait(1500));
+	if (!hasPicker(screen)) {
+		screen = await waitForPickerClosed(pane, wait(1e3));
+		if (agentId === null ? !isMainView(screen) : isMainView(screen)) throw new Error("Codex didn't switch to the selected agent.");
+		return { selectedId: agentId };
+	}
+	const row = highlightedPickerRow(screen);
+	if (!row) throw new Error("Codex didn't highlight the selected row in its picker.");
+	const shownId = agentId === null ? null : pickerRowId(row.text) ?? null;
+	if (agentId === null ? !/^\s*Main\s*\[default\]/.test(row.label) : shownId?.toLowerCase() !== agentId.toLowerCase()) throw new Error("Codex highlighted a different row in its picker.");
+	await pane.type("\r");
+	screen = await waitForPickerClosed(pane, wait(3e3));
+	if (agentId === null ? !isMainView(screen) : isMainView(screen)) throw new Error("Codex didn't switch to the selected agent.");
+	return { selectedId: agentId };
+}
 /**
 * Built-in harness: Codex (OpenAI's `@openai/codex` CLI).
 *
@@ -448,8 +622,9 @@ function tomlStringArray(values) {
 const createPlugin = (host) => ({
 	subagents: {
 		discovery: "hooks",
-		navigation: "unavailable",
-		setup: "Review the Subshell subagent monitoring hooks in /hooks and trust them to show active subagents in the sidebar."
+		navigation: "native",
+		setup: "Review the Subshell subagent monitoring hooks in /hooks and trust them to show active subagents in the sidebar.",
+		select: selectCodexSubagent
 	},
 	capabilities: () => [
 		"subagents",
@@ -468,7 +643,8 @@ const createPlugin = (host) => ({
 			for (const event of [
 				"SubagentStart",
 				"SubagentStop",
-				"SessionStart"
+				"SessionStart",
+				"PostToolUse"
 			]) args.push("-c", `hooks.${event}=[{hooks=[{type="command",command=${JSON.stringify(command)},statusMessage="Subshell subagent monitoring",timeout=2}]}]`);
 		}
 		const s = preset.settings ?? {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@subshell-ai/plugin-codex",
   "description": "Codex harness plugin for Subshell",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
     "@internal/tsconfig": "workspace:*",
     "@subshell-ai/plugin-api": "workspace:*",
     "@types/bun": "1.3.14",
-    "hash-runner": "4.0.0",
+    "hash-runner": "5.0.0",
     "tsdown": "0.22.14",
     "typescript": "7.0.2"
   },