@iowarp/clio-coder 0.3.7 → 0.3.9

package/src/interactive/permission-hint.ts

@@ -1,5 +1,19 @@
 import type { HintEntry } from "./overlay-frame.js";
 
+/**
+ * The key that opens and closes local inspection of a parked mutation. It lives
+ * here rather than beside the preview builder so the composer rail can name it
+ * without pulling the diff machinery into the Stage 0 boot shell closure.
+ */
+export const MUTATION_PREVIEW_KEY = "v";
+
+/**
+ * Whether this card has a mutation to read, and whether it is open.
+ * `none` covers every ask with nothing local to inspect, including a worker
+ * escalation, whose arguments never leave the worker.
+ */
+export type PermissionInspectionHint = "none" | "closed" | "open";
+
 /**
  * The keys that answer a parked call, as data, so the dialog footer and the
  * composer rail render the same policy at any width.
@@ -16,17 +30,35 @@ import type { HintEntry } from "./overlay-frame.js";
  *
  * Esc says `deny`, not `close`: closing the dialog denies the call, and on the
  * one surface where a misread is a wrong decision about a tool call the key
- * names its effect.
+ * names its effect. It keeps that meaning while the mutation is open, so the
+ * inspect key is what puts the mutation away again.
  *
  * With a draft in the composer, Enter is inert (issue #186): the habitual send
  * key must not resolve toward "allow" on a safety rail. The entry then says so
  * and names the key that clears the draft, which the router passes through.
+ *
+ * A parked `write` or `edit` adds the inspect key (issue #254). It is
+ * droppable, and deliberately so: at 40 columns the four entries do not fit,
+ * and the three keys that answer the call outrank the one that reads it. The
+ * key keeps working at every width; the `/help` Autonomy & safety net topic is
+ * where it is documented for the widths that cannot show it.
  */
