@iowarp/clio-coder 0.3.3 → 0.3.6

package/src/interactive/context-overlay.ts

@@ -2,9 +2,11 @@ import { homedir } from "node:os";
 import { relative } from "node:path";
 import { BusChannels } from "../core/bus-events.js";
 import type { SafeEventBus } from "../core/event-bus.js";
+import type { WorkingSetView } from "../domains/context/working-set/contract.js";
+import { formatContextWindowSlots } from "../domains/providers/index.js";
 import type { ContextLedger, ContextLedgerGroup } from "../domains/session/context-ledger.js";
 import { type OverlayHandle, Text, type TUI, visibleWidth } from "../engine/tui.js";
-import { contextCategorySwatch, renderContextMeterGrid } from "./context-meter.js";
+import { contextCategorySwatch, renderContextMeterGrid, renderEvictedTokensLine } from "./context-meter.js";
 import { buildHint, showClioOverlayFrame } from "./overlay-frame.js";
 import { abbreviateModelId, type ClioToken, clioTheme, formatContextPercent } from "./theme/index.js";
 
@@ -81,7 +83,85 @@ function legendRow(group: ContextLedgerGroup, contentWidth: number): string {
 	return `${swatch} ${theme.fg(labelToken, labelText)} ${theme.fg("muted", right)}`;
 }
 
