pi-improve-interation 0.0.1

package/node_modules/yaml/dist/visit.js

@@ -0,0 +1,236 @@
+'use strict';
+
+var identity = require('./nodes/identity.js');
+
+const BREAK = Symbol('break visit');
+const SKIP = Symbol('skip children');
+const REMOVE = Symbol('remove node');
+/**
+ * Apply a visitor to an AST node or document.
+ *
+ * Walks through the tree (depth-first) starting from `node`, calling a
+ * `visitor` function with three arguments:
+ *   - `key`: For sequence values and map `Pair`, the node's index in the
+ *     collection. Within a `Pair`, `'key'` or `'value'`, correspondingly.
+ *     `null` for the root node.
+ *   - `node`: The current node.
+ *   - `path`: The ancestry of the current node.
+ *
+ * The return value of the visitor may be used to control the traversal:
+ *   - `undefined` (default): Do nothing and continue
+ *   - `visit.SKIP`: Do not visit the children of this node, continue with next
+ *     sibling
+ *   - `visit.BREAK`: Terminate traversal completely
+ *   - `visit.REMOVE`: Remove the current node, then continue with the next one
+ *   - `Node`: Replace the current node, then continue by visiting it
+ *   - `number`: While iterating the items of a sequence or map, set the index
+ *     of the next step. This is useful especially if the index of the current
+ *     node has changed.
+ *
+ * If `visitor` is a single function, it will be called with all values
+ * encountered in the tree, including e.g. `null` values. Alternatively,
+ * separate visitor functions may be defined for each `Map`, `Pair`, `Seq`,
+ * `Alias` and `Scalar` node. To define the same visitor function for more than
+ * one node type, use the `Collection` (map and seq), `Value` (map, seq & scalar)
+ * and `Node` (alias, map, seq & scalar) targets. Of all these, only the most
+ * specific defined one will be used for each node.
+ */
+function visit(node, visitor) {
+    const visitor_ = initVisitor(visitor);
+    if (identity.isDocument(node)) {
+        const cd = visit_(null, node.contents, visitor_, Object.freeze([node]));
+        if (cd === REMOVE)
+            node.contents = null;
+    }
+    else
+        visit_(null, node, visitor_, Object.freeze([]));
+}
+// Without the `as symbol` casts, TS declares these in the `visit`
+// namespace using `var`, but then complains about that because
+// `unique symbol` must be `const`.
+/** Terminate visit traversal completely */
+visit.BREAK = BREAK;
+/** Do not visit the children of the current node */
+visit.SKIP = SKIP;
+/** Remove the current node */
+visit.REMOVE = REMOVE;
+function visit_(key, node, visitor, path) {
+    const ctrl = callVisitor(key, node, visitor, path);
+    if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
+        replaceNode(key, path, ctrl);
+        return visit_(key, ctrl, visitor, path);
+    }
+    if (typeof ctrl !== 'symbol') {
+        if (identity.isCollection(node)) {
+            path = Object.freeze(path.concat(node));
+            for (let i = 0; i < node.items.length; ++i) {
+                const ci = visit_(i, node.items[i], visitor, path);
+                if (typeof ci === 'number')
+                    i = ci - 1;
+                else if (ci === BREAK)
+                    return BREAK;
+                else if (ci === REMOVE) {
+                    node.items.splice(i, 1);
+                    i -= 1;
+                }
+            }
+        }
+        else if (identity.isPair(node)) {
+            path = Object.freeze(path.concat(node));
+            const ck = visit_('key', node.key, visitor, path);
+            if (ck === BREAK)
+                return BREAK;
+            else if (ck === REMOVE)
+                node.key = null;
+            const cv = visit_('value', node.value, visitor, path);
+            if (cv === BREAK)
+                return BREAK;
+            else if (cv === REMOVE)
+                node.value = null;
+        }
+    }
+    return ctrl;
+}
+/**
+ * Apply an async visitor to an AST node or document.
+ *
+ * Walks through the tree (depth-first) starting from `node`, calling a
+ * `visitor` function with three arguments:
+ *   - `key`: For sequence values and map `Pair`, the node's index in the
+ *     collection. Within a `Pair`, `'key'` or `'value'`, correspondingly.
+ *     `null` for the root node.
+ *   - `node`: The current node.
+ *   - `path`: The ancestry of the current node.
+ *
+ * The return value of the visitor may be used to control the traversal:
+ *   - `Promise`: Must resolve to one of the following values
+ *   - `undefined` (default): Do nothing and continue
+ *   - `visit.SKIP`: Do not visit the children of this node, continue with next
+ *     sibling
+ *   - `visit.BREAK`: Terminate traversal completely
+ *   - `visit.REMOVE`: Remove the current node, then continue with the next one
+ *   - `Node`: Replace the current node, then continue by visiting it
+ *   - `number`: While iterating the items of a sequence or map, set the index
+ *     of the next step. This is useful especially if the index of the current
+ *     node has changed.
+ *
+ * If `visitor` is a single function, it will be called with all values
+ * encountered in the tree, including e.g. `null` values. Alternatively,
+ * separate visitor functions may be defined for each `Map`, `Pair`, `Seq`,
+ * `Alias` and `Scalar` node. To define the same visitor function for more than
+ * one node type, use the `Collection` (map and seq), `Value` (map, seq & scalar)
+ * and `Node` (alias, map, seq & scalar) targets. Of all these, only the most
+ * specific defined one will be used for each node.
+ */
+async function visitAsync(node, visitor) {
+    const visitor_ = initVisitor(visitor);
+    if (identity.isDocument(node)) {
+        const cd = await visitAsync_(null, node.contents, visitor_, Object.freeze([node]));
+        if (cd === REMOVE)
+            node.contents = null;
+    }
+    else
+        await visitAsync_(null, node, visitor_, Object.freeze([]));
+}
+// Without the `as symbol` casts, TS declares these in the `visit`
+// namespace using `var`, but then complains about that because
+// `unique symbol` must be `const`.
+/** Terminate visit traversal completely */
+visitAsync.BREAK = BREAK;
+/** Do not visit the children of the current node */
+visitAsync.SKIP = SKIP;
+/** Remove the current node */
+visitAsync.REMOVE = REMOVE;
+async function visitAsync_(key, node, visitor, path) {
+    const ctrl = await callVisitor(key, node, visitor, path);
+    if (identity.isNode(ctrl) || identity.isPair(ctrl)) {
+        replaceNode(key, path, ctrl);
+        return visitAsync_(key, ctrl, visitor, path);
+    }
+    if (typeof ctrl !== 'symbol') {
+        if (identity.isCollection(node)) {
+            path = Object.freeze(path.concat(node));
+            for (let i = 0; i < node.items.length; ++i) {
+                const ci = await visitAsync_(i, node.items[i], visitor, path);
+                if (typeof ci === 'number')
+                    i = ci - 1;
+                else if (ci === BREAK)
+                    return BREAK;
+                else if (ci === REMOVE) {
+                    node.items.splice(i, 1);
+                    i -= 1;
+                }
+            }
+        }
+        else if (identity.isPair(node)) {
+            path = Object.freeze(path.concat(node));
+            const ck = await visitAsync_('key', node.key, visitor, path);
+            if (ck === BREAK)
+                return BREAK;
+            else if (ck === REMOVE)
+                node.key = null;
+            const cv = await visitAsync_('value', node.value, visitor, path);
+            if (cv === BREAK)
+                return BREAK;
+            else if (cv === REMOVE)
+                node.value = null;
+        }
+    }
+    return ctrl;
+}
+function initVisitor(visitor) {
+    if (typeof visitor === 'object' &&
+        (visitor.Collection || visitor.Node || visitor.Value)) {
+        return Object.assign({
+            Alias: visitor.Node,
+            Map: visitor.Node,
+            Scalar: visitor.Node,
+            Seq: visitor.Node
+        }, visitor.Value && {
+            Map: visitor.Value,
+            Scalar: visitor.Value,
+            Seq: visitor.Value
+        }, visitor.Collection && {
+            Map: visitor.Collection,
+            Seq: visitor.Collection
+        }, visitor);
+    }
+    return visitor;
+}
+function callVisitor(key, node, visitor, path) {
+    if (typeof visitor === 'function')
+        return visitor(key, node, path);
+    if (identity.isMap(node))
+        return visitor.Map?.(key, node, path);
+    if (identity.isSeq(node))
+        return visitor.Seq?.(key, node, path);
+    if (identity.isPair(node))
+        return visitor.Pair?.(key, node, path);
+    if (identity.isScalar(node))
+        return visitor.Scalar?.(key, node, path);
+    if (identity.isAlias(node))
+        return visitor.Alias?.(key, node, path);
+    return undefined;
+}
+function replaceNode(key, path, node) {
+    const parent = path[path.length - 1];
+    if (identity.isCollection(parent)) {
+        parent.items[key] = node;
+    }
+    else if (identity.isPair(parent)) {
+        if (key === 'key')
+            parent.key = node;
+        else
+            parent.value = node;
+    }
+    else if (identity.isDocument(parent)) {
+        parent.contents = node;
+    }
+    else {
+        const pt = identity.isAlias(parent) ? 'alias' : 'scalar';
+        throw new Error(`Cannot replace node with ${pt} parent`);
+    }
+}
+
+exports.visit = visit;
+exports.visitAsync = visitAsync;

