@pi-in-go/pigpen-ahp 0.1.0

package/proof/oracle/test/client-workarounds.test.ts

@@ -0,0 +1,320 @@
+/** Per-connection URI compatibility without leaking client dialects into core state. */
+
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { after, before, describe, it } from "node:test";
+import {
+	ActionType,
+	type ChatState,
+	JsonRpcErrorCodes,
+	MessageKind,
+	type SessionState,
+	SUPPORTED_PROTOCOL_VERSIONS,
+} from "@microsoft/agent-host-protocol";
+import { AhpClient, RpcError } from "@microsoft/agent-host-protocol/client";
+import { WebSocketTransport } from "@microsoft/agent-host-protocol/ws";
+import { chatUri, ROOT_CHANNEL, sessionIdFromUri, sessionUri } from "../src/core/channels.ts";
+import { ClientWorkarounds } from "../src/core/client-workarounds.ts";
+import { PI_PROVIDER } from "../src/pi/provider.ts";
+import type { RunningServer } from "../src/transport/websocket.ts";
+import { expectRpcError, must } from "./support/assertions.ts";
+import { type HydratedSessionFixture, startHydratedSessionFixture } from "./support/hydrated-session.ts";
+import { assertValid } from "./support/schema.ts";
+
+async function expectVscodeDisposalRefusal(request: Promise<unknown>): Promise<void> {
+	const error = await expectRpcError(request, JsonRpcErrorCodes.InvalidRequest);
+	assert.match(error.message, /temporarily disabled for VS Code/u);
+	assert.match(error.message, /VS Code provisional-session lifecycle bug/u);
+	assert.match(error.message, /session was kept/u);
+}
+
+async function initialSnapshotResources(
+	server: RunningServer,
+	clientId: string,
+	initialSubscriptions: string[],
+	clientInfo?: { name: string },
+): Promise<string[]> {
+	const client = new AhpClient(await WebSocketTransport.connect(`ws://127.0.0.1:${server.port}`));
+	client.connect();
+	try {
+		const result = await client.request("initialize", {
+			channel: ROOT_CHANNEL,
+			clientId,
+			protocolVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
+			initialSubscriptions,
+			...(clientInfo ? { clientInfo } : {}),
+		});
+		return result.snapshots.map((snapshot) => snapshot.resource);
+	} finally {
+		await client.shutdown();
+	}
+}
+
+describe("client URI dialects over the wire", () => {
+	let fixture: HydratedSessionFixture;
+
+	before(async () => {
+		fixture = await startHydratedSessionFixture();
+	});
+
+	after(async () => {
+		await fixture.close();
+	});
+
+	it("answers VS Code at the URIs it computes for itself", async () => {
+		const client = await fixture.connectAsVSCode();
+		const providerSession = `pi:/${fixture.sessionId}`;
+		const derived = `ahp-chat://default/${Buffer.from(providerSession).toString("base64url")}`;
+
+		const session = await client.subscribe(providerSession);
+		const sessionState = session.result.snapshot?.state as SessionState;
+		assert.equal(session.result.snapshot?.resource, providerSession);
+		assert.equal(sessionState.defaultChat, derived);
+
+		const { result } = await client.subscribe(derived);
+		const state = must(result.snapshot).state as ChatState;
+		assert.equal(result.snapshot?.resource, derived);
+		assert.ok(state.turns.length > 0, "the transcript must come back, not an empty chat");
+		assertValid("state", "ChatState", state);
+	});
+
+	for (const [name, clientInfo, usesDerivedChat] of [
+		["VS Code", { name: "vscode-editor-window" }, true],
+		["unnamed provider-alias client", undefined, false],
+	] as const) {
+		it(`applies the ${name} dialect to initialize-time subscriptions`, async () => {
+			const providerSession = `pi:/${fixture.sessionId}`;
+			const chat = usesDerivedChat
+				? `ahp-chat://default/${Buffer.from(providerSession).toString("base64url")}`
+				: chatUri(fixture.sessionId);
+			const subscriptions = [providerSession, chat];
+
+			assert.deepEqual(
+				await initialSnapshotResources(fixture.server, `initial-subscriptions-${name}`, subscriptions, clientInfo),
+				subscriptions,
+			);
+		});
+	}
+});
+
+describe("VS Code session disposal workaround", () => {
+	it("protects a durable session that this connection did not create", async () => {
+		const fixture = await startHydratedSessionFixture();
+		try {
+			const client = await fixture.connectAsVSCode();
+			const resource = `pi:/${fixture.sessionId}`;
+
+			await expectVscodeDisposalRefusal(client.request("disposeSession", { channel: resource }));
+
+			assert.deepEqual(fixture.deletedFiles, []);
+			const listed = await client.request("listSessions", { channel: ROOT_CHANNEL });
+			assert.equal(
+				listed.items.some((item) => item.resource === resource),
+				true,
+			);
+		} finally {
+			await fixture.close();
+		}
+	});
+
+	it("still disposes an empty session created by this VS Code connection", async () => {
+		const fixture = await startHydratedSessionFixture();
+		try {
+			const client = await fixture.connectAsVSCode();
+			const id = randomUUID();
+			const resource = `pi:/${id}`;
+			await client.request("createSession", { channel: resource });
+
+			await client.request("disposeSession", { channel: resource });
+
+			assert.equal(fixture.host.store.has(sessionUri(id)), false);
+		} finally {
+			await fixture.close();
+		}
+	});
+
+	it("restores an empty session after disposal fails so VS Code can retry", async () => {
+		let attempts = 0;
+		const fixture = await startHydratedSessionFixture({
+			deleteFile: () => {
+				attempts += 1;
+				return attempts === 1 ? { ok: false, error: "temporary failure" } : { ok: true };
+			},
+		});
+		try {
+			const client = await fixture.connectAsVSCode();
+			const id = randomUUID();
+			const resource = `pi:/${id}`;
+			await client.request("createSession", { channel: resource });
+
+			const error = await expectRpcError(
+				client.request("disposeSession", { channel: resource }),
+				JsonRpcErrorCodes.InternalError,
+			);
+			assert.match(error.message, /temporary failure/u);
+			await client.request("disposeSession", { channel: resource });
+
+			assert.equal(attempts, 2);
+			assert.equal(fixture.host.store.has(sessionUri(id)), false);
+		} finally {
+			await fixture.close();
+		}
+	});
+
+	it("protects a session after its first turn starts", async () => {
+		const fixture = await startHydratedSessionFixture();
+		try {
+			const client = await fixture.connectAsVSCode();
+			const id = randomUUID();
+			const resource = `pi:/${id}`;
+			const chat = `ahp-chat://default/${Buffer.from(resource).toString("base64url")}`;
+			await client.request("createSession", { channel: resource });
+			client.dispatch(chat, {
+				type: ActionType.ChatTurnStarted,
+				turnId: "materialized-turn",
+				startedAt: new Date().toISOString(),
+				message: { text: "keep this", origin: { kind: MessageKind.User } },
+			});
+
+			await expectVscodeDisposalRefusal(client.request("disposeSession", { channel: resource }));
+
+			assert.equal(fixture.host.store.has(sessionUri(id)), true);
+		} finally {
+			await fixture.close();
+		}
+	});
+});
+
+describe("session URI classification", () => {
+	it("recognises only canonical or explicitly allowed session schemes", () => {
+		const id = "9991C40A-74CC-4991-85CC-F37CD2BFF065";
+		assert.equal(sessionIdFromUri(`pi:/${id}`, [PI_PROVIDER]), id);
+		assert.equal(sessionIdFromUri("ahp-session:/abc"), "abc");
+		assert.equal(sessionIdFromUri("copilot:/test-session"), undefined);
+		assert.equal(sessionIdFromUri("copilot:/test-session", ["copilot"]), "test-session");
+		assert.equal(sessionIdFromUri("pi://test-session", [PI_PROVIDER]), undefined);
+	});
+
+	it("does not infer sessions from other channel schemes", () => {
+		for (const uri of ["ahp-chat:/c1", "ahp-terminal:/t1", "agenthost-terminal:/t1", "file:///etc/passwd"]) {
+			assert.equal(sessionIdFromUri(uri, [PI_PROVIDER]), undefined, uri);
+		}
+	});
+
+	it("retargets VS Code's chat-addressed rename to the owning session", () => {
+		const id = "rename-me";
+		const workarounds = new ClientWorkarounds();
+		workarounds.identify({ name: "vscode-editor-window" });
+		const message = {
+			jsonrpc: "2.0" as const,
+			method: "dispatchAction",
+			params: {
+				channel: `ahp-chat://default/${Buffer.from(`pi:/${id}`).toString("base64url")}`,
+				clientSeq: 1,
+				action: { type: ActionType.SessionTitleChanged, title: "Renamed" },
+			},
+		};
+
+		workarounds.applyToIncoming(message);
+
+		assert.equal(message.params.channel, sessionUri(id));
+	});
+
+	it("rewrites URI-bearing action and catalogue fields for VS Code", () => {
+		const id = "nested-fields";
+		const session = sessionUri(id);
+		const chat = chatUri(id);
+		const providerSession = `pi:/${id}`;
+		const derivedChat = `ahp-chat://default/${Buffer.from(providerSession).toString("base64url")}`;
+		const workarounds = new ClientWorkarounds();
+		workarounds.identify({ name: "vscode-editor-window" });
+
+		const removed = workarounds.applyToOutgoing({
+			jsonrpc: "2.0",
+			method: "root/sessionRemoved",
+			params: { channel: ROOT_CHANNEL, session },
+		});
+		assert.deepEqual(removed, {
+			jsonrpc: "2.0",
+			method: "root/sessionRemoved",
+			params: { channel: ROOT_CHANNEL, session: providerSession },
+		});
+
+		const updated = workarounds.applyToOutgoing({
+			jsonrpc: "2.0",
+			method: "action",
+			params: {
+				channel: session,
+				action: { type: ActionType.SessionChatUpdated, chat, changes: { resource: chat } },
+				serverSeq: 1,
+			},
+		});
+		assert.deepEqual(updated, {
+			jsonrpc: "2.0",
+			method: "action",
+			params: {
+				channel: providerSession,
+				action: {
+					type: ActionType.SessionChatUpdated,
+					chat: derivedChat,
+					changes: { resource: derivedChat },
+				},
+				serverSeq: 1,
+			},
+		});
+	});
+
+	it("leaves VS Code's client-chosen terminal URI outside session translation", () => {
+		const channel = "agenthost-terminal:/terminal-1";
+		const workarounds = new ClientWorkarounds();
+		workarounds.identify({ name: "vscode-editor-window" });
+
+		const message = { jsonrpc: "2.0" as const, method: "action", params: { channel } };
+		assert.deepEqual(workarounds.applyToOutgoing(message), message);
+	});
+
+	it("does not hydrate or dispose a durable session through VS Code's terminal URI", async () => {
+		const fixture = await startHydratedSessionFixture();
+		try {
+			const client = await fixture.connectAsVSCode();
+			const channel = `agenthost-terminal:/${fixture.sessionId}`;
+			await assert.rejects(
+				client.subscribe(channel),
+				RpcError,
+				"an uncreated terminal must not open a matching session",
+			);
+			await assert.rejects(
+				client.request("disposeSession", { channel }),
+				RpcError,
+				"a terminal URI must not delete a matching session",
+			);
+			assert.equal(fixture.host.store.has(channel), false);
+			assert.deepEqual(fixture.deletedFiles, []);
+		} finally {
+			await fixture.close();
+		}
+	});
+
+	it("accepts the provider scheme but rejects an undeclared session scheme", async () => {
+		const fixture = await startHydratedSessionFixture();
+		try {
+			await assert.rejects(fixture.client.request("createSession", { channel: `custom:/${randomUUID()}` }), RpcError);
+
+			const id = randomUUID().toUpperCase();
+			const uri = `pi:/${id}`;
+			await fixture.client.request("createSession", { channel: uri });
+
+			const { result } = await fixture.client.subscribe(uri);
+			assert.ok(result.snapshot, "the session must exist at the URI the client chose");
+			assert.equal(result.snapshot.resource, uri);
+			assert.equal((result.snapshot.state as SessionState).defaultChat, chatUri(id));
+			assert.equal(fixture.host.store.has(sessionUri(id)), true, "core state stays canonical");
+			assert.equal(fixture.host.store.has(uri), false);
+
+			await fixture.client.request("disposeSession", { channel: uri });
+			assert.equal(fixture.host.store.has(sessionUri(id)), false);
+		} finally {
+			await fixture.close();
+		}
+	});
+});

