@pi-in-go/pigpen-ahp 0.1.0

package/proof/oracle/src/tunnel/devtunnel.ts

@@ -0,0 +1,293 @@
+/**
+ * Driving the `devtunnel` CLI.
+ *
+ * Not bundled: it is a separate .NET CLI that only tunnel users need, and it
+ * must be installed and logged in before these operations can run.
+ *
+ * The CLI's JSON is decoded at this boundary. Decoders accept additive fields
+ * but reject missing or malformed fields that the host relies on.
+ */
+
+import { spawnSync } from "node:child_process";
+import { IDENTITY_LABEL, LAUNCHER_LABEL, PROTOCOL_LABEL, TUNNEL_PORT } from "./discovery.ts";
+
+export class TunnelError extends Error {}
+
+export interface DevTunnelCommandResult {
+	readonly status: number | null;
+	readonly signal: NodeJS.Signals | null;
+	readonly stdout: string;
+	readonly stderr: string;
+}
+
+export type DevTunnelRunner = (args: readonly string[]) => DevTunnelCommandResult;
+
+interface PortDetails {
+	readonly portNumber: number;
+	readonly protocol: string;
+	readonly accessControl?: unknown;
+}
+
+export interface Tunnel {
+	readonly tunnelId: string;
+	readonly labels: readonly string[];
+}
+
+// Process boundary ----------------------------------------------------------
+
+function missingCliError(): TunnelError {
+	return new TunnelError(
+		[
+			"`devtunnel` not found on PATH.",
+			"",
+			"Install it from https://aka.ms/devtunnels/download, then log in:",
+			"",
+			"    devtunnel user login -g      GitHub account",
+			"    devtunnel user login         Microsoft account (the default)",
+		].join("\n"),
+	);
+}
+
+function spawnDevtunnel(args: readonly string[]): DevTunnelCommandResult {
+	const result = spawnSync("devtunnel", [...args], { encoding: "utf8" });
+	if (result.error) {
+		const error = result.error as NodeJS.ErrnoException;
+		if (error.code === "ENOENT") {
+			throw missingCliError();
+		}
+		throw new TunnelError(`failed to start devtunnel:\n${error.message}`);
+	}
+	return {
+		status: result.status,
+		signal: result.signal,
+		stdout: result.stdout ?? "",
+		stderr: result.stderr ?? "",
+	};
+}
+
+function failureDetail(result: DevTunnelCommandResult): string {
+	const termination = result.signal
+		? `signal ${result.signal}`
+		: result.status === null
+			? "no exit status"
+			: `exit status ${result.status}`;
+	const output = [result.stderr.trim(), result.stdout.trim()].filter(Boolean);
+	return [termination, ...output].join("\n");
+}
+
+function payload(stdout: string): string {
+	return stdout.trim() || "<empty output>";
+}
+
+function parseObject(command: string, stdout: string): Record<string, unknown> {
+	let value: unknown;
+	try {
+		value = JSON.parse(stdout);
+	} catch {
+		throw new TunnelError(`devtunnel ${command} returned invalid JSON:\n${payload(stdout)}`);
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new TunnelError(`devtunnel ${command} returned an unexpected JSON value:\n${payload(stdout)}`);
+	}
+	return value as Record<string, unknown>;
+}
+
+// Command-specific JSON decoders -------------------------------------------
+
+function unexpectedResponse(command: string, stdout: string): TunnelError {
+	return new TunnelError(`devtunnel ${command} returned an unexpected response:\n${payload(stdout)}`);
+}
+
+function decodeLoginStatus(value: Record<string, unknown>, stdout: string): "logged-in" | "logged-out" {
+	if (typeof value.status !== "string") {
+		throw unexpectedResponse("user show", stdout);
+	}
+	switch (value.status.trim().toLowerCase()) {
+		case "logged in":
+			return "logged-in";
+		case "not logged in":
+			return "logged-out";
+		default:
+			throw unexpectedResponse("user show", stdout);
+	}
+}
+
+function decodeTunnels(value: Record<string, unknown>, stdout: string): Tunnel[] {
+	if (Array.isArray(value.tunnels)) {
+		return value.tunnels.map((item) => {
+			if (typeof item !== "object" || item === null || Array.isArray(item)) {
+				throw unexpectedResponse("list", stdout);
+			}
+			const tunnel = item as Record<string, unknown>;
+			if (
+				typeof tunnel.tunnelId !== "string" ||
+				tunnel.tunnelId.length === 0 ||
+				!Array.isArray(tunnel.labels) ||
+				!tunnel.labels.every((label) => typeof label === "string")
+			) {
+				throw unexpectedResponse("list", stdout);
+			}
+			return { tunnelId: tunnel.tunnelId, labels: tunnel.labels };
+		});
+	}
+	if (typeof value.warning === "string" && /\bno tunnels? found\b/i.test(value.warning)) {
+		return [];
+	}
+	throw unexpectedResponse("list", stdout);
+}
+
+function decodeCreatedTunnelId(value: Record<string, unknown>, stdout: string): string {
+	if (typeof value.tunnel !== "object" || value.tunnel === null || Array.isArray(value.tunnel)) {
+		throw unexpectedResponse("create", stdout);
+	}
+	const id = (value.tunnel as Record<string, unknown>).tunnelId;
+	if (typeof id !== "string" || id.length === 0) {
+		throw unexpectedResponse("create", stdout);
+	}
+	return id;
+}
+
+function decodePort(value: unknown, command: "port list" | "port show", stdout: string): PortDetails {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw unexpectedResponse(command, stdout);
+	}
+	const port = value as Record<string, unknown>;
+	const protocol = typeof port.protocol === "string" ? port.protocol.trim().toLowerCase() : "";
+	if (
+		typeof port.portNumber !== "number" ||
+		!Number.isSafeInteger(port.portNumber) ||
+		port.portNumber < 1 ||
+		port.portNumber > 65_535 ||
+		protocol.length === 0
+	) {
+		throw unexpectedResponse(command, stdout);
+	}
+	return { portNumber: port.portNumber, protocol, accessControl: port.accessControl };
+}
+
+function decodePortList(value: Record<string, unknown>, stdout: string): PortDetails[] {
+	if (Array.isArray(value.ports)) {
+		return value.ports.map((port) => decodePort(port, "port list", stdout));
+	}
+	if (typeof value.warning === "string" && /\bno (?:tunnel )?ports? found\b/i.test(value.warning)) {
+		return [];
+	}
+	throw unexpectedResponse("port list", stdout);
+}
+
+function decodePortDetails(value: Record<string, unknown>, stdout: string): PortDetails {
+	return decodePort(value.port, "port show", stdout);
+}
+
+// Domain adapter ------------------------------------------------------------
+
+export class DevTunnelCli {
+	readonly #runner: DevTunnelRunner;
+
+	constructor(runner: DevTunnelRunner = spawnDevtunnel) {
+		this.#runner = runner;
+	}
+
+	#run(command: string, args: readonly string[]): DevTunnelCommandResult {
+		const result = this.#runner(args);
+		if (result.status !== 0) {
+			throw new TunnelError(`devtunnel ${command} failed:\n${failureDetail(result)}`);
+		}
+		return result;
+	}
+
+	#runJson(command: string, args: readonly string[]): { value: Record<string, unknown>; stdout: string } {
+		const result = this.#run(command, args);
+		return { value: parseObject(command, result.stdout), stdout: result.stdout };
+	}
+
+	requireLogin(): void {
+		const { value, stdout } = this.#runJson("user show", ["user", "show", "--json"]);
+		if (decodeLoginStatus(value, stdout) === "logged-out") {
+			throw new TunnelError(
+				[
+					"`devtunnel` is not logged in. Run one of:",
+					"",
+					"    devtunnel user login -g      GitHub account",
+					"    devtunnel user login         Microsoft account (the default)",
+					"",
+					"Add -d for device-code auth when there is no browser.",
+				].join("\n"),
+			);
+		}
+	}
+
+	/** Returns this host's first labelled tunnel, if a previous run made one. */
+	findTunnel(): Tunnel | undefined {
+		const { value, stdout } = this.#runJson("list", [
+			"list",
+			"--all-labels",
+			IDENTITY_LABEL,
+			"--all-labels",
+			LAUNCHER_LABEL,
+			"--json",
+		]);
+		const found = decodeTunnels(value, stdout)[0];
+		if (found && (!found.labels.includes(IDENTITY_LABEL) || !found.labels.includes(LAUNCHER_LABEL))) {
+			throw unexpectedResponse("list", stdout);
+		}
+		return found;
+	}
+
+	createTunnel(name: string | undefined): string {
+		const labels = [LAUNCHER_LABEL, PROTOCOL_LABEL, IDENTITY_LABEL, ...(name ? [name] : [])];
+		const { value, stdout } = this.#runJson("create", [
+			"create",
+			"--json",
+			...labels.flatMap((label) => ["-l", label]),
+		]);
+		return decodeCreatedTunnelId(value, stdout);
+	}
+
+	#createPort(id: string): void {
+		this.#run("port create", ["port", "create", id, "-p", String(TUNNEL_PORT), "--protocol", "http", "--json"]);
+	}
+
+	/**
+	 * Ensures the fixed port uses an HTTP origin. The relay terminates TLS, while
+	 * pi-ahp's local listener speaks HTTP/WebSocket. A wrong-protocol port is
+	 * replaced only after confirming that it has no port-specific ACL.
+	 */
+	ensurePort(id: string): void {
+		const listed = this.#runJson("port list", ["port", "list", id, "--json"]);
+		const current = decodePortList(listed.value, listed.stdout).find((port) => port.portNumber === TUNNEL_PORT);
+		if (!current) {
+			this.#createPort(id);
+			return;
+		}
+		if (current.protocol === "http") return;
+
+		// List output does not carry port-specific ACLs. Re-read the details before
+		// a destructive protocol migration, and trust the newer response if the
+		// port changed concurrently.
+		const shown = this.#runJson("port show", ["port", "show", id, "-p", String(TUNNEL_PORT), "--json"]);
+		const details = decodePortDetails(shown.value, shown.stdout);
+		if (details.portNumber !== TUNNEL_PORT) {
+			throw unexpectedResponse("port show", shown.stdout);
+		}
+		if (details.protocol === "http") return;
+		const hasPortAcl = Array.isArray(details.accessControl)
+			? details.accessControl.length > 0
+			: details.accessControl != null;
+		if (hasPortAcl) {
+			throw new TunnelError(
+				`devtunnel port ${TUNNEL_PORT} uses ${details.protocol} and has port-specific access control; replace it manually`,
+			);
+		}
+
+		this.#run("port delete", ["port", "delete", id, "-p", String(TUNNEL_PORT), "--json"]);
+		this.#createPort(id);
+	}
+
+	/** Swaps the display label, leaving the identity and protocol labels alone. */
+	rename(id: string, from: string | undefined, to: string): void {
+		const args = ["update", id, "--add-labels", to];
+		if (from) args.push("--remove-labels", from);
+		this.#run("update", args);
+	}
+}

