@iowarp/clio-coder 0.3.8 → 0.4.0

package/src/interactive/prewarm.ts

@@ -0,0 +1,197 @@
+/**
+ * The session pre-warm round: the request the next turn would send, minus the
+ * operator's text, issued as soon as the prefix is known.
+ *
+ * On a local server prefill is the cost. A fresh session's first turn prefills
+ * the whole compiled prompt plus the tool schemas before the model emits a
+ * token, and a resumed session's first turn prefills the entire replayed
+ * history. Both are paid after the operator presses Enter, and both are fully
+ * determined before they type anything. llama.cpp picks the slot with the
+ * longest common prefix and re-evaluates only the suffix, so sending the prefix
+ * early leaves the processed KV in the slot for the real turn to land on.
+ *
+ * The payload is not hand-assembled. It goes through `streamSimple`, the same
+ * dispatcher `createEngineAgent` hands pi-agent-core as its `streamFn`, with the
+ * same system prompt, the same tool schemas, the same replayed messages, and the
+ * same thinking level, so `withSamplingOverrides`, the thinking composition, and
+ * `cache_prompt` resolve exactly as they do for a turn. Any byte that differs
+ * ahead of the user turn would defeat the purpose.
+ */
+
+import type { BackendCompletionTimings } from "../core/cache-telemetry.js";
+import { streamSimple } from "../engine/ai.js";
+import type { AgentMessage, AgentTool, EngineModel, Usage } from "../engine/types.js";
+
+/**
+ * The one user message appended so the chat template renders the prefix up to
+ * the user turn. One character: it has to exist for the template to close the
+ * prefix, and everything after the last shared byte is re-evaluated by the real
+ * turn anyway.
+ */
+export const PREWARM_USER_TEXT = ".";
+
+/** Output budget for the round. The tokens the model produces are not the point. */
+export const PREWARM_MAX_TOKENS = 1;
+
+/** Which trigger asked for the pre-warm. Recorded on the ledger entry. */
+export type PrewarmTrigger = "session-start" | "resume" | "compaction";
+
+export interface PrewarmContext {
+	systemPrompt: string;
+	messages: ReadonlyArray<AgentMessage>;
+	tools: ReadonlyArray<AgentTool>;
+}
+
+/**
+ * The roles pi-agent-core's default `convertToLlm` keeps when it turns the
+ * agent's message list into provider messages. The pre-warm applies the same
+ * filter so its message array is the one a turn would send, not the agent's
+ * internal list.
+ */
+const LLM_MESSAGE_ROLES: ReadonlySet<string> = new Set(["user", "assistant", "toolResult"]);
+
+/**
+ * The prefix of the next turn's request: system prompt, tool schemas, and the
+ * replayed conversation, with no user turn yet.
+ */
+function prewarmPrefix(state: {
+	systemPrompt: string;
+	messages: ReadonlyArray<AgentMessage>;
+	tools: ReadonlyArray<AgentTool>;
+}): PrewarmContext {
+	return {
+		systemPrompt: state.systemPrompt,
+		messages: state.messages.filter((message) => LLM_MESSAGE_ROLES.has((message as { role?: string }).role ?? "")),
+		tools: [...state.tools],
+	};
+}
+
+export interface PrewarmRoundInput {
+	model: EngineModel;
+	/** Live agent state the next turn would send. Read-only; the round copies it. */
+	state: {
+		systemPrompt: string;
+		messages: ReadonlyArray<AgentMessage>;
+		tools: ReadonlyArray<AgentTool>;
+		thinkingLevel: string;
+	};
+	apiKey?: string;
+	signal?: AbortSignal;
+	/** Test seam. Production uses the engine dispatcher a turn runs on. */
+	streamFn?: typeof streamSimple;
+}
+
+export interface PrewarmRoundResult {
+	/** True when the operator submitted (or the session moved) before the round settled. */
+	aborted: boolean;
+	/** Provider usage for the round; null when the backend reported none. */
+	usage: Usage | null;
+	/** Backend prefill and prediction timings when the server reported them. */
+	backend: BackendCompletionTimings | null;
+	/** Wall clock the round spent, in the shape a turn's assistant entry uses. */
+	timing: { ttftMs: number | null; apiMs: number };
+	/** Provider error text when the round failed outright. */
+	errorMessage: string | null;
+}
+
+function usageOf(message: unknown): Usage | null {
+	if (message === null || typeof message !== "object") return null;
+	const usage = (message as { usage?: unknown }).usage;
+	return usage !== null && typeof usage === "object" ? (usage as Usage) : null;
+}
+
+function backendOf(message: unknown): BackendCompletionTimings | null {
+	if (message === null || typeof message !== "object") return null;
+	const backend = (message as { backendTimings?: unknown }).backendTimings;
+	return backend !== null && typeof backend === "object" ? (backend as BackendCompletionTimings) : null;
+}
+
+/**
+ * Prompt tokens the backend actually processed for one pre-warm. The server's
+ * own prompt count is authoritative when it reported one; otherwise the
+ * provider usage prompt side, cached tokens folded in, is the honest figure.
+ * Null when neither exists, which is different from a measured zero.
+ */
+export function prewarmPromptTokens(result: Pick<PrewarmRoundResult, "usage" | "backend">): number | null {
+	if (result.backend) return result.backend.promptTokens;
+	const usage = result.usage;
+	if (!usage) return null;
+	const total = (usage.input || 0) + (usage.cacheRead || 0) + (usage.cacheWrite || 0);
+	return total > 0 ? total : null;
+}
+
+/**
+ * Send the prefix and wait for the backend to acknowledge it. Resolves rather
+ * than rejects on a provider failure: a pre-warm is an optimization, and a
+ * backend that refuses it must not be able to break the session it was warming.
+ */
+export async function runPrewarmRound(input: PrewarmRoundInput): Promise<PrewarmRoundResult> {
+	const prefix = prewarmPrefix(input.state);
+	const context = {
+		systemPrompt: prefix.systemPrompt,
+		messages: [
+			...prefix.messages,
+			{ role: "user", content: [{ type: "text", text: PREWARM_USER_TEXT }], timestamp: Date.now() },
+		],
+		tools: prefix.tools,
+	};
+	// pi-agent-core maps `thinkingLevel: "off"` onto an absent `reasoning`; the
+	// pre-warm has to make the same mapping or the thinking composition resolves
+	// against a different level and the rendered template moves.
+	const options: Record<string, unknown> = { maxTokens: PREWARM_MAX_TOKENS };
+	if (input.state.thinkingLevel !== "off") options.reasoning = input.state.thinkingLevel;
+	if (input.apiKey !== undefined) options.apiKey = input.apiKey;
+	if (input.signal !== undefined) options.signal = input.signal;
+
+	const send = input.streamFn ?? streamSimple;
+	const startedAt = performance.now();
+	let firstDeltaAt: number | null = null;
+	const elapsed = (): number => Math.round(Math.max(0, performance.now() - startedAt));
+	const ttft = (): number | null => (firstDeltaAt === null ? null : Math.round(Math.max(0, firstDeltaAt - startedAt)));
+
+	try {
+		const events = send(
+			input.model,
+			context as unknown as Parameters<typeof streamSimple>[1],
+			options as unknown as Parameters<typeof streamSimple>[2],
+		);
+		for await (const event of events) {
+			if (firstDeltaAt === null && event.type !== "start") firstDeltaAt = performance.now();
+			if (event.type === "done") {
+				return {
+					aborted: false,
+					usage: usageOf(event.message),
+					backend: backendOf(event.message),
+					timing: { ttftMs: ttft(), apiMs: elapsed() },
+					errorMessage: null,
+				};
+			}
+			if (event.type === "error") {
+				const failed = event.error as { stopReason?: unknown; errorMessage?: unknown };
+				const aborted = event.reason === "aborted" || failed.stopReason === "aborted" || input.signal?.aborted === true;
+				return {
+					aborted,
+					usage: usageOf(event.error),
+					backend: backendOf(event.error),
+					timing: { ttftMs: ttft(), apiMs: elapsed() },
+					errorMessage: aborted ? null : typeof failed.errorMessage === "string" ? failed.errorMessage : "pre-warm failed",
+				};
+			}
+		}
+	} catch (error) {
+		return {
+			aborted: input.signal?.aborted === true,
+			usage: null,
+			backend: null,
+			timing: { ttftMs: ttft(), apiMs: elapsed() },
+			errorMessage: input.signal?.aborted === true ? null : error instanceof Error ? error.message : String(error),
+		};
+	}
+	return {
+		aborted: input.signal?.aborted === true,
+		usage: null,
+		backend: null,
+		timing: { ttftMs: ttft(), apiMs: elapsed() },
+		errorMessage: null,
+	};
+}

