@pi-in-go/pigpen-ahp 0.1.0

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

@@ -0,0 +1,84 @@
+/**
+ * Pre-creation session configuration.
+ *
+ * Before `createSession`, a client asks the host what a new session needs to be
+ * configured with. The exchange is iterative: the client sends the working
+ * directory and whatever the user has filled in so far, and the host returns the
+ * *full* current property set plus resolved values — never a delta — so options
+ * can appear and disappear as earlier choices are made.
+ *
+ * Model selection stays out of this schema: models are advertised on
+ * `AgentInfo.models` and chosen per message via `Message.model`. The schema here
+ * covers only what pi must decide before creating the session.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/root-channel
+ */
+
+import type {
+	ResolveSessionConfigParams,
+	ResolveSessionConfigResult,
+	SessionConfigCompletionsParams,
+	SessionConfigCompletionsResult,
+	SessionConfigSchema,
+} from "@microsoft/agent-host-protocol";
+import { fileUriToPath } from "../core/uri.ts";
+import { type ProjectTrustPolicy, resolveProjectTrust } from "./project-trust.ts";
+
+/** Config key describing whether trust-gated project resources load. */
+export const PROJECT_TRUST_KEY = "projectResources";
+
+export interface SessionConfigOptions {
+	readonly defaultWorkingDirectory: string;
+	readonly projectTrustPolicy?: ProjectTrustPolicy;
+}
+
+export class SessionConfigService {
+	readonly #options: SessionConfigOptions;
+
+	constructor(options: SessionConfigOptions) {
+		this.#options = options;
+	}
+
+	/**
+	 * Describes what a new session in this directory would do.
+	 *
+	 * Only one property, and it is read-only: whether trust-gated resources from
+	 * the target directory and its ancestors will load. It is surfaced because
+	 * the answer changes with the directory and materially changes the agent's
+	 * tools, settings, and instructions.
+	 */
+	resolve(params: ResolveSessionConfigParams): ResolveSessionConfigResult {
+		const workingDirectory = params.workingDirectory
+			? fileUriToPath(params.workingDirectory)
+			: this.#options.defaultWorkingDirectory;
+		const trust = resolveProjectTrust(workingDirectory, this.#options.projectTrustPolicy);
+
+		const schema: SessionConfigSchema = {
+			type: "object",
+			properties: {
+				[PROJECT_TRUST_KEY]: {
+					type: "boolean",
+					title: "Load project resources",
+					description:
+						trust.reason === "no-project-resources"
+							? "This folder has no trust-gated project resources."
+							: `Trust-gated project resources (${trust.reason}).`,
+					// Host policy, not a per-session choice — see project-trust.ts.
+					readOnly: true,
+				},
+			},
+		};
+
+		return { schema, values: { [PROJECT_TRUST_KEY]: trust.trusted } };
+	}
+
+	/**
+	 * No dynamic values to enumerate.
+	 *
+	 * Every property this host exposes has a static domain, so the completions
+	 * endpoint exists only to keep a client that probes it from erroring.
+	 */
+	completions(_params: SessionConfigCompletionsParams): SessionConfigCompletionsResult {
+		return { items: [] };
+	}
+}

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

@@ -0,0 +1,75 @@
+/**
+ * The parts of a session that are about its *history file* rather than its
+ * lifecycle: paging older turns in, and resolving where a truncation lands.
+ *
+ * Both are questions about pi's append-only entry tree, not about registries or
+ * channels, and both need the same two things — a session manager and the id
+ * prefix its turn ids were built from. Keeping them beside the rebuild they
+ * depend on means the registry stays about *live sessions* instead of also
+ * knowing how a turn id maps onto a session entry.
+ */
+
+import type { SessionManager } from "@earendil-works/pi-coding-agent";
+import { ActionType, type ChatState, type URI } from "@microsoft/agent-host-protocol";
+import type { AhpHost } from "../core/host.ts";
+import { ProtocolError } from "../protocol/errors.ts";
+import { CLEAR_ALL_ANCHOR, rebuildHistoryFromSession } from "./history.ts";
+import { loadOlderTurns } from "./turn-paging.ts";
+
+/** The session file, and the prefix its turn ids were derived from. */
+export interface HistorySource {
+	readonly sessionManager: SessionManager;
+	readonly sessionId: string;
+	/**
+	 * Anchors already known for turns this host ran itself.
+	 *
+	 * Consulted first because a live turn's id came from the client and cannot
+	 * be recomputed from the file.
+	 */
+	readonly turnAnchors: ReadonlyMap<string, string>;
+}
+
+/**
+ * Resolves the pi entry a `chat/truncated` names.
+ *
+ * `undefined` turnId means "clear everything", which maps to the very first
+ * user message: navigating to a user entry lands the leaf on its parent, and
+ * the first one's parent is `null`.
+ */
+export function truncationAnchor(source: HistorySource, turnId: string | undefined): string | undefined {
+	const key = turnId ?? CLEAR_ALL_ANCHOR;
+	const known = source.turnAnchors.get(key);
+	if (known) {
+		return known;
+	}
+	// A turn this host never ran: recompute from the file, which is where a
+	// hydrated session's ids came from in the first place.
+	return rebuildHistoryFromSession(source.sessionManager, { turnIdPrefix: source.sessionId }).anchors.get(key);
+}
+
+/**
+ * Serves `fetchTurns` for a chat.
+ *
+ * Dispatches the page before returning, as the protocol requires — the client's
+ * state must already hold it when the call resolves.
+ */
+export function dispatchOlderTurns(
+	host: AhpHost,
+	channel: URI,
+	source: HistorySource,
+	cursor: string | undefined,
+): void {
+	const state = host.store.get(channel) as ChatState | undefined;
+	if (cursor !== undefined && cursor !== state?.turnsNextCursor) {
+		throw ProtocolError.invalidParams(`Unrecognised fetchTurns cursor for ${channel}`);
+	}
+
+	const page = loadOlderTurns(source.sessionManager, source.sessionId, cursor);
+	// Dispatched even when empty: it is what clears a cursor that has no more
+	// history behind it, so the client stops asking.
+	host.dispatchServerAction(channel, {
+		type: ActionType.ChatTurnsLoaded,
+		turns: page.turns,
+		...(page.nextCursor ? { turnsNextCursor: page.nextCursor } : {}),
+	});
+}

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

@@ -0,0 +1,219 @@
+/**
+ * Loads a durable pi session into live channel state.
+ *
+ * Sessions outlive the host process: pi writes them to
+ * `~/.pi/agent/sessions/**`, `listSessions` reports them, and a client then
+ * subscribes to one. Only sessions this host created are in memory, so opening
+ * any other one has to reconstruct its channels from disk — otherwise
+ * `subscribe` answers `NotFound` for a session the catalogue just advertised.
+ */
+
+import { stat } from "node:fs/promises";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import {
+	type ChatState,
+	MessageKind,
+	type ModelSelection,
+	SessionLifecycle,
+	type SessionState,
+	SessionStatus,
+	type URI,
+} from "@microsoft/agent-host-protocol";
+import { chatSummaryOf } from "../channels/chat.ts";
+import { chatIdFromUri, chatUri, isChatChannel, sessionIdFromUri, sessionUri } from "../core/channels.ts";
+import type { AhpHost, ChannelHydrator } from "../core/host.ts";
+import { pathToFileUri } from "../core/uri.ts";
+import { rebuildTurnsFromSession } from "./history.ts";
+import { modelSelectionId, THINKING_CONFIG_KEY } from "./models.ts";
+import { PI_PROVIDER } from "./provider.ts";
+import type { PiSessionCatalogue } from "./session-catalogue.ts";
+import { sessionDisplayTitle } from "./session-title.ts";
+import { initialTurnsCursor } from "./turn-paging.ts";
+
+export interface SessionHydratorOptions {
+	readonly host: AhpHost;
+	readonly catalogue: PiSessionCatalogue;
+	/** Sessions this host already has live; those must never be reloaded over. */
+	readonly isLive: (sessionChannel: URI) => boolean;
+	/** Prevents a disk session from becoming live while its removal is pending. */
+	readonly isDisposing: (sessionChannel: URI) => boolean;
+	/**
+	 * The model to show when the session file records none.
+	 *
+	 * A hydrated session has no agent yet, so nothing else can answer "which
+	 * model is selected" — and a client with an empty picker cannot send.
+	 */
+	readonly fallbackSelection?: () => ModelSelection | undefined;
+	/**
+	 * Registers the loaded session so it can later run turns.
+	 *
+	 * Without this a resumed session is read-only in a way nothing reports:
+	 * the client's message reduces into state and echoes back, but no agent is
+	 * listening and no reply ever comes.
+	 */
+	readonly adopt?: (session: {
+		uri: URI;
+		sessionId: string;
+		workingDirectory: string;
+		sessionManager: SessionManager;
+		chatChannel: URI;
+		createdAt: string;
+	}) => void;
+	readonly log?: (message: string) => void;
+}
+
+export class SessionHydrator implements ChannelHydrator {
+	readonly #options: SessionHydratorOptions;
+	/** Session and chat subscriptions for one id join the same disk materialization. */
+	readonly #hydrations = new Map<string, Promise<void>>();
+
+	constructor(options: SessionHydratorOptions) {
+		this.#options = options;
+	}
+
+	async hydrate(channel: URI): Promise<boolean> {
+		// A chat and its session share one id, so either URI loads the pair.
+		// The provider alias is explicit: an unknown channel scheme must not
+		// become a session merely because its path resembles one.
+		const sessionId = isChatChannel(channel) ? chatIdFromUri(channel) : sessionIdFromUri(channel, [PI_PROVIDER]);
+		if (!sessionId) {
+			return false;
+		}
+
+		// Register the session under the URI the client actually used, so a
+		// non-standard scheme resolves to the same channel it subscribed to.
+		const session = isChatChannel(channel) ? sessionUri(sessionId) : channel;
+		if (this.#options.isLive(session)) {
+			return this.#options.host.store.has(channel);
+		}
+		if (this.#options.isDisposing(session)) {
+			return false;
+		}
+
+		const pending = this.#hydrations.get(sessionId);
+		if (pending) {
+			await pending;
+			return this.#options.host.store.has(channel);
+		}
+
+		const hydration = this.#hydrateSession(sessionId, session);
+		this.#hydrations.set(sessionId, hydration);
+		try {
+			await hydration;
+		} finally {
+			if (this.#hydrations.get(sessionId) === hydration) {
+				this.#hydrations.delete(sessionId);
+			}
+		}
+		return this.#options.host.store.has(channel);
+	}
+
+	async #hydrateSession(sessionId: string, session: URI): Promise<void> {
+		const chat = chatUri(sessionId);
+		const file = await this.#options.catalogue.findSessionFile(sessionId);
+		if (!file) {
+			return;
+		}
+
+		let manager: SessionManager;
+		try {
+			manager = SessionManager.open(file);
+		} catch (error) {
+			this.#options.log?.(`cannot open ${file}: ${String(error)}`);
+			return;
+		}
+
+		const turns = rebuildTurnsFromSession(manager, { turnIdPrefix: sessionId });
+		// Present only when the window really is a tail: its presence is the
+		// protocol's signal that more history can be paged in.
+		const turnsNextCursor = initialTurnsCursor(manager, sessionId, turns);
+		const lastTurn = turns[turns.length - 1];
+		let modifiedAt = lastTurn?.startedAt ?? new Date().toISOString();
+		try {
+			modifiedAt = (await stat(file)).mtime.toISOString();
+		} catch {
+			// The file may disappear after it was located; the reconstructed
+			// transcript timestamp remains a valid fallback for this snapshot.
+		}
+		const workingDirectory = manager.getCwd();
+		const title = sessionDisplayTitle(manager.getSessionName(), firstUserText(turns));
+
+		// Another create/adopt or disposal may have won during file I/O. From this
+		// check through adoption there is no await, so live state cannot be
+		// replaced by this disk snapshot after the check.
+		if (this.#options.isLive(session) || this.#options.isDisposing(session)) {
+			return;
+		}
+
+		// Read, for the same reason the catalogue reports read — see
+		// `readSessionSummary`. The reducer still clears the bit if a turn starts.
+		const status = SessionStatus.Idle | SessionStatus.IsRead;
+
+		// Which model this conversation was last using. The agent starts only on
+		// the first new turn, so without seeding it here the client's model
+		// picker is empty until the user has already sent something.
+		//
+		// The recorded model is checked field by field: a session file can carry a
+		// partially-populated entry, and the wire id needs both halves of pi's
+		// `(provider, modelId)` identity.
+		const recorded = manager.buildSessionContext();
+		const recordedProvider = recorded.model?.provider;
+		const recordedId = recorded.model?.modelId;
+		const selection: ModelSelection | undefined =
+			typeof recordedProvider === "string" &&
+			recordedProvider.length > 0 &&
+			typeof recordedId === "string" &&
+			recordedId.length > 0
+				? {
+						id: modelSelectionId({ provider: recordedProvider, id: recordedId }),
+						config: { [THINKING_CONFIG_KEY]: recorded.thinkingLevel },
+					}
+				: this.#options.fallbackSelection?.();
+
+		const chatState: ChatState = {
+			resource: chat,
+			title,
+			status,
+			modifiedAt,
+			turns,
+			...(turnsNextCursor ? { turnsNextCursor } : {}),
+			...(selection ? { draft: { text: "", origin: { kind: MessageKind.User }, model: selection } } : {}),
+		};
+		this.#options.host.store.create(chat, chatState);
+
+		const sessionState: SessionState = {
+			provider: PI_PROVIDER,
+			title,
+			status,
+			// The transcript is genuinely available, so the session is ready. It
+			// simply has no agent attached until someone starts a turn.
+			lifecycle: SessionLifecycle.Ready,
+			...(workingDirectory ? { workingDirectories: [pathToFileUri(workingDirectory)] } : {}),
+			activeClients: [],
+			chats: [chatSummaryOf(chatState)],
+			defaultChat: chat,
+			_meta: { piSessionFile: file, hydrated: true },
+		};
+		this.#options.host.store.create(session, sessionState, "session");
+
+		this.#options.adopt?.({
+			uri: session,
+			sessionId,
+			workingDirectory,
+			sessionManager: manager,
+			chatChannel: chat,
+			createdAt: turns[0]?.startedAt ?? modifiedAt,
+		});
+
+		this.#options.log?.(`hydrated ${session} with ${turns.length} turns`);
+	}
+}
+
+function firstUserText(turns: readonly { message: { text: string } }[]): string | undefined {
+	for (const turn of turns) {
+		if (turn.message.text.trim()) {
+			return turn.message.text;
+		}
+	}
+	return undefined;
+}