@pi-in-go/pigpen-ahp 0.1.0

package/proof/oracle/src/pi/message-input.ts

@@ -0,0 +1,212 @@
+/**
+ * Converts supported AHP user-message attachments into pi's prompt shape.
+ * Resource references become paths or URIs, simple attachments contribute their
+ * model representation, embedded text is decoded as UTF-8, and embedded images
+ * become pi image-content blocks. Other attachment kinds remain unsupported.
+ */
+
+import { fileURLToPath } from "node:url";
+import type { ImageContent } from "@earendil-works/pi-ai";
+import {
+	type Message,
+	MessageAttachmentKind,
+	type MessageEmbeddedResourceAttachment,
+	type MessageResourceAttachment,
+	type TextRange,
+} from "@microsoft/agent-host-protocol";
+import { normalizeImageMimeType } from "./image-mime.ts";
+
+export interface PiMessageInput {
+	readonly text: string;
+	readonly images?: ImageContent[];
+}
+
+type RejectedMessage = { readonly rejectionReason: string };
+type PreparedMessage = PiMessageInput | RejectedMessage;
+type PreparedText = { readonly text: string } | RejectedMessage;
+type PreparedEmbedded = { readonly text: string } | { readonly image: ImageContent } | RejectedMessage;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isTextRange(value: unknown): value is TextRange {
+	if (!isRecord(value) || !isRecord(value.start) || !isRecord(value.end)) return false;
+	return [value.start.line, value.start.character, value.end.line, value.end.character].every(isNonNegativeInteger);
+}
+
+function decodeBase64(data: unknown): Buffer | undefined {
+	if (typeof data !== "string" || !/^[A-Za-z0-9+/]*={0,2}$/u.test(data) || data.length % 4 === 1) {
+		return undefined;
+	}
+	const padding = data.indexOf("=");
+	if (padding !== -1 && (padding < data.length - 2 || data.length % 4 !== 0)) {
+		return undefined;
+	}
+	const decoded = Buffer.from(data, "base64");
+	const canonical = decoded.toString("base64").replace(/=+$/u, "");
+	return canonical === data.replace(/=+$/u, "") ? decoded : undefined;
+}
+
+function rangeText(range: TextRange): string {
+	return `${range.start.line + 1}:${range.start.character + 1}-${range.end.line + 1}:${range.end.character + 1}`;
+}
+
+function baseContentType(contentType: string): string {
+	return contentType.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+}
+
+function embeddedContent(attachment: MessageEmbeddedResourceAttachment): PreparedEmbedded {
+	if (typeof attachment.contentType !== "string") {
+		return { rejectionReason: `Embedded resource ${attachment.label} requires a content type` };
+	}
+	const contentType = baseContentType(attachment.contentType);
+	if (!contentType) {
+		return { rejectionReason: `Embedded resource ${attachment.label} requires a content type` };
+	}
+	const bytes = decodeBase64(attachment.data);
+	if (!bytes) {
+		return { rejectionReason: `Embedded resource ${attachment.label} is not valid base64` };
+	}
+
+	const imageMimeType = normalizeImageMimeType(contentType);
+	if (imageMimeType) {
+		if (bytes.length === 0) {
+			return { rejectionReason: `Embedded image ${attachment.label} is empty` };
+		}
+		return {
+			image: {
+				type: "image",
+				data: bytes.toString("base64"),
+				mimeType: imageMimeType,
+			},
+		};
+	}
+
+	// MIME is advisory for non-images: successful UTF-8 decoding decides whether
+	// an embedded resource can safely join pi's text prompt.
+	let decoded: string;
+	try {
+		decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		return { rejectionReason: `Embedded resource ${attachment.label} is not valid UTF-8` };
+	}
+	const selected = attachment.selection?.range;
+	if (!selected) {
+		return { text: decoded };
+	}
+	return { text: `[selection ${rangeText(selected)}]\n${decoded}` };
+}
+
+function resourceText(attachment: MessageResourceAttachment): PreparedText {
+	if (typeof attachment.uri !== "string") {
+		return { rejectionReason: "A resource attachment requires a URI" };
+	}
+	const selected = attachment.selection?.range;
+	let reference = attachment.uri;
+	if (/^file:/iu.test(reference)) {
+		try {
+			reference = fileURLToPath(reference);
+		} catch {
+			// Preserve a remote or malformed file URI rather than guessing a path.
+		}
+	}
+	return { text: `${reference}${selected ? `:${rangeText(selected)}` : ""}` };
+}
+
+function prepareMessage(value: unknown): PreparedMessage {
+	if (
+		!isRecord(value) ||
+		typeof value.text !== "string" ||
+		!isRecord(value.origin) ||
+		typeof value.origin.kind !== "string"
+	) {
+		return { rejectionReason: "A message requires text and an origin" };
+	}
+	if (value.attachments !== undefined && !Array.isArray(value.attachments)) {
+		return { rejectionReason: "Message attachments must be an array" };
+	}
+	if (value.model !== undefined && (!isRecord(value.model) || typeof value.model.id !== "string")) {
+		return { rejectionReason: "A message model requires an id" };
+	}
+	if (value.agent !== undefined) {
+		return { rejectionReason: "This host does not support custom agents" };
+	}
+	const message = value as unknown as Message;
+
+	const representations: string[] = [];
+	const images: ImageContent[] = [];
+	for (const attachment of message.attachments ?? []) {
+		if (!isRecord(attachment) || typeof attachment.type !== "string" || typeof attachment.label !== "string") {
+			return { rejectionReason: "Every message attachment requires a type and label" };
+		}
+		if (attachment.range !== undefined && !isTextRange(attachment.range)) {
+			return { rejectionReason: `Attachment ${attachment.label} has an invalid text range` };
+		}
+		if (
+			"selection" in attachment &&
+			attachment.selection !== undefined &&
+			(!isRecord(attachment.selection) || !isTextRange(attachment.selection.range))
+		) {
+			return { rejectionReason: `Attachment ${attachment.label} has an invalid text selection` };
+		}
+		switch (attachment.type) {
+			case MessageAttachmentKind.Resource: {
+				const resource = resourceText(attachment);
+				if ("rejectionReason" in resource) {
+					return resource;
+				}
+				representations.push(resource.text);
+				break;
+			}
+			case MessageAttachmentKind.Simple:
+				if (typeof attachment.modelRepresentation !== "string") {
+					return { rejectionReason: "A simple attachment requires modelRepresentation" };
+				}
+				if (attachment.modelRepresentation) {
+					representations.push(attachment.modelRepresentation);
+				}
+				break;
+			case MessageAttachmentKind.EmbeddedResource: {
+				const embedded = embeddedContent(attachment);
+				if ("rejectionReason" in embedded) {
+					return embedded;
+				}
+				if ("image" in embedded) {
+					images.push(embedded.image);
+				} else {
+					representations.push(embedded.text);
+				}
+				break;
+			}
+			default:
+				return { rejectionReason: `This host does not support ${attachment.type} attachments` };
+		}
+	}
+
+	return {
+		text: [message.text, ...representations].filter(Boolean).join("\n\n"),
+		...(images.length > 0 ? { images } : {}),
+	};
+}
+
+export function messageRejectionReason(message: unknown): string | undefined {
+	const prepared = prepareMessage(message);
+	return "rejectionReason" in prepared ? prepared.rejectionReason : undefined;
+}
+
+export function messageInputForPi(message: Message): PiMessageInput {
+	const prepared = prepareMessage(message);
+	if ("rejectionReason" in prepared) {
+		throw new Error(prepared.rejectionReason);
+	}
+	return prepared;
+}
+
+export function messageTextForPi(message: Message): string {
+	return messageInputForPi(message).text;
+}

