@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/tools/dispatch-plan.ts

@@ -20,6 +20,7 @@ import type { ResultContract } from "../domains/agents/result-contract.js";
 import { AGENT_AUTOMATION_AUTHORITIES, type AgentAutomationAuthority } from "../domains/agents/spec.js";
 import type { DispatchRequest } from "../domains/dispatch/contract.js";
 import { type ExecutionRole, isExecutionRole } from "../domains/dispatch/execution-role.js";
+import { type DispatchIntent, isDispatchIntent } from "../domains/dispatch/intent.js";
 import {
 	type ApprovedAssignmentRoute,
 	cloneApprovedAssignmentRoute,
@@ -31,7 +32,15 @@ import { isRoutingIntent, type RoutingIntent } from "../domains/dispatch/routing
 import type { DispatchFailoverCandidate, DispatchFailoverMode } from "../domains/dispatch/validation.js";
 import { prepareDispatchArguments } from "./dispatch-arguments.js";
 
-export type DispatchPlanTopology = "parallel" | "sequential" | "pipeline" | "review" | "compete" | "detached" | "fleet";
+export type DispatchPlanTopology =
+	| "parallel"
+	| "sequential"
+	| "pipeline"
+	| "review"
+	| "compete"
+	| "council"
+	| "detached"
+	| "fleet";
 
 export type DispatchPlanSource = null | {
 	kind: "scout-transition";
@@ -51,6 +60,9 @@ export interface DispatchPlanTaskView {
 	task: string;
 	/** Exact canonical bounded briefing approved for this task. */
 	briefing?: string;
+	worktree?: true;
+	apply?: "merge" | "preserve";
+	worktreeDestination?: string;
 	model?: string;
 	node?: string;
 	/** Effective transport identity; host is authenticated for SSH placement. */
@@ -59,7 +71,8 @@ export interface DispatchPlanTaskView {
 	/** Effective configured target id used as the execution pin. */
 	target?: string;
 	/** Coordinator role when the topology expands one user task into several runs. */
-	role?: "task" | "builder" | "reviewer" | "candidate" | "judge";
+	role?: "task" | "builder" | "reviewer" | "candidate" | "judge" | "member" | "synthesis";
+	council?: { label: string; color?: string; round: number; rounds: number; synthesis: "none" | "judge" | "vote" };
 	/** One-based source task or gate cycle/candidate number. */
 	position?: number;
 	/** Normalized advisory posture and hard bounds sealed into the plan. */
@@ -79,6 +92,8 @@ export interface DispatchPlanTaskView {
 	authorityGrant: DispatchPlanAuthorityGrant;
 	agentDecision: RouteDecisionV1 | null;
 	wave: number | null;
+	intent?: DispatchIntent;
+	resolvedVerification?: NonNullable<DispatchRequest["resolvedVerification"]>;
 }
 
 export interface DispatchPlanView {
@@ -112,7 +127,20 @@ export interface ResolvedDispatchPlanArtifact {
 		Required<Pick<DispatchPlanTaskView, "agent" | "task" | "model" | "node" | "target">> &
 			Required<Pick<DispatchPlanTaskView, "nodeKind" | "failover">> &
 			Required<Pick<DispatchPlanTaskView, "routingIntent">> &
-			Pick<DispatchPlanTaskView, "briefing" | "nodeHost" | "role" | "position" | "allowedCandidates"> &
+			Pick<
+				DispatchPlanTaskView,
+				| "briefing"
+				| "worktree"
+				| "apply"
+				| "worktreeDestination"
+				| "nodeHost"
+				| "role"
+				| "council"
+				| "position"
+				| "allowedCandidates"
+				| "intent"
+				| "resolvedVerification"
+			> &
 			Required<
 				Pick<
 					DispatchPlanTaskView,
@@ -136,7 +164,7 @@ export interface ResolvedDispatchPlanArtifact {
 export function withResolvedPlanTaskPin(
 	request: DispatchRequest,
 	task: ResolvedDispatchPlanArtifact["tasks"][number] | undefined,
-	options: { pinTask?: boolean } = {},
+	options: { pinTask?: boolean; pinBriefing?: boolean } = {},
 ): DispatchRequest {
 	if (task === undefined) return request;
 	const {
@@ -170,7 +198,24 @@ export function withResolvedPlanTaskPin(
 			? {}
 			: { allowedCandidates: task.allowedCandidates.map((candidate) => ({ ...candidate })) }),
 		task: options.pinTask === false ? request.task : task.task,
-		...(task.briefing !== undefined ? { briefing: task.briefing } : {}),
+		...(options.pinBriefing === false
+			? request.briefing !== undefined
+				? { briefing: request.briefing }
+				: {}
+			: task.briefing !== undefined
+				? { briefing: task.briefing }
+				: {}),
+		...(task.worktree === true
+			? {
+					worktree: true as const,
+					apply: task.apply ?? "merge",
+					...(task.worktreeDestination === undefined ? {} : { taskWorktreeDestination: task.worktreeDestination }),
+				}
+			: {}),
+		...(task.intent !== undefined ? { intent: structuredClone(task.intent) } : {}),
+		...(task.resolvedVerification !== undefined
+			? { resolvedVerification: task.resolvedVerification.map((check) => ({ ...check, argv: [...check.argv] })) }
+			: {}),
 		target: task.target,
 		model: task.model,
 		node: task.node,
@@ -224,6 +269,12 @@ function taskViews(args: Record<string, unknown>): DispatchPlanTaskView[] {
 		};
 		const briefing = "briefing" in record ? str(record.briefing) : str(args.briefing);
 		if (briefing !== undefined) view.briefing = briefing;
+		const worktree = "worktree" in record ? record.worktree : args.worktree;
+		if (worktree === true) {
+			view.worktree = true;
+			const apply = "apply" in record ? record.apply : args.apply;
+			view.apply = apply === "preserve" ? "preserve" : "merge";
+		}
 		const model = str(record.model) ?? sharedModel;
 		if (model !== undefined) view.model = model;
 		const node = str(record.node) ?? sharedNode;
@@ -266,6 +317,7 @@ function canonicalCandidates(value: unknown): DispatchFailoverCandidate[] | null
 function topologyOf(args: Record<string, unknown>): DispatchPlanTopology {
 	if (isRecord(args.apply_winner)) return "compete";
 	if (args.mode === "compete") return "compete";
+	if (args.mode === "council") return "council";
 	if (args.review === true || isRecord(args.review)) return "review";
 	if (args.detach === true) return "detached";
 	if (args.mode === "sequential") return "sequential";
@@ -315,6 +367,15 @@ function renderPlanText(
 		lines.push(
 			`  ${index + 1}.${role} agent=${safeField(task.agent)}${target}${model}${node}${failover}${routingText} task=${JSON.stringify(safeField(task.task))}`,
 		);
+		if (task.council !== undefined) {
+			lines.push(
+				`    council label=${safeField(task.council.label)} color=${safeField(task.council.color ?? "none")} round=${task.council.round} rounds=${task.council.rounds} synthesis=${task.council.synthesis}`,
+			);
+		}
+		if (task.worktree === true)
+			lines.push(
+				`    worktree=true apply=${task.apply ?? "merge"} destination=${safeField(task.worktreeDestination ?? "unresolved")}`,
+			);
 		if (task.allowedCandidates !== undefined) {
 			for (const [candidateIndex, candidate] of task.allowedCandidates.entries()) {
 				lines.push(
@@ -352,6 +413,15 @@ function renderPlanText(
 				`    briefing_bytes=${Buffer.byteLength(task.briefing, "utf8")} briefing_sha256=${createHash("sha256").update(task.briefing, "utf8").digest("hex")} briefing_preview=${JSON.stringify(safeField(task.briefing))}`,
 			);
 		}
+		if (task.intent !== undefined) {
+			const serialized = JSON.stringify(task.intent);
+			lines.push(`    intent_sha256=${createHash("sha256").update(serialized, "utf8").digest("hex")}`);
+		}
+		for (const check of task.resolvedVerification ?? []) {
+			lines.push(
+				`    verification check=${safeField(check.check)} argv=${JSON.stringify(check.argv)} cwd=${JSON.stringify(check.cwd)} timeout_ms=${check.timeoutMs}`,
+			);
+		}
 	}
 	return lines.join("\n");
 }
@@ -362,12 +432,16 @@ function isResolvedTask(value: unknown): value is ResolvedDispatchPlanArtifact["
 		"agent",
 		"task",
 		"briefing",
+		"worktree",
+		"apply",
+		"worktreeDestination",
 		"model",
 		"node",
 		"nodeKind",
 		"nodeHost",
 		"target",
 		"role",
+		"council",
 		"position",
 		"routingIntent",
 		"failover",
@@ -381,6 +455,8 @@ function isResolvedTask(value: unknown): value is ResolvedDispatchPlanArtifact["
 		"authorityGrant",
 		"agentDecision",
 		"wave",
+		"intent",
+		"resolvedVerification",
 	]);
 	if (Object.keys(value).some((key) => !allowedKeys.has(key))) return false;
 	for (const key of [
@@ -409,17 +485,37 @@ function isResolvedTask(value: unknown): value is ResolvedDispatchPlanArtifact["
 		value.role !== "builder" &&
 		value.role !== "reviewer" &&
 		value.role !== "candidate" &&
-		value.role !== "judge"
+		value.role !== "judge" &&
+		value.role !== "member" &&
+		value.role !== "synthesis"
 	) {
 		return false;
 	}
 	if (value.position !== undefined && (!Number.isInteger(value.position) || Number(value.position) < 1)) return false;
+	if (value.council !== undefined) {
+		if (
+			!isRecord(value.council) ||
+			typeof value.council.label !== "string" ||
+			value.council.label.length === 0 ||
+			(value.council.color !== undefined && typeof value.council.color !== "string") ||
+			!Number.isInteger(value.council.round) ||
+			Number(value.council.round) < 1 ||
+			!Number.isInteger(value.council.rounds) ||
+			Number(value.council.rounds) < 1 ||
+			(value.council.synthesis !== "none" && value.council.synthesis !== "judge" && value.council.synthesis !== "vote")
+		)
+			return false;
+	}
 	if (value.nodeKind !== "local" && value.nodeKind !== "ssh") return false;
 	if (value.nodeKind === "ssh" && (typeof value.nodeHost !== "string" || value.nodeHost.trim().length === 0))
 		return false;
 	if (value.nodeKind === "local" && value.nodeHost !== undefined) return false;
 	if (value.briefing !== undefined && (typeof value.briefing !== "string" || value.briefing.trim().length === 0))
 		return false;
+	if (value.worktree !== undefined && value.worktree !== true) return false;
+	if (value.apply !== undefined && value.apply !== "merge" && value.apply !== "preserve") return false;
+	if (value.apply !== undefined && value.worktree !== true) return false;
+	if (value.worktreeDestination !== undefined && typeof value.worktreeDestination !== "string") return false;
 	if (failoverModeOf(value.failover) === undefined) return false;
 	if (!isRoutingIntent(value.routingIntent)) return false;
 	if (value.routeApproval !== null && !isApprovedAssignmentRoute(value.routeApproval)) return false;
@@ -441,6 +537,21 @@ function isResolvedTask(value: unknown): value is ResolvedDispatchPlanArtifact["
 		return false;
 	if (value.authorityGrant !== null && !isAuthorityGrant(value.authorityGrant)) return false;
 	if (value.agentDecision !== null && !isAgentDecision(value.agentDecision)) return false;
+	if (value.intent !== undefined && !isDispatchIntent(value.intent)) return false;
+	if (
+		value.resolvedVerification !== undefined &&
+		(!Array.isArray(value.resolvedVerification) ||
+			!value.resolvedVerification.every(
+				(check) =>
+					isRecord(check) &&
+					typeof check.check === "string" &&
+					Array.isArray(check.argv) &&
+					check.argv.every((arg) => typeof arg === "string") &&
+					typeof check.cwd === "string" &&
+					typeof check.timeoutMs === "number",
+			))
+	)
+		return false;
 	if (value.failover === "approved") {
 		if (canonicalCandidates(value.allowedCandidates) === null) return false;
 	} else if (value.allowedCandidates !== undefined) {
@@ -455,11 +566,16 @@ const RESULT_CONTRACT_KINDS = new Set<ResultContract["kind"]>([
 	"architect-plan",
 	"scout-report",
 	"verifier-report",
+	"council-report",
 	"debugger-report",
 	"research-report",
 	"mutation-report",
 	"provenance-report",
+	"oracle-report",
 	"external-delegation",
+	"artifact-report",
+	"context-handbook",
+	"delegation-plan",
 ]);
 
 function isAuthorityGrant(value: unknown): value is Exclude<DispatchPlanAuthorityGrant, null> {
@@ -572,6 +688,7 @@ export function resolvedDispatchPlanFromArgs(args: Record<string, unknown>): Res
 		value.topology !== "pipeline" &&
 		value.topology !== "review" &&
 		value.topology !== "compete" &&
+		value.topology !== "council" &&
 		value.topology !== "detached" &&
 		value.topology !== "fleet"
 	) {
@@ -632,6 +749,13 @@ export function resolvedDispatchPlanFromArgs(args: Record<string, unknown>): Res
 			agent: task.agent.trim(),
 			task: task.task.trim(),
 			...(task.briefing !== undefined ? { briefing: task.briefing.trim() } : {}),
+			...(task.worktree === true
+				? {
+						worktree: true as const,
+						apply: task.apply ?? "merge",
+						...(task.worktreeDestination === undefined ? {} : { worktreeDestination: task.worktreeDestination }),
+					}
+				: {}),
 			model: task.model.trim(),
 			node: task.node.trim(),
 			nodeKind: task.nodeKind,
@@ -652,7 +776,12 @@ export function resolvedDispatchPlanFromArgs(args: Record<string, unknown>): Res
 				: {}),
 			...(task.nodeHost !== undefined ? { nodeHost: task.nodeHost.trim() } : {}),
 			...(task.role !== undefined ? { role: task.role } : {}),
+			...(task.council !== undefined ? { council: { ...task.council } } : {}),
 			...(task.position !== undefined ? { position: task.position } : {}),
+			...(task.intent !== undefined ? { intent: structuredClone(task.intent) } : {}),
+			...(task.resolvedVerification !== undefined
+				? { resolvedVerification: task.resolvedVerification.map((check) => ({ ...check, argv: [...check.argv] })) }
+				: {}),
 		})),
 		costCeilingUsd: value.costCeilingUsd,
 		deadlineMs: value.deadlineMs as number | null,
@@ -716,6 +845,7 @@ export function describeDispatchPlan(rawArgs: Record<string, unknown> | undefine
 		(tasks.length > 1 ||
 			source !== null ||
 			topology === "compete" ||
+			topology === "council" ||
 			remote ||
 			tasks.some((task) => task.failover === "approved") ||
 			confirmation !== undefined ||