@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/frame/src/data/snapshot.ts

@@ -0,0 +1,223 @@
+import { hostname } from "node:os";
+
+import type { AccountState, Board, PeerMark, RoomMark, WritingMark } from "../kit/index.ts";
+import { VERSION, type ExtensionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
+
+import { plainText } from "../render/safe.ts";
+
+import type { GitState } from "./git.ts";
+import type { RequestView, RunView } from "./telemetry.ts";
+import {
+	type Averages,
+	averagesOf,
+	cacheHitPercent,
+	cacheWarming,
+	emptyTotals,
+	type Totals,
+	totalsOf,
+} from "./totals.ts";
+
+interface ModelInfo {
+	name: string;
+	provider: string;
+	reasoning: boolean;
+}
+
+interface ContextInfo {
+	percent: number;
+	tokens: number;
+	window: number;
+}
+
+/** pi-sandbox sets this while it's on, and empties it when it goes off. */
+export const SANDBOX_STATUS = "sandbox";
+
+export interface Snapshot {
+	now: number;
+	cwd: string;
+	home: string | undefined;
+	branch: string | null;
+	git: GitState | undefined;
+	host: string | undefined;
+	sessionName: string | undefined;
+	/** The word the room calls this session by, in its color once it is in a room. */
+	me: { handle: string; color?: string } | undefined;
+	version: string;
+	model: ModelInfo | undefined;
+	account: AccountState | undefined;
+	thinking: string | undefined;
+	context: ContextInfo | undefined;
+	totals: Totals;
+	cacheHit: number | undefined;
+	cacheWarming: boolean;
+	subscription: boolean;
+	request: RequestView | undefined;
+	last: RequestView | undefined;
+	run: RunView | undefined;
+	averages: Averages;
+	statuses: ReadonlyMap<string, string>;
+	/** Whether pi-sandbox is confining commands. Undefined when it isn't installed. */
+	sandbox: "on" | "off" | undefined;
+	/** When a board feature keeps it. */
+	board: Board | undefined;
+	/** When a peers feature keeps them. */
+	peers: PeerMark[];
+	/** Empty when the peers feature publishes only `peers`. */
+	peersRooms: RoomMark[];
+	peersUnread: number;
+	peersWriting: WritingMark[];
+}
+
+export function emptySnapshot(): Snapshot {
+	return {
+		now: 0,
+		cwd: "",
+		home: undefined,
+		branch: null,
+		git: undefined,
+		host: undefined,
+		sessionName: undefined,
+		me: undefined,
+		version: VERSION,
+		model: undefined,
+		account: undefined,
+		thinking: undefined,
+		context: undefined,
+		totals: emptyTotals(),
+		cacheHit: undefined,
+		cacheWarming: false,
+		subscription: false,
+		request: undefined,
+		last: undefined,
+		run: undefined,
+		averages: { decode: undefined, prefill: undefined },
+		statuses: new Map(),
+		sandbox: undefined,
+		board: undefined,
+		peers: [],
+		peersRooms: [],
+		peersUnread: 0,
+		peersWriting: [],
+	};
+}
+
+export interface LiveInputs {
+	branch: string | null;
+	git: GitState | undefined;
+	account?: AccountState | undefined;
+	request: RequestView | undefined;
+	last: RequestView | undefined;
+	run: RunView | undefined;
+	statuses: ReadonlyMap<string, string>;
+	sandboxInstalled?: boolean;
+	board?: Board | undefined;
+	me?: { handle: string; color?: string } | undefined;
+	peers?: PeerMark[] | undefined;
+	peersRooms?: RoomMark[] | undefined;
+	peersUnread?: number | undefined;
+	peersWriting?: WritingMark[] | undefined;
+}
+
+interface Derived {
+	totals: Totals;
+	cacheHit: number | undefined;
+	cacheWarming: boolean;
+	averages: Averages;
+	context: ContextInfo | undefined;
+	answeredBy: string | undefined;
+}
+
+const VIRTUAL_API = "pi-virtual";
+
+export class SnapshotReader {
+	#key: string | undefined;
+	#derived: Derived | undefined;
+	readonly #host = hostname().split(".")[0];
+
+	read(ctx: ExtensionContext, live: LiveInputs): Snapshot {
+		const model = ctx.model;
+		const derived = this.#derive(ctx);
+
+		return {
+			now: Date.now(),
+			cwd: ctx.cwd,
+			home: process.env.HOME ?? process.env.USERPROFILE,
+			branch: live.branch,
+			git: live.git,
+			host: this.#host,
+			sessionName: ctx.sessionManager.getSessionName(),
+			me: live.me,
+			version: VERSION,
+			model:
+				model === undefined
+					? undefined
+					: {
+							name:
+								model.api === VIRTUAL_API && derived.answeredBy !== undefined
+									? `${model.name} \u2192 ${derived.answeredBy}`
+									: (model.name ?? model.id),
+							provider: ctx.modelRegistry.getProviderDisplayName(model.provider),
+							reasoning: model.reasoning,
+						},
+			thinking: ctx.thinkingLevel,
+			account: live.account,
+			...derived,
+			subscription: model === undefined ? false : ctx.modelRegistry.isUsingOAuth(model),
+			request: live.request,
+			last: live.last,
+			run: live.run,
+			statuses: new Map(
+				[...live.statuses.entries()]
+					.toSorted(([a], [b]) => a.localeCompare(b))
+					.map(([key, text]): [string, string] => [key, sanitize(text)])
+					.filter(([, text]) => text !== ""),
+			),
+			sandbox: !live.sandboxInstalled ? undefined : live.statuses.get(SANDBOX_STATUS) ? "on" : "off",
+			board: live.board,
+			peers: live.peers ?? [],
+			peersRooms: live.peersRooms ?? [],
+			peersUnread: live.peersUnread ?? 0,
+			peersWriting: live.peersWriting ?? [],
+		};
+	}
+
+	#derive(ctx: ExtensionContext): Derived {
+		// Entries are appended at the leaf, so the sums change only when the leaf or the model does.
+		const key = `${ctx.sessionManager.getLeafId() ?? ""}\u0000${ctx.model?.provider}/${ctx.model?.id}`;
+		if (this.#derived !== undefined && key === this.#key) return this.#derived;
+
+		const entries: readonly SessionEntry[] = ctx.sessionManager.getBranch();
+		this.#key = key;
+		this.#derived = {
+			totals: totalsOf(entries),
+			cacheHit: cacheHitPercent(entries),
+			cacheWarming: cacheWarming(entries),
+			averages: averagesOf(entries),
+			context: contextOf(ctx),
+			answeredBy: answeredBy(ctx, entries),
+		};
+		return this.#derived;
+	}
+}
+
+/** A virtual model only says what was selected. The latest answer says which model it chose. */
+function answeredBy(ctx: ExtensionContext, entries: readonly SessionEntry[]): string | undefined {
+	for (let index = entries.length - 1; index >= 0; index--) {
+		const entry = entries[index];
+		if (entry?.type !== "message" || entry.message.role !== "assistant") continue;
+		if (entry.message.stopReason === "error" || entry.message.stopReason === "aborted") continue;
+		const { provider, model } = entry.message;
+		return plainText(ctx.modelRegistry.find(provider, model)?.name ?? model).replace(/\s+/g, " ");
+	}
+	return undefined;
+}
+
+function contextOf(ctx: ExtensionContext): ContextInfo | undefined {
+	const usage = ctx.getContextUsage();
+	if (usage === undefined || usage.percent === null || usage.tokens === null) return undefined;
+	return { percent: usage.percent, tokens: usage.tokens, window: usage.contextWindow };
+}
+
+function sanitize(text: string): string {
+	return text.replace(/[\r\n\t]+/g, " ").trim();
+}

