immune-brain 2.8.2

package/plugins/immune-brain/.pi-extension/pi-canary-assurance.ts

@@ -0,0 +1,154 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text, type Component } from "@earendil-works/pi-tui";
+import { renderStructuredCall, renderStructuredResult } from "./pi-canary-interaction";
+
+export type AssuranceRole = "qa" | "review";
+
+export interface AssuranceCorrelation {
+	record_revision: string;
+	intent_content_hash: string;
+	diff_hash: string;
+}
+
+export interface AssuranceFindingPresentation {
+	id: string;
+	kind: "blocking" | "advisory";
+	acceptance_id: string | null;
+	summary: string;
+}
+
+export interface AssuranceResultPresentation {
+	passed_acceptance_ids: string[];
+	missing_acceptance_ids: string[];
+	findings: AssuranceFindingPresentation[];
+}
+
+
+export interface CanaryToolArgs {
+	task_id: string;
+	action: { op: string };
+}
+
+export function renderCanaryCall(args: CanaryToolArgs, theme: Theme): Component {
+	return renderStructuredCall(
+		"imm_kernel_canary",
+		args.action?.op ?? "unknown",
+		args.task_id,
+		theme,
+	);
+}
+
+export function renderCanaryResult(
+	result: { content?: Array<{ type?: string; text?: string }>; details?: Record<string, unknown> },
+	theme: Theme,
+): Component {
+	return renderStructuredResult(result, theme);
+}
+
+export function renderAssuranceResultMessage(
+	message: { content?: unknown; details?: unknown },
+	options: { expanded?: boolean; outputPad?: number },
+	theme: Theme,
+): Component {
+	const payload = isRecord(message.details) ? message.details : undefined;
+	if (
+		!payload
+		|| typeof payload.task_id !== "string"
+		|| (payload.role !== "qa" && payload.role !== "review")
+		|| typeof payload.terminal !== "string"
+	) {
+		const fallback = typeof message.content === "string" ? message.content : "Assurance result unavailable";
+		return new Text(theme.fg("dim", fallback), options.outputPad ?? 0, 0);
+	}
+
+	const presentation = isAssuranceResultPresentation(payload.presentation)
+		? payload.presentation
+		: undefined;
+	const findings = presentation?.findings ?? [];
+	const blockers = findings.filter((finding) => finding.kind === "blocking");
+	const warnings = findings.filter((finding) => finding.kind === "advisory");
+	const passed = presentation?.passed_acceptance_ids ?? [];
+	const missing = presentation?.missing_acceptance_ids ?? [];
+	const terminal = payload.terminal.replaceAll("_", " ");
+	const role = payload.role === "qa" ? "QA" : "Review";
+	const status = `${role} ${terminal}`;
+	const lines = [`${theme.fg("muted", "Status:")} ${theme.fg("accent", capitalize(status))}`];
+
+	if (presentation) {
+		lines.push(
+			`${theme.fg("muted", "Result:")} ${[
+				theme.fg(blockers.length > 0 ? "error" : "muted", `Blockers: ${blockers.length}`),
+				theme.fg(warnings.length > 0 ? "warning" : "muted", `Warnings: ${warnings.length}`),
+				theme.fg("success", `Passed: ${passed.length}`),
+				theme.fg(missing.length > 0 ? "warning" : "muted", `Missing: ${missing.length}`),
+			].join(" | ")}`,
+		);
+		const next = renderNextAction(payload.next_action);
+		if (next) lines.push(`${theme.fg("muted", "Next:")} ${theme.fg("dim", next)}`);
+		for (const finding of blockers) lines.push(renderFinding(finding, theme));
+		if (options.expanded) {
+			for (const finding of warnings) lines.push(renderFinding(finding, theme));
+			if (passed.length > 0) lines.push(theme.fg("dim", `Passed acceptance: ${passed.join(", ")}`));
+			if (missing.length > 0) lines.push(theme.fg("warning", `Missing acceptance: ${missing.join(", ")}`));
+			if (typeof payload.summary === "string" && payload.summary) lines.push(theme.fg("dim", payload.summary));
+		}
+	} else if (typeof payload.summary === "string" && payload.summary) {
+		lines.push(`${theme.fg("muted", "Result:")} ${theme.fg("dim", payload.summary)}`);
+	}
+
+	return new Text(lines.join("\n"), options.outputPad ?? 0, 0);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isAssuranceResultPresentation(value: unknown): value is AssuranceResultPresentation {
+	if (!isRecord(value)) return false;
+	if (!isStringArray(value.passed_acceptance_ids) || !isStringArray(value.missing_acceptance_ids)) return false;
+	return Array.isArray(value.findings) && value.findings.every((finding) =>
+		isRecord(finding)
+		&& typeof finding.id === "string"
+		&& (finding.kind === "blocking" || finding.kind === "advisory")
+		&& (finding.acceptance_id === null || typeof finding.acceptance_id === "string")
+		&& typeof finding.summary === "string");
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function capitalize(value: string): string {
+	return value.length === 0 ? value : `${value[0].toUpperCase()}${value.slice(1)}`;
+}
+
+function renderNextAction(value: unknown): string | undefined {
+	switch (value) {
+		case "request_authorization":
+			return "Agent opens native confirmation";
+		case "repair_findings":
+			return "Agent repairs blocking findings";
+		case "inspect_assurance_failure":
+			return "Agent inspects the assurance failure";
+		case "none":
+			return "No action required";
+		default:
+			return undefined;
+	}
+}
+
+function renderFinding(finding: AssuranceFindingPresentation, theme: Theme): string {
+	const label = finding.kind === "blocking"
+		? theme.fg("error", "[blocking]")
+		: theme.fg("warning", "[advisory]");
+	const acceptance = finding.acceptance_id ? ` (${finding.acceptance_id})` : "";
+	return `${label} ${finding.id}${acceptance}: ${finding.summary}`;
+}
+
+// Foreground Tool results render directly in the chat transcript. There is no
+// session-owned status or message continuation channel.
+export class AssurancePresenter {
+	publish(): void {}
+	clear(): void {}
+	reset(): void {}
+}

package/plugins/immune-brain/.pi-extension/pi-canary-interaction.ts

@@ -0,0 +1,349 @@
+import { DynamicBorder, type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
+import { Container, SelectList, Text, type Component, type SelectItem } from "@earendil-works/pi-tui";
+
+export const USER_ATTENTION_EVENT = "immune-brain:user-attention.v1" as const;
+export const TASK_RAIL_KEY = "immune-brain.task-rail" as const;
+
+export type UserAttentionReason =
+	| "enrollment"
+	| "descriptor_waiver"
+	| "breaking_intent_revision"
+	| "review_authorization"
+	| "authority_repair";
+
+export interface UserAttentionEventV1 {
+	active: boolean;
+	attention_id: string;
+	task_id: string;
+	reason: UserAttentionReason;
+	label?: string;
+}
+
+export type TaskRailState =
+	| "Planning"
+	| "Approval required"
+	| "Working"
+	| "Verifying"
+	| "Reviewing"
+	| "Blocked"
+	| "Completed"
+	| "Stopped";
+
+export interface TaskRailView {
+	task_id: string;
+	state: TaskRailState;
+	result: string;
+	next: string;
+}
+
+export interface AuthorityDialogAction<T extends string> {
+	value: T;
+	label: string;
+	description: string;
+}
+
+export interface AuthorityDialogOptions<T extends string> {
+	title: string;
+	summary: string;
+	details: string;
+	actions: readonly AuthorityDialogAction<T>[];
+	signal?: AbortSignal;
+}
+
+type EventPublisher = Pick<ExtensionAPI, "events">;
+type UiContext = Pick<ExtensionContext, "ui">;
+
+const terminalRailUis = new WeakSet<object>();
+const deliveredNotifications = new WeakMap<object, Set<string>>();
+
+function beginUserAttention(
+	pi: EventPublisher,
+	event: Omit<UserAttentionEventV1, "active">,
+): () => void {
+	let active = true;
+	emitAttention(pi, { ...event, active: true });
+	return () => {
+		if (!active) return;
+		active = false;
+		emitAttention(pi, {
+			active: false,
+			attention_id: event.attention_id,
+			task_id: event.task_id,
+			reason: event.reason,
+		});
+	};
+}
+
+async function withUserAttention<T>(
+	pi: EventPublisher,
+	event: Omit<UserAttentionEventV1, "active">,
+	waitForUser: () => Promise<T>,
+): Promise<T> {
+	const endAttention = beginUserAttention(pi, event);
+	try {
+		return await waitForUser();
+	} finally {
+		endAttention();
+	}
+}
+
+export async function requestAuthorityDialog<T extends string, R = T | undefined>(
+	pi: EventPublisher,
+	ctx: UiContext,
+	event: Omit<UserAttentionEventV1, "active">,
+	options: AuthorityDialogOptions<T>,
+	completeDecision?: (selection: T | undefined) => Promise<R>,
+): Promise<R> {
+	return withUserAttention(pi, event, async () => {
+		let selected: T | undefined;
+		let finish: ((result: T | undefined) => void) | undefined;
+		let settled = false;
+		const complete = (result: T | undefined) => {
+			if (settled) return;
+			settled = true;
+			finish?.(result);
+		};
+		const abort = () => complete(undefined);
+		if (!options.signal?.aborted) {
+			options.signal?.addEventListener("abort", abort, { once: true });
+			try {
+				selected = await ctx.ui.custom<T | undefined>((tui, theme, _keybindings, done) => {
+					finish = done;
+					if (settled || options.signal?.aborted) done(undefined);
+					let expanded = false;
+					const detailText = new Text(theme.fg("muted", "Details collapsed; press d to expand."), 1, 0);
+					const selectList = new SelectList(
+						options.actions.map((action): SelectItem => ({ ...action })),
+						options.actions.length,
+						{
+							selectedPrefix: (text) => theme.fg("accent", text),
+							selectedText: (text) => theme.fg("accent", text),
+							description: (text) => theme.fg("muted", text),
+							scrollInfo: (text) => theme.fg("dim", text),
+							noMatch: (text) => theme.fg("warning", text),
+						},
+					);
+					selectList.onSelect = (item) => complete(item.value as T);
+					selectList.onCancel = () => complete(undefined);
+					const container = new Container();
+					container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+					container.addChild(new Text(theme.fg("accent", theme.bold(options.title)), 1, 0));
+					container.addChild(new Text(options.summary, 1, 0));
+					container.addChild(detailText);
+					container.addChild(selectList);
+					container.addChild(new Text(theme.fg("dim", "d: toggle details | enter: choose | esc: cancel"), 1, 0));
+					container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+					return {
+						render: (width) => container.render(width),
+						invalidate: () => container.invalidate(),
+						handleInput: (data) => {
+							if (data === "d" || data === "D") {
+								expanded = !expanded;
+								detailText.setText(expanded ? options.details : theme.fg("muted", "Details collapsed; press d to expand."));
+								tui.requestRender();
+								return;
+							}
+							selectList.handleInput(data);
+							tui.requestRender();
+						},
+					};
+				}, {
+					overlay: true,
+					overlayOptions: { anchor: "center", width: "80%", maxHeight: "80%" },
+				});
+			} finally {
+				options.signal?.removeEventListener("abort", abort);
+			}
+		}
+		return completeDecision ? await completeDecision(selected) : selected as R;
+	});
+}
+
+export function presentTaskRail(ctx: UiContext, view: TaskRailView): void {
+	try {
+		ctx.ui.setWidget(TASK_RAIL_KEY, renderTaskRail(view), { placement: "aboveEditor" });
+		if (view.state === "Completed" || view.state === "Stopped") terminalRailUis.add(ctx.ui);
+		else terminalRailUis.delete(ctx.ui);
+	} catch {
+		notifyOnce(ctx, `task-rail:${view.task_id}`, "Task Rail is unavailable; Tool results remain authoritative.", "warning");
+	}
+}
+
+export function presentTaskRailResult(
+	ctx: UiContext,
+	taskId: string,
+	details: Record<string, unknown> | undefined,
+): void {
+	if (!details) return;
+	const taskState = record(details.task_state);
+	const lifecycle = string(taskState?.lifecycle) ?? string(details.lifecycle) ?? string(details.stage);
+	const operation = string(details.operation);
+	const rawState = string(details.state);
+	const result = string(details.result) ?? string(details.reason) ?? operation ?? rawState ?? "Task state updated";
+	const next = string(details.next_action) ?? "Continue through the projected authority";
+	presentTaskRail(ctx, {
+		task_id: taskId,
+		state: railState({ lifecycle, obligation: string(taskState?.next_obligation), operation, state: rawState }),
+		result,
+		next,
+	});
+}
+
+export function clearTerminalTaskRailOnInput(ctx: UiContext): void {
+	if (!terminalRailUis.has(ctx.ui)) return;
+	clearTaskRail(ctx);
+}
+
+export function clearTaskRail(ctx: UiContext): void {
+	try {
+		ctx.ui.setWidget(TASK_RAIL_KEY, undefined);
+	} catch {
+		// Tool rows remain the fallback observation surface.
+	}
+	terminalRailUis.delete(ctx.ui);
+}
+
+export function resetInteractionPresentation(ctx?: UiContext): void {
+	if (!ctx) return;
+	clearTaskRail(ctx);
+	deliveredNotifications.delete(ctx.ui);
+}
+
+export function notifyOnce(
+	ctx: UiContext,
+	key: string,
+	message: string,
+	level: "warning" | "error",
+): void {
+	let delivered = deliveredNotifications.get(ctx.ui);
+	if (!delivered) {
+		delivered = new Set<string>();
+		deliveredNotifications.set(ctx.ui, delivered);
+	}
+	if (delivered.has(key)) return;
+	delivered.add(key);
+	try {
+		ctx.ui.notify(message, level);
+	} catch {
+		// Notifications never participate in workflow authority.
+	}
+}
+
+export function renderStructuredCall(
+	tool: string,
+	action: string,
+	subject: string | undefined,
+	theme: Theme,
+): Component {
+	return new Text(
+		[
+			theme.fg("toolTitle", theme.bold(tool)),
+			theme.fg("muted", action),
+			...(subject ? [theme.fg("accent", subject)] : []),
+		].join(" "),
+		0,
+		0,
+	);
+}
+
+export function renderStructuredResult(
+	result: { content?: Array<{ type?: string; text?: string }>; details?: Record<string, unknown> },
+	theme: Theme,
+): Component {
+	const details = result.details;
+	if (!details) return new Text(theme.fg("dim", "Result details unavailable"), 0, 0);
+	const taskState = record(details.task_state);
+	const lifecycle = string(taskState?.lifecycle) ?? string(details.lifecycle) ?? string(details.stage);
+	const state = string(details.state) ?? "unknown";
+	const summary = string(details.result) ?? string(details.reason) ?? string(details.operation) ?? state;
+	const next = string(details.next_action) ?? "No action reported";
+	const terminal = lifecycle === "done" || lifecycle === "stopped";
+	const lines = [
+		`${theme.fg("muted", "State:")} ${theme.fg(state === "blocked" || state === "failed" ? "warning" : "accent", lifecycle ?? state)}`,
+		`${theme.fg("muted", "Result:")} ${theme.fg(state === "blocked" || state === "failed" ? "warning" : "dim", summary)}`,
+		`${theme.fg("muted", "Next:")} ${theme.fg("dim", next)}`,
+	];
+	if (terminal && taskState) lines.push(...renderFinalLines(taskState, theme));
+	return new Text(lines.join("\n"), 0, 0);
+}
+
+export function loopResultDetails(result: unknown, operation: string): Record<string, unknown> {
+	const projected = record(result);
+	const next = string(projected?.next) ?? "none";
+	return {
+		state: "projected",
+		operation,
+		result: `Loop selected ${next} without state mutation`,
+		next_action: next === "none" ? "No action required" : `Follow ${next} authority`,
+	};
+}
+
+function emitAttention(pi: EventPublisher, event: UserAttentionEventV1): void {
+	try {
+		pi.events.emit(USER_ATTENTION_EVENT, event);
+	} catch {
+		// External attention adapters are optional and non-authoritative.
+	}
+}
+
+function renderTaskRail(view: TaskRailView): string[] {
+	return [
+		`Task ${boundedMiddle(view.task_id, 52)} · ${view.state}`,
+		`Result: ${bounded(view.result, 112)}`,
+		`Next: ${bounded(view.next, 112)}`,
+	];
+}
+
+function railState(input: { lifecycle?: string; obligation?: string; operation?: string; state?: string }): TaskRailState {
+	if (input.state === "blocked" || input.state === "failed" || input.state === "settlement_unknown") return "Blocked";
+	if (input.lifecycle === "done") return "Completed";
+	if (input.lifecycle === "stopped") return "Stopped";
+	if (input.state === "awaiting_user" || input.operation === "request_authorization") return "Approval required";
+	if (input.operation === "advance_assurance") return "Verifying";
+	if (input.operation === "submit_review" || input.obligation === "run_review") return "Reviewing";
+	if (input.lifecycle === "active") return "Working";
+	if (input.state === "running") return "Planning";
+	return "Working";
+}
+
+function renderFinalLines(taskState: Record<string, unknown>, theme: Theme): string[] {
+	const fresh = strings(taskState.fresh_acceptance_ids).length;
+	const missing = strings(taskState.missing_acceptance_ids).length;
+	const approvals = strings(taskState.fresh_approval_kinds);
+	const blockers = strings(taskState.blocking_finding_ids).length
+		+ strings(taskState.unresolved_user_decision_ids).length
+		+ strings(taskState.replan_required_ids).length;
+	const diffHash = string(taskState.diff_hash);
+	return [
+		`${theme.fg("muted", "Acceptance:")} ${theme.fg(missing === 0 ? "success" : "warning", `${fresh}/${fresh + missing} fresh`)}`,
+		`${theme.fg("muted", "QA / Review:")} ${theme.fg("dim", approvals.length > 0 ? approvals.join(", ") : "not recorded")}`,
+		`${theme.fg("muted", "Residual blockers:")} ${theme.fg(blockers === 0 ? "dim" : "warning", String(blockers))}`,
+		`${theme.fg("muted", "Repository health:")} ${theme.fg("dim", "not assessed")}`,
+		`${theme.fg("muted", "Git:")} ${theme.fg("dim", diffHash ? `task diff ${diffHash.slice(0, 15)}` : "not reported")}`,
+	];
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+		? value as Record<string, unknown>
+		: undefined;
+}
+
+function string(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function strings(value: unknown): string[] {
+	return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+}
+
+function bounded(value: string, max: number): string {
+	return value.length <= max ? value : `${value.slice(0, max - 3)}...`;
+}
+
+function boundedMiddle(value: string, max: number): string {
+	if (value.length <= max) return value;
+	const visible = max - 3;
+	const start = Math.ceil(visible / 2);
+	return `${value.slice(0, start)}...${value.slice(-(visible - start))}`;
+}

package/plugins/immune-brain/.pi-extension/pi-canary-invocations.ts

@@ -0,0 +1,90 @@
+// P2B2 task-scoped invocation registry. NOT part of the Kernel runtime graph.
+// One linear state transition per task: `open -> committed | cancelled`.
+// Concurrent assure/authorize operations for the same task are rejected;
+// timeout/cancel wins `open -> cancelled` first; a successful continuation
+// must win `open -> committed` immediately before mint/apply; application
+// failure leaves the invocation closed so retry requires a new invocation.
+// No memory/file cross-transaction atomicity is claimed.
+
+export type InvocationState = "open" | "committed" | "cancelled";
+
+export interface InvocationToken {
+	readonly task_id: string;
+	readonly nonce: string;
+}
+
+export interface InvocationRegistry {
+	/** Open a new invocation for one task; rejects if one is already open. */
+	open(taskId: string): InvocationToken;
+	/**
+	 * Linearization point: wins `open -> committed` for exactly this token.
+	 * Throws for a foreign token or a token whose invocation already ended.
+	 * Only the winner may mint/apply a capability.
+	 */
+	commit(token: InvocationToken): void;
+	/** Wins `open -> cancelled` (timeout/cancel/abort path). */
+	cancel(token: InvocationToken): void;
+	/** Inspect the current state of the caller's token. */
+	stateOf(token: InvocationToken): InvocationState;
+	/** Whether any invocation for the task is currently open. */
+	isOpen(taskId: string): boolean;
+	/** Internal task state (for tests). */
+	states(): Record<string, InvocationState>;
+}
+
+export function createInvocationRegistry(): InvocationRegistry {
+	const states = new Map<string, { token: InvocationToken; state: InvocationState }>();
+
+	function tokenOf(taskId: string, nonce: string): InvocationToken {
+		return Object.freeze({ task_id: taskId, nonce });
+	}
+
+	function entryOf(token: InvocationToken): { token: InvocationToken; state: InvocationState } {
+		const entry = states.get(token.task_id);
+		if (!entry || entry.token.nonce !== token.nonce)
+			throw new Error("invocation token is not recognized for this task");
+		return entry;
+	}
+
+	return {
+		open(taskId: string): InvocationToken {
+			if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(taskId))
+				throw new Error("task id is not a safe file identity");
+			const existing = states.get(taskId);
+			if (existing && existing.state === "open") {
+				throw new Error(
+					`task ${taskId} already has an open invocation; concurrent assure/authorize is rejected`,
+				);
+			}
+			// A closed (committed/cancelled) invocation is replaced by a fresh
+			// one: retry requires a new invocation.
+			const token = tokenOf(taskId, `${taskId}:${Date.now()}:${Math.random().toString(36).slice(2, 10)}`);
+			states.set(taskId, { token, state: "open" });
+			return token;
+		},
+		commit(token: InvocationToken): void {
+			const entry = entryOf(token);
+			if (entry.state !== "open")
+				throw new Error(
+					`invocation for task ${token.task_id} is already ${entry.state}; a new invocation is required`,
+				);
+			entry.state = "committed";
+		},
+		cancel(token: InvocationToken): void {
+			const entry = entryOf(token);
+			if (entry.state === "open") entry.state = "cancelled";
+			// Cancel on an already-closed invocation is a no-op (idempotent).
+		},
+		stateOf(token: InvocationToken): InvocationState {
+			return entryOf(token).state;
+		},
+		isOpen(taskId: string): boolean {
+			return states.get(taskId)?.state === "open";
+		},
+		states(): Record<string, InvocationState> {
+			const out: Record<string, InvocationState> = {};
+			for (const [taskId, entry] of states) out[taskId] = entry.state;
+			return out;
+		},
+	};
+}