@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/src/runs/foreground/subagent-params.ts

@@ -0,0 +1,320 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type AgentConfig, type AgentDiscoveryOptions, type AgentScope } from "../../agents/agents.ts";
+import { materializeAgentDefaultOutputPath, normalizeSingleOutputOverride } from "../shared/single-output.ts";
+import type { IntercomBridgeState } from "../../intercom/intercom-bridge.ts";
+import {
+	type ChainStep,
+	type DynamicParallelStep,
+	type ParallelStep,
+	type SequentialStep,
+} from "../../shared/settings.ts";
+import {
+	type AcceptanceInput,
+	type ControlConfig,
+	type ExtensionConfig,
+	type JsonSchemaObject,
+	type MaxOutputConfig,
+	type ManagementRunState,
+	type NestedRouteInfo,
+	type ResolvedControlConfig,
+	type SingleResult,
+	type SubagentExecutionResult,
+	type SubagentRunMode,
+	type SubagentState,
+} from "../../shared/types.ts";
+
+export function maxParallelTasksMessage(maxParallelTasks: number): string {
+	return `Max ${maxParallelTasks} tasks. Split the batch into smaller parallel calls or raise parallel.maxTasks in ~/.pi/agent/extensions/subagent/config.json.`;
+}
+
+export interface TaskParam {
+	agent: string;
+	task: string;
+	label?: string;
+	cwd?: string;
+	count?: number;
+	outputSchema?: JsonSchemaObject;
+	output?: string | boolean;
+	outputMode?: "inline" | "file-only";
+	reads?: string[] | boolean;
+	progress?: boolean;
+	model?: string;
+	skill?: string | string[] | boolean;
+	acceptance?: AcceptanceInput;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isTaskParamLike(value: unknown): value is TaskParam {
+	return isRecord(value) && typeof value.agent === "string";
+}
+
+function isDynamicParallelStepLike(value: unknown): value is DynamicParallelStep {
+	return isRecord(value)
+		&& isRecord(value.expand)
+		&& isRecord(value.parallel)
+		&& typeof value.parallel.agent === "string"
+		&& isRecord(value.collect)
+		&& typeof value.collect.as === "string";
+}
+
+function isParallelStepLike(value: unknown): value is ParallelStep {
+	return isRecord(value) && Array.isArray(value.parallel) && value.parallel.every(isTaskParamLike);
+}
+
+function isSequentialStepLike(value: unknown): value is SequentialStep {
+	return isRecord(value) && typeof value.agent === "string";
+}
+
+function isChainStepLike(value: unknown): value is ChainStep {
+	if (!isRecord(value)) return false;
+	return isDynamicParallelStepLike(value) || isParallelStepLike(value) || isSequentialStepLike(value);
+}
+
+export interface SubagentParamsLike {
+	action?: string;
+	id?: string;
+	runId?: string;
+	questionId?: string;
+	decision?: "accepted" | "needs_changes";
+	offset?: number;
+	limit?: number;
+	cursor?: string;
+	sort?: "attention" | "newest" | "oldest" | "relevance";
+	state?: ManagementRunState;
+	text?: string;
+	query?: string;
+	before?: number;
+	full?: boolean;
+	dir?: string;
+	index?: number;
+	agent?: string;
+	task?: string;
+	label?: string;
+	message?: string;
+	/** Internal human-view provenance; not accepted by the model tool schema. */
+	messageOrigin?: "human";
+	chain?: ChainStep[];
+	tasks?: TaskParam[];
+	concurrency?: number;
+	timeoutMs?: number;
+	maxRuntimeMs?: number;
+	extendMs?: number;
+	worktree?: boolean;
+	context?: "fresh" | "fork";
+	async?: boolean;
+	clarify?: boolean;
+	share?: boolean;
+	control?: ControlConfig;
+	sessionDir?: string;
+	cwd?: string;
+	maxOutput?: MaxOutputConfig;
+	artifacts?: boolean;
+	includeProgress?: boolean;
+	progress?: boolean;
+	model?: string;
+	skill?: string | string[] | boolean;
+	output?: string | boolean;
+	outputMode?: "inline" | "file-only";
+	outputSchema?: JsonSchemaObject;
+	agentScope?: string;
+	chainName?: string;
+	config?: unknown;
+	chainDir?: string;
+	acceptance?: AcceptanceInput;
+}
+
+export function resolveAsyncExecutionMode(
+	params: Pick<SubagentParamsLike, "async" | "clarify" | "timeoutMs" | "maxRuntimeMs">,
+	asyncByDefault: boolean,
+): { effectiveAsync: boolean; backgroundRequestedWhileClarifying: boolean } {
+	const hasForegroundTimeout = params.timeoutMs !== undefined || params.maxRuntimeMs !== undefined;
+	const requestedAsync = params.async ?? (hasForegroundTimeout ? false : asyncByDefault);
+	return {
+		effectiveAsync: requestedAsync && params.clarify !== true,
+		backgroundRequestedWhileClarifying: params.async === true && params.clarify === true,
+	};
+}
+
+type RawSubagentParamsLike = Record<string, unknown>;
+
+function stringValue(params: RawSubagentParamsLike, key: string): string | undefined {
+	const value = params[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+function booleanValue(params: RawSubagentParamsLike, key: string): boolean | undefined {
+	const value = params[key];
+	return typeof value === "boolean" ? value : undefined;
+}
+
+function numberValue(params: RawSubagentParamsLike, key: string): number | undefined {
+	const value = params[key];
+	return typeof value === "number" ? value : undefined;
+}
+
+function contextValue(params: RawSubagentParamsLike): SubagentParamsLike["context"] {
+	const value = params.context;
+	return value === "fresh" || value === "fork" ? value : undefined;
+}
+
+function outputModeValue(params: RawSubagentParamsLike): SubagentParamsLike["outputMode"] {
+	const value = params.outputMode;
+	return value === "inline" || value === "file-only" ? value : undefined;
+}
+
+function outputValue(params: RawSubagentParamsLike): SubagentParamsLike["output"] {
+	const value = params.output;
+	return typeof value === "string" || typeof value === "boolean" ? value : undefined;
+}
+
+export function usesAgentDefaultOutput(output: string | boolean | undefined): boolean {
+	return output === undefined || output === true || output === "true";
+}
+
+export function resolveTopLevelOutputOverride(params: {
+	requestedOutput: string | boolean | undefined;
+	agentDefaultOutput: string | false | undefined;
+	artifactsDir: string;
+	runId: string;
+	agent: string;
+	index?: number;
+}): string | false | undefined {
+	const effectiveOutput = usesAgentDefaultOutput(params.requestedOutput)
+		? normalizeSingleOutputOverride(true, params.agentDefaultOutput)
+		: normalizeSingleOutputOverride(params.requestedOutput, params.agentDefaultOutput);
+	if (!usesAgentDefaultOutput(params.requestedOutput)) return effectiveOutput;
+	return materializeAgentDefaultOutputPath({
+		output: effectiveOutput,
+		artifactsDir: params.artifactsDir,
+		runId: params.runId,
+		agent: params.agent,
+		index: params.index,
+	});
+}
+
+function skillValue(params: RawSubagentParamsLike): SubagentParamsLike["skill"] {
+	const value = params.skill;
+	if (typeof value === "string" || typeof value === "boolean") return value;
+	return Array.isArray(value) && value.every((item) => typeof item === "string") ? value : undefined;
+}
+
+function maxOutputValue(params: RawSubagentParamsLike): MaxOutputConfig | undefined {
+	const value = params.maxOutput;
+	if (!isRecord(value)) return undefined;
+	return {
+		...(typeof value.bytes === "number" ? { bytes: value.bytes } : {}),
+		...(typeof value.lines === "number" ? { lines: value.lines } : {}),
+	};
+}
+
+function isControlConfig(value: unknown): value is ControlConfig {
+	return isRecord(value);
+}
+
+function isAcceptanceInput(value: unknown): value is AcceptanceInput {
+	return isRecord(value);
+}
+
+export function normalizeSubagentParamsLike(params: RawSubagentParamsLike): SubagentParamsLike {
+	const normalized: SubagentParamsLike = {
+		action: stringValue(params, "action"),
+		id: stringValue(params, "id"),
+		runId: stringValue(params, "runId"),
+		questionId: stringValue(params, "questionId"),
+		decision: params.decision === "accepted" || params.decision === "needs_changes" ? params.decision : undefined,
+		offset: numberValue(params, "offset"),
+		limit: numberValue(params, "limit"),
+		cursor: stringValue(params, "cursor"),
+		sort: ["attention", "newest", "oldest", "relevance"].includes(String(params.sort)) ? params.sort as SubagentParamsLike["sort"] : undefined,
+		state: ["live", "completed", "failed", "blocked", "paused", "unknown"].includes(String(params.state)) ? params.state as ManagementRunState : undefined,
+		text: stringValue(params, "text"),
+		query: stringValue(params, "query"),
+		before: numberValue(params, "before"),
+		full: booleanValue(params, "full"),
+		dir: stringValue(params, "dir"),
+		index: numberValue(params, "index"),
+		agent: stringValue(params, "agent"),
+		task: stringValue(params, "task"),
+		label: stringValue(params, "label"),
+		message: stringValue(params, "message"),
+		concurrency: numberValue(params, "concurrency"),
+		timeoutMs: numberValue(params, "timeoutMs"),
+		maxRuntimeMs: numberValue(params, "maxRuntimeMs"),
+		extendMs: numberValue(params, "extendMs"),
+		worktree: booleanValue(params, "worktree"),
+		context: contextValue(params),
+		async: booleanValue(params, "async"),
+		clarify: booleanValue(params, "clarify"),
+		share: booleanValue(params, "share"),
+		control: isControlConfig(params.control) ? params.control : undefined,
+		sessionDir: stringValue(params, "sessionDir"),
+		cwd: stringValue(params, "cwd"),
+		maxOutput: maxOutputValue(params),
+		artifacts: booleanValue(params, "artifacts"),
+		includeProgress: booleanValue(params, "includeProgress"),
+		progress: booleanValue(params, "progress"),
+		model: stringValue(params, "model"),
+		skill: skillValue(params),
+		output: outputValue(params),
+		outputMode: outputModeValue(params),
+		outputSchema: isRecord(params.outputSchema) ? params.outputSchema : undefined,
+		agentScope: stringValue(params, "agentScope"),
+		chainName: stringValue(params, "chainName"),
+		config: params.config,
+		chainDir: stringValue(params, "chainDir"),
+		acceptance: isAcceptanceInput(params.acceptance) ? params.acceptance : undefined,
+	};
+	if (params.tasks !== undefined) {
+		if (!Array.isArray(params.tasks) || !params.tasks.every(isTaskParamLike)) {
+			throw new Error("tasks must be an array of task objects with an agent.");
+		}
+		normalized.tasks = params.tasks;
+	}
+	if (params.chain !== undefined) {
+		if (!Array.isArray(params.chain) || !params.chain.every(isChainStepLike)) {
+			throw new Error("chain must contain valid sequential, parallel, or dynamic fanout steps.");
+		}
+		normalized.chain = params.chain;
+	}
+	return normalized;
+}
+
+export interface ExecutorDeps {
+	pi: ExtensionAPI;
+	state: SubagentState;
+	config: ExtensionConfig;
+	asyncByDefault: boolean;
+	tempArtifactsDir: string;
+	getSubagentSessionRoot: (parentSessionFile: string | null) => string;
+	expandTilde: (p: string) => string;
+	discoverAgents: (cwd: string, scope: AgentScope, options?: AgentDiscoveryOptions) => { agents: AgentConfig[] };
+	allowMutatingManagementActions?: boolean;
+	ensureSessionState?: (ctx: ExtensionContext) => void | Promise<void>;
+}
+
+export interface ExecutionContextData {
+	params: SubagentParamsLike;
+	effectiveCwd: string;
+	ctx: ExtensionContext;
+	signal: AbortSignal | undefined;
+	onUpdate?: (r: SubagentExecutionResult) => void;
+	agents: AgentConfig[];
+	runId: string;
+	shareEnabled: boolean;
+	sessionRoot: string;
+	sessionDirForIndex: (idx?: number) => string;
+	sessionFileForIndex: (idx?: number) => string | undefined;
+	sessionFileForAgentIndex: (agentName: string | undefined, idx?: number) => string | undefined;
+	artifactsEnabled: boolean;
+	artifactsDir: string;
+	backgroundRequestedWhileClarifying: boolean;
+	effectiveAsync: boolean;
+	foregroundTimeoutMs?: number;
+	controlConfig: ResolvedControlConfig;
+	intercomBridge: IntercomBridgeState;
+	nestedRoute?: NestedRouteInfo;
+	onDetachedResultsSettled?: (mode: SubagentRunMode, results: SingleResult[], totalSteps?: number) => void;
+}

package/src/runs/foreground/wait-run.ts

@@ -0,0 +1,124 @@
+import * as path from "node:path";
+import { writeAsyncControlRequest } from "../background/async-control.ts";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ownedRunExecutionResult, ownedRunProgressResult, ownedRunStatusResult, ownedRunView, resolveOwnedRun } from "../shared/run-records.ts";
+import { formatSupervisorQuestions, getRunMetadataDir, listOwnedRunQuestions, questionProcessAlive, readRunJson, supervisorQuestionPage } from "../shared/supervisor-questions.ts";
+import { formatRunAction } from "../../shared/status-format.ts";
+import { getSingleResultOutput, readStatus } from "../../shared/utils.ts";
+import { INTERCOM_DETACH_REQUEST_EVENT, INTERCOM_DETACH_RESPONSE_EVENT, POLL_INTERVAL_MS, type OwnedRun, type SubagentExecutionResult } from "../../shared/types.ts";
+import { resolveSubagentRunId } from "../background/run-id-resolver.ts";
+import { resolveNestedAsyncDir } from "../shared/nested-events.ts";
+import { nestedResolutionScopeForExecutor } from "./foreground-control.ts";
+import type { ExecutorDeps } from "./subagent-params.ts";
+
+/** Wait on the saved outcome, not the transient notification file or an early terminal status. */
+export async function waitForOwnedRun(input: {
+	id: string;
+	index?: number;
+	deps: ExecutorDeps;
+	ctx: ExtensionContext;
+	signal?: AbortSignal;
+	onUpdate?: (result: SubagentExecutionResult) => void;
+	cancelNewRun?: boolean;
+	executionResult?: boolean;
+	includeProgress?: boolean;
+}): Promise<SubagentExecutionResult> {
+	const { deps, id, index, ctx } = input;
+	const owner = ctx.sessionManager.getSessionId(), session = deps.state.currentSessionId;
+	let run: OwnedRun | undefined, nested = false;
+	try {
+		run = resolveOwnedRun(deps.state, id);
+		if (!run) {
+			const resolved = resolveSubagentRunId(id, { state: deps.state, nested: nestedResolutionScopeForExecutor(deps) });
+			if (resolved?.kind === "nested") {
+				const asyncDir = resolveNestedAsyncDir(resolved.match.rootRunId, resolved.match.run);
+				const status = asyncDir ? readStatus(asyncDir) : null;
+				if (status?.runId === resolved.id) {
+					const savedOwner = readRunJson<{ sessionId: string }>(path.join(getRunMetadataDir(resolved.id), "question-owner.json"));
+					// Read through the authorized route without adopting the descendant or attributing its usage to this caller.
+					run = { runId: resolved.id, rootRunId: resolved.match.rootRunId, ownerSessionId: savedOwner?.sessionId ?? status.sessionId ?? "",
+						source: "async", mode: status.mode, cwd: status.cwd ?? "", task: "Nested delegated run", startedAt: status.startedAt, asyncDir, pid: status.pid,
+						children: (status.steps ?? []).map((step, index) => ({ agent: step.agent, index, sessionFile: step.sessionFile })) };
+					nested = true;
+				}
+			}
+		}
+	} catch (error) {
+		return { content: [{ type: "text", text: String(error) }], isError: true, details: { mode: "management", results: [] } };
+	}
+	if (!run || (!nested && run.ownerSessionId !== owner)) return { content: [{ type: "text", text: "Run is not available to wait on in this session. This wait did not start or stop work." }], isError: true, details: { mode: "management", results: [] } };
+	const target = run;
+	const waiting = deps.state.waitingRuns ??= new Map();
+	waiting.set(target.runId, (waiting.get(target.runId) ?? 0) + 1);
+	return new Promise((resolve) => {
+		let finished = false, timer: ReturnType<typeof setInterval> | undefined, unsubscribe: (() => void) | undefined;
+		let previous = "";
+		const finish = (status: "completed" | "cancelled" | "yielded" | "awaiting_input" | "unavailable", text: string, result?: SubagentExecutionResult) => {
+			if (finished) return;
+			finished = true;
+			const remaining = (waiting.get(target.runId) ?? 1) - 1;
+			if (remaining) waiting.set(target.runId, remaining); else waiting.delete(target.runId);
+			if (timer) clearInterval(timer);
+			unsubscribe?.(); input.signal?.removeEventListener("abort", abort);
+			const execution = input.executionResult && status === "completed" ? ownedRunExecutionResult(target, deps.state, index, input.includeProgress) : undefined;
+			const saved = status === "completed" ? readRunJson<{ completionId?: string }>(path.join(getRunMetadataDir(target.runId), "result.json")) : undefined;
+			resolve({ ...result, ...execution, content: status === "completed" && execution ? execution.content : [{ type: "text", text }],
+				...(status === "unavailable" || status === "cancelled" ? { isError: true } : {}),
+				details: { mode: "management", results: [], ...result?.details, ...execution?.details, wait: { runId: target.runId, completionId: saved?.completionId, index, status } } });
+		};
+		const abort = () => {
+			if (input.cancelNewRun && target.asyncDir) {
+				writeAsyncControlRequest(target.asyncDir, target.runId, "cancel");
+			}
+			finish("cancelled", input.cancelNewRun ? `Wait cancelled; cancellation requested for newly launched run ${target.runId}. Process exit is not yet confirmed.` : `Stopped waiting for ${target.runId}. The child was not stopped; completion will arrive automatically.`);
+		};
+		const check = () => {
+			if (deps.state.currentSessionId !== session || ctx.sessionManager.getSessionId() !== owner) { finish("unavailable", "The owning session changed. This wait ended without stopping the child."); return; }
+			try {
+				const runQuestions = listOwnedRunQuestions(target.ownerSessionId, target.runId);
+				// Poll execution facts once. Native conversation configuration is only
+				// needed when returning an inspection, never for live progress.
+				const view = ownedRunView(target, deps.state, {
+					pendingInput: runQuestions.some((question) => question.state === "awaiting_input" || question.state === "answer_pending"),
+					readConfiguration: false, includeContinuations: false,
+				});
+				const children = view.children.filter((child) => index === undefined || child.index === index);
+				if (index !== undefined && !children.length) { finish("unavailable", `Run ${target.runId} has no child at index ${index}.`); return; }
+				const questions = runQuestions.filter((question) => question.ownerSessionId === owner && (index === undefined || question.index === index) && question.state === "awaiting_input");
+				if (questions.length) {
+					const result = ownedRunStatusResult(target, deps.state);
+					const page = supervisorQuestionPage(questions), childSafe = Boolean(nestedResolutionScopeForExecutor(deps));
+					Object.assign(result.details, page);
+					finish("awaiting_input", `Run ${target.runId} needs input; waiting ended without stopping it.\n\n${formatSupervisorQuestions(page.questions, childSafe)}\n\nAll questions: ${formatRunAction("questions", target.runId, index === undefined ? {} : { index }, childSafe)}`, result); return;
+				}
+				if ((index !== undefined || view.resultPath) && children.every((child) => child.result && child.state !== "live" && child.state !== "unknown") && (index !== undefined || view.state !== "live")) {
+					const result = ownedRunStatusResult(target, deps.state);
+					result.isError = children.some((child) => child.state === "failed") || (index === undefined && view.state === "failed") || undefined;
+					finish("completed", [`Saved result for ${target.runId}${index !== undefined ? ` child ${index}` : ""}: ${index !== undefined ? children[0]!.state : view.state}`, ...children.map((child) => `\n${child.agent}: ${child.state}\n${getSingleResultOutput(child.result!) || child.result?.error || "(no output)"}`), result.content.map((part) => part.type === "text" ? part.text : "").join("\n")].join("\n"), result);
+					return;
+				}
+				const pid = target.pid ?? (target.asyncDir ? readStatus(target.asyncDir)?.pid : undefined);
+				const producerAlive = pid ? questionProcessAlive({ pid }) : children.some((child) => child.state === "live");
+				if (!producerAlive) { finish("unavailable", `No saved final result is available for ${target.runId}; completion is unconfirmed. Inspect the saved session. No work was started.`, ownedRunStatusResult(target, deps.state)); return; }
+				const update = `Waiting for ${target.runId}${index !== undefined ? ` child ${index}` : ""}: ${children.map((child) => child.state).join(", ")}. ${input.cancelNewRun ? "Cancelling requests cancellation of this newly launched run; process exit still needs confirmation." : "Cancelling this wait leaves existing work alive."}`;
+				if (input.onUpdate) {
+					const progress = ownedRunProgressResult(target, deps.state, index, view);
+					const signature = JSON.stringify(progress.details.progress?.map(({ durationMs: _duration, ...activity }) => activity));
+					if (signature !== previous) { previous = signature; input.onUpdate({ ...progress, content: [{ type: "text", text: update }, ...progress.content] }); }
+				}
+			} catch (error) { finish("unavailable", `Wait could not read ${target.runId}: ${error instanceof Error ? error.message : String(error)}`); }
+		};
+		unsubscribe = deps.pi.events.on(INTERCOM_DETACH_REQUEST_EVENT, (payload) => {
+			if (finished || !payload || typeof payload !== "object") return;
+			const requestId = (payload as { requestId?: unknown }).requestId;
+			if (typeof requestId !== "string") return;
+			deps.pi.events.emit(INTERCOM_DETACH_RESPONSE_EVENT, { requestId, accepted: true });
+			finish("yielded", `Released the wait for an incoming Intercom message. Run ${target.runId} is unchanged. Continue useful work or end the turn; completion will arrive automatically.`);
+		});
+		input.signal?.addEventListener("abort", abort, { once: true });
+		if (input.signal?.aborted) abort(); else check();
+		// Unlike passive background tracking, this foreground call owes a result.
+		// The detached runner cannot keep this process alive; finish() releases the timer.
+		if (!finished) timer = setInterval(check, POLL_INTERVAL_MS);
+	});
+}