@huseynsnmz/pi-suite 0.1.0 → 0.2.1

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

@@ -4,7 +4,7 @@ import { stripTerminalSequences } from "@earendil-works/pi-tui";
 const MODE_STATUS = "pi-modes";
 const REPORTED = /^mode: (normal|auto|plan|read-only|yolo)$/;
 
-type Mode = "normal" | "auto" | "plan" | "read-only" | "yolo";
+export type Mode = "normal" | "auto" | "plan" | "read-only" | "yolo";
 
 /** The same colors pi-modes gives the word. In `normal`, the frame stays pi's own. */
 const FRAME_COLORS = { auto: "warning", plan: "accent", "read-only": "success", yolo: "error" } as const;
@@ -15,9 +15,35 @@ export function modeOf(statuses: ReadonlyMap<string, string>): Mode | undefined
 	return REPORTED.exec(stripTerminalSequences(status).trim())?.[1] as Mode | undefined;
 }
 
+/** A message's frame stays pi's own in `normal` too. */
+export function modeColor(mode: Mode): (typeof FRAME_COLORS)[keyof typeof FRAME_COLORS] | undefined {
+	return mode === "normal" ? undefined : FRAME_COLORS[mode];
+}
+
 export function frameColorOf(
 	statuses: ReadonlyMap<string, string>,
 ): (typeof FRAME_COLORS)[keyof typeof FRAME_COLORS] | undefined {
 	const mode = modeOf(statuses);
-	return mode === undefined || mode === "normal" ? undefined : FRAME_COLORS[mode];
+	return mode === undefined ? undefined : modeColor(mode);
+}
+
+/** Saved with the session, so a resumed conversation still shows which mode each message went out in. */
+export const SENT_IN_ENTRY = "pi-frame-sent-in";
+
+/** The session entry of each message sent in a mode, joined on the message's timestamp, since a live message has no entry yet. */
+export function sentInFromEntries(
+	entries: readonly { type: string; id?: string; customType?: string; data?: unknown; message?: { role?: string; timestamp?: number } }[],
+): Map<string, Mode> {
+	const byTime = new Map<number, Mode>();
+	for (const entry of entries) {
+		if (entry.type !== "custom" || entry.customType !== SENT_IN_ENTRY) continue;
+		const { at, mode } = (entry.data ?? {}) as { at?: unknown; mode?: unknown };
+		if (typeof at === "number" && typeof mode === "string" && REPORTED.test(`mode: ${mode}`)) byTime.set(at, mode as Mode);
+	}
+	const sent = new Map<string, Mode>();
+	for (const entry of entries) {
+		const mode = entry.type === "message" && entry.message?.role === "user" ? byTime.get(entry.message.timestamp ?? -1) : undefined;
+		if (mode !== undefined && entry.id !== undefined) sent.set(entry.id, mode);
+	}
+	return sent;
 }

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

@@ -1,6 +1,6 @@
 import { hostname } from "node:os";
 
-import type { AccountState, Board, PeerMark, RoomMark, WritingMark } from "@adeildo/pi-kit";
+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";

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

@@ -1,5 +1,5 @@
 // Under the folder and the model, only what changed or waits on you since the last session here.
-import { formatClock, GLYPH } from "@adeildo/pi-kit";
+import { formatClock, GLYPH } from "../kit/index.ts";
 
 import type { GithubState } from "./github.ts";
 import type { Snapshot } from "./snapshot.ts";

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

