@subshell-ai/plugin-claude-code 3.1.2 → 3.1.3

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. */
@@ -500,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" */
@@ -643,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,5 +1,5 @@
 import { join, resolve } from "node:path";
-//#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",
@@ -159,6 +159,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" };
@@ -177,6 +190,7 @@ function parseManifest(pkgJson) {
 		entry: block.entry,
 		...detect ? { detect } : {},
 		...install ? { install } : {},
+		...update ? { update } : {},
 		...hostEnv ? { hostEnv } : {},
 		...parsedNetwork ? { network: parsedNetwork } : {},
 		...block.pickable === false ? { pickable: false } : {}
@@ -286,7 +300,7 @@ function validateGenericPreset(preset) {
 const parsed = parseManifest({
 	name: "@subshell-ai/plugin-claude-code",
 	description: "Claude Code harness plugin for Subshell",
-	version: "3.1.2",
+	version: "3.1.3",
 	license: "Apache-2.0",
 	type: "module",
 	main: "dist/index.js",
@@ -652,6 +666,68 @@ function projectSlug(cwd) {
 * the name it already had.
 */
 const STATUS_GLYPH = /^[^\p{L}\p{N}]+/u;
+const DOWN = "\x1B[B";
+const UP = "\x1B[A";
+const ENTER = "\r";
+const ESC = "\x1B";
+const CLAUDE_SELECT_MARK = "[>❯]";
+const CLAUDE_STATUS_GLYPH = "[●◉◯○◦•]";
+const CLAUDE_AGENT_ROW = new RegExp(`^\\s*(${CLAUDE_SELECT_MARK})?\\s*(${CLAUDE_STATUS_GLYPH})?\\s*([^\\s·]+)(?:\\s+·\\s+|\\s{2,})`);
+const CLAUDE_MAIN_ROW = new RegExp(`^\\s*(${CLAUDE_SELECT_MARK})?\\s*(${CLAUDE_STATUS_GLYPH})?\\s*main(?:\\s{2,}.*)?\\s*$`);
+function claudePanelRows(screen) {
+	const lines = screen.split("\n");
+	const prompt = lines.findLastIndex((line) => /^\s*❯\s+(?![●◉◯○◦•])/.test(line));
+	return (prompt < 0 ? lines : lines.slice(prompt + 1)).map((line) => {
+		const main = line.match(CLAUDE_MAIN_ROW);
+		if (main) return {
+			name: "main",
+			selected: main[1] === ">" || main[1] === "❯"
+		};
+		const agent = line.match(CLAUDE_AGENT_ROW);
+		return agent ? {
+			name: (agent[3] ?? "").trim(),
+			selected: agent[1] === ">" || agent[1] === "❯"
+		} : void 0;
+	}).filter((row) => row !== void 0 && (row.name === "main" || /^[\p{L}\p{N}_.-]+$/u.test(row.name)));
+}
+async function selectClaudeSubagent(input) {
+	const { agentId, agents, pane } = input;
+	let screen = await pane.read();
+	let rows = claudePanelRows(screen);
+	if (agentId === null) {
+		if (rows.some((row) => row.selected && row.name === "main")) return { selectedId: null };
+		if (!rows.length) {
+			if (!(/main\s*>\s*\S/.test(screen) || agents.some((agent) => screen.includes(agent.name)))) throw new Error("Claude isn't showing an agent view to return from.");
+			await pane.type(ESC);
+			screen = await pane.read();
+			rows = claudePanelRows(screen);
+		}
+		if (!rows.length) throw new Error("Claude isn't showing its agent panel.");
+		if (!rows.some((row) => row.selected)) return { selectedId: null };
+		for (let step = 0; step < rows.length + 2; step++) {
+			if (claudePanelRows(await pane.read()).findIndex((row) => row.selected) === 0) break;
+			await pane.type(UP);
+		}
+		if (!claudePanelRows(await pane.read()).some((row) => row.selected && row.name === "main")) throw new Error("Claude didn't select the main agent in its agent panel.");
+		await pane.type(ENTER);
+		return { selectedId: null };
+	}
+	const target = agents.find((agent) => agent.id === agentId);
+	if (!target) throw new Error("Claude didn't report that subagent.");
+	if (!rows.length) throw new Error("Claude isn't showing its agent panel.");
+	const targetName = target.name.trim();
+	const ordinal = agents.filter((agent) => agent.name.trim() === targetName).findIndex((agent) => agent.id === agentId);
+	const targetRow = rows.flatMap((row, index) => row.name === targetName ? [index] : [])[ordinal] ?? -1;
+	if (targetRow < 0) throw new Error("Claude didn't list that subagent in its agent panel.");
+	for (let step = 0; step < rows.length + 2; step++) {
+		const current = claudePanelRows(await pane.read()).findIndex((row) => row.selected);
+		if (current === targetRow) break;
+		await pane.type(current < 0 || current < targetRow ? DOWN : UP);
+	}
+	if (!claudePanelRows(await pane.read())[targetRow]?.selected) throw new Error("Claude didn't select that subagent in its agent panel.");
+	await pane.type(ENTER);
+	return { selectedId: agentId };
+}
 /**
 * Built-in harness: Claude Code.
 *
@@ -672,7 +748,8 @@ const STATUS_GLYPH = /^[^\p{L}\p{N}]+/u;
 const createPlugin = (host) => ({
 	subagents: {
 		discovery: "hooks",
-		navigation: "unavailable"
+		navigation: "native",
+		select: selectClaudeSubagent
 	},
 	capabilities: () => [
 		"subagents",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@subshell-ai/plugin-claude-code",
   "description": "Claude Code harness plugin for Subshell",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",