package/node_modules/yaml/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "yaml",
+  "version": "2.8.3",
+  "license": "ISC",
+  "author": "Eemeli Aro <eemeli@gmail.com>",
+  "funding": "https://github.com/sponsors/eemeli",
+  "repository": "github:eemeli/yaml",
+  "description": "JavaScript parser and stringifier for YAML",
+  "keywords": [
+    "YAML",
+    "parser",
+    "stringifier"
+  ],
+  "homepage": "https://eemeli.org/yaml/",
+  "files": [
+    "browser/",
+    "dist/",
+    "util.js"
+  ],
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "bin": "./bin.mjs",
+  "browser": {
+    "./dist/index.js": "./browser/index.js",
+    "./dist/util.js": "./browser/dist/util.js",
+    "./util.js": "./browser/dist/util.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/index.js",
+      "default": "./browser/index.js"
+    },
+    "./package.json": "./package.json",
+    "./util": {
+      "types": "./dist/util.d.ts",
+      "node": "./dist/util.js",
+      "default": "./browser/dist/util.js"
+    }
+  },
+  "scripts": {
+    "build": "npm run build:node && npm run build:browser",
+    "build:browser": "rollup -c config/rollup.browser-config.mjs",
+    "build:node": "rollup -c config/rollup.node-config.mjs",
+    "clean": "git clean -fdxe node_modules",
+    "lint": "eslint config/ src/",
+    "prettier": "prettier --write .",
+    "prestart": "rollup --sourcemap -c config/rollup.node-config.mjs",
+    "start": "node --enable-source-maps -i -e 'YAML=require(\"./dist/index.js\");const{parse,parseDocument,parseAllDocuments}=YAML'",
+    "test": "jest --config config/jest.config.js",
+    "test:all": "npm test && npm run test:types && npm run test:dist && npm run test:dist:types",
+    "test:browsers": "cd playground && npm test",
+    "test:dist": "npm run build:node && jest --config config/jest.config.js",
+    "test:dist:types": "tsc --allowJs --moduleResolution node --noEmit --target es5 dist/index.js",
+    "test:types": "tsc --noEmit && tsc --noEmit -p tests/tsconfig.json",
+    "docs:install": "cd docs-slate && bundle install",
+    "predocs:deploy": "node docs/prepare-docs.mjs",
+    "docs:deploy": "cd docs-slate && ./deploy.sh",
+    "predocs": "node docs/prepare-docs.mjs",
+    "docs": "cd docs-slate && bundle exec middleman server",
+    "preversion": "npm test && npm run build",
+    "prepublishOnly": "npm run clean && npm test && npm run build"
+  },
+  "browserslist": "defaults, not ie 11",
+  "prettier": {
+    "arrowParens": "avoid",
+    "semi": false,
+    "singleQuote": true,
+    "trailingComma": "none"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.12.10",
+    "@babel/plugin-transform-typescript": "^7.12.17",
+    "@babel/preset-env": "^7.12.11",
+    "@eslint/js": "^9.9.1",
+    "@rollup/plugin-babel": "^6.0.3",
+    "@rollup/plugin-replace": "^6.0.3",
+    "@rollup/plugin-typescript": "^12.1.1",
+    "@types/jest": "^29.2.4",
+    "@types/node": "^20.11.20",
+    "babel-jest": "^29.0.1",
+    "eslint": "^9.9.1",
+    "eslint-config-prettier": "^10.1.8",
+    "fast-check": "^2.12.0",
+    "jest": "^29.0.1",
+    "jest-resolve": "^29.7.0",
+    "jest-ts-webcompat-resolver": "^1.0.0",
+    "prettier": "^3.0.2",
+    "rollup": "^4.12.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.4.0"
+  },
+  "engines": {
+    "node": ">= 14.6"
+  }
+}