@@ -1,4 +1,4 @@
-import { type UsageLike } from "@adeildo/pi-kit";
+import { type UsageLike } from "../kit/index.ts";
 
 export {
 	emptyTotals,
@@ -7,7 +7,7 @@ export {
 	totalsOf,
 	type Totals,
 	usageTotals,
-} from "@adeildo/pi-kit";
+} from "../kit/index.ts";
 import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 
 export interface RequestRecord {

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

@@ -2,7 +2,7 @@
 import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 
-import { isObject } from "@adeildo/pi-kit";
+import { isObject } from "../kit/index.ts";
 
 import type { LastVisit } from "./start-notes.ts";
 

package/packages/frame/src/index.ts

@@ -17,18 +17,18 @@ import {
 	type SessionSource,
 	skillNames,
 	sourceFor,
-} from "@adeildo/pi-kit";
+} from "./kit/index.ts";
 import type {
 	ExtensionAPI,
 	ExtensionContext,
 	ReadonlyFooterDataProvider,
 } from "@earendil-works/pi-coding-agent";
-import { keyText } from "@earendil-works/pi-coding-agent";
+import { keyText, parseSkillBlock } from "@earendil-works/pi-coding-agent";
 import { Key, type KeyId, type TUI } from "@earendil-works/pi-tui";
 
 import { type GitState, readGit } from "./data/git.ts";
 import { cmdAsKey, SETTINGS_SHORTCUT, watchCmdKey } from "./render/keys.ts";
-import { frameColorOf } from "./data/mode.ts";
+import { frameColorOf, type Mode, modeOf, SENT_IN_ENTRY, sentInFromEntries } from "./data/mode.ts";
 import { type GithubState, readGithub } from "./data/github.ts";
 import { emptySnapshot, type LiveInputs, type Snapshot, SnapshotReader } from "./data/snapshot.ts";
 import type { LastVisit } from "./data/start-notes.ts";