package/packages/frame/src/data/start-notes.ts

@@ -0,0 +1,104 @@
+// Under the folder and the model, only what changed or waits on you since the last session here.
+import { formatClock, GLYPH } from "../kit/index.ts";
+
+import type { GithubState } from "./github.ts";
+import type { Snapshot } from "./snapshot.ts";
+
+const PLAN_LIMIT = 70;
+
+export interface LastVisit {
+	at: number;
+	version: string;
+}
+
+export interface StartNote {
+	mark: string;
+	color: string;
+	text: string;
+	detail?: string;
+}
+
+export function startNotes(
+	snapshot: Pick<Snapshot, "peers" | "account" | "git" | "branch">,
+	version: string,
+	last: LastVisit | undefined,
+	github?: GithubState,
+): StartNote[] {
+	const notes: StartNote[] = [];
+	const { account, git } = snapshot;
+
+	if (account?.needsLogin === true)
+		notes.push({
+			mark: GLYPH.cross,
+			color: "error",
+			text: `${account.label} needs a sign-in`,
+			detail: "/accounts",
+		});
+	if (git !== undefined && git.conflicted > 0)
+		notes.push({ mark: GLYPH.cross, color: "error", text: `${git.conflicted} files in conflict` });
+	if (git !== undefined && git.behind > 0)
+		notes.push({
+			mark: GLYPH.down,
+			color: "warning",
+			text: `${snapshot.branch ?? "this branch"} is ${git.behind} behind`,
+			detail: "pull before you start",
+		});
+	if (github?.ci !== undefined)
+		notes.push({
+			mark: GLYPH.cross,
+			color: "error",
+			text: `CI failed on ${github.ci.branch}`,
+			detail: `${github.ci.sha}  ${github.ci.name}`,
+		});
+	if (github?.pr !== undefined)
+		notes.push({
+			mark: GLYPH.flag,
+			color: "warning",
+			text: `${github.pr.ref ?? `PR #${github.pr.number}`} ${github.pr.title}`,
+			detail: github.pr.waits,
+		});
+	for (const peer of snapshot.peers)
+		notes.push({
+			mark: GLYPH.diamond,
+			color: peer.color,
+			text: `@${peer.handle}`,
+			detail: peerState(peer.state),
+		});
+	for (const window of account?.windows ?? []) {
+		if (window.used < PLAN_LIMIT) continue;
+		notes.push({
+			mark: GLYPH.up,
+			color: window.used >= 90 ? "error" : "warning",
+			text: `${window.name} at ${Math.round(window.used)}%`,
+			detail: window.resetsIn === undefined ? undefined : `resets in ${window.resetsIn}`,
+		});
+	}
+	if (last !== undefined && last.version !== version)
+		notes.push({
+			mark: GLYPH.up,
+			color: "accent",
+			text: `${GLYPH.pi}-frame ${version} is new`,
+			detail: `was ${last.version}`,
+		});
+	return notes;
+}
+
+function peerState(state: "running" | "idle" | "waiting"): string {
+	switch (state) {
+		case "running":
+			return "works here";
+		case "waiting":
+			return "waits for you";
+		case "idle":
+			return "is open here";
+	}
+}
+
+/** Local time, or the day when it was not today. */
+export function since(at: number, now: number): string {
+	const then = new Date(at);
+	const time = formatClock(at);
+	if (new Date(now).toDateString() === then.toDateString()) return time;
+	const days = Math.round((now - at) / 86_400_000);
+	return days <= 1 ? `yesterday ${time}` : `${days} days ago`;
+}

