@selesai/code 0.5.20 → 0.5.21

package/dist/extensions/pi-subagents/src/extension/chain-validation.ts

@@ -0,0 +1,165 @@
+/**
+ * Friendly chain parameter validation.
+ *
+ * The runtime (pi-ai) validates tool arguments against the TypeBox schema before
+ * the tool's `execute` runs. When a chain step has an extra property, the model
+ * receives a raw TypeBox message such as `chain.1: must not have additional
+ * properties` — which does not name the offending property, list the allowed
+ * ones, or show the expected shape. Agents then iteratively guess the format and
+ * waste several turns before getting it right.
+ *
+ * `validateChainInput` runs from the tool's `prepareArguments` shim (and the RPC
+ * bridge) *before* schema validation. It throws a rich, actionable error for the
+ * common chain-shape failures, so the model sees which property is disallowed,
+ * what is allowed, and a valid example — instead of a raw TypeBox diagnostic.
+ *
+ * Allowed property names and additional-property strictness are derived directly
+ * from the schema objects in `schemas.ts` so this stays aligned with TypeBox.
+ */
+
+import {
+	ChainItem,
+	ParallelTaskSchema,
+	DynamicParallelTemplateSchema,
+	DynamicExpandSchema,
+	DynamicCollectSchema,
+} from "./schemas.ts";
+
+type ObjectSchema = {
+	properties?: Record<string, unknown>;
+	additionalProperties?: unknown;
+};
+
+function allowedKeysOf(schema: ObjectSchema | undefined): string[] {
+	return schema?.properties ? Object.keys(schema.properties) : [];
+}
+
+const ExpandFromSchema = (DynamicExpandSchema.properties?.from ?? {}) as ObjectSchema;
+
+export const CHAIN_STEP_KEYS = allowedKeysOf(ChainItem);
+export const PARALLEL_TASK_KEYS = allowedKeysOf(ParallelTaskSchema);
+export const DYNAMIC_TEMPLATE_KEYS = allowedKeysOf(DynamicParallelTemplateSchema);
+export const EXPAND_KEYS = allowedKeysOf(DynamicExpandSchema);
+export const EXPAND_FROM_KEYS = allowedKeysOf(ExpandFromSchema);
+export const COLLECT_KEYS = allowedKeysOf(DynamicCollectSchema);
+
+const CHAIN_STEP_EXAMPLE = '{"agent": "builder", "task": "do X"}';
+const PARALLEL_TASK_EXAMPLE = '{"agent": "builder", "task": "do X"}';
+const DYNAMIC_TEMPLATE_EXAMPLE = '{"agent": "builder", "task": "Review {item.path}"}';
+const EXPAND_EXAMPLE = '{"from": {"output": "targets", "path": "/items"}, "maxItems": 4}';
+const EXPAND_FROM_EXAMPLE = '{"output": "targets", "path": "/items"}';
+const COLLECT_EXAMPLE = '{"as": "reviews"}';
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function disallowedKeys(value: Record<string, unknown>, allowed: readonly string[]): string[] {
+	return Object.keys(value).filter((key) => !allowed.includes(key));
+}
+
+function typeName(value: unknown): string {
+	if (Array.isArray(value)) return "array";
+	return typeof value;
+}
+
+function quoteList(keys: string[]): string {
+	return keys.map((key) => `"${key}"`).join(", ");
+}
+
+function disallowedMessage(
+	path: string,
+	keys: string[],
+	allowed: readonly string[],
+	example?: string,
+): string {
+	const subject = keys.length === 1
+		? `property "${keys[0]}" is not allowed`
+		: `properties ${quoteList(keys)} are not allowed`;
+	const examplePart = example ? `\n\nExample: ${example}` : "";
+	return `subagent ${path}: ${subject}.\nAllowed properties: ${allowed.join(", ")}.${examplePart}`;
+}
+
+function expectObject(value: unknown, path: string, allowed: readonly string[], example?: string): asserts value is Record<string, unknown> {
+	if (!isPlainObject(value)) {
+		const examplePart = example ? `\n\nExample: ${example}` : "";
+		throw new Error(
+			`subagent ${path}: expected an object, received ${typeName(value)}.\nAllowed properties: ${allowed.join(", ")}.${examplePart}`,
+		);
+	}
+}
+
+function checkNoExtraKeys(
+	value: Record<string, unknown>,
+	path: string,
+	schema: ObjectSchema,
+	allowed: readonly string[],
+	example?: string,
+): void {
+	if (schema.additionalProperties !== false) return;
+	const extra = disallowedKeys(value, allowed);
+	if (extra.length > 0) {
+		throw new Error(disallowedMessage(path, extra, allowed, example));
+	}
+}
+
+/**
+ * Validates the `chain` array on a raw subagent tool-call argument object and
+ * throws a friendly, actionable error when a chain step (or a nested
+ * `parallel`/`expand`/`collect` object) has a disallowed property or wrong shape.
+ *
+ * No-op when `chain` is absent or not an array, so management/control/single/
+ * parallel calls are unaffected.
+ */
+export function validateChainInput(args: unknown): void {
+	if (!isPlainObject(args)) return;
+	const chain = (args as Record<string, unknown>).chain;
+	if (!Array.isArray(chain)) return;
+
+	chain.forEach((step, index) => {
+		const stepPath = `chain step validation failed at chain[${index}]`;
+		expectObject(step, stepPath, CHAIN_STEP_KEYS, CHAIN_STEP_EXAMPLE);
+		checkNoExtraKeys(step, stepPath, ChainItem, CHAIN_STEP_KEYS, CHAIN_STEP_EXAMPLE);
+
+		if (step.expand !== undefined) {
+			const expandPath = `${stepPath}.expand`;
+			expectObject(step.expand, expandPath, EXPAND_KEYS, EXPAND_EXAMPLE);
+			checkNoExtraKeys(step.expand, expandPath, DynamicExpandSchema, EXPAND_KEYS, EXPAND_EXAMPLE);
+
+			const from = (step.expand as Record<string, unknown>).from;
+			if (from !== undefined) {
+				const fromPath = `${expandPath}.from`;
+				expectObject(from, fromPath, EXPAND_FROM_KEYS, EXPAND_FROM_EXAMPLE);
+				checkNoExtraKeys(from, fromPath, ExpandFromSchema, EXPAND_FROM_KEYS, EXPAND_FROM_EXAMPLE);
+			}
+		}
+
+		if (step.collect !== undefined) {
+			const collectPath = `${stepPath}.collect`;
+			expectObject(step.collect, collectPath, COLLECT_KEYS, COLLECT_EXAMPLE);
+			checkNoExtraKeys(step.collect, collectPath, DynamicCollectSchema, COLLECT_KEYS, COLLECT_EXAMPLE);
+		}
+
+		const parallel = step.parallel;
+		if (parallel === undefined) return;
+
+		if (Array.isArray(parallel)) {
+			parallel.forEach((task, pIndex) => {
+				const taskPath = `${stepPath}.parallel[${pIndex}]`;
+				expectObject(task, taskPath, PARALLEL_TASK_KEYS, PARALLEL_TASK_EXAMPLE);
+				checkNoExtraKeys(task, taskPath, ParallelTaskSchema, PARALLEL_TASK_KEYS, PARALLEL_TASK_EXAMPLE);
+			});
+			return;
+		}
+
+		if (isPlainObject(parallel)) {
+			const templatePath = `${stepPath}.parallel (dynamic fanout template)`;
+			checkNoExtraKeys(parallel, templatePath, DynamicParallelTemplateSchema, DYNAMIC_TEMPLATE_KEYS, DYNAMIC_TEMPLATE_EXAMPLE);
+			return;
+		}
+
+		throw new Error(
+			`subagent ${stepPath}.parallel: expected an array of task objects or a dynamic fanout template object, received ${typeName(parallel)}.\n\nExample static: [${PARALLEL_TASK_EXAMPLE}]\nExample dynamic: ${DYNAMIC_TEMPLATE_EXAMPLE}`,
+		);
+	});
+}

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