package/node_modules/yaml/util.js

@@ -0,0 +1,2 @@
+// Re-exporter for Node.js < 12.16.0
+module.exports = require('./dist/util.js')

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "pi-improve-interation",
+  "version": "0.0.1",
+  "description": "Companion enhancement layer over pi-subagents (and future open-source pi packages) — adapter framework for orchestration add-ons, no fork required",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ai-feier",
+  "homepage": "https://github.com/Ai-feier/pi-improve-interation#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ai-feier/pi-improve-interation.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-subagents",
+    "subagents",
+    "orchestration",
+    "agents"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"test/*.test.ts\"",
+    "test:watch": "node --test --watch \"test/*.test.ts\""
+  },
+  "dependencies": {
+    "pi-subagents": "^0.62.0"
+  },
+  "bundledDependencies": [
+    "pi-subagents"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "^0.84.4",
+    "@types/node": "^24",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "test",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "bundleDependencies": [
+    "pi-subagents"
+  ]
+}

package/src/adapters/index.ts

@@ -0,0 +1,13 @@
+import type { PluginAdapter } from "./types.ts";
+import { piSubagentsAdapter } from "./pi-subagents/index.ts";
+
+/**
+ * Adapter registry. Adding a new enhanced host package:
+ * 1. create src/adapters/<host-id>/index.ts implementing PluginAdapter
+ * 2. append it here
+ */
+export const adapters: readonly PluginAdapter[] = [piSubagentsAdapter];
+
+export function getAdapter(id: string): PluginAdapter | undefined {
+ return adapters.find((adapter) => adapter.id === id);
+}

