@pi-in-go/pigpen-ahp 0.1.0

package/proof/oracle/src/pi/session-storage.ts

@@ -0,0 +1,29 @@
+import { join } from "node:path";
+import { getAgentDir, SessionManager } from "@earendil-works/pi-coding-agent";
+import { PiSessionCatalogue } from "./session-catalogue.ts";
+
+/** Allocates pi's canonical history manager for a newly created session. */
+export type SessionManagerFactory = (workingDirectory: string, sessionId: string) => SessionManager;
+
+/** Paired read/write boundary for pi's durable session corpus. */
+export interface PiSessionStorage {
+	readonly catalogue: PiSessionCatalogue;
+	readonly createSessionManager: SessionManagerFactory;
+}
+
+/** Pi's standard durable, cwd-partitioned session tree. */
+const durableSessionManagerFactory: SessionManagerFactory = (workingDirectory, sessionId) =>
+	SessionManager.create(workingDirectory, undefined, { id: sessionId });
+
+/**
+ * Production storage follows the SDK default: SessionManager resolves each
+ * cwd-partitioned write directory, while the catalogue scans the matching
+ * `getAgentDir()/sessions` root. Pi's separate session-dir precedence lives in
+ * its CLI rather than an exported SDK resolver, so the host does not duplicate it.
+ */
+export function createDefaultPiSessionStorage(): PiSessionStorage {
+	return {
+		catalogue: new PiSessionCatalogue(join(getAgentDir(), "sessions")),
+		createSessionManager: durableSessionManagerFactory,
+	};
+}

package/proof/oracle/src/pi/session-title.ts

@@ -0,0 +1,18 @@
+/** Shared display-title rules for live, catalogued, and hydrated sessions. */
+
+export const NEW_SESSION_TITLE = "New Session";
+const UNTITLED_SESSION_TITLE = "Untitled session";
+const TITLE_FALLBACK_LENGTH = 60;
+
+/** pi displays the first user message when no explicit session name exists. */
+export function fallbackSessionTitle(text: string | undefined): string | undefined {
+	const collapsed = text?.replace(/\s+/gu, " ").trim() ?? "";
+	if (!collapsed) {
+		return undefined;
+	}
+	return collapsed.length > TITLE_FALLBACK_LENGTH ? `${collapsed.slice(0, TITLE_FALLBACK_LENGTH - 1)}…` : collapsed;
+}
+
+export function sessionDisplayTitle(name: string | undefined, firstUserMessage: string | undefined): string {
+	return name?.trim() || fallbackSessionTitle(firstUserMessage) || UNTITLED_SESSION_TITLE;
+}

package/proof/oracle/src/pi/turn-paging.ts