package/src/interactive/render-trace.ts

@@ -1,6 +1,6 @@
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { appendFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import type { TuiRenderObserver, TuiRenderPhase } from "../engine/tui.js";
 
 /** The trace format is append-only JSONL so partial sessions remain readable. */
@@ -106,6 +106,106 @@ export type RenderTraceRecord =
 	  }
 	| { type: "trace_drop"; version: typeof RENDER_TRACE_VERSION; at: number; records: number };
 
+/** One byte-level delivery from the stdin reader to the application listener. */
+export type RenderTraceInputIngressRecord = Extract<RenderTraceRecord, { type: "input_ingress" }>;
+
+/**
+ * How many `input_ingress` records and how many committed frame records the
+ * always-on ring keeps, each. 256 keystrokes and 256 committed frames cover the
+ * last stretch of interaction an operator would still be describing when they
+ * kill a wedged pane, and cost about 200 KB of process memory in the worst case
+ * (a frame record carries its terminal-write commits).
+ */
+export const INPUT_WEDGE_RING_CAPACITY = 256;
+
+/** Subdirectory of the state directory that holds SIGTERM wedge dumps. */
+export const INPUT_WEDGE_DUMP_DIRNAME = "input-wedge";
+
+/** Dumps kept in that directory; older ones are removed as new ones land. */
+export const INPUT_WEDGE_DUMP_RETAINED = 5;
+
+/**
+ * Which half of the input pipeline was still moving when the dump was taken.
+ *
+ * `input-not-committed` is the consumer's failure: bytes reached the
+ * application listener and no frame that carries them ever reached stdout.
+ * `no-input-recorded` is the reader's: nothing was delivered at all, so an
+ * operator who was typing was typing into a reader that had stopped.
+ * `input-committed` says neither half of this pipeline was stuck.
+ */
+export type InputWedgeClassification = "no-input-recorded" | "input-not-committed" | "input-committed";
+
+export interface InputWedgeSnapshot {
+	version: typeof RENDER_TRACE_VERSION;
+	capacity: number;
+	pid: number;
+	/** Wall clock at trace open, so a record's relative `at` maps onto real time. */
+	openedAtEpochMs: number;
+	atEpochMs: number;
+	/** Milliseconds since trace open, the same clock every record's `at` uses. */
+	at: number;
+	classification: InputWedgeClassification;
+	msSinceLastInputIngress: number | null;
+	msSinceLastCommittedFrame: number | null;
+	inputIngress: RenderTraceInputIngressRecord[];
+	frames: RenderTraceFrameRecord[];
+}
+
+/** Bounded FIFO that overwrites its oldest entry rather than growing. */
+function createRing<T>(capacity: number): { push(value: T): void; toArray(): T[] } {
+	const slots: T[] = [];
+	let next = 0;
+	return {
+		push(value): void {
+			if (slots.length < capacity) slots.push(value);
+			else slots[next] = value;
+			next = (next + 1) % capacity;
+		},
+		toArray(): T[] {
+			if (slots.length < capacity) return [...slots];
+			return [...slots.slice(next), ...slots.slice(0, next)];
+		},
+	};
+}
+
+/**
+ * Read the two rings the way the ticket asks the wedge to be read: the newest
+ * input the operator should have seen, against the newest frame that reached
+ * stdout carrying it.
+ */
+function classifyInputWedge(
+	inputIngress: ReadonlyArray<RenderTraceInputIngressRecord>,
+	frames: ReadonlyArray<RenderTraceFrameRecord>,
+): InputWedgeClassification {
+	const newest = [...inputIngress].reverse().find((record) => record.visualExpected) ?? inputIngress.at(-1);
+	if (newest === undefined) return "no-input-recorded";
+	return frames.some((frame) => frame.inputHighWater >= newest.inputSeq) ? "input-committed" : "input-not-committed";
+}
+
+/**
+ * Write one snapshot under `<stateDir>/input-wedge/`, newest-first by name, and
+ * drop everything past the retention bound. Synchronous on purpose: the caller
+ * is a signal handler on a process that is about to end.
+ */
+export function writeInputWedgeDump(stateDir: string, snapshot: InputWedgeSnapshot): string {
+	const directory = join(stateDir, INPUT_WEDGE_DUMP_DIRNAME);
+	mkdirSync(directory, { recursive: true });
+	const stamp = new Date(snapshot.atEpochMs).toISOString().replace(/[:.]/gu, "-");
+	const path = join(directory, `${stamp}-${snapshot.pid}.json`);
+	writeFileSync(path, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+	try {
+		const existing = readdirSync(directory)
+			.filter((name) => name.endsWith(".json"))
+			.sort();
+		for (const name of existing.slice(0, Math.max(0, existing.length - INPUT_WEDGE_DUMP_RETAINED))) {
+			rmSync(join(directory, name), { force: true });
+		}
+	} catch {
+		// Retention is housekeeping; a dump that landed is worth more than a tidy directory.
+	}
+	return path;
+}
+
 interface TraceWriter {
 	enqueue(record: RenderTraceRecord): void;
 	close(): Promise<void>;
@@ -236,6 +336,8 @@ export interface RenderTrace extends TuiRenderObserver {
 	recordTerminalDrain(writeId: number): void;
 	currentFrameId(): number | null;
 	onFirstFrameCommit(listener: (frameId: number) => void): void;
+	/** The always-on ring as it stands, classified. Allocates; call it once, on the way out. */
+	snapshotInputWedge(): InputWedgeSnapshot;
 	close(): Promise<void>;
 }
 
@@ -255,17 +357,32 @@ export function renderTracePath(env: NodeJS.ProcessEnv = process.env): string |
 	return raw && raw.length > 0 ? raw : null;
 }
 
+/**
+ * One tracer, two sinks. The JSONL file is the armed sink: it exists only when
+ * `CLIO_CODER_RENDER_TRACE` named a path, and it keeps every record. The
+ * bounded in-memory ring is the always-on sink: it keeps the last
+ * {@link INPUT_WEDGE_RING_CAPACITY} `input_ingress` records and the same number
+ * of committed frames, so the SIGTERM that recovers a wedged pane can still say
+ * which half of the input pipeline stopped (#224). A null `path` is the
+ * ring-only mode, and there the recorders that only ever fed the file keep
+ * their counters and skip building a record nothing would read.
+ */
 export function createRenderTrace(
-	path: string,
+	path: string | null,
 	now: () => number = () => performance.now(),
 	writerOptions: AsyncTraceWriterOptions = {},
 ): RenderTrace {
 	// Initialization happens before the terminal/TUI starts, never in a frame.
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, "", "utf8");
+	if (path !== null) {
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, "", "utf8");
+	}
 	const openedAt = now();