package/proof/oracle/src/pi/models.ts

@@ -0,0 +1,124 @@
+/**
+ * Maps pi's model catalogue onto the protocol's agent/model description.
+ *
+ * The host advertises exactly one agent — pi — with the models its current
+ * runtime reports as available. Model-specific options such as pi's thinking
+ * level travel as a `configSchema`, the protocol's escape hatch for this:
+ * clients render it as a form and pass the values back in `ModelSelection`.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/root-channel
+ */
+
+import { getSupportedThinkingLevels, type Model, type ModelThinkingLevel } from "@earendil-works/pi-ai";
+import type { AgentInfo, ConfigSchema, SessionModelInfo } from "@microsoft/agent-host-protocol";
+import { PI_PROVIDER } from "./provider.ts";
+
+export type ThinkingLevel = ModelThinkingLevel;
+
+interface PiModelIdentity {
+	readonly provider: string;
+	readonly id: string;
+}
+
+/** AHP needs one opaque id, so use pi's canonical `provider/modelId` reference. */
+export function modelSelectionId(model: PiModelIdentity): string {
+	return `${model.provider}/${model.id}`;
+}
+
+/**
+ * Resolves a wire id, with a narrow fallback for drafts written by older hosts.
+ * An ambiguous legacy id is accepted only when it already names the current
+ * model; otherwise guessing a provider would run the turn somewhere unintended.
+ */
+export function findModelBySelectionId<T extends PiModelIdentity>(
+	models: readonly T[],
+	selectionId: string,
+	current?: PiModelIdentity,
+): T | undefined {
+	const qualified = models.find((model) => modelSelectionId(model) === selectionId);
+	if (qualified) {
+		return qualified;
+	}
+
+	const legacyMatches = models.filter((model) => model.id === selectionId);
+	if (legacyMatches.length === 1) {
+		return legacyMatches[0];
+	}
+	if (current?.id === selectionId) {
+		return legacyMatches.find((model) => model.provider === current.provider);
+	}
+	return undefined;
+}
+
+/** The config key carrying the thinking level in `ModelSelection.config`. */
+export const THINKING_CONFIG_KEY = "thinkingLevel";
+
+/** Uses pi's own capability rules so the advertised picker cannot drift. */
+export function supportedThinkingLevels(model: Model<never>): ThinkingLevel[] {
+	return getSupportedThinkingLevels(model);
+}
+
+function thinkingConfigSchema(model: Model<never>): ConfigSchema | undefined {
+	const levels = supportedThinkingLevels(model);
+	// A model with only `off` has nothing to configure; omitting the schema
+	// keeps the client from rendering a pointless single-option picker.
+	if (levels.length <= 1) {
+		return undefined;
+	}
+	return {
+		type: "object",
+		properties: {
+			[THINKING_CONFIG_KEY]: {
+				type: "string",
+				title: "Thinking",
+				description: "How much reasoning effort the model spends before answering.",
+				default: levels.includes("medium") ? "medium" : levels[0],
+				enum: [...levels],
+				enumLabels: levels.map((level) => level.charAt(0).toUpperCase() + level.slice(1)),
+			},
+		},
+	};
+}
+
+export function toSessionModelInfo(model: Model<never>): SessionModelInfo {
+	const configSchema = thinkingConfigSchema(model);
+	return {
+		id: modelSelectionId(model),
+		provider: PI_PROVIDER,
+		name: model.name,
+		maxContextWindow: model.contextWindow,
+		maxOutputTokens: model.maxTokens,
+		supportsVision: model.input.includes("image"),
+		...(configSchema ? { configSchema } : {}),
+		// `_meta` is the protocol's documented place for provider-specific
+		// extras; clients may surface pricing but must not depend on it.
+		_meta: {
+			piProvider: model.provider,
+			api: model.api,
+			pricing: model.cost,
+		},
+	};
+}
+
+/**
+ * Builds the single `AgentInfo` this host advertises.
+ *
+ * Empty `protectedResources`: pi resolves model-provider credentials itself,
+ * so there is nothing for the client to authenticate against at the protocol
+ * level. Keeping the empty list explicit also distinguishes that settled state
+ * for clients that conservatively treat an omitted field as unresolved.
+ *
+ * No `capabilities`: this host serves one chat per session and one working
+ * directory, so neither `multipleChats` nor `multipleWorkingDirectories` is
+ * declared. Their absence is what tells a client not to attempt those calls.
+ * Vision is model-specific instead and is published on each model above.
+ */
+export function buildAgentInfo(models: readonly Model<never>[]): AgentInfo {
+	return {
+		provider: PI_PROVIDER,
+		displayName: "pi",
+		description: "pi coding agent",
+		models: models.map(toSessionModelInfo),
+		protectedResources: [],
+	};
+}

