@iowarp/clio-coder 0.3.6 → 0.3.8

package/src/domains/dispatch/delegation-plan.ts

@@ -0,0 +1,164 @@
+import { createHash } from "node:crypto";
+import { pathBoundaryCovers } from "../../core/path-boundary.js";
+import { normalizeWriteBoundary } from "../agents/write-boundary.js";
+
+export type DelegationTaskMode = "sequential" | "parallel";
+
+export interface DelegationPlanTask {
+	id: string;
+	agent: string;
+	description: string;
+	depends_on: ReadonlyArray<string>;
+	writes: ReadonlyArray<string>;
+	mode?: DelegationTaskMode;
+}
+
+export interface DelegationPlan {
+	tasks: ReadonlyArray<DelegationPlanTask>;
+}
+
+export type DelegationPlanReason =
+	| "delegation_plan_malformed"
+	| "delegation_plan_over_max_tasks"
+	| "delegation_plan_duplicate_id"
+	| "delegation_plan_roster_violation"
+	| "delegation_plan_dependency_unknown"
+	| "delegation_plan_dependency_cycle"
+	| "delegation_plan_writes_outside_boundary";
+
+export type DelegationPlanValidation =
+	| { ok: true; plan: DelegationPlan; hash: string }
+	| { ok: false; reason: DelegationPlanReason; detail: string };
+
+export interface ValidateDelegationPlanInput {
+	value: unknown;
+	roster: ReadonlyArray<string>;
+	maxTasks: number;
+	writes: ReadonlyArray<string>;
+}
+
+export const DELEGATION_PROPOSAL_BRIEFING_MAX_BYTES = 12_000;
+
+export function buildDelegationProposalBriefing(proposals: ReadonlyArray<{ agent: string; output: string }>): string {
+	const value = proposals.map((proposal) => `PROPOSAL ${proposal.agent}\n${proposal.output}`).join("\n\n");
+	if (Buffer.byteLength(value, "utf8") <= DELEGATION_PROPOSAL_BRIEFING_MAX_BYTES) return value;
+	const suffix = "\n[truncated]";
+	const source = Buffer.from(value, "utf8");
+	let end = DELEGATION_PROPOSAL_BRIEFING_MAX_BYTES - Buffer.byteLength(suffix, "utf8");
+	while (end > 0) {
+		const byte = source[end];
+		if (byte === undefined || (byte & 0xc0) !== 0x80) break;
+		end -= 1;
+	}
+	return `${source.subarray(0, end).toString("utf8")}${suffix}`;
+}
+
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u;
+
+function malformed(detail: string): DelegationPlanValidation {
+	return { ok: false, reason: "delegation_plan_malformed", detail };
+}
+
+export function validateDelegationPlan(input: ValidateDelegationPlanInput): DelegationPlanValidation {
+	if (input.value === null || typeof input.value !== "object" || Array.isArray(input.value)) {
+		return malformed("delegation plan must be an object");
+	}
+	const record = input.value as Record<string, unknown>;
+	if (Object.keys(record).some((key) => key !== "tasks") || !Array.isArray(record.tasks)) {
+		return malformed("delegation plan must carry only tasks[]");
+	}
+	if (record.tasks.length === 0) return malformed("delegation plan must carry at least one task");
+	if (record.tasks.length > input.maxTasks) {
+		return {
+			ok: false,
+			reason: "delegation_plan_over_max_tasks",
+			detail: `delegation plan returned ${record.tasks.length} tasks, above maxTasks ${input.maxTasks}`,
+		};
+	}
+	const roster = new Set(input.roster);
+	const ids = new Set<string>();
+	const tasks: DelegationPlanTask[] = [];
+	for (const raw of record.tasks) {
+		if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return malformed("every task must be an object");
+		const task = raw as Record<string, unknown>;
+		if (
+			Object.keys(task).some((key) => !["id", "agent", "description", "depends_on", "writes", "mode"].includes(key)) ||
+			typeof task.id !== "string" ||
+			!ID_RE.test(task.id) ||
+			typeof task.agent !== "string" ||
+			task.agent.length === 0 ||
+			typeof task.description !== "string" ||
+			task.description.trim().length === 0 ||
+			!Array.isArray(task.depends_on) ||
+			task.depends_on.some((value) => typeof value !== "string" || value.length === 0) ||
+			!Array.isArray(task.writes) ||
+			task.writes.some((value) => typeof value !== "string" || value.length === 0) ||
+			(task.mode !== undefined && task.mode !== "sequential" && task.mode !== "parallel")
+		) {
+			return malformed("each task requires id, agent, description, depends_on[], writes[], and an optional valid mode");
+		}
+		if (ids.has(task.id)) {
+			return { ok: false, reason: "delegation_plan_duplicate_id", detail: `duplicate task id '${task.id}'` };
+		}
+		if (!roster.has(task.agent)) {
+			return {
+				ok: false,
+				reason: "delegation_plan_roster_violation",
+				detail: `task '${task.id}' names agent '${task.agent}' outside the roster`,
+			};
+		}
+		let writes: ReadonlyArray<string>;
+		try {
+			writes = normalizeWriteBoundary(task.writes as string[]);
+		} catch (error) {
+			return malformed(`task '${task.id}' has invalid writes: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const outside = writes.find((path) => !pathBoundaryCovers(input.writes, path));
+		if (outside !== undefined) {
+			return {
+				ok: false,
+				reason: "delegation_plan_writes_outside_boundary",
+				detail: `task '${task.id}' writes '${outside}' outside the plan step boundary`,
+			};
+		}
+		ids.add(task.id);
+		tasks.push({
+			id: task.id,
+			agent: task.agent,
+			description: task.description,
+			depends_on: [...(task.depends_on as string[])],
+			writes,
+			...(task.mode !== undefined ? { mode: task.mode as DelegationTaskMode } : {}),
+		});
+	}
+	for (const task of tasks) {
+		const unknown = task.depends_on.find((dependency) => !ids.has(dependency));
+		if (unknown !== undefined) {
+			return {
+				ok: false,
+				reason: "delegation_plan_dependency_unknown",
+				detail: `task '${task.id}' depends on unknown task '${unknown}'`,
+			};
+		}
+	}
+	const remaining = new Set(ids);
+	const completed = new Set<string>();
+	while (remaining.size > 0) {
+		const ready = tasks.filter(
+			(task) => remaining.has(task.id) && task.depends_on.every((dependency) => completed.has(dependency)),
+		);
+		if (ready.length === 0) {
+			return {
+				ok: false,
+				reason: "delegation_plan_dependency_cycle",
+				detail: `delegation plan dependency cycle includes ${[...remaining].sort().join(", ")}`,
+			};
+		}
+		for (const task of ready) {
+			remaining.delete(task.id);
+			completed.add(task.id);
+		}
+	}
+	const plan = { tasks } satisfies DelegationPlan;
+	return { ok: true, plan, hash: createHash("sha256").update(JSON.stringify(plan)).digest("hex") };
+}

package/src/domains/dispatch/execution-plan.ts

@@ -3,7 +3,7 @@ import type { ResultContract } from "../agents/result-contract.js";
 import type { AgentAutomationAuthority } from "../agents/spec.js";
 import type { ExecutionRole } from "./execution-role.js";
 
-export type ExecutionPlanTopology = "parallel" | "sequential" | "pipeline" | "review" | "compete" | "fleet";
+export type ExecutionPlanTopology = "parallel" | "sequential" | "pipeline" | "review" | "compete" | "council" | "fleet";
 export type ExecutionPlanScope = "readonly" | "workspace";
 export type ExecutionPlanFailurePolicy = "stop" | "continue";
 
@@ -56,6 +56,19 @@ export interface ExecutionPlanAgentStep {
 	 * contract declares no boundary at all and is therefore not enforced.
 	 */
 	writes?: ReadonlyArray<string>;
+	/** Exact per-step route defaults from a version 5 fleet contract. */
+	target?: string;
+	profile?: string;
+	/** Version 5 gate authoring and baseline execution facts. */
+	gate?: { path: string; commandId: string };
+	/** Version 5 dynamic planning facts. */
+	plan?: {
+		roster: ReadonlyArray<string>;
+		maxTasks: number;
+		proposals: boolean;
+	};
+	/** The plan step that admitted this dynamically authored task. */
+	planParentId?: string;
 }
 
 /**
@@ -85,6 +98,8 @@ export interface ExecutionPlanCodeStep {
 	commitFrom?: ReadonlyArray<string>;
 	/** Declared write boundary; see `ExecutionPlanAgentStep.writes`. */
 	writes?: ReadonlyArray<string>;
+	/** A gate check executes a declared gate file through this command. */
+	gate?: { gateId: string; path: string };
 }
 
 export type ExecutionPlanStep = ExecutionPlanAgentStep | ExecutionPlanCodeStep;
@@ -106,6 +121,8 @@ export interface ExecutionPlan {
 	topology: ExecutionPlanTopology;
 	rootTask: string;
 	maxWorkers: number;
+	/** Serialize writer admission when set. The only supported value in this cut is one. */
+	writers?: 1;
 	onFailure: ExecutionPlanFailurePolicy;
 	steps: ReadonlyArray<ExecutionPlanStep>;
 	loops: ReadonlyArray<ExecutionPlanLoop>;
@@ -240,6 +257,7 @@ function checkLoops(steps: ReadonlyArray<ExecutionPlanStep>, loops: ReadonlyArra
 function checkWriteBoundaryWaves(
 	steps: ReadonlyArray<ExecutionPlanStep>,
 	waves: ReadonlyArray<ReadonlyArray<string>>,
+	writerLimit?: 1,
 ): void {
 	const byId = new Map(steps.map((step) => [step.id, step]));
 	for (const [index, wave] of waves.entries()) {
@@ -250,7 +268,7 @@ function checkWriteBoundaryWaves(
 		const declared = members.filter((step) => step.writes !== undefined);
 		if (declared.length === 0) continue;
 		const undeclared = members.filter((step) => step.writes === undefined);
-		if (undeclared.length > 0) {
+		if (undeclared.length > 0 && writerLimit !== 1) {
 			throw new Error(
 				`execution plan: wave ${index} mixes boundary-enforced steps (${declared
 					.map((step) => step.id)
@@ -260,7 +278,7 @@ function checkWriteBoundaryWaves(
 			);
 		}
 		const writers = declared.filter((step) => (step.writes?.length ?? 0) > 0);
-		if (writers.length > 1) {
+		if (writers.length > 1 && writerLimit !== 1) {
 			throw new Error(
 				`execution plan: wave ${index} schedules ${writers.length} steps that may write (${writers
 					.map((step) => step.id)
@@ -273,6 +291,9 @@ function checkWriteBoundaryWaves(
 }
 
 export function compileExecutionPlan(input: ExecutionPlanInput): ExecutionPlan {
+	if (input.writers !== undefined && input.writers !== 1) {
+		throw new Error("execution plan: writers must be 1 when present");
+	}
 	const steps = canonicalSteps(input.steps);
 	const loops = (input.loops ?? []).map((loop) => ({
 		...loop,
@@ -281,12 +302,13 @@ export function compileExecutionPlan(input: ExecutionPlanInput): ExecutionPlan {
 	}));
 	checkLoops(steps, loops);
 	const waves = executionPlanWaves(steps, input.maxWorkers);
-	checkWriteBoundaryWaves(steps, waves);
+	checkWriteBoundaryWaves(steps, waves, input.writers);
 	const canonical = {
 		version: 4 as const,
 		topology: input.topology,
 		rootTask: input.rootTask,
 		maxWorkers: input.maxWorkers,
+		...(input.writers === 1 ? { writers: 1 as const } : {}),
 		onFailure: input.onFailure,
 		steps,
 		loops,
@@ -309,6 +331,55 @@ export function executionPlanAncestors(plan: ExecutionPlan, stepId: string): Rea
 	return ancestors;
 }
 
+/** Recompile a plan with coordinator-validated dynamic agent tasks. */
+export function spliceExecutionPlan(
+	plan: ExecutionPlan,
+	parentId: string,
+	tasks: ReadonlyArray<{
+		id: string;
+		agentId: string;
+		task: string;
+		dependencies: ReadonlyArray<string>;
+		writes: ReadonlyArray<string>;
+		target?: string;
+		profile?: string;
+		requestedAuthority: AgentAutomationAuthority;
+		approvedAuthority: AgentAutomationAuthority | null;
+		expectedResultContract: ResultContract["kind"];
+		executionRole: ExecutionRole;
+	}>,
+): ExecutionPlan {
+	const parent = plan.steps.find((step) => step.id === parentId);
+	if (parent?.kind !== "agent" || parent.plan === undefined) {
+		throw new Error(`execution plan: '${parentId}' is not a plan step`);
+	}
+	const inserted: ExecutionPlanStepInput[] = tasks.map((task) => ({
+		kind: "agent",
+		id: task.id,
+		agentId: task.agentId,
+		executionRole: task.executionRole,
+		scope: task.writes.length > 0 ? "workspace" : "readonly",
+		expectedResultContract: task.expectedResultContract,
+		requestedAuthority: task.requestedAuthority,
+		approvedAuthority: task.approvedAuthority,
+		dependencies: [parentId, ...task.dependencies],
+		task: task.task,
+		writes: [...task.writes],
+		...(task.target !== undefined ? { target: task.target } : {}),
+		...(task.profile !== undefined ? { profile: task.profile } : {}),
+		planParentId: parentId,
+	}));
+	return compileExecutionPlan({
+		topology: plan.topology,
+		rootTask: plan.rootTask,
+		maxWorkers: plan.maxWorkers,
+		...(plan.writers === 1 ? { writers: 1 as const } : {}),
+		onFailure: plan.onFailure,
+		steps: [...plan.steps, ...inserted],
+		loops: plan.loops,
+	});
+}
+
 /** A linear step declares no dependencies; the compiler chains them by position. */
 export type ExecutionPlanLinearStepInput =
 	| (Omit<ExecutionPlanAgentStep, "kind" | "dependencies"> & { kind?: "agent" })
@@ -317,7 +388,7 @@ export type ExecutionPlanLinearStepInput =
 export function compileLinearExecutionPlan(
 	input: Omit<ExecutionPlanInput, "steps"> & { steps: ReadonlyArray<ExecutionPlanLinearStepInput> },
 ): ExecutionPlan {
-	const parallel = input.topology === "parallel" || input.topology === "compete";
+	const parallel = input.topology === "parallel" || input.topology === "compete" || input.topology === "council";
 	return compileExecutionPlan({
 		...input,
 		steps: input.steps.map((step, index): ExecutionPlanStepInput => {

package/src/domains/dispatch/execution-role.ts

@@ -47,7 +47,7 @@ export function isExecutionRole(value: unknown): value is ExecutionRole {
  * statistics belong to: every compete candidate occupies a distinct `candidate`
  * position but they are all ordinary `builder` routes.
  */
-export type GateTopologyRole = "builder" | "reviewer" | "candidate" | "judge";
+export type GateTopologyRole = "builder" | "reviewer" | "candidate" | "judge" | "member" | "synthesis";
 
 /**
  * Facts the role is derived from. `capabilityClass` and `resultContractKind`
@@ -86,6 +86,8 @@ export function deriveExecutionRole(input: ExecutionRoleInput): ExecutionRole {
 	if (input.attempt > 0) return "recovery";
 	if (input.gateRole === "reviewer") return "reviewer";
 	if (input.gateRole === "judge") return "judge";
+	if (input.gateRole === "synthesis") return "judge";
+	if (input.gateRole === "member") return "researcher";
 	if (input.gateRole === "builder" || input.gateRole === "candidate") return "builder";
 	if (input.resultContractKind === "verifier-report") return "verifier";
 	if (input.capabilityClass === "read-only") return "researcher";
@@ -170,9 +172,17 @@ export function gateDeciderAgentId(requested: string | undefined): string {
  * the slot. The gate validates that answer and fails closed on a malformed one,
  * so also enforcing an inapplicable recipe postcondition would fail the run
  * before its verdict could be read.
+ *
+ * `synthesis` is the third decider and belongs here for the same reason.
+ * {@link deriveExecutionRole} already resolves it to the `judge` role, and
+ * `isBoundedGateRolePrompt` admits it only under the council judge prompt,
+ * which asks for `{"verdict","text"}`. A council seats the read-only
+ * `researcher` by default, whose recipe declares `research-report`, so leaving
+ * the recipe postcondition on the slot sealed a contract failure on every
+ * correct synthesis and burned the configured retries reproducing it.
  */
 export function appliesRecipeResultContract(gateRole: GateTopologyRole | undefined): boolean {
-	return gateRole !== "reviewer" && gateRole !== "judge";
+	return gateRole !== "reviewer" && gateRole !== "judge" && gateRole !== "synthesis";
 }
 
 /** The route dimensions a gate correlation is measured across. */