ultimate-pi 0.19.1 → 0.22.0

package/.pi/lib/agents-policy.mjs

@@ -31,10 +31,26 @@ const MUTATING_TOOLS = new Set(["write", "edit"]);
 
 const cache = new Map();
 
+const EXTENSION_BUNDLE_MODULES = {
+	executor: [
+		"subagent-governance.ts",
+		"harness-anchored-edit.ts",
+		"harness-lens.ts",
+	],
+};
+
 export function packageAgentsPolicyPath(packageRoot) {
 	return join(packageRoot, ".pi", "harness", "agents.policy.yaml");
 }
 
+/** Absolute paths for subprocess `-e` loads (curated; avoids parent-only extensions). */
+export function resolveExtensionBundlePaths(packageRoot, bundleName) {
+	const modules = EXTENSION_BUNDLE_MODULES[bundleName];
+	if (!modules) return [];
+	const extDir = join(packageRoot, ".pi", "extensions");
+	return modules.map((name) => join(extDir, name));
+}
+
 export function projectAgentsPolicyPath(projectRoot) {
 	return join(projectRoot, ".pi", "agents.policy.yaml");
 }
@@ -52,12 +68,19 @@ function readYamlFile(path) {
 	}
 }
 
+function normalizeExtensionBundle(raw) {
+	if (typeof raw.extension_bundle !== "string") return undefined;
+	const bundle = raw.extension_bundle.trim();
+	return bundle.length > 0 ? bundle : undefined;
+}
+
 function normalizeKindEntry(raw) {
 	if (!raw || typeof raw !== "object") return null;
 	const tools = Array.isArray(raw.tools) ? raw.tools.map(String) : [];
 	return {
 		tools,
 		extensions: raw.extensions === false ? false : Boolean(raw.extensions),
+		extensionBundle: normalizeExtensionBundle(raw),
 		readOnly: raw.read_only === true,
 		maxTurns:
 			typeof raw.max_turns === "number" && raw.max_turns > 0
@@ -93,6 +116,7 @@ function normalizeAgentEntry(raw) {
 				: raw.extensions === true
 					? true
 					: undefined,
+		extensionBundle: normalizeExtensionBundle(raw),
 		maxTurns:
 			typeof raw.max_turns === "number" && raw.max_turns > 0
 				? raw.max_turns
@@ -162,10 +186,25 @@ export function resolveEffectiveTools(agentId, merged) {
 	for (const t of entry.toolsDeny ?? []) base.delete(t);
 	for (const t of BUILTIN_DENY_TOOLS) base.delete(t);
 
+	const extensionBundle =
+		entry.extensionBundle ?? kind.extensionBundle ?? undefined;
+	const extensionsFull =
+		!extensionBundle &&
+		(entry.extensions === true
+			? true
+			: entry.extensions === false
+				? false
+				: Boolean(kind.extensions));
+	const extensionsOff = !extensionsFull;
+
 	return {
 		kind: kindName,
 		effectiveTools: [...base],
-		extensionsOff: entry.extensions === true ? false : entry.extensions === false ? true : !kind.extensions,
+		extensionsOff,
+		extensionBundle,
+		extensionsFull,
+		/** Suppress Pi builtins when harness read/edit register (full extensions or subprocess bundle). */
+		noBuiltinTools: extensionsFull || Boolean(extensionBundle),
 		readOnly: kind.readOnly,
 		maxTurns: entry.maxTurns ?? kind.maxTurns,
 		thinking: entry.thinking ?? kind.thinking,
@@ -223,7 +262,45 @@ function isMutatingBash(command) {
 		command,
 	);
 }
+function deniesReadOnlyBatchExecute(toolInput) {
+	const commands = toolInput.commands;
+	if (!Array.isArray(commands)) return false;
+	for (const c of commands) {
+		const cmd =
+			typeof c === "string" ? c : String(c?.command ?? c?.code ?? "");
+		if (cmd && isMutatingBash(cmd)) return true;
+	}
+	return false;
+}
+
+function deniesReadOnlyExecute(toolInput) {
+	const code = String(toolInput.code ?? toolInput.command ?? "");
+	return Boolean(code && isMutatingBash(code));
+}
 
+function deniesReadOnlyBash(agentId, toolInput) {
+	const command = String(toolInput.command ?? "");
+	if (command && isMutatingBash(command)) return true;
+	if (
+		isHarnessPlanningAgent(agentId) &&
+		command &&
+		PLANNING_ARTIFACT_JSON_WRITE.test(command)
+	) {
+		return true;
+	}
+	if (
+		isHarnessPlanningAgent(agentId) &&
+		command &&
+		PLANNING_BASH_DENY_PATTERNS.some((p) => p.test(command))
+	) {
+		return true;
+	}
+	return false;
+}
+
+/**
+ * Manifest allowlist + subprocess constraints (replaces harness-subagent-policy.ts).
+ */
 /**
  * Manifest allowlist + subprocess constraints (replaces harness-subagent-policy.ts).
  */
@@ -258,40 +335,15 @@ export function allowsAgentTool(input) {
 	if (MUTATING_TOOLS.has(toolName) && spec.readOnly) return false;
 
 	if (toolName === "ctx_batch_execute" && spec.readOnly) {
-		const commands = toolInput.commands;
-		if (Array.isArray(commands)) {
-			for (const c of commands) {
-				const cmd =
-					typeof c === "string"
-						? c
-						: String(c?.command ?? c?.code ?? "");
-				if (cmd && isMutatingBash(cmd)) return false;
-			}
-		}
+		if (deniesReadOnlyBatchExecute(toolInput)) return false;
 	}
 
 	if (toolName === "ctx_execute" && spec.readOnly) {
-		const code = String(toolInput.code ?? toolInput.command ?? "");
-		if (code && isMutatingBash(code)) return false;
+		if (deniesReadOnlyExecute(toolInput)) return false;
 	}
 
 	if (toolName === "bash" && spec.readOnly) {
-		const command = String(toolInput.command ?? "");
-		if (command && isMutatingBash(command)) return false;
-		if (
-			isHarnessPlanningAgent(agentId) &&
-			command &&
-			PLANNING_ARTIFACT_JSON_WRITE.test(command)
-		) {
-			return false;
-		}
-		if (
-			isHarnessPlanningAgent(agentId) &&
-			command &&
-			PLANNING_BASH_DENY_PATTERNS.some((p) => p.test(command))
-		) {
-			return false;
-		}
+		if (deniesReadOnlyBash(agentId, toolInput)) return false;
 	}
 
 	return true;
@@ -304,6 +356,9 @@ export function applyAgentPolicyToConfig(agent, packageRoot, projectRoot) {
 		...agent,
 		tools: spec.effectiveTools.length > 0 ? spec.effectiveTools : undefined,
 		extensionsOff: spec.extensionsOff,
+		extensionBundle: spec.extensionBundle,
+		extensionsFull: spec.extensionsFull,
+		noBuiltinTools: spec.noBuiltinTools,
 		maxTurns: spec.maxTurns ?? agent.maxTurns,
 		thinking: spec.thinking ?? agent.thinking,
 		model: spec.model ?? agent.model,

package/.pi/lib/agents-policy.ts

@@ -16,4 +16,5 @@ export {
 	projectAgentsPolicyPath,
 	projectPoliciesDir,
 	resolveEffectiveTools,
+	resolveExtensionBundlePaths,
 } from "./agents-policy.mjs";

package/.pi/lib/agt/build-evaluation-context.ts

@@ -125,6 +125,106 @@ function bashPlanningJsonDenied(command: string, agentType: string): boolean {
 	return PLANNING_ARTIFACT_JSON_WRITE.test(command);
 }
 
+function isReadOnlyAgentKind(agentKind: string): boolean {
+	return (
+		agentKind === "planner" ||
+		agentKind === "evaluator" ||
+		agentKind === "adversary" ||
+		agentKind === "tie_breaker" ||
+		agentKind === "trace" ||
+		agentKind === "incident" ||
+		agentKind === "meta"
+	);
+}
+
+async function resolvePlanMutation(args: {
+	sessionActive: boolean;
+	toolName: string;
+	toolInput: Record<string, unknown>;
+	phase: HarnessPhase;
+	runCtx: HarnessRunContext | null;
+	projectRoot: string;
+	aborted: boolean;
+	entries: unknown[];
+	sessionId: string;
+}): Promise<{ allowed: boolean; reason?: string }> {
+	const mutatingTool = args.toolName === "write" || args.toolName === "edit";
+	if (!(args.sessionActive && mutatingTool)) return { allowed: true };
+	return isPlanPhaseAllowedMutation(
+		args.toolName,
+		args.toolInput,
+		args.phase,
+		args.runCtx,
+		args.projectRoot,
+		{
+			aborted: args.aborted,
+			entries: args.entries,
+			ownerSessionId: args.runCtx?.owner_pi_session_id,
+			currentSessionId: args.sessionId,
+		},
+	);
+}
+
+function resolveContextMode(args: {
+	sessionActive: boolean;
+	toolName: string;
+	toolInput: Record<string, unknown>;
+	phase: HarnessPhase;
+	aborted: boolean;
+	budgetBypass: boolean;
+	agentKind: string;
+}): { blocked: boolean; reason?: string } {
+	if (!args.sessionActive) return { blocked: false, reason: "" };
+	return evaluateContextModeMutation(
+		args.toolName,
+		args.toolInput,
+		args.phase,
+		{
+			aborted: args.aborted,
+			budgetBypass: args.budgetBypass,
+			readOnlyAgent: isReadOnlyAgentKind(args.agentKind),
+		},
+	);
+}
+
+function shouldBlockEvalPlanPacketWrite(args: {
+	sessionActive: boolean;
+	runCtx: HarnessRunContext | null;
+	phase: HarnessPhase;
+	toolName: string;
+	toolInput: Record<string, unknown>;
+}): boolean {
+	if (!args.sessionActive || !args.runCtx?.plan_packet_path) return false;
+	if (args.phase !== "evaluate" && args.phase !== "adversary") return false;
+	if (args.toolName !== "write" && args.toolName !== "edit") return false;
+	const target = String(args.toolInput.path ?? args.toolInput.filePath ?? "");
+	return target.includes("plan-packet.yaml");
+}
+
+function resolveMutatingBashFlags(args: {
+	sessionActive: boolean;
+	bashCommand: string;
+	aborted: boolean;
+	phase: HarnessPhase;
+	toolName: string;
+}): { mutatingBashPhaseBlock: boolean; abortMutatingBlock: boolean } {
+	const isMutating = Boolean(
+		args.bashCommand && isMutatingBash(args.bashCommand),
+	);
+	return {
+		mutatingBashPhaseBlock:
+			args.sessionActive &&
+			isMutating &&
+			!args.aborted &&
+			args.phase !== "execute" &&
+			args.phase !== "merge",
+		abortMutatingBlock:
+			args.sessionActive &&
+			args.aborted &&
+			(isMutating || args.toolName === "write" || args.toolName === "edit"),
+	};
+}
+
 function harnessSessionActive(entries: unknown[]): boolean {
 	return isHarnessAutoSession(entries);
 }
@@ -142,35 +242,27 @@ export async function buildHarnessAgtEvaluationContext(
 		input.toolName === "bash" ? String(input.toolInput.command ?? "") : "";
 	const sessionActive = harnessSessionActive(input.entries);
 
-	const MUTATING_FILE_TOOLS = new Set(["write", "edit"]);
-	const planMutation =
-		sessionActive && MUTATING_FILE_TOOLS.has(input.toolName)
-			? await isPlanPhaseAllowedMutation(
-					input.toolName,
-					input.toolInput,
-					phase,
-					runCtx,
-					input.projectRoot,
-					{
-						aborted: input.policyState.aborted,
-						entries: input.entries,
-						ownerSessionId: runCtx?.owner_pi_session_id,
-						currentSessionId: input.sessionId,
-					},
-				)
-			: { allowed: true };
+	const planMutation = await resolvePlanMutation({
+		sessionActive,
+		toolName: input.toolName,
+		toolInput: input.toolInput,
+		phase,
+		runCtx,
+		projectRoot: input.projectRoot,
+		aborted: input.policyState.aborted,
+		entries: input.entries,
+		sessionId: input.sessionId,
+	});
 
-	const ctxMode = sessionActive
-		? evaluateContextModeMutation(input.toolName, input.toolInput, phase, {
-				aborted: input.policyState.aborted,
-				budgetBypass: input.policyState.budgetBypass,
-				readOnlyAgent:
-					agentKind === "planner" ||
-					agentKind === "evaluator" ||
-					agentKind === "adversary" ||
-					agentKind === "tie_breaker",
-			})
-		: { blocked: false, reason: "" };
+	const ctxMode = resolveContextMode({
+		sessionActive,
+		toolName: input.toolName,
+		toolInput: input.toolInput,
+		phase,
+		aborted: input.policyState.aborted,
+		budgetBypass: input.policyState.budgetBypass,
+		agentKind,
+	});
 
 	const spawnDecision = evaluateSubagentToolCall(input.toolName, agentId);
 
@@ -184,40 +276,27 @@ export async function buildHarnessAgtEvaluationContext(
 		isParentOrchestrator,
 	});
 
-	let evalPlanPacketBlock = false;
-	if (
-		sessionActive &&
-		runCtx?.plan_packet_path &&
-		(phase === "evaluate" || phase === "adversary") &&
-		(input.toolName === "write" || input.toolName === "edit")
-	) {
-		const target = String(
-			input.toolInput.path ?? input.toolInput.filePath ?? "",
-		);
-		if (target.includes("plan-packet.yaml")) {
-			evalPlanPacketBlock = true;
-		}
-	}
+	const evalPlanPacketBlock = shouldBlockEvalPlanPacketWrite({
+		sessionActive,
+		runCtx,
+		phase,
+		toolName: input.toolName,
+		toolInput: input.toolInput,
+	});
 
 	const writePath =
 		input.toolName === "write" || input.toolName === "edit"
 			? extractWritePathFromToolInput(input.toolInput)
 			: null;
 
-	const mutatingBashPhaseBlock =
-		sessionActive &&
-		Boolean(bashCommand && isMutatingBash(bashCommand)) &&
-		!input.policyState.aborted &&
-		phase !== "execute" &&
-		phase !== "merge";
-
-	const abortMutatingBlock =
-		sessionActive &&
-		input.policyState.aborted &&
-		((bashCommand && isMutatingBash(bashCommand)) ||
-			input.toolName === "write" ||
-			input.toolName === "edit");
-
+	const { mutatingBashPhaseBlock, abortMutatingBlock } =
+		resolveMutatingBashFlags({
+			sessionActive,
+			bashCommand,
+			aborted: input.policyState.aborted,
+			phase,
+			toolName: input.toolName,
+		});
 	return {
 		tool_name: input.toolName,
 		harness_phase: phase,
@@ -249,14 +328,7 @@ export async function buildHarnessAgtEvaluationContext(
 		eval_plan_packet_write_block: evalPlanPacketBlock,
 		is_submit_tool: input.toolName.startsWith("submit_"),
 		is_planning_agent: isHarnessPlanningAgent(agentId),
-		is_read_only_kind:
-			agentKind === "planner" ||
-			agentKind === "evaluator" ||
-			agentKind === "adversary" ||
-			agentKind === "tie_breaker" ||
-			agentKind === "trace" ||
-			agentKind === "incident" ||
-			agentKind === "meta",
+		is_read_only_kind: isReadOnlyAgentKind(agentKind),
 		is_executor_kind: agentKind === "executor",
 		trust_score: Number(process.env.HARNESS_TRUST_SCORE ?? "1"),
 		delegation_ceiling: Number(process.env.HARNESS_DELEGATION_CEILING ?? "1"),

package/.pi/lib/ask-user/constants.mjs

@@ -0,0 +1,3 @@
+/** @sync .pi/lib/ask-user/constants.ts */
+export const FREEFORM_OPTION_TITLE = "Type something…";
+export const MAX_QUESTIONNAIRE_QUESTIONS = 8;

package/.pi/lib/ask-user/constants.ts

@@ -0,0 +1,4 @@
+/** Freeform row label in TUI/headless presenters (agents: "custom answer", not this literal). */
+export const FREEFORM_OPTION_TITLE = "Type something…";
+
+export const MAX_QUESTIONNAIRE_QUESTIONS = 8;

package/.pi/lib/ask-user/contracts/glimpse-parse.ts

@@ -0,0 +1,56 @@
+import type { AskResponse, QuestionnaireDetail } from "../types.js";
+
+export function parseGlimpseRawResult(
+	raw: Record<string, unknown> | null,
+	cancelled: boolean,
+): AskResponse | null {
+	if (cancelled || !raw) return null;
+
+	const kind = raw.kind;
+	if (kind === "freeform") {
+		return {
+			kind: "freeform",
+			text: String(raw.text ?? "").trim(),
+			additionalComments: pickString(raw.additionalComments),
+		};
+	}
+
+	if (kind === "questionnaire") {
+		const questionnaireDetails: QuestionnaireDetail[] = Array.isArray(
+			raw.questionnaireDetails,
+		)
+			? raw.questionnaireDetails.map((d: unknown) => {
+					const entry = d as Record<string, unknown>;
+					return {
+						question: String(entry.question ?? ""),
+						answer: String(entry.answer ?? ""),
+						kind: entry.kind === "freeform" ? "freeform" : "selection",
+						comment: pickString(entry.comment),
+					};
+				})
+			: [];
+
+		return {
+			kind: "questionnaire",
+			questionnaireDetails,
+			additionalComments: pickString(raw.additionalComments),
+		};
+	}
+
+	const selections = Array.isArray(raw.selections)
+		? raw.selections.map(String)
+		: raw.selection
+			? [String(raw.selection)]
+			: [];
+
+	return {
+		kind: "selection",
+		selections,
+		comment: pickString(raw.comment),
+		additionalComments: pickString(raw.additionalComments),
+	};
+}
+
+function pickString(raw: unknown): string | undefined {
+	return raw ? String(raw) : undefined;
+}

package/.pi/lib/ask-user/contracts/glimpse-payload-build.ts

@@ -0,0 +1,58 @@
+import type { ValidatedAskParams } from "../types.js";
+import type { GlimpseAskUserPayload } from "./glimpse-payload.js";
+
+export function buildGlimpsePayload(
+	validated: ValidatedAskParams,
+	sessionName?: string,
+): GlimpseAskUserPayload {
+	const hasQuestions = validated.mode === "questionnaire";
+	const hasOptions = validated.options.length > 0;
+
+	let payloadType: GlimpseAskUserPayload["type"];
+	if (hasQuestions) {
+		payloadType = "questionnaire";
+	} else if (!hasOptions) {
+		payloadType = "freeform";
+	} else if (validated.allowMultiple) {
+		payloadType = "multi-select";
+	} else {
+		payloadType = "single-select";
+	}
+
+	let question = validated.question;
+	let context = validated.context;
+	if (!context && validated.question.length > 120) {
+		const match = validated.question.match(/^(.+?[.?!])(\s+|$)/);
+		if (match && match[0].length < validated.question.length) {
+			question = match[1].trim();
+			context = validated.question.slice(match[0].length).trim();
+		}
+	}
+
+	return {
+		type: payloadType,
+		question,
+		context,
+		contextFormat: validated.contextFormat,
+		options: validated.options.map((o) => ({
+			title: o.title,
+			description: o.description,
+			recommended: o.recommended,
+		})),
+		questions: validated.questions.map((q) => ({
+			title: q.title,
+			description: q.description,
+			allowMultiple: q.allowMultiple,
+			options: q.options.map((o) => ({
+				title: o.title,
+				description: o.description,
+				recommended: o.recommended,
+			})),
+		})),
+		allowMultiple: validated.allowMultiple,
+		allowFreeform: validated.allowFreeform,
+		allowComment: validated.allowComment,
+		allowSkip: validated.allowSkip,
+		sessionName,
+	};
+}

package/.pi/lib/ask-user/contracts/glimpse-payload.ts

@@ -0,0 +1,38 @@
+/**
+ * Synced with @alexleekt/pi-ask-user-glimpse@0.5.1 shared/ask-user.ts — harness-owned payload contract.
+ */
+
+export interface GlimpseQuestionOption {
+	title: string;
+	description?: string;
+	recommended?: boolean;
+}
+
+export interface GlimpseQuestion {
+	title: string;
+	description?: string;
+	options?: GlimpseQuestionOption[];
+	allowMultiple?: boolean;
+}
+
+export type GlimpsePayloadType =
+	| "single-select"
+	| "multi-select"
+	| "questionnaire"
+	| "freeform";
+
+export interface GlimpseAskUserPayload {
+	type: GlimpsePayloadType;
+	question: string;
+	context?: string;
+	contextFormat?: "markdown" | "html";
+	options: GlimpseQuestionOption[];
+	questions?: GlimpseQuestion[];
+	allowMultiple: boolean;
+	allowFreeform: boolean;
+	allowComment: boolean;
+	allowSkip?: boolean;
+	sessionName?: string;
+}
+
+export const GLIMPSE_FREEFORM_OPTION_TITLE = "My answer isn't listed above";

package/.pi/lib/ask-user/core/questionnaire.ts

@@ -0,0 +1,74 @@
+import type {
+	DialogResult,
+	NormalizedQuestion,
+	QuestionnaireDetail,
+	ValidatedAskParams,
+} from "../types.js";
+
+/** Build flat ask params for one questionnaire card (TUI/headless sequential). */
+export function questionToFlatParams(
+	parent: ValidatedAskParams,
+	q: NormalizedQuestion,
+	index: number,
+	total: number,
+): ValidatedAskParams {
+	const header =
+		total > 1 ? `[${index + 1}/${total}] ${parent.question}` : parent.question;
+	return {
+		...parent,
+		mode: "flat",
+		question: q.title,
+		context: [header, q.description].filter(Boolean).join("\n\n") || undefined,
+		options: q.options,
+		questions: [],
+		allowMultiple: q.allowMultiple,
+		allowFreeform: q.options.length === 0 ? true : parent.allowFreeform,
+	};
+}
+
+export function mergeQuestionnaireResults(
+	details: QuestionnaireDetail[],
+	last?: DialogResult,
+): DialogResult {
+	const additionalComments =
+		last?.response?.kind === "freeform"
+			? last.response.text
+			: last?.response && "additionalComments" in last.response
+				? last.response.additionalComments
+				: undefined;
+
+	return {
+		response: {
+			kind: "questionnaire",
+			questionnaireDetails: details,
+			additionalComments,
+		},
+		cancelled: false,
+		ui_backend: last?.ui_backend ?? "tui",
+		ui_degraded: last?.ui_degraded,
+	};
+}
+
+export function detailFromFlatResult(
+	questionLabel: string,
+	result: DialogResult,
+): QuestionnaireDetail | null {
+	if (result.cancelled || !result.response) return null;
+	const r = result.response;
+	if (r.kind === "freeform") {
+		return {
+			question: questionLabel,
+			answer: r.text,
+			kind: "freeform",
+		};
+	}
+	if (r.kind === "selection") {
+		return {
+			question: questionLabel,
+			answer: r.selections.join(", "),
+			kind: "selection",
+			comment: r.comment,
+		};
+	}
+	return null;
+}