package/proof/oracle/src/pi/project-trust.ts

@@ -0,0 +1,66 @@
+/**
+ * Project trust.
+ *
+ * A working directory can carry trust-gated pi resources: `.pi` settings,
+ * extensions, skills, prompts, themes and system instructions, plus inherited
+ * `.agents/skills`. Loading some of them executes project-controlled code or
+ * changes the agent's instructions.
+ *
+ * The interactive CLI resolves trust before loading those resources. Raw SDK
+ * construction instead defaults `projectTrusted` to true, so an embedding host
+ * must supply its decision explicitly. That matters here because
+ * `createSession` accepts the working directory from a remote client.
+ *
+ * The default `trust` policy preserves the SDK default. The stricter `inherit`
+ * policy reuses pi's trust store, so decisions made by either program apply to
+ * both.
+ */
+
+import { getAgentDir, hasTrustRequiringProjectResources, ProjectTrustStore } from "@earendil-works/pi-coding-agent";
+
+/**
+ * What to do about a working directory pi has no recorded decision for.
+ *
+ * - `trust` (default) — load project resources unconditionally, matching raw
+ *   SDK construction.
+ * - `inherit` — honour pi's trust store; decline for a directory it has no
+ *   decision for.
+ * - `never` — never load project resources.
+ */
+export type ProjectTrustPolicy = "trust" | "inherit" | "never";
+
+export interface TrustDecision {
+	readonly trusted: boolean;
+	/** Why, so a client can explain it rather than silently degrade. */
+	readonly reason: "no-project-resources" | "user-trusted" | "user-untrusted" | "policy" | "unknown-project";
+}
+
+export function resolveProjectTrust(
+	cwd: string,
+	policy: ProjectTrustPolicy = "trust",
+	agentDir: string = getAgentDir(),
+): TrustDecision {
+	if (policy === "never") {
+		return { trusted: false, reason: "policy" };
+	}
+
+	// Nothing in the directory needs gating — trusting it grants nothing.
+	if (!hasTrustRequiringProjectResources(cwd)) {
+		return { trusted: true, reason: "no-project-resources" };
+	}
+
+	if (policy === "trust") {
+		return { trusted: true, reason: "policy" };
+	}
+
+	// The very same store pi's CLI writes, so decisions carry both ways.
+	const stored = new ProjectTrustStore(agentDir).get(cwd);
+	if (stored === true) {
+		return { trusted: true, reason: "user-trusted" };
+	}
+	if (stored === false) {
+		return { trusted: false, reason: "user-untrusted" };
+	}
+	// No recorded decision, and a host has no user to ask.
+	return { trusted: false, reason: "unknown-project" };
+}

