@iowarp/clio-coder 0.3.4 → 0.3.7

package/src/interactive/theme/tokens.ts

@@ -119,3 +119,33 @@ export function createClioTheme(options: { truecolor?: boolean; color?: boolean
 		fgSequence: (token) => (color ? `\u001b[${fgCode(TOKENS[token], truecolor)}m` : ""),
 	};
 }
+
+/** True when `value` names one of the theme's own tokens, so it can be painted as one. */
+export function isClioToken(value: string): value is ClioToken {
+	return Object.hasOwn(TOKENS, value);
+}
+
+const HEX_COLOR = /^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$/u;
+
+/**
+ * Paint text in a configured `#rrggbb` color.
+ *
+ * A council roster member may carry one. A roster color is the operator's own
+ * choice rather than a token from the palette, which is why a literal color
+ * reaches the screen here and nowhere else. Returns the text unchanged when
+ * color is disabled or the value is not a six-digit hex color, so a caller can
+ * fall back to a token without inspecting the string twice. A terminal without
+ * truecolor gets the nearest color in the 6x6x6 xterm cube.
+ */
+export function paintHex(text: string, hex: string, options: { truecolor?: boolean; color?: boolean } = {}): string {
+	const match = HEX_COLOR.exec(hex);
+	if (match === null) return text;
+	if (!(options.color ?? !colorDisabled())) return text;
+	const truecolor = options.truecolor ?? detectTruecolor();
+	const red = Number.parseInt(match[1] ?? "0", 16);
+	const green = Number.parseInt(match[2] ?? "0", 16);
+	const blue = Number.parseInt(match[3] ?? "0", 16);
+	if (truecolor) return `\u001b[38;2;${red};${green};${blue}m${text}${SGR_RESET}`;
+	const cube = (channel: number): number => Math.round((channel / 255) * 5);
+	return `\u001b[38;5;${16 + 36 * cube(red) + 6 * cube(green) + cube(blue)}m${text}${SGR_RESET}`;
+}

package/src/interactive/turn-context.ts

@@ -23,7 +23,12 @@ import { selectVisibleEntries } from "../domains/context/working-set/visible.js"
 import type { ObservabilityContract } from "../domains/observability/contract.js";
 import type { CompiledSessionPrompt, SessionPromptInputs } from "../domains/prompts/compiler.js";
 import type { PromptsContract } from "../domains/prompts/contract.js";
-import type { ProvidersContract } from "../domains/providers/index.js";
+import {
+	type ContextWindowDetails,
+	type ContextWindowSource,
+	type ProvidersContract,
+	resolveRuntimeTarget,
+} from "../domains/providers/index.js";
 import type { LocalModelQuirks } from "../domains/providers/types/local-model-quirks.js";
 import {
 	AutoCompactionTrigger,
@@ -309,6 +314,75 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		return ceilChars(snapshot.pendingUserInput.length);
 	};
 
