@huseynsnmz/pi-suite 0.0.0-stage → 0.2.0

package/packages/frame/src/kit/contracts/by.ts

@@ -0,0 +1,22 @@
+// Who caused a state change: the operator at the terminal, the operator on a phone, or an agent.
+import { isObject } from "../decode.ts";
+
+export interface By {
+	kind: "terminal" | "client" | "agent";
+	/** The handle for a terminal or an agent; the device's name for a client. */
+	name: string;
+	/** The hostname. */
+	machine: string;
+}
+
+const KINDS: ReadonlySet<string> = new Set<By["kind"]>(["terminal", "client", "agent"]);
+
+export function isBy(value: unknown): value is By {
+	return (
+		isObject(value) &&
+		typeof value.kind === "string" &&
+		KINDS.has(value.kind) &&
+		typeof value.name === "string" &&
+		typeof value.machine === "string"
+	);
+}

package/packages/frame/src/kit/contracts/calls.ts

@@ -0,0 +1,46 @@
+// What decided a tool call, published by the deciding feature and read by whoever frames the call.
+import { defineContract } from "../contract.ts";
+import { boolean, guarded, isObject } from "../decode.ts";
+
+export const RULING_TONES = ["pending", "success", "warning", "error"] as const;
+
+export type RulingTone = (typeof RULING_TONES)[number];
+
+export interface CallRuling {
+	tone: RulingTone;
+	head: string;
+	why?: string;
+	note?: string;
+	detail?: string;
+	blocked?: boolean;
+}
+
+/** Keyed by tool call id. */
+export const RULING = defineContract<CallRuling, string>(
+	"calls:ruling",
+	guarded(isRuling, "a ruling with a tone and a head"),
+);
+
+/** A feature that frames every call answers true, so the ruling is not drawn twice. */
+export const CALLS_FRAMED = defineContract<boolean>("calls:framed", boolean);
+
+function isRuling(value: unknown): value is CallRuling {
+	return (
+		isObject(value) &&
+		typeof value.head === "string" &&
+		RULING_TONES.some((tone) => tone === value.tone)
+	);
+}
+
+/** In the order they are worth trying. */
+export const TARGET_FIELDS = ["path", "file_path", "command", "query", "url", "pattern"] as const;
+
+/** The path, command or query, cut to its first line; empty when the arguments name nothing. */
+export function callTarget(args: unknown): string {
+	const fields = typeof args === "object" && args !== null ? (args as Record<string, unknown>) : {};
+	for (const field of TARGET_FIELDS) {
+		const value = fields[field];
+		if (typeof value === "string" && value.trim() !== "") return value.split("\n")[0] ?? "";
+	}
+	return "";
+}

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