@@ -126,6 +126,8 @@ export const frameFeature = defineFeature({
 		registerToolFrames(scope);
 		registerEffort(scope);
 		registerTodos(scope, () => glyphs().set);
+		const sentLive = new Map<string, Mode>();
+		let sentSaved = { length: -1, modes: new Map<string, Mode>() };
 		framePiEntries(() => {
 			if (live.ctx === undefined) return undefined;
 			return {
@@ -133,6 +135,12 @@ export const frameFeature = defineFeature({
 				set: glyphs().set,
 				you: userFrame.get(scope),
 				from: (text: string) => PROMPT_FROM.current(scope, text)?.name,
+				sentIn: (id: string | undefined, text: string) => {
+					if (id === undefined) return sentLive.get(text);
+					const entries = live.ctx?.sessionManager.getEntries() ?? [];
+					if (entries.length !== sentSaved.length) sentSaved = { length: entries.length, modes: sentInFromEntries(entries) };
+					return sentSaved.modes.get(id);
+				},
 			};
 		});
 		showTimings((message, width) => {
@@ -215,6 +223,8 @@ export const frameFeature = defineFeature({
 			live.ctx = ctx;
 			telemetry.reset();
 			telemetry.restore(ctx.sessionManager.getEntries());
+			sentLive.clear();
+			sentSaved = { length: -1, modes: new Map() };
 			void probeGit(live);
 			if (ctx.mode !== "tui") return;
 
@@ -242,6 +252,18 @@ export const frameFeature = defineFeature({
 			showHeader(ctx);
 		});
 
+		scope.on("message_start", (event) => {
+			if (event.message.role !== "user") return;
+			const mode = modeOf(live.footerData?.getExtensionStatuses() ?? new Map());
+			if (mode === undefined) return;
+			const { content, timestamp } = event.message;
+			const text = typeof content === "string" ? content : content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("");
+			// Pi draws a skill's message as only what you typed after it.
+			sentLive.set(parseSkillBlock(text)?.userMessage ?? text, mode);
+			// Normal draws as a plain message, so a resumed session needs nothing saved for it.
+			if (mode !== "normal") scope.appendEntry(SENT_IN_ENTRY, { at: timestamp, mode });
+		});
+
 		scope.onShutdown(() => {
 			stopCmdKeys?.();
 			stopCmdKeys = undefined;

package/packages/frame/src/kit/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 adeildo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/frame/src/kit/app/attribution.ts

@@ -0,0 +1,30 @@
+// In the harness every feature runs inside one extension, so pi reports every failure under the
+// same name. These put the app and the feature in front of it instead.
+
+export function describe(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+// A sync function stays sync, because pi treats some handler results differently when they are
+// promises.
+export function attributed<A extends unknown[], R>(
+	label: string,
+	run: (...args: A) => R,
+): (...args: A) => R {
+	return (...args: A): R => {
+		let result: R;
+		try {
+			result = run(...args);
+		} catch (error) {
+			throw relabel(label, error);
+		}
+		if (!(result instanceof Promise)) return result;
+		return result.catch((error: unknown) => {
+			throw relabel(label, error);
+		}) as R;
+	};
+}
+
+function relabel(label: string, error: unknown): Error {
+	return new Error(`${label}: ${describe(error)}`, { cause: error });
+}

package/packages/frame/src/kit/app/builder.ts

@@ -0,0 +1,186 @@
+// `createApp(pi, ...).use(feature).build()`. Registration happens only in the factory, session work
+// from `session_start`, cleanup once per session, and a feature that fails to set up is a warning.
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { CHANGED } from "../contracts/screen.ts";
+import { boolean, isObject } from "../decode.ts";
+import { settingsScreen } from "../screen/feature.ts";
+import { globalSettingsPath, projectSettingsPath } from "../settings/files.ts";
+import { type Setting, type SettingsScope, setting } from "../settings/setting.ts";
+import { SettingsStore } from "../settings/store.ts";
+import { describe } from "./attribution.ts";
+import { answerClaims, ownerOf } from "./claim.ts";
+import type { Feature } from "./feature.ts";
+import { serveScreen } from "./host.ts";
+import { type AppState, createScope, type Hook } from "./scope.ts";
+
+export interface App extends SettingsScope {
+	readonly name: string;
+	readonly settings: SettingsStore;
+	has(featureId: string): boolean;
+}
+
+export interface AppOptions {
+	name: string;
+	settingsPath?: string;
+}
+
+export interface AppBuilder {
+	use(feature: Feature): AppBuilder;
+	build(): App;
+}
+
+export function createApp(pi: ExtensionAPI, options: AppOptions): AppBuilder {
+	const features: Feature[] = [];
+	const builder: AppBuilder = {
+		use(feature) {
+			features.push(feature);
+			return builder;
+		},
+		build: () => mount(pi, options, features),
+	};
+	return builder;
+}
+
+export function enabledSetting(feature: Feature): Setting<boolean> {
+	return setting({
+		id: `features.${feature.id}.enabled`,
+		default: true,
+		decoder: boolean,
+	});
+}
+
+function mount(pi: ExtensionAPI, options: AppOptions, features: readonly Feature[]): App {
+	const settings = new SettingsStore(options.settingsPath ?? globalSettingsPath());
+	const mounted = new Set<string>();
+	const queued: string[] = [];
+	let session: ExtensionContext | undefined;
+	let live = true;
+
+	function deliver(line: string): void {
+		if (session === undefined) queued.push(line);
+		else if (session.hasUI) session.ui.notify(line, "warning");
+		else console.error(line);
+	}
+
+	const state: AppState = {
+		name: options.name,
+		pi,
+		settings,
+		mounted,
+		commands: new Map(),
+		starts: [],
+		shutdowns: [],
+		screen: new Map(),
+		screenGroups: new Map(),
+		live: () => live,
+		stop: () => {
+			live = false;
+		},
+		report: (source, message) => deliver(`${options.name}: ${source}: ${message}`),
+	};
+	const app: App = { name: options.name, settings, has: (id) => mounted.has(id) };
+	const running: Feature[] = [];
+
+	answerClaims(pi, options.name, mounted, () => live);
+	serveScreen({
+		pi,
+		settings,
+		features: () => running,
+		screen: state.screen,
+		screenGroups: state.screenGroups,
+		session: () => session,
+		isLive: () => live,
+	});
+
+	// Every app writes the same files, so a write by one is read again by the others.
+	const store = crypto.randomUUID();
+	settings.onWrite(() => pi.events.emit(CHANGED, { source: store }));
+	pi.events.on(CHANGED, (data) => {
+		if (!live || !isObject(data) || data.source === store) return;
+		for (const line of settings.load(settings.projectPath)) state.report("settings", line);
+	});
+
+	// Registered first, so these run ahead of the features' own handlers.
+	pi.on("session_start", async (_event, ctx) => {
+		live = true;
+		session = ctx;
+		for (const line of queued.splice(0)) deliver(line);
+		const project = ctx.isProjectTrusted() ? projectSettingsPath(ctx.cwd) : undefined;
+		for (const line of settings.load(project)) state.report("settings", line);
+		await runInOrder(
+			state.starts,
+			(run) => run(ctx),
+			(source, error) => {
+				state.report(source, `failed to start the session: ${describe(error)}`);
+			},
+		);
+	});
+
+	pi.on("session_shutdown", async () => {
+		if (!live) return;
+		// Before the hooks: a hook stops a service, and a timer left running would read it after.
+		state.stop();
+		await runInOrder(
+			state.shutdowns.toReversed(),
+			(run) => run(),
+			(source, error) => {
+				state.report(source, `failed to shut down: ${describe(error)}`);
+			},
+		);
+		session = undefined;
+	});
+
+	// All the switches first, so one read of the file decides what is on.
+	const candidates: { feature: Feature; enabled: Setting<boolean> }[] = [];
+	for (const feature of [settingsScreen, ...features]) {
+		if (candidates.some((candidate) => candidate.feature.id === feature.id)) {
+			state.report(feature.id, "was added to this app twice; keeping the first");
+			continue;
+		}
+		const enabled = enabledSetting(feature);
+		try {
+			settings.register([enabled, ...(feature.settings ?? [])]);
+			candidates.push({ feature, enabled });
+		} catch (error) {
+			state.report(feature.id, `failed to set up: ${describe(error)}`);
+		}
+	}
+
+	for (const { feature, enabled } of candidates) {
+		if (!enabled.get(app)) continue;
+
+		const owner = ownerOf(pi, feature.id);
+		if (owner !== undefined) {
+			// Every app brings the screen, and one is enough.
+			if (feature !== settingsScreen)
+				state.report(feature.id, `already loaded by ${owner}, so this copy stays off`);
+			continue;
+		}
+
+		try {
+			feature.setup(createScope(state, feature.id));
+			mounted.add(feature.id);
+			running.push(feature);
+		} catch (error) {
+			state.report(feature.id, `failed to set up: ${describe(error)}`);
+		}
+	}
+
+	return app;
+}
+
+async function runInOrder<T>(
+	hooks: readonly Hook<T>[],
+	call: (run: T) => void | Promise<void>,
+	failed: (source: string, error: unknown) => void,
+): Promise<void> {
+	for (const hook of hooks) {
+		try {
+			// oxlint-disable-next-line no-await-in-loop -- the order is the point
+			await call(hook.run);
+		} catch (error) {
+			failed(hook.source, error);
+		}
+	}
+}

package/packages/frame/src/kit/app/claim.ts

@@ -0,0 +1,27 @@
+// An app asks the others on pi.events whether one already runs a feature, so the harness and a
+// standalone copy never run it twice. The bus is synchronous, so the answer is written on the payload.
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { isObject, object, string } from "../decode.ts";
+
+const CHANNEL = "harness:kit:claim";
+const claimShape = object({ feature: string });
+
+export function answerClaims(
+	pi: ExtensionAPI,
+	appName: string,
+	mounted: ReadonlySet<string>,
+	isLive: () => boolean,
+): void {
+	pi.events.on(CHANNEL, (data) => {
+		const claim = claimShape.decode(data, "");
+		if (!isLive() || !claim.ok || !isObject(data) || data.owner !== undefined) return;
+		if (mounted.has(claim.value.feature)) data.owner = appName;
+	});
+}
+
+export function ownerOf(pi: ExtensionAPI, featureId: string): string | undefined {
+	const claim: { feature: string; owner?: unknown } = { feature: featureId };
+	pi.events.emit(CHANNEL, claim);
+	return typeof claim.owner === "string" ? claim.owner : undefined;
+}

package/packages/frame/src/kit/app/feature.ts

@@ -0,0 +1,91 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	RegisteredCommand,
+} from "@earendil-works/pi-coding-agent";
+
+import type { Control, Json } from "../control.ts";
+import type { Setting, SettingsScope } from "../settings/setting.ts";
+import type { SettingsStore } from "../settings/store.ts";
+
+export type SessionHook = (ctx: ExtensionContext) => void | Promise<void>;
+export type ShutdownHook = () => void | Promise<void>;
+export type CommandOptions = Omit<RegisteredCommand, "name" | "sourceInfo">;
+
+export interface Feature {
+	/** Unique across every package, like `subscription`. It names the feature's settings too. */
+	id: string;
+	description: string;
+	/** The settings tab. Features with the same tab share it. Defaults to the id. */
+	tab?: string;
+	/** Section order on the tab. Sections not listed come after. A function runs when the screen opens. */
+	sections?: readonly string[] | ((ctx: ExtensionContext | undefined) => readonly string[]);
+	settings?: readonly Setting<unknown>[];
+	setup(scope: FeatureScope): void;
+}
+
+/** Extends `ExtensionAPI`, since reading it through another type collapses pi's per-event overloads. */
+export interface FeatureScope extends ExtensionAPI, SettingsScope {
+	readonly id: string;
+	readonly settings: SettingsStore;
+	onSessionStart(hook: SessionHook): void;
+	/** Runs once per session, newest first. */
+	onShutdown(hook: ShutdownHook): void;
+	/** Runs once after `ms`, never after the session ends; cancelled before any shutdown hook runs. */
+	defer(run: () => void, ms?: number): void;
+	/** Shown as `<app>: <feature>: <message>`. */
+	warn(message: string): void;
+	has(featureId: string): boolean;
+	readonly screen: ScreenRows;
+}
+
+interface ScreenRow {
+	id: string;
+	section: string;
+	label: string;
+	description: string;
+	/** How deep the row sits under its section. Each step indents two columns. */
+	indent?: number;
+}
+
+export interface ScreenValue extends ScreenRow {
+	control: Control | ((ctx: ExtensionContext) => Control);
+	get(ctx: ExtensionContext): Json;
+	/** Returns why the value was refused. */
+	set(value: Json, ctx: ExtensionContext): string | undefined;
+	/** Where the value applies, when that is not this session. */
+	meta?: string;
+	/** What the row shows in place of the value, like a count for a list. Undefined shows the value. */
+	text?(ctx: ExtensionContext): string | undefined;
+}
+
+export interface ScreenAction extends ScreenRow {
+	text?(ctx: ExtensionContext): string;
+	confirm?: string;
+	/** Returned text opens in the screen. A throw shows as an error. */
+	run(ctx: ExtensionContext): string | undefined | Promise<string | undefined>;
+}
+
+export interface ScreenInfo extends ScreenRow {
+	text(ctx: ExtensionContext): string;
+}
+
+export type ScreenEntry =
+	| ({ kind: "value" } & ScreenValue)
+	| ({ kind: "action" } & ScreenAction)
+	| ({ kind: "info" } & ScreenInfo);
+
+/** Rows a feature builds when the screen opens, for what is only known then. */
+export type ScreenGroup = (ctx: ExtensionContext) => ScreenEntry[];
+
+export interface ScreenRows {
+	value(row: ScreenValue): void;
+	action(row: ScreenAction): void;
+	info(row: ScreenInfo): void;
+	/** One call, many rows: the provider runs every time the screen opens. */
+	rows(provider: ScreenGroup): void;
+}
+
+export function defineFeature(feature: Feature): Feature {
+	return feature;
+}