+	/**
+	 * The window the next turn will resolve to, read the way ensureRuntime
+	 * reads it but without building an agent. Before the first turn of a
+	 * process, /resume included, state.runtime is null, and the ledger and the
+	 * footer meter said `context window unknown · 0 tokens` until a turn ran
+	 * (issue #189). Null when no target is configured or it does not resolve,
+	 * and the overlay's "unknown" is then true.
+	 */
+	const resolveWindowWithoutRuntime = (): ContextWindowDetails | null => {
+		const settings = deps.getSettings();
+		const targetId = settings.orchestrator?.target?.trim();
+		const wireModelId = settings.orchestrator?.model?.trim();
+		if (!targetId || !wireModelId) return null;
+		const resolved = resolveRuntimeTarget(deps.providers, {
+			targetId,
+			wireModelId,
+			requestedThinkingLevel: settings.orchestrator?.thinkingLevel ?? "off",
+			use: "orchestrator",
+			requireTools: false,
+			requireOutputBudget: true,
+		});
+		return resolved.ok ? resolved.target.contextWindowDetails : null;
+	};
+
+	const CONTEXT_WINDOW_SOURCES: ReadonlySet<string> = new Set<ContextWindowSource>([
+		"catalog",
+		"probe",
+		"loaded",
+		"target-override",
+		"model-hint",
+		"descriptor-default",
+		"unknown",
+	]);
+
+	/** The snapshot stores its source as a plain string; only a known label is worth repeating. */
+	const snapshotWindowSource = (snapshot: ContextSnapshot): ContextWindowSource | null =>
+		CONTEXT_WINDOW_SOURCES.has(snapshot.contextWindowSource)
+			? (snapshot.contextWindowSource as ContextWindowSource)
+			: null;
+
+	/**
+	 * Window facts while no runtime exists: the live resolution first, then the
+	 * resumed snapshot's recorded window, which is what the previous process
+	 * measured the same messages against.
+	 */
+	const windowWithoutRuntime = (): {
+		contextWindow: number;
+		contextWindowSource: ContextWindowSource | null;
+		contextWindowSlots: ContextWindowDetails["contextWindowSlots"];
+	} => {
+		const details = resolveWindowWithoutRuntime();
+		if (details) {
+			return {
+				contextWindow: details.effectiveContextWindow,
+				contextWindowSource: details.contextWindowSource,
+				contextWindowSlots: details.contextWindowSlots,
+			};
+		}
+		const snapshot = currentContextSnapshot;
+		if (snapshot && snapshot.effectiveContextWindow > 0) {
+			return {
+				contextWindow: snapshot.effectiveContextWindow,
+				contextWindowSource: snapshotWindowSource(snapshot),
+				contextWindowSlots: null,
+			};
+		}
+		return { contextWindow: 0, contextWindowSource: null, contextWindowSlots: null };
+	};
+
 	const liveContextEstimate = (agentRuntime: AgentRuntime, pendingUserText?: string): LiveContextEstimate => {
 		const contextWindow = agentRuntime.runtimeResolution.contextWindowDetails.effectiveContextWindow;
 		const estimateInput = {
@@ -846,8 +920,9 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 		},
 
 		contextUsage(): ContextUsageSnapshot {
-			if (!state.runtime) return contextUsageSnapshot(null, 0);
-			const effectiveWindow = state.runtime.runtimeResolution.contextWindowDetails.effectiveContextWindow;
+			const effectiveWindow = state.runtime
+				? state.runtime.runtimeResolution.contextWindowDetails.effectiveContextWindow
+				: windowWithoutRuntime().contextWindow;
 			if (!currentContextSnapshot) {
 				return contextUsageSnapshot(null, effectiveWindow);
 			}
@@ -867,28 +942,27 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			const settings = deps.getSettings();
 			const compactionThreshold = settings.compaction?.threshold ?? null;
 			const compactionAuto = settings.compaction?.auto !== false;
-			if (!state.runtime) {
-				return buildContextLedger({
-					provider: settings.orchestrator?.target ?? null,
-					model: settings.orchestrator?.model ?? null,
-					contextWindow: 0,
-					compactionThreshold,
-					compactionAuto,
-				});
-			}
-			const windowDetails = state.runtime.runtimeResolution.contextWindowDetails;
-			const effectiveWindow = windowDetails.effectiveContextWindow;
-
-			const provider = state.runtime.targetId ?? settings.orchestrator?.target ?? null;
-			const model = state.runtime.wireModelId ?? settings.orchestrator?.model ?? null;
+			// Without a runtime (before the first turn of this process, /resume
+			// included) the window comes from the live resolution or the resumed
+			// snapshot, and the token facts from the snapshot: the resumed
+			// messages are the ones it measured.
+			const window = state.runtime
+				? {
+						contextWindow: state.runtime.runtimeResolution.contextWindowDetails.effectiveContextWindow,
+						contextWindowSource: state.runtime.runtimeResolution.contextWindowDetails.contextWindowSource,
+						contextWindowSlots: state.runtime.runtimeResolution.contextWindowDetails.contextWindowSlots,
+					}
+				: windowWithoutRuntime();
+			const provider = state.runtime?.targetId ?? settings.orchestrator?.target ?? null;
+			const model = state.runtime?.wireModelId ?? settings.orchestrator?.model ?? null;
+			const liveToolCount = state.runtime?.agent.state.tools.length ?? 0;
 
 			if (!currentContextSnapshot) {
 				return buildContextLedger({
 					provider,
 					model,
-					contextWindow: effectiveWindow,
-					contextWindowSource: windowDetails.contextWindowSource,
-					toolCount: state.runtime.agent.state.tools.length,
+					...window,
+					toolCount: liveToolCount,
 					compactionThreshold,
 					compactionAuto,
 					promptCache: lastPromptCache,
@@ -903,15 +977,14 @@ export function createTurnContext(deps: TurnContextDeps): TurnContext {
 			return buildContextLedger({
 				provider,
 				model,
-				contextWindow: effectiveWindow,
-				contextWindowSource: windowDetails.contextWindowSource,
+				...window,
 				compactionThreshold,
 				compactionAuto,
 				systemPromptTokens: currentContextSnapshot.categories.system,
 				toolSchemaTokens: currentContextSnapshot.categories.tools,
 				// Persisted snapshots strip the captured schemas; fall back to
 				// the live agent state after a session resume.
-				toolCount: currentContextSnapshot.activeToolSchemas?.length ?? state.runtime.agent.state.tools.length,
+				toolCount: currentContextSnapshot.activeToolSchemas?.length ?? liveToolCount,
 				messageTokens: currentContextSnapshot.categories.messages,
 				agentsTokens: currentContextSnapshot.categories.agents,
 				skillsTokens: currentContextSnapshot.categories.skills,

package/src/interactive/turn-middleware.ts

@@ -25,7 +25,7 @@ export interface TurnMiddlewareDeps {
 	middleware?: MiddlewareContract | undefined;
 	session?: SessionContract | undefined;
 	middlewareToolChoice: MiddlewareToolChoiceControl;
-	emitNotice: (text: string) => void;
+	emitNotice: (text: string, level?: "info" | "warning" | "error") => void;
 	emitFooterNotice: (level: "info" | "success" | "warning" | "error", text: string, key: string) => void;
 }
 
@@ -55,6 +55,14 @@ export interface TurnMiddleware {
 	 * turn_end reminder takes.
 	 */
 	injectDeferredReminder(message: string, severity?: MiddlewareReminderSeverity): void;
+	/**
+	 * Deliver an operator-facing finding produced after its turn boundary closed.
+	 * The watchdog seam: its run settles well after the turn it reviewed, and
+	 * what it found is for the person, not the model. Unlike a deferred
+	 * reminder, this never joins the pending-reminder buffer and never appends a
+	 * `middlewareReminder` entry, so nothing it says can enter the next request.
+	 */
+	emitDeferredNotice(text: string, level?: "info" | "warning"): void;
 }
 
 export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
@@ -205,6 +213,7 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 				runtimeTier: agentRuntime.runtimeResolution.runtimeTier ?? "",
 				activeToolNames: toolNamesFromAgentState(agentRuntime.agent.state.tools).join(","),
 				turnToolCalls: state.turnToolCalls,
+				turnToolNames: state.turnToolNames.join(","),
 				sharedWorkerNote: state.turnSharedWorkerNote,
 			};
 			if (terminalToolResult !== undefined) {
@@ -279,5 +288,11 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 			appendMiddlewareReminderEntry(text, level);
 			deps.emitNotice(text);
 		},
+
+		emitDeferredNotice(text, level = "warning"): void {
+			const message = text.trim();
+			if (message.length === 0) return;
+			deps.emitNotice(message, level);
+		},
 	};
 }

package/src/interactive/turn-runtime.ts

@@ -7,6 +7,7 @@
 
 import { performance } from "node:perf_hooks";
 import type { ClioSettings } from "../core/config.js";
+import { attributedModelId } from "../core/response-model-id.js";
 import type { MiddlewareToolChoiceControl } from "../domains/middleware/index.js";
 import type { ObservabilityContract } from "../domains/observability/contract.js";
 import {
@@ -15,7 +16,7 @@ import {
 	type ProvidersContract,
 	refineRuntimeTargetWithModelHints,
 	resolveRuntimeTarget,
-	runtimeResolutionWarnings,
+	runtimeResolutionWarningsBesideThinkingNotice,
 	type TargetStatus,
 	targetRequiresAuth,
 } from "../domains/providers/index.js";
@@ -199,7 +200,12 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 				failure?.code ?? "admission-failed",
 			);
 		}
-		for (const message of runtimeResolutionWarnings(resolved.diagnostics)) {
+		// emitThinkingClampNotice prints the one combined thinking line when the
+		// dial takes effect; the thinking diagnostics are its two halves.
+		for (const message of runtimeResolutionWarningsBesideThinkingNotice(
+			resolved.diagnostics,
+			resolved.target.modelRuntime.thinking.notice,
+		)) {
 			const key = `${targetId}|${wireModelId}|${message}`;
 			if (announcedResolutionWarnings.has(key)) continue;
 			announcedResolutionWarnings.add(key);
@@ -229,6 +235,7 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 	 */
 	const TARGET_PROBE_TTL_MS = 5 * 60 * 1000;
 	let lastTargetProbe: { key: string; at: number } | null = null;
+	const targetProbesInFlight = new Map<string, Promise<void>>();
 	const ensureLiveCapabilitiesForSelectedModel = async (): Promise<void> => {
 		const settings = deps.getSettings();
 		const targetId = settings.orchestrator.target?.trim();
@@ -239,16 +246,29 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 		const runtimeDesc = deps.providers.getRuntime(target.runtime);
 		if (!runtimeDesc || runtimeDesc.tier === "cloud") return;
 		const key = `${targetId}|${wireModelId}`;
+		const inFlight = targetProbesInFlight.get(key);
+		if (inFlight) {
+			await inFlight;
+			return;
+		}
 		const now = Date.now();
 		if (lastTargetProbe?.key === key && now - lastTargetProbe.at < TARGET_PROBE_TTL_MS) return;
 		lastTargetProbe = { key, at: now };
-		let status: Awaited<ReturnType<ProvidersContract["probeTarget"]>> = null;
+		const probe = (async (): Promise<void> => {
+			let status: Awaited<ReturnType<ProvidersContract["probeTarget"]>> = null;
+			try {
+				status = await deps.providers.probeTarget(targetId);
+			} catch {
+				// Fall back to the last known target state.
+			}
+			announceColdModel(status, targetId, wireModelId);
+		})();
+		targetProbesInFlight.set(key, probe);
 		try {
-			status = await deps.providers.probeTarget(targetId);
-		} catch {
-			// Fall back to the last known target state.
+			await probe;
+		} finally {
+			if (targetProbesInFlight.get(key) === probe) targetProbesInFlight.delete(key);
 		}
-		announceColdModel(status, targetId, wireModelId);
 	};
 
 	/** One notice per target+model+state, so a repeated probe stays quiet. */
@@ -589,6 +609,7 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 				middlewareToolChoice.toolStarted(event.toolName);
 				deps.toolStartTimes.set(event.toolCallId, eventClock);
 				state.turnToolCalls += 1;
+				state.turnToolNames.push(event.toolName);
 			} else if (event.type === "tool_execution_end") {
 				toolsInFlight = Math.max(0, toolsInFlight - 1);
 				const startedAt = deps.toolStartTimes.get(event.toolCallId);
@@ -713,7 +734,11 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 				if (summary.hadUsage && (summary.tokens > 0 || summary.costUsd > 0)) {
 					deps.observability.recordTokens(
 						localRuntime.targetId,
-						localRuntime.wireModelId,
+						attributedModelId(
+							summary.lastResponseModelIdObservation,
+							localRuntime.wireModelId,
+							summary.lastDifferingResponseModelId,
+						),
 						summary.tokens,
 						summary.costUsd,
 						{
@@ -726,6 +751,10 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 							apiCalls: summary.apiCalls,
 						},
 						localRuntime.runtimeResolution.costProvenance,
+						{
+							requestedModelIds: [localRuntime.wireModelId],
+							responseModelIdObservationCounts: summary.responseModelIdObservationCounts,
+						},
 					);
 				}
 				if (summary.output > 0 && firstAssistantDeltaAt !== null) {

package/src/interactive/turn-state.ts

@@ -97,6 +97,8 @@ export interface ChatTurnState {
 	toolProseAssessedChars: number;
 	/** Tool calls observed in the current turn; feeds turn_end metadata. */
 	turnToolCalls: number;
+	/** Names of those calls, in order, so turn_end can tell a listing-only turn from a working one. */
+	turnToolNames: string[];
 	/** A `[worker result]` note the operator shared entered this turn, as the prompt or as a steer; feeds turn_end metadata. */
 	turnSharedWorkerNote: boolean;
 	/** One stalled-turn nudge per user prompt; reset when a real prompt arrives. */
@@ -123,6 +125,7 @@ export function createTurnState(initialThinkingLevel: ThinkingLevel): ChatTurnSt
 		streamStallReason: null,
 		toolProseAssessedChars: 0,
 		turnToolCalls: 0,
+		turnToolNames: [],
 		turnSharedWorkerNote: false,
 		stalledTurnNudgeSpent: false,
 		pendingRequestContinuation: false,

package/src/interactive/watchdog-run.ts

@@ -0,0 +1,75 @@
+/**
+ * The watchdog's run: one read-only verifier dispatch, one transcript notice.
+ *
+ * The middleware registration decides when to fire and what the turn changed;
+ * this decides nothing. It dispatches through the ordinary path so admission,
+ * the receipt, and the Fleet Runs island treat a watchdog run exactly as they
+ * treat any other, reads the failed checks out of the `verifier-report`
+ * contract, and hands the operator one line. A passing report produces nothing
+ * at all.
+ */
+
+import { BusChannels } from "../core/bus-events.js";
+import type { SafeEventBus } from "../core/event-bus.js";
+import { parseVerifierResult } from "../domains/agents/index.js";
+import type { DispatchContract, DispatchRequest } from "../domains/dispatch/contract.js";
+import { type AgentRoleFactsResolver, requestExecutionRole } from "../domains/dispatch/execution-role.js";
+import { WATCHDOG_TASK, type WatchdogTrigger, watchdogBriefing } from "../domains/middleware/index.js";
+import { watchdogBlockersNotice } from "./bus-notices.js";
+
+/** The builtin recipe the watchdog reviews with. */
+export const WATCHDOG_AGENT_ID = "verifier";
+
+export interface WatchdogRunDeps {
+	dispatch: DispatchContract;
+	bus?: SafeEventBus;
+	getAgentRoleFacts?: AgentRoleFactsResolver;
+	/** `watchdog.target` when the operator set one; the session's active target otherwise. */
+	target?: string | undefined;
+	/** One transcript line for the operator. Absent means the finding has nowhere to go and the run is skipped. */
+	emitNotice?: (text: string) => void;
+}
+
+/**
+ * Dispatch one watchdog review and report what it found.
+ *
+ * Resolves when the run has settled, whatever the outcome. A watchdog that
+ * failed is not a turn that failed: the review is advisory, so a broken run
+ * stays silent rather than raising an alarm about itself in the middle of the
+ * operator's work.
+ */
+export async function runWatchdogReview(trigger: WatchdogTrigger, deps: WatchdogRunDeps): Promise<void> {
+	if (!deps.emitNotice) return;
+	const request: DispatchRequest = {
+		agentId: WATCHDOG_AGENT_ID,
+		task: WATCHDOG_TASK,
+		briefing: watchdogBriefing(trigger),
+		executionRole: requestExecutionRole({
+			agentId: WATCHDOG_AGENT_ID,
+			...(deps.getAgentRoleFacts ? { resolveFacts: deps.getAgentRoleFacts } : {}),
+		}),
+		requestOrigin: "internal",
+		// Narrowed below whatever the session holds. A reviewer that could write
+		// would be a second builder nobody admitted.
+		autonomy: "read-only",
+		...(deps.target ? { target: deps.target } : {}),
+	};
+	const progressBus = deps.dispatch.ownsProgressBus?.(deps.bus) === true ? undefined : deps.bus;
+	try {
+		const handle = await deps.dispatch.dispatch(request);
+		for await (const event of handle.events) {
+			const typed = event as { type?: string };
+			if (!typed.type || typed.type === "heartbeat") continue;
+			progressBus?.emit(BusChannels.DispatchProgress, { runId: handle.runId, agentId: WATCHDOG_AGENT_ID, event });
+		}
+		const receipt = await handle.finalPromise;
+		const report = parseVerifierResult(receipt.output?.text ?? null);
+		if (report === null) return;
+		const notice = watchdogBlockersNotice(report.checks);
+		if (notice === null) return;
+		deps.emitNotice(notice.text);
+	} catch {
+		// An advisory review that could not run says nothing. The receipt, if one
+		// was written at all, is in the dispatch board like every other run.
+	}
+}