@selesai/code 0.13.13 → 0.13.15

package/dist/extensions/pi-subagents/src/runs/shared/completion-guard.ts

@@ -0,0 +1,252 @@
+import type { Message } from "@earendil-works/pi-ai";
+import type { AcceptanceRole, TrackedMutationEvidence } from "../../shared/types.ts";
+import { isMutatingTool } from "./long-running-guard.ts";
+import { classifyTaskMutationIntent, expectsImplementationMutation, taskMayMutate } from "./task-intent.ts";
+
+export { expectsImplementationMutation };
+
+const READ_ONLY_BUILTIN_TOOLS = new Set([
+	"read",
+	"grep",
+	"find",
+	"ls",
+	"web_search",
+	"fetch_content",
+	"get_search_content",
+	"intercom",
+	"contact_supervisor",
+	"structured_output",
+]);
+
+// Cursor native edit/write often land as thinking traces (inactive_trace /
+// transcript_trace) rather than toolCall parts when native tool replay is off
+// or the tool is inactive in context. Match pi-cursor-sdk display labels.
+const CURSOR_FILE_MUTATION_THINKING =
+	/(?:^|\n)\s*Cursor (?:edit|write)\s*:/i;
+
+const REVIVED_TASK_PREFIX = /^You are reviving a previous subagent conversation\.\n\nOriginal run: .+\nOriginal agent: .+(?:\nOriginal session file: .+)?\n\nUse the stored session context as background\. Answer the orchestrator's follow-up below\. Do not assume the original child process is still alive\.\n\nFollow-up:\n/;
+const IMPLEMENTATION_CHALLENGE_FOLLOW_UP_PATTERN = /^(?:Run )?implementation challenge pass (?:one|two|\d+)(?:\s+and implement any better current[- ]scope change\.?|\s+for the accepted candidate\.\s+Reconsider it and implement any better current[- ]scope change\.?)?$/i;
+const NO_BETTER_CHANGE_NEEDED_PATTERN = /^\s*no (?:better|further|additional) (?:current[- ]scope )?(?:code |source |file )?(?:change|changes|edit|edits|patch|patches) (?:is|are) needed\b/i;
+const KEPT_CURRENT_IMPLEMENTATION_PATTERN = /\b(?:kept (?:the )?current (?:implementation|candidate|shape)|(?:the )?current (?:implementation|candidate|shape) was kept)\b/i;
+const NO_CHANGE_MADE_PATTERN = /\bno (?:new )?(?:(?:code|source|file|test)(?:\s*(?:,\s*or|,|\/|or)\s*(?:code|source|file|test))* changes?|changes?) (?:were|was) made\b/i;
+const NO_BETTER_CHANGE_QUALIFIER_PATTERN = /\b(?:do\s+not|don't|dont|not|never|cannot|can't|cant|unable|uncertain|unsure|unclear|disagree|wrong|false|reject|rejected|rejecting|maybe|might|may|\w+n['’]t)\b/i;
+const REPORT_SENTENCE_PATTERN = /[^.!?]+(?:[.!?]+(?=(?:["”'’]?\s)|["”'’]?$)|$)/g;
+const QUOTED_CLAIM_PATTERN = /["“]([^"”]+)["”]([.!?]?\s*[^.!?]*)/g;
+const QUOTED_CLAIM_REFERENCE_PATTERN = /\b(?:that|this|it|claim|report|message|disagree)\b/i;
+const CLAIM_CONTRADICTION_PATTERN = /\bbut\b[^.!?]*\b(?:uncertain|unsure|unclear|disagree|wrong|false|reject|rejected|rejecting)\b/i;
+const IMPLEMENTATION_RETRACTION_PATTERN = /\b(?:found|identified)\s+(?:(?:a|an|the)\s+)?(?:required|necessary|additional|better)?\s*(?:(?:code|source|file|test)\s+)?(?:changes?|edits?|patches?)\b|\b(?:(?:implementation|code|source|file|test)\s+)?work\s+(?:remains?|is\s+(?:needed|required))\b|\b(?:(?:a|an|the)\s+)?(?:(?:code|source|file|test)\s+)?(?:changes?|edits?|patches?)\s+(?:are|is)\s+(?:needed|required)\b|\b(?:required|necessary|additional|better)\s+(?:(?:code|source|file|test)\s+)?(?:changes?|edits?|patches?)\b|\b(?:I|we)?\s*need\s+(?:(?:code|source|file|test)\s+)?(?:changes?|edits?|patches?)\b|\b(?:need|needs|require|requires)\s+(?:to\s+)?(?:implement|make|apply)\b/i;
+const IMPLEMENTATION_RETRACTION_GLOBAL_PATTERN = new RegExp(IMPLEMENTATION_RETRACTION_PATTERN.source, "gi");
+const DIRECT_CLAIM_RETRACTION_PATTERN = /^\s*(?:I\s+)?(?:disagree|reject|retract)\b|\b(?:disagree|retract|retracted|retracting|reject|rejected|rejecting)\b[^.!?]*\b(?:that|this|it|claim|report|message)\b|\b(?:that|this|it|claim|report|message)\b[^.!?]*\b(?:is|was)\s+(?:rejected|retracted)\b/i;
+const NEGATED_RETRACTION_PREFIX_PATTERN = /\b(?:no|not|\w+n['’]t)\b(?:\s+\w+){0,2}\s*$/i;
+const REPORTED_CLAIM_PREFIX_PATTERN = /["“]|\b(?:prior|previous)\s+(?:message|report)\b|\b(?:said|stated|reported)\b/i;
+const POST_CLAIM_SEPARATOR_PATTERN = /^[\s,;:.—–'"“‘’-]+/;
+
+interface CompletionMutationGuardInput {
+	agent: string;
+	task: string;
+	messages: Message[];
+	tools?: string[];
+	mcpDirectTools?: string[];
+	mutationTools?: string[];
+	toolAvailabilityError?: string;
+	mutationEvidence?: TrackedMutationEvidence;
+}
+
+export interface CompletionMutationGuardResult {
+	expectedMutation: boolean;
+	attemptedMutation: boolean;
+	triggered: boolean;
+	blocked: boolean;
+	message?: string;
+}
+
+interface ReportSentence {
+	text: string;
+	offset: number;
+}
+
+export function hasMutationToolCapability(tools: string[] | undefined, mcpDirectTools: string[] | undefined): boolean {
+	if ((mcpDirectTools?.length ?? 0) > 0) return true;
+	if (tools === undefined) return true;
+	return !tools.every((tool) => READ_ONLY_BUILTIN_TOOLS.has(tool));
+}
+
+function hasBuiltinMutationTool(tools: string[] | undefined): boolean {
+	return tools === undefined || tools.some((tool) => !READ_ONLY_BUILTIN_TOOLS.has(tool));
+}
+
+function isWriterRole(agent: string, acceptanceRole: AcceptanceRole | undefined): boolean {
+	return acceptanceRole === "writer"
+		|| (acceptanceRole === undefined && /\bworker\b/i.test(agent));
+}
+
+const WRITER_DELIVERY_PATTERN = /\b(?:address|resolve|work)\s+(?:backlog\s+)?(?:item|issue)\b|\b(?:land|ship)\s+(?:the\s+)?(?:change|changes|fix|feature|implementation)\b/i;
+
+export function validateImplementationToolContract(input: {
+	agent: string;
+	task: string;
+	tools?: string[];
+	mcpDirectTools?: string[];
+	configuredExtensions?: string[];
+	requestedTools?: string[];
+	acceptanceRole?: AcceptanceRole;
+	completionGuard?: boolean;
+}): string | undefined {
+	if (input.completionGuard === false) return undefined;
+	const requestedMutationTools = input.requestedTools?.filter((tool) => !READ_ONLY_BUILTIN_TOOLS.has(tool)) ?? [];
+	const declaredMutationToolsWereRemoved = requestedMutationTools.length > 0 && !hasBuiltinMutationTool(input.tools);
+	const configuredExtensionCapability = (input.configuredExtensions?.length ?? 0) > 0 && !declaredMutationToolsWereRemoved;
+	if (hasMutationToolCapability(input.tools, input.mcpDirectTools) || configuredExtensionCapability) return undefined;
+	const intent = classifyTaskMutationIntent(input.agent, input.task);
+	if (intent.kind === "read-only") return undefined;
+	const writerTaskMayMutate = isWriterRole(input.agent, input.acceptanceRole)
+		&& (taskMayMutate(input.task) || WRITER_DELIVERY_PATTERN.test(input.task));
+	if (intent.kind !== "implementation" && !writerTaskMayMutate && !declaredMutationToolsWereRemoved) return undefined;
+	return `Agent '${input.agent}' was given an implementation task, but its tool allowlist has no mutation-capable tools. Add bash, edit, write, or another mutation-capable tool to the agent, or use a read-only task/agent.`;
+}
+
+function hasCheckpointMutationEvidence(message: Message): boolean {
+	const record = message as unknown as {
+		role?: string;
+		type?: string;
+		customType?: unknown;
+		data?: unknown;
+		details?: unknown;
+	};
+	if ((record.role !== "custom" && record.type !== "custom") || record.customType !== "pi-checkpoint") return false;
+	const details = typeof record.details === "object" && record.details !== null && !Array.isArray(record.details)
+		? record.details as Record<string, unknown>
+		: undefined;
+	const data = typeof record.data === "object" && record.data !== null && !Array.isArray(record.data)
+		? record.data as Record<string, unknown>
+		: typeof details?.beforeCommit === "string" || typeof details?.afterCommit === "string"
+			? details
+			: details?.data && typeof details.data === "object" && !Array.isArray(details.data)
+				? details.data as Record<string, unknown>
+				: undefined;
+	return typeof data?.beforeCommit === "string"
+		&& typeof data.afterCommit === "string"
+		&& data.beforeCommit !== data.afterCommit;
+}
+
+export function hasMutationToolCall(messages: Message[], mutationTools?: readonly string[]): boolean {
+	for (const message of messages) {
+		if (hasCheckpointMutationEvidence(message)) return true;
+		if (message.role !== "assistant") continue;
+		for (const part of message.content) {
+			if (part.type === "thinking" && CURSOR_FILE_MUTATION_THINKING.test(part.thinking)) return true;
+			if (part.type !== "toolCall") continue;
+			const args = typeof part.arguments === "object" && part.arguments !== null && !Array.isArray(part.arguments)
+				? part.arguments as Record<string, unknown>
+				: {};
+			if (isMutatingTool(part.name, args, mutationTools)) return true;
+		}
+	}
+	return false;
+}
+
+function hasImplementationRetraction(text: string): boolean {
+	return Array.from(text.matchAll(IMPLEMENTATION_RETRACTION_GLOBAL_PATTERN)).some((retraction) =>
+		!NEGATED_RETRACTION_PREFIX_PATTERN.test(text.slice(0, retraction.index!)));
+}
+
+function hasDirectClaimRetraction(text: string): boolean {
+	return DIRECT_CLAIM_RETRACTION_PATTERN.test(text.replace(POST_CLAIM_SEPARATOR_PATTERN, ""));
+}
+
+function isInsideQuotedText(report: string, index: number): boolean {
+	let quote: "double" | "single" | undefined;
+	for (const char of report.slice(0, index)) {
+		if (quote === "double") {
+			if (char === "\"" || char === "”") quote = undefined;
+		} else if (quote === "single") {
+			if (char === "’") quote = undefined;
+		} else if (char === "\"" || char === "“") {
+			quote = "double";
+		} else if (char === "‘") {
+			quote = "single";
+		}
+	}
+	return quote !== undefined;
+}
+
+function unqualifiedClaimIndex(report: string, sentences: ReportSentence[], pattern: RegExp): number {
+	return sentences.findIndex((sentence) => {
+		const claim = sentence.text.match(pattern);
+		if (claim === null) return false;
+		const before = sentence.text.slice(0, claim.index!);
+		const after = sentence.text.slice(claim.index! + claim[0].length);
+		const previous = before.trimEnd().at(-1);
+		return previous !== "'"
+			&& previous !== "‘"
+			&& !isInsideQuotedText(report, sentence.offset + claim.index!)
+			&& !REPORTED_CLAIM_PREFIX_PATTERN.test(before)
+			&& !NO_BETTER_CHANGE_QUALIFIER_PATTERN.test(before)
+			&& !CLAIM_CONTRADICTION_PATTERN.test(after)
+			&& !hasImplementationRetraction(after)
+			&& !hasDirectClaimRetraction(after);
+	});
+}
+
+function hasLaterClaimRetraction(sentences: ReportSentence[], claimIndex: number): boolean {
+	return sentences.slice(claimIndex + 1).some((sentence) => hasImplementationRetraction(sentence.text)
+		|| hasDirectClaimRetraction(sentence.text));
+}
+
+function explicitlyRejectsQuotedClaim(report: string): boolean {
+	for (const [, claim, response] of report.matchAll(QUOTED_CLAIM_PATTERN)) {
+		if ((KEPT_CURRENT_IMPLEMENTATION_PATTERN.test(claim!) || NO_CHANGE_MADE_PATTERN.test(claim!))
+			&& NO_BETTER_CHANGE_QUALIFIER_PATTERN.test(response!)
+			&& QUOTED_CLAIM_REFERENCE_PATTERN.test(response!)) return true;
+	}
+	return false;
+}
+
+function isImplementationChallengeTask(task: string): boolean {
+	const followUp = task.replace(REVIVED_TASK_PREFIX, "");
+	return followUp !== task && IMPLEMENTATION_CHALLENGE_FOLLOW_UP_PATTERN.test(followUp.trim());
+}
+
+function reportsNoBetterChallengeChange(messages: Message[]): boolean {
+	const report = messages
+		.filter((message) => message.role === "assistant")
+		.flatMap((message) => message.content)
+		.flatMap((part) => part.type === "text" ? [part.text] : [])
+		.join("\n");
+	if (explicitlyRejectsQuotedClaim(report)) return false;
+	const sentences = Array.from(report.matchAll(REPORT_SENTENCE_PATTERN), (match) => ({
+		text: match[0],
+		offset: match.index!,
+	}));
+	const noBetterIndex = unqualifiedClaimIndex(report, sentences, NO_BETTER_CHANGE_NEEDED_PATTERN);
+	if (noBetterIndex >= 0) return !hasLaterClaimRetraction(sentences, noBetterIndex);
+	const keptIndex = unqualifiedClaimIndex(report, sentences, KEPT_CURRENT_IMPLEMENTATION_PATTERN);
+	const noChangeIndex = unqualifiedClaimIndex(report, sentences, NO_CHANGE_MADE_PATTERN);
+	return keptIndex >= 0
+		&& noChangeIndex >= 0
+		&& !hasLaterClaimRetraction(sentences, Math.min(keptIndex, noChangeIndex));
+}
+
+export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
+	if (input.toolAvailabilityError && expectsImplementationMutation(input.agent, input.task)) {
+		return {
+			expectedMutation: true,
+			attemptedMutation: false,
+			triggered: false,
+			blocked: true,
+			message: input.toolAvailabilityError,
+		};
+	}
+	const expectedMutation = hasMutationToolCapability(input.tools, input.mcpDirectTools)
+		? expectsImplementationMutation(input.agent, input.task)
+		: false;
+	const attemptedMutation = hasMutationToolCall(input.messages, input.mutationTools) || input.mutationEvidence?.attemptedMutation === true;
+	const noEditChallengeComplete = isImplementationChallengeTask(input.task)
+		&& reportsNoBetterChallengeChange(input.messages);
+	return {
+		expectedMutation,
+		attemptedMutation,
+		triggered: expectedMutation && !attemptedMutation && !noEditChallengeComplete,
+		blocked: false,
+	};
+}

package/dist/extensions/pi-subagents/src/runs/shared/context-mode.ts

@@ -0,0 +1,44 @@
+export type ContextMode = "fresh" | "fork";
+export type ContextSummary = ContextMode | "mixed";
+
+export function isContextMode(value: unknown): value is ContextMode {
+	return value === "fresh" || value === "fork";
+}
+
+export function isContextSummary(value: unknown): value is ContextSummary {
+	return isContextMode(value) || value === "mixed";
+}
+
+export function summarizeContextModes(modes: Array<ContextMode | undefined>): ContextSummary | undefined {
+	const resolved = modes.filter(isContextMode);
+	if (resolved.length === 0) return undefined;
+	const first = resolved[0]!;
+	return resolved.every((mode) => mode === first) ? first : "mixed";
+}
+
+export function contextModeLabel(mode: ContextMode | ContextSummary | undefined): string {
+	if (mode === "fork") return "[fork]";
+	if (mode === "fresh") return "[fresh]";
+	if (mode === "mixed") return "[mixed]";
+	return "";
+}
+
+export function contextModeBadge(
+	theme: { fg(name: string, text: string): string },
+	mode: ContextMode | ContextSummary | undefined,
+): string {
+	const label = contextModeLabel(mode);
+	if (!label) return "";
+	if (mode === "fork") return theme.fg("warning", ` ${label}`);
+	return theme.fg("dim", ` ${label}`);
+}
+
+export function contextModePrefix(
+	theme: { fg(name: string, text: string): string },
+	mode: ContextMode | ContextSummary | undefined,
+): string {
+	const label = contextModeLabel(mode);
+	if (!label) return "";
+	if (mode === "fork") return `${theme.fg("warning", label)} `;
+	return `${theme.fg("dim", label)} `;
+}

package/dist/extensions/pi-subagents/src/runs/shared/dynamic-fanout.ts

@@ -0,0 +1,297 @@
+import type { DynamicParallelStep, ParallelTaskItem } from "../../shared/settings.ts";
+import type { ArtifactPaths, ChainOutputMap, JsonSchemaObject, SingleResult } from "../../shared/types.ts";
+import { getSingleResultOutput } from "../../shared/utils.ts";
+import { validateStructuredOutputValue } from "./structured-output.ts";
+
+export class DynamicFanoutError extends Error {}
+
+export interface DynamicFanoutConfig {
+	maxItems?: number;
+	allowRunnerFields?: boolean;
+}
+
+export interface DynamicMaterializedItem {
+	index: number;
+	key: string;
+	idKey: string;
+	item: unknown;
+}
+
+export interface DynamicCollectedResult {
+	key: string;
+	index: number;
+	item: unknown;
+	agent: string;
+	exitCode: number | null;
+	text: string;
+	structured?: unknown;
+	error?: string;
+	timedOut?: boolean;
+	stopped?: boolean;
+	outputPath?: string;
+	artifactPaths?: ArtifactPaths;
+}
+
+export interface DynamicMaterializedGroup {
+	items: DynamicMaterializedItem[];
+	parallel: ParallelTaskItem[];
+	collectedOnEmpty?: DynamicCollectedResult[];
+}
+
+const SAFE_OUTPUT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ITEM_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ITEM_REF_PATTERN = /\{([A-Za-z_][A-Za-z0-9_]*)(?:\.([^{}]+))?\}/g;
+const RESERVED_TEMPLATE_NAMES = new Set(["task", "previous", "chain_dir", "outputs"]);
+const DYNAMIC_STEP_KEYS = new Set(["expand", "parallel", "collect", "concurrency", "failFast", "phase", "label", "acceptance", "agentContract", "gateOn"]);
+const RUNNER_DYNAMIC_STEP_KEYS = new Set([...DYNAMIC_STEP_KEYS, "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "sessionFiles", "thinkingOverrides"]);
+const DYNAMIC_EXPAND_KEYS = new Set(["from", "item", "key", "maxItems", "onEmpty"]);
+const DYNAMIC_EXPAND_FROM_KEYS = new Set(["output", "path"]);
+const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outputSchema", "cwd", "output", "outputMode", "reads", "progress", "skill", "model", "fast", "toolBudget", "acceptance", "agentContract", "gateOn"]);
+const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
+	...DYNAMIC_PARALLEL_KEYS,
+	"outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled", "waitToolDefaultTimeoutMs",
+	"structuredOutput", "structuredOutputSchema", "tools", "excludeTools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "capabilityCeiling", "completionGuard", "systemPrompt",
+	"systemPromptMode", "thinking", "modelCandidates", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "launchResolvedExtensions", "requestedCwd",
+]);
+const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);
+
+export function isSafeOutputName(name: string): boolean {
+	return SAFE_OUTPUT_NAME_PATTERN.test(name);
+}
+
+export function assertJsonPointer(pointer: string, label: string): void {
+	if (pointer === "") return;
+	if (!pointer.startsWith("/")) {
+		throw new DynamicFanoutError(`${label} must be a JSON Pointer starting with '/'.`);
+	}
+	for (const segment of pointer.slice(1).split("/")) {
+		if (/~(?![01])/.test(segment)) {
+			throw new DynamicFanoutError(`${label} contains invalid JSON Pointer escape.`);
+		}
+	}
+}
+
+function decodePointerSegment(segment: string): string {
+	return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+export function resolveJsonPointer(value: unknown, pointer: string, label: string): unknown {
+	assertJsonPointer(pointer, label);
+	if (pointer === "") return value;
+	let current = value;
+	for (const rawSegment of pointer.slice(1).split("/")) {
+		const segment = decodePointerSegment(rawSegment);
+		if (Array.isArray(current)) {
+			if (!/^(0|[1-9][0-9]*)$/.test(segment)) {
+				throw new DynamicFanoutError(`${label} segment '${segment}' does not address an array index.`);
+			}
+			const index = Number(segment);
+			if (index >= current.length) throw new DynamicFanoutError(`${label} does not exist.`);
+			current = current[index];
+			continue;
+		}
+		if (!current || typeof current !== "object") {
+			throw new DynamicFanoutError(`${label} does not exist.`);
+		}
+		const record = current as Record<string, unknown>;
+		if (!Object.prototype.hasOwnProperty.call(record, segment)) {
+			throw new DynamicFanoutError(`${label} does not exist.`);
+		}
+		current = record[segment];
+	}
+	return current;
+}
+
+function scalarToKey(value: unknown, label: string): string {
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+		const key = String(value);
+		if (!key.trim()) throw new DynamicFanoutError(`${label} resolved to an empty key.`);
+		if (/[\u0000-\u001F\u007F]/.test(key)) throw new DynamicFanoutError(`${label} resolved to an unsafe key.`);
+		if (key.length > 200) throw new DynamicFanoutError(`${label} resolved to a key longer than 200 characters.`);
+		return key;
+	}
+	throw new DynamicFanoutError(`${label} must resolve to a string, number, or boolean.`);
+}
+
+export function normalizeItemKeyForId(key: string): string {
+	const normalized = key
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 80);
+	return normalized || "item";
+}
+
+function valueToTemplateText(value: unknown, reference: string): string {
+	if (value === undefined) throw new DynamicFanoutError(`Unresolved item reference '${reference}'.`);
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || value === null) return String(value);
+	return JSON.stringify(value);
+}
+
+function resolveItemPath(item: unknown, pathText: string | undefined, reference: string): unknown {
+	if (!pathText) return item;
+	const pointer = `/${pathText.split(".").map((segment) => segment.replace(/~/g, "~0").replace(/\//g, "~1")).join("/")}`;
+	return resolveJsonPointer(item, pointer, reference);
+}
+
+export function resolveItemTemplate(template: string, itemName: string, item: unknown): string {
+	return template.replace(ITEM_REF_PATTERN, (raw, name: string, pathText: string | undefined) => {
+		if (name !== itemName) return raw;
+		if (pathText !== undefined && (!pathText.trim() || pathText.includes(".."))) {
+			throw new DynamicFanoutError(`Invalid item reference '${raw}'.`);
+		}
+		return valueToTemplateText(resolveItemPath(item, pathText, raw), raw);
+	});
+}
+
+function assertOnlyKeys(value: unknown, allowed: Set<string>, label: string): void {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new DynamicFanoutError(`${label} must be an object.`);
+	for (const key of Object.keys(value)) {
+		if (!allowed.has(key)) throw new DynamicFanoutError(`${label} does not support field '${key}'.`);
+	}
+}
+
+export function assertNoUnresolvedItemReferences(template: string, itemName: string, label: string): void {
+	for (const match of template.matchAll(/\{([^{}]*)\}/g)) {
+		const raw = match[0]!;
+		const reference = match[1]!;
+		if (reference === itemName || reference.startsWith(`${itemName}.`)) {
+			if (!ITEM_REF_PATTERN.test(raw) || reference === `${itemName}.` || reference.includes("..")) {
+				throw new DynamicFanoutError(`Invalid item reference '${raw}' in ${label}.`);
+			}
+			ITEM_REF_PATTERN.lastIndex = 0;
+			continue;
+		}
+		ITEM_REF_PATTERN.lastIndex = 0;
+		const name = reference.match(/^[A-Za-z_][A-Za-z0-9_]*/)?.[0];
+		if (name === itemName) throw new DynamicFanoutError(`Invalid item reference '${raw}' in ${label}.`);
+		if (name && RESERVED_TEMPLATE_NAMES.has(name)) continue;
+		if (name) throw new DynamicFanoutError(`Unsupported template reference '${raw}' in ${label}.`);
+	}
+	ITEM_REF_PATTERN.lastIndex = 0;
+	if (template.includes(`{${itemName}.}`) || new RegExp(`\\{${itemName}(?:\\.|$)[^}]*$`).test(template)) {
+		throw new DynamicFanoutError(`Invalid item reference in ${label}.`);
+	}
+}
+
+export function hasDynamicFanoutFields(step: unknown): boolean {
+	return !!step && typeof step === "object" && !Array.isArray(step)
+		&& (Object.prototype.hasOwnProperty.call(step, "expand") || Object.prototype.hasOwnProperty.call(step, "collect"));
+}
+
+export function validateDynamicStepShape(step: DynamicParallelStep, stepIndex: number, config: DynamicFanoutConfig = {}): void {
+	const prefix = `Dynamic chain step ${stepIndex + 1}`;
+	assertOnlyKeys(step, config.allowRunnerFields ? RUNNER_DYNAMIC_STEP_KEYS : DYNAMIC_STEP_KEYS, prefix);
+	if (!step.expand || !step.expand.from) throw new DynamicFanoutError(`${prefix} requires expand.from.`);
+	assertOnlyKeys(step.expand, DYNAMIC_EXPAND_KEYS, `${prefix} expand`);
+	assertOnlyKeys(step.expand.from, DYNAMIC_EXPAND_FROM_KEYS, `${prefix} expand.from`);
+	if (!isSafeOutputName(step.expand.from.output)) throw new DynamicFanoutError(`${prefix} has invalid expand.from.output '${step.expand.from.output}'.`);
+	assertJsonPointer(step.expand.from.path, `${prefix} expand.from.path`);
+	if (step.expand.key !== undefined) assertJsonPointer(step.expand.key, `${prefix} expand.key`);
+	const itemName = step.expand.item ?? "item";
+	if (!ITEM_NAME_PATTERN.test(itemName)) throw new DynamicFanoutError(`${prefix} has invalid expand.item '${itemName}'.`);
+	if (step.expand.maxItems === undefined && config.maxItems === undefined) {
+		throw new DynamicFanoutError(`${prefix} requires expand.maxItems or config.chain.dynamicFanout.maxItems.`);
+	}
+	if (step.expand.maxItems !== undefined && (!Number.isInteger(step.expand.maxItems) || step.expand.maxItems < 0)) {
+		throw new DynamicFanoutError(`${prefix} expand.maxItems must be an integer >= 0.`);
+	}
+	if (config.maxItems !== undefined && (!Number.isInteger(config.maxItems) || config.maxItems < 0)) {
+		throw new DynamicFanoutError("config.chain.dynamicFanout.maxItems must be an integer >= 0.");
+	}
+	if (!step.parallel || Array.isArray(step.parallel)) throw new DynamicFanoutError(`${prefix} requires a single parallel template object and cannot mix dynamic expand/collect with static parallel arrays.`);
+	assertOnlyKeys(step.parallel, config.allowRunnerFields ? RUNNER_DYNAMIC_PARALLEL_KEYS : DYNAMIC_PARALLEL_KEYS, `${prefix} parallel`);
+	if ("expand" in (step.parallel as object)) throw new DynamicFanoutError(`${prefix} does not support nested dynamic fanout.`);
+	if (!step.parallel.agent) throw new DynamicFanoutError(`${prefix} parallel.agent is required.`);
+	if (!step.collect?.as || !isSafeOutputName(step.collect.as)) throw new DynamicFanoutError(`${prefix} requires collect.as with a safe output name.`);
+	assertOnlyKeys(step.collect, DYNAMIC_COLLECT_KEYS, `${prefix} collect`);
+	for (const [label, template] of [
+		["parallel.task", step.parallel.task],
+		["parallel.label", step.parallel.label],
+	] as const) {
+		if (template) assertNoUnresolvedItemReferences(template, itemName, `${prefix} ${label}`);
+	}
+}
+
+export function resolveDynamicFanoutItems(step: DynamicParallelStep, outputs: ChainOutputMap, stepIndex: number, config: DynamicFanoutConfig = {}): DynamicMaterializedItem[] {
+	validateDynamicStepShape(step, stepIndex, config);
+	const sourceName = step.expand.from.output;
+	const source = outputs[sourceName];
+	if (!source) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} references unknown output '${sourceName}'.`);
+	if (source.structured === undefined) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} requires structured output '${sourceName}'.`);
+	const value = resolveJsonPointer(source.structured, step.expand.from.path, `Dynamic chain step ${stepIndex + 1} expand.from.path`);
+	if (!Array.isArray(value)) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} expand.from.path must resolve to an array.`);
+	const maxItems = step.expand.maxItems ?? config.maxItems;
+	if (maxItems === undefined) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} requires an effective maxItems.`);
+	if (value.length > maxItems) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} resolved ${value.length} items, exceeding maxItems ${maxItems}.`);
+	const seen = new Set<string>();
+	const seenIds = new Set<string>();
+	return value.map((item, index) => {
+		const key = step.expand.key === undefined
+			? String(index)
+			: scalarToKey(resolveJsonPointer(item, step.expand.key, `Dynamic chain step ${stepIndex + 1} expand.key`), `Dynamic chain step ${stepIndex + 1} expand.key`);
+		if (seen.has(key)) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} produced duplicate item key '${key}'.`);
+		seen.add(key);
+		const idKey = normalizeItemKeyForId(key);
+		if (seenIds.has(idKey)) throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} produced colliding item id '${idKey}'.`);
+		seenIds.add(idKey);
+		return { index, key, idKey, item };
+	});
+}
+
+export function materializeDynamicParallelStep(step: DynamicParallelStep, outputs: ChainOutputMap, stepIndex: number, config: DynamicFanoutConfig = {}): DynamicMaterializedGroup {
+	const items = resolveDynamicFanoutItems(step, outputs, stepIndex, config);
+	if (items.length === 0) {
+		if ((step.expand.onEmpty ?? "skip") === "fail") {
+			throw new DynamicFanoutError(`Dynamic chain step ${stepIndex + 1} source array is empty.`);
+		}
+		return { items, parallel: [], collectedOnEmpty: [] };
+	}
+	const itemName = step.expand.item ?? "item";
+	const parallel = items.map((entry) => {
+		const task = resolveItemTemplate(step.parallel.task ?? "{previous}", itemName, entry.item);
+		const label = step.parallel.label ? resolveItemTemplate(step.parallel.label, itemName, entry.item) : undefined;
+		return {
+			...step.parallel,
+			task,
+			...(label !== undefined ? { label } : {}),
+		};
+	});
+	return { items, parallel };
+}
+
+export function collectDynamicResults(
+	step: DynamicParallelStep,
+	items: DynamicMaterializedItem[],
+	results: Array<Pick<SingleResult, "agent" | "error" | "timedOut" | "stopped" | "structuredOutput" | "artifactPaths" | "savedOutputPath"> & { exitCode: number | null; output?: string; finalOutput?: string }>,
+): DynamicCollectedResult[] {
+	return items.map((entry, index) => {
+		const result = results[index];
+		const text = result
+			? ("output" in result && typeof result.output === "string" ? result.output : getSingleResultOutput(result as SingleResult))
+			: "";
+		return {
+			key: entry.key,
+			index: entry.index,
+			item: entry.item,
+			agent: result?.agent ?? step.parallel.agent,
+			exitCode: result?.exitCode ?? null,
+			text,
+			...(result?.structuredOutput !== undefined ? { structured: result.structuredOutput } : {}),
+			...(result?.error ? { error: result.error } : {}),
+			...(result?.timedOut ? { timedOut: true } : {}),
+			...(result?.stopped ? { stopped: true } : {}),
+			...(result?.savedOutputPath ? { outputPath: result.savedOutputPath } : {}),
+			...(result?.artifactPaths ? { artifactPaths: result.artifactPaths } : {}),
+		};
+	});
+}
+
+export async function validateDynamicCollection(schema: JsonSchemaObject | undefined, value: DynamicCollectedResult[]): Promise<void> {
+	if (!schema) return;
+	const validation = await validateStructuredOutputValue(schema, value);
+	if (validation.status === "invalid") {
+		throw new DynamicFanoutError(`Collected output validation failed: ${validation.message}`);
+	}
+}

package/dist/extensions/pi-subagents/src/runs/shared/extension-bindings.ts

@@ -0,0 +1,78 @@
+export const SELESAI_SUBAGENT_EXTENSION_BINDINGS_ENV = "SELESAI_SUBAGENT_EXTENSION_BINDINGS";
+export const MAX_EXTENSION_BINDING_NAMESPACES = 16;
+export const MAX_EXTENSION_BINDINGS_BYTES = 16 * 1024;
+export const MAX_EXTENSION_BINDINGS_DEPTH = 16;
+export const MAX_EXTENSION_BINDINGS_PROPERTIES = 256;
+
+const EXTENSION_BINDING_NAMESPACE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,62})\/[1-9][0-9]{0,8}$/;
+
+export type ExtensionBindingJson = null | boolean | number | string | ReadonlyArray<ExtensionBindingJson> | { readonly [key: string]: ExtensionBindingJson };
+export type ExtensionBindings = Readonly<Record<string, ExtensionBindingJson>>;
+
+export interface NormalizedExtensionBindings {
+	value: ExtensionBindings;
+	json: string;
+}
+
+function canonicalizeJson(value: unknown, path: string, depth: number, seen: Set<object>, propertyCount: { value: number }): ExtensionBindingJson {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error(`${path} must contain only finite JSON numbers.`);
+		return value;
+	}
+	if (typeof value !== "object") throw new Error(`${path} must contain only plain JSON values.`);
+	if (depth > MAX_EXTENSION_BINDINGS_DEPTH) throw new Error(`${path} exceeds the maximum nesting depth of ${MAX_EXTENSION_BINDINGS_DEPTH}.`);
+	if (seen.has(value)) throw new Error(`${path} must not contain cycles.`);
+	seen.add(value);
+	try {
+		if (Array.isArray(value)) {
+			const output: ExtensionBindingJson[] = [];
+			for (let index = 0; index < value.length; index++) {
+				if (!Object.prototype.hasOwnProperty.call(value, index)) throw new Error(`${path} must not contain sparse arrays.`);
+				output.push(canonicalizeJson(value[index], `${path}[${index}]`, depth + 1, seen, propertyCount));
+			}
+			return Object.freeze(output);
+		}
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) throw new Error(`${path} must contain only plain JSON objects.`);
+		if (Object.getOwnPropertySymbols(value).length > 0) throw new Error(`${path} must not contain symbol keys.`);
+		const descriptors = Object.getOwnPropertyDescriptors(value);
+		const output: Record<string, ExtensionBindingJson> = {};
+		for (const key of Object.keys(descriptors).sort()) {
+			const descriptor = descriptors[key]!;
+			if (!descriptor.enumerable || !("value" in descriptor)) throw new Error(`${path}.${key} must be an enumerable data property.`);
+			propertyCount.value += 1;
+			if (propertyCount.value > MAX_EXTENSION_BINDINGS_PROPERTIES) throw new Error(`extensionBindings exceeds ${MAX_EXTENSION_BINDINGS_PROPERTIES} total properties.`);
+			Object.defineProperty(output, key, { value: canonicalizeJson(descriptor.value, `${path}.${key}`, depth + 1, seen, propertyCount), enumerable: true, writable: false, configurable: false });
+		}
+		return Object.freeze(output);
+	} finally {
+		seen.delete(value);
+	}
+}
+
+export function normalizeExtensionBindings(input: unknown): NormalizedExtensionBindings | undefined {
+	if (input === undefined) return undefined;
+	if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("extensionBindings must be a plain JSON object.");
+	const prototype = Object.getPrototypeOf(input);
+	if (prototype !== Object.prototype && prototype !== null) throw new Error("extensionBindings must be a plain JSON object.");
+	const keys = Object.keys(input);
+	if (keys.length > MAX_EXTENSION_BINDING_NAMESPACES) throw new Error(`extensionBindings supports at most ${MAX_EXTENSION_BINDING_NAMESPACES} namespaces.`);
+	for (const key of keys) {
+		if (!EXTENSION_BINDING_NAMESPACE.test(key)) throw new Error(`extensionBindings namespace '${key}' must use a package-like name followed by '/<positive-version>'.`);
+	}
+	const value = canonicalizeJson(input, "extensionBindings", 0, new Set(), { value: 0 }) as ExtensionBindings;
+	const json = JSON.stringify(value);
+	const bytes = Buffer.byteLength(json, "utf8");
+	if (bytes > MAX_EXTENSION_BINDINGS_BYTES) throw new Error(`extensionBindings canonical JSON is ${bytes} bytes; maximum is ${MAX_EXTENSION_BINDINGS_BYTES}.`);
+	return { value, json };
+}
+
+export function encodeExtensionBindings(input: ExtensionBindings | undefined): string | undefined {
+	return input === undefined ? undefined : normalizeExtensionBindings(input)!.json;
+}
+
+export function omitExtensionBindingsEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+	const { [SELESAI_SUBAGENT_EXTENSION_BINDINGS_ENV]: _extensionBindings, ...sanitized } = env;
+	return sanitized;
+}