@@ -0,0 +1,89 @@
+import type { BoardView } from "../board/model.ts";
+// One shape per event type. Shapes only grow: a field that changes meaning gets a new name.
+import type { AskQuestion, AskResult } from "./ask.ts";
+import type { By } from "./by.ts";
+import type { CallRuling } from "./calls.ts";
+import type { PermissionMode } from "./mode.ts";
+
+export type RoomActivity = "running" | "idle";
+
+export type Delivery = "woke" | "after-run" | "steered" | "next-turn";
+
+/** Why a message handed for the next turn waits there. */
+export type Held = "asleep" | "quiet" | "full" | "stopped";
+
+export type Activity =
+	| { kind: "edited"; path: string }
+	| { kind: "ran"; command: string; ok: boolean }
+	| { kind: "committed"; sha: string; subject: string };
+
+/** `folder` is absolute with symlinks resolved. */
+export type Member = { folder: string } | { session: string; cwd: string };
+
+/** `listening` hears only what names it. `@everyone` and `@anyone` reach only `in`. */
+export type RoomMode = "in" | "listening" | "out";
+
+export interface LogEventMap {
+	/** `start` tells this process from a later one with the same pid. */
+	"session.started": { pid: number; host: string; model?: string; cwd?: string; start?: string };
+	"session.ended": Record<string, never>;
+	"session.named": { handle?: string };
+	"board.changed": { view: BoardView };
+	"session.state": { state: RoomActivity };
+	/** The text stays in pi's own session file. */
+	"session.prompted": Record<string, never>;
+	/** A prompt from somewhere other than the terminal; its text is in pi's session file. */
+	"prompt.received": { by: By };
+	activity: Activity;
+	/** `to` is session ids, "all" (`@everyone`) or "any" (`@anyone`). */
+	"message.posted": {
+		id: string;
+		from: "you" | "agent";
+		to: string[] | "all" | "any";
+		text: string;
+		urgent?: boolean;
+		/** 0 when a person started the run, d + 1 when a message of depth d woke it. Depth 4 wakes no one. */
+		depth?: number;
+	};
+	/** Written by the receiving session when it hands the message to its agent. */
+	"message.received": { id: string; mode: Delivery; held?: Held };
+	/** The operator lets through what `session` holds for its next turn. */
+	"messages.released": { session: string };
+	"message.read": { id: string };
+	"request.bid": { request: string; fit: number; reason: string; idle: boolean };
+	/** Written only by the session every other one agrees won. */
+	"request.taken": { request: string };
+	/** Its name is for people; two rooms may share one. */
+	"room.created": { name: string };
+	"room.added":
+		| {
+				member: { folder: string };
+				by: "you" | "agent";
+				why?: string;
+				allowedBy?: string;
+				/** A folder brings its sessions in taking part. */
+				mode?: never;
+		  }
+		| {
+				member: { session: string; cwd: string };
+				by: "you" | "agent";
+				why?: string;
+				allowedBy?: string;
+				mode?: RoomMode;
+		  };
+	"room.mode": { member: Member; mode: Exclude<RoomMode, "out"> };
+	/** A removed session stays out while its folder is in, until added by name again. */
+	"room.removed": { member: Member };
+	"room.closed": Record<string, never>;
+	/** `source` is the feature that asked. */
+	"ask.opened": { id: string; source: string; questions: AskQuestion[]; expiresAt?: number };
+	/** Without `by`, nobody known closed it. */
+	"ask.closed": { id: string; by?: By; result: AskResult };
+	/** `by` is the person who answered, when one did. */
+	"call.ruled": { toolCallId: string; ruling: CallRuling; by?: By };
+	"mode.changed": { mode: PermissionMode };
+	/** Logged before the command runs, so a resent id is a repeat across restarts. */
+	"command.received": { id: string; command: string; by?: By };
+	/** On the id of its `command.received` line. */
+	"command.outcome": { id: string; command: string; by?: By; outcome: "refused" | "failed" };
+}

package/packages/frame/src/kit/contracts/mode.ts

@@ -0,0 +1,26 @@
+import { defineContract } from "../contract.ts";
+import { type Problem, isObject, literal, pass } from "../decode.ts";
+import type { By } from "./by.ts";
+
+export const PERMISSION_MODES = ["manual", "edits", "judge", "full"] as const;
+
+export type PermissionMode = (typeof PERMISSION_MODES)[number];
+
+export const MODE = defineContract<PermissionMode>("mode", literal(...PERMISSION_MODES));
+
+export interface ModeSet {
+	/** Applied as if typed at the terminal, and announced through `MODE`. */
+	set(mode: PermissionMode, by?: By): void;
+}
+
+function isModeSet(value: unknown): value is ModeSet {
+	return isObject(value) && typeof value.set === "function";
+}
+
+export const MODE_SET = defineContract<ModeSet>("mode:set", {
+	decode(value) {
+		return isModeSet(value)
+			? pass(value)
+			: { ok: false, problems: [{ path: "", message: "a way to set the mode" }] as Problem[] };
+	},
+});

package/packages/frame/src/kit/contracts/names.ts

@@ -0,0 +1,12 @@
+import { defineContract } from "../contract.ts";
+import { guarded, isObject } from "../decode.ts";
+
+export interface NamesValue {
+	handle: string;
+}
+
+export const NAMES = defineContract<NamesValue>("names", guarded(isNames, "a name"));
+
+function isNames(value: unknown): value is NamesValue {
+	return isObject(value) && typeof value.handle === "string" && value.handle.length > 0;
+}

