@iowarp/clio-coder 0.4.6 → 0.4.8

package/src/interactive/overlays/settings.ts

@@ -54,6 +54,7 @@ import {
 	wrapTextWithAnsi,
 } from "../../engine/tui.js";
 import { clockLocal } from "../format-time.js";
+import { localKey } from "../keyboard-owner.js";
 import { buildHint, DEFAULT_SELECT_THEME, showClioOverlayFrame } from "../overlay-frame.js";
 import { barSep, clioTheme, GLYPH, padAnsi, rule, screenTitle } from "../theme/index.js";
 import { modelsForTarget } from "./model-selector.js";
@@ -119,6 +120,7 @@ const SELECT_DOWN = "\u001b[B";
 /** Settings pickers accept the same j/k navigation as the rows that open them. */
 class SettingsSelectList extends SelectList {
 	override handleInput(data: string): void {
+		data = localKey(data);
 		super.handleInput(data === "j" ? SELECT_DOWN : data === "k" ? SELECT_UP : data);
 	}
 }
@@ -149,7 +151,7 @@ const SETTINGS_SECTION_DESCRIPTIONS = {
 	orchestrator: "Interactive chat routing, prompt pre-warm, and the optional proactive-memory model plane.",
 	fleet: "Defaults, profiles, agent bindings, and route activation for dispatched workers, and where they run.",
 	targets: "Configured inference targets: which one chat and the fleet use, and whether each answers.",
-	models: "The /model picker, favorites, and Alt+J / Alt+K cycling.",
+	models: "The /model picker, favorites, and configured model cycling.",
 	budget: "Cost ceiling, per-turn output budget, worker concurrency, and the guardrail backstops.",
 	compaction: "When and how the context window is evicted and summarized under pressure.",
 	retry: "Automatic recovery from transient provider, network, and stalled-stream errors.",
@@ -422,7 +424,7 @@ const SETTINGS_DESCRIPTIONS_BY_ID = {
 	"panes.yazi.profile": "Use Clio's managed, themed engine profile or the operator's own file-manager configuration.",
 	"panes.yazi.followCwd": "Push the conversation directory into an already-open companion pane.",
 	"panes.yazi.ratio": "Share of the height the files dock takes, at most half.",
-	scope: "Alt+J and Alt+K model cycle set.",
+	scope: "Configured model-cycle action set.",
 	"modelSelector.recentLimit": "How many recently used models /model remembers.",
 	"modelSelector.favorites": "Exact target/model refs pinned in /model.",
 	"budget.sessionCeilingUsd": "Per-session cost cap.",
@@ -540,7 +542,8 @@ const SETTINGS_HELP_BY_ID: Partial<Record<EditableSettingId, string>> = {
 		"Bind base, custom, and shadow native agents such as scout, researcher, and provenance to profiles. ACP delegation agents cannot be bound.",
 	"delegation.defaults.toolGovernance":
 		"clio-coder-policy gates the agent through Clio's safety net; agent-managed trusts the agent; deny-all blocks every tool.",
-	scope: "Choose target-level or exact target/model refs. Alt+J / Alt+K step the chat target through this list.",
+	scope:
+		"Choose target-level or exact target/model refs. Explicit model-cycle bindings step the chat target through this list.",
 	runtimePlugins: "Comma-separated package names, loaded at startup. Restart Clio after changing.",
 	"terminal.notify":
 		"OSC 777, or OSC 9 on iTerm2, Windows Terminal, and ConEmu. Interactive TTY runs only; the body never carries prompt text, file paths, or model output.",
@@ -835,6 +838,7 @@ export class SubmenuWrapper implements Component {
 	}
 
 	handleInput(data: string): void {
+		data = localKey(data);
 		this.child.handleInput?.(data);
 	}
 
@@ -1253,6 +1257,7 @@ class ScopedModelChecklist implements Component {
 	}
 
 	handleInput(data: string): void {
+		data = localKey(data);
 		const kb = getKeybindings();
 		if (kb.matches(data, "tui.select.up") || data === "k") {
 			this.selectedRow = this.nextEntryIndex(this.selectedRow - 1, -1);
@@ -3037,10 +3042,6 @@ function fixedLines(lines: readonly string[], width: number, height: number): st
 }
 
 /** Typed text, as opposed to an escape sequence or a control byte. */
-function isPrintableInput(data: string): boolean {
-	if (data.length === 0 || data.startsWith("\u001b")) return false;
-	return Array.from(data).every((character) => character >= " " && character !== "\u007f");
-}
 
 function scrollWindow(total: number, selected: number, height: number): [number, number] {
 	if (height <= 0 || total <= height) return [0, total];
@@ -3303,6 +3304,17 @@ export class SettingsCenter implements Component {
 	 * Enter commits it and Esc restores the committed query.
 	 */
 	private filterDraft: string | null = null;
+	private readonly filterInput = new Input();
+	get keyboardScope(): "edit" | "review" {
+		return this.filterDraft !== null ? "edit" : "review";
+	}
+	undoInput(): boolean {
+		if (this.filterDraft === null) return false;
+		this.filterInput.applyEdit("undo");
+		this.filterDraft = this.filterInput.getValue();
+		this.normalizeSelection();
+		return true;
+	}
 	/** Local cycle preview for the selected row; committed on Enter. */
 	private pendingValue: string | null = null;
 
@@ -3360,6 +3372,7 @@ export class SettingsCenter implements Component {
 	 * presses and do nothing.
 	 */
 	handleInput(data: string): void {
+		data = localKey(data);
 		if (isKeyRelease(data)) return;
 		if (matchesKey(data, "escape")) {
 			this.back();
@@ -3376,6 +3389,7 @@ export class SettingsCenter implements Component {
 		const kb = getKeybindings();
 		if (data === "/") {
 			this.filterDraft = this.filterQuery;
+			this.filterInput.setValue(this.filterDraft);
 			return;
 		}
 		if (matchesKey(data, "tab")) {
@@ -3459,17 +3473,10 @@ export class SettingsCenter implements Component {
 			this.options.requestRender?.();
 			return;
 		}
-		if (data === "\x7f" || data === "\b") {
-			this.filterDraft = draft.slice(0, -1);
-			this.normalizeSelection();
-			this.options.requestRender?.();
-			return;
-		}
-		if (isPrintableInput(data)) {
-			this.filterDraft = draft + data;
-			this.normalizeSelection();
-			this.options.requestRender?.();
-		}
+		this.filterInput.handleInput(data);
+		this.filterDraft = this.filterInput.getValue();
+		this.normalizeSelection();
+		this.options.requestRender?.();
 	}
 
 	/** The query the catalog is narrowed by right now: the live draft while the

package/src/interactive/overlays/tree-selector.ts

@@ -2,6 +2,7 @@ import type { SessionContract } from "../../domains/session/contract.js";
 import type { TreeSnapshot, TreeSnapshotNode } from "../../domains/session/tree/navigator.js";
 import {
 	type Component,
+	Input,
 	matchesKey,
 	type OverlayHandle,
 	type TUI,
@@ -9,6 +10,7 @@ import {
 	visibleWidth,
 } from "../../engine/tui.js";
 import { clockLocal, dateLocal } from "../format-time.js";
+import { localKey } from "../keyboard-owner.js";
 import { buildHint, clioError, FocusBox, showClioOverlayFrame } from "../overlay-frame.js";
 import { type ClioTheme, clioTheme, GLYPH } from "../theme/index.js";
 
@@ -204,6 +206,13 @@ export class TreeOverlayView implements Component {
 	private showTimestamps = false;
 	private submode: Submode = "browse";
 	private labelBuffer = "";
+	private readonly labelInput = new Input();
+	undoInput(): boolean {
+		if (this.submode !== "edit-label") return false;
+		this.labelInput.applyEdit("undo");
+		this.labelBuffer = this.labelInput.getValue();
+		return true;
+	}
 	private status = "";
 	private statusKind: "info" | "error" = "info";
 
@@ -300,7 +309,11 @@ export class TreeOverlayView implements Component {
 
 	invalidate(): void {}
 
+	get keyboardScope(): "edit" | "browse" {
+		return this.submode === "edit-label" ? "edit" : "browse";
+	}
 	handleInput(data: string): void {
+		data = localKey(data);
 		if (this.submode === "edit-label") {
 			this.handleLabelInput(data);
 			return;
@@ -344,6 +357,7 @@ export class TreeOverlayView implements Component {
 		if (data === "e") {
 			this.submode = "edit-label";
 			this.labelBuffer = this.currentRow()?.node.label ?? "";
+			this.labelInput.setValue(this.labelBuffer);
 			this.setStatus("");
 			return;
 		}
@@ -375,17 +389,8 @@ export class TreeOverlayView implements Component {
 			this.refresh();
 			return;
 		}
-		// Backspace: DEL (0x7f) or BS (0x08).
-		if (data === "\x7f" || data === "\b") {
-			this.labelBuffer = this.labelBuffer.slice(0, -1);
-			return;
-		}
-		// Swallow other control sequences (arrows, etc.) so they do not end up
-		// in the label buffer.
-		if (data.length === 0) return;
-		// Accept printable chars (including multi-byte UTF-8 runs).
-		if (data.charCodeAt(0) < 0x20) return;
-		this.labelBuffer += data;
+		this.labelInput.handleInput(data);
+		this.labelBuffer = this.labelInput.getValue();
 	}
 
 	private setStatus(status: string, kind: "info" | "error" = "info"): void {

package/src/interactive/permission-hint.ts

@@ -14,6 +14,12 @@ export const MUTATION_PREVIEW_KEY = "v";
  */
 export type PermissionInspectionHint = "none" | "closed" | "open";
 
+/** The key that folds and unfolds the standing approval terms on the card. */
+export const PERMISSION_TERMS_KEY = "?";
+
+/** Whether the terms are open. The composer rail never shows this key, so it defaults closed there. */
+export type PermissionTermsHint = "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.
@@ -46,11 +52,18 @@ export type PermissionInspectionHint = "none" | "closed" | "open";
 export function permissionHintEntries(
 	composerHasDraft = false,
 	inspection: PermissionInspectionHint = "none",
+	terms?: PermissionTermsHint,
 ): 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 },
+		// The terms key is the card's own and the most droppable entry: the folded
+		// card already states what the keys do in one row. It sits before the
+		// inspect key so the narrowing drops it first.
+		...(terms === undefined
+			? []
+			: [{ key: PERMISSION_TERMS_KEY, verb: terms === "open" ? "hide terms" : "terms", short: "terms", critical: false }]),
 		...(inspection === "none"
 			? []
 			: inspection === "open"

package/src/interactive/permission-overlay.ts

@@ -15,12 +15,24 @@ import {
 	mutationPreviewWindow,
 } from "./mutation-preview.js";
 import { fitHintEntries } from "./overlay-frame.js";
-import { MUTATION_PREVIEW_KEY, type PermissionInspectionHint, permissionHintEntries } from "./permission-hint.js";
+import {
+	MUTATION_PREVIEW_KEY,
+	PERMISSION_TERMS_KEY,
+	type PermissionInspectionHint,
+	type PermissionTermsHint,
+	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 { MUTATION_PREVIEW_KEY, type PermissionInspectionHint, permissionHintEntries } from "./permission-hint.js";
+export {
+	MUTATION_PREVIEW_KEY,
+	PERMISSION_TERMS_KEY,
+	type PermissionInspectionHint,
+	type PermissionTermsHint,
+	permissionHintEntries,
+} from "./permission-hint.js";
 
 export interface ApprovalRequestView {
 	requestId: string;
@@ -106,12 +118,16 @@ export interface PermissionOverlayBodyHandle extends Component {
 	isInspecting(): boolean;
 	toggleInspect(): void;
 	scrollInspect(delta: number): void;
+	/** The standing approval terms, folded behind `?` (see `permissionOverlayLines`). */
+	isShowingTerms(): boolean;
+	toggleTerms(): void;
 }
 
 class PermissionOverlayBody implements PermissionOverlayBodyHandle {
 	private preview: MutationPreview | null = null;
 	private scroll = 0;
 	private lastLineCount = 0;
+	private terms = false;
 
 	constructor(
 		private readonly view: ApprovalRequestView,
@@ -143,8 +159,16 @@ class PermissionOverlayBody implements PermissionOverlayBodyHandle {
 		this.scroll = Math.max(0, Math.min(this.scroll + delta, maxScroll));
 	}
 
+	isShowingTerms(): boolean {
+		return this.terms;
+	}
+
+	toggleTerms(): void {
+		this.terms = !this.terms;
+	}
+
 	render(width: number): string[] {
-		if (this.preview === null) return permissionOverlayLines(this.view, width);
+		if (this.preview === null) return permissionOverlayLines(this.view, width, this.terms);
 		const rendered = permissionInspectionLines(this.view, this.preview, width, this.scroll);
 		this.lastLineCount = rendered.wrappedLineCount;
 		return rendered.lines;
@@ -153,13 +177,18 @@ class PermissionOverlayBody implements PermissionOverlayBodyHandle {
 	invalidate(): void {}
 }
 
-function truncate(value: string, max: number): string {
-	return value.length <= max ? value : `${value.slice(0, Math.max(0, max - 1))}…`;
-}
-
-/** `label: value`, with the value ellipsized to what the box actually has. */
-function field(label: string, value: string, width: number): string {
-	return `${label}${truncate(value, Math.max(1, width - label.length))}`;
+/**
+ * `label: value`, folded under the label rather than ellipsized.
+ *
+ * The target used to end in an ellipsis at the box edge, so a deep path lost
+ * its file name, which is the one token that says what the write touches. The
+ * value now wraps at spaces and hard-folds a token longer than the row, and a
+ * continuation row hangs under the value's first column.
+ */
+function field(label: string, value: string, width: number): string[] {
+	const indent = " ".repeat(label.length);
+	const rows = wrapSentence(value, Math.max(1, width - label.length));
+	return rows.map((row, index) => `${index === 0 ? label : indent}${row}`);
 }
 
 /**
@@ -235,8 +264,9 @@ export function permissionOverlayHint(
 	innerWidth: number,
 	composerHasDraft = false,
 	inspection: PermissionInspectionHint = "none",
+	terms: PermissionTermsHint = "closed",
 ): string {
-	return fitHintEntries(permissionHintEntries(composerHasDraft, inspection), innerWidth - 3);
+	return fitHintEntries(permissionHintEntries(composerHasDraft, inspection, terms), innerWidth - 3);
 }
 
 /** The tools whose parked call mutates a file, so a card without a preview owes the operator a reason. */
@@ -287,8 +317,8 @@ function permissionInspectionLines(
 	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)] : []),
+		...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),
@@ -299,6 +329,16 @@ function permissionInspectionLines(
 	return { lines, wrappedLineCount: wrapped.length };
 }
 
+/**
+ * The one-row statement of what the three keys do, in the presentation's own
+ * words, so the folded card still says what allow, deny, and stop mean.
+ */
+function termsSummary(presentation: DecisionPresentation, actionClass: string): string {
+	const stop = presentation.requiredActions.find((action) => action.id === "stop");
+	const stopWords = stop?.consequence.includes("main-agent turn") ? "ends the main-agent turn" : "ends the turn";
+	return `Allow runs this one ${actionClass} call and leaves the autonomy level alone. Deny skips it. Stop ${stopWords}. Press ${PERMISSION_TERMS_KEY} for the full terms.`;
+}
+
 /**
  * The overlay's body, laid out for the width the frame gives it.
  *
@@ -306,8 +346,14 @@ function permissionInspectionLines(
  * rest, so a 40-column terminal saw the safety sentences end mid-word and an
  * 80-column one saw the command being authorized end mid-argument, both with
  * nothing marking the cut.
+ *
+ * Seven of the card's thirteen rows were then the same on every call: the
+ * approval, consequence, reversibility, deny, stop, and hard-block sentences.
+ * They are the terms of the decision, not the decision, so they fold behind
+ * `?` and the card leads with what changes per call: the tool, the target in
+ * full, the mutation facts, and who asked.
  */
-function permissionOverlayLines(view: ApprovalRequestView, width: number): string[] {
+function permissionOverlayLines(view: ApprovalRequestView, width: number, terms = false): string[] {
 	const content = Math.max(8, Math.floor(width));
 	const presentation = permissionDecisionPresentation(view);
 	// The parked call is awaiting a decision, not blocked: the raw rejection
@@ -315,19 +361,18 @@ function permissionOverlayLines(view: ApprovalRequestView, width: number): strin
 	// wording contradicts the ask. Tool, Target, Action, and the asking axis
 	// carry everything the operator needs to decide.
 	const lines = [
-		field("Tool: ", `${view.tool} · Action: ${view.actionClass}`, content),
-		...(view.target !== undefined && view.target.length > 0 ? [field("Target: ", view.target, content)] : []),
+		...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.
+		// 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),
-				]
+			? wrapSentence(
+					`Mutation: ${mutationFactsLine(view.mutation)} · press ${MUTATION_PREVIEW_KEY} to read it before deciding`,
+					content,
+				)
 			: []),
 		...(view.mutation === undefined && view.origin.kind === "worker" && isFileMutationTool(view.tool)
 			? wrapSentence(
@@ -336,6 +381,7 @@ function permissionOverlayLines(view: ApprovalRequestView, width: number): strin
 				)
 			: []),
 		...wrapSentence(`Requested by: ${presentation.requestedByCopy}`, content),
+		...(view.queueDepth !== undefined && view.queueDepth > 1 ? [`1 of ${view.queueDepth} parked`] : []),
 		...(view.artifact !== undefined
 			? [
 					"",
@@ -344,16 +390,19 @@ function permissionOverlayLines(view: ApprovalRequestView, width: number): strin
 				]
 			: []),
 		"",
+	];
+	if (!terms) {
+		lines.push(...wrapSentence(termsSummary(presentation, view.actionClass), content));
+		return lines;
+	}
+	lines.push(
 		...wrapSentence(`Approval: ${presentation.authorizationCopy}`, content),
 		...wrapSentence(`Consequence: ${presentation.consequenceCopy}`, content),
 		...wrapSentence(presentation.reversibilityCopy, content),
 		...wrapSentence(`Deny: ${actionConsequence(presentation, "deny")}`, content),
 		...wrapSentence(`Stop: ${actionConsequence(presentation, "stop")}`, content),
 		...wrapSentence("Hard-blocked actions remain blocked.", content),
-	];
-	if (view.queueDepth !== undefined && view.queueDepth > 1) {
-		lines.splice(lines.indexOf(""), 0, `1 of ${view.queueDepth} parked`);
-	}
+	);
 	return lines;
 }
 

package/src/interactive/prewarm.ts

@@ -1,197 +1,11 @@
-/**
- * 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,
-	};
-}
+/** Compatibility entry point; engine preparation is shared with headless callers. */
+export {
+	PREWARM_MAX_TOKENS,
+	PREWARM_USER_TEXT,
+	type PrewarmContext,
+	type PrewarmRoundInput,
+	type PrewarmRoundResult,
+	type PrewarmTrigger,
+	prewarmPromptTokens,
+	runPrewarmRound,
+} from "../engine/prewarm.js";

package/src/interactive/prompt-source-label.ts

@@ -0,0 +1,21 @@
+import type { ResourceSourceInfo } from "../domains/resources/collision.js";
+
+/**
+ * The package a prompt came from, in the words the operator installed it by.
+ * A plugin root's source is `plugin:<scope>:<id>`; the rest are Clio's own
+ * roots and the foreign roots it reads, which carry the agent kind and scope.
+ * A leaf on purpose: the slash registry names the source in a card and must
+ * stay off the render graph.
+ */
+export function promptSourceLabel(sourceInfo: Pick<ResourceSourceInfo, "source" | "scope">): string {
+	const source = sourceInfo.source;
+	if (source === undefined) return `${sourceInfo.scope} prompts`;
+	const plugin = /^plugin:(?:[^:]+):(.+)$/u.exec(source);
+	if (plugin?.[1]) return `plugin ${plugin[1]}`;
+	if (source === "config") return "user prompts";
+	if (source === "project") return "project prompts";
+	if (source === "library") return "library";
+	const foreign = /^([a-z0-9-]+)-(user|project)$/u.exec(source);
+	if (foreign?.[1] && foreign[2]) return `${foreign[1]} ${foreign[2]} prompts`;
+	return source;
+}