-export function permissionHintEntries(composerHasDraft = false): HintEntry[] {
+export function permissionHintEntries(
+	composerHasDraft = false,
+	inspection: PermissionInspectionHint = "none",
+): HintEntry[] {
 	return [
 		composerHasDraft
 			? { key: "Backspace", verb: "clear the draft to allow", short: "clear draft", critical: true }
 			: { key: "Enter", verb: "allow once", short: "allow", critical: true },
+		...(inspection === "none"
+			? []
+			: inspection === "open"
+				? [
+						{ key: "↑↓", verb: "scroll", critical: false },
+						{ key: MUTATION_PREVIEW_KEY, verb: "hide mutation", short: "hide", critical: false },
+					]
+				: [{ key: MUTATION_PREVIEW_KEY, verb: "inspect mutation", short: "inspect", critical: false }]),
 		{ key: "s", verb: "stop turn", short: "stop", critical: true },
 		// With a draft, deny and stop are the only immediate answers, so Esc
 		// outranks the narrowing that would otherwise drop it first.

package/src/interactive/permission-overlay.ts

@@ -6,13 +6,21 @@ import {
 	decisionFactsForPermission,
 } from "../domains/safety/decision-presentation.js";
 import type { Component, OverlayOptions, TUI } from "../engine/tui.js";
+import {
+	MUTATION_PREVIEW_VISIBLE_ROWS,
+	type MutationFacts,
+	type MutationInspector,
+	type MutationPreview,
+	mutationFactsLine,
+	mutationPreviewWindow,
+} from "./mutation-preview.js";
 import { fitHintEntries } from "./overlay-frame.js";
-import { permissionHintEntries } from "./permission-hint.js";
+import { MUTATION_PREVIEW_KEY, type PermissionInspectionHint, permissionHintEntries } from "./permission-hint.js";
 import type { ClioToken } from "./theme/index.js";
 
 export { type AskAxis, askAxis } from "../domains/safety/approval-axis.js";
 export { describeCallTarget, sanitizeCallTargetText } from "../domains/safety/call-target.js";
-export { permissionHintEntries } from "./permission-hint.js";
+export { MUTATION_PREVIEW_KEY, type PermissionInspectionHint, permissionHintEntries } from "./permission-hint.js";
 
 export interface ApprovalRequestView {
 	requestId: string;
@@ -34,6 +42,14 @@ export interface ApprovalRequestView {
 	 * when nothing meaningful is derivable.
 	 */
 	target?: string;
+	/**
+	 * Size and digest facts for a parked `write` or `edit`, and nothing else
+	 * about it. The mutation text is deliberately absent: this view is what
+	 * reaches the transcript row, the parked notice, and the approval-state
+	 * event, so anything on it has already left the overlay. The text itself is
+	 * held by the inspector the overlay opener is given (issue #254).
+	 */
+	mutation?: MutationFacts;
 	queueDepth?: number;
 }
 
@@ -79,11 +95,59 @@ export function permissionOverlayPlacement(
 	};
 }
 
-class PermissionOverlayBody implements Component {
-	constructor(private readonly view: ApprovalRequestView) {}
+/**
+ * The overlay body, plus the inspection state the key router drives. The
+ * preview is built on the first toggle rather than per frame, so the file read
+ * and the diff happen once when the operator asks for them.
+ */
+export interface PermissionOverlayBodyHandle extends Component {
+	/** Whether this card has a mutation the operator can read locally. */
+	canInspect(): boolean;
+	isInspecting(): boolean;
+	toggleInspect(): void;
+	scrollInspect(delta: number): void;
+}
+
+class PermissionOverlayBody implements PermissionOverlayBodyHandle {
+	private preview: MutationPreview | null = null;
+	private scroll = 0;
+	private lastLineCount = 0;
+
+	constructor(
+		private readonly view: ApprovalRequestView,
+		private readonly inspect?: MutationInspector,
+	) {}
+
+	canInspect(): boolean {
+		return this.inspect !== undefined;
+	}
+
+	isInspecting(): boolean {
+		return this.preview !== null;
+	}
+
+	toggleInspect(): void {
+		if (this.inspect === undefined) return;
+		if (this.preview !== null) {
+			this.preview = null;
+			this.scroll = 0;
+			return;
+		}
+		this.preview = this.inspect();
+		this.scroll = 0;
+	}
+
+	scrollInspect(delta: number): void {
+		if (this.preview === null) return;
+		const maxScroll = Math.max(0, this.lastLineCount - MUTATION_PREVIEW_VISIBLE_ROWS);
+		this.scroll = Math.max(0, Math.min(this.scroll + delta, maxScroll));
+	}
 
 	render(width: number): string[] {
-		return permissionOverlayLines(this.view, width);
+		if (this.preview === null) return permissionOverlayLines(this.view, width);
+		const rendered = permissionInspectionLines(this.view, this.preview, width, this.scroll);
+		this.lastLineCount = rendered.wrappedLineCount;
+		return rendered.lines;
 	}
 
 	invalidate(): void {}
@@ -167,14 +231,74 @@ export function permissionOverlayTone(view: ApprovalRequestView): ClioToken {
  * three columns the bottom border spends on `─ ` and the trailing space come
  * off the top, which is what `buildResponsiveHint` does for every other frame.
  */
-export function permissionOverlayHint(innerWidth: number, composerHasDraft = false): string {
-	return fitHintEntries(permissionHintEntries(composerHasDraft), innerWidth - 3);
+export function permissionOverlayHint(
+	innerWidth: number,
+	composerHasDraft = false,
+	inspection: PermissionInspectionHint = "none",
+): string {
+	return fitHintEntries(permissionHintEntries(composerHasDraft, inspection), innerWidth - 3);
+}
+
+/** The tools whose parked call mutates a file, so a card without a preview owes the operator a reason. */
+function isFileMutationTool(tool: string): boolean {
+	return tool === "write" || tool === "edit";
 }
 
 function actionConsequence(presentation: DecisionPresentation, id: "deny" | "stop"): string {
 	return presentation.requiredActions.find((action) => action.id === id)?.consequence ?? "";
 }
 
+/**
+ * Hard wrap for mutation text. Prose wraps on words; a proposed file line and a
+ * diff row do not, because the column a character sits in is part of what the
+ * operator is reading. The continuation marker says the row was folded rather
+ * than cut, which is the difference between a wrap and unmarked truncation.
+ */
+function wrapMutationLine(value: string, max: number): string[] {
+	if (max <= 1) return [value];
+	if (value.length <= max) return [value];
+	const lines: string[] = [];
+	let remaining = value;
+	while (remaining.length > max) {
+		lines.push(`${remaining.slice(0, max - 1)}↩`);
+		remaining = remaining.slice(max - 1);
+	}
+	lines.push(remaining);
+	return lines;
+}
+
+/**
+ * The card with the mutation open. The tool, target, and digest facts stay at
+ * the top so the bytes on screen remain tied to the call they belong to, and
+ * the standing safety prose gives way to the mutation itself: the operator
+ * opened this to read what changes, and the keys that answer the ask are on the
+ * footer throughout.
+ */
+function permissionInspectionLines(
+	view: ApprovalRequestView,
+	preview: MutationPreview,
+	width: number,
+	scroll: number,
+): { lines: string[]; wrappedLineCount: number } {
+	const content = Math.max(8, Math.floor(width));
+	const wrapped = preview.body.flatMap((line) => wrapMutationLine(line, content));
+	const pane = mutationPreviewWindow(wrapped, scroll);
+	const notes: string[] = [];
+	if (preview.neutralized) notes.push("control characters shown as ·");
+	if (preview.tabsExpanded) notes.push("tabs shown as spaces");
+	const lines = [
+		field("Tool: ", `${view.tool} · Action: ${view.actionClass}`, content),
+		...(view.target !== undefined && view.target.length > 0 ? [field("Target: ", view.target, content)] : []),
+		...wrapSentence(`Mutation: ${mutationFactsLine(preview.facts)}`, content),
+		"",
+		...wrapSentence(preview.heading, content),
+		...pane.window,
+		...(pane.position === null ? [] : [pane.position]),
+		...(notes.length > 0 ? [`Rendered safely: ${notes.join(", ")}.`] : []),
+	];
+	return { lines, wrappedLineCount: wrapped.length };
+}
+
 /**
  * The overlay's body, laid out for the width the frame gives it.
  *
@@ -193,6 +317,24 @@ export function permissionOverlayLines(view: ApprovalRequestView, width: number)
 	const lines = [
 		field("Tool: ", `${view.tool} · Action: ${view.actionClass}`, content),
 		...(view.target !== undefined && view.target.length > 0 ? [field("Target: ", view.target, content)] : []),
+		// Size and digest stay on the collapsed card whether or not the operator
+		// opens the mutation, so the decision always carries the identity of the
+		// bytes it applies to.
+		// Wrapped, never ellipsized: at 40 columns the digest is the tail of the
+		// line, and ellipsizing it would drop the one fact that ties the decision
+		// to the bytes it applies to.
+		...(view.mutation !== undefined
+			? [
+					...wrapSentence(`Mutation: ${mutationFactsLine(view.mutation)}`, content),
+					...wrapSentence(`Press ${MUTATION_PREVIEW_KEY} to read it before deciding.`, content),
+				]
+			: []),
+		...(view.mutation === undefined && view.origin.kind === "worker" && isFileMutationTool(view.tool)
+			? wrapSentence(
+					"No local preview: this call's arguments stay inside the worker, so you are approving the target above without inspecting the mutation.",
+					content,
+				)
+			: []),
 		...wrapSentence(`Requested by: ${presentation.requestedByCopy}`, content),
 		...(view.artifact !== undefined
 			? [
@@ -215,6 +357,14 @@ export function permissionOverlayLines(view: ApprovalRequestView, width: number)
 	return lines;
 }
 
-export function createPermissionOverlayBody(view: ApprovalRequestView): Component {
-	return new PermissionOverlayBody(view);
+/**
+ * The overlay body for one parked call. The inspector, when present, is the
+ * only path the mutation text takes: it is never placed on `view`, so nothing
+ * that renders or forwards the view can carry the bytes with it.
+ */
+export function createPermissionOverlayBody(
+	view: ApprovalRequestView,
+	inspect?: MutationInspector,
+): PermissionOverlayBodyHandle {
+	return new PermissionOverlayBody(view, inspect);
 }

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,
+	};
+}