pi-auto-permissions 0.1.0

package/src/guardian/types.ts

@@ -0,0 +1,149 @@
+/*
+ * Guardian assessment types are adapted and modified from OpenAI Codex
+ * codex-rs/core/src/guardian/mod.rs and prompt.rs at commit
+ * 0fb559f0f6e231a88ac02ea002d3ecd248e2b515; Apache-2.0.
+ */
+import type { ModelThinkingLevel, ThinkingLevel } from "@earendil-works/pi-ai";
+
+export type GuardianRiskLevel = "low" | "medium" | "high" | "critical";
+
+export type GuardianUserAuthorization = "unknown" | "low" | "medium" | "high";
+
+export type GuardianVerdictOutcome = "allow" | "deny";
+
+export interface GuardianVerdict {
+	readonly outcome: GuardianVerdictOutcome;
+	readonly riskLevel: GuardianRiskLevel;
+	readonly userAuthorization: GuardianUserAuthorization;
+	readonly rationale: string;
+}
+
+/**
+ * The exact model selection committed in global state. `thinkingLevel` is Pi's
+ * native type so the permission extension cannot invent a parallel setting.
+ */
+export interface GuardianReviewerSelection {
+	readonly provider: string;
+	readonly modelId: string;
+	readonly thinkingLevel: ModelThinkingLevel;
+}
+
+/**
+ * The backend is part of the approval identity even for non-shell tools.  An
+ * unavailable supported-platform sandbox still permits Auto to review direct
+ * file and trusted custom tools, so it must be representable here rather than
+ * being aliased to another backend.
+ */
+export type GuardianBackend = "sandboxed" | "review-only" | "unavailable";
+
+/**
+ * An immutable snapshot of every value to which an allow verdict is bound.
+ * Returning `null` from `getCurrentBinding` means that the session is no longer
+ * alive or the action is no longer eligible to execute.
+ */
+export interface GuardianReviewBinding {
+	readonly canonicalAction: string;
+	readonly globalRevision: number;
+	readonly sessionRevision: number;
+	readonly backend: GuardianBackend;
+	readonly sessionId: string;
+	readonly reviewer: GuardianReviewerSelection;
+}
+
+export type GuardianTranscriptItem =
+	| {
+			readonly kind: "user";
+			readonly text: string;
+			/** Synthetic context masquerading as a user message never grants authorization. */
+			readonly contextual?: boolean;
+	  }
+	| { readonly kind: "assistant"; readonly text: string }
+	| { readonly kind: "tool_call"; readonly toolName: string; readonly text: string }
+	| { readonly kind: "tool_result"; readonly toolName?: string; readonly text: string }
+	| { readonly kind: "developer" | "system"; readonly text: string };
+
+export interface GuardianModelRequest {
+	readonly provider: string;
+	readonly modelId: string;
+	/** Pi provider option: an explicit `off` selection is represented as undefined. */
+	readonly reasoning: ThinkingLevel | undefined;
+	readonly systemPrompt: string;
+	readonly userPrompt: string;
+	readonly outputSchema: GuardianOutputSchema;
+	/** The reviewer is deliberately independent and receives no tools. */
+	readonly tools: readonly [];
+	readonly attempt: number;
+}
+
+export interface GuardianModelResponse {
+	readonly text: string;
+}
+
+export type GuardianModelCall = (
+	request: GuardianModelRequest,
+	signal: AbortSignal,
+) => Promise<GuardianModelResponse>;
+
+export interface GuardianOutputSchema {
+	readonly type: "object";
+	readonly additionalProperties: false;
+	readonly properties: {
+		readonly risk_level: {
+			readonly type: "string";
+			readonly enum: readonly GuardianRiskLevel[];
+		};
+		readonly user_authorization: {
+			readonly type: "string";
+			readonly enum: readonly GuardianUserAuthorization[];
+		};
+		readonly outcome: {
+			readonly type: "string";
+			readonly enum: readonly GuardianVerdictOutcome[];
+		};
+		readonly rationale: { readonly type: "string" };
+	};
+	readonly required: readonly ["outcome"];
+}
+
+export type GuardianDenialReason =
+	| "model_denied"
+	| "invalid_input"
+	| "malformed_verdict"
+	| "model_error"
+	| "internal_error"
+	| "timeout"
+	| "cancelled"
+	| "stale_binding"
+	| "queue_exhausted"
+	| "circuit_breaker";
+
+export interface GuardianAllowResult {
+	readonly outcome: "allow";
+	readonly attempts: number;
+	readonly binding: GuardianReviewBinding;
+	readonly verdict: GuardianVerdict;
+	readonly interruptTurn: false;
+}
+
+export interface GuardianDenyResult {
+	readonly outcome: "deny";
+	readonly attempts: number;
+	readonly reason: GuardianDenialReason;
+	readonly message: string;
+	readonly interruptTurn: boolean;
+	readonly verdict?: GuardianVerdict;
+}
+
+export type GuardianReviewResult = GuardianAllowResult | GuardianDenyResult;
+
+export interface GuardianReviewInput {
+	readonly turnId: string;
+	readonly binding: GuardianReviewBinding;
+	readonly transcript: readonly GuardianTranscriptItem[];
+	readonly retryReason?: string;
+	readonly signal?: AbortSignal;
+	readonly getCurrentBinding: () =>
+		| GuardianReviewBinding
+		| null
+		| Promise<GuardianReviewBinding | null>;
+}