@@ -0,0 +1,94 @@
+/**
+ * Paging older turns into a chat.
+ *
+ * A hydrated chat shows the window pi itself renders — everything back to the
+ * most recent compaction. The conversation before that is still on disk, and
+ * without a way to reach it a long, repeatedly-compacted session looks like it
+ * only ever had its last few exchanges.
+ *
+ * `fetchTurns` is that way. The command returns nothing itself: the host
+ * dispatches `chat/turnsLoaded`, which prepends the older turns into the same
+ * reduced state and updates or clears the cursor.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/chat-channel
+ */
+
+import type { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { Turn } from "@microsoft/agent-host-protocol";
+import { rebuildHistory } from "./history.ts";
+
+/** Turns per page. Large enough to be worth a round-trip, small enough to stay cheap. */
+const DEFAULT_PAGE_SIZE = 20;
+
+export interface OlderTurnsPage {
+	/** Oldest-first, as the action requires. */
+	readonly turns: Turn[];
+	/** Cursor for the next page older than this one, absent when at the beginning. */
+	readonly nextCursor?: string;
+}
+
+/**
+ * Every turn on the session's current branch, ignoring compaction.
+ *
+ * `getBranch()` walks root→leaf, so it sees the whole conversation; the visible
+ * window comes from `buildContextEntries()`, which starts at the last
+ * compaction. Turn ids are derived from the entry that opened each turn, so the
+ * two rebuilds agree on ids wherever they overlap — which is also what lets the
+ * reducer dedupe a page against what the client already holds.
+ */
+function fullBranchTurns(manager: SessionManager, prefix: string): Turn[] {
+	return rebuildHistory(manager.getBranch(), { turnIdPrefix: prefix }).turns;
+}
+
+/**
+ * The cursor to publish for a chat, or `undefined` when nothing older exists.
+ *
+ * Its presence is the protocol's signal that `turns` is a tail window rather
+ * than the whole conversation.
+ */
+export function initialTurnsCursor(
+	manager: SessionManager,
+	prefix: string,
+	visible: readonly Turn[],
+): string | undefined {
+	const oldestVisible = visible[0];
+	if (!oldestVisible) {
+		return undefined;
+	}
+	const full = fullBranchTurns(manager, prefix);
+	const boundary = full.findIndex((turn) => turn.id === oldestVisible.id);
+	// `boundary <= 0` means the visible window already starts at the beginning.
+	return boundary > 0 ? oldestVisible.id : undefined;
+}
+
+/**
+ * Loads the page immediately older than `cursor`.
+ *
+ * The cursor names the oldest turn the client currently holds, so paging is
+ * anchored to content rather than to an offset — appending to a session cannot
+ * shift it, and a cursor for a turn that has since been truncated away simply
+ * finds nothing rather than returning the wrong slice.
+ */
+export function loadOlderTurns(
+	manager: SessionManager,
+	prefix: string,
+	cursor: string | undefined,
+	limit: number = DEFAULT_PAGE_SIZE,
+): OlderTurnsPage {
+	if (!cursor) {
+		return { turns: [] };
+	}
+	const full = fullBranchTurns(manager, prefix);
+	const boundary = full.findIndex((turn) => turn.id === cursor);
+	if (boundary <= 0) {
+		return { turns: [] };
+	}
+
+	const start = Math.max(0, boundary - Math.max(1, limit));
+	const turns = full.slice(start, boundary);
+	return {
+		turns,
+		// More remains only if this page did not reach the beginning.
+		...(start > 0 && turns[0] ? { nextCursor: turns[0].id } : {}),
+	};
+}

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

@@ -0,0 +1,66 @@
+/** Reconstructs the protocol-visible part of a user message stored by pi. */
+
+import {
+	type Message,
+	type MessageAttachment,
+	MessageAttachmentKind,
+	MessageKind,
+} from "@microsoft/agent-host-protocol";
+import { normalizeImageMimeType } from "./image-mime.ts";
+
+interface PiContentBlock {
+	readonly type?: unknown;
+	readonly text?: unknown;
+	readonly data?: unknown;
+	readonly mimeType?: unknown;
+}
+
+function blocksOf(content: unknown): PiContentBlock[] {
+	return Array.isArray(content)
+		? content.filter((block): block is PiContentBlock => typeof block === "object" && block !== null)
+		: [];
+}
+
+export function textFromPiUserContent(content: unknown): string {
+	if (typeof content === "string") {
+		return content;
+	}
+	return blocksOf(content)
+		.filter((block) => block.type === "text" && typeof block.text === "string")
+		.map((block) => block.text as string)
+		.join("");
+}
+
+function imageAttachments(content: unknown): MessageAttachment[] {
+	const attachments: MessageAttachment[] = [];
+	for (const block of blocksOf(content)) {
+		if (block.type !== "image" || typeof block.data !== "string" || typeof block.mimeType !== "string") {
+			continue;
+		}
+		const contentType = normalizeImageMimeType(block.mimeType);
+		if (!contentType) {
+			continue;
+		}
+		attachments.push({
+			type: MessageAttachmentKind.EmbeddedResource,
+			label: `Image ${attachments.length + 1}`,
+			displayKind: "image",
+			data: block.data,
+			contentType,
+		});
+	}
+	return attachments;
+}
+
+/**
+ * pi persists image bytes but not client-side labels, so replay uses stable
+ * ordinal labels while preserving the actual image and MIME type.
+ */
+export function userMessageFromPiContent(content: unknown): Message {
+	const attachments = imageAttachments(content);
+	return {
+		text: textFromPiUserContent(content),
+		origin: { kind: MessageKind.User },
+		...(attachments.length > 0 ? { attachments } : {}),
+	};
+}

package/proof/oracle/src/protocol/errors.ts

@@ -0,0 +1,44 @@
+/**
+ * Protocol-level errors.
+ *
+ * Handlers throw {@link ProtocolError}; the router turns it into a JSON-RPC
+ * error response. Anything else becomes `InternalError` (-32603).
+ */
+
+import { AhpErrorCodes, JsonRpcErrorCodes } from "@microsoft/agent-host-protocol";
+
+export class ProtocolError extends Error {
+	readonly code: number;
+	readonly data: unknown;
+
+	constructor(code: number, message: string, data?: unknown) {
+		super(message);
+		this.name = "ProtocolError";
+		this.code = code;
+		this.data = data;
+	}
+
+	static invalidParams(message: string, data?: unknown): ProtocolError {
+		return new ProtocolError(JsonRpcErrorCodes.InvalidParams, message, data);
+	}
+
+	static methodNotFound(method: string): ProtocolError {
+		return new ProtocolError(JsonRpcErrorCodes.MethodNotFound, `Unknown method: ${method}`);
+	}
+
+	static sessionNotFound(channel: string): ProtocolError {
+		return new ProtocolError(AhpErrorCodes.SessionNotFound, `Session not found: ${channel}`);
+	}
+
+	static sessionAlreadyExists(channel: string): ProtocolError {
+		return new ProtocolError(AhpErrorCodes.SessionAlreadyExists, `Session already exists: ${channel}`);
+	}
+
+	static providerNotFound(provider: string): ProtocolError {
+		return new ProtocolError(AhpErrorCodes.ProviderNotFound, `No agent for provider: ${provider}`);
+	}
+
+	static notFound(uri: string): ProtocolError {
+		return new ProtocolError(AhpErrorCodes.NotFound, `Not found: ${uri}`);
+	}
+}

package/proof/oracle/src/protocol/jsonrpc.ts

@@ -0,0 +1,89 @@
+/**
+ * JSON-RPC 2.0 wire helpers.
+ *
+ * AHP is transport-agnostic JSON-RPC 2.0. Every command's and every
+ * notification's `params` carries a top-level `channel: URI`, so a receiver can
+ * dispatch any message by inspecting `(method, params.channel)` without
+ * per-method deserialisation.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/overview
+ */
+
+import type { URI } from "@microsoft/agent-host-protocol";
+
+/** A JSON-RPC request: has both `method` and `id`. */
+export interface JsonRpcRequest {
+	readonly jsonrpc: "2.0";
+	readonly id: number;
+	readonly method: string;
+	readonly params?: unknown;
+}
+
+/** A JSON-RPC notification: has `method` but no `id`. */
+export interface JsonRpcNotification {
+	readonly jsonrpc: "2.0";
+	readonly method: string;
+	readonly params?: unknown;
+}
+
+export interface JsonRpcSuccessResponse {
+	readonly jsonrpc: "2.0";
+	readonly id: number;
+	readonly result: unknown;
+}
+
+export interface JsonRpcErrorResponse {
+	readonly jsonrpc: "2.0";
+	readonly id: number;
+	readonly error: {
+		readonly code: number;
+		readonly message: string;
+		readonly data?: unknown;
+	};
+}
+
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+export function isJsonRpcRequest(message: unknown): message is JsonRpcRequest {
+	return isObject(message) && typeof message.method === "string" && typeof message.id === "number";
+}
+
+export function isJsonRpcNotification(message: unknown): message is JsonRpcNotification {
+	return isObject(message) && typeof message.method === "string" && message.id === undefined;
+}
+
+/**
+ * Reads the universal routing key off a message's params.
+ *
+ * Returns `undefined` when the params are missing or carry no `channel`, which
+ * the caller surfaces as `InvalidParams` — the field is required on every
+ * command and notification in the protocol.
+ */
+export function readChannel(params: unknown): URI | undefined {
+	if (!isObject(params)) {
+		return undefined;
+	}
+	const channel = params.channel;
+	return typeof channel === "string" ? channel : undefined;
+}
+
+export function successResponse(id: number, result: unknown): JsonRpcSuccessResponse {
+	return { jsonrpc: "2.0", id, result };
+}
+
+export function errorResponse(id: number, code: number, message: string, data?: unknown): JsonRpcErrorResponse {
+	return {
+		jsonrpc: "2.0",
+		id,
+		error: data === undefined ? { code, message } : { code, message, data },
+	};
+}
+
+export function notification(method: string, params: unknown): JsonRpcNotification {
+	return { jsonrpc: "2.0", method, params };
+}

package/proof/oracle/src/protocol/version.ts

@@ -0,0 +1,39 @@
+/**
+ * Protocol version negotiation.
+ *
+ * The client offers `InitializeParams.protocolVersions` most-preferred first;
+ * the server picks the first entry it can speak and echoes it back as
+ * `InitializeResult.protocolVersion`. If there is no overlap the server MUST
+ * return `UnsupportedProtocolVersion` (-32005) rather than a result.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/versioning
+ */
+
+import { AhpErrorCodes, PROTOCOL_VERSION } from "@microsoft/agent-host-protocol";
+import { ProtocolError } from "./errors.ts";
+
+/** Generated wire models do not down-convert required fields across minor versions. */
+const HOST_SUPPORTED_VERSIONS: readonly string[] = [PROTOCOL_VERSION];
+
+/**
+ * Picks the client's most-preferred version that this host also speaks.
+ *
+ * @throws {ProtocolError} `UnsupportedProtocolVersion` when there is no overlap.
+ *   The error `data` advertises what the host can speak so the client can
+ *   decide whether to downgrade.
+ */
+export function negotiateProtocolVersion(offered: readonly string[] | undefined): string {
+	if (!Array.isArray(offered) || offered.length === 0 || offered.some((version) => typeof version !== "string")) {
+		throw ProtocolError.invalidParams("initialize requires a non-empty protocolVersions array of strings");
+	}
+	for (const candidate of offered) {
+		if (HOST_SUPPORTED_VERSIONS.includes(candidate)) {
+			return candidate;
+		}
+	}
+	throw new ProtocolError(
+		AhpErrorCodes.UnsupportedProtocolVersion,
+		`No mutually supported protocol version. Offered: ${offered.join(", ")}`,
+		{ supportedVersions: [...HOST_SUPPORTED_VERSIONS] },
+	);
+}

package/proof/oracle/src/transport/websocket.ts

@@ -0,0 +1,136 @@
+/**
+ * WebSocket transport.
+ *
+ * AHP does not mandate a transport — anything reliable, ordered, bidirectional,
+ * and message-framed works. This transport carries one JSON-RPC message per
+ * WebSocket frame.
+ *
+ * Access control to the endpoint itself is a transport concern, handled here
+ * during the HTTP upgrade rather than inside the protocol.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/transport
+ */
+
+import { createServer, type Server as HttpServer } from "node:http";
+import { type WebSocket, WebSocketServer } from "ws";
+import type { Transport } from "../core/connection.ts";
+import type { AhpHost } from "../core/host.ts";
+import type { JsonRpcMessage } from "../protocol/jsonrpc.ts";
+
+export interface WebSocketTransportOptions {
+	readonly host?: string;
+	readonly port?: number;
+	/** Expected as `?token=` or VS Code's `?tkn=` when set. */
+	readonly connectionToken?: string;
+	readonly log?: (message: string) => void;
+}
+
+class WebSocketClientTransport implements Transport {
+	readonly #socket: WebSocket;
+	readonly #log: ((message: string) => void) | undefined;
+
+	constructor(socket: WebSocket, log?: (message: string) => void) {
+		this.#socket = socket;
+		this.#log = log;
+	}
+
+	send(message: JsonRpcMessage): void {
+		if (this.#socket.readyState === this.#socket.OPEN) {
+			this.#socket.send(JSON.stringify(message));
+		}
+	}
+
+	close(): void {
+		this.#socket.close();
+	}
+
+	onMessage(handler: (message: unknown) => void): void {
+		this.#socket.on("message", (data: Buffer | ArrayBuffer | Buffer[]) => {
+			const text = Array.isArray(data)
+				? Buffer.concat(data).toString("utf8")
+				: Buffer.from(data as Buffer).toString("utf8");
+			try {
+				handler(JSON.parse(text));
+			} catch (error) {
+				// A frame we cannot parse has no `id`, so there is nobody to answer.
+				this.#log?.(`Dropping unparseable frame: ${String(error)}`);
+			}
+		});
+	}
+
+	onClose(handler: () => void): void {
+		this.#socket.on("close", handler);
+	}
+}
+
+export interface RunningServer {
+	readonly host: string;
+	readonly port: number;
+	close(): Promise<void>;
+}
+
+/** Starts a WebSocket server and wires each connection into the host. */
+export async function serveWebSocket(
+	ahpHost: AhpHost,
+	options: WebSocketTransportOptions = {},
+): Promise<RunningServer> {
+	const bindHost = options.host ?? "127.0.0.1";
+	// Port 0 asks the OS for a free port; the caller reads the real one back.
+	const bindPort = options.port ?? 0;
+
+	const httpServer: HttpServer = createServer((_request, response) => {
+		response.writeHead(426, { "Content-Type": "text/plain" });
+		response.end("Upgrade required");
+	});
+
+	const wss = new WebSocketServer({ noServer: true });
+
+	httpServer.on("upgrade", (request, socket, head) => {
+		if (options.connectionToken) {
+			const url = new URL(request.url ?? "/", "http://localhost");
+			// VS Code calls a manually configured connection token `tkn`; generic
+			// AHP examples use `token`, so a protected direct listener accepts both.
+			const presented = url.searchParams.get("token") ?? url.searchParams.get("tkn");
+			if (presented !== options.connectionToken) {
+				options.log?.("Rejecting upgrade: bad token");
+				socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+				socket.destroy();
+				return;
+			}
+		}
+		wss.handleUpgrade(request, socket, head, (ws) => {
+			wss.emit("connection", ws, request);
+		});
+	});
+
+	wss.on("connection", (socket: WebSocket) => {
+		ahpHost.accept(new WebSocketClientTransport(socket, options.log));
+	});
+
+	await new Promise<void>((resolve, reject) => {
+		httpServer.once("error", reject);
+		httpServer.listen(bindPort, bindHost, () => {
+			httpServer.removeListener("error", reject);
+			resolve();
+		});
+	});
+
+	const address = httpServer.address();
+	if (address === null || typeof address === "string") {
+		throw new Error("Failed to determine the bound address");
+	}
+
+	return {
+		host: bindHost,
+		port: address.port,
+		close: () =>
+			new Promise<void>((resolve) => {
+				for (const client of wss.clients) {
+					client.terminate();
+				}
+				wss.close(() => {
+					httpServer.close(() => resolve());
+				});
+			}),
+	};
+}