package/packages/frame/src/kit/contracts/peers.ts

@@ -0,0 +1,77 @@
+import { defineContract } from "../contract.ts";
+import { guarded, isObject } from "../decode.ts";
+import type { RoomMode } from "./events.ts";
+
+export interface PeerMark {
+	handle: string;
+	/** A theme color name, so a peer looks the same in the footer, the room and the board. */
+	color: string;
+	state: "running" | "idle" | "waiting";
+	room?: string;
+}
+
+/** A room this session is in, how it stands there, and the other agents in it. */
+export interface RoomMark {
+	name: string;
+	mode: RoomMode;
+	peers: PeerMark[];
+}
+
+export interface WritingMark {
+	handle: string;
+	color: string;
+	/** `you`, `@handle` or `everyone`. */
+	to: string;
+}
+
+export interface PeersState {
+	peers: PeerMark[];
+	/** Absent when the session is in no room yet, which differs from a session with no color. */
+	me?: PeerMark;
+	/** Messages to this session its agent has not read yet. */
+	unread: number;
+	/** A draft is never worth a frame over the editor, so it goes to the footer. */
+	writing?: WritingMark[];
+	/** The folder's room first. */
+	rooms?: RoomMark[];
+}
+
+export const PEERS = defineContract<PeersState>(
+	"peers",
+	guarded(isPeersState, "a list of peers and an unread count"),
+);
+
+const STATES = new Set(["running", "idle", "waiting"]);
+
+function isPeersState(value: unknown): value is PeersState {
+	if (!isObject(value) || typeof value.unread !== "number") return false;
+	if (!Array.isArray(value.peers) || !value.peers.every(isPeerMark)) return false;
+	if (value.me !== undefined && !isPeerMark(value.me)) return false;
+	if (value.rooms !== undefined && !(Array.isArray(value.rooms) && value.rooms.every(isRoomMark)))
+		return false;
+	if (value.writing === undefined) return true;
+	return Array.isArray(value.writing) && value.writing.every(isWritingMark);
+}
+
+const MODES = new Set(["in", "listening", "out"]);
+
+function isRoomMark(value: unknown): value is RoomMark {
+	if (!isObject(value) || typeof value.name !== "string") return false;
+	if (typeof value.mode !== "string" || !MODES.has(value.mode)) return false;
+	return Array.isArray(value.peers) && value.peers.every(isPeerMark);
+}
+
+function isWritingMark(value: unknown): value is WritingMark {
+	if (!isObject(value)) return false;
+	return (
+		typeof value.handle === "string" &&
+		typeof value.color === "string" &&
+		typeof value.to === "string"
+	);
+}
+
+function isPeerMark(value: unknown): value is PeerMark {
+	if (!isObject(value) || typeof value.handle !== "string" || typeof value.color !== "string")
+		return false;
+	return typeof value.state === "string" && STATES.has(value.state);
+}

package/packages/frame/src/kit/contracts/prompts.ts

@@ -0,0 +1,8 @@
+// Where a prompt came from when a person sent it from a client. The routing of `@` mentions treats it
+// as typed at the terminal, and the transcript says where it came from.
+import { defineContract } from "../contract.ts";
+import { guarded } from "../decode.ts";
+import { type By, isBy } from "./by.ts";
+
+/** Keyed by the prompt's text, as pi hands it to `input` and draws it. */
+export const PROMPT_FROM = defineContract<By, string>("prompts:from", guarded(isBy, "a sender"));

package/packages/frame/src/kit/contracts/screen.ts

