@huseynsnmz/pi-suite 0.1.0 → 0.2.0

package/packages/frame/src/kit/decode.ts

@@ -0,0 +1,210 @@
+// Decoders for everything from outside. No decoder throws, and only this module inspects `typeof`.
+import type { Control } from "./control.ts";
+
+export interface Problem {
+	path: string;
+	message: string;
+}
+
+export type Decoded<T> =
+	| { ok: true; value: T; problems: Problem[] }
+	| { ok: false; problems: Problem[] };
+
+export interface Decoder<T> {
+	decode(input: unknown, path: string): Decoded<T>;
+	control?: Control;
+}
+
+export function pass<T>(value: T, problems: Problem[] = []): Decoded<T> {
+	return { ok: true, value, problems };
+}
+
+export function fail<T>(entry: Problem): Decoded<T> {
+	return { ok: false, problems: [entry] };
+}
+
+export function problem(path: string, message: string): Problem {
+	return { path, message };
+}
+
+export function fieldPath(path: string, key: string): string {
+	return path === "" ? key : `${path}.${key}`;
+}
+
+export function formatProblems(problems: Problem[]): string[] {
+	return problems.map((entry) => `${entry.path}: ${entry.message}`);
+}
+
+export function isObject(input: unknown): input is Record<string, unknown> {
+	return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+
+export const string: Decoder<string> = {
+	control: { type: "text" },
+	decode(input, path) {
+		return typeof input === "string" ? pass(input) : fail(problem(path, "expected a string"));
+	},
+};
+
+export const trimmedString: Decoder<string> = {
+	control: { type: "text" },
+	decode(input, path) {
+		if (typeof input !== "string" || input.trim() === "")
+			return fail(problem(path, "expected a non-empty string"));
+		return pass(input.trim());
+	},
+};
+
+export const boolean: Decoder<boolean> = {
+	control: { type: "toggle" },
+	decode(input, path) {
+		return typeof input === "boolean" ? pass(input) : fail(problem(path, "expected a boolean"));
+	},
+};
+
+export const unit: Decoder<number> = {
+	control: { type: "number", min: 0, max: 1, step: 0.05 },
+	decode(input, path) {
+		if (typeof input !== "number" || !Number.isFinite(input) || input < 0 || input > 1)
+			return fail(problem(path, "expected a number from 0 to 1"));
+		return pass(input);
+	},
+};
+
+export const duration: Decoder<number> = {
+	control: { type: "number", min: 0, step: 500, unit: "ms" },
+	decode(input, path) {
+		if (typeof input !== "number" || !Number.isFinite(input) || input < 0)
+			return fail(problem(path, "expected a non-negative number of milliseconds"));
+		return pass(input);
+	},
+};
+
+export function integer(min: number, max: number): Decoder<number> {
+	return {
+		control: { type: "number", min, max, step: 1 },
+		decode(input, path) {
+			if (typeof input !== "number" || !Number.isInteger(input) || input < min || input > max) {
+				return fail(problem(path, `expected a whole number from ${min} to ${max}`));
+			}
+			return pass(input);
+		},
+	};
+}
+
+/** `expected` is how the value is described to the user. */
+export function matching(pattern: RegExp, expected: string): Decoder<string> {
+	return {
+		control: { type: "text" },
+		decode(input, path) {
+			if (typeof input === "string" && pattern.test(input)) return pass(input);
+			return fail(problem(path, `expected ${expected}`));
+		},
+	};
+}
+
+export function literal<const T extends readonly string[]>(...values: T): Decoder<T[number]> {
+	const expected = values.map((value) => `"${value}"`).join(" or ");
+	return {
+		control: { type: "choice", options: values.map((value) => ({ value })) },
+		decode(input, path) {
+			if (typeof input === "string" && (values as readonly string[]).includes(input))
+				return pass(input as T[number]);
+			return fail(problem(path, `expected ${expected}`));
+		},
+	};
+}
+
+export function nullable<T>(inner: Decoder<T>): Decoder<T | null> {
+	const control: Control | undefined =
+		inner.control?.type === "number" ? { ...inner.control, nullable: true } : inner.control;
+	return {
+		control,
+		decode(input, path) {
+			return input === null ? pass(null) : inner.decode(input, path);
+		},
+	};
+}
+
+export function withDefaultOf<T>(inner: Decoder<T>, fallback: () => T): Decoder<T> {
+	return {
+		control: inner.control,
+		decode(input, path) {
+			if (input === undefined) return pass(fallback());
+			const result = inner.decode(input, path);
+			return result.ok ? result : pass(fallback(), result.problems);
+		},
+	};
+}
+
+export function withDefault<T>(inner: Decoder<T>, fallback: T): Decoder<T> {
+	return withDefaultOf(inner, () => fallback);
+}
+
+export function stringList(expected: string): Decoder<string[]> {
+	const notAList = `expected an array of ${expected}`;
+	const dropped = "ignored entries that are not non-empty strings";
+
+	return {
+		control: { type: "list" },
+		decode(input, path) {
+			if (!Array.isArray(input)) return fail(problem(path, notAList));
+
+			const value: string[] = [];
+			let missing = 0;
+			for (const entry of input) {
+				if (typeof entry === "string" && entry !== "") value.push(entry);
+				else missing++;
+			}
+
+			const problems = missing > 0 ? [problem(path, dropped)] : [];
+			return pass(value, problems);
+		},
+	};
+}
+
+export function stringListOrEmpty(
+	fallback: readonly string[],
+	expected: string,
+): Decoder<string[]> {
+	const parse = stringList(expected);
+	return {
+		control: parse.control,
+		decode(input, path) {
+			if (input === undefined) return pass([...fallback]);
+			const result = parse.decode(input, path);
+			return result.ok ? result : pass([], result.problems);
+		},
+	};
+}
+
+export function guarded<T>(test: (input: unknown) => input is T, expected: string): Decoder<T> {
+	return {
+		decode(input, path) {
+			return test(input) ? pass(input) : fail(problem(path, `expected ${expected}`));
+		},
+	};
+}
+
+export function object<T extends Record<string, unknown>>(shape: {
+	[K in keyof T]: Decoder<T[K]>;
+}): Decoder<T> {
+	return {
+		decode(input, path) {
+			if (!isObject(input)) return fail(problem(path, "expected an object"));
+
+			const problems: Problem[] = [];
+			const value = {} as T;
+			let complete = true;
+
+			for (const key of Object.keys(shape) as (keyof T & string)[]) {
+				const result = shape[key].decode(input[key], fieldPath(path, key));
+				problems.push(...result.problems);
+				if (result.ok) value[key] = result.value;
+				else complete = false;
+			}
+
+			return complete ? pass(value, problems) : { ok: false, problems };
+		},
+	};
+}

package/packages/frame/src/kit/events/log.ts

@@ -0,0 +1,313 @@
+// One log per session, followed live by other sessions and replayed later. Only the session writes
+// its file and the extensions share one thread, so lines never interleave.
+import {
+	appendFileSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readSync,
+	openSync,
+	closeSync,
+	fstatSync,
+	rmSync,
+	statSync,
+	watch,
+} from "node:fs";
+import { join } from "node:path";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import type { LogEventMap } from "../contracts/events.ts";
+import { isObject } from "../decode.ts";
+
+export const EVENTS_VERSION = 1;
+/** Every event is also published here, inside the process. */
+export const LOGGED_EVENT = "harness:logged";
+
+export type EventType = keyof LogEventMap;
+
+export interface LoggedEvent<K extends EventType = EventType> {
+	v: typeof EVENTS_VERSION;
+	id: string;
+	/** Milliseconds since the epoch. */
+	at: number;
+	session: string;
+	type: K;
+	data: LogEventMap[K];
+	/** So a viewer can open that point of the conversation. */
+	entry?: string;
+}
+
+export interface LogTarget {
+	dir: string;
+	session: string;
+}
+
+interface Bus {
+	emit(channel: string, data: unknown): void;
+}
+
+export interface LogSession {
+	getCwd(): string;
+	getSessionId(): string;
+}
+
+/** Lets tests and tools move every log. */
+export function eventsRoot(): string {
+	return process.env.PI_HARNESS_EVENTS ?? join(getAgentDir(), "harness", "events");
+}
+
+export function eventsDir(cwd: string, root = eventsRoot()): string {
+	return join(root, `--${cwd.replace(/^[/\\]+/, "").replace(/[/\\:]+/g, "-")}--`);
+}
+
+/** A folder's directory starts with `--`, so a room never takes its name. */
+export function roomsDir(root = eventsRoot()): string {
+	return join(root, "rooms");
+}
+
+export function roomDir(id: string, root = eventsRoot()): string {
+	return join(roomsDir(root), id);
+}
+
+/** One small file per open session, so finding them reads no logs. */
+export function liveDir(root = eventsRoot()): string {
+	return join(root, "live");
+}
+
+export function targetOf(session: LogSession, root?: string): LogTarget {
+	return { dir: eventsDir(session.getCwd(), root), session: session.getSessionId() };
+}
+
+export function logPath(target: LogTarget): string {
+	return join(target.dir, `${target.session}.jsonl`);
+}
+
+let counter = 0;
+
+export function logEvent<K extends EventType>(
+	target: LogTarget,
+	bus: Bus | undefined,
+	type: K,
+	data: LogEventMap[K],
+	entry?: string,
+	at = Date.now(),
+): LoggedEvent<K> {
+	counter = (counter + 1) % 1_296;
+	const event: LoggedEvent<K> = {
+		v: EVENTS_VERSION,
+		id: `${at.toString(36)}${counter.toString(36).padStart(2, "0")}${Math.random().toString(36).slice(2, 6)}`,
+		at,
+		session: target.session,
+		type,
+		data,
+		...(entry === undefined ? {} : { entry }),
+	};
+	try {
+		mkdirSync(target.dir, { recursive: true });
+		appendFileSync(logPath(target), `${JSON.stringify(event)}\n`);
+	} catch {
+		// A log that cannot be written must never stop the session.
+	}
+	bus?.emit(LOGGED_EVENT, event);
+	return event;
+}
+
+/** A context with no session behind it logs nothing. */
+export function logFrom<K extends EventType>(
+	ctx: { sessionManager: Partial<LogSession> },
+	bus: Bus | undefined,
+	type: K,
+	data: LogEventMap[K],
+	entry?: string,
+): LoggedEvent<K> | undefined {
+	const { getCwd, getSessionId } = ctx.sessionManager;
+	if (getCwd === undefined || getSessionId === undefined) return undefined;
+	return logEvent(targetOf(ctx.sessionManager as LogSession), bus, type, data, entry);
+}
+
+export { HOST } from "../host.ts";
+
+/** Which event types a reader folds; the others are skipped before they are parsed. */
+export type Wanted = (type: string) => boolean;
+
+/**
+ * The events written after `offset`; a line still being written waits for the next read. Lines are
+ * found and their types read in the bytes, so a line the reader does not want is never decoded.
+ */
+export function readFrom(
+	path: string,
+	offset: number,
+	wanted?: Wanted,
+): { events: LoggedEvent[]; offset: number } {
+	let fd: number;
+	try {
+		fd = openSync(path, "r");
+	} catch {
+		return { events: [], offset };
+	}
+	try {
+		const size = fstatSync(fd).size;
+		if (size <= offset) return { events: [], offset: size < offset ? 0 : offset };
+		const buffer = Buffer.allocUnsafe(size - offset);
+		readSync(fd, buffer, 0, buffer.length, offset);
+		const end = buffer.lastIndexOf(NEWLINE);
+		if (end === -1) return { events: [], offset };
+		const events: LoggedEvent[] = [];
+		for (let start = 0; start < end;) {
+			const stop = buffer.indexOf(NEWLINE, start);
+			if (wanted === undefined || wanted(typeIn(buffer, start, stop)))
+				events.push(...parsed(buffer.toString("utf8", start, stop)));
+			start = stop + 1;
+		}
+		return { events, offset: offset + end + 1 };
+	} finally {
+		closeSync(fd);
+	}
+}
+
+const NEWLINE = 0x0a;
+const QUOTE = 0x22;
+const TYPE_BYTES = Buffer.from('"type":"');
+
+/** `logEvent` writes `type` before `data`, so the first `"type":"` in a line is the event's. */
+function typeIn(buffer: Buffer, start: number, stop: number): string {
+	const line = buffer.subarray(start, stop);
+	const at = line.indexOf(TYPE_BYTES);
+	if (at === -1) return "";
+	const from = at + TYPE_BYTES.length;
+	const close = line.indexOf(QUOTE, from);
+	return close === -1 ? "" : line.toString("latin1", from, close);
+}
+
+export const KEEP_LOGS_MS = 7 * 24 * 60 * 60_000;
+
+/** Deletes the logs of sessions that are not open and have written nothing for `KEEP_LOGS_MS`. */
+export function pruneLogs(dir: string, root = eventsRoot(), now = Date.now()): void {
+	let names: string[];
+	try {
+		names = readdirSync(dir);
+	} catch {
+		return;
+	}
+	for (const name of names) {
+		if (!name.endsWith(".jsonl")) continue;
+		if (existsSync(join(liveDir(root), `${name.slice(0, -".jsonl".length)}.json`))) continue;
+		const path = join(dir, name);
+		const written = statSync(path, { throwIfNoEntry: false })?.mtimeMs ?? now;
+		if (now - written > KEEP_LOGS_MS) rmSync(path, { force: true });
+	}
+}
+
+export function readTail(path: string, bytes = TAIL_BYTES): LoggedEvent[] {
+	let fd: number;
+	try {
+		fd = openSync(path, "r");
+	} catch {
+		return [];
+	}
+	try {
+		const size = fstatSync(fd).size;
+		const from = Math.max(0, size - bytes);
+		const buffer = Buffer.alloc(size - from);
+		if (buffer.length === 0) return [];
+		readSync(fd, buffer, 0, buffer.length, from);
+		const text = buffer.toString("utf8");
+		// The first line of a tail is usually cut in half, and half an event is not one.
+		const whole = from === 0 ? text : text.slice(text.indexOf("\n") + 1);
+		const end = whole.lastIndexOf("\n");
+		if (end === -1) return [];
+		return whole
+			.slice(0, end)
+			.split("\n")
+			.flatMap((line) => parsed(line));
+	} finally {
+		closeSync(fd);
+	}
+}
+
+/** Enough for the last commands of a long session. */
+const TAIL_BYTES = 512 * 1024;
+
+/** Checks the shape, since any version may have written the line. */
+function isLoggedEvent(value: unknown): value is LoggedEvent {
+	return (
+		isObject(value) &&
+		value.v === EVENTS_VERSION &&
+		typeof value.id === "string" &&
+		typeof value.type === "string" &&
+		typeof value.session === "string" &&
+		typeof value.at === "number" &&
+		isObject(value.data) &&
+		(value.entry === undefined || typeof value.entry === "string")
+	);
+}
+
+function parsed(line: string): LoggedEvent[] {
+	try {
+		const value: unknown = JSON.parse(line);
+		// A line without its `data` is not an event, and would hand `undefined` to whatever folds it.
+		if (!isLoggedEvent(value)) return [];
+		return [value];
+	} catch {
+		return [];
+	}
+}
+
+/** Reads from where it was left: new events, oldest first. */
+export class FolderFeed {
+	readonly #dir: string;
+	readonly #wanted: Wanted | undefined;
+	readonly #offsets = new Map<string, number>();
+
+	constructor(dir: string, wanted?: Wanted) {
+		this.#dir = dir;
+		this.#wanted = wanted;
+	}
+
+	get dir(): string {
+		return this.#dir;
+	}
+
+	read(): LoggedEvent[] {
+		let files: string[];
+		try {
+			files = readdirSync(this.#dir).filter((name) => name.endsWith(".jsonl"));
+		} catch {
+			return [];
+		}
+		const fresh: LoggedEvent[] = [];
+		for (const name of files) {
+			const path = join(this.#dir, name);
+			const { events, offset } = readFrom(path, this.#offsets.get(path) ?? 0, this.#wanted);
+			this.#offsets.set(path, offset);
+			// Not a spread: a big log overflows the stack.
+			for (const event of events) fresh.push(event);
+		}
+		return fresh.toSorted((a, b) => a.at - b.at || a.id.localeCompare(b.id));
+	}
+
+	/** Polls every second where the folder cannot be watched. */
+	watch(changed: () => void): () => void {
+		mkdirSync(this.#dir, { recursive: true });
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const soon = () => {
+			if (timer !== undefined) return;
+			timer = setTimeout(() => {
+				timer = undefined;
+				changed();
+			}, 30);
+		};
+		try {
+			const watcher = watch(this.#dir, soon);
+			watcher.on("error", () => {});
+			return () => {
+				watcher.close();
+				if (timer !== undefined) clearTimeout(timer);
+			};
+		} catch {
+			const poll = setInterval(changed, 1_000);
+			return () => clearInterval(poll);
+		}
+	}
+}

package/packages/frame/src/kit/format.ts

@@ -0,0 +1,25 @@
+// How numbers read on screen, the same in every package.
+
+export function formatTokens(count: number): string {
+	const n = Math.max(0, Math.round(count));
+	if (n < 1000) return String(n);
+	if (n < 10_000) return `${trim((n / 1000).toFixed(1))}k`;
+	if (n < 1_000_000) return `${Math.round(n / 1000)}k`;
+	if (n < 10_000_000) return `${trim((n / 1_000_000).toFixed(1))}M`;
+	return `${Math.round(n / 1_000_000)}M`;
+}
+
+/** A price: cents are worth showing under $10, and noise above it. */
+export function formatCost(amount: number): string {
+	if (amount === 0) return "$0.00";
+	return amount < 10 ? `$${amount.toFixed(3)}` : `$${amount.toFixed(2)}`;
+}
+
+function trim(fixed: string): string {
+	return fixed.endsWith(".0") ? fixed.slice(0, -2) : fixed;
+}
+
+export function formatClock(at: number): string {
+	const date = new Date(at);
+	return `${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
+}

package/packages/frame/src/kit/host.ts

@@ -0,0 +1,4 @@
+// This machine as presence entries, log lines and `by` name it.
+import { hostname } from "node:os";
+
+export const HOST = hostname();

package/packages/frame/src/kit/index.ts

@@ -0,0 +1,25 @@
+// The part of @adeildo/pi-kit 6.0.0 that frame uses. See LICENSE.
+export { createApp } from "./app/builder.ts";
+export { defineFeature, type FeatureScope } from "./app/feature.ts";
+export { messageRendererFor, resolveToolRenderers } from "./app/renderers.ts";
+export { type Board, type BoardCard, type BoardOp, emptyBoard, foldBoard } from "./board/model.ts";
+export { ACCOUNT, type AccountState, type AccountWindow } from "./contracts/accounts.ts";
+export { BOARD } from "./contracts/board.ts";
+export { type CallRuling, CALLS_FRAMED, callTarget, RULING, type RulingTone } from "./contracts/calls.ts";
+export { NAMES } from "./contracts/names.ts";
+export { type PeerMark, PEERS, type RoomMark, type WritingMark } from "./contracts/peers.ts";
+export { PROMPT_FROM } from "./contracts/prompts.ts";
+export { drawSkillRefs, SKILL_REF, skillNames, skillQueryAt } from "./contracts/skills.ts";
+export { type SessionSource, type SessionSummary, type SourceItem } from "./contracts/sources.ts";
+export { provideViews } from "./contracts/views.ts";
+export { type Json } from "./control.ts";
+export { boolean, isObject, literal } from "./decode.ts";
+export { formatClock, formatCost, formatTokens } from "./format.ts";
+export { hideImagesUnderOverlays } from "./overlay-images.ts";
+export { tildify } from "./paths.ts";
+export { setting } from "./settings/setting.ts";
+export { sourceFor } from "./sources/file.ts";
+export { emptyTotals, promptOf, tokensOf, type Totals, totalsOf, type UsageLike, usageTotals } from "./totals.ts";
+export { CHANGES_CUT, CHANGES_X, drawnByWidth, type EntryFrame, entryFrame } from "./ui/entry.ts";
+export { frame, FRAME_Y, frameInner, type KeyHint } from "./ui/frame.ts";
+export { CUT, GLYPH, LINE, SPIN } from "./ui/glyphs.ts";

package/packages/frame/src/kit/legacy-tasks.ts

@@ -0,0 +1,39 @@
+// Entries of the removed tasks feature: their model calls still count toward cost, and their handle
+// names old sessions.
+import { isObject } from "./decode.ts";
+
+const TASKS_UPDATE = "pi-tasks:update";
+const TASKS_USAGE = "pi-tasks:usage";
+/** The same two, from the package's first name. */
+const GOAL_UPDATE = "pi-goal:update";
+const GOAL_USAGE = "pi-goal:usage";
+
+const PAID: ReadonlySet<string> = new Set([TASKS_UPDATE, TASKS_USAGE, GOAL_UPDATE, GOAL_USAGE]);
+
+export interface TasksUsage {
+	input: number;
+	output: number;
+	cost: number;
+}
+
+export function tasksUsageOf(entry: unknown): TasksUsage | undefined {
+	if (!isObject(entry) || entry.type !== "custom" || !isObject(entry.data)) return undefined;
+	if (typeof entry.customType !== "string" || !PAID.has(entry.customType)) return undefined;
+	const usage = entry.data.usage;
+	if (!isObject(usage) || typeof usage.cost !== "number") return undefined;
+	return {
+		input: typeof usage.input === "number" ? usage.input : 0,
+		output: typeof usage.output === "number" ? usage.output : 0,
+		cost: usage.cost,
+	};
+}
+
+export function tasksHandleOf(branch: readonly unknown[]): string | undefined {
+	for (let index = branch.length - 1; index >= 0; index--) {
+		const entry = branch[index];
+		if (!isObject(entry) || entry.type !== "custom" || entry.customType !== TASKS_UPDATE) continue;
+		const state = isObject(entry.data) ? entry.data.state : undefined;
+		if (isObject(state) && typeof state.handle === "string") return state.handle;
+	}
+	return undefined;
+}

package/packages/frame/src/kit/overlay-images.ts

@@ -0,0 +1,36 @@
+// pi-tui paints pictures over overlays. Delete this file and its calls once
+// https://github.com/earendil-works/pi/issues/10863 is fixed.
+import type { TUI } from "@earendil-works/pi-tui";
+
+const IMAGE = ["\x1b_G", "\x1b]1337;File="] as const;
+
+interface Composer {
+	hasOverlay?: () => boolean;
+	compositeOverlays?: (lines: string[], width: number, height: number) => string[];
+}
+
+const wrapped = new WeakSet<object>();
+
+export function hideImagesUnderOverlays(tui: TUI): void {
+	const composer = tui as unknown as Composer;
+	const compose = composer.compositeOverlays;
+	const hasOverlay = composer.hasOverlay;
+	if (wrapped.has(tui) || typeof compose !== "function" || typeof hasOverlay !== "function") return;
+	wrapped.add(tui);
+	composer.compositeOverlays = function (lines, width, height) {
+		const shown = hasOverlay.call(this) ? withoutImages(lines, height) : lines;
+		return compose.call(this, shown, width, height);
+	};
+}
+
+/** Only the last screenful; the scrollback stays untouched. */
+export function withoutImages(lines: readonly string[], height: number): string[] {
+	const out = [...lines];
+	for (let index = Math.max(0, out.length - height); index < out.length; index++)
+		if (isImage(out[index] ?? "")) out[index] = "";
+	return out;
+}
+
+function isImage(line: string): boolean {
+	return IMAGE.some((prefix) => line.includes(prefix));
+}

package/packages/frame/src/kit/paths.ts

@@ -0,0 +1,16 @@
+// The home folder as `~`, both ways: what you type expands, and what is shown shortens.
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+
+export function expandHome(path: string, home = homedir()): string {
+	if (path === "~") return home;
+	return path.startsWith("~/") ? join(home, path.slice(2)) : path;
+}
+
+export function tildify(path: string, home = homedir()): string {
+	if (home === "" || !isAbsolute(path)) return path;
+	const rest = relative(resolve(home), resolve(path));
+	if (rest === "") return "~";
+	if (rest === ".." || rest.startsWith(`..${sep}`) || isAbsolute(rest)) return path;
+	return `~${sep}${rest}`;
+}