package/src/adapters/pi-subagents/agents.ts

@@ -0,0 +1,136 @@
+import { createRequire } from "node:module";
+import { readdir, readFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Agent discovery for the /agent:* palette (pi-subagents adapter).
+ *
+ * Sources, in override order (later wins on name collision, mirroring
+ * pi-subagents' mergeRuntimeAgents semantics):
+ *   1. builtin — *.md in the installed pi-subagents package agents/ dir
+ *   2. custom  — ~/.pi/agent/agents and <project>/.pi/agents *.md files
+ *   3. runtime — names collected from pi-subagents' runtime registration events
+ */
+export interface AgentEntry {
+	name: string;
+	source: "builtin" | "custom" | "runtime";
+	/** Frontmatter description from the agent's md file, when present. */
+	description?: string;
+}
+
+/** Core builtins, used when the installed package's agents/ dir cannot be read. */
+const CORE_BUILTIN_AGENTS = [
+	"delegate",
+	"oracle",
+	"researcher",
+	"reviewer",
+	"scout",
+	"worker",
+] as const;
+
+/**
+ * Minimal frontmatter parsing: single-line `key: value` pairs between `---`
+ * fences. Block scalars (YAML `>-`) are not expanded — agent frontmatter in
+ * practice uses single-line names and descriptions.
+ */
+function parseFrontmatter(content: string): Record<string, string> {
+	const fence = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
+	if (!fence?.[1]) {
+		return {};
+	}
+	const fields: Record<string, string> = {};
+	for (const line of fence[1].split(/\r?\n/)) {
+		const pair = /^(\w[\w-]*):\s*(.*)$/.exec(line.trim());
+		const key = pair?.[1];
+		const value = pair?.[2];
+		if (!key || value === undefined) {
+			continue;
+		}
+		fields[key] = value.replace(/^['"]|['"]$/g, "").trim();
+	}
+	return fields;
+}
+
+/**
+ * Scan an agents directory; every *.md file is one agent. Name and description
+ * come from frontmatter when present, falling back to the file stem.
+ */
+export async function scanAgentsDir(
+	dir: string,
+	source: AgentEntry["source"],
+): Promise<AgentEntry[]> {
+	let files: string[];
+	try {
+		files = (await readdir(dir)).filter((file) => file.endsWith(".md"));
+	} catch {
+		return [];
+	}
+	const entries = await Promise.all(
+		files.map(async (file) => {
+			const stem = basename(file, ".md");
+			try {
+				const frontmatter = parseFrontmatter(
+					await readFile(join(dir, file), "utf8"),
+				);
+				return {
+					name: frontmatter.name || stem,
+					source,
+					description: frontmatter.description || undefined,
+				};
+			} catch {
+				return { name: stem, source };
+			}
+		}),
+	);
+	return entries;
+}
+
+/** Builtins from the bundled pi-subagents package; falls back to the core six. */
+export async function listBuiltinAgents(): Promise<AgentEntry[]> {
+	const fallback = (): AgentEntry[] =>
+		CORE_BUILTIN_AGENTS.map((name) => ({ name, source: "builtin" }));
+	try {
+		// "." export resolves to the package root's index.ts; resolve() only
+		// computes the path, it never executes the .ts entry.
+		const entryPath = createRequire(import.meta.url).resolve("pi-subagents");
+		const agents = await scanAgentsDir(
+			join(dirname(entryPath), "agents"),
+			"builtin",
+		);
+		return agents.length > 0 ? agents : fallback();
+	} catch {
+		return fallback();
+	}
+}
+
+/** Custom agents: ~/.pi/agent/agents (global) and <projectCwd>/.pi/agents (project). */
+export async function listCustomAgents(
+	projectCwd: string,
+): Promise<AgentEntry[]> {
+	const [globalAgents, projectAgents] = await Promise.all([
+		scanAgentsDir(join(homedir(), ".pi", "agent", "agents"), "custom"),
+		scanAgentsDir(join(projectCwd, ".pi", "agents"), "custom"),
+	]);
+	return [...projectAgents, ...globalAgents];
+}
+
+/**
+ * Merge agent groups by name; each group overrides same-named entries from
+ * earlier groups. An entry without a description inherits the one it overrides.
+ */
+export function mergeAgentEntries(...groups: AgentEntry[][]): AgentEntry[] {
+	const byName = new Map<string, AgentEntry>();
+	for (const group of groups) {
+		for (const entry of group) {
+			const existing = byName.get(entry.name);
+			const merged: AgentEntry = { ...existing, ...entry };
+			const description = entry.description ?? existing?.description;
+			if (description !== undefined) {
+				merged.description = description;
+			}
+			byName.set(entry.name, merged);
+		}
+	}
+	return [...byName.values()];
+}

package/src/adapters/pi-subagents/autocomplete.ts

@@ -0,0 +1,46 @@
+import type {
+	AutocompleteItem,
+	AutocompleteProvider,
+} from "@earendil-works/pi-tui";
+import type { AgentEntry } from "./agents.ts";
+
+/** A mention like "@rev" at a token boundary in the composer. */
+const AGENT_MENTION_PATTERN = /(?:^|[ \t])@([^\s@]*)$/;
+
+/**
+ * "@" autocomplete for agents, layered on top of pi's built-in provider.
+ *
+ * - `@<query>` lists agents whose name starts with the query
+ * - `@` alone (or no agent match) falls back to the built-in file/path
+ *   completion so normal "@" file mentions keep working
+ */
+export function createAgentAutocompleteProvider(
+	current: AutocompleteProvider,
+	getAgents: () => Promise<AgentEntry[]>,
+): AutocompleteProvider {
+	return {
+		triggerCharacters: ["@"],
+		async getSuggestions(lines, cursorLine, cursorCol, options) {
+			const beforeCursor = (lines[cursorLine] ?? "").slice(0, cursorCol);
+			const query = AGENT_MENTION_PATTERN.exec(beforeCursor)?.[1];
+			if (query === undefined || query.length === 0) {
+				return current.getSuggestions(lines, cursorLine, cursorCol, options);
+			}
+			const agents = (await getAgents()).filter((agent) =>
+				agent.name.toLowerCase().startsWith(query.toLowerCase()),
+			);
+			if (agents.length === 0) {
+				return current.getSuggestions(lines, cursorLine, cursorCol, options);
+			}
+			const items: AutocompleteItem[] = agents.map((agent) => ({
+				value: `@agent:${agent.name}`,
+				label: `@agent:${agent.name}`,
+				description: agent.description ?? `${agent.source} agent`,
+			}));
+			return { prefix: `@${query}`, items };
+		},
+		applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+			return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+		},
+	};
+}

package/src/adapters/pi-subagents/index.ts

@@ -0,0 +1,48 @@
+import type { AdapterProbeResult, PluginAdapter } from "../types.ts";
+
+/**
+ * Adapter over pi-subagents (npm: pi-subagents, MIT, nicobailon/pi-subagents).
+ *
+ * Verified integration surface (pi-subagents 0.62.0), all imports lazy so this
+ * extension still loads when the host package is absent:
+ *
+ * - Delegation event transport (extension-to-extension over the pi event bus):
+ *   `SUBAGENT_DELEGATION_REQUEST_EVENT` = "prompt-template:subagent:request",
+ *   plus started/update/response/cancel events. See pi-subagents/delegation.
+ * - Runtime agent registration: `registerAgent` via pi-subagents/agents.
+ * - Shared types: pi-subagents/shared-types.
+ */
+const PI_SUBAGENTS_EXPECTED_REQUEST_EVENT = "prompt-template:subagent:request";
+
+export const piSubagentsAdapter: PluginAdapter = {
+	id: "pi-subagents",
+	packageName: "pi-subagents",
+
+	async probe(): Promise<AdapterProbeResult> {
+		let delegation: typeof import("pi-subagents/delegation");
+		try {
+			delegation = await import("pi-subagents/delegation");
+		} catch (err) {
+			return {
+				ok: false,
+				detail: `pi-subagents is not resolvable from this package (${(err as Error).message}). Fix: run \`pi install npm:pi-subagents\` and \`npm install\` in this package.`,
+			};
+		}
+
+		if (
+			delegation.SUBAGENT_DELEGATION_REQUEST_EVENT !==
+			PI_SUBAGENTS_EXPECTED_REQUEST_EVENT
+		) {
+			return {
+				ok: false,
+				detail: `delegation event constant drifted: expected "${PI_SUBAGENTS_EXPECTED_REQUEST_EVENT}", got "${String(delegation.SUBAGENT_DELEGATION_REQUEST_EVENT)}". Check the installed pi-subagents version against this adapter.`,
+			};
+		}
+
+		return {
+			ok: true,
+			detail:
+				"delegation event transport resolved; extension-to-extension delegation available",
+		};
+	},
+};

package/src/adapters/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Adapter contract: one adapter per enhanced open-source pi package.
+ *
+ * An adapter encapsulates everything specific to the host package —
+ * how to probe it, which API surface it exposes, how versions drift —
+ * so enhancement features stay host-agnostic.
+ */
+export interface PluginAdapter {
+	/** Stable adapter id, e.g. "pi-subagents". */
+	id: string;
+	/** npm package this adapter enhances, e.g. "pi-subagents". */
+	packageName: string;
+	/**
+	 * Minimal integration probe. Never throws — returns diagnostics so
+	 * /plus-doctor can render them.
+	 */
+	probe(): Promise<AdapterProbeResult>;
+}
+
+export interface AdapterProbeResult {
+	ok: boolean;
+	/** Host package version, when the host exposes it. */
+	version?: string;
+	detail: string;
+}