@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/interactive/dispatch-board.ts

@@ -24,6 +24,7 @@ import {
 	type RunStatus,
 	runKindSupportsLiveSteering,
 } from "../domains/dispatch/types.js";
+import { describeWriteBoundaryAttributionDowngrade } from "../domains/dispatch/write-boundary.js";
 import {
 	summarizeTrustStatus,
 	type TrustSummaryProjection,
@@ -36,17 +37,12 @@ import {
 	type ObservabilityNotice,
 	type ObservabilitySnapshot,
 } from "../domains/observability/index.js";
-import type { CostProvenance } from "../domains/providers/index.js";
+import { type CostProvenance, foregroundStreamUsage } from "../domains/providers/index.js";
 import { sanitizeCallTargetText } from "../domains/safety/call-target.js";
 import { type Component, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../engine/tui.js";
 import { formatWorkerContextMeter } from "./context-meter.js";
-import {
-	COUNCIL_SYNTHESIS_LABEL,
-	type CouncilGroupView,
-	type CouncilMemberView,
-	councilGroupBody,
-	councilIslandLines,
-} from "./council-grid.js";
+import { COUNCIL_SYNTHESIS_LABEL } from "./council.js";
+import { type CouncilGroupView, type CouncilMemberView, councilGroupBody, councilIslandLines } from "./council-grid.js";
 import { formatFooterTokens } from "./footer-panel.js";
 import {
 	type ClioTheme,
@@ -88,6 +84,12 @@ export interface DispatchSteerAcknowledgement {
 	chars: number;
 }
 
+export interface DispatchWriteRecordDowngrade {
+	reason: "opaque_tool_succeeded";
+	tool: string;
+	toolCallId: string;
+}
+
 export interface DispatchBoardRow {
 	runId: string;
 	agentId: string;
@@ -97,6 +99,8 @@ export interface DispatchBoardRow {
 	runtimeId: string;
 	targetId: string;
 	wireModelId: string;
+	/** Canonical inference scheduler and its independent request-slot bound. */
+	endpoint?: { key: string; label: string; limit: number };
 	/** Sanitized, one-line summary of the task assigned to this run. */
 	taskSummary?: string;
 	/** Immutable budget admission provenance for this run. */
@@ -156,6 +160,8 @@ export interface DispatchBoardRow {
 	retry?: DispatchRetryPresentation;
 	/** Most recent worker delivery acknowledgement for an operator steer. */
 	steerAcknowledgement?: DispatchSteerAcknowledgement;
+	/** First successful opaque call that opened this run's write record. */
+	writeRecordDowngrade?: DispatchWriteRecordDowngrade;
 	/**
 	 * Where this run sits in a fleet plan: the wave the step was scheduled in
 	 * and the step id it executes. Present only for runs a fleet plan
@@ -598,13 +604,37 @@ function progressAnswerLines(
 	return body.map((row, index) => `${index === 0 ? cardKvKey(theme, "answer") : " ".repeat(gutter)}${row}`);
 }
 
+/** Keep the canonical tier and every summary clause visible by wrapping the value under its card key. */
+function trustCardLines(theme: ClioTheme, row: DispatchBoardRow, contentWidth: number): string[] {
+	const gutter = CARD_KV_KEY_WIDTH + 1;
+	const valueWidth = Math.max(1, contentWidth - gutter);
+	const trust =
+		row.trust === undefined
+			? theme.fg("dim", isTerminalStatus(row.status) ? "receipt not read back" : "not sealed yet")
+			: theme.fg(
+					trustVerdictToken(row.trust.verdict),
+					`${trustVerdictGlyph(row.trust.verdict)} ${row.trust.verdict}; ${row.trust.text}`,
+				);
+	const host =
+		row.hostVerification === undefined ? "" : ` · ${theme.fg("muted", `host checks ${row.hostVerification}`)}`;
+	return wrapTextWithAnsi(`${trust}${host}`, valueWidth).map(
+		(line, index) => `${index === 0 ? cardKvKey(theme, "trust") : " ".repeat(gutter)}${line}`,
+	);
+}
+
 export function renderDispatchCard(
 	row: DispatchBoardRow,
 	width: number,
 	evidence?: RunEvidencePresentation,
-	options: { selected?: boolean; expanded?: boolean } = {},
+	options: {
+		selected?: boolean;
+		expanded?: boolean;
+		endpointActive?: number;
+		endpointQueued?: number;
+		theme?: ClioTheme;
+	} = {},
 ): string[] {
-	const theme = clioTheme();
+	const theme = options.theme ?? clioTheme();
 	const contentWidth = Math.max(0, width - 4);
 	const agentLabel = agentDisplayLabel(row);
 	const elapsed = formatCompactMs(row.elapsedMs);
@@ -653,6 +683,14 @@ export function renderDispatchCard(
 	const statusUnits = [
 		statusStr,
 		theme.fg("muted", `node ${row.node ?? "local"}`),
+		...(row.endpoint !== undefined
+			? [
+					theme.fg(
+						"info",
+						`slots ${options.endpointActive ?? 0}/${row.endpoint.limit}${(options.endpointQueued ?? 0) > 0 ? ` +${options.endpointQueued} queued` : ""} ${row.endpoint.label}`,
+					),
+				]
+			: []),
 		...(row.gate !== undefined ? [theme.fg("info", `gate ${row.gate.role} c${row.gate.cycle}`)] : []),
 		...(row.rerouteCount !== undefined && row.rerouteCount > 0
 			? [theme.fg("warning", `rerouted x${row.rerouteCount}`)]
@@ -663,15 +701,6 @@ export function renderDispatchCard(
 		`${theme.fg("dim", "ttft")} ${theme.fg("muted", ttft)}`,
 		`${theme.fg("dim", "cost")} ${theme.fg("muted", cost)}`,
 	];
-	// The trust line is the canonical projection, styled by its verdict tier;
-	// a host check is folded into that projection as validation grounding, so
-	// it is named as a secondary fact and never as independent verification.
-	const trustUnits = [
-		row.trust === undefined
-			? theme.fg("dim", isTerminalStatus(row.status) ? "trust: receipt not read back" : "trust: not sealed yet")
-			: theme.fg(trustVerdictToken(row.trust.verdict), `${trustVerdictGlyph(row.trust.verdict)} ${row.trust.text}`),
-		...(row.hostVerification !== undefined ? [theme.fg("muted", `host checks ${row.hostVerification}`)] : []),
-	];
 	const contextUnit = formatWorkerContextMeter(row.lastContextTokens ?? 0, row.contextWindow, theme);
 	// The phase column: a fleet step says which wave it belongs to and which
 	// step it is; every other run leaves the cell empty rather than inventing a
@@ -690,7 +719,7 @@ export function renderDispatchCard(
 			? [truncateToWidth(`${cardKvKey(theme, "task")}${theme.fg("muted", row.taskSummary)}`, contentWidth, "…", false)]
 			: []),
 		cardUnitsLine(theme, "status", statusUnits, contentWidth),
-		cardUnitsLine(theme, "trust", trustUnits, contentWidth),
+		...trustCardLines(theme, row, contentWidth),
 		...(row.budget !== undefined
 			? [
 					truncateToWidth(
@@ -751,6 +780,16 @@ export function renderDispatchCard(
 			),
 		);
 	}
+	if (row.writeRecordDowngrade) {
+		const warning = describeWriteBoundaryAttributionDowngrade({
+			...row.writeRecordDowngrade,
+			runId: row.runId,
+			stepId: row.phase?.stepId ?? null,
+		});
+		bodyLines.push(
+			...wrapTextWithAnsi(`${cardKvKey(theme, "record")}${theme.fg("warning", `open: ${warning}`)}`, contentWidth),
+		);
+	}
 	// The proof row is present only when the observability projection knows an
 	// evidence state for this run; an unknown/none state adds no line, so cards
 	// without evidence keep their existing three-line body.
@@ -969,6 +1008,15 @@ export function formatDispatchBoardLines(
 		});
 	}
 
+	const endpointActive: Record<string, number> = { ...foregroundStreamUsage() };
+	const endpointQueued: Record<string, number> = {};
+	for (const row of rows) {
+		if (row.endpoint === undefined) continue;
+		if (row.status === "enqueued") endpointQueued[row.endpoint.key] = (endpointQueued[row.endpoint.key] ?? 0) + 1;
+		else if (row.status === "running" || row.status === "stale" || row.status === "cancelling")
+			endpointActive[row.endpoint.key] = (endpointActive[row.endpoint.key] ?? 0) + 1;
+	}
+
 	// A council is one question asked of several members, so its rows render as
 	// one card holding the whole group rather than as unrelated neighbours.
 	const cards = dispatchBoardItems(rows, selectedRunId).map((item) =>
@@ -977,6 +1025,12 @@ export function formatDispatchBoardLines(
 			: renderDispatchCard(item.row, width, deriveRunEvidenceState(observability, item.row.runId), {
 					selected: item.row.runId === selectedRunId,
 					expanded: detailExpanded && item.row.runId === selectedRunId,
+					...(item.row.endpoint !== undefined
+						? {
+								endpointActive: endpointActive[item.row.endpoint.key] ?? 0,
+								endpointQueued: endpointQueued[item.row.endpoint.key] ?? 0,
+							}
+						: {}),
 				}),
 	);
 	const body: string[] = [];
@@ -1155,6 +1209,15 @@ function parseGateBadge(value: unknown): { role: string; cycle: number } | undef
 	return { role: record.role, cycle };
 }
 
+function parseEndpointCapacity(value: unknown): DispatchBoardRow["endpoint"] | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	const record = value as { key?: unknown; label?: unknown; limit?: unknown };
+	const key = parseNonEmptyString(record.key);
+	const label = parseNonEmptyString(record.label);
+	const limit = parsePositiveInt(record.limit);
+	return key === undefined || label === undefined || limit === undefined ? undefined : { key, label, limit };
+}
+
 function parseCouncilBadge(value: unknown): DispatchBoardRow["council"] | undefined {
 	if (typeof value !== "object" || value === null) return undefined;
 	const record = value as { group?: unknown; label?: unknown; color?: unknown; round?: unknown };
@@ -1351,6 +1414,7 @@ function toRow(entry: DispatchBoardEntry, now: number): DispatchBoardRow {
 		runtimeId: entry.runtimeId,
 		targetId: entry.targetId,
 		wireModelId: entry.wireModelId,
+		...(entry.endpoint !== undefined ? { endpoint: { ...entry.endpoint } } : {}),
 		...(entry.taskSummary !== undefined ? { taskSummary: entry.taskSummary } : {}),
 		...(entry.budget !== undefined ? { budget: entry.budget } : {}),
 		status: retry ? "retrying" : entry.status,
@@ -1379,6 +1443,7 @@ function toRow(entry: DispatchBoardEntry, now: number): DispatchBoardRow {
 		recentTools: progress.recentActions.map((action) => action.tool),
 		...(retry ? { retry: { ...retry } } : {}),
 		...(entry.steerAcknowledgement ? { steerAcknowledgement: { ...entry.steerAcknowledgement } } : {}),
+		...(entry.writeRecordDowngrade ? { writeRecordDowngrade: { ...entry.writeRecordDowngrade } } : {}),
 	};
 }
 
@@ -1461,6 +1526,7 @@ export function createDispatchBoardStore(
 		const agentAudience = parseAgentAudience(raw.agentAudience, previous?.agentAudience);
 		const requestOrigin = parseRequestOrigin(raw.requestOrigin, previous?.requestOrigin);
 		const node = parseNonEmptyString(raw.node) ?? previous?.node;
+		const endpoint = parseEndpointCapacity(raw.endpoint) ?? previous?.endpoint;
 		const gate = parseGateBadge(raw.gate) ?? previous?.gate;
 		const council = parseCouncilBadge(raw.council) ?? previous?.council;
 		const rerouteCount = parsePositiveInt(raw.rerouteCount) ?? previous?.rerouteCount;
@@ -1477,6 +1543,7 @@ export function createDispatchBoardStore(
 			runtimeId: parseText(raw.runtimeId, previous?.runtimeId ?? "-"),
 			targetId: parseText(raw.targetId, previous?.targetId ?? "-"),
 			wireModelId: parseText(raw.wireModelId, previous?.wireModelId ?? "-"),
+			...(endpoint !== undefined ? { endpoint } : {}),
 			...(taskSummary !== undefined ? { taskSummary } : {}),
 			...(budget !== undefined ? { budget } : {}),
 			status,
@@ -1505,6 +1572,7 @@ export function createDispatchBoardStore(
 			progress: previous?.progress ?? createWorkerProgressFold(),
 			...(previous?.retry ? { retry: { ...previous.retry } } : {}),
 			...(previous?.steerAcknowledgement ? { steerAcknowledgement: { ...previous.steerAcknowledgement } } : {}),
+			...(previous?.writeRecordDowngrade ? { writeRecordDowngrade: { ...previous.writeRecordDowngrade } } : {}),
 		};
 		entries.set(runId, entry);
 		pruneEntries(entries, (evicted) => fleetPhases.delete(evicted));
@@ -1654,6 +1722,20 @@ export function createDispatchBoardStore(
 					entry.ttftMs = Math.round(performance.now() - entry.startedAtClockMs);
 				}
 			}
+			if (type === "clio_write_record_downgraded") {
+				const rawPayload = (workerEvent as { payload?: unknown }).payload;
+				const payload =
+					typeof rawPayload === "object" && rawPayload !== null ? (rawPayload as Record<string, unknown>) : null;
+				const tool = payload === null ? undefined : parseNonEmptyString(payload.tool);
+				const toolCallId = payload === null ? undefined : parseNonEmptyString(payload.toolCallId);
+				if (payload?.reason === "opaque_tool_succeeded" && tool !== undefined && toolCallId !== undefined) {
+					entry.writeRecordDowngrade = {
+						reason: "opaque_tool_succeeded",
+						tool: sanitizeCallTargetText(tool),
+						toolCallId: sanitizeCallTargetText(toolCallId),
+					};
+				}
+			}
 			// The one fold that reads worker prose and tool activity. Everything the
 			// board says about what a worker is saying or touching comes from here,
 			// so the board and the transcript block cannot tell two stories.

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

@@ -26,7 +26,11 @@ import {
 	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 {
+	bindExecutionPlanEndpoints,
+	type ExecutionPlan,
+	type ExecutionPlanStep,
+} from "../domains/dispatch/execution-plan.js";
 import {
 	type AgentRoleFactsResolver,
 	requestExecutionRole,
@@ -40,6 +44,7 @@ export interface FleetRunPreviewRoute {
 	targetId: string;
 	wireModelId: string;
 	nodeId: string;
+	endpoint?: { key: string; label: string; limit: number; foregroundHeld?: number };
 }
 
 export interface FleetRunPreviewStep {
@@ -207,6 +212,40 @@ export function compileFleetRunPreview(input: FleetRunPreviewInput): FleetRunPre
 		diagnostics.push(describeError(error));
 		return fail();
 	}
+	const routes = new Map<string, FleetRunPreviewRoute>();
+	if (input.resolveRoute !== undefined) {
+		for (const step of plan.steps) {
+			if (step.kind === "code") continue;
+			try {
+				const 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 } : {}),
+				});
+				if (route !== null) routes.set(step.id, route);
+			} catch (error) {
+				diagnostics.push(`step '${step.id}' route preflight failed: ${describeError(error)}`);
+			}
+		}
+		plan = bindExecutionPlanEndpoints(
+			plan,
+			Object.fromEntries(
+				[...routes].map(([stepId, route]) => [
+					stepId,
+					route.endpoint === undefined
+						? undefined
+						: {
+								key: route.endpoint.key,
+								limit: route.endpoint.limit,
+								...(route.endpoint.foregroundHeld !== undefined ? { foregroundHeld: route.endpoint.foregroundHeld } : {}),
+							},
+				]),
+			),
+		);
+	}
 
 	// 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
@@ -261,20 +300,7 @@ export function compileFleetRunPreview(input: FleetRunPreviewInput): FleetRunPre
 					},
 				];
 			}
-			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)}`);
-			}
+			const route = routes.get(step.id) ?? null;
 			return [
 				{
 					...base,

package/src/interactive/handoff-round.ts

@@ -34,6 +34,22 @@ export const HANDOFF_SYSTEM_PROMPT = [
 /** A handoff record is a list of short entries, so the budget is modest. */
 export const HANDOFF_MAX_TOKENS = 4096;
 
+/** The name the wire dialect gives the schema, where it takes one. */
+export const HANDOFF_SCHEMA_NAME = "handoff_record";
+
+/** Characters of the refused answer quoted back to the model in the repair round. */
+export const HANDOFF_REPAIR_QUOTE_CHARS = 600;
+
+/**
+ * What the first round returned and why the parser refused it. The repair round
+ * shows the model both, because "return one JSON object" repeated verbatim is
+ * the instruction it already failed (issue #223).
+ */
+export interface HandoffRepairInput {
+	complaint: string;
+	previous: string;
+}
+
 export interface HandoffRoundInput {
 	model: EngineModel;
 	/** Read-only. The round copies before appending its own message. */
@@ -42,15 +58,38 @@ export interface HandoffRoundInput {
 	apiKey?: string;
 	signal?: AbortSignal;
 	maxTokens?: number;
+	/** Resolved runtime id, which decides whether the schema can be bound on the wire. */
+	runtimeId?: string;
+	/** Set on the second and last round, after the parser refused the first. */
+	repair?: HandoffRepairInput;
+}
+
+function repairText(goal: string, repair: HandoffRepairInput): string {
+	const quoted = repair.previous.slice(0, HANDOFF_REPAIR_QUOTE_CHARS);
+	return [
+		`The next session's goal is: ${goal}`,
+		"",
+		"Your previous answer could not be read as a handoff record.",
+		`The parser said: ${repair.complaint}`,
+		"This is what you returned, verbatim:",
+		"---",
+		quoted.length > 0 ? quoted : "(nothing)",
+		"---",
+		"Answer again with one JSON object matching the schema and nothing else.",
+		"No prose before it, no prose after it, no code fence.",
+	].join("\n");
 }
 
 /** Run the round. Provider failures reject; the caller renders the reason. */
 export async function runHandoffRound(input: HandoffRoundInput): Promise<SideQuestionResult> {
-	const { goal, ...rest } = input;
+	const { goal, repair, ...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.`,
+		responseSchema: { name: HANDOFF_SCHEMA_NAME, schema: HANDOFF_RESPONSE_SCHEMA },
+		userText: repair
+			? repairText(goal, repair)
+			: `The next session's goal is: ${goal}\n\nExtract the handoff record for that goal now.`,
 	});
 }