package/proof/oracle/src/pi/provider.ts

@@ -0,0 +1,2 @@
+/** The single `AgentInfo.provider` this host advertises. */
+export const PI_PROVIDER = "pi";

package/proof/oracle/src/pi/resource-paths.ts

@@ -0,0 +1,80 @@
+/** Shared file-URI parsing and root policy for resource commands and watches. */
+
+import { realpathSync } from "node:fs";
+import { lstat, readlink, realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AhpErrorCodes } from "@microsoft/agent-host-protocol";
+import { ProtocolError } from "../protocol/errors.ts";
+
+function errorCodeOf(error: unknown): string | undefined {
+	return (error as NodeJS.ErrnoException | undefined)?.code;
+}
+
+/** Resolves symlinks in the existing prefix while preserving a missing suffix. */
+async function canonicalPath(path: string): Promise<string> {
+	const absolute = resolve(path);
+	try {
+		return await realpath(absolute);
+	} catch (error) {
+		if (errorCodeOf(error) !== "ENOENT") throw error;
+	}
+
+	try {
+		if ((await lstat(absolute)).isSymbolicLink()) {
+			const target = await readlink(absolute);
+			return canonicalPath(resolve(dirname(absolute), target));
+		}
+	} catch (error) {
+		if (errorCodeOf(error) !== "ENOENT") throw error;
+	}
+
+	const parent = dirname(absolute);
+	return parent === absolute ? absolute : join(await canonicalPath(parent), basename(absolute));
+}
+
+/**
+ * Converts resource URIs to local paths and applies the optional root allowlist.
+ *
+ * A single policy instance can be shared by request/response resource methods
+ * and live resource watches, keeping both surfaces on the same access rules.
+ * Empty roots intentionally mean unrestricted access: reaching this endpoint
+ * already permits starting pi with shell tools, so this is not a sandbox.
+ */
+export class ResourcePathPolicy {
+	readonly #roots: readonly string[];
+
+	constructor(roots: readonly string[] = []) {
+		this.#roots = roots.map((root) => realpathSync(resolve(root)));
+	}
+
+	async pathFor(uri: unknown): Promise<string> {
+		if (typeof uri !== "string" || !uri.startsWith("file://")) {
+			throw ProtocolError.invalidParams(`Only file: URIs are supported, got: ${uri}`);
+		}
+		let path: string;
+		try {
+			path = fileURLToPath(uri);
+		} catch {
+			throw ProtocolError.invalidParams(`Malformed file URI: ${uri}`);
+		}
+		if (this.#roots.length === 0) {
+			return path;
+		}
+
+		let candidate: string;
+		try {
+			candidate = await canonicalPath(path);
+		} catch (error) {
+			if (error instanceof ProtocolError) throw error;
+			throw new ProtocolError(AhpErrorCodes.PermissionDenied, error instanceof Error ? error.message : String(error));
+		}
+		const permitted = this.#roots.some(
+			(root) => candidate === root || candidate.startsWith(root.endsWith(sep) ? root : root + sep),
+		);
+		if (!permitted) {
+			throw new ProtocolError(AhpErrorCodes.PermissionDenied, `Outside the permitted roots: ${uri}`);
+		}
+		return path;
+	}
+}