@selesai/code 0.8.5 → 0.8.7

package/dist/extensions/pi-subagents/src/extension/index.ts

@@ -16,6 +16,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { keyText, type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@selesai/code";
 import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
@@ -23,6 +24,7 @@ import { discoverAgents } from "../agents/agents.ts";
 import { ensureAccessibleDir } from "../shared/accessible-dir.ts";
 import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
 import { resolveCurrentSessionId } from "../shared/session-identity.ts";
+import { resolveSessionLineage } from "../shared/session-lineage.ts";
 import { cleanupOldChainDirs } from "../shared/settings.ts";
 import { clearLegacyResultAnimationTimer, renderSubagentResult, renderSubagentSummary } from "../tui/render.ts";
 import { openSubagentFleet } from "../tui/fleet.ts";
@@ -32,6 +34,7 @@ import { validateChainInput } from "./chain-validation.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
 import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
 import { getActiveAsyncCapacitySnapshot, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
+import { cleanupResultIndexes } from "../runs/background/result-files.ts";
 import { createResultWatcher } from "../runs/background/result-watcher.ts";
 import { createScheduledRunManager } from "../runs/background/scheduled-runs.ts";
 import { registerSlashCommands } from "../slash/slash-commands.ts";
@@ -60,6 +63,7 @@ import { resolveMissionStoreLocation } from "../missions/store.ts";
 import { listRetainedChildren } from "../runs/background/retained-children.ts";
 import {
 	type Details,
+	type MainWindowRendererConfig,
 	type SubagentState,
 	DIRS,
 	DEFAULT_ARTIFACT_CONFIG,
@@ -82,6 +86,13 @@ import {
 
 export { loadConfig, resolveAsyncByDefault } from "./config.ts";
 
+const SLOW_RELOAD_PHASE_MS = 250;
+
+function logSlowPhase(label: string, startedAt: number): void {
+	const elapsed = Date.now() - startedAt;
+	if (elapsed >= SLOW_RELOAD_PHASE_MS) console.error(`Subagent reload phase '${label}' took ${elapsed}ms.`);
+}
+
 function workflowLaneKeys(script: string): string[] {
 	const keys: string[] = [];
 	const seen = new Set<string>();
@@ -258,12 +269,14 @@ function rebuildSlashResultContainer(
 	result: AgentToolResult<Details>,
 	options: { expanded: boolean },
 	theme: ExtensionContext["ui"]["theme"],
+	rendererConfig?: MainWindowRendererConfig,
+	foregroundDetachShortcut?: string,
 ): void {
 	container.clear();
 	container.addChild(new Spacer(1));
 	const boxTheme = isSlashResultRunning(result) ? "toolPendingBg" : isSlashResultError(result) ? "toolErrorBg" : "toolSuccessBg";
 	const box = new Box(1, 1, (text: string) => theme.bg(boxTheme, text));
-	box.addChild(renderSubagentResult(result, options, theme));
+	box.addChild(renderSubagentResult(result, options, theme, undefined, rendererConfig, foregroundDetachShortcut));
 	container.addChild(box);
 }
 
@@ -271,6 +284,8 @@ function createSlashResultComponent(
 	details: SlashMessageDetails,
 	options: { expanded: boolean },
 	theme: ExtensionContext["ui"]["theme"],
+	rendererConfig?: MainWindowRendererConfig,
+	foregroundDetachShortcut?: string,
 ): Container {
 	const container = new Container();
 	let lastVersion = -1;
@@ -278,7 +293,7 @@ function createSlashResultComponent(
 		const snapshot = getSlashRenderableSnapshot(details);
 		if (snapshot.version !== lastVersion || isSlashResultRunning(snapshot.result)) {
 			lastVersion = snapshot.version;
-			rebuildSlashResultContainer(container, snapshot.result, options, theme);
+			rebuildSlashResultContainer(container, snapshot.result, options, theme, rendererConfig, foregroundDetachShortcut);
 		}
 		return Container.prototype.render.call(container, width);
 	};
@@ -375,6 +390,20 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const tempArtifactsDir = getArtifactsDir(null);
 	const artifactCleanupDays = config.artifactConfig?.cleanupDays ?? DEFAULT_ARTIFACT_CONFIG.cleanupDays;
 	cleanupAllArtifactDirs(artifactCleanupDays);
+	const resultIndexCleanupTimer = setTimeout(() => {
+		try {
+			cleanupResultIndexes(DIRS.results);
+		} catch (error) {
+			console.error("Failed to clean stale subagent result indexes:", error);
+		}
+	}, 30_000);
+	resultIndexCleanupTimer.unref?.();
+
+	// Replay guard for lineage result adoption: accept result files written at
+	// most this long before the adoption window opened (covers completions that
+	// raced the session switch). Older files were left behind by a dead watcher
+	// and are ignored until their owning session is resumed.
+	const ADOPTED_RESULT_SLACK_MS = 60_000;
 
 	const state: SubagentState = {
 		baseCwd: "",
@@ -383,6 +412,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		...(config.authorityPolicy ? { authorityPolicy: config.authorityPolicy } : {}),
 		...(config.missions ? { missionStoreConfig: config.missions } : {}),
 		parentSessionFile: null,
+		trustedSessionRoots: [],
 		subagentInProgress: false,
 		subagentSpawns: {
 			sessionId: null,
@@ -456,6 +486,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	);
 
 	const runtimeCleanup = () => {
+		clearTimeout(resultIndexCleanupTimer);
 		stopResultWatcher();
 		state.currentSessionId = null;
 		completionNotifier.dispose();
@@ -486,7 +517,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	pi.registerMessageRenderer<SlashMessageDetails>(SLASH_RESULT_TYPE, (message, options, theme) => {
 		const details = resolveSlashMessageDetails(message.details);
 		if (!details) return undefined;
-		return createSlashResultComponent(details, options, theme);
+		return createSlashResultComponent(details, options, theme, config.mainWindowRenderer, config.foregroundDetachShortcut);
 	});
 
 	pi.registerMessageRenderer<undefined>(SLASH_TEXT_RESULT_TYPE, (message, _options, _theme) => {
@@ -580,28 +611,31 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		label: "Subagent",
 		description: buildSubagentToolDescription(config),
 		parameters,
+		keepParameterDescriptions: true,
 
 		execute(id, params, signal, onUpdate, ctx) {
 			return executeSubagentCollapsed(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx);
 		},
 
 		renderCall(args, theme) {
+			const gap = " ".repeat(config.mainWindowRenderer?.horizontalSpacing ?? 1);
+			const title = theme.fg("toolTitle", theme.bold("subagent"));
 			if (args.action) {
 				const target = args.agent || args.chainName || "";
 				return new Text(
-					`${theme.fg("toolTitle", theme.bold("subagent "))}${args.action}${target ? ` ${theme.fg("accent", target)}` : ""}`,
+					`${title}${gap}${args.action}${target ? `${gap}${theme.fg("accent", target)}` : ""}`,
 					0, 0,
 				);
 			}
 			if (args.workflowScript)
 				return new Text(
-					`${theme.fg("toolTitle", theme.bold("subagent "))}${formatWorkflowManifest(args.workflowScript, args.async, false)}`,
+					`${title}${gap}${formatWorkflowManifest(args.workflowScript, args.async, false)}`,
 					0,
 					0,
 				);
-			const asyncLabel = args.async === true ? theme.fg("warning", " [async]") : "";
+			const asyncLabel = args.async === true ? `${gap}${theme.fg("warning", "[async]")}` : "";
 			return new Text(
-				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", args.agent || "?")}${asyncLabel}`,
+				`${title}${gap}${theme.fg("accent", args.agent || "?")}${asyncLabel}`,
 				0,
 				0,
 			);
@@ -612,7 +646,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			const renderedResult = { ...result, isError: context.isError };
 			return summaryInlineToolDisplay
 				? renderSubagentSummary(renderedResult, options, theme)
-				: renderSubagentResult(renderedResult, options, theme);
+				: renderSubagentResult(renderedResult, options, theme, undefined, config.mainWindowRenderer, config.foregroundDetachShortcut);
 		},
 
 	};
@@ -630,26 +664,41 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 
 	pi.on("agent_end", async (_event, ctx) => {
 		if (!ctx.hasUI) await drainOutstandingWork({ state, events: pi.events });
-		const ownerSessionId = state.currentSessionId;
-		if (!ownerSessionId) return;
+		const ownerSessionIds = state.sessionLineage?.length
+			? state.sessionLineage
+			: state.currentSessionId ? [state.currentSessionId] : [];
+		if (ownerSessionIds.length === 0) return;
 		goalTurnId += 1;
 		try {
 			const location = resolveMissionStoreLocation({ projectRoot: state.baseCwd, ...(config.missions ? { config: config.missions } : {}) });
-			const retainedChildren = listRetainedChildren(DIRS.async, ownerSessionId);
-			for (const notice of collectGoalContinuationNotices({ location, ownerSessionId, retainedChildren, turnId: goalTurnId })) {
-				handleSubagentControlNotice({
-					pi,
-					state,
-					visibleControlNotices: new Set(),
-					details: { source: "goal", event: notice.event, noticeText: notice.message },
-				});
+			const retainedChildren = listRetainedChildren(DIRS.async, ownerSessionIds);
+			const emittedMissions = new Set<string>();
+			for (const ownerSessionId of ownerSessionIds) {
+				for (const notice of collectGoalContinuationNotices({ location, ownerSessionId, retainedChildren, turnId: goalTurnId })) {
+					if (emittedMissions.has(notice.missionId)) continue;
+					emittedMissions.add(notice.missionId);
+					handleSubagentControlNotice({
+						pi,
+						state,
+						visibleControlNotices: new Set(),
+						details: { source: "goal", event: notice.event, noticeText: notice.message },
+					});
+				}
 			}
 		} catch (error) {
 			console.error("Failed to evaluate goal missions:", error);
 		}
 	});
 
-	registerSlashCommands(pi, state, { fleetKeybindings: config.fleetKeybindings });
+	registerSlashCommands(pi, state, {
+		fleetKeybindings: config.fleetKeybindings,
+		foregroundDetachShortcut: config.foregroundDetachShortcut,
+	});
+	pi.on("resources_discover", () => {
+		return {
+			promptPaths: [fileURLToPath(new URL("../../prompts", import.meta.url))],
+		};
+	});
 
 	const eventUnsubscribeStoreKey = "__piSubagentEventUnsubscribes";
 	const controlNoticeSeenStoreKey = "__piSubagentVisibleControlNotices";
@@ -758,14 +807,51 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			resolveMaxActiveAsyncRunsPerSession(config.maxActiveAsyncRunsPerSession),
 			{ liveWorkflowRunIds: new Set(state.workflowControllers?.keys() ?? []) },
 		);
+		const adoptedActive = [...state.asyncJobs.values()].filter((job) => job.adopted && (job.status === "queued" || job.status === "running")).length;
+		if (adoptedActive > 0) {
+			state.activeAsyncCapacity = {
+				...state.activeAsyncCapacity,
+				used: state.activeAsyncCapacity.used + adoptedActive,
+			};
+		}
+	};
+
+	const formatActiveWorkflowSummary = (target: SubagentState, intro: string): string => {
+		const active = [...target.asyncJobs.values()]
+			.filter((job) => job.status === "queued" || job.status === "running")
+			.sort((left, right) => (left.startedAt ?? 0) - (right.startedAt ?? 0));
+		const lines = active.map((job) => {
+			const label = job.mode === "workflow"
+				? `workflow[${job.workflowKey ?? "script"}]`
+				: `${job.mode ?? "run"}${job.agents?.length ? ` ${job.agents.join(", ")}` : ""}`;
+			const step = job.currentStep !== undefined
+				? ` · step ${job.currentStep + 1}/${job.chainStepCount ?? job.stepsTotal ?? "?"}`
+				: "";
+			const activity = job.currentTool ? ` · last: ${job.currentTool}` : "";
+			const adopted = job.adopted ? " (carried over from a previous session)" : "";
+			return `- ${job.asyncId} ${label}${step}${activity}${adopted}`;
+		});
+		return [
+			intro,
+			...lines,
+			"Monitor with subagent status <id>; interrupt/resume/steer by run id; children.list lists completed steps. Results arrive automatically.",
+		].join("\n");
 	};
 
-	const resetSessionState = (ctx: ExtensionContext, recovering: boolean) => {
+	const resetSessionState = (ctx: ExtensionContext, recovering: boolean, previousSessionFile?: string | null) => {
+		state.sessionLineage = resolveSessionLineage({ sessionManager: ctx.sessionManager }, { parentHint: previousSessionFile ?? null });
+		state.handoffResumePending = false;
+		if (state.sessionLineage.length > 1) state.adoptedResultWindowStart = Date.now() - ADOPTED_RESULT_SLACK_MS;
+		else state.adoptedResultWindowStart = undefined;
 		state.widgetsSuspended = false;
 		state.baseCwd = ctx.cwd;
 		goalTurnId = 0;
 		state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
 		state.parentSessionFile = ctx.sessionManager.getSessionFile();
+		state.trustedSessionRoots = [...new Set([
+			...(config.defaultSessionDir ? [path.resolve(expandTilde(config.defaultSessionDir))] : []),
+			...(state.parentSessionFile ? [getSubagentSessionRoot(state.parentSessionFile)] : []),
+		])];
 		state.subagentSpawns = {
 			sessionId: state.currentSessionId,
 			count: 0,
@@ -785,18 +871,39 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 			}
 		}
 		state.lastUiContext = ctx;
+		let phaseStartedAt = Date.now();
 		refreshActiveAsyncCapacity();
+		logSlowPhase("active-capacity", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		cleanupSessionArtifacts(ctx);
+		logSlowPhase("session-artifact-cleanup", phaseStartedAt);
 		state.foregroundControls.clear();
 		state.lastForegroundControlId = null;
+		phaseStartedAt = Date.now();
 		resetJobs(ctx);
+		logSlowPhase("reset-jobs", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		restoreForegroundRunHistory(state, { resultsDir: DIRS.results });
-		restoreActiveJobs(ctx);
+		logSlowPhase("foreground-history", phaseStartedAt);
+		phaseStartedAt = Date.now();
+		const adoptedJobs = restoreActiveJobs(ctx);
+		logSlowPhase("active-job-restore", phaseStartedAt);
+		state.handoffResumePending = adoptedJobs > 0 && state.lastUiContext?.hasUI === true;
+		phaseStartedAt = Date.now();
 		scheduledRunManager.bindSession(ctx);
+		logSlowPhase("scheduled-runs", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
+		logSlowPhase("slash-snapshots", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		waitSubscriptionManager.restore();
+		logSlowPhase("wait-subscriptions", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		startResultWatcher();
+		logSlowPhase("result-watcher-start", phaseStartedAt);
+		phaseStartedAt = Date.now();
 		primeExistingResults({ triggerTurn: !recovering });
+		logSlowPhase("result-prime", phaseStartedAt);
 		fleetStatus?.setContext(ctx);
 	};
 
@@ -807,6 +914,17 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 
 	pi.on("agent_settled", () => {
 		resumeWidgetsAfterCompaction();
+		if (state.handoffResumePending && state.lastUiContext?.hasUI === true) {
+			state.handoffResumePending = false;
+			pi.sendMessage(
+				{
+					customType: "subagent-handoff-resume",
+					content: formatActiveWorkflowSummary(state, "Session handoff detected. The previous session's background workflows were carried over:"),
+					display: false,
+				},
+				{ triggerTurn: true },
+			);
+		}
 	});
 
 	pi.on("session_before_compact", (event) => {
@@ -819,7 +937,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 		pi.sendMessage(
 			{
 				customType: "subagent-compaction-resume",
-				content: "Compaction is complete. Resume the parent task now; background subagent results will arrive separately when ready.",
+				content: formatActiveWorkflowSummary(state, "Compaction is complete. Resume the parent task now; results for the runs below arrive separately when ready:"),
 				display: false,
 			},
 			{ triggerTurn: true },
@@ -828,7 +946,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 
 	pi.on("session_start", (event, ctx) => {
 		const recovering = event.reason === "startup" || event.reason === "reload" || event.reason === "resume";
-		resetSessionState(ctx, recovering);
+		const previousSessionFile = event.reason === "new" || event.reason === "fork" ? event.previousSessionFile : null;
+		resetSessionState(ctx, recovering, previousSessionFile);
 		herdrStatusBridge.sessionStarted({
 			hasUI: ctx.hasUI === true,
 			runs: activeHerdrRuns(),
@@ -839,9 +958,13 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 
 	pi.on("session_shutdown", async () => {
 		state.widgetsSuspended = false;
+		clearTimeout(resultIndexCleanupTimer);
 		stopResultWatcher();
 		state.currentSessionId = null;
 		state.parentSessionFile = null;
+		state.sessionLineage = undefined;
+		state.adoptedResultWindowStart = undefined;
+		state.handoffResumePending = false;
 		completionNotifier.dispose();
 		delete process.env[SUBAGENT_PARENT_SESSION_ENV];
 		for (const unsubscribe of eventUnsubscribes) {

package/dist/extensions/pi-subagents/src/extension/public-execution.ts

@@ -9,6 +9,7 @@ export interface PublicSubagentExecutionParams {
 	concurrency?: unknown;
 	chainDir?: unknown;
 	workflowScript?: unknown;
+	output?: unknown;
 	resume?: unknown;
 	clarify?: unknown;
 	runFanoutBudget?: unknown;
@@ -33,7 +34,7 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
 	}
 	const action = params.action;
 	if (action !== undefined && (typeof action !== "string" || !action.trim())) {
-		return { ok: false, error: "action must be a non-empty management/control action, or omit action and execute directly.", mode: "management" };
+		return { ok: false, error: "action must be a non-empty management/control action, or omit action and use workflowScript.", mode: "management" };
 	}
 	const normalizedAction = typeof action === "string" ? action.trim() : undefined;
 	if (params.clarify === true && params.workflowScript !== undefined) {
@@ -59,10 +60,16 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
 		if (params.workflowScript !== undefined) {
 			return { ok: false, error: "workflowScript execution must omit action; only schedule.create accepts action with workflowScript.", mode: "management" };
 		}
+		if (params.task !== undefined) {
+			return { ok: false, error: "Structured single-child task cannot be combined with a management/control action.", mode: "management" };
+		}
 		return { ok: true, params: { ...params, action: normalizedAction } };
 	}
-	if (typeof params.workflowScript === "string" && params.workflowScript.trim()) {
-		return { ok: true, params };
+	if (params.step !== undefined) {
+		return { ok: false, error: "step is only available with action='append-step'; it is not an execution mode.", mode: "workflow" };
+	}
+	if (params.workflowScript !== undefined && (params.agent !== undefined || params.task !== undefined)) {
+		return { ok: false, error: "Structured single-child execution cannot be combined with workflowScript.", mode: "workflow" };
 	}
 	if (params.chain !== undefined) {
 		return { ok: true, params };
@@ -70,8 +77,29 @@ export function normalizePublicSubagentExecution<T extends PublicSubagentExecuti
 	if (params.tasks !== undefined) {
 		return { ok: true, params };
 	}
-	if (params.agent !== undefined || params.task !== undefined || params.step !== undefined) {
-		return { ok: true, params };
+	if (params.agent !== undefined || params.task !== undefined) {
+		if (typeof params.agent !== "string" || !params.agent.trim()) {
+			return { ok: false, error: "Structured single-child execution requires agent to be a non-empty string.", mode: "workflow" };
+		}
+		if (params.task !== undefined && typeof params.task !== "string") {
+			return { ok: false, error: "Structured single-child task must be a string when provided.", mode: "workflow" };
+		}
+		const { agent: _agent, task: _task, output, ...workflowDefaults } = params;
+		const child = {
+			agent: params.agent.trim(),
+			...(params.task !== undefined ? { task: params.task } : {}),
+			output: output === undefined ? true : output,
+		};
+		return {
+			ok: true,
+			params: {
+				...workflowDefaults,
+				workflowScript: `console.info("Converted structured single-child request to workflow runs.run('main', ...)."); return runs.run("main", ${JSON.stringify(child)})`,
+			} as T,
+		};
+	}
+	if (typeof params.workflowScript !== "string" || !params.workflowScript.trim()) {
+		return { ok: false, error: "Execution requires one mode: { agent, task? }, { chain: [...] }, { tasks: [...] }, or { workflowScript }.", mode: "workflow" };
 	}
-	return { ok: false, error: "Execution requires one mode: { agent, task? }, { chain: [...] }, { tasks: [...] }, or { workflowScript }.", mode: "workflow" };
+	return { ok: true, params };
 }

package/dist/extensions/pi-subagents/src/extension/rpc.ts

@@ -21,6 +21,7 @@ import { sanitizeDisplayText, truncateDisplayText } from "../shared/display-text
 import { readStatus } from "../shared/utils.ts";
 import { SubagentParams } from "./schemas.ts";
 import { normalizePublicSubagentExecution } from "./public-execution.ts";
+import { ASYNC_STATUS_SNAPSHOT_KIND, ASYNC_STATUS_SNAPSHOT_VERSION, buildAsyncStatusSnapshotForState } from "../runs/background/async-status-snapshot.ts";
 
 export const SUBAGENT_RPC_PROTOCOL_VERSION = 1;
 export const SUBAGENT_RPC_REQUEST_EVENT = "subagents:rpc:v1:request";
@@ -381,6 +382,7 @@ function pingData(ctx: ExtensionContext | null) {
 		capabilities: {
 			status: true,
 			fleetStatus: { version: 1 },
+			asyncStatusSnapshot: { kind: ASYNC_STATUS_SNAPSHOT_KIND, version: ASYNC_STATUS_SNAPSHOT_VERSION },
 			asyncSpawn: true,
 			steer: true,
 			nonRecoveringSteer: true,
@@ -550,13 +552,15 @@ async function handleRequest(
 			request.method,
 			{ action: "status", ...normalizeTargetParams(request.params, "status") },
 		);
+		const sessionId = resolveCurrentSessionId(ctx.sessionManager);
 		return {
 			...status,
 			fleet: buildFleetStatus(
 				options.state,
 				fleetKeys,
-				resolveCurrentSessionId(ctx.sessionManager),
+				sessionId,
 			),
+			asyncSnapshot: buildAsyncStatusSnapshotForState(options.state, sessionId),
 		};
 	}
 	if (request.method === "steer") {

package/dist/extensions/pi-subagents/src/extension/schemas.ts

@@ -89,11 +89,11 @@ const AcceptanceOverride = Type.Unsafe({
 		{ type: "boolean", enum: [false] },
 		{ type: "object", additionalProperties: true },
 	],
-	description: `Optional acceptance policy. For reviewer/read-only calls, omit acceptance. Example: { level: "checked", evidence: ["commands-run", "changed-files"] }. Supported evidence kinds: ${AcceptanceEvidenceKinds.join(", ")}. Evidence levels end at verified; use acceptance.review.required for review. Omitted means auto-inferred unless agentContract compatibility behavior is enabled.`,
+	description: `Optional acceptance policy. Omit for read-only calls. Example: { level: "checked", evidence: ["commands-run", "changed-files"] }. Supported evidence kinds: ${AcceptanceEvidenceKinds.join(", ")}. Evidence levels end at verified; use acceptance.review.required for review.`,
 });
 
 const AgentContractOverride = Type.Object({
-	version: Type.Integer({ enum: [1], description: "Enable compatibility behavior for this run/child." }),
+	version: Type.Integer({ minimum: 1, maximum: 1, description: "Enable compatibility behavior for this run/child." }),
 }, { additionalProperties: false, description: "Compatibility behavior. Omit for the default behavior." });
 
 const ChainGateOverride = Type.String({
@@ -255,49 +255,49 @@ const ControlOverrides = Type.Object({
 });
 
 const SubagentParamProperties = {
-	agent: Type.Optional(Type.String({ description: "Agent target for management actions such as get, update, delete, and models." })),
-	task: Type.Optional(Type.String({ description: "Task (SINGLE mode, optional for self-contained agents)" })),
+	agent: Type.Optional(Type.String({ description: "Agent for one-child execution, or target for agent management actions." })),
+	task: Type.Optional(Type.String({ description: "Optional one-child task. Requires agent; cannot combine with action or workflowScript." })),
 	resume: Type.Optional(Type.String({ description: "Retained child run id for a workflowScript runs.run/runs.all item. Mutually exclusive with agent; task supplies the follow-up." })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({ minLength: 1,
-		description: "Optional management/control action. Omit this field for workflowScript execution; use it only for management/control actions."
+		description: "Optional management/control action. Omit this field for structured single-child or workflowScript execution; use it only for management/control actions."
 	})),
 	name: Type.Optional(Type.String({ description: "Human-readable name for action='schedule.create'." })),
 	id: Type.Optional(Type.String({
-		description: "Run id or prefix for status, interrupt, stop, dismiss, resume, steer, append-step, approve-checkpoint, reject-checkpoint, mission.attach-run, or the decision id for mission.resolve-decision."
+		description: "Run id/prefix for status/debug.run, interrupt, steer, append-step, approve-checkpoint, reject-checkpoint, or mission."
 	})),
 	runId: Type.Optional(Type.String({
-		description: "Target run ID for interrupt, stop, dismiss, resume, steer, append-step, approve-checkpoint, reject-checkpoint, or mission.attach-run. Prefer id for new calls."
+		description: "Target run ID for debug.run, interrupt, steer, append-step, or mission.attach-run. Prefer id."
 	})),
 	dir: Type.Optional(Type.String({
-		description: "Async run directory for action='status', action='stop', action='resume', or action='steer'."
+		description: "Async run directory for status/debug.run, stop, resume, or steer."
 	})),
 	handoffPath: Type.Optional(Type.String({ description: "worktree.discard manifest." })),
 	index: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based child index for actions that target a specific child or transcript." })),
 	view: Type.Optional(Type.String({
 		enum: ["fleet", "transcript"],
-		description: "Optional status view. Use view='fleet' for a read-only active foreground/async fleet surface, or view='transcript' with id/dir (and optional index) to tail a run transcript.",
+		description: "Optional status view: 'fleet' for a read-only fleet surface, or 'transcript' with id/dir (and optional index) to tail a run transcript.",
 	})),
 	lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 500, description: "Maximum transcript lines for action='status', view='transcript'. Defaults to 80." })),
 	topic: Type.Optional(Type.String()),
 	message: Type.Optional(Type.String({ description: "Follow-up message for resume, live guidance for steer, or optional startup prompt for project.open." })),
-	mode: Type.Optional(Type.String({ enum: ["steer", "follow_up", "auto"], description: "Delivery mode for action='steer'. steer interrupts at the next safe point (default), follow_up waits for the next turn boundary, and auto follows up mid-turn but delivers immediately between turns." })),
-	steeringRecovery: Type.Optional(Type.Boolean({ description: "For action='steer', allow pause-and-revive recovery after a missed acknowledgment. Defaults true for direct tool calls in steer mode; extension RPC steering forces false so callers retain exact child ownership." })),
-	additional: Type.Optional(Type.Integer({ minimum: 1, description: "Positive launches to add with action='grant-spawn-budget'. Root interactive parent with native user confirmation only; total grants cannot exceed the original configured cap." })),
-	scope: Type.Optional(Type.String({ enum: ["session", "user", "project"], description: "Scope for action='watchdog.configure'. Defaults to session to avoid persistent settings writes unless user/project is explicit." })),
+	mode: Type.Optional(Type.String({ enum: ["steer", "follow_up", "auto"], description: "Delivery mode for action='steer': steer interrupts at the next safe point (default), follow_up waits for the next turn boundary, auto follows up mid-turn." })),
+	steeringRecovery: Type.Optional(Type.Boolean({ description: "For action='steer', allow pause-and-revive recovery after a missed acknowledgment. Defaults true for direct tool calls; false for extension RPC steering." })),
+	additional: Type.Optional(Type.Integer({ minimum: 1, description: "Positive launches to add with action='grant-spawn-budget'. Root interactive parent with native user confirmation only." })),
+	scope: Type.Optional(Type.String({ enum: ["session", "user", "project"], description: "Scope for action='watchdog.configure'. Defaults to session." })),
 	target: Type.Optional(Type.String({ enum: ["main", "children", "child"], description: "Target for watchdog actions." })),
 	focus: Type.Optional(Type.Boolean({ description: "Focus the new Herdr pane for inspector.open or project.open." })),
 	thinking: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "boolean", enum: [false] }], description: "Thinking level for action='watchdog.configure' (off/minimal/low/medium/high/xhigh/max, inherit, or false for off)." })),
-	schedule: Type.Optional(Type.String({ deprecated: true, description: "Removed one-shot schedule field. Use action='schedule.create' with at." })),
-	scheduleName: Type.Optional(Type.String({ deprecated: true, description: "Removed schedule display field. Use name." })),
+	schedule: Type.Optional(Type.String({ deprecated: true, description: "Deprecated. Use action='schedule.create' with at." })),
+	scheduleName: Type.Optional(Type.String({ deprecated: true, description: "Deprecated. Use name." })),
 	at: Type.Optional(Type.String({ description: "One-shot trigger for action='schedule.create': a relative delay such as '+10m' or an ISO timestamp with timezone." })),
 	every: Type.Optional(Type.String({ description: "Fixed recurring interval for action='schedule.create', such as '30m', '6h', '2d', or '2w'." })),
-	on: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "integer" }], description: "Calendar selector reserved for a later schedule slice." })),
-	timezone: Type.Optional(Type.String({ description: "IANA timezone reserved for a later calendar schedule slice." })),
+	on: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "integer" }], description: "Reserved for a later calendar schedule slice." })),
+	timezone: Type.Optional(Type.String({ description: "Reserved for a later calendar schedule slice." })),
 	overlap: Type.Optional(Type.String({ enum: ["skip"], description: "Overlap policy. This slice supports skip only." })),
 	catchUp: Type.Optional(Type.String({ enum: ["none", "latest"], description: "Missed occurrence policy for recurring schedules. Defaults to latest." })),
 	missionId: Type.Optional(Type.String({ description: "Mission id." })),
-	mission: Type.Optional(Type.Unsafe({ ...MissionLaunchOverride, description: "Mission object, or false for no mission. Set exactly one non-empty title or summary; objective and labels are optional. goal may only be true and then requires budget.tokens." })),
+	mission: Type.Optional(Type.Unsafe({ ...MissionLaunchOverride, description: "Mission object, or false for no mission. Requires exactly one non-empty title or summary; goal may only be true and then requires budget.tokens." })),
 	missionUpdate: Type.Optional(Type.Unsafe({ ...MissionUpdateOverride, description: "Mission update: objective, goal false or {paused:boolean}, budget, summary, labels, decisions, artifacts, or delivery receipts." })),
 	missionStatus: Type.Optional(Type.String({ description: "Mission status." })),
 	missionScope: Type.Optional(Type.String({ description: "Mission list scope: project (default) or global pointer index." })),
@@ -316,10 +316,10 @@ const SubagentParamProperties = {
 		],
 		description: "Agent/chain config for create/update. Object or JSON string; presence of steps creates a chain."
 	})),
-	workflowScript: Type.Optional(Type.String({ minLength: 1, description: "Trusted inline JavaScript statement body. Starts async by default; pass async:false for a small foreground run. Use explicit return for output. Use await prompts.render(ref, vars?) for task text. Use await runs.run(key, {agent, task, worktree?, gate?}) or runs.run(key, {resume, task}), runs.all([...]), runs.status(id), runs.ref(s), emit(value), console, and return. Mission workflows also have async state.get(key) and state.set(key, JSONValue). Compose sequential and parallel phases dynamically. Set worktree:true at workflow or child level for a separate managed worktree; child fields override workflow defaults. gate is one host-run command and cannot be combined with acceptance. runs.run accepts one child only. No filesystem, shell, Pi tools, or host globals." })),
+	workflowScript: Type.Optional(Type.String({ minLength: 1, description: "Trusted inline JavaScript statement body; use explicit return for output. Available: runs.run(key, {agent, task, ...}) and runs.run(key, {resume, task}), runs.all([...]), runs.status(id), runs.ref(s), await prompts.render(ref, vars?), emit, console; mission workflows also have async state.get/set. Scripts start async by default. Set worktree:true at workflow or child level for a separate managed worktree; child fields override workflow defaults. Compose sequential and parallel phases dynamically. No filesystem, shell, Pi tools, or host globals." })),
 	chain: Type.Optional(Type.Unsafe({
 		anyOf: [Type.Array(ChainItem, { minItems: 1, description: "Sequential chain of steps" })],
-		description: "Sequential chain of steps. Steps support template variables {task}, {previous}, {chain_dir}, and {outputs.name}; use as: \"name\" on a step to bind {outputs.name} for later steps, phase/label for status readability, outputSchema for structured results, and { checkpoint: \"name\", message?: \"...\" } for human gates paused until approve-checkpoint / reject-checkpoint. Set gateOn: \"acceptance\" to advance on acceptance instead of execution.",
+		description: "Sequential chain of steps. Steps support template variables {task}, {previous}, {chain_dir}, and {outputs.name}; use as: \"name\" on a step to bind {outputs.name} for later steps; { checkpoint: \"name\", message?: \"...\" } pauses for approve-checkpoint / reject-checkpoint; gateOn: \"acceptance\" advances on acceptance instead of execution.",
 	})),
 	tasks: Type.Optional(Type.Unsafe({
 		anyOf: [
@@ -328,27 +328,28 @@ const SubagentParamProperties = {
 		],
 		description: "Top-level parallel tasks array, or a single dynamic fanout child template when expand/collect are present.",
 	})),
-	chatProgress: Type.Optional(Type.String({ enum: ["auto", "off", "terminal", "milestones", "live-card"], description: "WorkflowScript chat progress projection. auto shows a live in-chat card for watched foreground workflows in the same Git repository, milestones for background runs, and terminal for other-repo work." })),
-	worktree: Type.Optional(Type.Boolean({ description: "Managed child isolation. true gives each workflow child a separate git worktree; an individual runs.run/runs.all item can override a workflow default with worktree:false." })),
+	chatProgress: Type.Optional(Type.String({ enum: ["auto", "off", "terminal", "milestones", "live-card"], description: "WorkflowScript chat progress projection: auto shows a live in-chat card for watched foreground workflows in the same Git repository, milestones for background runs, terminal otherwise." })),
+	worktree: Type.Optional(Type.Boolean({ description: "Managed child isolation. true gives each workflow child a separate git worktree; individual runs.run/runs.all items can override with worktree:false." })),
 	step: Type.Optional(Type.Unsafe({ ...ChainItem, description: "One chain step for action='append-step' only. Not an execution mode." })),
 	context: Type.Optional(Type.String({
 		enum: ["fresh", "fork"],
-		description: "'fresh' or 'fork' to branch from parent session. Explicit context overrides every child in the invocation. If omitted, each requested agent uses its own defaultContext; agents without defaultContext: 'fork' run fresh.",
+		description: "'fresh' or 'fork' to branch from parent session. Explicit context overrides every child in the invocation. If omitted, each requested agent uses its own defaultContext; agents without one run 'fork' fresh.",
 	})),
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
-	clarify: Type.Optional(Type.Boolean({ description: "Show TUI to preview/edit before execution. Explicit clarify: true keeps the run foreground for the clarify UI; omitted clarify can still run in the background when async: true is set." })),
-	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Timeout. Foreground and single async runs use config timeoutMs, else 30m; async composites have no default parent deadline. Alias maxRuntimeMs." })),
-	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias timeoutMs. Foreground and single async runs use config timeoutMs, else 30m; async composites have no default parent deadline." })),
+	clarify: Type.Optional(Type.Boolean({ description: "Show TUI to preview/edit before execution; explicit true keeps the run foreground." })),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Timeout. Defaults to config timeoutMs or 30m for foreground/single async runs. Alias maxRuntimeMs." })),
+	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias of timeoutMs." })),
+	toolTimeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Optional hard per-tool-call timeout in milliseconds." })),
 	turnBudget: Type.Optional(TurnBudgetOverride),
 	toolBudget: Type.Optional(ToolBudgetOverride),
 	usageBudget: Type.Optional(UsageBudgetOverride),
-	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
+	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default 'both')." })),
 	cwd: Type.Optional(Type.String({ description: "Execution cwd, or target project directory for project.open/status/close." })),
 	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: true)" })),
 	includeProgress: Type.Optional(Type.Boolean({ description: "Include full progress in result (default: false)" })),
 	share: Type.Optional(Type.Boolean({ description: "Upload session to GitHub Gist for sharing (default: false)" })),
 	sessionDir: Type.Optional(
-		Type.String({ description: "Directory to store session logs (default: temp; enables sessions even if share=false)" }),
+		Type.String({ description: "Directory to store session logs (default: temp)." }),
 	),
 	control: Type.Optional(ControlOverrides),
 	// Workflow defaults forwarded to each runs.run/runs.all child unless overridden there.
@@ -372,10 +373,10 @@ const { step: _legacyChainStep, ...subagentParamPropertiesWithoutStep } = Subage
 const trimmedSubagentParamProperties = {
 	...subagentParamPropertiesWithoutStep,
 	id: Type.Optional(Type.String({
-		description: "Run id or prefix for status, interrupt, stop, resume, steer, mission.attach-run, or the decision id for mission.resolve-decision."
+		description: "Run id/prefix for status/debug.run, interrupt, steer, or mission.attach-run."
 	})),
 	runId: Type.Optional(Type.String({
-		description: "Target run ID for interrupt, stop, resume, steer, or mission.attach-run. Prefer id for new calls."
+		description: "Target run ID for debug.run, interrupt, steer, or mission.attach-run. Prefer id."
 	})),
 };
 const SubagentParamsSchema = Type.Object(SubagentParamProperties);