pi-subagents 0.32.0 → 0.33.0

package/src/extension/rpc.ts

@@ -0,0 +1,369 @@
+import * as path from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Compile } from "typebox/compile";
+import { resolveAsyncRunLocation } from "../runs/background/async-resume.ts";
+import { deliverTimeoutRequest } from "../runs/background/control-channel.ts";
+import { reconcileAsyncRun } from "../runs/background/stale-run-reconciler.ts";
+import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
+import { type Details, ASYNC_DIR, RESULTS_DIR } from "../shared/types.ts";
+import { readStatus } from "../shared/utils.ts";
+import { SubagentParams } from "./schemas.ts";
+
+export const SUBAGENT_RPC_PROTOCOL_VERSION = 1;
+export const SUBAGENT_RPC_REQUEST_EVENT = "subagents:rpc:v1:request";
+export const SUBAGENT_RPC_READY_EVENT = "subagents:rpc:v1:ready";
+export const SUBAGENT_RPC_REPLY_EVENT_PREFIX = "subagents:rpc:v1:reply:";
+
+export const SUBAGENT_RPC_METHODS = ["ping", "status", "spawn", "interrupt", "stop"] as const;
+export type SubagentRpcMethod = typeof SUBAGENT_RPC_METHODS[number];
+
+export interface SubagentRpcRequestEnvelope {
+	version: typeof SUBAGENT_RPC_PROTOCOL_VERSION;
+	requestId: string;
+	method: SubagentRpcMethod;
+	params?: unknown;
+	source?: {
+		extension?: string;
+		[key: string]: unknown;
+	};
+}
+
+export type SubagentRpcReplyEnvelope<T = unknown> = {
+	version: typeof SUBAGENT_RPC_PROTOCOL_VERSION;
+	requestId: string;
+	method?: SubagentRpcMethod;
+	success: true;
+	data: T;
+} | {
+	version: typeof SUBAGENT_RPC_PROTOCOL_VERSION;
+	requestId: string;
+	method?: SubagentRpcMethod;
+	success: false;
+	error: {
+		code: SubagentRpcErrorCode;
+		message: string;
+	};
+};
+
+type SubagentRpcErrorCode =
+	| "invalid_request"
+	| "invalid_params"
+	| "unsupported_version"
+	| "unsupported_method"
+	| "no_active_session"
+	| "execution_failed"
+	| "not_found"
+	| "invalid_state";
+
+interface EventBus {
+	on(event: string, handler: (data: unknown) => void): (() => void) | void;
+	emit(event: string, data: unknown): void;
+}
+
+interface RegisterSubagentRpcBridgeOptions {
+	events: EventBus;
+	getContext: () => ExtensionContext | null;
+	execute: (
+		id: string,
+		params: SubagentParamsLike,
+		signal: AbortSignal,
+		onUpdate: ((result: AgentToolResult<Details>) => void) | undefined,
+		ctx: ExtensionContext,
+	) => Promise<AgentToolResult<Details>>;
+	asyncDirRoot?: string;
+	resultsDir?: string;
+	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+	now?: () => number;
+}
+
+class SubagentRpcError extends Error {
+	readonly code: SubagentRpcErrorCode;
+
+	constructor(code: SubagentRpcErrorCode, message: string) {
+		super(message);
+		this.name = "SubagentRpcError";
+		this.code = code;
+	}
+}
+
+const subagentParamsValidator = Compile(SubagentParams);
+
+export function subagentRpcReplyEvent(requestId: string): string {
+	return `${SUBAGENT_RPC_REPLY_EVENT_PREFIX}${requestId}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function assertRequestId(value: unknown): string {
+	if (typeof value !== "string" || value.trim().length === 0 || /[\r\n]/.test(value)) {
+		throw new SubagentRpcError("invalid_request", "RPC requestId must be a non-empty string without newlines.");
+	}
+	return value;
+}
+
+function assertRecordParams(params: unknown, method: SubagentRpcMethod): Record<string, unknown> {
+	if (params === undefined) return {};
+	if (!isRecord(params)) throw new SubagentRpcError("invalid_params", `RPC ${method} params must be an object.`);
+	return params;
+}
+
+function assertSubagentParams(params: SubagentParamsLike, label: string): void {
+	if (subagentParamsValidator.Check(params)) return;
+	const messages = [...subagentParamsValidator.Errors(params)]
+		.slice(0, 4)
+		.map((error) => error.message);
+	throw new SubagentRpcError("invalid_params", `${label}: ${messages.join("; ") || "invalid subagent parameters"}`);
+}
+
+function textFromToolResult(result: AgentToolResult<Details>): string {
+	return result.content
+		.filter((part): part is { type: "text"; text: string } => part.type === "text")
+		.map((part) => part.text)
+		.join("\n");
+}
+
+function dataFromToolResult(result: AgentToolResult<Details>): { text: string; details?: Details; isError?: boolean } {
+	return {
+		text: textFromToolResult(result),
+		...(result.details ? { details: result.details } : {}),
+		...(result.isError ? { isError: true } : {}),
+	};
+}
+
+function failIfToolError(result: AgentToolResult<Details>): void {
+	if (!result.isError) return;
+	throw new SubagentRpcError("execution_failed", textFromToolResult(result) || "Subagent RPC execution failed.");
+}
+
+function normalizeTargetParams(params: unknown, method: SubagentRpcMethod): Pick<SubagentParamsLike, "id" | "runId" | "dir" | "index"> {
+	const input = assertRecordParams(params, method);
+	const output: Pick<SubagentParamsLike, "id" | "runId" | "dir" | "index"> = {};
+	if (input.id !== undefined) output.id = input.id as string;
+	if (input.runId !== undefined) output.runId = input.runId as string;
+	if (input.dir !== undefined) output.dir = input.dir as string;
+	if (input.index !== undefined) output.index = input.index as number;
+	return output;
+}
+
+function sessionData(ctx: ExtensionContext | null): { cwd?: string; sessionId?: string; sessionFile?: string | null } {
+	if (!ctx) return {};
+	return {
+		cwd: ctx.cwd,
+		sessionId: ctx.sessionManager.getSessionId() ?? undefined,
+		sessionFile: ctx.sessionManager.getSessionFile() ?? null,
+	};
+}
+
+function pingData(ctx: ExtensionContext | null) {
+	return {
+		version: SUBAGENT_RPC_PROTOCOL_VERSION,
+		methods: [...SUBAGENT_RPC_METHODS],
+		capabilities: {
+			status: true,
+			asyncSpawn: true,
+			interrupt: true,
+			stop: true,
+		},
+		events: {
+			ready: SUBAGENT_RPC_READY_EVENT,
+			request: SUBAGENT_RPC_REQUEST_EVENT,
+			replyPrefix: SUBAGENT_RPC_REPLY_EVENT_PREFIX,
+		},
+		session: sessionData(ctx),
+	};
+}
+
+async function executeChecked(
+	options: RegisterSubagentRpcBridgeOptions,
+	ctx: ExtensionContext,
+	requestId: string,
+	method: SubagentRpcMethod,
+	params: SubagentParamsLike,
+): Promise<{ text: string; details?: Details; isError?: boolean }> {
+	assertSubagentParams(params, `RPC ${method} params`);
+	const controller = new AbortController();
+	const result = await options.execute(`rpc-${method}-${requestId}`, params, controller.signal, undefined, ctx);
+	failIfToolError(result);
+	return dataFromToolResult(result);
+}
+
+function spawnParams(params: unknown): SubagentParamsLike {
+	const input = assertRecordParams(params, "spawn");
+	if (input.action !== undefined) {
+		throw new SubagentRpcError("invalid_params", "RPC spawn does not accept management/control actions. Use status or interrupt RPC methods instead.");
+	}
+	if (input.async === false) {
+		throw new SubagentRpcError("invalid_params", "RPC spawn only supports detached async launches; omit async or set async: true.");
+	}
+	if (input.clarify === true) {
+		throw new SubagentRpcError("invalid_params", "RPC spawn cannot open the clarify UI; omit clarify or set clarify: false.");
+	}
+	return { ...(input as SubagentParamsLike), async: true, clarify: false };
+}
+
+function stopAsyncRun(
+	params: unknown,
+	options: RegisterSubagentRpcBridgeOptions,
+	ctx: ExtensionContext,
+): { runId: string; asyncDir: string; previousState: string; state: "stopping"; message: string } {
+	const target = normalizeTargetParams(params, "stop");
+	assertSubagentParams({ action: "status", ...target }, "RPC stop target params");
+	const asyncDirRoot = options.asyncDirRoot ?? ASYNC_DIR;
+	const resultsDir = options.resultsDir ?? RESULTS_DIR;
+	let location;
+	try {
+		location = resolveAsyncRunLocation(target, asyncDirRoot, resultsDir);
+	} catch (error) {
+		throw new SubagentRpcError("invalid_params", error instanceof Error ? error.message : String(error));
+	}
+	if (!location.asyncDir) {
+		throw new SubagentRpcError("not_found", "Async run not found or already completed; stop requires a live async run directory.");
+	}
+
+	const currentSessionId = ctx.sessionManager.getSessionId();
+	const initialStatus = readStatus(location.asyncDir);
+	const initialRunId = initialStatus?.runId ?? location.resolvedId ?? path.basename(location.asyncDir);
+	if (!initialStatus) throw new SubagentRpcError("not_found", `Status file not found for async run '${initialRunId}'.`);
+	if (!currentSessionId || initialStatus.sessionId !== currentSessionId) {
+		throw new SubagentRpcError("not_found", `Async run '${initialRunId}' was not found in the active session.`);
+	}
+
+	let status;
+	try {
+		status = reconcileAsyncRun(location.asyncDir, { resultsDir, kill: options.kill, now: options.now }).status;
+	} catch (error) {
+		throw new SubagentRpcError("execution_failed", error instanceof Error ? error.message : String(error));
+	}
+	const runId = status?.runId ?? initialRunId;
+	if (!status) throw new SubagentRpcError("not_found", `Status file not found for async run '${runId}'.`);
+	if (status.sessionId !== currentSessionId) {
+		throw new SubagentRpcError("not_found", `Async run '${runId}' was not found in the active session.`);
+	}
+	if (status.state !== "running") {
+		throw new SubagentRpcError("invalid_state", `Async run ${runId} is ${status.state}; stop only supports running async runs.`);
+	}
+
+	try {
+		deliverTimeoutRequest({
+			asyncDir: location.asyncDir,
+			pid: status.pid,
+			kill: options.kill,
+			now: options.now,
+			source: "rpc-stop",
+		});
+	} catch (error) {
+		throw new SubagentRpcError("execution_failed", error instanceof Error ? error.message : String(error));
+	}
+
+	return {
+		runId,
+		asyncDir: location.asyncDir,
+		previousState: status.state,
+		state: "stopping",
+		message: `Stop requested for async run ${runId}.`,
+	};
+}
+
+async function handleRequest(
+	request: SubagentRpcRequestEnvelope,
+	options: RegisterSubagentRpcBridgeOptions,
+): Promise<unknown> {
+	const ctx = options.getContext();
+	if (request.method === "ping") return pingData(ctx);
+	if (!ctx) throw new SubagentRpcError("no_active_session", "No active extension context for subagent RPC.");
+
+	if (request.method === "spawn") {
+		return executeChecked(options, ctx, request.requestId, request.method, spawnParams(request.params));
+	}
+	if (request.method === "status") {
+		return executeChecked(options, ctx, request.requestId, request.method, { action: "status", ...normalizeTargetParams(request.params, "status") });
+	}
+	if (request.method === "interrupt") {
+		return executeChecked(options, ctx, request.requestId, request.method, { action: "interrupt", ...normalizeTargetParams(request.params, "interrupt") });
+	}
+	if (request.method === "stop") {
+		return stopAsyncRun(request.params, options, ctx);
+	}
+	throw new SubagentRpcError("unsupported_method", `Unsupported subagent RPC method: ${String(request.method)}`);
+}
+
+function parseRequest(raw: unknown): SubagentRpcRequestEnvelope {
+	if (!isRecord(raw)) throw new SubagentRpcError("invalid_request", "Subagent RPC request must be an object.");
+	const requestId = assertRequestId(raw.requestId);
+	if (raw.version !== SUBAGENT_RPC_PROTOCOL_VERSION) {
+		throw new SubagentRpcError("unsupported_version", `Unsupported subagent RPC version: ${String(raw.version)}.`);
+	}
+	if (typeof raw.method !== "string" || !(SUBAGENT_RPC_METHODS as readonly string[]).includes(raw.method)) {
+		throw new SubagentRpcError("unsupported_method", `Unsupported subagent RPC method: ${String(raw.method)}.`);
+	}
+	return {
+		version: SUBAGENT_RPC_PROTOCOL_VERSION,
+		requestId,
+		method: raw.method as SubagentRpcMethod,
+		...(raw.params !== undefined ? { params: raw.params } : {}),
+		...(isRecord(raw.source) ? { source: raw.source as SubagentRpcRequestEnvelope["source"] } : {}),
+	};
+}
+
+function safeReplyRequestId(raw: unknown): string {
+	if (!isRecord(raw)) return "unknown";
+	const requestId = raw.requestId;
+	return typeof requestId === "string" && requestId.trim().length > 0 && !/[\r\n]/.test(requestId)
+		? requestId
+		: "unknown";
+}
+
+function errorReply(raw: unknown, error: unknown): SubagentRpcReplyEnvelope {
+	const requestId = safeReplyRequestId(raw);
+	const method = isRecord(raw) && typeof raw.method === "string" && (SUBAGENT_RPC_METHODS as readonly string[]).includes(raw.method)
+		? raw.method as SubagentRpcMethod
+		: undefined;
+	const rpcError = error instanceof SubagentRpcError
+		? error
+		: new SubagentRpcError("execution_failed", error instanceof Error ? error.message : String(error));
+	return {
+		version: SUBAGENT_RPC_PROTOCOL_VERSION,
+		requestId,
+		...(method ? { method } : {}),
+		success: false,
+		error: {
+			code: rpcError.code,
+			message: rpcError.message,
+		},
+	};
+}
+
+export function registerSubagentRpcBridge(options: RegisterSubagentRpcBridgeOptions): {
+	emitReady: (ctx?: ExtensionContext | null) => void;
+	dispose: () => void;
+} {
+	const unsubscribe = options.events.on(SUBAGENT_RPC_REQUEST_EVENT, async (raw) => {
+		let request: SubagentRpcRequestEnvelope | undefined;
+		try {
+			request = parseRequest(raw);
+			const data = await handleRequest(request, options);
+			options.events.emit(subagentRpcReplyEvent(request.requestId), {
+				version: SUBAGENT_RPC_PROTOCOL_VERSION,
+				requestId: request.requestId,
+				method: request.method,
+				success: true,
+				data,
+			} satisfies SubagentRpcReplyEnvelope);
+		} catch (error) {
+			const reply = errorReply(request ?? raw, error);
+			options.events.emit(subagentRpcReplyEvent(reply.requestId), reply);
+		}
+	});
+
+	return {
+		emitReady: (ctx) => {
+			options.events.emit(SUBAGENT_RPC_READY_EVENT, pingData(ctx ?? options.getContext()));
+		},
+		dispose: () => {
+			if (typeof unsubscribe === "function") unsubscribe();
+		},
+	};
+}

package/src/extension/schemas.ts

@@ -3,7 +3,6 @@
  */
 
 import { Type } from "typebox";
-import { SUBAGENT_ACTIONS } from "../shared/types.ts";
 
 function keepTopLevelParameterDescriptions<T>(schema: T): T {
 	return pruneNestedDescriptions(schema, []) as T;
@@ -75,6 +74,24 @@ const AcceptanceOverride = Type.Unsafe({
 	description: "Optional acceptance policy. Omitted means auto-inferred; verified requires configured runtime commands.",
 });
 
+const TurnBudgetOverride = Type.Object({
+	maxTurns: Type.Integer({ minimum: 1 }),
+	graceTurns: Type.Optional(Type.Integer({ minimum: 0 })),
+}, { additionalProperties: false, description: "Optional assistant-turn budget. At maxTurns the child is asked to wrap up; after graceTurns additional assistant turns it is aborted and partial output is returned." });
+
+const ToolBudgetBlock = Type.Unsafe({
+	anyOf: [
+		{ type: "array", minItems: 1, items: { type: "string", minLength: 1 } },
+		{ type: "string", enum: ["*"] },
+	],
+});
+
+const ToolBudgetOverride = Type.Object({
+	soft: Type.Optional(Type.Integer({ minimum: 1 })),
+	hard: Type.Integer({ minimum: 1 }),
+	block: Type.Optional(ToolBudgetBlock),
+}, { additionalProperties: false, description: "Optional child tool-call budget. soft nudges the child; after hard, block tools (default read/grep/find/ls, or '*' for all tools) are blocked so the child can finalize." });
+
 const TaskItem = Type.Object({
 	agent: Type.String(), 
 	task: Type.String(), 
@@ -86,6 +103,7 @@ const TaskItem = Type.Object({
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking for this task" })),
 	model: Type.Optional(Type.String({ description: "Override model for this task (e.g. 'google/gemini-3-pro')" })),
 	skill: Type.Optional(SkillOverride),
+	toolBudget: Type.Optional(ToolBudgetOverride),
 	acceptance: Type.Optional(AcceptanceOverride),
 });
 
@@ -105,6 +123,7 @@ const ParallelTaskSchema = Type.Object({
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for this task" })),
+	toolBudget: Type.Optional(ToolBudgetOverride),
 	acceptance: Type.Optional(AcceptanceOverride),
 });
 
@@ -132,6 +151,7 @@ const DynamicParallelTemplateSchema = Type.Object({
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for this task" })),
+	toolBudget: Type.Optional(ToolBudgetOverride),
 	acceptance: Type.Optional(AcceptanceOverride),
 }, { additionalProperties: false });
 
@@ -157,6 +177,7 @@ const ChainItem = Type.Object({
 	progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for this step" })),
+	toolBudget: Type.Optional(ToolBudgetOverride),
 	acceptance: Type.Optional(AcceptanceOverride),
 	parallel: Type.Optional(Type.Unsafe({
 		anyOf: [
@@ -197,20 +218,26 @@ const SubagentParamsSchema = Type.Object({
 	task: Type.Optional(Type.String({ description: "Task (SINGLE mode, optional for self-contained agents)" })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({
-		enum: [...SUBAGENT_ACTIONS],
-		description: "Management/control action. Omit for execution mode."
+		description: "Management/control action only. Must be omitted for execution mode (single, parallel, or chain)."
 	})),
 	id: Type.Optional(Type.String({
-		description: "Run id or prefix for action='status', action='interrupt', action='resume', or action='append-step'."
+		description: "Run id or prefix for action='status', action='interrupt', action='resume', action='steer', or action='append-step'."
 	})),
 	runId: Type.Optional(Type.String({
-		description: "Target run ID for action='interrupt', action='resume', or action='append-step'. Defaults to the most recently active controllable run for interrupt. Prefer id for new calls."
+		description: "Target run ID for action='interrupt', action='resume', action='steer', or action='append-step'. Defaults to the most recently active controllable run for interrupt. Prefer id for new calls."
 	})),
 	dir: Type.Optional(Type.String({
-		description: "Async run directory for action='status' or action='resume'."
+		description: "Async run directory for action='status', action='resume', or action='steer'."
+	})),
+	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.",
 	})),
-	index: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based child index for actions that target a specific child." })),
-	message: Type.Optional(Type.String({ description: "Follow-up message for action='resume'. Use index to choose a child from multi-child runs." })),
+	lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 500, description: "Maximum transcript lines for action='status', view='transcript'. Defaults to 80." })),
+	message: Type.Optional(Type.String({ description: "Follow-up message for action='resume' or non-terminal guidance for action='steer'. Use index to choose a child from multi-child runs." })),
+	schedule: Type.Optional(Type.String({ description: "Explicit one-shot schedule for action='schedule'. Only honored when scheduledRuns.enabled is true. Use '+10m' or a future ISO timestamp with timezone; scheduled runs always launch async with fresh context." })),
+	scheduleName: Type.Optional(Type.String({ description: "Optional display name for action='schedule'." })),
 	// Chain identifier for management (can't reuse 'chain' — that's the execution array)
 	chainName: Type.Optional(Type.String({
 		description: "Chain name for get/update/delete management actions"
@@ -237,6 +264,8 @@ const SubagentParamsSchema = Type.Object({
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
 	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Optional run-level timeout in ms for foreground and async/background runs. Alias of maxRuntimeMs." })),
 	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias of timeoutMs for optional run-level timeout in foreground and async/background runs." })),
+	turnBudget: Type.Optional(TurnBudgetOverride),
+	toolBudget: Type.Optional(ToolBudgetOverride),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
 	cwd: Type.Optional(Type.String()),
 	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: true)" })),
@@ -263,3 +292,18 @@ const SubagentParamsSchema = Type.Object({
 });
 
 export const SubagentParams = keepTopLevelParameterDescriptions(SubagentParamsSchema);
+
+const WaitParamsSchema = Type.Object({
+	id: Type.Optional(Type.String({
+		description: "Run id or prefix to wait for one specific run. Omit to wait across every active async run started in this session.",
+	})),
+	all: Type.Optional(Type.Boolean({
+		description: "Wait for ALL active runs to finish. Default false: return as soon as the first run finishes, so a fleet manager can spawn a replacement and wait again. Ignored when id targets a single run.",
+	})),
+	timeoutMs: Type.Optional(Type.Integer({
+		minimum: 1,
+		description: "Give up waiting after this many milliseconds (the runs keep going regardless). Defaults to 1800000 (30 minutes).",
+	})),
+});
+
+export const WaitParams = keepTopLevelParameterDescriptions(WaitParamsSchema);