@@ -0,0 +1,75 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+// Every harness piece is its own extension, so the screen asks them over pi.events.
+import type { Control, Json } from "../control.ts";
+import type { Layer } from "../settings/store.ts";
+
+export const LIST = "harness:screen:list";
+export const APPLY = "harness:screen:apply";
+export const RUN = "harness:screen:run";
+export const DONE = "harness:screen:done";
+export const CHANGED = "harness:settings:changed";
+
+export type RowKind = "setting" | "value" | "action" | "info";
+
+export interface RowView {
+	feature: string;
+	id: string;
+	kind: RowKind;
+	section: string;
+	label: string;
+	description: string;
+	control?: Control;
+	value?: Json;
+	text?: string;
+	confirm?: string;
+	indent?: number;
+	/** When that is not this session. */
+	meta?: string;
+	layer?: Layer;
+	fallback?: Json;
+	/** The global value a project value hides. */
+	hidden?: Json;
+	restart?: boolean;
+	/** Drawn under the list. */
+	preview?: Preview;
+}
+
+export type Preview = (value: Json, theme: Theme, width: number) => string[];
+
+export interface TabView {
+	title: string;
+	sections: string[];
+	rows: RowView[];
+}
+
+export interface ListRequest {
+	tabs: TabView[];
+}
+
+/** `unset` drops the value that wins, so the one below shows. */
+export interface ApplyRequest {
+	feature: string;
+	id: string;
+	op: "set" | "unset";
+	value?: Json;
+	answer?: { error?: string };
+}
+
+export interface RunRequest {
+	feature: string;
+	id: string;
+	request: string;
+	answer?: { error?: string };
+}
+
+export interface RunDone {
+	request: string;
+	text?: string;
+	error?: string;
+}
+
+export interface Changed {
+	/** The store that wrote, so it skips its own write. */
+	source: string;
+}

package/packages/frame/src/kit/contracts/skills.ts