+	const openedAtEpochMs = Date.now();
 	const at = (): number => rounded(now() - openedAt);
-	const writer = createAsyncTraceWriter(path, { ...writerOptions, recordTime: at });
+	const writer = path === null ? null : createAsyncTraceWriter(path, { ...writerOptions, recordTime: at });
+	const inputRing = createRing<RenderTraceInputIngressRecord>(INPUT_WEDGE_RING_CAPACITY);
+	const frameRing = createRing<RenderTraceFrameRecord>(INPUT_WEDGE_RING_CAPACITY);
 	let frameSeq = 0;
 	let writeSeq = 0;
 	let eventSeq = 0;
@@ -282,7 +399,7 @@ export function createRenderTrace(
 	const ranges = new Map<string, { codeUnits: number; graphemes: number }>();
 	const pendingDrains = new Map<number, { frameId: number | null; at: number }>();
 
-	writer.enqueue({ type: "trace_start", version: RENDER_TRACE_VERSION, at: 0 });
+	writer?.enqueue({ type: "trace_start", version: RENDER_TRACE_VERSION, at: 0 });
 
 	const trace: RenderTrace = {
 		recordPanelRender(metrics): void {
@@ -294,12 +411,15 @@ export function createRenderTrace(
 		},
 		recordVisibleEvent(fields): number {
 			eventSeq += 1;
+			// The ring keeps no provider deltas, so ring-only mode does not pay for
+			// grapheme segmentation on every token of every stream.
+			if (writer === null) return eventSeq;
 			const key = `${generation}:${fields.kind}:${fields.contentIndex}`;
 			const previous = ranges.get(key) ?? { codeUnits: 0, graphemes: 0 };
 			const graphemes = graphemeCount(fields.delta);
 			const next = { codeUnits: previous.codeUnits + fields.delta.length, graphemes: previous.graphemes + graphemes };
 			ranges.set(key, next);
-			writer.enqueue({
+			writer?.enqueue({
 				type: "event_ingress",
 				version: RENDER_TRACE_VERSION,
 				eventSeq,
@@ -317,7 +437,7 @@ export function createRenderTrace(
 		},
 		recordQueue(sequence, action): void {
 			queueDepth = Math.max(0, queueDepth + (action === "admit" ? 1 : -1));
-			writer.enqueue({
+			writer?.enqueue({
 				type: "queue",
 				version: RENDER_TRACE_VERSION,
 				eventSeq: sequence,
@@ -328,7 +448,7 @@ export function createRenderTrace(
 		},
 		recordPanelApplied(sequence): void {
 			panelHighWater = Math.max(panelHighWater, sequence);
-			writer.enqueue({
+			writer?.enqueue({
 				type: "panel",
 				version: RENDER_TRACE_VERSION,
 				eventSeq: sequence,
@@ -339,7 +459,7 @@ export function createRenderTrace(
 		recordInputIngress(action, bytes, visualExpected = action !== "no-visual-change"): number {
 			inputSeq += 1;
 			if (visualExpected) inputHighWater = inputSeq;
-			writer.enqueue({
+			const record: RenderTraceInputIngressRecord = {
 				type: "input_ingress",
 				version: RENDER_TRACE_VERSION,
 				inputSeq,
@@ -347,7 +467,9 @@ export function createRenderTrace(
 				at: at(),
 				bytes,
 				visualExpected,
-			});
+			};
+			inputRing.push(record);
+			writer?.enqueue(record);
 			return inputSeq;
 		},
 		beginFrame(fields): FrameState {
@@ -403,8 +525,11 @@ export function createRenderTrace(
 				},
 				commits: frame.commits,
 			};
-			writer.enqueue(record);
+			writer?.enqueue(record);
 			if (frame.commits.length > 0) {
+				// Only a frame that reached stdout answers the question the ring exists
+				// for, which is whether the consumer half is still painting.
+				frameRing.push(record);
 				lastCommitAt = frame.commits.at(-1)?.at ?? endAt;
 				if (!firstCommitDelivered) {
 					firstCommitDelivered = true;
@@ -439,6 +564,7 @@ export function createRenderTrace(
 				backpressured: !fields.returned,
 			};
 			currentFrame?.commits.push(commit);
+			if (writer === null) return writeSeq;
 			writer.enqueue({ type: "terminal_write", version: RENDER_TRACE_VERSION, frameId, ...commit });
 			if (!fields.returned) pendingDrains.set(writeSeq, { frameId, at: commit.at });
 			return writeSeq;
@@ -448,7 +574,7 @@ export function createRenderTrace(
 			if (!pending) return;
 			pendingDrains.delete(writeId);
 			const drainAt = at();
-			writer.enqueue({
+			writer?.enqueue({
 				type: "terminal_drain",
 				version: RENDER_TRACE_VERSION,
 				writeId,
@@ -461,7 +587,28 @@ export function createRenderTrace(
 		onFirstFrameCommit(listener): void {
 			firstCommitListener = listener;
 		},
-		close: () => writer.close(),
+		snapshotInputWedge(): InputWedgeSnapshot {
+			const inputIngress = inputRing.toArray();
+			const frames = frameRing.toArray();
+			const nowAt = at();
+			const lastIngressAt = inputIngress.at(-1)?.at;
+			const lastFrame = frames.at(-1);
+			const lastFrameCommitAt = lastFrame?.commits.at(-1)?.at ?? lastFrame?.endAt;
+			return {
+				version: RENDER_TRACE_VERSION,
+				capacity: INPUT_WEDGE_RING_CAPACITY,
+				pid: process.pid,
+				openedAtEpochMs,
+				atEpochMs: Date.now(),
+				at: nowAt,
+				classification: classifyInputWedge(inputIngress, frames),
+				msSinceLastInputIngress: lastIngressAt === undefined ? null : rounded(nowAt - lastIngressAt),
+				msSinceLastCommittedFrame: lastFrameCommitAt === undefined ? null : rounded(nowAt - lastFrameCommitAt),
+				inputIngress,
+				frames,
+			};
+		},
+		close: () => writer?.close() ?? Promise.resolve(),
 	};
 	return trace;
 }

package/src/interactive/renderers/compaction-summary.ts

@@ -49,6 +49,35 @@ export function renderCompactionSummaryLine(input: CompactionSummaryLineInput):
 	return `[context engine] llm_summary: ${input.messagesSummarized} messages summarized to ${input.summaryChars} chars; ~${input.tokensBefore} tokens before${tail}`;
 }
 
+/** Why the non-destructive stage had nothing to do before a summary ran. */
+export type EvictionSkipReason = "all-protected" | "nothing-evictable" | "disabled";
+
+export interface EvictionSkipLineInput {
+	reason: EvictionSkipReason;
+	/** Turn starts in the visible slice the policy was offered. */
+	turns: number;
+	protectLastTurns: number;
+	policyId: string;
+}
+
+/**
+ * One line saying the working-set stage was considered and declined, in the
+ * same `[context engine] working set:` voice its eviction notice uses. Without
+ * it a short session falls from the pressure threshold straight into the
+ * destructive summary with nothing in the transcript explaining why the cheap
+ * stage did not run (smoke pass 2, G1).
+ */
+export function renderEvictionSkipLine(input: EvictionSkipLineInput): string {
+	const turnWord = input.turns === 1 ? "turn" : "turns";
+	const cause =
+		input.reason === "disabled"
+			? "eviction is off (context.workingSet.enabled false)"
+			: input.reason === "all-protected"
+				? `nothing evictable, all ${input.turns} ${turnWord} are inside the protected window (protectLastTurns ${input.protectLastTurns})`
+				: `nothing evictable by ${input.policyId} above the protected window (protectLastTurns ${input.protectLastTurns})`;
+	return `[context engine] working set: ${cause}; llm_summary runs instead`;
+}
+
 export interface RenderCompactionSummaryOptions {
 	/** Override the default markdown theme. Defaults to the local theme above. */
 	theme?: MarkdownTheme;

package/src/interactive/renderers/tool-execution.ts

@@ -18,6 +18,7 @@ import { formatSize } from "../../engine/truncate.js";
 import { visibleWidth, wrapTextWithAnsi } from "../../engine/tui.js";
 import { classifyResourceRead, toolPresentationPolicy } from "../../tools/presentation.js";
 import { toolResultPresentationPolicy, toolResultPresentationText } from "../../tools/result-disposition.js";
+import { mutationFactsLine } from "../mutation-preview.js";
 import type { ApprovalRequestView } from "../permission-overlay.js";
 import { clioTheme, formatCompactMs, GLYPH } from "../theme/index.js";
 import { renderDiffLines } from "./diff.js";
@@ -490,6 +491,9 @@ export function renderToolAwaitingApproval(
 		["action", view.actionClass],
 		["axis", axis],
 		...(view.target !== undefined && view.target.length > 0 ? [["target", view.target]] : []),
+		// Size and digest, never the mutation text: this row is the transcript,
+		// which is written, replayed, and shared (issue #254).
+		...(view.mutation !== undefined ? [["mutation", mutationFactsLine(view.mutation)]] : []),
 	] as const;
 	for (const [label, value] of facts) {
 		lines.push(...indentAndWrap(`${dim(`${label} ·`)} ${value}`, width, false));