@iowarp/clio-coder 0.3.6 → 0.3.8

package/src/interactive/fleet-run-preview.ts

@@ -0,0 +1,307 @@
+/**
+ * What `/fleet run <name>` will do, projected before anything dispatches.
+ *
+ * The projection is the compiled plan and nothing else. It calls the same
+ * loader, the same graph and command validation, the same plan compiler, and
+ * the same write-boundary preflight the headless `fleet` subcommands call, so
+ * the overlay cannot show an operator a run that differs from the one the
+ * scheduler would execute. No fleet logic is reimplemented here; this module
+ * only arranges the compiled facts into rows a terminal can render.
+ *
+ * A preflight failure is data, not an exception. Every diagnostic is collected
+ * and returned so the overlay can render the whole list with no accept action,
+ * rather than surfacing the first failure and hiding the rest.
+ */
+
+import {
+	FLEET_COMMANDS_REMEDY,
+	type FleetCommandRegistry,
+	FleetCommandRegistryMissingError,
+	type FleetContract,
+	fleetStepBoundaries,
+	loadFleetCommands,
+	loadFleetContract,
+	renderFleetPrompt,
+	validateFleetCommands,
+	validateFleetGraph,
+} from "../domains/agents/index.js";
+import type { AgentSpec } from "../domains/agents/spec.js";
+import type { ExecutionPlan, ExecutionPlanStep } from "../domains/dispatch/execution-plan.js";
+import {
+	type AgentRoleFactsResolver,
+	requestExecutionRole,
+	withAttemptRole,
+} from "../domains/dispatch/execution-role.js";
+import { compileFleetExecutionPlan } from "../domains/dispatch/fleet-plan.js";
+import { preflightWriteBoundaries } from "../domains/dispatch/write-boundary-enforcer.js";
+
+/** Where a step would run, as the dispatch domain resolves it today. */
+export interface FleetRunPreviewRoute {
+	targetId: string;
+	wireModelId: string;
+	nodeId: string;
+}
+
+export interface FleetRunPreviewStep {
+	stepId: string;
+	kind: ExecutionPlanStep["kind"];
+	scope: "readonly" | "workspace";
+	/** Agent steps only. */
+	agentId?: string;
+	/** Resolved route for an agent step; absent when the domain could not resolve one. */
+	route?: FleetRunPreviewRoute;
+	/** Code steps only: the registered command id and the argv it will run. */
+	commandId?: string;
+	argv?: ReadonlyArray<string>;
+	/** Declared write boundary. Empty is the claim "changes nothing"; undefined is no claim. */
+	writes: ReadonlyArray<string> | undefined;
+	/** Loop membership for a node a bounded loop unrolled to. */
+	loop?: { loopId: string; role: "check" | "repair"; attempt: number };
+	target?: string;
+	profile?: string;
+	gate?: { path: string; commandId: string } | { gateId: string; path: string };
+	plan?: { roster: ReadonlyArray<string>; maxTasks: number; proposals: boolean };
+}
+
+export interface FleetRunPreviewWave {
+	index: number;
+	steps: ReadonlyArray<FleetRunPreviewStep>;
+}
+
+export interface FleetRunPreviewBudget {
+	/** Session ceiling this run is admitted under. */
+	ceilingUsd: number;
+	currentUsd: number;
+	/** The contract's own declared ceiling, or null when it declares none. */
+	contractUsd: number | null;
+}
+
+export interface FleetRunPreview {
+	name: string;
+	/** Variables rendered into the plan and sealed into its durable run record. */
+	vars: Readonly<Record<string, string>>;
+	planHash: string;
+	waves: ReadonlyArray<FleetRunPreviewWave>;
+	budget: FleetRunPreviewBudget;
+	/** The compiled plan itself, so an accepted preview dispatches what was shown. */
+	plan: ExecutionPlan;
+	contract: FleetContract;
+	commands: FleetCommandRegistry | null;
+	/** Rendered prompt body every agent node carries as its task. */
+	task: string;
+}
+
+export type FleetRunPreviewResult =
+	| { ok: true; preview: FleetRunPreview }
+	| { ok: false; name: string; diagnostics: ReadonlyArray<string> };
+
+/** Everything the projection needs from the running process. */
+export interface FleetRunPreviewInput {
+	workspaceRoot: string;
+	name: string;
+	vars: Readonly<Record<string, string>>;
+	/** Recipe lookup; a step naming an unknown agent is a diagnostic. */
+	getAgentSpec: (agentId: string) => AgentSpec | null;
+	/** Role facts for the execution role each node runs under. */
+	roleFacts: AgentRoleFactsResolver;
+	/** Session budget state; absent leaves the ceiling unknown and checks nothing. */
+	budget?: { ceilingUsd: number; currentUsd: number; verdict: "under" | "at" | "over" };
+	/** Effective route for an agent step. Absent or null renders the step without one. */
+	resolveRoute?: (step: {
+		stepId: string;
+		agentId: string;
+		/** The compiled step task; a route preview validates the request it would send, and an empty task is refused. */
+		task: string;
+		scope: "readonly" | "workspace";
+		target?: string;
+		profile?: string;
+	}) => FleetRunPreviewRoute | null;
+	/** Contract and registry loaders, overridable so tests project a fixture. */
+	load?: (workspaceRoot: string, name: string) => { contract: FleetContract; commands: FleetCommandRegistry | null };
+}
+
+function defaultLoad(
+	workspaceRoot: string,
+	name: string,
+): { contract: FleetContract; commands: FleetCommandRegistry | null } {
+	const contract = loadFleetContract(workspaceRoot, name);
+	// loadFleetContract already refused any unregistered command id; this read
+	// is the binding the runner executes.
+	return { contract, commands: loadFleetCommands(workspaceRoot) };
+}
+
+function describeError(error: unknown): string {
+	if (error instanceof FleetCommandRegistryMissingError) return `${error.message}\n${FLEET_COMMANDS_REMEDY}`;
+	return error instanceof Error ? error.message : String(error);
+}
+
+/** The contract position a compiled node came from; a loop half keeps its position id. */
+function positionId(step: ExecutionPlanStep): string {
+	return step.loop === undefined ? step.id : `${step.loop.loopId}.${step.loop.role}`;
+}
+
+/**
+ * Compile the plan and project it into waves. Returns diagnostics instead of
+ * throwing: an operator meets a broken contract in the overlay, with every
+ * reason it cannot run, and no accept key.
+ */
+export function compileFleetRunPreview(input: FleetRunPreviewInput): FleetRunPreviewResult {
+	const diagnostics: string[] = [];
+	const fail = (): FleetRunPreviewResult => ({ ok: false, name: input.name, diagnostics });
+
+	let contract: FleetContract;
+	let commands: FleetCommandRegistry | null;
+	try {
+		({ contract, commands } = (input.load ?? defaultLoad)(input.workspaceRoot, input.name));
+	} catch (error) {
+		diagnostics.push(describeError(error));
+		return fail();
+	}
+
+	let task: string;
+	try {
+		validateFleetGraph(contract);
+		validateFleetCommands(contract, commands);
+		task = renderFleetPrompt(contract.body, input.vars);
+	} catch (error) {
+		diagnostics.push(describeError(error));
+		return fail();
+	}
+
+	let plan: ExecutionPlan;
+	try {
+		plan = compileFleetExecutionPlan({
+			contract,
+			task,
+			resolveAgent(context) {
+				const spec = input.getAgentSpec(context.agentId);
+				if (spec === null) {
+					throw new Error(`unknown agent '${context.agentId}' (step '${context.stepId}' must name a recipe from /agents)`);
+				}
+				if (spec.capabilityClass === "orchestration" || spec.capabilityClass === "internal") {
+					throw new Error(`fleet step '${context.stepId}' has no automatable agent authority`);
+				}
+				const requestRole = requestExecutionRole({
+					agentId: context.agentId,
+					resolveFacts: input.roleFacts,
+					...(context.gateRole !== undefined ? { gateRole: context.gateRole } : {}),
+				});
+				return {
+					requestedAuthority: spec.capabilityClass,
+					approvedAuthority: spec.capabilityClass,
+					// A gate decider answers the coordinator's question, so its
+					// postcondition is the gate result contract, not its recipe's.
+					expectedResultContract:
+						context.planRole === true
+							? "delegation-plan"
+							: context.gateAuthorRole === true
+								? "artifact-report"
+								: context.gateRole === "reviewer"
+									? "verifier-report"
+									: spec.resultContract.kind,
+					executionRole: withAttemptRole(requestRole, context.attempt),
+				};
+			},
+		});
+	} catch (error) {
+		diagnostics.push(describeError(error));
+		return fail();
+	}
+
+	// A declared boundary is verified against the checkout, so the checkout has
+	// to be one this can read. Refused here, before any dispatch, rather than
+	// discovered as an unenforceable claim halfway through the run.
+	try {
+		preflightWriteBoundaries(plan, input.workspaceRoot);
+	} catch (error) {
+		diagnostics.push(describeError(error));
+	}
+
+	const budget: FleetRunPreviewBudget = {
+		ceilingUsd: input.budget?.ceilingUsd ?? 0,
+		currentUsd: input.budget?.currentUsd ?? 0,
+		contractUsd: contract.budgetUsd,
+	};
+	if (input.budget) {
+		if (input.budget.verdict === "over" || input.budget.verdict === "at") {
+			diagnostics.push(`budget ceiling crossed: $${budget.currentUsd.toFixed(4)} / $${budget.ceilingUsd.toFixed(4)}`);
+		} else if (contract.budgetUsd !== null) {
+			const remaining = budget.ceilingUsd - budget.currentUsd;
+			if (contract.budgetUsd > remaining) {
+				diagnostics.push(
+					`fleet budget $${contract.budgetUsd.toFixed(2)} exceeds remaining session budget $${remaining.toFixed(2)}`,
+				);
+			}
+		}
+	}
+
+	const boundaries = new Map(fleetStepBoundaries(contract).map((entry) => [entry.id, entry.writes]));
+	const byId = new Map(plan.steps.map((step) => [step.id, step]));
+	const waves: FleetRunPreviewWave[] = plan.waves.map((wave, index) => ({
+		index,
+		steps: wave.flatMap((stepId): FleetRunPreviewStep[] => {
+			const step = byId.get(stepId);
+			if (step === undefined) return [];
+			const declared = boundaries.has(positionId(step)) ? boundaries.get(positionId(step)) : step.writes;
+			const base = {
+				stepId: step.id,
+				scope: step.scope,
+				writes: declared,
+				...(step.loop !== undefined ? { loop: { ...step.loop } } : {}),
+				...(step.gate !== undefined ? { gate: { ...step.gate } } : {}),
+			};
+			if (step.kind === "code") {
+				const command = commands?.commands.get(step.commandId);
+				return [
+					{
+						...base,
+						kind: "code" as const,
+						commandId: step.commandId,
+						...(command !== undefined ? { argv: [...command.argv] } : {}),
+					},
+				];
+			}
+			let route: FleetRunPreviewRoute | null = null;
+			try {
+				route =
+					input.resolveRoute?.({
+						stepId: step.id,
+						agentId: step.agentId,
+						task: step.task,
+						scope: step.scope,
+						...(step.target !== undefined ? { target: step.target } : {}),
+						...(step.profile !== undefined ? { profile: step.profile } : {}),
+					}) ?? null;
+			} catch (error) {
+				diagnostics.push(`step '${step.id}' route preflight failed: ${describeError(error)}`);
+			}
+			return [
+				{
+					...base,
+					kind: "agent" as const,
+					agentId: step.agentId,
+					...(step.target !== undefined ? { target: step.target } : {}),
+					...(step.profile !== undefined ? { profile: step.profile } : {}),
+					...(step.plan !== undefined ? { plan: { ...step.plan, roster: [...step.plan.roster] } } : {}),
+					...(route !== null ? { route } : {}),
+				},
+			];
+		}),
+	}));
+	if (diagnostics.length > 0) return fail();
+
+	return {
+		ok: true,
+		preview: {
+			name: contract.name,
+			vars: { ...input.vars },
+			planHash: plan.hash,
+			waves,
+			budget,
+			plan,
+			contract,
+			commands,
+			task,
+		},
+	};
+}