package/proof/oracle/src/tunnel/discovery.ts

@@ -0,0 +1,37 @@
+/** Shared Agent Host Dev Tunnel discovery contract plus pi-ahp's private labels. */
+
+/** Required for clients using the VS Code-compatible discovery convention. */
+export const LAUNCHER_LABEL = "vscode-server-launcher";
+
+/**
+ * Protocol 5 selects direct forwarding. Protocol 6 expects an
+ * `/agent-host/select` gateway, which a plain `devtunnel` port forward cannot
+ * provide. VS Code appends a tunnel-id-derived `tkn` on the v5 path; pi-ahp
+ * ignores it and relies on the Dev Tunnel access boundary.
+ *
+ * This versions the tunnel arrangement, not AHP itself.
+ */
+export const PROTOCOL_LABEL = "protocolv5";
+
+/** The fixed forwarded port used by the discovery convention. */
+export const TUNNEL_PORT = 31546;
+
+/**
+ * Finds this host's tunnel on later runs without becoming its display name.
+ * Compatible clients exclude underscore-prefixed labels from that name.
+ */
+export const IDENTITY_LABEL = "_pi_ahp";
+
+/** Returns the client-facing tunnel name, when one exists. */
+export function displayLabel(labels: readonly string[]): string | undefined {
+	return labels.find((label) => !label.startsWith("_") && label !== LAUNCHER_LABEL && !label.startsWith("protocolv"));
+}
+
+/** Applies the discovery convention's normalization to a user-supplied name. */
+export function nameLabel(name: string): string | undefined {
+	const slug = name
+		.replace(/^-+/g, "")
+		.replace(/[^\w-]/g, "")
+		.substring(0, 20);
+	return slug || undefined;
+}