-export function renderContextLedgerLines(ledger: ContextLedger, contentWidth: number): string[] {
+function evictedTokens(view: WorkingSetView): number {
+	let total = 0;
+	for (const state of view.evicted.values()) total += state.tokensFreed;
+	return total;
+}
+
+function formatChurn(view: WorkingSetView): string {
+	if (view.itemsEvicted === 0) return "n/a";
+	return (view.recalls / view.itemsEvicted).toFixed(2);
+}
+
+/**
+ * Prose for one cache-disturbance reason. The wire values are stamped by
+ * `noteColdReason` in turn-context.ts and persisted on the assistant entry's
+ * `promptCache.expectedColdReasons`; the overlay reads them back, so an unknown
+ * reason renders as itself rather than disappearing.
+ */
+function coldReasonLabel(reason: string): string {
+	switch (reason) {
+		case "working_set_evict":
+			return "working-set eviction";
+		case "compaction":
+			return "compaction";
+		case "dispatch":
+			return "dispatch traffic";
+		default:
+			return reason;
+	}
+}
+
+/** The operator's working-set configuration, as `/context` states it. */
+export interface WorkingSetConfigView {
+	enabled: boolean;
+	policy: string;
+}
+
+/**
+ * The working-set section: what the projection has taken out of the window
+ * and how often the model has asked for it back. Churn is recalls over items
+ * evicted; a high number means the policy evicts what is still needed.
+ */
+/**
+ * The policy line names what is configured, not what last ran. `lastPolicyId`
+ * is stamped by the first applied event, and eviction runs only when pressure
+ * crosses `compaction.threshold`, so a whole session at the shipped default
+ * read `policy none` (issue #190). With no configuration in hand (older
+ * callers) the last applied policy is still the best available claim.
+ */
+function workingSetPolicyLabel(view: WorkingSetView, config: WorkingSetConfigView | null | undefined): string {
+	if (config === null || config === undefined) return `policy ${view.lastPolicyId ?? "none"}`;
+	if (!config.enabled) return "disabled";
+	const state = view.evictionEvents === 0 ? " · no events yet" : "";
+	const lastRan =
+		view.lastPolicyId !== null && view.lastPolicyId !== config.policy ? ` (last event by ${view.lastPolicyId})` : "";
+	return `policy ${config.policy}${lastRan}${state}`;
+}
+
+function renderWorkingSetLines(view: WorkingSetView, config: WorkingSetConfigView | null | undefined): string[] {
+	const theme = clioTheme();
+	const items = view.evicted.size;
+	const summary = [
+		`${items} evicted item${items === 1 ? "" : "s"}`,
+		`${formatTokens(evictedTokens(view))} tokens`,
+		`${view.evictionEvents} event${view.evictionEvents === 1 ? "" : "s"}`,
+		`${view.recalls} recall${view.recalls === 1 ? "" : "s"}`,
+		`churn ${formatChurn(view)}`,
+	].join(" · ");
+	return [
+		`${theme.fg("muted", "working set")} ${theme.fg("dim", "·")} ${theme.fg("accent", workingSetPolicyLabel(view, config))}`,
+		theme.fg("dim", summary),
+	];
+}
+
+export function renderContextLedgerLines(
+	ledger: ContextLedger,
+	contentWidth: number,
+	workingSet?: WorkingSetView | null,
+	workingSetConfig?: WorkingSetConfigView | null,
+): string[] {
 	const theme = clioTheme();
 	const lines: string[] = [];
 
@@ -98,7 +178,14 @@ export function renderContextLedgerLines(ledger: ContextLedger, contentWidth: nu
 
 	if (ledger.contextWindow > 0) {
 		const source = ledger.measured ? "measured" : "≈ estimated";
-		const summary = `${formatTokens(ledger.usedTokens)} / ${formatTokens(ledger.contextWindow)} tokens (${formatContextPercent(ledger.percent)})`;
+		// `196,608 (786,432 / 4 slots)`: a llama.cpp window that is one slot's
+		// share of the server's KV budget names the split, because the bare
+		// number reads as the whole server and the meter is measured against
+		// the share (issue #187).
+		const window = ledger.contextWindowSlots
+			? formatContextWindowSlots(ledger.contextWindow, ledger.contextWindowSlots)
+			: formatTokens(ledger.contextWindow);
+		const summary = `${formatTokens(ledger.usedTokens)} / ${window} tokens (${formatContextPercent(ledger.percent)})`;
 		const provenance = contextWindowProvenanceLabel(ledger.contextWindowSource);
 		const trailer = provenance ? `${provenance} window · ${source}` : source;
 		lines.push(`${theme.fg("title", summary)} ${theme.fg("dim", "·")} ${theme.fg("muted", trailer)}`);
@@ -110,8 +197,13 @@ export function renderContextLedgerLines(ledger: ContextLedger, contentWidth: nu
 	lines.push("");
 
 	for (const group of ledger.meter) lines.push(legendRow(group, contentWidth));
+	if (workingSet && workingSet.evicted.size > 0) lines.push(renderEvictedTokensLine(evictedTokens(workingSet), theme));
 
 	lines.push("");
+	if (workingSet) {
+		for (const line of renderWorkingSetLines(workingSet, workingSetConfig)) lines.push(line);
+		lines.push("");
+	}
 	if (ledger.projectPreload && ledger.groups.some((group) => group.category === "project")) {
 		lines.push(theme.fg("dim", `project preload: ${ledger.projectPreload}`));
 	}
@@ -141,11 +233,21 @@ export function renderContextLedgerLines(ledger: ContextLedger, contentWidth: nu
 		const uncached =
 			cache.uncachedInputTokens !== null ? `uncached input ${formatTokens(cache.uncachedInputTokens)}` : null;
 		const line = ["prompt cache:", shell, "·", backend, "·", read, ...(uncached ? ["·", uncached] : [])].join(" ");
+		// Reasons Clio recorded before the run: working-set eviction, summary
+		// compaction, and dispatch traffic all move the byte prefix a local
+		// single-slot backend caches, so a cold turn after one of them is the
+		// expected outcome rather than a provider surprise.
+		const coldReasons = cache.backendVerdict === "cold" ? (cache.expectedColdReasons ?? []) : [];
 		// A reused shell with a cold backend means Clio kept the bytes stable
 		// but the provider re-prefilled anyway; surface that disagreement
-		// instead of hiding it.
-		const misleading = cache.shellReused && cache.backendVerdict === "cold";
+		// instead of hiding it. An expected reason explains the same numbers, so
+		// it is reported on its own line and not as a warning.
+		const misleading = cache.shellReused && cache.backendVerdict === "cold" && coldReasons.length === 0;
 		lines.push(theme.fg(misleading ? "warning" : "dim", line));
+		if (coldReasons.length > 0) {
+			const reasons = coldReasons.map(coldReasonLabel).join(", ");
+			lines.push(theme.fg("dim", `last cold turn: ${reasons} (expected)`));
+		}
 	}
 
 	if (ledger.lastCompaction) {
@@ -170,6 +272,10 @@ export interface OpenContextOverlayOptions {
 		onEvent(handler: (event: { type: string }) => void): () => void;
 		isStreaming(): boolean;
 	};
+	/** Working-set fold at the live leaf; null or absent hides the section. */
+	getWorkingSet?: () => WorkingSetView | null;
+	/** The configured `context.workingSet` block, so the policy line states what is set. */
+	getWorkingSetConfig?: () => WorkingSetConfigView | null;
 }
 
 /**
@@ -183,7 +289,14 @@ export function openContextOverlay(
 	getLedger: () => ContextLedger,
 	options?: OpenContextOverlayOptions,
 ): OverlayHandle {
-	const text = new Text(renderContextLedgerLines(getLedger(), DEFAULT_CONTENT_WIDTH).join("\n"), 0, 0);
+	const render = (): string =>
+		renderContextLedgerLines(
+			getLedger(),
+			DEFAULT_CONTENT_WIDTH,
+			options?.getWorkingSet?.() ?? null,
+			options?.getWorkingSetConfig?.() ?? null,
+		).join("\n");
+	const text = new Text(render(), 0, 0);
 	const handle = showClioOverlayFrame(tui, text, {
 		anchor: "center",
 		width: CONTEXT_OVERLAY_WIDTH,
@@ -192,7 +305,7 @@ export function openContextOverlay(
 	});
 
 	const refresh = (): void => {
-		text.setText(renderContextLedgerLines(getLedger(), DEFAULT_CONTENT_WIDTH).join("\n"));
+		text.setText(render());
 		text.invalidate();
 		tui.requestRender();
 	};

package/src/interactive/context-recall-command.ts

@@ -0,0 +1,110 @@
+/**
+ * `/context recall <ref>`: the operator's half of working-set recall.
+ *
+ * The model recalls through `context(scope="recall", ref=...)`, which puts the
+ * body back in front of the model at the tail of the working set. This command
+ * answers a different question, asked by a person: what was in the result the
+ * marker replaced. So the body goes to the transcript and nowhere else. It is
+ * never submitted as a turn, never replayed, and never counted against the
+ * context window, which is why an operator can read a 40k-line build log back
+ * without paying for it.
+ *
+ * Everything else is identical to the tool path, deliberately: the same
+ * `resolveRecall` over the same fold at the same live leaf, the same
+ * `contextRecall` ledger entry (with `trigger: "operator"`), and the same
+ * `BusChannels.ContextRecalled` publication. A recall is a churn signal
+ * whoever asked for it, and a policy that keeps evicting something a human
+ * keeps reading back is a policy worth changing.
+ */
+
+import type { ContextRecalledPayload } from "../core/bus-events.js";
+import type { EvictedState } from "../domains/context/working-set/contract.js";
+import { foldWorkingSet } from "../domains/context/working-set/fold.js";
+import {
+	buildRecallFields,
+	recallErrorMessage,
+	recallParentTurnId,
+	resolveRecall,
+} from "../domains/context/working-set/recall.js";
+import type { SessionEntryInput } from "../domains/session/contract.js";
+import type { SessionEntry } from "../domains/session/entries.js";
+
+/** Ledger access the command needs, mirroring the context tool's `ContextSessionDeps`. */
+export interface OperatorRecallDeps {
+	hasSession(): boolean;
+	readEntries(): ReadonlyArray<SessionEntry>;
+	/** The live append point (`/tree` pin or tree leaf); undefined lets the fold infer it. */
+	activeLeafTurnId(): string | undefined;
+	appendEntry(entry: SessionEntryInput): SessionEntry;
+	/** Publisher for `BusChannels.ContextRecalled`; the runtime supplies the bus. */
+	onRecalled?: (payload: ContextRecalledPayload) => void;
+	now?: () => number;
+}
+
+export type OperatorRecallOutcome =
+	| {
+			ok: true;
+			/** One-line summary for the notice bar. */
+			headline: string;
+			/** The original body, byte-exact, for the transcript. */
+			body: string;
+	  }
+	| { ok: false; message: string };
+
+function formatTokens(tokens: number): string {
+	return tokens.toLocaleString("en-US");
+}
+
+/**
+ * Ref, why it left, what it costs to read, and where the full artifact lives
+ * when the original result was offloaded. Nothing else: the body is on the next
+ * line and the operator is already looking at it.
+ */
+function headlineFor(ref: string, tokens: number, state: EvictedState | undefined, offloadPath?: string): string {
+	const parts = [ref];
+	if (state !== undefined) {
+		parts.push(state.by === undefined ? `evicted: ${state.reason}` : `evicted: ${state.reason} by ${state.by}`);
+	}
+	parts.push(`${formatTokens(tokens)} tokens`);
+	if (offloadPath !== undefined) parts.push(`offload: ${offloadPath}`);
+	return `[/context recall] ${parts.join(" · ")}`;
+}
+
+export function runOperatorRecall(ref: string, deps: OperatorRecallDeps): OperatorRecallOutcome {
+	if (!deps.hasSession()) {
+		return { ok: false, message: "[/context recall] no active session; start one with /new or /resume first" };
+	}
+	const trimmed = ref.trim();
+	if (trimmed.length === 0) {
+		return { ok: false, message: "[/context recall] needs a ref: the turnId named in an [evicted ...] marker" };
+	}
+	const entries = deps.readEntries();
+	const leaf = deps.activeLeafTurnId();
+	const view = foldWorkingSet(entries, leaf);
+	const resolved = resolveRecall(entries, view, trimmed, leaf);
+	// A ref that resolves to nothing is usually a typo or a stale marker; the
+	// shared message ends with the refs the operator could have typed instead.
+	if (!resolved.ok)
+		return { ok: false, message: `[/context recall] ${recallErrorMessage(resolved.error, entries, view)}` };
+	const { result } = resolved;
+	const fields = buildRecallFields(result, { trigger: "operator" });
+	try {
+		deps.appendEntry({ ...fields, parentTurnId: recallParentTurnId(entries, leaf) });
+	} catch (err) {
+		return {
+			ok: false,
+			message: `[/context recall] recall of ${result.ref.entry} could not be recorded: ${err instanceof Error ? err.message : String(err)}`,
+		};
+	}
+	deps.onRecalled?.({
+		ref: result.ref.entry,
+		trigger: "operator",
+		tokensReadmitted: result.tokens,
+		at: deps.now?.() ?? Date.now(),
+	});
+	return {
+		ok: true,
+		headline: headlineFor(result.ref.entry, result.tokens, view.evicted.get(result.ref.entry), result.offloadPath),
+		body: result.body,
+	};
+}

package/src/interactive/cost-overlay.ts

@@ -1,3 +1,8 @@
+import {
+	addResponseModelIdObservationCounts,
+	type ResponseModelIdObservationCounts,
+	responseModelIdObservationCountsLabel,
+} from "../core/response-model-id.js";
 import {
 	aggregateCostAmounts,
 	type CostAggregate,
@@ -16,7 +21,9 @@ export const COST_OVERLAY_WIDTH = DEFAULT_CONTENT_WIDTH + 4;
 
 export interface CostRow {
 	providerId: string;
-	modelId: string;
+	attributedModelId: string;
+	requestedModelIds: string[];
+	responseModelIdObservationCounts: ResponseModelIdObservationCounts;
 	runs: number;
 	tokens: number;
 	input: number;
@@ -33,9 +40,17 @@ function formatTokens(n: number): string {
 }
 
 export function aggregateCostEntries(entries: ReadonlyArray<CostEntry>): CostRow[] {
-	const grouped = new Map<string, { row: Omit<CostRow, "cost">; entries: CostEntry[] }>();
+	const grouped = new Map<
+		string,
+		{
+			row: Omit<CostRow, "cost" | "requestedModelIds" | "responseModelIdObservationCounts">;
+			requestedModelIds: Set<string>;
+			responseModelIdObservationCounts: ResponseModelIdObservationCounts;
+			entries: CostEntry[];
+		}
+	>();
 	for (const entry of entries) {
-		const key = `${entry.providerId}::${entry.modelId}`;
+		const key = `${entry.providerId}::${entry.attributedModelId}`;
 		const existing = grouped.get(key);
 		if (existing) {
 			existing.row.runs += 1;
@@ -46,13 +61,18 @@ export function aggregateCostEntries(entries: ReadonlyArray<CostEntry>): CostRow
 			existing.row.cacheWrite += entry.cacheWrite;
 			existing.row.reasoningTokens += entry.reasoningTokens;
 			existing.row.apiCalls += entry.apiCalls ?? 1;
+			for (const requestedModelId of entry.requestedModelIds) existing.requestedModelIds.add(requestedModelId);
+			addResponseModelIdObservationCounts(
+				existing.responseModelIdObservationCounts,
+				entry.responseModelIdObservationCounts,
+			);
 			existing.entries.push(entry);
 			continue;
 		}
 		grouped.set(key, {
 			row: {
 				providerId: entry.providerId,
-				modelId: entry.modelId,
+				attributedModelId: entry.attributedModelId,
 				runs: 1,
 				tokens: entry.tokens,
 				input: entry.input,
@@ -62,22 +82,31 @@ export function aggregateCostEntries(entries: ReadonlyArray<CostEntry>): CostRow
 				reasoningTokens: entry.reasoningTokens,
 				apiCalls: entry.apiCalls ?? 1,
 			},
+			requestedModelIds: new Set(entry.requestedModelIds),
+			responseModelIdObservationCounts: { ...entry.responseModelIdObservationCounts },
 			entries: [entry],
 		});
 	}
-	const rows = Array.from(grouped.values(), ({ row, entries }) => ({
+	const rows = Array.from(grouped.values(), ({ row, entries, requestedModelIds, responseModelIdObservationCounts }) => ({
 		...row,
+		requestedModelIds: [...requestedModelIds].sort(),
+		responseModelIdObservationCounts,
 		cost: aggregateCostAmounts(entries.map((entry) => ({ usd: entry.usd, provenance: entry.provenance }))),
 	}));
 	rows.sort((a, b) => {
 		if (a.providerId !== b.providerId) return a.providerId < b.providerId ? -1 : 1;
-		if (a.modelId !== b.modelId) return a.modelId < b.modelId ? -1 : 1;
+		if (a.attributedModelId !== b.attributedModelId) return a.attributedModelId < b.attributedModelId ? -1 : 1;
 		return 0;
 	});
 	return rows;
 }
 
-function sumRows(rows: ReadonlyArray<CostRow>): Omit<CostRow, "providerId" | "modelId" | "cost"> {
+function sumRows(
+	rows: ReadonlyArray<CostRow>,
+): Omit<
+	CostRow,
+	"providerId" | "attributedModelId" | "requestedModelIds" | "responseModelIdObservationCounts" | "cost"
+> {
 	return rows.reduce(
 		(acc, row) => ({
 			runs: acc.runs + row.runs,
@@ -156,6 +185,8 @@ function modelBlock(row: CostRow): string[] {
 	// block with token rows and no cost row.
 	const cost = formatCostAggregate(row.cost);
 	return kvBlock([
+		["requested model ids", row.requestedModelIds.join(", ")],
+		["response model id observation", responseModelIdObservationCountsLabel(row.responseModelIdObservationCounts)],
 		["turns", formatTokens(row.runs)],
 		["model calls", formatTokens(row.apiCalls)],
 		...(cost === null ? [] : [["cost", cost] as const]),
@@ -185,7 +216,7 @@ export function formatCostOverlayBodyLines(
 	} else {
 		for (const [index, row] of rows.entries()) {
 			if (index > 0) lines.push("");
-			lines.push(theme.style("accent", `${row.providerId} · ${row.modelId}`, { bold: true }));
+			lines.push(theme.style("accent", `${row.providerId} · attributed model ${row.attributedModelId}`, { bold: true }));
 			for (const line of modelBlock(row)) {
 				lines.push(line);
 			}