package/src/interactive/footer/notifications.ts

@@ -79,6 +79,225 @@ export function classifyNoticeLevel(text: string): NotificationLevel {
 	return "info";
 }
 
+/**
+ * Desktop notification: a content-free nudge to a terminal that is not on
+ * screen right now.
+ *
+ * The payload is deliberately not a message. The title is fixed and the body
+ * comes from a closed vocabulary, so a notification that lands on a shared
+ * screen, a phone mirroring notifications, or a corporate notification log
+ * cannot leak a prompt, a path, a model answer, or a worker's task text. What
+ * it carries is that something needs the operator, and nothing more.
+ */
+export const DESKTOP_NOTIFY_TITLE = "clio-coder";
+
+/** Maximum body length in bytes after sanitization. */
+export const DESKTOP_NOTIFY_BODY_MAX_BYTES = 128;
+
+/**
+ * The three events that earn a notification. `batch` carries the batch's short
+ * id because an operator running several fan-outs needs to know which one came
+ * back; the id is a generated identifier, never operator or model text.
+ */
+export type DesktopNotifyEvent =
+	| { kind: "turn-finished" }
+	| { kind: "batch-settled"; shortId: string }
+	| { kind: "approval-needed" };
+
+/**
+ * Terminals whose OSC 777 support is absent or unreliable and which understand
+ * OSC 9 instead. Matched case-insensitively against TERM_PROGRAM and, for
+ * Windows Terminal, against the presence of WT_SESSION.
+ */
+const OSC9_TERM_PROGRAMS: ReadonlyArray<string> = [
+	"iterm.app",
+	"iterm2",
+	"windowsterminal",
+	"windows terminal",
+	"conemu",
+];
+
+const BEL = "\u0007";
+
+/**
+ * Strip C0/C1 controls and the `;` an OSC payload uses as its own separator.
+ *
+ * The classification is by code point rather than by a character-class regex:
+ * a literal control range inside a pattern is exactly the thing the payload
+ * must not carry, and spelling one out is how it gets copied in by accident.
+ */
+function sanitizeNotifyText(text: string): string {
+	let out = "";
+	for (const char of text) {
+		const code = char.codePointAt(0) ?? 0;
+		const isControl = code <= 0x1f || (code >= 0x7f && code <= 0x9f);
+		out += isControl || char === ";" ? " " : char;
+	}
+	return out.replace(/\s+/gu, " ").trim();
+}
+
+/** Clamp to the byte bound without splitting a multi-byte character. */
+function boundNotifyBytes(text: string, maxBytes: number): string {
+	const encoder = new TextEncoder();
+	if (encoder.encode(text).length <= maxBytes) return text;
+	let out = "";
+	let used = 0;
+	for (const char of text) {
+		const size = encoder.encode(char).length;
+		if (used + size > maxBytes) break;
+		out += char;
+		used += size;
+	}
+	return out;
+}
+
+/** The closed-vocabulary body for one event. */
+export function desktopNotifyBody(event: DesktopNotifyEvent): string {
+	if (event.kind === "turn-finished") return "turn finished";
+	if (event.kind === "approval-needed") return "approval needed";
+	const shortId = boundNotifyBytes(sanitizeNotifyText(event.shortId), 32);
+	return shortId.length > 0 ? `batch ${shortId} settled` : "batch settled";
+}
+
+/** True when the environment names a terminal that answers OSC 9 rather than OSC 777. */
+export function prefersOsc9(env: Readonly<Record<string, string | undefined>>): boolean {
+	if (typeof env.WT_SESSION === "string" && env.WT_SESSION.length > 0) return true;
+	const program = (env.TERM_PROGRAM ?? "").trim().toLowerCase();
+	if (program.length === 0) return false;
+	return OSC9_TERM_PROGRAMS.some((candidate) => program === candidate || program.includes(candidate));
+}
+
+/**
+ * Build the one escape sequence for an event. OSC 777 is the default and
+ * carries both the fixed title and the body; OSC 9 carries only the body and is
+ * chosen for the terminals that implement it instead. Exactly one sequence is
+ * returned, so a single event can never produce two notifications.
+ */
+export function buildDesktopNotifySequence(
+	event: DesktopNotifyEvent,
+	env: Readonly<Record<string, string | undefined>> = process.env,
+): string {
+	const body = boundNotifyBytes(sanitizeNotifyText(desktopNotifyBody(event)), DESKTOP_NOTIFY_BODY_MAX_BYTES);
+	if (prefersOsc9(env)) return `\u001b]9;${body}${BEL}`;
+	return `\u001b]777;notify;${DESKTOP_NOTIFY_TITLE};${body}${BEL}`;
+}
+
+export interface DesktopNotifierDeps {
+	/**
+	 * Protocol write on the terminal owner. It happens outside a render
+	 * transaction, so the trace records it with `frameId: null` and it never
+	 * lands inside a frame.
+	 */
+	write: (data: string) => void;
+	/** Live `terminal.notify`, re-read per event so a hot config reload takes effect. */
+	enabled: () => boolean;
+	/**
+	 * True only on the interactive TTY path. Headless, ACP, and non-TTY runs
+	 * pass false (or wire no notifier at all) and never emit a sequence.
+	 */
+	interactiveTty: () => boolean;
+	env?: Readonly<Record<string, string | undefined>>;
+}
+
+export interface DesktopNotifier {
+	notify(event: DesktopNotifyEvent): void;
+}
+
+/**
+ * Emit content-free desktop notifications for the three operator-waiting
+ * events. Every call re-checks the setting and the surface, so turning
+ * `terminal.notify` off mid-session silences the next event.
+ */
+export function createDesktopNotifier(deps: DesktopNotifierDeps): DesktopNotifier {
+	const env = deps.env ?? process.env;
+	return {
+		notify(event) {
+			if (!deps.interactiveTty()) return;
+			if (!deps.enabled()) return;
+			try {
+				deps.write(buildDesktopNotifySequence(event, env));
+			} catch {
+				// A terminal that refuses the write is not a reason to interrupt the
+				// turn that produced the event.
+			}
+		},
+	};
+}
+
+/** Minimal projection of a detached batch, matching `DetachedBatchNudgeView`. */
+export interface DesktopNotifyBatchView {
+	id: string;
+	total: number;
+	terminal: number;
+}
+
+export interface InteractiveDesktopNotificationsDeps extends DesktopNotifierDeps {
+	/**
+	 * Live detached-batch progress. Read on every dispatch terminal event so a
+	 * batch whose last run just finished is announced exactly once.
+	 */
+	getOpenBatches?: () => ReadonlyArray<DesktopNotifyBatchView>;
+}
+
+export interface InteractiveDesktopNotifications {
+	/** A model turn reached its end. */
+	turnEnded(): void;
+	/** A dispatch run reached a terminal state; announces any batch that settled with it. */
+	dispatchSettled(): void;
+	/** A worker permission or an ask_user request parked waiting for the operator. */
+	approvalParked(): void;
+}
+
+/** Batch ids stay short in the payload: enough to tell two fan-outs apart. */
+const BATCH_SHORT_ID_CHARS = 8;
+
+/**
+ * The three notification events, wired to the surfaces that produce them.
+ *
+ * Batch settlement has no event of its own on the bus, so it is derived: every
+ * dispatch terminal event recomputes open-batch progress and any batch that
+ * crossed from running to fully terminal since the last look is announced. The
+ * announced set is remembered, so a batch that stays collectible for another
+ * ten minutes does not re-notify on every later run.
+ */
+export function createInteractiveDesktopNotifications(
+	deps: InteractiveDesktopNotificationsDeps,
+): InteractiveDesktopNotifications {
+	const notifier = createDesktopNotifier(deps);
+	const announcedBatches = new Set<string>();
+	return {
+		turnEnded(): void {
+			notifier.notify({ kind: "turn-finished" });
+		},
+		dispatchSettled(): void {
+			const getOpenBatches = deps.getOpenBatches;
+			if (!getOpenBatches) return;
+			let views: ReadonlyArray<DesktopNotifyBatchView>;
+			try {
+				views = getOpenBatches();
+			} catch {
+				return;
+			}
+			const open = new Set<string>();
+			for (const view of views) {
+				open.add(view.id);
+				if (view.total <= 0 || view.terminal < view.total) continue;
+				if (announcedBatches.has(view.id)) continue;
+				announcedBatches.add(view.id);
+				notifier.notify({ kind: "batch-settled", shortId: view.id.slice(0, BATCH_SHORT_ID_CHARS) });
+			}
+			// A collected batch leaves the open list; forget it so its id can be
+			// announced again if the store ever reuses it.
+			for (const id of [...announcedBatches]) {
+				if (!open.has(id)) announcedBatches.delete(id);
+			}
+		},
+		approvalParked(): void {
+			notifier.notify({ kind: "approval-needed" });
+		},
+	};
+}
+
 function resolveExpiry(level: NotificationLevel, addedAt: number, ttlMs: number | undefined): number | null {
 	if (ttlMs !== undefined) return ttlMs <= 0 ? null : addedAt + ttlMs;
 	return level === "info" || level === "success" ? addedAt + DEFAULT_INFO_TTL_MS : null;

package/src/interactive/handoff-round.ts

@@ -0,0 +1,56 @@
+/**
+ * The `/handoff` extraction round: one model call beside the session, no tools.
+ *
+ * It rides the same out-of-turn seam `/btw` uses, for the same reason: the
+ * input is the compiled message history the next turn would see, and the round
+ * must not enter the turn state machine, the transcript, or the ledger. The
+ * only difference is the instruction and the output contract, which is JSON
+ * validated against `HANDOFF_RESPONSE_SCHEMA` on the way back.
+ */
+
+import { HANDOFF_RESPONSE_SCHEMA } from "../domains/session/handoff.js";
+import type { AgentMessage, EngineModel } from "../engine/types.js";
+import { runOutOfTurnRound, type SideQuestionResult } from "./side-question.js";
+
+/**
+ * The whole system prompt for the round. The session's own compiled prompt is
+ * not reused: it carries the working agreement for a turn that edits files and
+ * calls tools, and this round does neither.
+ */
+export const HANDOFF_SYSTEM_PROMPT = [
+	"You are extracting a handoff record from a coding session that is about to end.",
+	"The conversation above is read-only context.",
+	"Answer with one JSON object and nothing else: no prose, no code fence, no explanation.",
+	"decisions are choices this session settled, each with a summary and an optional rationale.",
+	"facts are durable statements about the work that the next session needs.",
+	"files name paths this session actually opened, edited, or searched, each with why it matters.",
+	"commands are shell invocations worth repeating, each with why.",
+	"openQuestions are what is still unresolved.",
+	"Never invent a file path. Every path must be one this conversation shows a tool call touching.",
+	"Leave a list empty rather than filling it with guesses.",
+	`The object must match this JSON schema exactly: ${JSON.stringify(HANDOFF_RESPONSE_SCHEMA)}`,
+].join(" ");
+
+/** A handoff record is a list of short entries, so the budget is modest. */
+export const HANDOFF_MAX_TOKENS = 4096;
+
+export interface HandoffRoundInput {
+	model: EngineModel;
+	/** Read-only. The round copies before appending its own message. */
+	messages: ReadonlyArray<AgentMessage>;
+	goal: string;
+	apiKey?: string;
+	signal?: AbortSignal;
+	maxTokens?: number;
+}
+
+/** Run the round. Provider failures reject; the caller renders the reason. */
+export async function runHandoffRound(input: HandoffRoundInput): Promise<SideQuestionResult> {
+	const { goal, ...rest } = input;
+	return runOutOfTurnRound({
+		...rest,
+		maxTokens: input.maxTokens ?? HANDOFF_MAX_TOKENS,
+		systemPrompt: HANDOFF_SYSTEM_PROMPT,
+		userText: `The next session's goal is: ${goal}\n\nExtract the handoff record for that goal now.`,
+	});
+}