package/packages/frame/src/data/telemetry.ts

@@ -0,0 +1,337 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+import { STALL_MS } from "../render/timing.ts";
+import {
+	emptyTotals,
+	perSecond,
+	promptOf,
+	REQUEST_CHANGES,
+	type RequestRecord,
+	type Totals,
+	usageTotals,
+} from "./totals.ts";
+
+const MIN_SAMPLE_MS = 250;
+/** Measured over 16,889 assistant messages: 2.88 characters per output token. */
+const DEFAULT_CHARS_PER_TOKEN = 2.9;
+
+/** So the wait for the first thought can be told from the first word. */
+export type DeltaKind = "thinking" | "writing";
+
+export interface RequestView {
+	streaming: boolean;
+	waiting: boolean;
+	elapsedMs: number;
+	/** From the request leaving to the first token of any kind. */
+	waitMs: number | undefined;
+	/** The same wait while it runs. */
+	waitingMs: number;
+	/** To the response headers: the provider's own latency. */
+	serverMs: number | undefined;
+	/** From the headers to the first token: the model reading the prompt. */
+	prefillMs: number | undefined;
+	/** Unset when it wrote without thinking. */
+	thoughtMs: number | undefined;
+	decode: number | undefined;
+	prefill: number | undefined;
+	usage: Totals;
+	estimated: boolean;
+}
+
+/** One call to the model, for the line under its response. */
+export interface Timing {
+	/** When it left. */
+	at: number;
+	streaming: boolean;
+	waitMs: number | undefined;
+	waitingMs: number;
+	serverMs: number | undefined;
+	thoughtMs: number | undefined;
+	totalMs: number;
+	writingMs: number;
+	/** Pauses of `STALL_MS` or more while it wrote. */
+	stallMs: number;
+	output: number;
+	estimated: boolean;
+}
+
+export interface RunView {
+	running: boolean;
+	elapsedMs: number;
+	requests: number;
+	cost: number;
+}
+
+interface Request {
+	startedAt: number;
+	sentAt: number | undefined;
+	headersAt: number | undefined;
+	firstTokenAt: number | undefined;
+	firstWritingAt: number | undefined;
+	endedAt: number | undefined;
+	messageAt?: number;
+	usage: Totals;
+	characters: number;
+	lastDeltaAt: number | undefined;
+	stallMs: number;
+}
+
+interface Run {
+	startedAt: number;
+	endedAt: number | undefined;
+	requests: number;
+	cost: number;
+}
+
+interface UsageLike {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: { total: number };
+}
+
+function span(from: number | undefined, to: number | undefined): number | undefined {
+	return from === undefined || to === undefined ? undefined : to - from;
+}
+
+export class Telemetry {
+	readonly #now: () => number;
+	#run: Run | undefined;
+	#request: Request | undefined;
+	#last: RequestView | undefined;
+	/** By the response's timestamp, which stays the same while it's written. */
+	#byMessage = new Map<number, Request>();
+	#restored = new Map<number, Timing>();
+	/** They arrive before the pi message they belong to. */
+	#sentAt: number | undefined;
+	#headersAt: number | undefined;
+	/** So the live estimate uses a real ratio. */
+	#sampled = { characters: 0, output: 0 };
+
+	constructor(now: () => number = Date.now) {
+		this.#now = now;
+	}
+
+	runStarted(): void {
+		this.#run = { startedAt: this.#now(), endedAt: undefined, requests: 0, cost: 0 };
+	}
+
+	runEnded(): void {
+		if (this.#run !== undefined && this.#run.endedAt === undefined) this.#run.endedAt = this.#now();
+	}
+
+	/** Before every call to the model: the start of the wait. */
+	providerRequestSent(): void {
+		this.#sentAt = this.#now();
+		this.#headersAt = undefined;
+		this.#attach();
+	}
+
+	/** Before the stream is read. */
+	providerResponseArrived(): void {
+		this.#headersAt = this.#now();
+		this.#attach();
+	}
+
+	requestStarted(): void {
+		this.#sentAt = undefined;
+		this.#headersAt = undefined;
+		this.#begin();
+		if (this.#run === undefined || this.#run.endedAt !== undefined) this.runStarted();
+		if (this.#run !== undefined) this.#run.requests++;
+	}
+
+	/** Later requests of a turn: the next call after a tool ran. */
+	answerStarted(messageAt?: number): void {
+		if (this.#request === undefined || this.#request.endedAt !== undefined) this.#begin();
+		if (messageAt !== undefined && this.#request !== undefined) {
+			this.#byMessage.set(messageAt, this.#request);
+			this.#request.messageAt = messageAt;
+		}
+	}
+
+	answerGrew(delta: string, usage: UsageLike, kind: DeltaKind): void {
+		const request = this.#request;
+		if (request === undefined || request.endedAt !== undefined) return;
+		request.usage = usageTotals(usage);
+		if (delta.length === 0) return;
+		const grewAt = this.#now();
+		const gap = grewAt - (request.lastDeltaAt ?? grewAt);
+		if (gap >= STALL_MS) request.stallMs += gap;
+		request.lastDeltaAt = grewAt;
+		request.characters += delta.length;
+		request.firstTokenAt ??= this.#now();
+		if (kind === "writing") request.firstWritingAt ??= this.#now();
+	}
+
+	answerEnded(usage: UsageLike): RequestRecord | undefined {
+		const request = this.#request;
+		if (request === undefined || request.endedAt !== undefined) return undefined;
+
+		const now = this.#now();
+		request.endedAt = now;
+		request.usage = usageTotals(usage);
+		if (this.#run !== undefined) this.#run.cost += usage.cost.total;
+		if (request.usage.output === 0 && request.firstTokenAt === undefined) return undefined;
+
+		if (request.characters > 0 && request.usage.output > 0) {
+			this.#sampled.characters += request.characters;
+			this.#sampled.output += request.usage.output;
+		}
+
+		const firstTokenAt = request.firstTokenAt ?? now;
+		const from = request.sentAt ?? request.startedAt;
+		this.#last = this.#view(request);
+		const timing = this.#timing(request);
+		return {
+			output: request.usage.output,
+			prompt: promptOf(request.usage),
+			firstTokenMs: firstTokenAt - from,
+			generationMs: now - firstTokenAt,
+			at: from,
+			messageAt: request.messageAt,
+			serverMs: span(request.sentAt, request.headersAt),
+			thoughtMs: timing.thoughtMs,
+			totalMs: now - from,
+			stallMs: request.stallMs,
+		};
+	}
+
+	timingOf(messageAt: number): Timing | undefined {
+		const request = this.#byMessage.get(messageAt);
+		return request === undefined ? this.#restored.get(messageAt) : this.#timing(request);
+	}
+
+	/** The calls an earlier run of this session recorded. */
+	restore(entries: readonly SessionEntry[]): void {
+		for (const entry of entries) {
+			if (entry.type !== "custom" || entry.customType !== REQUEST_CHANGES) continue;
+			const record = entry.data as Partial<RequestRecord> | undefined;
+			if (record?.messageAt === undefined || record.at === undefined) continue;
+			this.#restored.set(record.messageAt, {
+				at: record.at,
+				streaming: false,
+				waitMs: record.firstTokenMs,
+				waitingMs: record.firstTokenMs ?? 0,
+				serverMs: record.serverMs,
+				thoughtMs: record.thoughtMs,
+				totalMs: record.totalMs ?? 0,
+				writingMs: record.generationMs ?? 0,
+				stallMs: record.stallMs ?? 0,
+				output: record.output ?? 0,
+				estimated: false,
+			});
+		}
+	}
+
+	request(): RequestView | undefined {
+		const request = this.#request;
+		return request === undefined ? undefined : this.#view(request);
+	}
+
+	last(): RequestView | undefined {
+		return this.#last;
+	}
+
+	run(): RunView | undefined {
+		const run = this.#run;
+		if (run === undefined) return undefined;
+		const running = run.endedAt === undefined;
+		return {
+			running,
+			elapsedMs: (run.endedAt ?? this.#now()) - run.startedAt,
+			requests: run.requests,
+			cost: run.cost,
+		};
+	}
+
+	reset(): void {
+		this.#run = undefined;
+		this.#request = undefined;
+		this.#last = undefined;
+		this.#byMessage.clear();
+		this.#restored.clear();
+		this.#sentAt = undefined;
+		this.#headersAt = undefined;
+	}
+
+	#begin(): void {
+		this.#request = {
+			startedAt: this.#now(),
+			sentAt: this.#sentAt,
+			headersAt: this.#headersAt,
+			firstTokenAt: undefined,
+			firstWritingAt: undefined,
+			endedAt: undefined,
+			usage: emptyTotals(),
+			characters: 0,
+			lastDeltaAt: undefined,
+			stallMs: 0,
+		};
+	}
+
+	/** Pi sends before it opens the message, so the marks may arrive first. */
+	#attach(): void {
+		const request = this.#request;
+		if (request === undefined || request.endedAt !== undefined) return;
+		request.sentAt = this.#sentAt;
+		request.headersAt = this.#headersAt;
+	}
+
+	#timing(request: Request): Timing {
+		const view = this.#view(request);
+		const end = request.endedAt ?? this.#now();
+		const from = request.sentAt ?? request.startedAt;
+		// While it's paused, the pause so far counts too.
+		const pause = request.endedAt === undefined ? end - (request.lastDeltaAt ?? end) : 0;
+		return {
+			at: from,
+			streaming: view.streaming,
+			waitMs: view.waitMs,
+			waitingMs: view.waitingMs,
+			serverMs: view.serverMs,
+			thoughtMs: view.thoughtMs,
+			totalMs: end - from,
+			writingMs: request.firstTokenAt === undefined ? 0 : end - request.firstTokenAt,
+			stallMs: request.stallMs + (pause >= STALL_MS ? pause : 0),
+			output: view.usage.output,
+			estimated: view.estimated,
+		};
+	}
+
+	#view(request: Request): RequestView {
+		const now = this.#now();
+		const streaming = request.endedAt === undefined;
+		const from = request.sentAt ?? request.startedAt;
+		const waitMs = span(from, request.firstTokenAt);
+		const estimated = streaming && request.usage.output === 0;
+		const output = estimated
+			? Math.round(request.characters / this.#charsPerToken())
+			: request.usage.output;
+		const writingMs =
+			request.firstTokenAt === undefined ? 0 : (request.endedAt ?? now) - request.firstTokenAt;
+		const thoughtMs = span(request.firstTokenAt, request.firstWritingAt);
+
+		return {
+			streaming,
+			waiting: streaming && request.firstTokenAt === undefined,
+			elapsedMs: (request.endedAt ?? now) - request.startedAt,
+			waitMs,
+			waitingMs: (request.endedAt ?? now) - from,
+			serverMs: span(request.sentAt, request.headersAt),
+			prefillMs: span(request.headersAt ?? request.sentAt, request.firstTokenAt),
+			thoughtMs: thoughtMs !== undefined && thoughtMs > 0 ? thoughtMs : undefined,
+			decode: writingMs < MIN_SAMPLE_MS && streaming ? undefined : perSecond(output, writingMs),
+			prefill: waitMs === undefined ? undefined : perSecond(promptOf(request.usage), waitMs),
+			usage: { ...request.usage, output },
+			estimated,
+		};
+	}
+
+	/** This session's ratio, or the measured default. */
+	#charsPerToken(): number {
+		const { characters, output } = this.#sampled;
+		return output > 0 ? characters / output : DEFAULT_CHARS_PER_TOKEN;
+	}
+}