@@ -1,8 +1,10 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ExtensionConfig } from "../shared/types.ts";
+import type { ArtifactDirPreference, ExtensionConfig } from "../shared/types.ts";
 import { getAgentDir } from "../shared/utils.ts";
 
+const ARTIFACT_DIR_PREFERENCES = new Set<ArtifactDirPreference>(["project", "session", "temp"]);
+
 export function getConfigPath(): string {
 	return path.join(getAgentDir(), "extensions", "subagent", "config.json");
 }
@@ -13,6 +15,10 @@ function readConfigForUpdate(configPath = getConfigPath()): ExtensionConfig {
 	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
 		throw new Error(`Subagent config at '${configPath}' must be a JSON object`);
 	}
+	const config = parsed as Record<string, unknown>;
+	if (config.artifactDir !== undefined && !ARTIFACT_DIR_PREFERENCES.has(config.artifactDir as ArtifactDirPreference)) {
+		throw new Error(`config.artifactDir must be "project", "session", or "temp"`);
+	}
 	return parsed as ExtensionConfig;
 }
 

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

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { discoverAgentsAll, type AgentSource } from "../agents/agents.ts";
 import { isAsyncAvailable } from "../runs/background/async-execution.ts";
+import { formatSpawnBudgetSummary, getSpawnBudgetSnapshot } from "../runs/shared/spawn-budget.ts";
 import { diagnoseIntercomBridge, type IntercomBridgeDiagnostic } from "../intercom/intercom-bridge.ts";
 import { discoverAvailableSkills, type SkillSource } from "../agents/skills.ts";
 import {
@@ -162,6 +163,17 @@ function formatIntercomDiagnostic(diagnostic: IntercomBridgeDiagnostic, context:
 	return lines;
 }
 
+function formatSpawnBudgetSection(input: DoctorReportInput): string[] {
+	const snapshot = getSpawnBudgetSnapshot(input.state, input.config, input.currentSessionId ?? input.state.currentSessionId);
+	return [
+		`- usage: ${formatSpawnBudgetSummary(snapshot)}`,
+		`- recent grants: ${snapshot.grantHistory.length === 0
+			? "none"
+			: snapshot.grantHistory.map((grant) => `+${grant.amount} at ${new Date(grant.grantedAt).toISOString()} (${grant.previousLimit} → ${grant.limit})`).join("; ")}`,
+		"- reset boundary: a new parent session resets usage and grants; compaction does not",
+	];
+}
+
 function formatPermissionSystemSection(): string[] {
 	const lines: string[] = [];
 	const parentSession = process.env["SELESAI_SUBAGENT_PARENT_SESSION"] ?? "";
@@ -199,6 +211,9 @@ export function buildDoctorReport(input: DoctorReportInput): string {
 		"Discovery",
 		...formatDiscovery(input, deps),
 		"",
+		"Spawn budget",
+		...formatSpawnBudgetSection(input),
+		"",
 		"Permission system",
 		...formatPermissionSystemSection(),
 		"",

package/dist/extensions/pi-subagents/src/extension/fanout-child.ts

@@ -5,6 +5,7 @@ import type { ExtensionAPI, ToolDefinition } from "@selesai/code";
 import { discoverAgents } from "../agents/agents.ts";
 import { getArtifactsDir } from "../shared/artifacts.ts";
 import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
+import { resolveWaitToolConfig } from "../runs/background/wait-config.ts";
 import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
 import { readNestedControlRequests, resolveNestedRouteFromEnv, writeNestedControlResult } from "../runs/shared/nested-events.ts";
 import { deliverSubagentIntercomMessageEvent } from "../intercom/result-intercom.ts";
@@ -146,6 +147,7 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 		state,
 		config,
 		asyncByDefault: config.asyncByDefault === true,
+		waitToolEnabled: resolveWaitToolConfig(config.waitTool).enabled,
 		tempArtifactsDir: getArtifactsDir(null),
 		getSubagentSessionRoot,
 		expandTilde,
@@ -159,7 +161,7 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 		description: [
 			"Delegate to subagents from child-safe fanout mode.",
 			"Allowed management/control actions: list, get, status, interrupt, resume, steer, append-step, doctor.",
-			"Agent config mutation actions (create, update, delete, eject, disable, enable, reset) are blocked in this mode.",
+			"Mutating management actions (create, update, delete, eject, disable, enable, reset, grant-spawn-budget) are blocked in this mode.",
 		].join("\n"),
 		parameters: SubagentParams,
 		execute(id, params, signal, onUpdate, ctx) {