@@ -0,0 +1,81 @@
+import { defineContract, type EventScope } from "../contract.ts";
+import { stringList } from "../decode.ts";
+
+export const SKILLS = defineContract<string[]>("skills:names", stringList("skill names"));
+
+export const SKILL_REF = "/skill:";
+
+/** Empty when no skills feature runs. */
+export function skillNames(scope: EventScope): string[] {
+	return SKILLS.current(scope) ?? [];
+}
+
+/** Group 1 is what came before, group 2 the name. */
+function skillRefPattern(names: readonly string[]): RegExp | undefined {
+	if (names.length === 0) return undefined;
+	const alternatives = names
+		.toSorted((left, right) => right.length - left.length)
+		.map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+		.join("|");
+	return new RegExp(`(^|[\\s([{"'])${SKILL_REF}(${alternatives})(?![\\w-])`, "g");
+}
+
+const TYPING = /(?:^|[\s([{"'])(\/([\w.:-]*))$/;
+
+export interface SkillQuery {
+	/** What the completion replaces, slash included. */
+	typed: string;
+	query: string;
+}
+
+/** Undefined at the start of the message, where pi's own palette opens. */
+export function skillQueryAt(
+	lines: readonly string[],
+	cursorLine: number,
+	cursorCol: number,
+): SkillQuery | undefined {
+	const before = (lines[cursorLine] ?? "").slice(0, cursorCol);
+	const match = TYPING.exec(before);
+	if (match === null) return undefined;
+	const [, typed = "", query = ""] = match;
+	if (cursorLine === 0 && before.trimStart() === typed) return undefined;
+	return { typed, query };
+}
+
+export function referencedSkills(text: string, names: readonly string[]): string[] {
+	const pattern = skillRefPattern(names);
+	if (pattern === undefined) return [];
+	const found: string[] = [];
+	for (const prose of outsideCode(text)) {
+		for (const match of prose.matchAll(pattern)) {
+			const name = match[2];
+			if (name !== undefined && !found.includes(name)) found.push(name);
+		}
+	}
+	return found;
+}
+
+export function drawSkillRefs(
+	text: string,
+	names: readonly string[],
+	draw: (name: string) => string,
+): string {
+	const pattern = skillRefPattern(names);
+	if (pattern === undefined) return text;
+	return splitCode(text)
+		.map(({ code, part }) =>
+			code
+				? part
+				: part.replace(pattern, (_whole, before: string, name: string) => `${before}${draw(name)}`),
+		)
+		.join("");
+}
+
+/** The text cut at inline code: `/skill:x` in backticks stays text. */
+function splitCode(text: string): { code: boolean; part: string }[] {
+	return text.split(/(`[^`]*`)/).map((part, index) => ({ code: index % 2 === 1, part }));
+}
+
+function outsideCode(text: string): string[] {
+	return splitCode(text).flatMap(({ code, part }) => (code ? [] : [part]));
+}

package/packages/frame/src/kit/contracts/sources.ts

@@ -0,0 +1,81 @@
+// Screens draw a session from a source: this pi, a session file, or a remote one. A source holds
+// functions, so it travels on raw channels rather than `defineContract`, whose values are JSON.
+import type { ExtensionAPI, SessionEntry } from "@earendil-works/pi-coding-agent";
+
+import { isObject } from "../decode.ts";
+
+type Events = ExtensionAPI["events"];
+
+export interface SessionSummary {
+	session: string;
+	/** The hostname. */
+	machine: string;
+	cwd: string;
+	/** Pi's `/name`, not the room's handle. */
+	name?: string;
+	/** Pi draws the branch from it back to the root. */
+	leafId?: string;
+	model?: { provider: string; id: string };
+	thinkingLevel?: string;
+	/** `window` is missing where the source cannot know it, such as a file. */
+	context?: { tokens: number; window?: number };
+}
+
+export interface SourceCursor {
+	entry?: string;
+}
+
+/** `reset`: the source lost its place, so drop what was held; everything follows from the start. */
+export type SourceItem =
+	| { kind: "entry"; entry: SessionEntry }
+	| { kind: "summary"; summary: SessionSummary }
+	| { kind: "reset" }
+	| { kind: "ended" };
+
+export interface SessionSource {
+	open(): Promise<SessionSummary>;
+	/** Follows from `after`, or from the start, until the returned function is called. */
+	follow(after: SourceCursor | undefined, on: (item: SourceItem) => void): () => void;
+}
+
+/** `file` lets a session of this machine be read without anyone's help. */
+export interface SourceAddress {
+	session: string;
+	machine: string;
+	file?: string;
+}
+
+/** Remote answers with its sources; the kit's file source is the fallback. */
+export const SOURCES = "harness:sources";
+interface SourceRequest {
+	address: SourceAddress;
+	source?: SessionSource;
+}
+
+/** An undefined answer leaves the address to another provider. */
+export function provideSources(
+	events: Events,
+	answer: (address: SourceAddress) => SessionSource | undefined,
+): () => void {
+	return events.on(SOURCES, (data) => {
+		const request = data as SourceRequest;
+		if (!isObject(data) || request.source !== undefined || !isSourceAddress(request.address))
+			return;
+		request.source = answer(request.address);
+	});
+}
+
+export function askSource(events: Events, address: SourceAddress): SessionSource | undefined {
+	const request: SourceRequest = { address };
+	events.emit(SOURCES, request);
+	return request.source;
+}
+
+export function isSourceAddress(value: unknown): value is SourceAddress {
+	return (
+		isObject(value) &&
+		typeof value.session === "string" &&
+		typeof value.machine === "string" &&
+		(value.file === undefined || typeof value.file === "string")
+	);
+}

package/packages/frame/src/kit/contracts/views.ts

@@ -0,0 +1,42 @@
+// Showing a session over the screen: the look answers, the panel and remote ask. Raw channels, like the sources'.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { isObject } from "../decode.ts";
+import { isSourceAddress, type SourceAddress } from "./sources.ts";
+
+type Events = ExtensionAPI["events"];
+
+export const VIEW_OPEN = "harness:view.open";
+export const VIEW_AVAILABLE = "harness:view.available";
+
+export function canOpenView(events: Events): boolean {
+	const probe = { available: false };
+	events.emit(VIEW_AVAILABLE, probe);
+	return probe.available;
+}
+
+/** False when nobody took the request. */
+export function openView(events: Events, address: SourceAddress): boolean {
+	const request = { address, opened: false };
+	events.emit(VIEW_OPEN, request);
+	return request.opened;
+}
+
+export function provideViews(
+	events: Events,
+	open: (address: SourceAddress) => boolean,
+	available: () => boolean = () => true,
+): () => void {
+	const stops = [
+		events.on(VIEW_AVAILABLE, (data) => {
+			if (isObject(data) && available()) data.available = true;
+		}),
+		events.on(VIEW_OPEN, (data) => {
+			if (!isObject(data) || data.opened === true || !isSourceAddress(data.address)) return;
+			data.opened = open(data.address);
+		}),
+	];
+	return () => {
+		for (const stop of stops) stop();
+	};
+}

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

@@ -0,0 +1,59 @@
+// Plain JSON, because the screen may live in another package.
+export type Json = string | number | boolean | null | Json[] | { [key: string]: Json };
+
+export interface ControlOption {
+	value: Json;
+	label?: string;
+	description?: string;
+}
+
+export type Control =
+	| { type: "toggle" }
+	| { type: "choice"; options: ControlOption[]; custom?: boolean }
+	| { type: "number"; min?: number; max?: number; step?: number; unit?: string; nullable?: boolean }
+	| { type: "text"; multiline?: boolean; presets?: ControlOption[] }
+	| { type: "list"; options?: ControlOption[] };
+
+export function formatValue(control: Control, value: Json | undefined): string {
+	if (value === undefined || value === null) return control.type === "number" ? "none" : "";
+	switch (control.type) {
+		case "toggle":
+			return value === true ? "on" : "off";
+		case "choice":
+			return optionLabel(control.options, value);
+		case "number":
+			return control.unit === undefined ? String(value) : `${value}${control.unit}`;
+		case "text":
+			if (typeof value !== "string") return JSON.stringify(value);
+			if (control.presets !== undefined) {
+				const preset = control.presets.find((option) => option.value === value);
+				if (preset !== undefined) return preset.label ?? String(preset.value);
+				if (value.trim() === "") return "(empty)";
+				return "custom";
+			}
+			return firstLine(value);
+		case "list":
+			if (!Array.isArray(value)) return JSON.stringify(value);
+			if (value.length === 0) return "(none)";
+			return value.map((entry) => optionLabel(control.options ?? [], entry)).join(", ");
+	}
+}
+
+export function optionLabel(options: readonly ControlOption[], value: Json): string {
+	const option = options.find((entry) => sameJson(entry.value, value));
+	return optionText(option ?? { value });
+}
+
+export function optionText(option: ControlOption): string {
+	if (option.label !== undefined) return option.label;
+	return typeof option.value === "string" ? option.value : JSON.stringify(option.value);
+}
+
+export function sameJson(left: unknown, right: unknown): boolean {
+	return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function firstLine(text: string): string {
+	const line = text.split("\n")[0] ?? "";
+	return text.includes("\n") ? `${line} ...` : line;
+}

package/packages/frame/src/kit/dark-theme.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { Theme } from "@earendil-works/pi-coding-agent";
+
+const BACKGROUND_TOKENS = new Set([
+	"selectedBg",
+	"searchMatchBg",
+	"userMessageBg",
+	"customMessageBg",
+	"toolPendingBg",
+	"toolSuccessBg",
+	"toolErrorBg",
+]);
+
+/** Read from pi's own theme file, so a pi release that moves it fails loudly. */
+export function darkTheme(): Theme {
+	const root = dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent")));
+	const file = JSON.parse(
+		readFileSync(join(root, "modes/interactive/theme/dark.json"), "utf8"),
+	) as { vars: Record<string, string | number>; colors: Record<string, string | number> };
+	const resolve = (value: string | number, seen: Set<string>): string | number => {
+		if (typeof value !== "string") return value;
+		const target = file.vars[value];
+		if (target === undefined || seen.has(value)) return value;
+		return resolve(target, seen.add(value));
+	};
+	const foreground: Record<string, string | number> = {};
+	const background: Record<string, string | number> = {};
+	for (const [token, value] of Object.entries(file.colors)) {
+		const target = BACKGROUND_TOKENS.has(token) ? background : foreground;
+		target[token] = resolve(value, new Set());
+	}
+	return new Theme(
+		foreground as ConstructorParameters<typeof Theme>[0],
+		background as ConstructorParameters<typeof Theme>[1],
+		"truecolor",
+		{ name: "dark" },
+	);
+}