pi-subagents 0.40.0 → 0.41.0

package/src/workflows/scripted-workflow.ts

@@ -0,0 +1,415 @@
+import { Worker } from "node:worker_threads";
+
+const KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+const WORKER_SOURCE = String.raw`
+const { parentPort } = require("node:worker_threads");
+const vm = require("node:vm");
+const { inspect } = require("node:util");
+
+let nextCallId = 0;
+const pending = new Map();
+const runKeyPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function stableRunJson(value) {
+  if (Array.isArray(value)) return "[" + value.map(stableRunJson).join(",") + "]";
+  if (value && typeof value === "object") return "{" + Object.keys(value).sort().map((key) => JSON.stringify(key) + ":" + stableRunJson(value[key])).join(",") + "}";
+  return JSON.stringify(value) ?? "undefined";
+}
+
+function hostCall(method, args) {
+  return new Promise((resolve, reject) => {
+    const callId = ++nextCallId;
+    pending.set(callId, { resolve, reject });
+    parentPort.postMessage({ type: "call", callId, method, args });
+  });
+}
+
+function formatRef(result) {
+  if (!result || typeof result !== "object") throw new Error("runs.ref(result) requires a run result object.");
+  const parts = ["run " + (result.key || "unknown")];
+  if (result.runId) parts.push("id=" + String(result.runId).slice(0, 8));
+  return "[" + parts.join("; ") + "]";
+}
+
+const runFingerprints = new Map();
+
+function validateRunCall(key, params, label, fingerprints) {
+  if (typeof key !== "string" || !runKeyPattern.test(key)) throw new Error(label + " has an invalid key.");
+  if (!params || typeof params !== "object" || Array.isArray(params)) throw new Error(label + " requires a params object.");
+  if (Object.prototype.hasOwnProperty.call(params, "action") || Object.prototype.hasOwnProperty.call(params, "workflowScript") || Object.prototype.hasOwnProperty.call(params, "tasks") || Object.prototype.hasOwnProperty.call(params, "chain") || Object.prototype.hasOwnProperty.call(params, "concurrency") || Object.prototype.hasOwnProperty.call(params, "chainDir")) {
+    const hint = label === "runs.run" ? "; use runs.all(...) and JavaScript control flow for orchestration." : ".";
+    throw new Error(label + " accepts one child via { agent, task } and execution controls only" + hint);
+  }
+  if (params.worktree !== undefined && typeof params.worktree !== "boolean") throw new Error(label + " worktree must be true or false.");
+  assertJsonValue(params, label + " params");
+  const fingerprint = stableRunJson(params);
+  const existing = fingerprints.get(key);
+  if (existing !== undefined && existing !== fingerprint) throw new Error("Duplicate workflow key '" + key + "' used with incompatible launch params.");
+  fingerprints.set(key, fingerprint);
+}
+
+const runs = Object.freeze({
+  run(key, params) {
+    validateRunCall(key, params, "runs.run", runFingerprints);
+    return hostCall("run", { key, params });
+  },
+  all(items) {
+    if (!Array.isArray(items)) throw new Error("runs.all(items) requires an array.");
+    const fingerprints = new Map(runFingerprints);
+    const calls = [];
+    for (let index = 0; index < items.length; index++) {
+      if (!Object.prototype.hasOwnProperty.call(items, index)) throw new Error("runs.all items must not contain sparse entries.");
+      const item = items[index];
+      if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error("runs.all item " + index + " must be an object.");
+      const { key, ...params } = item;
+      validateRunCall(key, params, "runs.all item " + index, fingerprints);
+      calls.push({ key, params });
+    }
+    for (const { key, params } of calls) runFingerprints.set(key, stableRunJson(params));
+    return Promise.all(calls.map(({ key, params }) => hostCall("run", { key, params, collectFailure: true })));
+  },
+  status(keyOrRunId) { return hostCall("status", { keyOrRunId }); },
+  ref: formatRef,
+  refs(results) {
+    if (!Array.isArray(results)) throw new Error("runs.refs(results) requires an array.");
+    return results.map(formatRef).join("\n");
+  },
+});
+
+let contextObjectPrototype;
+
+const capturedConsole = Object.freeze(Object.fromEntries(
+  ["log", "info", "warn", "error"].map((level) => [level, (...args) => {
+    parentPort.postMessage({ type: "console", level, text: args.map((value) => typeof value === "string" ? value : inspect(value, { depth: 4, breakLength: 120 })).join(" ") });
+  }]),
+));
+
+function assertJsonValue(value, path = "emit", seen = new Set()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(path + " must contain only finite JSON numbers.");
+    return;
+  }
+  if (typeof value !== "object") throw new Error(path + " must be a JSON value; received " + typeof value + ".");
+  if (seen.has(value)) throw new Error(path + " must not contain cycles.");
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      if (!Object.prototype.hasOwnProperty.call(value, index)) throw new Error(path + " must not contain sparse array entries.");
+      assertJsonValue(value[index], path + "[" + index + "]", seen);
+    }
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== null && prototype !== Object.prototype && prototype !== contextObjectPrototype) 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.");
+    for (const [key, entry] of Object.entries(value)) assertJsonValue(entry, path + "." + key, seen);
+  }
+  seen.delete(value);
+}
+
+parentPort.on("message", async (message) => {
+  if (message.type === "response") {
+    const entry = pending.get(message.callId);
+    if (!entry) return;
+    pending.delete(message.callId);
+    if (message.ok) entry.resolve(message.value);
+    else entry.reject(new Error(message.error));
+    return;
+  }
+  if (message.type !== "start") return;
+  try {
+    const sandbox = { runs, emit(value) { assertJsonValue(value); parentPort.postMessage({ type: "emit", value }); }, console: capturedConsole };
+    const context = vm.createContext(sandbox, { codeGeneration: { strings: false, wasm: false } });
+    contextObjectPrototype = vm.runInContext("Object.prototype", context);
+    const compiled = new vm.Script("(async () => {\n" + message.script + "\n})()", { filename: "workflow-script.js" });
+    const value = await compiled.runInContext(context);
+    const persistedValue = value === undefined ? null : value;
+    assertJsonValue(persistedValue, "return");
+    parentPort.postMessage({ type: "complete", value: persistedValue });
+  } catch (error) {
+    parentPort.postMessage({ type: "error", error: error && error.stack ? error.stack : String(error) });
+  }
+});
+`;
+
+export interface WorkflowScriptChildResult {
+	key: string;
+	ok: boolean;
+	runId?: string;
+	output: string;
+	error?: string;
+	structuredOutput?: unknown;
+	artifactPaths: string[];
+	results?: unknown[];
+}
+
+export interface WorkflowScriptTraceEntry {
+	operation: "run" | "status";
+	key: string;
+	state: "started" | "completed" | "failed" | "reused";
+	runId?: string;
+	durationMs?: number;
+	phase?: string;
+	label?: string;
+	error?: string;
+}
+
+export interface WorkflowScriptResult {
+	value: unknown;
+	emits: unknown[];
+	console: Array<{ level: "log" | "info" | "warn" | "error"; text: string }>;
+	trace: WorkflowScriptTraceEntry[];
+	children: WorkflowScriptChildResult[];
+}
+
+export class WorkflowScriptError extends Error {
+	readonly partial: Omit<WorkflowScriptResult, "value">;
+
+	constructor(message: string, partial: Omit<WorkflowScriptResult, "value">) {
+		super(message);
+		this.name = "WorkflowScriptError";
+		this.partial = partial;
+	}
+}
+
+export interface RunWorkflowScriptOptions {
+	script: string;
+	timeoutMs: number;
+	signal?: AbortSignal;
+	launch: (key: string, params: Record<string, unknown>, signal: AbortSignal) => Promise<WorkflowScriptChildResult>;
+	status: (keyOrRunId: string, signal: AbortSignal) => Promise<WorkflowScriptChildResult>;
+	onTrace?: (trace: WorkflowScriptTraceEntry[]) => void;
+	onEmit?: (emits: unknown[]) => void;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isPlainJsonObject(value: unknown): value is Record<string, unknown> {
+	if (!isRecord(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || prototype === Object.prototype;
+}
+
+function omitUndefinedWorkflowValues(value: unknown, seen = new Set<object>()): unknown {
+	if (value === null || typeof value !== "object") return value;
+	if (seen.has(value)) return value;
+	seen.add(value);
+	const normalized = Array.isArray(value)
+		? value.map((entry) => entry === undefined ? null : omitUndefinedWorkflowValues(entry, seen))
+		: isPlainJsonObject(value)
+			? Object.fromEntries(Object.entries(value).flatMap(([key, entry]) => entry === undefined ? [] : [[key, omitUndefinedWorkflowValues(entry, seen)]]))
+			: value;
+	seen.delete(value);
+	return normalized;
+}
+
+export function assertWorkflowJsonValue(value: unknown, path = "value", seen = new Set<object>()): void {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return;
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error(`${path} must contain only finite JSON numbers.`);
+		return;
+	}
+	if (typeof value !== "object") throw new Error(`${path} must be a JSON value; received ${typeof value}.`);
+	if (seen.has(value)) throw new Error(`${path} must not contain cycles.`);
+	seen.add(value);
+	if (Array.isArray(value)) {
+		for (let index = 0; index < value.length; index++) {
+			if (!Object.hasOwn(value, index)) throw new Error(`${path} must not contain sparse array entries.`);
+			assertWorkflowJsonValue(value[index], `${path}[${index}]`, seen);
+		}
+	} else {
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== null && prototype !== Object.prototype) 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.`);
+		for (const [key, entry] of Object.entries(value)) assertWorkflowJsonValue(entry, `${path}.${key}`, seen);
+	}
+	seen.delete(value);
+}
+
+export function formatWorkflowJsonPreview(value: unknown, maxLength: number): string | undefined {
+	try {
+		assertWorkflowJsonValue(value);
+		const serialized = JSON.stringify(value);
+		return typeof serialized === "string" ? serialized.slice(0, maxLength) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function stableJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+	if (isRecord(value)) return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+	return JSON.stringify(value) ?? "undefined";
+}
+
+function validateKey(value: unknown): string {
+	if (typeof value !== "string" || !KEY_PATTERN.test(value)) {
+		throw new Error("runs.run key must be 1-128 characters using letters, numbers, '.', '_' or '-', and start with a letter or number.");
+	}
+	return value;
+}
+
+function workflowStringMetadata(params: Record<string, unknown>): Pick<WorkflowScriptTraceEntry, "phase" | "label"> {
+	return {
+		...(typeof params.phase === "string" && params.phase.trim() ? { phase: params.phase.trim() } : {}),
+		...(typeof params.label === "string" && params.label.trim() ? { label: params.label.trim() } : {}),
+	};
+}
+
+export async function runWorkflowScript(options: RunWorkflowScriptOptions): Promise<WorkflowScriptResult> {
+	if (!options.script.trim()) throw new Error("workflowScript must not be empty.");
+	if (!Number.isInteger(options.timeoutMs) || options.timeoutMs < 1) throw new Error("workflow script timeout must be a positive integer.");
+
+	const worker = new Worker(WORKER_SOURCE, { eval: true });
+	const emits: unknown[] = [];
+	const consoleEntries: WorkflowScriptResult["console"] = [];
+	const trace: WorkflowScriptTraceEntry[] = [];
+	const children = new Map<string, WorkflowScriptChildResult>();
+	const childOrder: string[] = [];
+	const launches = new Map<string, { fingerprint: string; promise: Promise<WorkflowScriptChildResult> }>();
+	const childController = new AbortController();
+	let settled = false;
+
+	const partial = (): Omit<WorkflowScriptResult, "value"> => ({ emits, console: consoleEntries, trace, children: childOrder.flatMap((key) => {
+		const child = children.get(key);
+		return child ? [child] : [];
+	}) });
+	const traceChanged = () => options.onTrace?.([...trace]);
+
+	return await new Promise<WorkflowScriptResult>((resolve, reject) => {
+		const finish = (outcome: { value: unknown } | { error: Error }) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			options.signal?.removeEventListener("abort", onAbort);
+			void worker.terminate();
+			childController.abort("error" in outcome ? outcome.error : new Error("Workflow script completed; unawaited child launches are aborted."));
+			if ("error" in outcome) reject(new WorkflowScriptError(outcome.error.message, partial()));
+			else resolve({ value: outcome.value, ...partial() });
+		};
+		const onAbort = () => finish({ error: new Error("Workflow script aborted.") });
+		const timer = setTimeout(() => finish({ error: new Error(`Workflow script timed out after ${options.timeoutMs}ms.`) }), options.timeoutMs);
+		options.signal?.addEventListener("abort", onAbort, { once: true });
+		if (options.signal?.aborted) return onAbort();
+
+		worker.on("error", (error) => finish({ error: new Error(`Workflow worker failed: ${error instanceof Error ? error.message : String(error)}`) }));
+		worker.on("exit", (code) => {
+			if (!settled && code !== 0) finish({ error: new Error(`Workflow worker exited with code ${code}.`) });
+		});
+		worker.on("message", (message: Record<string, unknown>) => {
+			if (message.type === "emit") {
+				try {
+					assertWorkflowJsonValue(message.value, "emit");
+				} catch (error) {
+					finish({ error: new Error(`Workflow emit could not be persisted: ${error instanceof Error ? error.message : String(error)}`) });
+					return;
+				}
+				emits.push(message.value);
+				try {
+					options.onEmit?.([...emits]);
+				} catch (error) {
+					emits.pop();
+					finish({ error: new Error(`Workflow emit could not be persisted: ${error instanceof Error ? error.message : String(error)}`) });
+				}
+				return;
+			}
+			if (message.type === "console") {
+				const level = message.level;
+				if ((level === "log" || level === "info" || level === "warn" || level === "error") && typeof message.text === "string") consoleEntries.push({ level, text: message.text });
+				return;
+			}
+			if (message.type === "complete") {
+				try {
+					assertWorkflowJsonValue(message.value, "return");
+				} catch (error) {
+					return finish({ error: new Error(`Workflow return could not be persisted: ${error instanceof Error ? error.message : String(error)}`) });
+				}
+				return finish({ value: message.value });
+			}
+			if (message.type === "error") return finish({ error: new Error(typeof message.error === "string" ? message.error : "Workflow script failed.") });
+			if (message.type !== "call" || typeof message.callId !== "number" || typeof message.method !== "string" || !isRecord(message.args)) return;
+
+			const respond = (promise: Promise<WorkflowScriptChildResult>) => {
+				void promise.then(
+					(value) => worker.postMessage({ type: "response", callId: message.callId, ok: true, value: omitUndefinedWorkflowValues(value) }),
+					(error: unknown) => worker.postMessage({ type: "response", callId: message.callId, ok: false, error: error instanceof Error ? error.message : String(error) }),
+				);
+			};
+
+			if (message.method === "status") {
+				const keyOrRunId = message.args.keyOrRunId;
+				if (typeof keyOrRunId !== "string" || !keyOrRunId.trim()) return respond(Promise.reject(new Error("runs.status(keyOrRunId) requires a non-empty string.")));
+				const known = children.get(keyOrRunId);
+				const target = known?.runId ?? keyOrRunId;
+				trace.push({ operation: "status", key: keyOrRunId, state: "started", ...(known?.runId ? { runId: known.runId } : {}) });
+				traceChanged();
+				respond(options.status(target, childController.signal).then((result) => {
+					trace.push({ operation: "status", key: keyOrRunId, state: result.ok ? "completed" : "failed", ...(result.runId ? { runId: result.runId } : {}), ...(!result.ok ? { error: result.output } : {}) });
+					traceChanged();
+					if (!result.ok) throw new Error(`Status '${keyOrRunId}' failed: ${result.output}`);
+					return result;
+				}));
+				return;
+			}
+			if (message.method !== "run") return respond(Promise.reject(new Error(`Unknown runs API method '${message.method}'.`)));
+
+			let key: string;
+			try {
+				key = validateKey(message.args.key);
+			} catch (error) {
+				return respond(Promise.reject(error));
+			}
+			const params = message.args.params;
+			if (!isRecord(params)) return respond(Promise.reject(new Error(`runs.run('${key}', params) requires a params object.`)));
+			if (params.action !== undefined) return respond(Promise.reject(new Error(`runs.run('${key}') accepts execution params only; management action is not allowed.`)));
+			if (params.workflowScript !== undefined) return respond(Promise.reject(new Error(`runs.run('${key}') cannot start a nested workflow script.`)));
+			if (params.tasks !== undefined || params.chain !== undefined || params.concurrency !== undefined || params.chainDir !== undefined) {
+				return respond(Promise.reject(new Error(`runs.run('${key}') accepts one child via { agent, task }; use runs.all(...) and JavaScript control flow for orchestration.`)));
+			}
+			if (params.worktree !== undefined && typeof params.worktree !== "boolean") {
+				return respond(Promise.reject(new Error(`runs.run('${key}') worktree must be true or false.`)));
+			}
+			const collectFailure = message.args.collectFailure === true;
+			const deliver = (promise: Promise<WorkflowScriptChildResult>) => collectFailure
+				? promise
+				: promise.then((result) => {
+					if (!result.ok) throw new Error(`Run '${key}' failed: ${result.error ?? result.output}`);
+					return result;
+				});
+			const fingerprint = stableJson(params);
+			const existing = launches.get(key);
+			if (existing) {
+				if (existing.fingerprint !== fingerprint) return respond(Promise.reject(new Error(`Duplicate workflow key '${key}' used with incompatible launch params.`)));
+				trace.push({ operation: "run", key, state: "reused", ...workflowStringMetadata(params) });
+				traceChanged();
+				return respond(deliver(existing.promise));
+			}
+
+			const startedAt = Date.now();
+			childOrder.push(key);
+			trace.push({ operation: "run", key, state: "started", ...workflowStringMetadata(params) });
+			traceChanged();
+			const promise = Promise.resolve().then(() => options.launch(key, { ...params, async: params.async ?? false }, childController.signal)).then((result) => {
+				const normalized = !result.ok && !result.error ? { ...result, error: result.output } : result;
+				children.set(key, normalized);
+				trace.push({ operation: "run", key, state: normalized.ok ? "completed" : "failed", durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), ...(normalized.runId ? { runId: normalized.runId } : {}), ...(!normalized.ok ? { error: normalized.error ?? normalized.output } : {}) });
+				traceChanged();
+				return normalized;
+			}, (error: unknown) => {
+				const text = error instanceof Error ? error.message : String(error);
+				const failure: WorkflowScriptChildResult = { key, ok: false, output: text, error: text, artifactPaths: [] };
+				children.set(key, failure);
+				trace.push({ operation: "run", key, state: "failed", durationMs: Date.now() - startedAt, ...workflowStringMetadata(params), error: text });
+				traceChanged();
+				return failure;
+			});
+			launches.set(key, { fingerprint, promise });
+			respond(deliver(promise));
+		});
+
+		worker.postMessage({ type: "start", script: options.script });
+	});
+}

package/agents/advisor.md

@@ -1,73 +0,0 @@
----
-name: advisor
-description: Compatibility alias for oracle; high-context decision-consistency advisor
-tools: read, grep, find, ls, bash, intercom
-thinking: high
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-defaultContext: fork
----
-
-You are the advisor, the compatibility alias for oracle: a high-context decision-consistency subagent.
-
-Your primary job is to prevent the main agent from making hidden, conflicting, or inconsistent decisions by treating the inherited forked context as the authoritative contract. You are not the primary executor. You do not silently become a second decision-maker.
-
-Before you do anything else, reconstruct the key inherited decisions, constraints, and open questions from the forked conversation, codebase state, and task. Those decisions form your baseline contract. Preserve them unless there is strong evidence they should be overturned.
-
-If you need clarification from the main agent and runtime bridge instructions are present, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply. Use `reason: "progress_update"` only for concise updates when blocked, explicitly asked for progress, or when a recommendation or concern would benefit from immediate discussion. Keep coordination traffic tight and purposeful. Do not narrate your whole review through `contact_supervisor`.
-
-Do not send routine completion handoffs. If no coordination is needed, return the final oracle recommendation normally. Fall back to generic `intercom` only if `contact_supervisor` is unavailable and the runtime bridge instructions identify a safe target.
-
-Core responsibilities:
-- reconstruct inherited decisions, constraints, and open questions from the context
-- identify drift between the current trajectory and those inherited decisions
-- surface contradictions and hidden assumptions the main agent may be missing
-- call out when a proposed move conflicts with an earlier decision or constraint
-- protect consistency over novelty; prefer the path that honors existing decisions unless the context clearly supports a pivot
-- when you do recommend a pivot, explain exactly which prior assumption or decision should be revised and why
-- exploit your clean forked context to spot things the main agent may have missed due to context rot, accumulated reasoning, or errors in the original instruction
-- look beyond the explicit question and suggest guidance based on the overall agent trajectory, even when not directly asked
-
-What you do not do by default:
-- do not edit files or write code
-- do not propose additional parallel decision-makers or new subagent trees unless explicitly asked
-- do not assume a `worker` implementation handoff is the default outcome
-- do not propose broad pivots unless the context clearly supports them
-- do not continue the user conversation directly
-
-Working rules:
-- Use `bash` only for inspection, verification, or read-only analysis.
-- If information is missing and it matters, ask the main agent with `contact_supervisor` and `reason: "need_decision"` instead of guessing.
-- If the answer depends on a decision the main agent has not made yet, stop and ask with `contact_supervisor` before continuing.
-- When bridge instructions are present, send concise coordination messages only when a recommendation, concern, or question would benefit from immediate discussion instead of waiting silently until the final return.
-- Prefer narrow, specific corrections to the current path over rewriting the whole plan.
-
-Your output should follow this shape. If no executor handoff is warranted, say so plainly.
-
-Inherited decisions:
-- the key decisions, constraints, and assumptions already in play
-
-Diagnosis:
-- what is actually going on
-- what the main agent may be missing
-
-Drift / contradiction check:
-- where the current trajectory conflicts with inherited decisions or constraints
-- what assumptions have quietly changed
-
-Recommendation:
-- the best next move
-- why it is the best move
-- if recommending a pivot, which inherited decision is being revised and why
-
-Risks:
-- what could still go wrong
-- what assumptions remain uncertain
-
-Need from main agent:
-- specific question or decision required before continuing, if any
-
-Suggested execution prompt:
-- a concrete prompt for `worker`, only if an implementation handoff is actually warranted
-- if no handoff is warranted, say so explicitly

package/src/extension/chain-validation.ts

@@ -1,181 +0,0 @@
-/**
- * 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": "worker", "task": "do X"} or {"checkpoint": "review", "message": "Approve before implementation?"}';
-const PARALLEL_TASK_EXAMPLE = '{"agent": "worker", "task": "do X"}';
-const DYNAMIC_TEMPLATE_EXAMPLE = '{"agent": "worker", "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 validateCheckpointShape(step: Record<string, unknown>, path: string): void {
-	if (step.checkpoint === undefined) return;
-	const allowed = new Set(["checkpoint", "message", "phase", "label"]);
-	const mixed = Object.keys(step).filter((key) => !allowed.has(key));
-	if (mixed.length > 0) {
-		throw new Error(`subagent ${path}: checkpoint steps cannot be mixed with child-launch properties ${quoteList(mixed)}.\n\nExample: {"checkpoint": "review", "message": "Approve before implementation?"}`);
-	}
-	if (typeof step.checkpoint !== "string" || !step.checkpoint.trim()) {
-		throw new Error(`subagent ${path}.checkpoint: expected a non-empty string.`);
-	}
-	if (step.message !== undefined && typeof step.message !== "string") {
-		throw new Error(`subagent ${path}.message: expected a string.`);
-	}
-}
-
-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);
-		validateCheckpointShape(step, stepPath);
-
-		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}`,
-		);
-	});
-}