gentle-pi 2.4.0 → 2.6.0

package/lib/review-consent-component.ts

@@ -0,0 +1,247 @@
+import {
+	isKeyRelease,
+	matchesKey,
+	type KeybindingsManager,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+
+export interface ReviewConsentAction {
+	readonly label: string;
+	readonly effect: string;
+}
+
+export interface ReviewConsentContent {
+	readonly headline: string;
+	readonly reason: string;
+	readonly value: string;
+	readonly risk: string;
+	readonly target: string;
+	readonly projection: string;
+	readonly evidence: readonly string[];
+	readonly ownership: string;
+	readonly offPathNote: string;
+	readonly offPathCommand: string;
+	readonly actions: readonly [ReviewConsentAction, ReviewConsentAction, ReviewConsentAction];
+}
+
+export interface ReviewConsentComponentTheme {
+	fg(color: "accent" | "dim" | "mdHeading" | "muted", text: string): string;
+	bold(text: string): string;
+}
+
+export interface ReviewConsentComponentOptions {
+	readonly content: ReviewConsentContent;
+	readonly theme: ReviewConsentComponentTheme;
+	readonly keybindings: KeybindingsManager | undefined;
+	readonly terminalRows: () => number;
+	readonly onSelect: (index: number) => void;
+	readonly onCancel: () => void;
+}
+
+type LineKind = "body" | "header" | "action";
+interface Line { text: string; kind: LineKind; action?: number; }
+
+function wrap(prefix: string, text: string, width: number): string[] {
+	if (width <= prefix.length) return wrapTextWithAnsi(prefix + text, width);
+	const indent = " ".repeat(prefix.length);
+	return wrapTextWithAnsi(text, width - prefix.length).map((line, index) => index === 0 ? prefix + line : indent + line);
+}
+
+export class ReviewConsentComponent {
+	private readonly options: ReviewConsentComponentOptions;
+	private selected = 0;
+	private mode: "actions" | "details" = "actions";
+	private detailsScroll = 0;
+	private actionScroll = 0;
+	private actionLines: Line[] = [];
+	private actionRanges: Array<{ start: number; end: number }> = [];
+	private details: Line[] = [];
+	private bodyHeight = 1;
+	private contextHeight = 1;
+	private actionHeight = 1;
+	private renderedWidth: number | undefined;
+	private renderedRows: number | undefined;
+	private canConfirm = false;
+
+	constructor(options: ReviewConsentComponentOptions) {
+		this.options = options;
+	}
+
+	getActionOptions(): readonly string[] {
+		return this.options.content.actions.map((action, index) => `${index + 1}. ${action.label}\nEffect: ${action.effect}`);
+	}
+
+	handleInput(data: string): void {
+		if (isKeyRelease(data)) return;
+		if (this.matches(data, "tui.select.cancel")) return this.options.onCancel();
+		if (data === "d" || data === "D") {
+			this.mode = this.mode === "actions" ? "details" : "actions";
+			this.detailsScroll = 0;
+			this.canConfirm = false;
+			return;
+		}
+		if (this.matches(data, "tui.select.confirm")) {
+			if (this.mode === "actions" && this.canConfirm) this.options.onSelect(this.selected);
+			return;
+		}
+		if (this.mode === "actions") {
+			if (this.matches(data, "tui.select.up")) this.moveSelection(-1);
+			else if (this.matches(data, "tui.select.down")) this.moveSelection(1);
+			return;
+		}
+		if (this.matches(data, "tui.select.up") || matchesKey(data, "pageUp")) this.detailsScroll -= this.matches(data, "tui.select.up") ? 1 : this.step();
+		else if (this.matches(data, "tui.select.down") || matchesKey(data, "pageDown")) this.detailsScroll += this.matches(data, "tui.select.down") ? 1 : this.step();
+		this.canConfirm = false;
+	}
+
+	render(width: number): string[] {
+		const safeWidth = Math.max(1, width);
+		const rows = Math.max(1, this.options.terminalRows());
+		if (this.renderedWidth !== safeWidth || this.renderedRows !== rows) {
+			this.renderedWidth = safeWidth;
+			this.renderedRows = rows;
+			this.canConfirm = false;
+		}
+		const actions = this.buildActions(safeWidth);
+		this.actionLines = actions.lines;
+		this.actionRanges = actions.ranges;
+		this.details = this.buildDetails(safeWidth);
+		if (this.mode === "details") return this.renderDetailsScreen(safeWidth, rows);
+		if (rows < 8) return this.renderCompact(safeWidth, rows);
+		this.bodyHeight = rows;
+		return this.renderScreen(safeWidth).slice(0, rows);
+	}
+
+	invalidate(): void {}
+
+	private renderScreen(width: number): string[] {
+		const title = wrapTextWithAnsi("Review consent", width).map((line) => this.options.theme.fg("mdHeading", this.options.theme.bold(line)));
+		const wrappedHeadline = wrapTextWithAnsi(this.options.content.headline, width);
+		const question = this.options.content.headline === "Review consent" || wrappedHeadline.length > 2 ? [] : wrappedHeadline;
+		const reason = wrapTextWithAnsi(this.options.content.reason, width);
+		const footer = wrapTextWithAnsi("↑↓ choose · Enter confirm · Esc cancel · D details", width).map((line) => this.options.theme.fg("dim", line));
+		const primary = [...title, ...question, ...this.actionLines.map((line) => this.style(line)), "", ...footer];
+		const lines = [...title, ...question, ...reason, ...this.actionLines.map((line) => this.style(line)), "", ...footer];
+		const height = Math.min(20, this.bodyHeight);
+		if (lines.length > height) {
+			if (primary.length <= height) {
+				this.canConfirm = true;
+				return primary;
+			}
+			this.canConfirm = false;
+			return [...title, ...this.safeActions(width).map((line) => this.style(line))];
+		}
+		this.canConfirm = true;
+		return lines;
+	}
+
+	private renderDetailsScreen(width: number, rows: number): string[] {
+		const title = wrapTextWithAnsi("Details (read-only)", width).map((line) => this.options.theme.fg("mdHeading", this.options.theme.bold(line)));
+		const footer = wrapTextWithAnsi("PgUp/PgDn · D return · Esc", width).map((line) => this.options.theme.fg("dim", line));
+		const height = rows - title.length - footer.length;
+		if (height < 1) return wrapTextWithAnsi("Details; resize; D return; Esc cancel.", width).slice(0, rows);
+		this.contextHeight = height;
+		this.detailsScroll = Math.max(0, Math.min(this.detailsScroll, Math.max(0, this.details.length - height)));
+		return [...title, ...this.renderDetails(height), ...footer];
+	}
+
+	private renderActions(width: number, height: number): string[] {
+		const range = this.actionRanges[this.selected];
+		if (!range || range.end - range.start + 1 > height) {
+			this.canConfirm = false;
+			return this.safeActions(width).slice(0, height).map((line) => this.style(line));
+		}
+		if (range.start < this.actionScroll) this.actionScroll = range.start;
+		if (range.end >= this.actionScroll + height) this.actionScroll = range.end - height + 1;
+		this.actionScroll = Math.max(0, Math.min(this.actionScroll, Math.max(0, this.actionLines.length - height)));
+		this.canConfirm = range.start >= this.actionScroll && range.end < this.actionScroll + height;
+		return this.actionLines.slice(this.actionScroll, this.actionScroll + height).map((line) => this.style(line));
+	}
+
+	private renderDetails(height: number): string[] {
+		this.detailsScroll = Math.max(0, Math.min(this.detailsScroll, Math.max(0, this.details.length - height)));
+		return this.details.slice(this.detailsScroll, this.detailsScroll + height).map((line) => this.style(line));
+	}
+
+	private renderCompact(width: number, rows: number): string[] {
+		this.canConfirm = false;
+		return this.safeActions(width).slice(0, rows).map((line) => this.style(line));
+	}
+
+	private renderTiny(width: number, rows: number): string[] {
+		this.canConfirm = false;
+		return wrapTextWithAnsi("Resize; Esc cancel; Enter off.", width).slice(0, rows);
+	}
+
+	private buildActions(width: number): { lines: Line[]; ranges: Array<{ start: number; end: number }> } {
+		const lines: Line[] = [];
+		const ranges: Array<{ start: number; end: number }> = [];
+		const add = (prefix: string, text: string, kind: LineKind = "body", action?: number) => {
+			for (const value of wrap(prefix, text, width)) lines.push({ text: value, kind, action });
+		};
+		for (const [index, action] of this.options.content.actions.entries()) {
+			const start = lines.length;
+			add(`${index === this.selected ? "→ " : "  "}${index + 1}. `, action.label, "action", index);
+			ranges.push({ start, end: lines.length - 1 });
+		}
+		lines.push({ text: "", kind: "body" });
+		add("Effect: ", this.options.content.actions[this.selected].effect, "action", this.selected);
+		return { lines, ranges };
+	}
+
+	private safeActions(width: number): Line[] {
+		return [
+			...wrap("", "Resize; Esc cancel; Enter off.", width).map((text) => ({ text, kind: "body" as const })),
+			...wrap("", `Action ${this.selected + 1}/3 needs its full effect.`, width).map((text) => ({ text, kind: "action" as const, action: this.selected })),
+			...wrap("", "D opens details.", width).map((text) => ({ text, kind: "body" as const })),
+		];
+	}
+
+	private buildDetails(width: number): Line[] {
+		const lines: Line[] = [];
+		const add = (prefix: string, text: string, kind: LineKind = "body") => {
+			for (const value of wrap(prefix, text, width)) lines.push({ text: value, kind });
+		};
+		add("Provider headline: ", this.options.content.headline);
+		add("Reason: ", this.options.content.reason);
+		add("Value: ", this.options.content.value);
+		add("Risk: ", this.options.content.risk);
+		add("Target: ", this.options.content.target);
+		add("Projection: ", this.options.content.projection);
+		add("", "Risk evidence:");
+		for (const item of this.options.content.evidence) add("  - ", item);
+		add("Ownership: ", this.options.content.ownership);
+		add("Off-path note: ", this.options.content.offPathNote);
+		add("Off-path command: ", this.options.content.offPathCommand);
+		add("", "Action consequences (read-only):", "header");
+		for (const action of this.options.content.actions) {
+			add("Action: ", action.label);
+			add("Effect: ", action.effect);
+			lines.push({ text: "", kind: "body" });
+		}
+		return lines;
+	}
+
+	private moveSelection(delta: number): void {
+		this.selected = Math.max(0, Math.min(2, this.selected + delta));
+		this.canConfirm = false;
+	}
+
+	private style(line: Line): string {
+		if (line.kind === "header") return this.options.theme.fg("accent", this.options.theme.bold(line.text));
+		if (line.kind === "action" && line.action === this.selected) return this.options.theme.fg("accent", line.text);
+		return line.text;
+	}
+
+	private step(): number {
+		return Math.max(1, this.contextHeight - 1);
+	}
+
+	private matches(data: string, binding: "tui.select.up" | "tui.select.down" | "tui.select.confirm" | "tui.select.cancel"): boolean {
+		if (this.options.keybindings) return this.options.keybindings.matches(data, binding);
+		const key = binding === "tui.select.up" ? "up"
+			: binding === "tui.select.down" ? "down"
+				: binding === "tui.select.confirm" ? "enter" : "escape";
+		return matchesKey(data, key);
+	}
+}

package/lib/review-consent-ui.ts

@@ -0,0 +1,110 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ReviewConsentComponent, type ReviewConsentContent } from "./review-consent-component.ts";
+import type { ReviewConsentEnvelope, ReviewConsentV3 } from "./review-integration-v2.ts";
+
+export const HOST_REVIEW_SESSION_PERMISSION_LABEL = "Review and allow this session";
+
+const HOST_REVIEW_SESSION_PERMISSION_EFFECT =
+	"Reviews this change and allows later reviews in this session and repository; revoke anytime.";
+
+const HOST_REVIEW_SESSION_PERMISSION_OWNERSHIP =
+	"The first two actions are provider-owned and apply only to this candidate. The third action is owned by the Pi host. It runs the current provider grant for this frozen candidate and lets the host use one fresh validated provider grant for each later candidate while this exact Pi session and canonical Git repository identity, including sibling worktrees, remain active. Reload preserves it; new, resume, fork, quit, process restart, or explicit revocation ends it. It grants no verdict, acknowledgement, maintenance, delivery, or cross-repository authority.";
+
+export type ReviewConsentUiSelection =
+	| { kind: "provider"; answer: "granted" | "declined" }
+	| { kind: "host-session" };
+
+export interface ReviewConsentUiModel {
+	readonly title: string;
+	readonly options: readonly [string, string, string];
+	readonly content: ReviewConsentContent;
+}
+
+export function isPiConsentV3(consent: ReviewConsentEnvelope): consent is ReviewConsentV3 {
+	return consent.schema === "gentle-ai.review-integration.consent/v3" && consent.agent === "pi";
+}
+
+export function formatReviewConsentUi(consent: ReviewConsentV3): ReviewConsentUiModel {
+	const evidence = consent.riskEvidence.map((item) => `- ${item}`).join("\n");
+	const title = [
+		consent.headline,
+		"",
+		`Reason: ${consent.reason}`,
+		`Value: ${consent.value}`,
+		`Risk: ${consent.riskLevel}; ${consent.changedFiles} changed file(s), ${consent.changedLines} changed line(s).`,
+		`Target: ${consent.targetIdentity}`,
+		`Projection: ${consent.projection}`,
+		"Risk evidence:",
+		evidence,
+		"",
+		`Ownership: ${HOST_REVIEW_SESSION_PERMISSION_OWNERSHIP}`,
+		"",
+		`Off-path note: ${consent.offPath.note}`,
+		`Off-path command: ${consent.offPath.command}`,
+	].join("\n");
+	const options = [
+		`1. ${consent.choices[0].label}\nEffect: ${consent.choices[0].effect}`,
+		`2. ${consent.choices[1].label}\nEffect: ${consent.choices[1].effect}`,
+		`3. ${HOST_REVIEW_SESSION_PERMISSION_LABEL}\nEffect: ${HOST_REVIEW_SESSION_PERMISSION_EFFECT}`,
+	] as const;
+	return {
+		title,
+		options,
+		content: {
+			headline: consent.headline,
+			reason: consent.reason,
+			value: consent.value,
+			risk: `${consent.riskLevel}; ${consent.changedFiles} changed file(s), ${consent.changedLines} changed line(s).`,
+			target: consent.targetIdentity,
+			projection: consent.projection,
+			evidence: consent.riskEvidence,
+			ownership: HOST_REVIEW_SESSION_PERMISSION_OWNERSHIP,
+			offPathNote: consent.offPath.note,
+			offPathCommand: consent.offPath.command,
+			actions: [
+				{ label: consent.choices[0].label, effect: consent.choices[0].effect },
+				{ label: consent.choices[1].label, effect: consent.choices[1].effect },
+				{ label: HOST_REVIEW_SESSION_PERMISSION_LABEL, effect: HOST_REVIEW_SESSION_PERMISSION_EFFECT },
+			],
+		},
+	};
+}
+
+export async function presentReviewConsentUi(
+	context: ExtensionContext,
+	consent: ReviewConsentEnvelope,
+): Promise<ReviewConsentUiSelection | undefined> {
+	if (!isPiConsentV3(consent)) return undefined;
+	const model = formatReviewConsentUi(consent);
+	try {
+		if (context.mode === "tui") {
+			return await context.ui.custom<ReviewConsentUiSelection | undefined>((tui, theme, keybindings, done) => {
+				const component = new ReviewConsentComponent({
+					content: model.content,
+					theme,
+					keybindings,
+					terminalRows: () => tui.terminal.rows,
+					onSelect: (index) => done(index === 0 ? { kind: "provider", answer: "granted" }
+						: index === 1 ? { kind: "provider", answer: "declined" } : { kind: "host-session" }),
+					onCancel: () => done(undefined),
+				});
+				return {
+					getActionOptions: () => component.getActionOptions(),
+					render: (width) => component.render(width),
+					invalidate: () => component.invalidate(),
+					handleInput: (data) => {
+						component.handleInput(data);
+						tui.requestRender();
+					},
+				};
+			});
+		}
+		const selected = await context.ui.select(model.title, [...model.options]);
+		if (selected === model.options[0]) return { kind: "provider", answer: "granted" };
+		if (selected === model.options[1]) return { kind: "provider", answer: "declined" };
+		if (selected === model.options[2]) return { kind: "host-session" };
+		return undefined;
+	} catch {
+		return undefined;
+	}
+}

