pi-subagents 0.69.0 → 0.70.0

package/src/extension/tool-description.ts

@@ -1,175 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { ExtensionConfig, ToolDescriptionMode } from "../shared/types.ts";
-import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
-
-const CUSTOM_TOOL_DESCRIPTION_FILE = "subagent-tool-description.md";
-const CUSTOM_TOOL_DESCRIPTION_MAX_BYTES = 50 * 1024;
-const AGENT_SELECTION_GUIDANCE = 'First call {action:"list",capabilities:true}: executable, non-disabled agents only; external-cli requires runner.available === true. Passive PATH/PATHEXT/X_OK is not authentication/version/launch proof; preflight is authoritative.';
-const SUBAGENT_FAILURE_RECOVERY_GUIDANCE = "Workflow, child launch, prompt runtime, extension load or child tooling failure is a lane infrastructure blocker. Stop; report exact failure, run/status and repo/cwd/worktree/branch/ref; verify clean worktree or capture partial diff before same-protocol retry or asking the owner. Never silently switch to interactive_shell, pi -ne, Codex/Claude/Cursor CLI or foreground/external mode: governed-workflow fallback requires explicit owner approval, not Pi core's generic pi -ne hint. Explicit foreground/CLI requests and work outside that protocol remain valid.";
-
-export const SUBAGENT_SAFETY_GUIDANCE = `SAFETY-CRITICAL SUBAGENT GUIDANCE:
-• Direct parent execution is the default. Invoke subagents only when delegation is authorized by the operator's current request or applicable user/project instructions; task size, complexity, risk, tool-call count, or recipe fit do not independently authorize delegation.
-• ${AGENT_SELECTION_GUIDANCE}
-• ${SUBAGENT_FAILURE_RECOVERY_GUIDANCE}
-• Omit action for execution. For an authorized delegated multi-step/parallel workflow: exactly one top-level subagent workflow call with async:true; children launch only inside it.
-• Async follows asyncByDefault (normally true); async:false only to block the parent, not for final reviews/gates. Consume results at dependency barriers. Native async completion wakes this session: return control, no sleep/poll or bg_wait merely for a wake. bg_wait is for provider/detached work without native notification needing a same-turn result.
-• Ordinary child subagents are not orchestrators; only configured fanout within depth/session limits. For an authorized delegated workflow, keep one writer per cwd/worktree and isolate concurrent writers. Use fresh-context read-only reviewers when independent review was requested, then parent synthesis/fixes. Oracle/advisor unknowns use supervisor dialogue; one-shot only when requested.
-• Bind durable output on runs.run/runs.all, not task filename prose; return actual outputReference/outputPathMapping/artifactPaths, evidence and residual risks.
-• children.list: resume only resumable rows. {action:"resume",id,message} detaches a follow-up/challenge with stored agent/model/tool contract. If none is resumable, label a same-role fallback challenge. Scripts await runs.run(newKey,{resume:runId,task}); continue from latest returned runId. Each distinct resume pass needs a new stable key; same-key reuse requires identical launch parameters.
-• Named resources own authority; raw workflowScript/workflowScriptPath cannot use runs.host. Granted commands/relative outputs use workflow cwd, never per-step cwd.
-• Inspect asyncId/asyncDir (status.json, events.jsonl, logs) with status/debug.run; control with interrupt/stop/resume/steer. Read {action:"guide",topic:"tool-reference"} for controls/evidence gates.`;
-
-const EXECUTION_GUIDANCE = `Delegate one child with {agent,task?}; otherwise choose exactly one of {workflowScript,args?}, {workflowScriptPath,args?} or {workflow,args}. agent/task exclude workflow inputs; task excludes action. agent may target management actions. action is management/control; validate accepts either script without launching. workflowScriptPath loads from request cwd before sandbox execution.
-Scripts: JavaScript statement bodies with explicit return, top-level await, plain helpers/Promise chains; nested async function/arrow/method helpers are rejected. Await runs.run('key',{agent,task}) before .output; await runs.all([{key,agent,task},...]) for an ordered array, not a key map. Observe every stored run promise with direct await, Promise.race or Promise.all. Await/return runs.steer(key,message,options?) for a prior key, never raw run ids; queued/delivered/missed/failed receipts are not compliance proof.
-Before advanced orchestration (runs.lanes, rolling fanout, mission state, handoffs), read {action:"guide",topic:"workflows"} or the pi-subagents skill. Raw-script sandboxes add deeply frozen args; all sandboxes provide runs, emit, console, JavaScript and enabled mission state, with no filesystem/shell/Pi tools/host globals. External CLI agents support native options only when their runner declares them; read guide tool-reference before passing model, structured output, acceptance/agentContract, tool budget, fast, fork context or skills/tools.
-Model override: first call {action:"models"}; copy exact provider/id, not agent names. Thinking uses model suffix, not watchdog-only thinking.
-Named resources: {workflow:'review',args:{task:'...'}} or {workflow:'run-ci',args:{command:'npm test'}}. Raw scripts also accept bounded plain-data args; raw-script args persist as evidence, so never include secrets. worktree:true requires clean source; baseRef defaults to HEAD at allocation or a supported named ref, never full 40/64-character commit IDs or revision expressions.`;
-
-export const DEFAULT_SUBAGENT_TOOL_DESCRIPTION = `${EXECUTION_GUIDANCE}\n\n${SUBAGENT_SAFETY_GUIDANCE}`;
-
-export const SUBAGENT_TOOL_PROMPT_SNIPPET = "For operator-requested delegation, use subagents; compose multi-child work in one workflow call.";
-export const SUBAGENT_TOOL_PROMPT_GUIDELINES = [
-	"Do not invoke subagents unless the operator requested delegation directly or through applicable instructions.",
-];
-
-export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = DEFAULT_SUBAGENT_TOOL_DESCRIPTION;
-
-export const FULL_SUBAGENT_TOOL_DESCRIPTION = `${DEFAULT_SUBAGENT_TOOL_DESCRIPTION}
-
-WORKFLOW DETAILS:
-• runs.lanes([{key,stages:[{key,agent,task},{key,resume:'previous',task}]}]) runs first stages together, later stages sequentially per lane. Failures stay lane-local; only explicit structuredOutput.verdict === 'blocked' blocks a successful stage, never reviewer prose.
-• Workflow child controls default onto runs.run/runs.all items; child fields override them. worktree:true isolates each child and returns handoff artifacts. usageBudget is shared across the workflow; already-running children are not stopped.
-• Missions auto-attach unless mission:false; await state.get(key)/state.set(key,JSONValue) requires a mission. See guide topic missions. Omit acceptance for reviewer/read-only calls; acceptance.review.required requests independent writer review.
-• Management discovery: list/get/models/guide; create/update/delete/eject/disable/enable/reset/refine; mission.*, schedule.*, watchdog.*, inspector.*, project.*, lane.status/recordMerge/recordSupersession; worktree.discard and plan-only worktree.cleanup; doctor and grant-spawn-budget. Use guide topics agents, missions, observability, tool-reference, configuration, models, watchdog or extension-api for exact action fields. Schedules take script inputs, not direct children; recipes live in the missions guide.`;
-
-function isToolDescriptionMode(value: unknown): value is ToolDescriptionMode {
-	return value === "full" || value === "compact" || value === "custom";
-}
-
-function warn(options: ToolDescriptionOptions | undefined, message: string): void {
-	(options?.warn ?? console.warn)(`[pi-subagents] ${message}`);
-}
-
-export interface ToolDescriptionOptions {
-	cwd?: string;
-	agentDir?: string;
-	warn?: (message: string) => void;
-}
-
-export interface SubagentToolPromptMetadata {
-	promptSnippet?: string;
-	promptGuidelines?: string[];
-}
-
-export function buildSubagentToolPromptMetadata(config: Pick<ExtensionConfig, "toolDescriptionMode"> = {}): SubagentToolPromptMetadata {
-	if (config.toolDescriptionMode !== undefined) return {};
-	return {
-		promptSnippet: SUBAGENT_TOOL_PROMPT_SNIPPET,
-		promptGuidelines: SUBAGENT_TOOL_PROMPT_GUIDELINES,
-	};
-}
-
-export function resolveToolDescriptionMode(config: Pick<ExtensionConfig, "toolDescriptionMode">, options?: ToolDescriptionOptions): ToolDescriptionMode {
-	const mode = config.toolDescriptionMode;
-	if (mode === undefined) return "full";
-	if (isToolDescriptionMode(mode)) return mode;
-	warn(options, `Ignoring invalid toolDescriptionMode ${JSON.stringify(mode)}; expected "full", "compact", or "custom".`);
-	return "full";
-}
-
-function customDescriptionPaths(options?: ToolDescriptionOptions): string[] {
-	const cwd = options?.cwd ?? process.cwd();
-	const agentDir = options?.agentDir ?? getAgentDir();
-	return [
-		path.join(getProjectConfigDir(cwd), CUSTOM_TOOL_DESCRIPTION_FILE),
-		path.join(agentDir, CUSTOM_TOOL_DESCRIPTION_FILE),
-	];
-}
-
-function renderCustomTemplate(template: string, options?: ToolDescriptionOptions): string {
-	const cwd = options?.cwd ?? process.cwd();
-	const agentDir = options?.agentDir ?? getAgentDir();
-	const projectConfigDir = getProjectConfigDir(cwd);
-	const variables: Record<string, () => string> = {
-		fullDescription: () => FULL_SUBAGENT_TOOL_DESCRIPTION,
-		full: () => FULL_SUBAGENT_TOOL_DESCRIPTION,
-		compactDescription: () => COMPACT_SUBAGENT_TOOL_DESCRIPTION,
-		compact: () => COMPACT_SUBAGENT_TOOL_DESCRIPTION,
-		safetyGuidance: () => SUBAGENT_SAFETY_GUIDANCE,
-		safety: () => SUBAGENT_SAFETY_GUIDANCE,
-		agentDir: () => agentDir,
-		projectConfigDir: () => projectConfigDir,
-	};
-	return template.replace(/\{\{(\w+)\}\}/g, (raw, name: string) => {
-		const replacement = variables[name];
-		if (replacement) return replacement();
-		warn(options, `${CUSTOM_TOOL_DESCRIPTION_FILE}: unknown placeholder ${raw} left unchanged.`);
-		return raw;
-	});
-}
-
-function loadCustomToolDescription(options?: ToolDescriptionOptions): string | undefined {
-	for (const filePath of customDescriptionPaths(options)) {
-		let stat: fs.Stats;
-		try {
-			stat = fs.statSync(filePath);
-		} catch (error) {
-			if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") continue;
-			warn(options, `Failed to inspect custom tool description '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
-			continue;
-		}
-		if (!stat.isFile()) {
-			warn(options, `Ignoring custom tool description '${filePath}' because it is not a file.`);
-			continue;
-		}
-		if (stat.size > CUSTOM_TOOL_DESCRIPTION_MAX_BYTES) {
-			warn(options, `Ignoring custom tool description '${filePath}' because it is larger than ${CUSTOM_TOOL_DESCRIPTION_MAX_BYTES} bytes.`);
-			continue;
-		}
-		try {
-			const template = fs.readFileSync(filePath, "utf-8").trim();
-			if (!template) {
-				warn(options, `Ignoring empty custom tool description '${filePath}'.`);
-				continue;
-			}
-			const rendered = renderCustomTemplate(template, options).trim();
-			if (!rendered) {
-				warn(options, `Ignoring custom tool description '${filePath}' because it rendered empty.`);
-				continue;
-			}
-			return rendered;
-		} catch (error) {
-			warn(options, `Failed to read custom tool description '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
-		}
-	}
-	return undefined;
-}
-
-function withMandatorySafetyGuidance(description: string): string {
-	const customDescription = description
-		.split(SUBAGENT_SAFETY_GUIDANCE)
-		.flatMap((part) => part.split(SUBAGENT_FAILURE_RECOVERY_GUIDANCE))
-		.map((part) => part.trim())
-		.filter(Boolean)
-		.join("\n\n");
-	return customDescription
-		? `${customDescription}\n\n${SUBAGENT_SAFETY_GUIDANCE}`
-		: SUBAGENT_SAFETY_GUIDANCE;
-}
-
-export function buildSubagentToolDescription(config: Pick<ExtensionConfig, "toolDescriptionMode"> = {}, options?: ToolDescriptionOptions): string {
-	if (config.toolDescriptionMode === undefined) return DEFAULT_SUBAGENT_TOOL_DESCRIPTION;
-	const mode = resolveToolDescriptionMode(config, options);
-	let description: string;
-	if (mode === "compact") description = COMPACT_SUBAGENT_TOOL_DESCRIPTION;
-	else if (mode === "custom") {
-		const custom = loadCustomToolDescription(options);
-		if (custom) description = withMandatorySafetyGuidance(custom);
-		else {
-			warn(options, `${CUSTOM_TOOL_DESCRIPTION_FILE} was not found or valid for toolDescriptionMode "custom"; using full description.`);
-			description = FULL_SUBAGENT_TOOL_DESCRIPTION;
-		}
-	} else description = FULL_SUBAGENT_TOOL_DESCRIPTION;
-	return description;
-}

package/src/extension/tool-result.ts

@@ -1,19 +0,0 @@
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-
-/**
- * Convert pi-subagents' internal logical-error result into the rejection Pi's
- * public tool boundary uses to emit a canonical errored ToolResult.
- *
- * Keep this at registered tool boundaries. Internal workflows intentionally
- * retain their return-based error handling.
- */
-export function finalizeToolResult<T>(result: AgentToolResult<T>): AgentToolResult<T> {
-	if (result.isError !== true) return result;
-
-	const message = result.content
-		.flatMap((item) => item.type === "text" && typeof item.text === "string" ? [item.text] : [])
-		.join("\n")
-		.trim();
-
-	throw new Error(message || "pi-subagents reported a logical tool failure.");
-}

package/src/inspectors/actions.ts

@@ -1,148 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { readMissionBinding } from "../missions/lifecycle.ts";
-import { listMissions, missionRecordPath, resolveMissionStoreLocation } from "../missions/store.ts";
-import type { MissionStoreConfig } from "../missions/types.ts";
-import { resolveAuthorityDecision, type AuthorityPolicyConfig } from "../policy/authority.ts";
-import { DIRS, type Details, type SubagentState } from "../shared/types.ts";
-import { readStatus } from "../shared/utils.ts";
-import { resolveSubagentRunId } from "../runs/background/run-id-resolver.ts";
-import { resolveNodeExecutable } from "../shared/node-executable.ts";
-import { encodeSessionRoots } from "./session-roots-codec.ts";
-import { formatShellCommand } from "./shell-command.ts";
-import type { InspectorAction, InspectorContext, InspectorLaunch, InspectorParams, InspectorPlugin, InspectorTarget } from "./types.ts";
-
-export { INSPECTOR_ACTIONS } from "./types.ts";
-export type { InspectorAction, InspectorParams, InspectorPlugin } from "./types.ts";
-
-function result(text: string, isError = false): AgentToolResult<Details> {
-	const response: AgentToolResult<Details> = {
-		content: [{ type: "text", text }],
-		details: { mode: "management", results: [] },
-	};
-	if (isError) response.isError = true;
-	return response;
-}
-
-function pathWithin(base: string, candidate: string): boolean {
-	const resolvedBase = path.resolve(base);
-	const resolvedCandidate = path.resolve(candidate);
-	return resolvedCandidate === resolvedBase || resolvedCandidate.startsWith(`${resolvedBase}${path.sep}`);
-}
-function trustedDir(dir: string, deps: InspectorDispatcherDeps): boolean {
-	try {
-		if (fs.lstatSync(dir).isSymbolicLink() || !fs.statSync(dir).isDirectory()) return false;
-		const real = fs.realpathSync(dir);
-		if ([...(deps.state?.asyncJobs.values() ?? []), ...(deps.state?.fleetJobs?.values() ?? [])].some((job) => {
-			try {
-				return fs.realpathSync(job.asyncDir) === real;
-			} catch {
-				return false;
-			}
-		})) return true;
-		const root = deps.asyncDirRoot ?? DIRS.async;
-		return fs.existsSync(root) && pathWithin(root, dir) && pathWithin(fs.realpathSync(root), real);
-	} catch { return false; }
-}
-function resolveTarget(params: InspectorParams, deps: InspectorDispatcherDeps): InspectorTarget | { error: string } {
-	const requested = params.id ?? params.runId;
-	let runId: string;
-	let asyncDir: string;
-	if (params.dir) {
-		asyncDir = path.resolve(params.dir);
-		if (!trustedDir(asyncDir, deps)) return { error: `Async run directory '${asyncDir}' is outside trusted run roots.` };
-		const status = readStatus(asyncDir);
-		if (!status) return { error: `No async run status found in '${asyncDir}'.` };
-		if (requested && requested !== status.runId && !status.runId.startsWith(requested)) return { error: `Run '${requested}' does not match status run '${status.runId}'.` };
-		runId = status.runId;
-	} else {
-		if (!requested) return { error: "Inspector actions require id or dir." };
-		try {
-			const found = resolveSubagentRunId(requested, { state: deps.state, asyncDirRoot: deps.asyncDirRoot ?? DIRS.async, resultsDir: deps.resultsDir ?? DIRS.results });
-			if (!found) return { error: `No subagent run found for '${requested}'.` };
-			if (found.kind !== "async" || !found.location.asyncDir) return { error: `Run '${found.id}' is not an inspectable async run with lifecycle artifacts.` };
-			runId = found.id;
-			asyncDir = found.location.asyncDir;
-		} catch (cause) {
-			return { error: cause instanceof Error ? cause.message : String(cause) };
-		}
-	}
-	const status = readStatus(asyncDir);
-	if (!status) return { error: `No lifecycle status exists for async run '${runId}'.` };
-	if (params.index !== undefined && (params.index < 0 || params.index >= (status.steps?.length ?? 0))) return { error: `Async run '${runId}' has ${status.steps?.length ?? 0} children. Index ${params.index} is out of range.` };
-	const target: InspectorTarget = { runId, asyncDir, status: { cwd: status.cwd, state: status.state, steps: status.steps } };
-	if (params.index !== undefined) target.index = params.index;
-	return target;
-}
-function missionFor(target: InspectorTarget, deps: InspectorDispatcherDeps): { id: string; path: string } | undefined {
-	try {
-		const binding = readMissionBinding(target.asyncDir);
-		if (binding) return { id: binding.missionId, path: missionRecordPath(binding.location, binding.missionId) };
-		const location = resolveMissionStoreLocation(deps.missions ? { projectRoot: deps.cwd, config: deps.missions } : { projectRoot: deps.cwd });
-		const mission = listMissions(location).records.find((record) => record.runs.some((run) => run.runId === target.runId));
-		return mission ? { id: mission.id, path: missionRecordPath(location, mission.id) } : undefined;
-	} catch {
-		return undefined;
-	}
-}
-function launchFor(target: InspectorTarget, deps: InspectorDispatcherDeps): InspectorLaunch {
-	const mission = missionFor(target, deps);
-	const runnerPath = deps.runnerPath ?? fileURLToPath(new URL("../../inspector-runner.mjs", import.meta.url));
-	const job = deps.state?.asyncJobs.get(target.runId) ?? deps.state?.fleetJobs?.get(target.runId);
-	const sessionRoots = [...new Set([...(deps.sessionRoots ?? deps.state?.trustedSessionRoots ?? []), ...(job?.sessionRoot ? [job.sessionRoot] : [])])];
-	const allowSteer = resolveAuthorityDecision({ action: "steerRun", policy: deps.authorityPolicy }) === "auto";
-	const allowStop = resolveAuthorityDecision({ action: "stopRun", policy: deps.authorityPolicy }) === "auto";
-	const argv = [runnerPath, "--async-dir", target.asyncDir, "--run-id", target.runId, "--allow-steer", String(allowSteer), "--allow-stop", String(allowStop), "--session-roots", encodeSessionRoots(sessionRoots)];
-	if (target.index !== undefined) argv.push("--index", String(target.index));
-	if (mission) argv.push("--mission-path", mission.path);
-	const executable = resolveNodeExecutable();
-	const launch: InspectorLaunch = { executable, argv, displayCommand: formatShellCommand(executable, argv), allowSteer, allowStop, sessionRoots };
-	if (mission) launch.mission = mission;
-	return launch;
-}
-
-export interface InspectorDispatcherDeps {
-	state?: SubagentState;
-	asyncDirRoot?: string;
-	resultsDir?: string;
-	missions?: MissionStoreConfig;
-	authorityPolicy?: AuthorityPolicyConfig;
-	sessionRoots?: string[];
-	cwd: string;
-	signal?: AbortSignal;
-	now?: () => Date;
-	runnerPath?: string;
-	env?: NodeJS.ProcessEnv;
-	plugins?: readonly InspectorPlugin[];
-}
-export async function handleInspectorAction(action: InspectorAction, params: InspectorParams, deps: InspectorDispatcherDeps): Promise<AgentToolResult<Details>> {
-	const target = resolveTarget(params, deps);
-	if ("error" in target) return result(target.error, true);
-	const context: InspectorContext = {
-		cwd: deps.cwd,
-		signal: deps.signal,
-		env: deps.env ?? process.env,
-		target,
-	};
-	if (deps.now) context.now = deps.now;
-	if (action === "inspector.command") return result(launchFor(target, deps).displayCommand);
-	const plugins = deps.plugins ?? [];
-	if (action === "inspector.open") {
-		for (const plugin of plugins) {
-			if (await plugin.available(context)) return plugin.open(context, launchFor(target, deps), params);
-		}
-		return result("No inspector plugin is available. Start a supported inspector host, or use inspector.command for a standalone command.", true);
-	}
-	const owner = plugins.find((plugin) => plugin.owns(context));
-	if (!owner) return result(`No inspector plugin owns this binding for async run ${target.runId}.`);
-	if (action === "inspector.status") {
-		return owner.status
-			? owner.status(context)
-			: result(`Inspector plugin '${owner.name}' does not support status for async run ${target.runId}.`, true);
-	}
-	return owner.close
-		? owner.close(context)
-		: result(`Inspector plugin '${owner.name}' does not support close for async run ${target.runId}.`, true);
-}

package/src/inspectors/ghostty/actions.ts

@@ -1,74 +0,0 @@
-import { execFile, type ExecFileOptionsWithStringEncoding } from "node:child_process";
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { Details } from "../../shared/types.ts";
-import type { InspectorContext, InspectorLaunch, InspectorParams } from "../types.ts";
-
-/** Static Ghostty 1.3 AppleScript; dynamic values arrive as `on run argv` arguments. */
-export const GHOSTTY_APPLESCRIPT = `on run argv
-  set launchCommand to item 1 of argv
-  set launchCwd to item 2 of argv
-  set shouldFocus to item 3 of argv
-  tell application "Ghostty"
-    set sourceWindow to front window
-    set sourceTab to selected tab of sourceWindow
-    set sourceTerminal to focused terminal of sourceTab
-    set surfaceConfiguration to new surface configuration
-    set initial working directory of surfaceConfiguration to launchCwd
-    set command of surfaceConfiguration to launchCommand
-    set newTerminal to split sourceTerminal direction right with configuration surfaceConfiguration
-    if shouldFocus is "true" then
-      focus newTerminal
-    else
-      focus sourceTerminal
-    end if
-    return id of newTerminal
-  end tell
-end run`;
-
-export type GhosttyRunner = (args: readonly string[], options: ExecFileOptionsWithStringEncoding) => Promise<{ stdout: string; stderr: string }>;
-
-function defaultRunner(args: readonly string[], options: ExecFileOptionsWithStringEncoding): Promise<{ stdout: string; stderr: string }> {
-	return new Promise((resolve, reject) => {
-		execFile("/usr/bin/osascript", [...args], options, (error, stdout, stderr) => {
-			if (error) {
-				const failure = error instanceof Error ? error : new Error(String(error));
-				reject(failure);
-				return;
-			}
-			resolve({ stdout, stderr });
-		});
-	});
-}
-
-function result(text: string, isError = false): AgentToolResult<Details> {
-	const response: AgentToolResult<Details> = {
-		content: [{ type: "text", text }],
-		details: { mode: "management", results: [] },
-	};
-	if (isError) response.isError = true;
-	return response;
-}
-
-const failureHint = "Ghostty inspector requires Ghostty 1.3+ and Automation permission for osascript.";
-
-export async function openGhosttyInspector(
-	context: InspectorContext,
-	launch: InspectorLaunch,
-	params: InspectorParams,
-	runner: GhosttyRunner = defaultRunner,
-): Promise<AgentToolResult<Details>> {
-	try {
-		const output = await runner(["-e", GHOSTTY_APPLESCRIPT, "--", launch.displayCommand, context.target.status.cwd ?? context.cwd, params.focus === true ? "true" : "false"], {
-			signal: context.signal,
-			timeout: 15_000,
-			encoding: "utf8",
-			maxBuffer: 64 * 1024,
-		});
-		const id = output.stdout.trim();
-		if (!id) return result(`Ghostty inspector error: Ghostty returned an empty terminal id. ${failureHint}`, true);
-		return result(`Opened read-only Ghostty inspector terminal ${id} for async run ${context.target.runId}. Status and close are unavailable because this plugin writes no binding.`);
-	} catch (cause) {
-		const message = cause instanceof Error ? cause.message : String(cause);
-		return result(`Ghostty inspector error: ${message}. ${failureHint}`, true);
-	}
-}

package/src/inspectors/ghostty/plugin.ts

@@ -1,29 +0,0 @@
-import { openGhosttyInspector, type GhosttyRunner } from "./actions.ts";
-import type { InspectorPlugin } from "../types.ts";
-
-/** 独立 Ghostty.app 的 bundle id (作者 Mitchell Hashimoto)。 */
-const GHOSTTY_BUNDLE_ID = "com.mitchellh.ghostty";
-
-export interface GhosttyPluginDeps {
-	platform?: NodeJS.Platform;
-	runner?: GhosttyRunner;
-}
-
-export function createGhosttyInspectorPlugin(deps: GhosttyPluginDeps = {}): InspectorPlugin {
-	const platform = deps.platform ?? process.platform;
-	return {
-		name: "ghostty",
-		available: (context) => {
-			// cmux 内嵌 Ghostty 内核, 也会把 TERM_PROGRAM 设成 "ghostty"。仅凭环境变量会让 plugin
-			// 在 cmux 下误接管, 随后 osascript 连不上真正的 Ghostty 应用而抛 -1728/-2741。
-			if (platform !== "darwin") return false;
-			if (context.env.TERM_PROGRAM?.toLowerCase() !== "ghostty") return false;
-			// macOS GUI 应用启动子进程时注入 __CFBundleIdentifier, 标识当前终端宿主 app。
-			// cmux 的 bundle id 是 com.cmuxterm.app, 而非 Ghostty; 即便系统同时装了独立 Ghostty,
-			// 也能据此判定当前终端不是 Ghostty, 避免误连独立 Ghostty 的窗口。
-			return context.env.__CFBundleIdentifier?.trim() === GHOSTTY_BUNDLE_ID;
-		},
-		owns: () => false,
-		open: (context, launch, params) => openGhosttyInspector(context, launch, params, deps.runner),
-	};
-}

package/src/inspectors/herdr/actions.ts

@@ -1,155 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import type { Details } from "../../shared/types.ts";
-import type { InspectorContext, InspectorLaunch, InspectorParams, InspectorTarget } from "../types.ts";
-import { detectHerdr, type HerdrClient, type HerdrErrorCode, type HerdrResult } from "./client.ts";
-
-export interface HerdrInspectorBinding {
-	schemaVersion: 1;
-	kind: "herdr-inspector";
-	runId: string;
-	asyncDir: string;
-	childIndex?: number;
-	missionId?: string;
-	missionPath?: string;
-	paneId: string;
-	openedAt: string;
-	lastFocusedAt?: string;
-	herdrVersion?: string;
-	command: string;
-}
-
-export function bindingPath(asyncDir: string, index?: number): string {
-	return path.join(asyncDir, "inspectors", `herdr${index === undefined ? "" : `-${index}`}.json`);
-}
-
-function parse(value: unknown): HerdrInspectorBinding | undefined {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const binding = value as Partial<HerdrInspectorBinding>;
-	if (binding.schemaVersion !== 1
-		|| binding.kind !== "herdr-inspector"
-		|| (binding.childIndex !== undefined && (!Number.isInteger(binding.childIndex) || binding.childIndex < 0))
-		|| typeof binding.runId !== "string"
-		|| typeof binding.asyncDir !== "string"
-		|| typeof binding.paneId !== "string"
-		|| typeof binding.openedAt !== "string"
-		|| typeof binding.command !== "string") return undefined;
-	return binding as HerdrInspectorBinding;
-}
-
-export function readHerdrInspectorBinding(asyncDir: string, index?: number): HerdrInspectorBinding | undefined {
-	try {
-		return parse(JSON.parse(fs.readFileSync(bindingPath(asyncDir, index), "utf8")));
-	} catch {
-		return undefined;
-	}
-}
-
-/** Read a binding only when it belongs to the requested inspector target. */
-export function readHerdrInspectorBindingForTarget(target: InspectorTarget): HerdrInspectorBinding | undefined {
-	const binding = readHerdrInspectorBinding(target.asyncDir, target.index);
-	if (!binding || binding.runId !== target.runId || binding.childIndex !== target.index) return undefined;
-	try {
-		if (fs.realpathSync(binding.asyncDir) !== fs.realpathSync(target.asyncDir)) return undefined;
-	} catch {
-		return undefined;
-	}
-	return binding;
-}
-
-function result(text: string, isError = false): AgentToolResult<Details> {
-	return {
-		content: [{ type: "text", text }],
-		...(isError ? { isError: true } : {}),
-		details: { mode: "management", results: [] },
-	};
-}
-
-function errorText(input: { code: HerdrErrorCode; message: string }): string {
-	return `Herdr inspector error (${input.code}): ${input.message}`;
-}
-
-function paneId(value: unknown): string | undefined {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const record = value as Record<string, unknown>;
-	const pane = record.pane && typeof record.pane === "object" ? record.pane as Record<string, unknown> : record;
-	for (const key of ["pane_id", "paneId", "id"]) {
-		if (typeof pane[key] === "string") return pane[key];
-	}
-	return undefined;
-}
-
-async function pane(client: HerdrClient, id: string, signal?: AbortSignal): Promise<HerdrResult<unknown>> {
-	return client.run(["pane", "get", id], { timeoutMs: 5_000, signal });
-}
-
-export async function openHerdrInspector(
-	context: InspectorContext,
-	launch: InspectorLaunch,
-	params: InspectorParams,
-	client: HerdrClient,
-): Promise<AgentToolResult<Details>> {
-	const detected = await detectHerdr(client, context.signal);
-	if (!detected.ok) return result(errorText(detected.error), true);
-	const existing = readHerdrInspectorBindingForTarget(context.target);
-	if (existing) {
-		const current = await pane(client, existing.paneId, context.signal);
-		if (current.ok && paneId(current.data) === existing.paneId) {
-			return result(`Herdr inspector pane ${existing.paneId} is already open for async run ${context.target.runId}.${params.focus ? " Herdr cannot refocus an arbitrary raw pane id; select it in the Herdr UI." : ""}`);
-		}
-	}
-	const split = await client.run([
-		"pane", "split", "--current", "--direction", "right",
-		"--cwd", context.target.status.cwd ?? context.cwd,
-		params.focus === true ? "--focus" : "--no-focus",
-	], { timeoutMs: 15_000, signal: context.signal });
-	if (!split.ok) return result(errorText(split.error), true);
-	const id = paneId(split.data);
-	if (!id) return result("Herdr inspector error (PANE_GONE): pane split returned no pane id.", true);
-	const started = await client.run(["pane", "run", id, launch.displayCommand], { timeoutMs: 15_000, signal: context.signal });
-	if (!started.ok) {
-		await client.run(["pane", "close", id], { timeoutMs: 5_000 });
-		return result(errorText(started.error), true);
-	}
-	const now = (context.now?.() ?? new Date()).toISOString();
-	const binding: HerdrInspectorBinding = {
-		schemaVersion: 1,
-		kind: "herdr-inspector",
-		runId: context.target.runId,
-		asyncDir: context.target.asyncDir,
-		...(context.target.index === undefined ? {} : { childIndex: context.target.index }),
-		...(launch.mission ? { missionId: launch.mission.id, missionPath: launch.mission.path } : {}),
-		paneId: id,
-		openedAt: now,
-		...(params.focus === true ? { lastFocusedAt: now } : {}),
-		herdrVersion: detected.data.versionText,
-		command: launch.displayCommand,
-	};
-	writeAtomicJson(bindingPath(context.target.asyncDir, context.target.index), binding);
-	return result(`Opened read-only Herdr inspector pane ${id} for async run ${context.target.runId}. Closing the pane does not stop the run.\nControls inside the pane: steer <message>, stop, status.`);
-}
-
-export async function statusHerdrInspector(context: InspectorContext, client: HerdrClient): Promise<AgentToolResult<Details>> {
-	const binding = readHerdrInspectorBindingForTarget(context.target);
-	if (!binding) {
-		return result(`No Herdr inspector binding exists for async run ${context.target.runId}${context.target.index === undefined ? "" : ` child ${context.target.index}`}.`);
-	}
-	const live = await pane(client, binding.paneId, context.signal);
-	if (!live.ok) {
-		return result(`${errorText(live.error)}\nBinding: ${bindingPath(context.target.asyncDir, context.target.index)}\nRun state remains authoritative: ${context.target.status.state}.`, true);
-	}
-	return result(`Herdr inspector ${binding.paneId} is open for async run ${context.target.runId}.\nRun state: ${context.target.status.state}\nBinding: ${bindingPath(context.target.asyncDir, context.target.index)}`);
-}
-
-export async function closeHerdrInspector(context: InspectorContext, client: HerdrClient): Promise<AgentToolResult<Details>> {
-	const binding = readHerdrInspectorBindingForTarget(context.target);
-	if (!binding) return result(`No Herdr inspector binding exists for async run ${context.target.runId}.`);
-	const closed = await client.run(["pane", "close", binding.paneId], { timeoutMs: 10_000, signal: context.signal });
-	if (!closed.ok && closed.error.code !== "NOT_FOUND" && closed.error.code !== "PANE_GONE") {
-		return result(errorText(closed.error), true);
-	}
-	fs.rmSync(bindingPath(context.target.asyncDir, context.target.index), { force: true });
-	return result(`Closed Herdr inspector pane ${binding.paneId} for async run ${context.target.runId}. The subagent run was not stopped.`);
-}