@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/interactive/permission-overlay.ts

@@ -0,0 +1,170 @@
+import type { Component } from "../engine/tui.js";
+import { buildResponsiveHint } from "./overlay-frame.js";
+
+export { type AskAxis, askAxis } from "../domains/safety/approval-axis.js";
+export { describeCallTarget, sanitizeCallTargetText } from "../domains/safety/call-target.js";
+
+export interface ApprovalRequestView {
+	requestId: string;
+	tool: string;
+	actionClass: string;
+	axis: { kind: "net"; ruleId: string } | { kind: "autonomy"; level: string };
+	origin: { kind: "main" } | { kind: "worker"; agentId: string; runId: string };
+	reason: string;
+	/** Typed, sanitized multi-line artifact that this one approval authorizes. */
+	artifact?: { kind: "dispatch-plan"; text: string };
+	/**
+	 * One-line preview of the call's object: the command for bash, the path
+	 * for file tools, else a compact args preview. The operator is deciding
+	 * whether to allow this exact call, so the overlay must show what the
+	 * call will touch, not just the tool name. Main-agent asks derive it from
+	 * the parked call's args; worker escalations carry it in the escalation
+	 * payload. Absent only when nothing meaningful is derivable.
+	 */
+	target?: string;
+	queueDepth?: number;
+}
+
+const PERMISSION_OVERLAY_CONTENT_WIDTH = 78;
+
+export const PERMISSION_OVERLAY_WIDTH = PERMISSION_OVERLAY_CONTENT_WIDTH + 4;
+
+class PermissionOverlayBody implements Component {
+	constructor(private readonly view: ApprovalRequestView) {}
+
+	render(width: number): string[] {
+		return permissionOverlayLines(this.view, width);
+	}
+
+	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))}`;
+}
+
+/**
+ * Greedy word wrap for prose. The safety sentences are the operator's only
+ * statement of what allow and stop mean, so they wrap: cutting them at the
+ * border produced "allow or de" on the surface where a misread is a wrong
+ * decision about a tool call.
+ */
+function wrapSentence(value: string, max: number): string[] {
+	if (max <= 0) return [value];
+	const lines: string[] = [];
+	let current = "";
+	for (const word of value.split(" ")) {
+		if (current.length === 0) current = word;
+		else if (current.length + 1 + word.length <= max) current = `${current} ${word}`;
+		else {
+			lines.push(current);
+			current = word;
+		}
+		while (current.length > max) {
+			lines.push(current.slice(0, max));
+			current = current.slice(max);
+		}
+	}
+	if (current.length > 0) lines.push(current);
+	return lines;
+}
+
+function wrapArtifactLine(value: string, max: number): string[] {
+	if (value.length <= max) return [value];
+	const lines: string[] = [];
+	let remaining = value;
+	while (remaining.length > max) {
+		const candidate = remaining.slice(0, max + 1);
+		const whitespace = candidate.lastIndexOf(" ");
+		const cut = whitespace >= Math.floor(max / 2) ? whitespace : max;
+		lines.push(remaining.slice(0, cut));
+		remaining = `    ${remaining.slice(cut).trimStart()}`;
+	}
+	lines.push(remaining);
+	return lines;
+}
+
+function axisLabel(axis: ApprovalRequestView["axis"], style: ApprovalRequestView["origin"]["kind"]): string {
+	if (axis.kind === "net") return `safety-net rail ${axis.ruleId}`;
+	return style === "worker" ? `autonomy level ${axis.level}` : `autonomy level (${axis.level})`;
+}
+
+function askedBy(view: ApprovalRequestView): string {
+	if (view.origin.kind === "worker") {
+		return `worker ${view.origin.agentId} (run ${view.origin.runId}), ${axisLabel(view.axis, "worker")}`;
+	}
+	return axisLabel(view.axis, "main");
+}
+
+export function permissionOverlayTitle(): string {
+	return "Allow this action once?";
+}
+
+/**
+ * The footer for a box `innerWidth` columns wide inside its borders.
+ *
+ * At 40 columns the old positional elider removed `[s] stop turn` and left
+ * "allow once" and an ambiguous "close" in front of an operator trying to
+ * refuse. The key kept working, so the layout was hiding a live safety action.
+ * This surface used to answer that with three hand-written width tiers; it now
+ * states the same policy as data. Allow and stop are marked critical, Esc is
+ * marked droppable, and `fitHintEntries` shortens every label before it drops
+ * anything, which reproduces the three tiers exactly.
+ */
+export const permissionOverlayHint = buildResponsiveHint(
+	[
+		{ key: "Enter", verb: "allow once", short: "allow", critical: true },
+		{ key: "s", verb: "stop turn", short: "stop", critical: true },
+	],
+	{ key: "Esc", verb: "close", critical: false },
+);
+
+const SAFETY_SENTENCES: ReadonlyArray<string> = [
+	"Parked until you decide; allow or deny applies to this call only.",
+	"Stopping the turn denies it and ends the run, so nothing asks again.",
+	"Hard-blocked actions remain blocked.",
+];
+
+/**
+ * The overlay's body, laid out for the width the frame gives it.
+ *
+ * Every line used to be sized for a 78-column box and the frame hard-cut the
+ * 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.
+ */
+export function permissionOverlayLines(view: ApprovalRequestView, width: number): string[] {
+	const content = Math.max(8, Math.floor(width));
+	// The parked call is awaiting a decision, not blocked: the raw rejection
+	// short ("<tool> blocked: <class>") is never rendered here because its
+	// wording contradicts the ask. Tool, Target, Action, and the asking axis
+	// carry everything the operator needs to decide.
+	const lines = [
+		field("Tool: ", view.tool, content),
+		...(view.target !== undefined && view.target.length > 0 ? [field("Target: ", view.target, content)] : []),
+		field("Action: ", view.actionClass, content),
+		field("Asked by: ", askedBy(view), content),
+		...(view.artifact !== undefined
+			? [
+					"",
+					"Resolved dispatch plan:",
+					...view.artifact.text.split(/\r?\n/u).flatMap((line) => wrapArtifactLine(line, content)),
+				]
+			: []),
+		"",
+		...SAFETY_SENTENCES.flatMap((sentence) => wrapSentence(sentence, content)),
+	];
+	if (view.queueDepth !== undefined && view.queueDepth > 1) {
+		lines.splice(lines.indexOf(""), 0, `1 of ${view.queueDepth} parked`);
+	}
+	return lines;
+}
+
+export function createPermissionOverlayBody(view: ApprovalRequestView): Component {
+	return new PermissionOverlayBody(view);
+}

package/src/interactive/render-trace.ts

@@ -0,0 +1,125 @@
+import { appendFileSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * Opt-in per-frame render instrument. Off unless CLIO_CODER_RENDER_TRACE names a
+ * file, and it costs one `performance.now()` plus a buffered line per frame
+ * when it is on.
+ *
+ * It exists because "the TUI is janky with a fast model" is not a number.
+ * Two costs hide behind that sentence and they call for different fixes: time
+ * spent building the frame (chat-panel render, markdown, wrapping) and time
+ * spent writing it (bytes to the terminal, full redraws instead of diffs). A
+ * row per frame carrying both, plus the gap since the previous frame, tells
+ * them apart.
+ */
+export interface RenderTraceRow {
+	/** ms since the trace opened. */
+	at: number;
+	/** ms since the previous frame's write, or null for the first. */
+	sinceLastMs: number | null;
+	/** Bytes handed to the terminal for this frame. */
+	bytes: number;
+	/** Chat-panel render time attributed to this frame, when one was recorded. */
+	panelMs: number | null;
+	panelCacheHit: boolean | null;
+	panelEntries: number | null;
+	/** Stream deltas applied since the previous frame. */
+	deltas: number;
+	/** ms from the first unrendered delta to this frame, or null when none arrived. */
+	deltaLagMs: number | null;
+}
+
+export interface RenderTrace {
+	recordPanelRender(metrics: { durationMs: number; cacheHit: boolean; entriesRendered: number }): void;
+	/** One streamed text/thinking delta reached the panel. */
+	recordDelta(): void;
+	recordFrame(bytes: number): void;
+	close(): void;
+}
+
+/**
+ * Rows buffered before a synchronous append. Small enough that a session read
+ * mid-run sees the frames it just produced, which the first measuring attempt
+ * did not: a 64-row buffer that only ever flushed once described startup and
+ * said nothing about the streaming turn it was opened for.
+ */
+const FLUSH_EVERY = 8;
+
+export function renderTracePath(env: NodeJS.ProcessEnv = process.env): string | null {
+	const raw = env.CLIO_CODER_RENDER_TRACE?.trim();
+	return raw && raw.length > 0 ? raw : null;
+}
+
+export function createRenderTrace(path: string, now: () => number = () => performance.now()): RenderTrace {
+	mkdirSync(dirname(path), { recursive: true });
+	// Truncate on open so a trace is one session, never an append of several.
+	writeSync(openSync(path, "w"), "");
+	const openedAt = now();
+	let lastFrameAt: number | null = null;
+	// The panel renders during the frame that is about to be written, so its
+	// metrics are held until that write attributes them.
+	let pendingPanel: { durationMs: number; cacheHit: boolean; entriesRendered: number } | null = null;
+	let pendingDeltas = 0;
+	let firstPendingDeltaAt: number | null = null;
+	let buffer: string[] = [];
+
+	const flush = (): void => {
+		if (buffer.length === 0) return;
+		const payload = buffer.join("");
+		buffer = [];
+		try {
+			appendFileSync(path, payload);
+		} catch {
+			// A trace that cannot be written must not take the session down.
+		}
+	};
+
+	return {
+		recordPanelRender(metrics): void {
+			pendingPanel = metrics;
+		},
+		recordDelta(): void {
+			pendingDeltas += 1;
+			firstPendingDeltaAt ??= now() - openedAt;
+		},
+		recordFrame(bytes): void {
+			const at = now() - openedAt;
+			const row: RenderTraceRow = {
+				at: Math.round(at * 1000) / 1000,
+				sinceLastMs: lastFrameAt === null ? null : Math.round((at - lastFrameAt) * 1000) / 1000,
+				bytes,
+				panelMs: pendingPanel ? Math.round(pendingPanel.durationMs * 1000) / 1000 : null,
+				panelCacheHit: pendingPanel ? pendingPanel.cacheHit : null,
+				panelEntries: pendingPanel ? pendingPanel.entriesRendered : null,
+				deltas: pendingDeltas,
+				deltaLagMs: firstPendingDeltaAt === null ? null : Math.round((at - firstPendingDeltaAt) * 1000) / 1000,
+			};
+			lastFrameAt = at;
+			pendingPanel = null;
+			pendingDeltas = 0;
+			firstPendingDeltaAt = null;
+			buffer.push(`${JSON.stringify(row)}\n`);
+			if (buffer.length >= FLUSH_EVERY) flush();
+		},
+		close(): void {
+			flush();
+		},
+	};
+}
+
+/**
+ * Wrap a terminal so every frame's byte count reaches the trace. pi-tui emits
+ * exactly one `write` per rendered frame, so counting writes counts frames.
+ */
+export function traceTerminalWrites<TTerminal extends { write(data: string): void }>(
+	terminal: TTerminal,
+	trace: Pick<RenderTrace, "recordFrame">,
+): TTerminal {
+	const original = terminal.write.bind(terminal);
+	terminal.write = (data: string): void => {
+		trace.recordFrame(Buffer.byteLength(data, "utf8"));
+		original(data);
+	};
+	return terminal;
+}

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

@@ -0,0 +1,86 @@
+/**
+ * Renderer for BranchSummary session entries (Phase 12 / slice 12b).
+ *
+ * A branchSummary entry is produced when a fork inherits a compacted parent
+ * context: the new session opens with a single summary block standing in for
+ * the parent lineage. Showing that block up front is what tells a forked
+ * session's chat panel "you inherited this context" without replaying the
+ * pre-fork transcript verbatim.
+ *
+ * The renderer is pure: `(entry, width) -> string[]`. It mirrors the segment
+ * output shape the existing chat-panel render loop emits so a later slice can
+ * feed the lines through the transcript unchanged. No pi-agent-core or
+ * session-writer imports; tests construct a synthetic entry and assert on the
+ * rendered lines directly.
+ */
+
+import type { BranchSummaryEntry } from "../../domains/session/entries.js";
+import { Markdown, type MarkdownTheme, wrapTextWithAnsi } from "../../engine/tui.js";
+import { clioTheme, markdownTheme, screenTitle } from "../theme/index.js";
+
+const LABEL = "branch summary";
+const BODY_INDENT = "  ";
+
+const theme = clioTheme();
+const BRANCH_SUMMARY_THEME: MarkdownTheme = markdownTheme(theme);
+
+export interface RenderBranchSummaryOptions {
+	/** Override the default markdown theme. Falls back to the branch-summary theme above. */
+	theme?: MarkdownTheme;
+	/** Drop the `[branch summary]` header line. Useful when the label is drawn by the caller. */
+	hideLabel?: boolean;
+}
+
+/**
+ * One-line banner that announces a branch summary without the body. The
+ * replay path can use it as a placeholder when the full block is rendered
+ * lazily (future `Ctrl+O`-style expand).
+ */
+function renderBranchSummaryHeader(entry: BranchSummaryEntry, width: number): string[] {
+	const label = screenTitle(theme, `[${LABEL}]`);
+	const meta = theme.fg("dim", `from turn ${entry.fromTurnId}`);
+	return wrapTextWithAnsi(`${label} ${meta}`, width);
+}
+
+/**
+ * Render a BranchSummary entry as a framed, indented block the chat panel
+ * can splice into its transcript. Returns `[]` when the entry has no summary
+ * text so empty entries do not punch a blank block into the chat.
+ *
+ * Layout:
+ *   [branch summary] from turn <fromTurnId>
+ *     <markdown body line 1>
+ *     <markdown body line 2>
+ *     ...
+ *
+ * The leading label and the two-space body indent give the block a visible
+ * left edge without drawing box characters; box-drawing would collide with
+ * pi-tui's Markdown left pad and drift under wraps. `width` is the usable
+ * chat-pane width; the body is rendered at `width - BODY_INDENT.length` so
+ * the indent never forces a line past the pane edge.
+ */
+export function renderBranchSummaryEntry(
+	entry: BranchSummaryEntry,
+	width: number,
+	options: RenderBranchSummaryOptions = {},
+): string[] {
+	const summary = entry.summary.trim();
+	if (summary.length === 0) return [];
+
+	const out: string[] = [];
+	if (!options.hideLabel) {
+		out.push(...renderBranchSummaryHeader(entry, width));
+	}
+
+	const bodyWidth = Math.max(1, width - BODY_INDENT.length);
+	const theme = options.theme ?? BRANCH_SUMMARY_THEME;
+	const md = new Markdown(summary, 0, 0, theme);
+	for (const line of md.render(bodyWidth)) {
+		// Markdown right-pads each line to `bodyWidth` so background colors
+		// extend edge-to-edge. Trim the trailing pad before applying the
+		// indent so the visible width stays within the pane.
+		const trimmed = line.replace(/ +$/, "");
+		out.push(`${BODY_INDENT}${trimmed}`);
+	}
+	return out;
+}