@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/frame/src/render/streaming.ts

@@ -0,0 +1,223 @@
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+
+// While the model writes an edit or a write, these show the lines arriving, with a cursor.
+import { GLYPH, isObject, tildify } from "../kit/index.ts";
+import { getLanguageFromPath, highlightCode, type Theme } from "@earendil-works/pi-coding-agent";
+
+import { tabs } from "./format.ts";
+import { plainText } from "./safe.ts";
+
+export interface Stream {
+	lines: string[];
+	progress: string[];
+}
+
+interface StreamContext {
+	cwd: string;
+	expanded: boolean;
+	/** The cursor shows and the last key may be cut short. */
+	writing: boolean;
+	/** Keeps what was read from disk across renders of one call. */
+	state: { streamTarget?: Target };
+}
+
+type Streamer = (args: unknown, theme: Theme, context: StreamContext) => Stream | undefined;
+
+const WRITE_TAIL = 8;
+const EDIT_TAIL = 10;
+const CURSOR = GLYPH.cursor;
+/** Larger files are not read to count their lines. */
+const COUNT_LIMIT = 4 * 1024 * 1024;
+
+export const STREAMERS: Readonly<Record<string, Streamer>> = {
+	write: writeStream,
+	edit: editStream,
+};
+
+interface Target {
+	path: string;
+	lines?: number;
+	exists: boolean;
+}
+
+function writeStream(args: unknown, theme: Theme, context: StreamContext): Stream | undefined {
+	// The model may write the content before the path.
+	const content = field(args, "content");
+	if (content === undefined) return undefined;
+	const path = pathOf(args);
+
+	// A path still arriving may name another file on the way.
+	const target =
+		path !== undefined && pathSettled(args, context) ? targetOf(path, context) : undefined;
+	const note = target === undefined ? "" : `  ${theme.fg("muted", replaces(target))}`;
+	const lines = content.split("\n");
+	const shown = context.expanded ? lines : lines.slice(-WRITE_TAIL);
+	const first = lines.length - shown.length;
+	const gutter = String(lines.length).length;
+	const lang = path === undefined ? undefined : getLanguageFromPath(path);
+	const painted = lang
+		? highlightCode(shown.map(printable).join("\n"), lang)
+		: shown.map((line) => theme.fg("toolOutput", printable(line)));
+	const body = shown.map(
+		(_, index) =>
+			`${theme.fg("dim", String(first + index + 1).padStart(gutter))}  ${painted[index] ?? ""}`,
+	);
+	return {
+		lines: [
+			pathLine("write", path, theme) + note,
+			...above(first, gutter, theme),
+			...withCursor(body, theme, context.writing),
+		],
+		progress: [`${lines.length} line${lines.length === 1 ? "" : "s"}`, size(content)],
+	};
+}
+
+function editStream(args: unknown, theme: Theme, context: StreamContext): Stream | undefined {
+	const path = pathOf(args);
+	const edits = editsOf(args);
+	if (edits.length === 0) return undefined;
+
+	let removed = 0;
+	let added = 0;
+	const diff: string[] = [];
+	for (const [index, edit] of edits.entries()) {
+		if (index > 0) diff.push(theme.fg("dim", GLYPH.ellipsisAcross));
+		// Only the last edit can still be arriving.
+		const lines = editLines(edit, !context.writing || index < edits.length - 1);
+		for (const line of lines.before) diff.push(theme.fg("toolDiffContext", ` ${printable(line)}`));
+		for (const line of lines.out) diff.push(theme.fg("toolDiffRemoved", `-${printable(line)}`));
+		for (const line of lines.in) diff.push(theme.fg("toolDiffAdded", `+${printable(line)}`));
+		for (const line of lines.after) diff.push(theme.fg("toolDiffContext", ` ${printable(line)}`));
+		removed += lines.out.length;
+		added += lines.in.length;
+	}
+	const shown = context.expanded ? diff : diff.slice(-EDIT_TAIL);
+	const hidden = diff.length - shown.length;
+	return {
+		lines: [
+			pathLine("edit", path, theme),
+			...above(hidden, 0, theme),
+			...withCursor(shown, theme, context.writing),
+		],
+		progress: [...(edits.length > 1 ? [`edit ${edits.length}`] : []), `-${removed} +${added}`],
+	};
+}
+
+/** Lines both texts start and end with are context; a line not repeated yet counts as taken out. */
+export function editLines(
+	edit: PartialEdit,
+	complete: boolean,
+): { before: string[]; out: string[]; in: string[]; after: string[] } {
+	const old = edit.oldText?.split("\n") ?? [];
+	const next = edit.newText?.split("\n") ?? [];
+	// The last line of a text still arriving may be cut short.
+	const settled = complete ? next.length : next.length - 1;
+	let start = 0;
+	while (start < Math.min(old.length, settled) && old[start] === next[start]) start++;
+	let end = 0;
+	if (complete)
+		while (
+			end < Math.min(old.length, next.length) - start &&
+			old[old.length - 1 - end] === next[next.length - 1 - end]
+		)
+			end++;
+	return {
+		before: old.slice(0, start),
+		out: old.slice(start, old.length - end),
+		in: next.slice(start, next.length - end),
+		after: old.slice(old.length - end),
+	};
+}
+
+/** Pi's own renderer draws the same first line, so nothing moves when it takes over. */
+export function pathLine(tool: string, path: string | undefined, theme: Theme): string {
+	const title = theme.fg("toolTitle", theme.bold(tool));
+	if (path === undefined) return `${title} ${theme.fg("toolOutput", "...")}`;
+	return `${title} ${theme.fg("accent", printable(tildify(path)))}`;
+}
+
+/** A carriage return would cross the border, and escape codes would reach the terminal. */
+export function printable(line: string): string {
+	return tabs(plainText(line).replace(/\n/g, ""));
+}
+
+/** A key the model moved past is complete, and so is every key once the call is written. */
+function pathSettled(args: unknown, context: StreamContext): boolean {
+	if (!context.writing || !isObject(args)) return true;
+	const last = Object.keys(args).at(-1);
+	return last !== "path" && last !== "file_path";
+}
+
+function above(hidden: number, gutter: number, theme: Theme): string[] {
+	if (hidden <= 0) return [];
+	const lines = `${hidden} line${hidden === 1 ? "" : "s"} above`;
+	return [
+		`${" ".repeat(Math.max(0, gutter - 1))}${theme.fg("dim", GLYPH.ellipsisUp)}  ${theme.fg("muted", lines)}`,
+	];
+}
+
+function withCursor(lines: readonly string[], theme: Theme, writing: boolean): string[] {
+	if (!writing || lines.length === 0) return [...lines];
+	return [...lines.slice(0, -1), `${lines.at(-1)}${theme.fg("accent", CURSOR)}`];
+}
+
+function replaces(target: Target): string {
+	if (!target.exists) return "new file";
+	if (target.lines === undefined) return "replaces a file";
+	return `replaces ${target.lines} line${target.lines === 1 ? "" : "s"}`;
+}
+
+/** Once per call, when the path is complete. */
+function targetOf(path: string, context: StreamContext): Target {
+	const known = context.state.streamTarget;
+	if (known?.path === path) return known;
+	const full = resolve(context.cwd, path);
+	let target: Target = { path, exists: false };
+	try {
+		const info = statSync(full);
+		target = { path, exists: true };
+		if (info.isFile() && info.size <= COUNT_LIMIT) {
+			const text = readFileSync(full, "utf8");
+			target.lines = text === "" ? 0 : text.replace(/\n$/, "").split("\n").length;
+		}
+	} catch (error) {
+		// Missing is a new file; unreadable is still a file.
+		target = { path, exists: (error as NodeJS.ErrnoException).code !== "ENOENT" };
+	}
+	context.state.streamTarget = target;
+	return target;
+}
+
+function size(text: string): string {
+	const bytes = Buffer.byteLength(text);
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+
+function pathOf(args: unknown): string | undefined {
+	const path = field(args, "path") ?? field(args, "file_path");
+	return path === "" ? undefined : path;
+}
+
+function field(args: unknown, key: string): string | undefined {
+	const value = isObject(args) ? args[key] : undefined;
+	return typeof value === "string" ? value : undefined;
+}
+
+export interface PartialEdit {
+	oldText?: string;
+	newText?: string;
+}
+
+function editsOf(args: unknown): PartialEdit[] {
+	if (!isObject(args)) return [];
+	const { edits } = args;
+	const list = Array.isArray(edits) ? edits : [args];
+	return list.flatMap((edit) => {
+		const oldText = field(edit, "oldText");
+		const newText = field(edit, "newText");
+		return oldText === undefined && newText === undefined ? [] : [{ oldText, newText }];
+	});
+}

package/packages/frame/src/render/timing.ts

@@ -0,0 +1,106 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+import type { Timing } from "../data/telemetry.ts";
+import { latency, rate } from "./format.ts";
+
+/** From here on, a pause while writing is worth pointing out. */
+export const STALL_MS = 2_000;
+
+export function clockTime(at: number): string {
+	const date = new Date(at);
+	const two = (value: number) => String(value).padStart(2, "0");
+	const ms = String(date.getMilliseconds()).padStart(3, "0");
+	return `${two(date.getHours())}:${two(date.getMinutes())}:${two(date.getSeconds())}.${ms}`;
+}
+
+/** To the millisecond, as `812ms`, `4.218s` or `1m 04.218s`. */
+export function exactly(ms: number): string {
+	const whole = Math.round(ms);
+	if (whole < 1000) return `${whole}ms`;
+	if (whole < 60_000) return `${(whole / 1000).toFixed(3)}s`;
+	const seconds = ((whole % 60_000) / 1000).toFixed(3).padStart(6, "0");
+	return `${Math.floor(whole / 60_000)}m ${seconds}s`;
+}
+
+export interface AnsweredMessage {
+	timestamp: number;
+	stopReason?: string;
+	model?: string;
+}
+
+/** Each with its rank: the highest goes first when the line runs out of room. */
+type Part = [text: string, drop: number];
+
+function speedOf(timing: Timing): string | undefined {
+	const writing = timing.writingMs - timing.stallMs;
+	if (writing <= 0 || timing.output === 0) return undefined;
+	const speed = rate((timing.output / writing) * 1000);
+	return `${timing.estimated ? "~" : ""}${speed} tok/s`;
+}
+
+function partsOf(timing: Timing | undefined, message: AnsweredMessage): Part[] {
+	// A session from before this was recorded, or another session's: only the clock is known.
+	if (timing === undefined) return [[clockTime(message.timestamp), 0]];
+	const clock: Part = [clockTime(timing.at), 0];
+	const ttft: Part[] = timing.waitMs === undefined ? [] : [[`ttft ${latency(timing.waitMs)}`, 2]];
+	const stall: Part[] = timing.stallMs >= STALL_MS ? [[`stall ${latency(timing.stallMs)}`, 3]] : [];
+	const speed = speedOf(timing);
+	const rated: Part[] = speed === undefined ? [] : [[speed, 4]];
+
+	if (timing.streaming) {
+		if (timing.waitMs === undefined) return [clock, [`waiting ${latency(timing.waitingMs)}`, 0]];
+		return [clock, ...ttft, [`writing ${latency(timing.writingMs)}`, 0], ...stall, ...rated];
+	}
+	if (message.stopReason === "aborted") return [clock, ...ttft, [`stopped at ${latency(timing.totalMs)}`, 0]];
+	if (message.stopReason === "error") return [clock, ...ttft, [`failed at ${latency(timing.totalMs)}`, 0]];
+	return [
+		clock,
+		...ttft,
+		...(timing.serverMs === undefined ? [] : ([[`server ${latency(timing.serverMs)}`, 6]] as Part[])),
+		...(timing.thoughtMs === undefined ? [] : ([[`thought ${latency(timing.thoughtMs)}`, 5]] as Part[])),
+		[`total ${exactly(timing.totalMs)}`, 0],
+		...stall,
+		...rated,
+	];
+}
+
+/** Without the provider's path, as `kimi-k2.6` for `@cf/moonshotai/kimi-k2.6`. */
+function modelPart(message: AnsweredMessage): Part[] {
+	const name = message.model?.split("/").at(-1);
+	return name ? [[name, 1]] : [];
+}
+
+interface Settled {
+	key: string;
+	line: string;
+}
+
+/** A finished call's line can't change, and every one of them is asked for on every redraw. */
+const settled = new WeakMap<AnsweredMessage, Settled>();
+
+/** What's known of a call to the model, as much of it as fits. */
+export function timingLine(
+	timing: Timing | undefined,
+	message: AnsweredMessage,
+	width: number,
+): string {
+	if (timing?.streaming === true) return buildLine(timing, message, width);
+	const key = `${width}|${timing?.at}|${timing?.totalMs}|${timing?.output}|${message.stopReason}|${message.model}`;
+	const known = settled.get(message);
+	if (known?.key === key) return known.line;
+	const line = buildLine(timing, message, width);
+	settled.set(message, { key, line });
+	return line;
+}
+
+function buildLine(timing: Timing | undefined, message: AnsweredMessage, width: number): string {
+	const [clock, ...rest] = partsOf(timing, message) as [Part, ...Part[]];
+	let parts: Part[] = [clock, ...modelPart(message), ...rest];
+	const text = () => parts.map(([part]) => part).join("  ");
+	while (visibleWidth(text()) > width) {
+		const highest = Math.max(...parts.map(([, drop]) => drop));
+		if (highest === 0) break;
+		parts = parts.filter(([, drop]) => drop !== highest);
+	}
+	return text();
+}

package/packages/frame/src/render/tools.ts

@@ -0,0 +1,167 @@
+// The mark follows the icon set in the look's settings.
+import { GLYPH, SPIN } from "../kit/index.ts";
+
+import type { IconSet } from "./glyphs.ts";
+
+type ToolKind =
+	| "shell"
+	| "read"
+	| "search"
+	| "edit"
+	| "web"
+	| "agent"
+	| "ask"
+	| "peers"
+	| "memory"
+	| "mcp"
+	| "other";
+
+const ICONS: Record<IconSet, Record<ToolKind, string>> = {
+	nerd: {
+		shell: "\u{f120}", // nf-fa-terminal
+		read: "\u{f15c}", // nf-fa-file_lines
+		search: "\u{f002}", // nf-fa-search
+		edit: "\u{f044}", // nf-fa-pencil
+		web: "\u{f0ac}", // nf-fa-globe
+		agent: "\u{f06a9}", // nf-md-robot
+		ask: "\u{f059}", // nf-fa-circle_question
+		peers: "\u{f0c0}", // nf-fa-users
+		memory: "\u{f09d1}", // nf-md-brain
+		mcp: "\u{f1e6}", // nf-fa-plug
+		other: "\u{f013}", // nf-fa-gear
+	},
+	unicode: {
+		shell: GLYPH.pointer,
+		read: "\u25a4",
+		search: GLYPH.search,
+		edit: GLYPH.pencil,
+		web: "\u25cd",
+		agent: GLYPH.diamond,
+		ask: "?",
+		peers: "\u2042",
+		memory: GLYPH.diamondEmpty,
+		mcp: "\u226b",
+		other: GLYPH.ring,
+	},
+	ascii: {
+		shell: "$",
+		read: "=",
+		search: "/",
+		edit: "+",
+		web: "@",
+		agent: "*",
+		ask: "?",
+		peers: "&",
+		memory: "#",
+		mcp: ">",
+		other: "-",
+	},
+};
+
+export type CallPhase = "writing" | "waiting" | "running" | "done" | "failed";
+
+const MARKS: Record<IconSet, Record<CallPhase, string>> = {
+	nerd: {
+		writing: "\u{f044}", // nf-fa-pencil
+		waiting: "\u{f252}", // nf-fa-hourglass_half
+		running: "\u{f017}", // nf-fa-clock_o
+		done: "\u{f00c}", // nf-fa-check
+		failed: "\u{f00d}", // nf-fa-times
+	},
+	unicode: {
+		writing: GLYPH.pencil,
+		waiting: "\u29d6",
+		running: "\u25f7",
+		done: GLYPH.check,
+		failed: GLYPH.cross,
+	},
+	ascii: { writing: "~", waiting: ":", running: "...", done: "ok", failed: "!" },
+};
+
+interface Motion {
+	frames: readonly string[];
+	stepMs: number;
+}
+
+/** A clock outline for every hour, from twelve round to eleven. */
+const CLOCK = [0xf1456, ...Array.from({ length: 11 }, (_, hour) => 0xf144b + hour)].map((code) =>
+	String.fromCodePoint(code),
+);
+
+const MOTIONS: Record<IconSet, Partial<Record<CallPhase, Motion>>> = {
+	nerd: {
+		// The same spinner as an agent writing, in every font a Nerd Font is built on.
+		writing: { frames: SPIN.braille, stepMs: 100 },
+		waiting: { frames: ["\u{f251}", "\u{f252}", "\u{f253}"], stepMs: 400 }, // nf-fa-hourglass_start..end
+		running: { frames: CLOCK, stepMs: 110 }, // nf-md-clock_time_*_outline
+	},
+	unicode: {
+		writing: { frames: SPIN.braille, stepMs: 100 },
+		waiting: { frames: SPIN.hourglass, stepMs: 500 },
+		running: { frames: SPIN.quadrants, stepMs: 150 },
+	},
+	ascii: {
+		running: { frames: SPIN.ascii, stepMs: 150 },
+	},
+};
+
+/** A phase that lasts moves, so a call still going looks alive. */
+export function stateMark(phase: CallPhase, set: IconSet, now: number = Date.now()): string {
+	const motion = MOTIONS[set][phase];
+	if (motion === undefined) return MARKS[set][phase];
+	return motion.frames[Math.floor(now / motion.stepMs) % motion.frames.length] ?? MARKS[set][phase];
+}
+
+export function toolIcon(toolName: string, set: IconSet): string {
+	return ICONS[set][toolKind(toolName)];
+}
+
+/** An MCP tool says its server rather than `mcp__server__tool`. */
+export function toolLabel(toolName: string): string {
+	const mcp = toolName.match(/^mcp__([^_]+)__(.+)$/u);
+	return mcp === null ? toolName : `${mcp[1]}:${mcp[2]}`;
+}
+
+function toolKind(toolName: string): ToolKind {
+	if (toolName.startsWith("mcp__")) return "mcp";
+	if (toolName.startsWith("memory_")) return "memory";
+	switch (toolName) {
+		case "bash":
+		case "powershell":
+		case "shell":
+			return "shell";
+		case "read":
+		case "ls":
+		case "find":
+			return "read";
+		case "grep":
+		case "glob":
+		case "tool_search":
+			return "search";
+		case "edit":
+		case "write":
+		case "apply_patch":
+			return "edit";
+		case "web_search":
+		case "fetch":
+		case "webfetch":
+		case "web_fetch":
+		case "fetch_content":
+		case "get_search_content":
+		case "source_check":
+			return "web";
+		case "task":
+		case "agent":
+		case "subagent":
+		case "bg_wait":
+			return "agent";
+		case "ask_questions":
+			return "ask";
+		case "peers":
+			return "peers";
+		case "scratchpad":
+			return "memory";
+		default:
+			return "other";
+	}
+}

package/packages/frame/src/settings.ts

@@ -0,0 +1,105 @@
+import { boolean, literal, setting } from "./kit/index.ts";
+
+import type { FrameStyle } from "./render/frame.ts";
+import type { IconMode } from "./render/glyphs.ts";
+import type { SegmentId } from "./render/segments.ts";
+import { framePreview, iconsPreview, userFramePreview } from "./ui/previews.ts";
+import type { SlotName } from "./ui/screen.ts";
+
+// Only what depends on the terminal or taste is a setting: icons, line style, framed messages.
+
+export const SECTIONS = ["Appearance"];
+
+export type HeaderStyle = "card" | "compact";
+export type CursorStyle = "block" | "bar" | "underline";
+
+const PERMISSION_MODE: SegmentId = "status:pi-ask-permission:mode";
+
+/** The line above the editor: how long the agent has worked, and the last call that finished. */
+export const strip: readonly SegmentId[] = ["elapsed"];
+/** The other side of that line, or a line of its own under it when it does not fit. */
+export const stripRight: readonly SegmentId[] = ["board", "peers"];
+/** After the working spinner on the editor's top edge. */
+export const topLeft: readonly SegmentId[] = ["me", "branch", "session"];
+/** Where you are. */
+export const topRight: readonly SegmentId[] = ["path", "host"];
+/** How what you type is handled, and who does the work. */
+export const bottomLeft: readonly SegmentId[] = [PERMISSION_MODE, "model", "effort"];
+/** How full the context is. */
+export const bottomRight: readonly SegmentId[] = ["context"];
+/** What other packages report, the mode first, then the session: cost, tokens, cache, speeds. */
+export const below: readonly SegmentId[] = ["statuses", "cost", "tokens", "cache", "average"];
+/** The plan's quota: what each window spent, and when it resets. */
+export const belowRight: readonly SegmentId[] = ["quota"];
+
+/** The docs fixture draws with the same map. */
+export const SLOTS: Record<SlotName, readonly SegmentId[]> = {
+	strip,
+	stripRight,
+	topLeft,
+	topRight,
+	bottomLeft,
+	bottomRight,
+	below,
+	belowRight,
+};
+
+export const SEPARATOR = "  ";
+export const cursor: CursorStyle = "bar";
+export const header: HeaderStyle = "card";
+export const pathLength = 40;
+export const gaugeCells = 8;
+export const labels = true;
+
+export const icons = setting<IconMode>({
+	id: "frame.icons",
+	default: "auto",
+	decoder: literal("auto", "nerd", "unicode", "ascii"),
+	ui: {
+		section: "Appearance",
+		label: "Icons",
+		description: "Auto uses plain Unicode, or ASCII without UTF-8. Pick Nerd if your terminal uses a Nerd Font.",
+		preview: iconsPreview,
+	},
+});
+
+export const frame = setting<FrameStyle | "off">({
+	id: "frame.style",
+	default: "rounded",
+	decoder: literal("rounded", "square", "heavy", "line", "off"),
+	project: true,
+	ui: {
+		section: "Appearance",
+		label: "Editor frame",
+		description:
+			"The lines of the box around the editor. `line` keeps pi's two rules, `off` leaves the editor alone and moves what sits on its edges to the footer.",
+		preview: framePreview,
+	},
+});
+
+export const userFrame = setting({
+	id: "frame.userFrame",
+	default: true,
+	decoder: boolean,
+	ui: {
+		section: "Appearance",
+		label: "Your messages",
+		description:
+			"Your messages in a frame like the tool calls', named you, with no blank row above and below the text. Off keeps pi's block.",
+		preview: userFramePreview,
+	},
+});
+
+export const timing = setting({
+	id: "frame.timing",
+	default: true,
+	decoder: boolean,
+	ui: {
+		section: "Appearance",
+		label: "Timings",
+		description:
+			"A line under each response and on each tool box: when it started, to the millisecond, and how long it took.",
+	},
+});
+
+export const FRAME_SETTINGS = [icons, frame, userFrame, timing];