package/lib/review-host-relay.ts

@@ -140,6 +140,34 @@ export function classifyReviewHostRelayRefusal(stderr: string): "unknown-flag" |
 	return "other";
 }
 
+// ---------------------------------------------------------------------------
+// gentle-pi#638: only a relay-bound reviewer timeout is deterministic for the
+// exact selected slot: relaunching the same materialized request reaches the
+// same wall. Generic admission refusals, including malformed reviewer JSON and
+// binding_mismatch [invalid_request], describe repairable submitted bytes; a
+// fresh reviewer can change them. They keep the existing exact-reoffer path.
+// A future provider-issued, typed slot-deterministic refusal may be added here
+// only when its schema proves that this exact bound slot cannot be repaired.
+// ---------------------------------------------------------------------------
+
+export const REVIEW_HOST_RELAY_UNACHIEVABLE_REASON = {
+	PI_TIMED_OUT: "relay_transport_bound_exceeded",
+} as const;
+
+export function reviewHostRelayUnachievableReason(error: ReviewHostRelayError): string | undefined {
+	return error.kind === REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT
+		? REVIEW_HOST_RELAY_UNACHIEVABLE_REASON.PI_TIMED_OUT
+		: undefined;
+}
+
+// Optional bounded evidence for the declaration's --detail. Only the killed reviewer carries measurements worth recording; an admission refusal's text already rides failure.stderr, and unmeasured failures never get a fabricated detail.
+export function reviewHostRelayUnachievableDetail(error: ReviewHostRelayError): string | undefined {
+	if (error.kind === REVIEW_HOST_RELAY_FAILURE.PI_TIMED_OUT && error.elapsedMs !== null && error.timeoutMs !== null) {
+		return `killed after ${error.elapsedMs}ms against a ${error.timeoutMs}ms relay bound`;
+	}
+	return undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Slot detection — the provider decides. A collect input routes through the
 // host relay ONLY when the provider itself issued the `--materialize` token