package/src/guardian/verdict.ts

@@ -0,0 +1,211 @@
+/*
+ * Adapted and modified from OpenAI Codex
+ * codex-rs/core/src/guardian/prompt.rs at commit
+ * 0fb559f0f6e231a88ac02ea002d3ecd248e2b515; Apache-2.0.
+ */
+import { Buffer } from "node:buffer";
+
+import type {
+	GuardianOutputSchema,
+	GuardianRiskLevel,
+	GuardianUserAuthorization,
+	GuardianVerdict,
+	GuardianVerdictOutcome,
+} from "./types.js";
+
+export const GUARDIAN_MAX_VERDICT_BYTES = 16_384;
+
+const RISK_LEVELS = Object.freeze(["low", "medium", "high", "critical"] as const);
+const AUTHORIZATION_LEVELS = Object.freeze(["unknown", "low", "medium", "high"] as const);
+const OUTCOMES = Object.freeze(["allow", "deny"] as const);
+const ALLOWED_KEYS = new Set(["risk_level", "user_authorization", "outcome", "rationale"]);
+
+export const GUARDIAN_OUTPUT_SCHEMA: GuardianOutputSchema = Object.freeze({
+	type: "object",
+	additionalProperties: false,
+	properties: Object.freeze({
+		risk_level: Object.freeze({ type: "string", enum: RISK_LEVELS }),
+		user_authorization: Object.freeze({ type: "string", enum: AUTHORIZATION_LEVELS }),
+		outcome: Object.freeze({ type: "string", enum: OUTCOMES }),
+		rationale: Object.freeze({ type: "string" }),
+	}),
+	required: Object.freeze(["outcome"] as const),
+});
+
+export type GuardianVerdictErrorCode =
+	| "empty"
+	| "oversized"
+	| "invalid_json"
+	| "invalid_shape"
+	| "duplicate_field"
+	| "unknown_field"
+	| "missing_outcome"
+	| "invalid_outcome"
+	| "invalid_risk_level"
+	| "invalid_authorization"
+	| "invalid_rationale";
+
+export class GuardianVerdictError extends Error {
+	readonly code: GuardianVerdictErrorCode;
+
+	constructor(code: GuardianVerdictErrorCode, message: string) {
+		super(message);
+		this.name = "GuardianVerdictError";
+		this.code = code;
+	}
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isRiskLevel(value: unknown): value is GuardianRiskLevel {
+	return typeof value === "string" && (RISK_LEVELS as readonly string[]).includes(value);
+}
+
+function isAuthorization(value: unknown): value is GuardianUserAuthorization {
+	return typeof value === "string" && (AUTHORIZATION_LEVELS as readonly string[]).includes(value);
+}
+
+function isOutcome(value: unknown): value is GuardianVerdictOutcome {
+	return typeof value === "string" && (OUTCOMES as readonly string[]).includes(value);
+}
+
+function skipWhitespace(text: string, start: number): number {
+	let index = start;
+	while (index < text.length && /\s/u.test(text[index] ?? "")) index += 1;
+	return index;
+}
+
+function jsonStringEnd(text: string, start: number): number {
+	let escaped = false;
+	for (let index = start + 1; index < text.length; index += 1) {
+		const character = text[index];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (character === "\\") {
+			escaped = true;
+			continue;
+		}
+		if (character === '"') return index + 1;
+	}
+	return text.length;
+}
+
+/** JSON.parse accepts duplicate members and silently keeps the last one. */
+function assertNoDuplicateTopLevelFields(text: string): void {
+	let index = skipWhitespace(text, 0);
+	if (text[index] !== "{") return;
+	index = skipWhitespace(text, index + 1);
+	const fields = new Set<string>();
+	while (index < text.length && text[index] !== "}") {
+		const keyEnd = jsonStringEnd(text, index);
+		const field = JSON.parse(text.slice(index, keyEnd)) as string;
+		if (fields.has(field)) {
+			throw new GuardianVerdictError(
+				"duplicate_field",
+				`Guardian verdict repeats field: ${field}`,
+			);
+		}
+		fields.add(field);
+		index = skipWhitespace(text, keyEnd);
+		if (text[index] !== ":") return;
+		index += 1;
+
+		let nestedDepth = 0;
+		let inString = false;
+		let escaped = false;
+		for (; index < text.length; index += 1) {
+			const character = text[index];
+			if (inString) {
+				if (escaped) escaped = false;
+				else if (character === "\\") escaped = true;
+				else if (character === '"') inString = false;
+				continue;
+			}
+			if (character === '"') {
+				inString = true;
+				continue;
+			}
+			if (character === "{" || character === "[") {
+				nestedDepth += 1;
+				continue;
+			}
+			if (character === "]") {
+				nestedDepth -= 1;
+				continue;
+			}
+			if (character === "}" && nestedDepth > 0) {
+				nestedDepth -= 1;
+				continue;
+			}
+			if (nestedDepth === 0 && (character === "," || character === "}")) break;
+		}
+		if (text[index] === ",") index = skipWhitespace(text, index + 1);
+	}
+}
+
+/**
+ * Parses one complete JSON value and applies the pinned Guardian schema. There
+ * is intentionally no fence/prose extraction and no inference of an allow.
+ */
+export function parseGuardianVerdict(text: string): GuardianVerdict {
+	if (typeof text !== "string" || text.trim().length === 0) {
+		throw new GuardianVerdictError("empty", "Guardian verdict was empty");
+	}
+	if (Buffer.byteLength(text, "utf8") > GUARDIAN_MAX_VERDICT_BYTES) {
+		throw new GuardianVerdictError("oversized", "Guardian verdict exceeded its size limit");
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		throw new GuardianVerdictError("invalid_json", "Guardian verdict was not one JSON value");
+	}
+	if (!isRecord(parsed)) {
+		throw new GuardianVerdictError("invalid_shape", "Guardian verdict must be a JSON object");
+	}
+	assertNoDuplicateTopLevelFields(text);
+
+	for (const key of Object.keys(parsed)) {
+		if (!ALLOWED_KEYS.has(key)) {
+			throw new GuardianVerdictError("unknown_field", `Guardian verdict has unknown field: ${key}`);
+		}
+	}
+
+	if (!Object.hasOwn(parsed, "outcome")) {
+		throw new GuardianVerdictError("missing_outcome", "Guardian verdict omitted outcome");
+	}
+	if (!isOutcome(parsed.outcome)) {
+		throw new GuardianVerdictError("invalid_outcome", "Guardian outcome must be allow or deny");
+	}
+	const outcome = parsed.outcome;
+
+	if (parsed.risk_level !== undefined && !isRiskLevel(parsed.risk_level)) {
+		throw new GuardianVerdictError("invalid_risk_level", "Guardian risk_level was invalid");
+	}
+	if (parsed.user_authorization !== undefined && !isAuthorization(parsed.user_authorization)) {
+		throw new GuardianVerdictError(
+			"invalid_authorization",
+			"Guardian user_authorization was invalid",
+		);
+	}
+	if (parsed.rationale !== undefined && typeof parsed.rationale !== "string") {
+		throw new GuardianVerdictError("invalid_rationale", "Guardian rationale must be a string");
+	}
+
+	const riskLevel = parsed.risk_level ?? (outcome === "allow" ? "low" : "high");
+	const userAuthorization = parsed.user_authorization ?? "unknown";
+	const suppliedRationale = parsed.rationale?.trim();
+	const rationale =
+		suppliedRationale === undefined || suppliedRationale.length === 0
+			? outcome === "allow"
+				? "Auto-review returned a low-risk allow decision."
+				: "Auto-review returned a deny decision without a rationale."
+			: suppliedRationale;
+
+	return { outcome, riskLevel, userAuthorization, rationale };
+}

package/src/pi/index.ts

@@ -0,0 +1,13 @@
+export {
+	PI_GUARDIAN_MAX_OUTPUT_TOKENS,
+	PI_GUARDIAN_SCHEMA_PREAMBLE,
+	PI_MODEL_RUNTIME_COMPATIBILITY_VERSION,
+	createPiGuardianModelCall,
+	type PiGuardianModelCallOptions,
+} from "./model-reviewer.js";
+export {
+	PI_GUARDIAN_MAX_TRANSCRIPT_BYTES,
+	PI_GUARDIAN_MAX_TRANSCRIPT_ITEMS,
+	PI_GUARDIAN_TRANSCRIPT_OMISSION_MARKER,
+	guardianTranscriptFromSession,
+} from "./transcript.js";

package/src/pi/model-reviewer.ts

@@ -0,0 +1,235 @@
+import type {
+	Api,
+	Context,
+	Model,
+	ModelThinkingLevel,
+	ThinkingLevel,
+} from "@earendil-works/pi-ai";
+import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
+import {
+	type ModelRegistry,
+	type ModelRuntime,
+	VERSION as PI_CODING_AGENT_VERSION,
+} from "@earendil-works/pi-coding-agent";
+
+import {
+	GuardianModelError,
+	type GuardianModelCall,
+	type GuardianModelRequest,
+	type GuardianModelResponse,
+} from "../guardian/index.js";
+
+/**
+ * Pi 0.80.10 exposes model lookup and auth through ModelRegistry, but not model
+ * invocation. Its own-property `runtime` is therefore the one deliberately
+ * isolated compatibility seam in this adapter. Refuse unknown layouts and Pi
+ * versions instead of bypassing extension/custom providers through pi-ai's
+ * legacy global compatibility dispatcher.
+ */
+export const PI_MODEL_RUNTIME_COMPATIBILITY_VERSION = "0.80.10";
+export const PI_GUARDIAN_MAX_OUTPUT_TOKENS = 8_192;
+
+export const PI_GUARDIAN_SCHEMA_PREAMBLE =
+	"The final response must validate against this exact JSON Schema (the caller will reject any non-conforming response):";
+
+interface CompatibleModelRuntime {
+	completeSimple: ModelRuntime["completeSimple"];
+}
+
+export interface PiGuardianModelCallOptions {
+	/** Test seam only; request timestamps carry no authorization semantics. */
+	readonly now?: () => number;
+}
+
+function permanentModelError(message: string, cause?: unknown): GuardianModelError {
+	return new GuardianModelError(message, {
+		retryable: false,
+		...(cause === undefined ? {} : { cause }),
+	});
+}
+
+function transientModelError(message: string, cause?: unknown): GuardianModelError {
+	return new GuardianModelError(message, {
+		retryable: true,
+		...(cause === undefined ? {} : { cause }),
+	});
+}
+
+function exactRuntime(registry: ModelRegistry): CompatibleModelRuntime {
+	if (PI_CODING_AGENT_VERSION !== PI_MODEL_RUNTIME_COMPATIBILITY_VERSION) {
+		throw permanentModelError(
+			`Pi ${PI_CODING_AGENT_VERSION} is not supported by the Guardian model-runtime adapter`,
+		);
+	}
+
+	const descriptor = Object.getOwnPropertyDescriptor(registry, "runtime");
+	if (descriptor === undefined || !("value" in descriptor)) {
+		throw permanentModelError("Pi model runtime is unavailable");
+	}
+	const candidate: unknown = descriptor.value;
+	if (
+		candidate === null ||
+		typeof candidate !== "object" ||
+		typeof (candidate as Partial<CompatibleModelRuntime>).completeSimple !== "function"
+	) {
+		throw permanentModelError("Pi model runtime is incompatible");
+	}
+	return candidate as CompatibleModelRuntime;
+}
+
+function assertReviewerRequest(request: GuardianModelRequest): void {
+	if (
+		typeof request.provider !== "string" ||
+		request.provider.length === 0 ||
+		typeof request.modelId !== "string" ||
+		request.modelId.length === 0 ||
+		typeof request.systemPrompt !== "string" ||
+		typeof request.userPrompt !== "string" ||
+		!Array.isArray(request.tools) ||
+		request.tools.length !== 0
+	) {
+		throw permanentModelError("Guardian model request is invalid");
+	}
+}
+
+function requestedThinkingLevel(request: GuardianModelRequest): ModelThinkingLevel {
+	return request.reasoning ?? "off";
+}
+
+function assertThinkingSupported(model: Model<Api>, request: GuardianModelRequest): void {
+	const level = requestedThinkingLevel(request);
+	if (!getSupportedThinkingLevels(model).includes(level)) {
+		throw permanentModelError(
+			`Reviewer ${request.provider}/${request.modelId} does not support thinking level ${level}`,
+		);
+	}
+}
+
+function structuredSystemPrompt(request: GuardianModelRequest): string {
+	let schema: string | undefined;
+	try {
+		schema = JSON.stringify(request.outputSchema);
+	} catch (error) {
+		throw permanentModelError("Guardian output schema is not serializable", error);
+	}
+	if (typeof schema !== "string" || schema.length === 0) {
+		throw permanentModelError("Guardian output schema is unavailable");
+	}
+	return `${request.systemPrompt.trimEnd()}\n\n${PI_GUARDIAN_SCHEMA_PREAMBLE}\n${schema}\n`;
+}
+
+function extractResponseText(
+	message: Awaited<ReturnType<ModelRuntime["completeSimple"]>>,
+	request: GuardianModelRequest,
+): GuardianModelResponse {
+	if (message === null || typeof message !== "object") {
+		throw transientModelError("Pi reviewer returned a malformed response");
+	}
+	if (message.provider !== request.provider || message.model !== request.modelId) {
+		throw permanentModelError("Pi reviewer returned a response for a different model");
+	}
+	if (message.stopReason === "aborted") {
+		throw permanentModelError("Pi reviewer request was aborted");
+	}
+	if (message.stopReason === "error") {
+		throw transientModelError("Pi reviewer request failed");
+	}
+	if (!Array.isArray(message.content)) {
+		throw transientModelError("Pi reviewer returned malformed content");
+	}
+
+	const text: string[] = [];
+	for (const block of message.content) {
+		if (block.type === "text") {
+			text.push(block.text);
+			continue;
+		}
+		if (block.type === "thinking") continue;
+		// A reviewer has no tools. A tool call is invalid output even if a provider
+		// fabricates one, and is never executed by this adapter.
+		throw transientModelError("Pi reviewer attempted an unavailable tool call");
+	}
+	return { text: text.join("") };
+}
+
+/**
+ * Adapt Guardian's independent model-call contract to Pi's exact model catalog,
+ * auth stack, and provider runtime. All setup mismatches are permanent,
+ * fail-closed errors. Provider execution failures are eligible only for
+ * Guardian's separate bounded retry policy.
+ */
+export function createPiGuardianModelCall(
+	modelRegistry: ModelRegistry,
+	options: PiGuardianModelCallOptions = {},
+): GuardianModelCall {
+	const now = options.now ?? Date.now;
+	return async (
+		request: GuardianModelRequest,
+		signal: AbortSignal,
+	): Promise<GuardianModelResponse> => {
+		assertReviewerRequest(request);
+		if (signal.aborted) throw permanentModelError("Pi reviewer request was aborted");
+
+		const model = modelRegistry.find(request.provider, request.modelId);
+		if (
+			model === undefined ||
+			model.provider !== request.provider ||
+			model.id !== request.modelId
+		) {
+			throw permanentModelError(
+				`Reviewer model ${request.provider}/${request.modelId} is unavailable`,
+			);
+		}
+		assertThinkingSupported(model, request);
+
+		let auth: Awaited<ReturnType<ModelRegistry["getApiKeyAndHeaders"]>>;
+		try {
+			auth = await modelRegistry.getApiKeyAndHeaders(model);
+		} catch (error) {
+			throw permanentModelError(
+				`Reviewer authentication is unavailable for ${request.provider}`,
+				error,
+			);
+		}
+		if (!auth.ok) {
+			throw permanentModelError(
+				`Reviewer authentication is unavailable for ${request.provider}`,
+			);
+		}
+		// Auth resolution (notably OAuth refresh) has no AbortSignal in Pi's
+		// extension facade. Re-check before provider dispatch so an aggregate
+		// Guardian timeout cannot start a late model request after denial.
+		if (signal.aborted) throw permanentModelError("Pi reviewer request was aborted");
+
+		const runtime = exactRuntime(modelRegistry);
+		const context: Context = {
+			systemPrompt: structuredSystemPrompt(request),
+			messages: [
+				{
+					role: "user",
+					content: request.userPrompt,
+					timestamp: now(),
+				},
+			],
+			tools: [],
+		};
+
+		let message: Awaited<ReturnType<ModelRuntime["completeSimple"]>>;
+		try {
+			message = await runtime.completeSimple(model, context, {
+				signal,
+				maxTokens: Math.min(model.maxTokens, PI_GUARDIAN_MAX_OUTPUT_TOKENS),
+				maxRetries: 0,
+				...(request.reasoning === undefined
+					? {}
+					: { reasoning: request.reasoning as ThinkingLevel }),
+			});
+		} catch (error) {
+			if (signal.aborted) {
+				throw permanentModelError("Pi reviewer request was aborted", error);
+			}
+			throw transientModelError("Pi reviewer request failed", error);
+		}
+		return extractResponseText(message, request);
+	};
+}