pi-squire 0.15.0 → 0.17.0

package/src/completion-holds.ts

@@ -0,0 +1,104 @@
+// Process-local completion composition. Providers own hold readiness; Squire
+// advertises only its active exact-session runtime and never owns provider rows.
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const KEY: symbol = Symbol.for("pi.completion-holds.v1");
+type Hold = { provider: string; ready: boolean };
+type Table = {
+	version: 1;
+	hosts: Map<string, Map<string, string>>;
+	holds: Map<string, Map<string, Hold>>;
+};
+const shared: Record<symbol, unknown> = globalThis as unknown as Record<symbol, unknown>;
+
+function table(create: boolean): Table | undefined {
+	const value: unknown = shared[KEY];
+	if (value === undefined) {
+		if (!create) return undefined;
+		const fresh: Table = { version: 1, hosts: new Map(), holds: new Map() };
+		shared[KEY] = fresh;
+		return fresh;
+	}
+	if (
+		typeof value !== "object" ||
+		value === null ||
+		!("version" in value) ||
+		value.version !== 1 ||
+		!("hosts" in value) ||
+		!(value.hosts instanceof Map) ||
+		!("holds" in value) ||
+		!(value.holds instanceof Map)
+	)
+		throw new Error("invalid pi.completion-holds.v1 table; completion is blocked");
+	return value as Table;
+}
+
+function validHosts(hosts: unknown): hosts is Map<string, string> {
+	return (
+		hosts instanceof Map &&
+		[...hosts].every(
+			([name, runtime]) => typeof name === "string" && !!name && typeof runtime === "string" && !!runtime,
+		)
+	);
+}
+
+/** Missing table/no holds preserves normal completion; malformed data refuses. */
+export function externalHoldsReady(sessionId: string): boolean {
+	try {
+		const current: Table | undefined = table(false);
+		if (!current) return true;
+		const hosts: unknown = current.hosts.get(sessionId);
+		if (hosts !== undefined && !validHosts(hosts)) return false;
+		const holds: Map<string, Hold> | undefined = current.holds.get(sessionId);
+		if (holds === undefined) return true;
+		if (!(holds instanceof Map)) return false;
+		for (const [id, hold] of holds) {
+			if (
+				typeof id !== "string" ||
+				!id ||
+				typeof hold !== "object" ||
+				hold === null ||
+				typeof hold.provider !== "string" ||
+				!hold.provider ||
+				hold.ready !== true
+			)
+				return false;
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function removeHost(sessionId: string, token: string): void {
+	// Clean our own token even if another field/version has become malformed.
+	const value: unknown = shared[KEY];
+	if (typeof value !== "object" || value === null || !("hosts" in value) || !(value.hosts instanceof Map)) return;
+	const hosts: unknown = value.hosts.get(sessionId);
+	if (!(hosts instanceof Map) || hosts.get("pi-squire") !== token) return;
+	hosts.delete("pi-squire");
+	if (hosts.size === 0) value.hosts.delete(sessionId);
+}
+
+/** Call with ownedAPI: a losing duplicate runtime must never advertise support. */
+export function registerCompletionHost(pi: ExtensionAPI): () => boolean {
+	const token: string = randomUUID();
+	let sessionId: string | undefined;
+	pi.on("session_start", (_event, ctx) => {
+		if (sessionId !== undefined) removeHost(sessionId, token);
+		sessionId = ctx.sessionManager.getSessionId();
+		const current: Table | undefined = table(true);
+		if (!current) throw new Error("completion hold table is unavailable");
+		const saved: Map<string, string> | undefined = current.hosts.get(sessionId);
+		if (saved !== undefined && !validHosts(saved)) throw new Error("invalid completion hold hosts");
+		const hosts: Map<string, string> = saved ?? new Map();
+		hosts.set("pi-squire", token);
+		current.hosts.set(sessionId, hosts);
+	});
+	pi.on("session_shutdown", () => {
+		if (sessionId !== undefined) removeHost(sessionId, token);
+		sessionId = undefined;
+	});
+	return (): boolean => sessionId !== undefined && externalHoldsReady(sessionId);
+}

package/src/dashboard.ts

@@ -0,0 +1,144 @@
+// Presentation only. The navigator resolves these opaque ids and owns every action/refusal.
+import { type Component, isKeyRelease, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+import { type WidgetTheme, widgetText } from "./widget-render.ts";
+
+export type DashboardRow = { id: string; label: string; details: readonly string[]; depth?: number };
+export type DashboardIntent =
+	| { action: "switch" | "close" | "peek" | "resume"; id: string }
+	| { action: "new" }
+	| { action: "close-all" }
+	| undefined;
+export type DashboardPosition = { id?: string; detail: boolean; offset: number; branchList?: boolean };
+type DashboardOptions = {
+	items: readonly DashboardRow[];
+	root?: boolean;
+	branch?: string;
+	position: DashboardPosition;
+	detailBack: "list" | "exit";
+	theme: WidgetTheme;
+	done(result: DashboardIntent): void;
+	redraw(): void;
+	rows(): number;
+};
+
+function label(row: DashboardRow): string {
+	return "  ".repeat(Math.max(0, Math.min(64, row.depth ?? 0))) + widgetText(row.label);
+}
+
+/** One screen used by command and widget entry, with durable position across action dialogs. */
+export class Dashboard implements Component {
+	private readonly options: DashboardOptions;
+
+	constructor(options: DashboardOptions) {
+		this.options = options;
+		const found: boolean = options.items.some((row) => row.id === options.position.id);
+		if (!found) {
+			options.position.id = options.items[0]?.id;
+			options.position.offset = 0;
+			options.position.detail = false;
+		}
+	}
+
+	invalidate(): void {}
+
+	private selected(): DashboardRow | undefined {
+		return this.options.items.find((row) => row.id === this.options.position.id);
+	}
+
+	handleInput(data: string): void {
+		if (isKeyRelease(data)) return;
+		const { position, done } = this.options;
+		if (matchesKey(data, "escape")) {
+			if (position.detail && (this.options.detailBack === "list" || position.branchList)) {
+				position.detail = false;
+				position.offset = 0;
+			} else done(undefined);
+		} else if (matchesKey(data, "b") && this.options.branch !== undefined) {
+			position.branchList = true;
+			position.detail = false;
+			position.offset = 0;
+		} else if (matchesKey(data, "n")) done({ action: "new" });
+		else if (matchesKey(data, "a") && this.options.root) done({ action: "close-all" });
+		else if (matchesKey(data, "up")) this.move(-1);
+		else if (matchesKey(data, "down")) this.move(1);
+		else this.action(data);
+		this.options.redraw();
+	}
+
+	private action(data: string): void {
+		const item: DashboardRow | undefined = this.selected();
+		if (!item) return;
+		const { position, done } = this.options;
+		if (matchesKey(data, "enter")) {
+			if (position.detail) done({ action: "switch", id: item.id });
+			else {
+				position.detail = true;
+				position.offset = 0;
+			}
+		} else if (matchesKey(data, "p")) done({ action: "peek", id: item.id });
+		else if (matchesKey(data, "x")) done({ action: "close", id: item.id });
+		else if (matchesKey(data, "r")) done({ action: "resume", id: item.id });
+	}
+
+	private move(direction: -1 | 1): void {
+		const { items, position } = this.options;
+		if (position.detail) {
+			const max: number = Math.max(0, (this.selected()?.details.length ?? 0) - this.height());
+			position.offset = Math.max(0, Math.min(max, position.offset + direction));
+			return;
+		}
+		const index: number = items.findIndex((row) => row.id === position.id);
+		position.id = items[Math.max(0, Math.min(items.length - 1, index + direction))]?.id;
+	}
+
+	private height(): number {
+		return Math.max(1, this.options.rows() - 6);
+	}
+
+	render(width: number): string[] {
+		const { items, position, theme } = this.options;
+		const fit = (text: string): string => truncateToWidth(text, Math.max(0, width));
+		const item: DashboardRow | undefined = this.selected();
+		if (!item)
+			return [theme.bold(this.heading()), "", `No open delegates · n new · esc close${this.closeAllHint()}`].map(fit);
+		if (position.detail) return this.details(item).map(fit);
+		const index: number = items.indexOf(item);
+		const start: number = Math.max(0, index - this.height() + 1);
+		const rows: string[] = items
+			.slice(start, start + this.height())
+			.map((row) => (row.id === item.id ? theme.fg("accent", `▸ ${label(row)}`) : `  ${label(row)}`));
+		return [
+			theme.bold(this.heading()),
+			"",
+			...rows,
+			`${index + 1}/${items.length}`,
+			theme.fg(
+				"dim",
+				`↑↓ select · enter details · p peek · x close · r resume · n new · esc leave${this.closeAllHint()}`,
+			),
+		].map(fit);
+	}
+
+	private heading(): string {
+		return this.options.branch === undefined ? "Delegates" : `Delegate branch: ${widgetText(this.options.branch)}`;
+	}
+
+	private closeAllHint(): string {
+		if (!this.options.root) return "";
+		return this.options.branch === undefined ? " · a close all subtrees" : " · a close ALL ROOT subtrees";
+	}
+
+	private details(item: DashboardRow): string[] {
+		const { position, theme } = this.options;
+		return [
+			theme.bold(`Delegate: ${widgetText(item.label)}`),
+			"",
+			...item.details.slice(position.offset, position.offset + this.height()).map(widgetText),
+			"",
+			theme.fg(
+				"dim",
+				`↑↓ scroll · enter switch · p peek · x close · r resume · n new · esc back${this.options.branch === undefined ? "" : " · b branch list"}${this.closeAllHint()}`,
+			),
+		];
+	}
+}

package/src/git.ts

@@ -126,7 +126,12 @@ function identify(cwd: string): { identity: GitIdentity } | { launch: GitLaunch
 	// One question per path, so no output is split on a newline a path may contain.
 	const top = askGit(cwd, ["rev-parse", "--show-toplevel"]);
 	if (!top.ok) {
-		if (top.status === 128 && /not a git repository/i.test(top.message)) return { launch: { kind: "non-git" } };
+		if (
+			top.status === 128 &&
+			/not a git repository [(]or any (?:of the parent directories|parent up to mount point)/i.test(top.message)
+		) {
+			return { launch: { kind: "non-git" } };
+		}
 		return { launch: { kind: "unknown", reason: `git rev-parse failed: ${top.message}` } };
 	}
 	const common = askGit(cwd, ["rev-parse", "--git-common-dir"]);

package/src/identity.ts

@@ -0,0 +1,152 @@
+// Launch identity is session-local durable state, not the shared tree registry.
+// Readers (trust routing, caps and views) use session ids for routing; chain is
+// ordered roster names for labels only. A resume retains the original identity.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type ExtensionAPI, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { Agent, Roster } from "./agents.ts";
+import { readState, writeState } from "./local-state.ts";
+import { assertRootPlacement } from "./window-placement.ts";
+
+export const DELEGATION_TOOLS = ["delegate", "delegation_status", "delegation_close", "delegation_resume"] as const;
+export type Identity = {
+	parent: string;
+	root: string;
+	/** Original root project's preferred companion base, inherited unchanged. */
+	rootPlacement: string;
+	depth: number;
+	agent: string;
+	chain: string[];
+	autoExit: boolean;
+};
+/** Public, immutable exact-session observation; no internal placement or exit state. */
+export type IdentityNotification =
+	| Readonly<{ sessionId: string; status: "root" | "invalid" }>
+	| Readonly<{
+			sessionId: string;
+			status: "delegate";
+			identity: Readonly<{
+				parent: string;
+				root: string;
+				agent: string;
+				chain: readonly string[];
+				depth: number;
+			}>;
+	  }>;
+const pathFor = (session: string): string =>
+	join(getAgentDir(), "squire", "identity", `${encodeURIComponent(session)}.json`);
+export function readIdentity(session: string): Identity | undefined {
+	const value = readState<Identity>(pathFor(session));
+	if (value === undefined) return undefined;
+	if (
+		!value ||
+		typeof value.parent !== "string" ||
+		!value.parent ||
+		typeof value.root !== "string" ||
+		!value.root ||
+		!Number.isSafeInteger(value.depth) ||
+		value.depth < 1 ||
+		typeof value.agent !== "string" ||
+		!Array.isArray(value.chain) ||
+		!value.chain.every((name) => typeof name === "string") ||
+		typeof value.autoExit !== "boolean"
+	)
+		throw new Error(`invalid delegation identity for ${session}; repair its squire/identity record before reopening`);
+	assertRootPlacement(value.rootPlacement);
+	return value;
+}
+export const writeIdentity = (session: string, identity: Identity): void => writeState(pathFor(session), identity);
+
+export function maxDepth(): number {
+	const file = join(getAgentDir(), "squire", "settings.json");
+	let settings: { maxDepth?: unknown };
+	try {
+		settings = JSON.parse(readFileSync(file, "utf8")) as typeof settings;
+	} catch {
+		// Match existing settings readers: an unreadable file grants only the
+		// safe single-level default; a readable invalid maxDepth refuses.
+		return 1;
+	}
+	const value = settings?.maxDepth ?? 1;
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
+		throw new Error(`invalid maxDepth in ${file}: expected a positive integer`);
+	return value;
+}
+
+export function grantsNesting(agent: Agent, depth: number): boolean {
+	return (agent.allowNested === true || (agent.allowNested?.length ?? 0) > 0) && depth < maxDepth();
+}
+
+export function createIdentity(pi: ExtensionAPI): {
+	current(): Identity | undefined;
+	child(agent: Agent, ctx: ExtensionContext, rootPlacement: string): Identity;
+	admit(agent: string, roster: Roster): void;
+} {
+	// Launch writes exact-id identity before spawn. Inherited environment is
+	// labels for integrations, never authority for a new/forked session.
+	let current: Identity | undefined;
+	let problem: unknown;
+	pi.on("session_start", (_event, ctx) => {
+		const sessionId = ctx.sessionManager.getSessionId();
+		current = undefined;
+		problem = undefined;
+		try {
+			const restored = readIdentity(sessionId);
+			if (restored) writeIdentity(sessionId, restored);
+			current = restored;
+		} catch (error) {
+			problem = error;
+		}
+		const notification: IdentityNotification = current
+			? Object.freeze({
+					sessionId,
+					status: "delegate",
+					identity: Object.freeze({
+						parent: current.parent,
+						root: current.root,
+						agent: current.agent,
+						chain: Object.freeze([...current.chain]),
+						depth: current.depth,
+					}),
+				})
+			: Object.freeze({ sessionId, status: problem ? "invalid" : "root" });
+		// Synchronous listeners run before later session_start handlers or async work.
+		// This is a notification, not a gate or listener-success acknowledgement.
+		pi.events.emit("squire:identity", notification);
+		if (problem)
+			ctx.ui.notify(
+				`delegate: could not restore delegation identity: ${String(problem)}; launches and completion are blocked.`,
+				"error",
+			);
+	});
+	return {
+		current: () => {
+			if (problem) throw problem;
+			return current;
+		},
+		child: (agent: Agent, ctx: ExtensionContext, rootPlacement: string): Identity => ({
+			parent: ctx.sessionManager.getSessionId(),
+			root: current?.root ?? ctx.sessionManager.getSessionId(),
+			rootPlacement: current?.rootPlacement ?? rootPlacement,
+			depth: (current?.depth ?? 0) + 1,
+			agent: agent.name,
+			chain: [...(current?.chain ?? []), agent.name],
+			autoExit: agent.autoExit,
+		}),
+		admit: (agent: string, roster: Roster): void => {
+			if (problem) throw problem;
+			const limit = maxDepth();
+			if (!current) return;
+			if (!Number.isSafeInteger(current.depth) || current.depth < 1 || current.depth >= limit)
+				throw new Error(
+					`nested delegation refused at depth ${current.depth}: maxDepth is ${limit} in squire/settings.json`,
+				);
+			const own = roster.agents.find((item) => item.name === current?.agent);
+			const grant = own?.allowNested;
+			if (grant === true || (Array.isArray(grant) && grant.includes(agent))) return;
+			throw new Error(
+				`agent ${JSON.stringify(current.agent)} does not permit nested agent ${JSON.stringify(agent)}; permitted agents: ${Array.isArray(grant) && grant.length ? grant.join(", ") : "none"}. Set allow_nested_delegation in the parent's current agent definition.`,
+			);
+		},
+	};
+}