package/proof/oracle/test/active-turn-reconnect.test.ts

@@ -0,0 +1,274 @@
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, it } from "node:test";
+import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import {
+	type ActionEnvelope,
+	ActionType,
+	type ChatState,
+	MessageKind,
+	PendingMessageKind,
+	type ReconnectReplayResult,
+	ReconnectResultType,
+	type ReconnectSnapshotResult,
+	ResponsePartKind,
+	SUPPORTED_PROTOCOL_VERSIONS,
+	TurnState,
+} from "@microsoft/agent-host-protocol";
+import type { AhpClient, Subscription } from "@microsoft/agent-host-protocol/client";
+import { chatUri, ROOT_CHANNEL, sessionUri } from "../src/core/channels.ts";
+import type { PiBackend } from "../src/pi/chat-driver.ts";
+import { type Harness, nextClientId, startHarness } from "./harness.ts";
+import { eventually } from "./support/async.ts";
+
+const CLIENT_ID = "active-turn-reconnect-client";
+const TURN_ID = "active-turn";
+
+class ControlledBackend implements PiBackend {
+	readonly prompts: string[] = [];
+	readonly steers: string[] = [];
+	aborts = 0;
+	readonly #listeners = new Set<(event: AgentSessionEvent) => void>();
+
+	subscribe(listener: (event: AgentSessionEvent) => void): () => void {
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	}
+
+	async prompt(text: string): Promise<void> {
+		this.prompts.push(text);
+	}
+
+	async steer(text: string): Promise<void> {
+		this.steers.push(text);
+	}
+
+	async abort(): Promise<void> {
+		this.aborts += 1;
+	}
+
+	startResponse(text: string): void {
+		this.#emit({ type: "agent_start" });
+		this.#emit({ type: "message_start", message: { role: "assistant" } });
+		this.#emit({
+			type: "message_update",
+			message: { role: "assistant" },
+			assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta: text },
+		});
+	}
+
+	finishResponse(): void {
+		this.#emit({ type: "message_end", message: { role: "assistant" } });
+		this.#emit({ type: "agent_end", messages: [], willRetry: false });
+		this.#emit({ type: "agent_settled" });
+	}
+
+	#emit(event: object): void {
+		for (const listener of this.#listeners) {
+			listener(event as AgentSessionEvent);
+		}
+	}
+}
+
+interface ActiveTurnFixture {
+	readonly backend: ControlledBackend;
+	readonly baseline: number;
+	readonly chat: string;
+	readonly client: AhpClient;
+	readonly harness: Harness;
+	readonly session: string;
+	readonly workspace: string;
+}
+
+async function nextEnvelope(
+	subscription: Subscription,
+	matches: (envelope: ActionEnvelope) => boolean,
+	timeoutMs = 2_000,
+): Promise<ActionEnvelope> {
+	let handle: ReturnType<typeof setTimeout>;
+	const timeout = new Promise<never>((_, reject) => {
+		handle = setTimeout(() => reject(new Error("no matching action arrived")), timeoutMs);
+		handle.unref?.();
+	});
+	const next = (async () => {
+		while (true) {
+			const event = await subscription.next();
+			if (event.done) {
+				throw new Error("subscription ended early");
+			}
+			if (event.value.type === "action") {
+				const envelope = event.value.params as ActionEnvelope;
+				if (matches(envelope)) {
+					return envelope;
+				}
+			}
+		}
+	})();
+	return Promise.race([next, timeout]).finally(() => clearTimeout(handle));
+}
+
+async function startActiveTurn(replayBufferCapacity = 64): Promise<ActiveTurnFixture> {
+	const workspace = mkdtempSync(join(tmpdir(), "pi-ahp-active-reconnect-"));
+	const backend = new ControlledBackend();
+	const harness = await startHarness({
+		sessions: true,
+		workingDirectory: workspace,
+		replayBufferCapacity,
+		createBackend: () => backend,
+	});
+	const client = await harness.connect();
+	await client.initialize({ clientId: CLIENT_ID, protocolVersions: SUPPORTED_PROTOCOL_VERSIONS });
+
+	const id = randomUUID();
+	const session = sessionUri(id);
+	const chat = chatUri(id);
+	await client.request("createSession", { channel: session });
+	await client.subscribe(session);
+	await client.subscribe(chat);
+	client.dispatch(chat, {
+		type: ActionType.ChatTurnStarted,
+		turnId: TURN_ID,
+		startedAt: new Date().toISOString(),
+		message: { text: "keep working", origin: { kind: MessageKind.User } },
+	});
+	await eventually("the initial prompt to reach the backend", () => backend.prompts.length === 1);
+	assert.equal((harness.host.store.get(chat) as ChatState).activeTurn?.id, TURN_ID);
+
+	return { backend, baseline: harness.host.serverSeq, chat, client, harness, session, workspace };
+}
+
+async function dispose(fixture: ActiveTurnFixture): Promise<void> {
+	await fixture.harness.dispose();
+	rmSync(fixture.workspace, { recursive: true, force: true });
+}
+
+function responseText(state: ChatState): string | undefined {
+	const turn = state.activeTurn ?? state.turns.at(-1);
+	const part = turn?.responseParts.find((candidate) => candidate.kind === ResponsePartKind.Markdown);
+	return part?.kind === ResponsePartKind.Markdown ? part.content : undefined;
+}
+
+describe("active-turn reconnect", () => {
+	it("replays offline output and accepts steering and cancellation after reconnect", async () => {
+		const fixture = await startActiveTurn();
+		try {
+			const observer = await fixture.harness.connect();
+			await observer.initialize({ clientId: nextClientId(), protocolVersions: SUPPORTED_PROTOCOL_VERSIONS });
+			const { subscription: observerEvents } = await observer.subscribe(fixture.chat);
+
+			await fixture.client.shutdown();
+			await eventually(
+				"only the observer to remain subscribed",
+				() => fixture.harness.host.subscriberCount(fixture.chat) === 1,
+			);
+			fixture.backend.startResponse("offline partial");
+			const observed = await nextEnvelope(
+				observerEvents,
+				(envelope) => envelope.action.type === ActionType.ChatResponsePart,
+			);
+
+			const resumed = await fixture.harness.connect();
+			const result = (await resumed.reconnect({
+				clientId: CLIENT_ID,
+				lastSeenServerSeq: fixture.baseline,
+				subscriptions: [fixture.session, fixture.chat],
+			})) as ReconnectReplayResult;
+
+			assert.equal(result.type, ReconnectResultType.Replay);
+			assert.ok(result.actions.some((envelope) => envelope.serverSeq === observed.serverSeq));
+			assert.equal(responseText(fixture.harness.host.store.get(fixture.chat) as ChatState), "offline partial");
+			assert.deepEqual(fixture.backend.prompts, ["keep working"]);
+
+			resumed.dispatch(fixture.chat, {
+				type: ActionType.ChatPendingMessageSet,
+				kind: PendingMessageKind.Steering,
+				id: "after-reconnect",
+				message: { text: "focus here", origin: { kind: MessageKind.User } },
+			});
+			await eventually("reconnected steering to reach the backend", () => fixture.backend.steers.length === 1);
+			resumed.dispatch(fixture.chat, {
+				type: ActionType.ChatTurnCancelled,
+				turnId: TURN_ID,
+				duration: 0,
+			});
+			await eventually("reconnected cancellation to reach the backend", () => fixture.backend.aborts === 1);
+
+			const state = fixture.harness.host.store.get(fixture.chat) as ChatState;
+			assert.equal(state.activeTurn, undefined);
+			assert.equal(state.turns.at(-1)?.state, TurnState.Cancelled);
+		} finally {
+			await dispose(fixture);
+		}
+	});
+
+	it("replays a turn that completed while its client was offline", async () => {
+		const fixture = await startActiveTurn();
+		try {
+			await fixture.client.shutdown();
+			await eventually(
+				"the original chat subscription to disconnect",
+				() => fixture.harness.host.subscriberCount(fixture.chat) === 0,
+			);
+			fixture.backend.startResponse("finished offline");
+			fixture.backend.finishResponse();
+
+			const resumed = await fixture.harness.connect();
+			const result = (await resumed.reconnect({
+				clientId: CLIENT_ID,
+				lastSeenServerSeq: fixture.baseline,
+				subscriptions: [fixture.session, fixture.chat],
+			})) as ReconnectReplayResult;
+
+			assert.equal(result.type, ReconnectResultType.Replay);
+			assert.ok(result.actions.some((envelope) => envelope.action.type === ActionType.ChatTurnComplete));
+			const state = fixture.harness.host.store.get(fixture.chat) as ChatState;
+			assert.equal(state.turns.at(-1)?.state, TurnState.Complete);
+			assert.equal(responseText(state), "finished offline");
+			assert.deepEqual(fixture.backend.prompts, ["keep working"]);
+		} finally {
+			await dispose(fixture);
+		}
+	});
+
+	it("falls back to an active-turn snapshot and continues streaming", async () => {
+		const fixture = await startActiveTurn(4);
+		try {
+			await fixture.client.shutdown();
+			await eventually(
+				"the original chat subscription to disconnect",
+				() => fixture.harness.host.subscriberCount(fixture.chat) === 0,
+			);
+			fixture.backend.startResponse("snapshot partial");
+			for (let i = 0; i < 6; i++) {
+				fixture.harness.host.dispatchServerAction(ROOT_CHANNEL, {
+					type: ActionType.RootActiveSessionsChanged,
+					activeSessions: i,
+				});
+			}
+
+			const resumed = await fixture.harness.connect();
+			const resumedEvents = resumed.attachSubscription(fixture.chat);
+			const result = (await resumed.reconnect({
+				clientId: CLIENT_ID,
+				lastSeenServerSeq: fixture.baseline,
+				subscriptions: [fixture.session, fixture.chat],
+			})) as ReconnectSnapshotResult;
+
+			assert.equal(result.type, ReconnectResultType.Snapshot);
+			const chatSnapshot = result.snapshots.find((snapshot) => snapshot.resource === fixture.chat);
+			assert.ok(chatSnapshot);
+			assert.equal(responseText(chatSnapshot.state as ChatState), "snapshot partial");
+			fixture.backend.finishResponse();
+			await nextEnvelope(resumedEvents, (envelope) => envelope.action.type === ActionType.ChatTurnComplete);
+
+			const state = fixture.harness.host.store.get(fixture.chat) as ChatState;
+			assert.equal(state.turns.at(-1)?.state, TurnState.Complete);
+			assert.deepEqual(fixture.backend.prompts, ["keep working"]);
+		} finally {
+			await dispose(fixture);
+		}
+	});
+});