package/proof/oracle/test/completions.test.ts

@@ -0,0 +1,323 @@
+/**
+ * Inline completions for a message being composed.
+ *
+ * The protocol makes `CompletionItem.attachment` required, which decides what
+ * this feature is: an attachment picker. `@`-mentions fit; pi's slash commands
+ * do not, because they attach nothing.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/chat-channel
+ */
+
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, before, describe, it } from "node:test";
+import {
+	CompletionItemKind,
+	type CompletionsResult,
+	type InitializeResult,
+	JsonRpcErrorCodes,
+	MessageAttachmentKind,
+	SUPPORTED_PROTOCOL_VERSIONS,
+} from "@microsoft/agent-host-protocol";
+import { AhpClient, RpcError } from "@microsoft/agent-host-protocol/client";
+import { WebSocketTransport } from "@microsoft/agent-host-protocol/ws";
+import { installRootChannel } from "../src/channels/root.ts";
+import { AhpHost } from "../src/core/host.ts";
+import { CompletionService, findMention, MENTION_TRIGGER } from "../src/pi/completions.ts";
+import { type RunningServer, serveWebSocket } from "../src/transport/websocket.ts";
+import { assertValid } from "./support/schema.ts";
+
+const CHAT = "ahp-chat:/completions";
+
+describe("mention parsing", () => {
+	it("finds a mention the cursor sits in", () => {
+		const found = findMention("look at @foo", 12);
+		assert.deepEqual(found, { start: 8, end: 12, query: "foo" });
+	});
+
+	it("finds a bare mention at the start of the text", () => {
+		assert.equal(findMention("@src", 4)?.query, "src");
+	});
+
+	it("ignores an `@` that is not preceded by whitespace", () => {
+		// Otherwise every email address and decorator opens the picker.
+		assert.equal(findMention("mail me at a@b.com", 18), undefined);
+	});
+
+	it("ignores a cursor that is past the end of the mention", () => {
+		assert.equal(findMention("@foo bar", 8), undefined);
+	});
+
+	it("returns the empty query for a lone trigger", () => {
+		assert.equal(findMention("@", 1)?.query, "");
+	});
+});
+
+describe("completions", () => {
+	let workspace: string;
+	let service: CompletionService;
+
+	before(() => {
+		workspace = mkdtempSync(join(tmpdir(), "pi-ahp-completions-"));
+		writeFileSync(join(workspace, "readme.md"), "x");
+		writeFileSync(join(workspace, "report.txt"), "x");
+		writeFileSync(join(workspace, "other.js"), "x");
+		writeFileSync(join(workspace, ".hidden"), "x");
+		mkdirSync(join(workspace, "src", "lib"), { recursive: true });
+		writeFileSync(join(workspace, "src", "index.ts"), "x");
+		writeFileSync(join(workspace, "src", "lib", "deep.ts"), "x");
+		mkdirSync(join(workspace, "node_modules"));
+		writeFileSync(join(workspace, "node_modules", "reactive.js"), "x");
+		mkdirSync(join(workspace, "dist"));
+		writeFileSync(join(workspace, "dist", "generated.js"), "x");
+		mkdirSync(join(workspace, "build"));
+		writeFileSync(join(workspace, "build", "artifact.js"), "x");
+
+		service = new CompletionService({ workingDirectoryFor: () => workspace });
+	});
+
+	after(() => {
+		rmSync(workspace, { recursive: true, force: true });
+	});
+
+	const complete = (text: string, offset = text.length): Promise<CompletionsResult> =>
+		service.complete({ kind: CompletionItemKind.UserMessage, channel: CHAT, text, offset });
+
+	it("offers files matching the typed prefix", async () => {
+		const { items } = await complete("look at @re");
+
+		const inserted = items.map((item) => item.insertText);
+		assert.deepEqual(inserted.sort(), ["@readme.md", "@report.txt"]);
+	});
+
+	it("attaches the resource each item refers to", async () => {
+		const { items } = await complete("@readme");
+		const item = items[0];
+
+		assert.ok(item);
+		assert.equal(item.attachment.type, MessageAttachmentKind.Resource);
+		assert.equal(item.attachment.label, "readme.md");
+		assert.match((item.attachment as { uri: string }).uri, /readme\.md$/);
+		assertValid("commands", "CompletionItem", item);
+	});
+
+	it("marks the range the client should replace", async () => {
+		const { items } = await complete("look at @re");
+
+		// The span covers the `@` through the cursor, so accepting replaces the
+		// half-typed mention rather than appending to it.
+		assert.equal(items[0]?.rangeStart, 8);
+		assert.equal(items[0]?.rangeEnd, 11);
+	});
+
+	it("returns nested files instead of directory navigation items", async () => {
+		const { items } = await complete("@sr");
+
+		assert.deepEqual(
+			items.map((item) => item.insertText),
+			["@src/index.ts", "@src/lib/deep.ts"],
+		);
+		assert.ok(items.every((item) => item.attachment.displayKind === "document"));
+	});
+
+	it("matches a typed relative-path prefix", async () => {
+		const { items } = await complete("@src/in");
+
+		assert.deepEqual(
+			items.map((item) => item.insertText),
+			["@src/index.ts"],
+		);
+	});
+
+	it("matches a nested file by basename", async () => {
+		const { items } = await complete("@deep");
+
+		assert.deepEqual(
+			items.map((item) => item.insertText),
+			["@src/lib/deep.ts"],
+		);
+	});
+
+	it("keeps the temporary directory skip list narrow", async () => {
+		const inserted = (await complete("@")).items.map((item) => item.insertText);
+
+		assert.equal(
+			inserted.some((item) => item.includes("node_modules")),
+			false,
+		);
+		assert.equal(
+			inserted.some((item) => item.includes(".hidden")),
+			false,
+		);
+		assert.ok(inserted.includes("@dist/generated.js"));
+		assert.ok(inserted.includes("@build/artifact.js"));
+	});
+
+	it("does not interpret a query as path traversal", async () => {
+		const { items } = await complete("@../../etc/pass");
+		assert.deepEqual(items, []);
+	});
+
+	it("returns nothing for a completion kind it does not implement", async () => {
+		const result = await service.complete({
+			kind: "futureKind" as CompletionItemKind,
+			channel: CHAT,
+			text: "@not",
+			offset: 4,
+		});
+		assert.deepEqual(result.items, []);
+	});
+
+	it("returns nothing when the cursor is not in a mention", async () => {
+		assert.deepEqual((await complete("plain text")).items, []);
+	});
+
+	it("returns nothing for a chat it has no directory for", async () => {
+		const orphan = new CompletionService({ workingDirectoryFor: () => undefined });
+		const result = await orphan.complete({
+			kind: CompletionItemKind.UserMessage,
+			channel: CHAT,
+			text: "@re",
+			offset: 3,
+		});
+
+		assert.deepEqual(result.items, []);
+	});
+
+	it("caps how many items it returns", async () => {
+		const crowded = mkdtempSync(join(tmpdir(), "pi-ahp-crowded-"));
+		try {
+			for (let i = 0; i < 40; i++) {
+				writeFileSync(join(crowded, `file-${i}.txt`), "x");
+			}
+			const capped = new CompletionService({ workingDirectoryFor: () => crowded, maxItems: 5 });
+			const result = await capped.complete({
+				kind: CompletionItemKind.UserMessage,
+				channel: CHAT,
+				text: "@file",
+				offset: 5,
+			});
+
+			assert.equal(result.items.length, 5);
+		} finally {
+			rmSync(crowded, { recursive: true, force: true });
+		}
+	});
+});
+
+describe("completions over the wire", () => {
+	let server: RunningServer;
+	let client: AhpClient;
+	let initialization: InitializeResult;
+	let workspace: string;
+
+	before(async () => {
+		workspace = mkdtempSync(join(tmpdir(), "pi-ahp-completions-wire-"));
+		writeFileSync(join(workspace, "notes.md"), "x");
+
+		const host = new AhpHost({ completionTriggerCharacters: [MENTION_TRIGGER] });
+		installRootChannel(host, []);
+		host.serve({
+			completions: new CompletionService({
+				workingDirectoryFor: (channel) => (channel === CHAT ? workspace : undefined),
+			}),
+		});
+
+		server = await serveWebSocket(host, { host: "127.0.0.1", port: 0 });
+		client = new AhpClient(await WebSocketTransport.connect(`ws://127.0.0.1:${server.port}`));
+		client.connect();
+		initialization = await client.initialize({
+			clientId: "completions-client",
+			protocolVersions: SUPPORTED_PROTOCOL_VERSIONS,
+		});
+	});
+
+	after(async () => {
+		await client.shutdown();
+		await server.close();
+		rmSync(workspace, { recursive: true, force: true });
+	});
+
+	it("advertises only the trigger it can answer", () => {
+		// `/` is deliberately absent: pi's slash commands attach nothing, and
+		// every completion item must carry an attachment.
+		assert.deepEqual(initialization.completionTriggerCharacters, ["@"]);
+		assertValid("commands", "InitializeResult", initialization);
+	});
+
+	it("serves a schema-conforming result", async () => {
+		const result = await client.request("completions", {
+			kind: CompletionItemKind.UserMessage,
+			channel: CHAT,
+			text: "see @not",
+			offset: 8,
+		});
+
+		assert.equal(result.items.length, 1);
+		assert.equal(result.items[0]?.insertText, "@notes.md");
+		assertValid("commands", "CompletionsResult", result);
+	});
+
+	it("rejects non-chat completion targets", async () => {
+		const params = { kind: CompletionItemKind.UserMessage, text: "@not", offset: 4 };
+		for (const channel of [undefined, "ahp-session:/completions"]) {
+			await assert.rejects(
+				client.request("completions", { ...params, ...(channel ? { channel } : {}) } as never),
+				(error: unknown) => error instanceof RpcError && error.code === JsonRpcErrorCodes.InvalidParams,
+			);
+		}
+	});
+
+	it("maps provider-alias completion targets onto the default chat", async () => {
+		const vscode = new AhpClient(await WebSocketTransport.connect(`ws://127.0.0.1:${server.port}`));
+		vscode.connect();
+		await vscode.request("initialize", {
+			channel: "ahp-root://",
+			clientId: "vscode-completions-client",
+			clientInfo: { name: "vscode-editor-window" },
+			protocolVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
+		});
+		try {
+			const params = { kind: CompletionItemKind.UserMessage, text: "@not", offset: 4 };
+			for (const result of await Promise.all([
+				vscode.request("completions", { ...params, channel: "pi:/completions" }),
+				client.request("completions", { ...params, channel: "pi:/completions" }),
+			])) {
+				assert.deepEqual(
+					result.items.map((item) => item.insertText),
+					["@notes.md"],
+				);
+			}
+		} finally {
+			await vscode.shutdown();
+		}
+	});
+});
+
+describe("completions without a handler", () => {
+	it("answers with an empty list rather than MethodNotFound", async () => {
+		// The client debounces keystrokes into this call; an error per keypress
+		// would be worse than nothing to show.
+		const host = new AhpHost();
+		installRootChannel(host, []);
+		const server = await serveWebSocket(host, { host: "127.0.0.1", port: 0 });
+		const client = new AhpClient(await WebSocketTransport.connect(`ws://127.0.0.1:${server.port}`));
+		client.connect();
+		await client.initialize({ clientId: "bare-client", protocolVersions: SUPPORTED_PROTOCOL_VERSIONS });
+
+		try {
+			const result = await client.request("completions", {
+				kind: CompletionItemKind.UserMessage,
+				channel: CHAT,
+				text: "@x",
+				offset: 2,
+			});
+			assert.deepEqual(result.items, []);
+		} finally {
+			await client.shutdown();
+			await server.close();
+		}
+	});
+});