@pi-in-go/pigpen-ahp 0.1.0

package/proof/oracle/test/image-session.test.ts

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { it } from "node:test";
+import { createFauxCore, fauxAssistantMessage, type Message } from "@earendil-works/pi-ai";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { InProcessPiBackend } from "../src/pi/in-process-backend.ts";
+import { ONE_PIXEL_PNG } from "./support/images.ts";
+import { createReplayEnvironment } from "./support/replay.ts";
+
+it("passes and persists images while honouring preflight cancellation", async () => {
+	const environment = createReplayEnvironment();
+	const workspace = mkdtempSync(join(tmpdir(), "pi-ahp-image-session-"));
+	const manager = SessionManager.create(workspace, join(environment.agentDir, "sessions", "image-session"), {
+		id: "image-session",
+	});
+	let backend: InProcessPiBackend | undefined;
+	let contextMessages: Message[] = [];
+
+	try {
+		backend = await InProcessPiBackend.create({ cwd: workspace, sessionManager: manager });
+		const faux = createFauxCore({});
+		faux.setResponses([
+			(context) => {
+				contextMessages = structuredClone(context.messages);
+				return fauxAssistantMessage("I can see the image.");
+			},
+		]);
+		backend.session.agent.streamFunction = faux.stream as never;
+
+		await backend.prompt("Describe this image", [{ type: "image", data: ONE_PIXEL_PNG, mimeType: "image/png" }]);
+
+		const received = contextMessages.findLast((message) => message.role === "user");
+		assert.ok(received && Array.isArray(received.content));
+		assert.equal(received.content.length, 2);
+		assert.deepEqual(received.content[0], { type: "text", text: "Describe this image" });
+		const receivedImage = received.content[1];
+		assert.equal(receivedImage?.type, "image");
+		if (receivedImage?.type === "image") {
+			assert.equal(receivedImage.mimeType, "image/png");
+			assert.deepEqual(
+				Buffer.from(receivedImage.data, "base64").subarray(0, 8),
+				Buffer.from("89504e470d0a1a0a", "hex"),
+			);
+		}
+
+		const stored = manager.getEntries().find((entry) => entry.type === "message" && entry.message.role === "user");
+		const storedMessage = stored?.type === "message" && stored.message.role === "user" ? stored.message : undefined;
+		assert.deepEqual(storedMessage?.content, received.content);
+
+		const cancelled = new AbortController();
+		cancelled.abort();
+		await backend.prompt(
+			"Do not send this",
+			[{ type: "image", data: ONE_PIXEL_PNG, mimeType: "image/png" }],
+			cancelled.signal,
+		);
+		assert.equal(faux.state.callCount, 1, "cancelled image preflight started another model request");
+		assert.equal(
+			manager.getEntries().filter((entry) => entry.type === "message" && entry.message.role === "user").length,
+			1,
+		);
+	} finally {
+		backend?.dispose();
+		environment.close();
+		rmSync(workspace, { recursive: true, force: true });
+	}
+});

package/proof/oracle/test/live-turn.test.ts

@@ -0,0 +1,304 @@
+/**
+ * Live end-to-end smoke: a real client, a real model, the whole stack.
+ *
+ * Opt-in — needs a configured pi model provider and network access. Run with:
+ *
+ *     nix develop -c env \
+ *       PI_AHP_LIVE_SETTINGS=/absolute/path/to/settings.json \
+ *       PI_AHP_LIVE_AUTH=/absolute/path/to/auth.json \
+ *       pnpm exec node --test test/live-turn.test.ts
+ *
+ * The dedicated settings file must explicitly choose a default model and
+ * thinking level. Provider packages listed there are installed into the
+ * temporary Pi directory when missing; pin their versions for repeatability.
+ *
+ * Everything else in the suite is deterministic and offline; this exists to
+ * catch the one thing scripted backends cannot: that pi's *actual* event
+ * stream maps onto the protocol the way the mapper assumes.
+ */
+
+import assert from "node:assert/strict";
+import { randomUUID } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { after, before, describe, it } from "node:test";
+import { createAgentSessionServices, SettingsManager } from "@earendil-works/pi-coding-agent";
+import {
+	ActionType,
+	type ChatState,
+	MessageKind,
+	type ModelSelection,
+	ResponsePartKind,
+	type RootState,
+	SessionLifecycle,
+	type SessionState,
+	SUPPORTED_PROTOCOL_VERSIONS,
+	ToolCallStatus,
+	type Turn,
+	TurnState,
+} from "@microsoft/agent-host-protocol";
+import { AhpClient } from "@microsoft/agent-host-protocol/client";
+import { WebSocketTransport } from "@microsoft/agent-host-protocol/ws";
+import { chatUri, sessionUri } from "../src/core/channels.ts";
+import { createPiHost } from "../src/host/pi-host.ts";
+import { InProcessPiBackend } from "../src/pi/in-process-backend.ts";
+import { THINKING_CONFIG_KEY } from "../src/pi/models.ts";
+import { type RunningServer, serveWebSocket } from "../src/transport/websocket.ts";
+import { must, turnError } from "./support/assertions.ts";
+import { eventually } from "./support/async.ts";
+import { assertValid } from "./support/schema.ts";
+import { persistentSessionStorage } from "./support/session-storage.ts";
+
+const LIVE_SETTINGS = process.env.PI_AHP_LIVE_SETTINGS?.trim();
+const LIVE_AUTH = process.env.PI_AHP_LIVE_AUTH?.trim();
+const LIVE = LIVE_SETTINGS !== undefined || LIVE_AUTH !== undefined;
+const TURN_TIMEOUT_MS = 180_000;
+
+/**
+ * Printed by every offline run, so it is the suite's real documentation.
+ *
+ * `pnpm test` runs the whole directory instead of filtering this file out: a
+ * skipped test that says how to unskip itself is discoverable at the moment it
+ * is relevant, which a note in a file nobody opens is not.
+ */
+const SKIP_REASON = "needs a real model — set PI_AHP_LIVE_SETTINGS and PI_AHP_LIVE_AUTH";
+
+interface LiveSettingsFile {
+	readonly defaultProvider?: unknown;
+	readonly defaultModel?: unknown;
+	readonly defaultThinkingLevel?: unknown;
+	readonly modelThinkingLevels?: Record<string, unknown>;
+}
+
+describe("live turn", { skip: LIVE ? false : SKIP_REASON }, () => {
+	let root: string;
+	let workspace: string;
+	let server: RunningServer;
+	let client: AhpClient;
+	let built: Awaited<ReturnType<typeof createPiHost>>;
+	let host: Awaited<ReturnType<typeof createPiHost>>["host"];
+	let sessions: Awaited<ReturnType<typeof createPiHost>>["sessions"];
+	let selection: ModelSelection;
+	let thinking: string;
+	let previousAgentDir: string | undefined;
+
+	before(async () => {
+		root = mkdtempSync(join(tmpdir(), "pi-ahp-live-"));
+		previousAgentDir = process.env.PI_CODING_AGENT_DIR;
+		assert.ok(LIVE_SETTINGS, "PI_AHP_LIVE_SETTINGS must name a dedicated settings.json");
+		assert.ok(LIVE_AUTH, "PI_AHP_LIVE_AUTH must name a dedicated auth.json");
+		const settingsPath = resolve(LIVE_SETTINGS);
+		const authPath = resolve(LIVE_AUTH);
+		assert.ok(existsSync(settingsPath), `live-test settings file does not exist: ${settingsPath}`);
+		assert.ok(existsSync(authPath), `live-test auth file does not exist: ${authPath}`);
+		const settings = JSON.parse(readFileSync(settingsPath, "utf8")) as LiveSettingsFile;
+		assert.ok(
+			typeof settings.defaultProvider === "string" && settings.defaultProvider.length > 0,
+			"live-test settings must explicitly set defaultProvider",
+		);
+		assert.ok(
+			typeof settings.defaultModel === "string" && settings.defaultModel.length > 0,
+			"live-test settings must explicitly set defaultModel",
+		);
+		const modelId = `${settings.defaultProvider}/${settings.defaultModel}`;
+		const perModelThinking = settings.modelThinkingLevels?.[modelId];
+		const configuredThinking = perModelThinking ?? settings.defaultThinkingLevel;
+		assert.ok(
+			typeof configuredThinking === "string" && configuredThinking.length > 0,
+			"live-test settings must explicitly set a thinking level",
+		);
+		thinking = configuredThinking;
+		selection = { id: modelId, config: { [THINKING_CONFIG_KEY]: thinking } };
+		workspace = join(root, "workspace");
+		const agentDir = join(root, "agent");
+		const sessionRoot = join(agentDir, "sessions");
+		mkdirSync(workspace);
+		mkdirSync(agentDir);
+		writeFileSync(join(workspace, "note.txt"), "ALPHA BETA GAMMA\n");
+
+		// These explicit files are the only profile data imported. Package installs,
+		// token refreshes, sessions, and any settings writes stay in the temporary
+		// profile and disappear with it.
+		copyFileSync(settingsPath, join(agentDir, "settings.json"));
+		copyFileSync(authPath, join(agentDir, "auth.json"));
+		process.env.PI_CODING_AGENT_DIR = agentDir;
+
+		// SDK startup is deliberately cache-only. A clean live profile has no
+		// models-store yet, so refresh dynamic provider catalogues explicitly;
+		// the resulting cache remains inside this temporary directory.
+		const discovery = await createAgentSessionServices({
+			cwd: workspace,
+			settingsManager: SettingsManager.create(workspace, undefined, { projectTrusted: false }),
+		});
+		assert.deepEqual(discovery.diagnostics, [], "live-test provider extension failed to load");
+		const refreshed = await discovery.modelRuntime.refresh({
+			allowNetwork: true,
+			providers: [settings.defaultProvider],
+		});
+		assert.equal(refreshed.aborted, false, "live-test model discovery was aborted");
+		assert.equal(
+			refreshed.errors.size,
+			0,
+			`live-test model discovery failed: ${[...refreshed.errors].map(([provider, error]) => `${provider}: ${error.message}`).join("; ")}`,
+		);
+
+		built = await createPiHost({
+			serverInfo: { name: "pi-ahp", version: "live-test" },
+			workingDirectory: workspace,
+			modelRuntime: discovery.modelRuntime,
+			sessionStorage: persistentSessionStorage(sessionRoot),
+			projectTrustPolicy: "never",
+			createBackend: async (session) => {
+				const backend = await InProcessPiBackend.create({
+					cwd: session.workingDirectory,
+					sessionManager: session.sessionManager,
+					projectTrustPolicy: "never",
+				});
+				assert.deepEqual(
+					backend.currentSelection(),
+					selection,
+					"Pi did not initialize the explicitly requested live-test model",
+				);
+				return backend;
+			},
+		});
+		host = built.host;
+		sessions = built.sessions;
+		const rootState = host.store.get("ahp-root://") as RootState;
+		assertValid("state", "RootState", rootState);
+		const available = rootState.agents.flatMap((agent) => agent.models);
+		const requested = available.find((model) => model.id === selection.id);
+		assert.ok(
+			requested,
+			`configured live-test model ${selection.id} is unavailable; available models: ${available.map((model) => model.id).join(", ")}`,
+		);
+		const configuredLevels = requested.configSchema?.properties?.[THINKING_CONFIG_KEY]?.enum?.filter(
+			(level): level is string => typeof level === "string",
+		);
+		if (configuredLevels && configuredLevels.length > 0) {
+			assert.ok(
+				configuredLevels.includes(thinking),
+				`${selection.id} does not support thinking=${thinking}; choose one of: ${configuredLevels.join(", ")}`,
+			);
+		} else {
+			assert.equal(thinking, "off", `${selection.id} does not advertise configurable thinking; use off`);
+		}
+		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();
+		await client.initialize({
+			clientId: "live-client",
+			protocolVersions: SUPPORTED_PROTOCOL_VERSIONS,
+			initialSubscriptions: ["ahp-root://"],
+		});
+	});
+
+	after(async () => {
+		try {
+			await client?.shutdown();
+			await server?.close();
+			built?.terminals.shutdown();
+			await Promise.all([built?.changesets.dispose(), built?.watches.dispose()]);
+		} finally {
+			if (previousAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+			else process.env.PI_CODING_AGENT_DIR = previousAgentDir;
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	function assertSessionState(sessionChannel: string, chatChannel: string): void {
+		assertValid("state", "SessionState", host.store.get(sessionChannel));
+		assertValid("state", "ChatState", host.store.get(chatChannel));
+	}
+
+	function assertPersistedSelection(sessionChannel: string): void {
+		const context = must(sessions.get(sessionChannel)).sessionManager.buildSessionContext();
+		const model = must(context.model);
+		assert.equal(`${model.provider}/${model.modelId}`, selection.id);
+		assert.equal(context.thinkingLevel, thinking);
+	}
+
+	async function runLiveTurn(
+		turnId: string,
+		text: string,
+	): Promise<{ id: string; sessionChannel: string; turn: Turn }> {
+		const id = randomUUID();
+		const sessionChannel = sessionUri(id);
+		const chatChannel = chatUri(id);
+		await client.request("createSession", { channel: sessionChannel });
+		await client.subscribe(sessionChannel);
+		await client.subscribe(chatChannel);
+		await eventually(
+			"the live session backend to settle",
+			() => (host.store.get(sessionChannel) as SessionState).lifecycle !== SessionLifecycle.Creating,
+			{ timeoutMs: 30_000, intervalMs: 50 },
+		);
+		const sessionState = host.store.get(sessionChannel) as SessionState;
+		assert.equal(sessionState.lifecycle, SessionLifecycle.Ready, sessionState.creationError?.message);
+		client.dispatch(chatChannel, {
+			type: ActionType.ChatTurnStarted,
+			turnId,
+			startedAt: new Date().toISOString(),
+			message: { text, origin: { kind: MessageKind.User }, model: selection },
+		});
+		await eventually("the live turn to complete", () => (host.store.get(chatChannel) as ChatState).turns.length === 1, {
+			timeoutMs: TURN_TIMEOUT_MS,
+			intervalMs: 50,
+		});
+		const state = host.store.get(chatChannel) as ChatState;
+		assertSessionState(sessionChannel, chatChannel);
+		const turn = must(state.turns[0]);
+		assert.equal(turn.state, TurnState.Complete, `turn failed: ${turnError(turn)?.message ?? ""}`);
+		assert.equal(state.activeTurn, undefined);
+		assertPersistedSelection(sessionChannel);
+		return { id, sessionChannel, turn };
+	}
+
+	it("streams a real assistant reply into chat state", async () => {
+		const { id, sessionChannel, turn } = await runLiveTurn("live-1", "Reply with exactly the word: PONG");
+
+		const text = turn.responseParts
+			.filter((part) => part.kind === ResponsePartKind.Markdown)
+			.map((part) => (part as { content: string }).content)
+			.join("");
+		assert.match(text, /PONG/i);
+		// Usage only arrives if `message_end` carried it, which is the path the
+		// mapper reads.
+		assert.ok(turn.usage?.outputTokens !== undefined, "no usage reported");
+
+		const live = sessions.get(sessionChannel);
+		assert.ok(live, "session should still be live");
+		assert.equal(live.sessionId, id);
+		const file = live.sessionManager.getSessionFile();
+		assert.ok(file, "pi should have written a session file for a real turn");
+		const contents = readFileSync(file, "utf8");
+		assert.match(contents, /Reply with exactly the word: PONG/);
+		assert.match(contents, new RegExp(`"id"\\s*:\\s*"${id}"`));
+	});
+
+	it("drives a real tool call to completion without confirmation", async () => {
+		const { turn } = await runLiveTurn(
+			"live-tool",
+			"Read note.txt in the working directory and reply with its exact contents.",
+		);
+
+		const toolCalls = turn.responseParts.filter((part) => part.kind === ResponsePartKind.ToolCall);
+		assert.ok(toolCalls.length > 0, "expected at least one tool call");
+		for (const part of toolCalls) {
+			const toolCall = (part as { toolCall: { status: string; toolName: string } }).toolCall;
+			// Auto-confirmed calls go straight to running, so every one should
+			// have reached a terminal state by the time the turn closed.
+			assert.ok(
+				toolCall.status === ToolCallStatus.Completed || toolCall.status === ToolCallStatus.Cancelled,
+				`tool ${toolCall.toolName} ended in ${toolCall.status}`,
+			);
+		}
+
+		const text = turn.responseParts
+			.filter((part) => part.kind === ResponsePartKind.Markdown)
+			.map((part) => (part as { content: string }).content)
+			.join("");
+		assert.match(text, /ALPHA BETA GAMMA/);
+	});
+});

package/proof/oracle/test/mapper-fixtures.test.ts

@@ -0,0 +1,293 @@
+/**
+ * Replays recorded pi event streams through the mapper, offline.
+ *
+ * These fixtures were captured from a real model (`scripts/capture-fixtures.ts`)
+ * and scrubbed of machine- and tenant-specific values. They cover provider
+ * event shapes that synthetic mapper fixtures may omit.
+ *
+ * The assertions are deliberately structural rather than exact-output: the model
+ * is free to phrase things differently on a re-capture, but the *shape* of the
+ * turn must hold.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	ActionType,
+	type ChatState,
+	chatReducer,
+	ResponsePartKind,
+	type StateAction,
+	ToolCallStatus,
+	TurnState,
+} from "@microsoft/agent-host-protocol";
+import { initialChatState } from "../src/channels/chat.ts";
+import { TurnMapper, userTurnStarted } from "../src/pi/event-mapper.ts";
+import { must } from "./support/assertions.ts";
+import { loadRecordedFixtures, type RecordedFixture } from "./support/recorded-fixtures.ts";
+import { assertValid } from "./support/schema.ts";
+
+const CHAT_URI = "ahp-chat:/replay";
+const TURN_ID = "replay-turn";
+
+interface Replayed {
+	readonly fixture: RecordedFixture;
+	readonly actions: StateAction[];
+	readonly state: ChatState;
+}
+
+function replay(fixture: RecordedFixture): Replayed {
+	const mapper = new TurnMapper(TURN_ID, 0);
+	const actions: StateAction[] = [userTurnStarted(TURN_ID, fixture.prompt, "1970-01-01T00:00:00.000Z")];
+	for (const event of fixture.events) {
+		actions.push(...mapper.handle(event));
+	}
+
+	let state = initialChatState(CHAT_URI, "Replay");
+	for (const action of actions) {
+		state = chatReducer(state, action as never);
+	}
+	return { fixture, actions, state };
+}
+
+const fixtures = loadRecordedFixtures().map(({ fixture }) => fixture);
+const fixturesByName = new Map(fixtures.map((fixture) => [fixture.name, fixture]));
+const replayedByName = new Map<string, Replayed>();
+
+function get(name: string): Replayed {
+	const fixture = fixturesByName.get(name);
+	assert.ok(fixture, `unknown recorded fixture: ${name}`);
+	let replayed = replayedByName.get(name);
+	if (!replayed) {
+		replayed = replay(fixture);
+		replayedByName.set(name, replayed);
+	}
+	return replayed;
+}
+
+function allReplayed(): Replayed[] {
+	return fixtures.map((fixture) => get(fixture.name));
+}
+
+function markdownText(state: ChatState): string {
+	const turn = state.turns[0] ?? state.activeTurn;
+	return (turn?.responseParts ?? [])
+		.filter((part) => part.kind === ResponsePartKind.Markdown)
+		.map((part) => (part as { content: string }).content)
+		.join("");
+}
+
+interface ReplayedToolCall {
+	readonly status: string;
+	readonly toolName: string;
+	readonly success?: boolean;
+	readonly displayName?: string;
+	readonly invocationMessage?: string;
+	readonly pastTenseMessage?: string;
+	readonly toolInput?: string;
+	readonly content?: readonly { readonly type: string; readonly text?: string }[];
+	readonly error?: { readonly message?: string };
+}
+
+function toolCalls(state: ChatState): ReplayedToolCall[] {
+	const turn = state.turns[0] ?? state.activeTurn;
+	return (turn?.responseParts ?? [])
+		.filter((part) => part.kind === ResponsePartKind.ToolCall)
+		.map((part) => (part as { toolCall: ReplayedToolCall }).toolCall);
+}
+
+/** The text a tool reported, as the client would concatenate it. */
+function toolResultText(call: ReplayedToolCall): string {
+	return (call.content ?? [])
+		.filter((block) => block.type === "text")
+		.map((block) => block.text ?? "")
+		.join("");
+}
+
+function assertReplayInvariants({ fixture, actions, state }: Replayed): void {
+	const opened = actions.filter((action) => action.type === ActionType.ChatTurnStarted).length;
+	const terminators = actions.filter(
+		(action) =>
+			action.type === ActionType.ChatTurnComplete ||
+			action.type === ActionType.ChatTurnCancelled ||
+			action.type === ActionType.ChatError,
+	);
+
+	// More than one turn means pi injected a message mid-run; each still has to
+	// terminate exactly once.
+	assert.equal(terminators.length, opened, `${fixture.name}: every opened turn must terminate once`);
+	assert.equal(state.activeTurn, undefined, `${fixture.name}: active turn remained after replay`);
+	assert.equal(state.turns.length, opened, `${fixture.name}: reduced turn count differs from opened turns`);
+
+	for (const action of actions) {
+		assertValid("actions", "StateAction", action, `${fixture.name}: non-conforming ${action.type}`);
+	}
+	for (const call of toolCalls(state)) {
+		assert.ok(
+			call.status === ToolCallStatus.Completed || call.status === ToolCallStatus.Cancelled,
+			`${fixture.name}: ${call.toolName} ended in ${call.status}`,
+		);
+	}
+
+	// A delta naming an unknown partId is a silent reducer no-op, so validate
+	// creation order as well as uniqueness.
+	const created = new Set<string>();
+	const ids: Array<string | undefined> = [];
+	for (const action of actions) {
+		if (action.type === ActionType.ChatResponsePart) {
+			const id = "id" in action.part ? action.part.id : undefined;
+			ids.push(id);
+			if (id) created.add(id);
+		}
+		if (action.type === ActionType.ChatDelta || action.type === ActionType.ChatReasoning) {
+			assert.ok(created.has(action.partId), `${fixture.name}: delta targets unknown part ${action.partId}`);
+		}
+	}
+	assert.equal(new Set(ids).size, ids.length, `${fixture.name}: response part ids collided within a turn`);
+}
+
+describe("recorded stream replay — invariants", () => {
+	for (const fixture of fixtures) {
+		it(`${fixture.name} — ${fixture.description}`, () => {
+			assertReplayInvariants(get(fixture.name));
+		});
+	}
+});
+
+describe("recorded stream replay — per scenario", () => {
+	it("plain-text: answers with no tool calls", () => {
+		const { state } = get("plain-text");
+		assert.equal(state.turns[0]?.state, TurnState.Complete);
+		assert.equal(toolCalls(state).length, 0);
+		assert.match(markdownText(state), /PONG/i);
+	});
+
+	it("describes a tool call in terms a user can act on", () => {
+		// These three fields are what a client renders around a tool call: a
+		// heading, a line while it runs, and a line once it has. pi knows which
+		// file was read or which command ran, and a message that only repeats the
+		// tool's name spends all three on saying `read` three times.
+		for (const { fixture, state } of allReplayed()) {
+			for (const call of toolCalls(state)) {
+				if (!call.toolInput || call.toolInput === "{}") {
+					continue;
+				}
+				assert.notEqual(
+					call.invocationMessage,
+					call.toolName,
+					`${fixture.name}: ${call.toolName} announces itself with nothing but its own name`,
+				);
+				// The two lines sit next to each other in a transcript, one for a
+				// call in flight and one for a call that finished. Identical text
+				// leaves a completed call still claiming to be running.
+				assert.notEqual(
+					call.pastTenseMessage,
+					call.invocationMessage,
+					`${fixture.name}: ${call.toolName} still says it is ${call.invocationMessage} after it finished`,
+				);
+			}
+		}
+	});
+
+	it("shows a tool's subject rather than its arguments as JSON", () => {
+		// `toolInput` is what a client renders for the call itself, and the
+		// protocol carries no structured parameters beside it, so serialising the
+		// argument object spends the field on quoting and braces. Each of pi's
+		// tools has one argument that says what the call is about.
+		for (const { fixture, state } of allReplayed()) {
+			for (const call of toolCalls(state)) {
+				if (call.toolInput === undefined) {
+					continue;
+				}
+				assert.ok(
+					!call.toolInput.startsWith("{"),
+					`${fixture.name}: ${call.toolName} shows its arguments as JSON: ${call.toolInput.slice(0, 60)}`,
+				);
+			}
+		}
+	});
+
+	it("tool-edit: hands the client the patch, not a count of edited blocks", () => {
+		// pi computes a unified diff for every edit and reports only how many
+		// blocks it replaced. The patch is the part a client can render — the
+		// same monospace, syntax-highlighted block a shell command gets.
+		const { state } = get("tool-edit");
+		const edits = toolCalls(state).filter((call) => call.toolName === "edit");
+		assert.ok(edits.length >= 1, "expected an edit call");
+		for (const call of edits) {
+			const shown = toolResultText(call);
+			assert.match(shown, /^--- |\n--- /, `edit result carries no patch: ${shown.slice(0, 80)}`);
+			assert.match(shown, /^\+.*$/m, "a patch with no added lines is not a patch");
+		}
+	});
+
+	it("single-tool: runs one tool and answers from its result", () => {
+		const { state } = get("single-tool");
+		assert.equal(state.turns[0]?.state, TurnState.Complete);
+		assert.ok(toolCalls(state).length >= 1);
+		assert.match(markdownText(state), /ALPHA BETA GAMMA/);
+	});
+
+	it("parallel-tools: keeps several tool calls in one message distinct", () => {
+		const { state } = get("parallel-tools");
+		const calls = toolCalls(state);
+		assert.ok(calls.length >= 2, `expected multiple tool calls, got ${calls.length}`);
+		assert.match(markdownText(state), /FIRST/);
+		assert.match(markdownText(state), /SECOND/);
+	});
+
+	it("tool-loop: spans several assistant messages without part collisions", () => {
+		const { fixture, state } = get("tool-loop");
+		const assistantMessages = fixture.events.filter(
+			(event) =>
+				event.type === "message_start" && (event as { message?: { role?: string } }).message?.role === "assistant",
+		).length;
+
+		// The scenario exists to produce more than one assistant message, which
+		// is where pi's contentIndex restarts at 0.
+		assert.ok(assistantMessages >= 2, `expected multiple assistant messages, got ${assistantMessages}`);
+		assert.equal(state.turns[0]?.state, TurnState.Complete);
+		assert.match(markdownText(state), /42/);
+	});
+
+	it("tool-error: surfaces a failed tool without failing the turn", () => {
+		const { state } = get("tool-error");
+		const failed = toolCalls(state).filter((call) => call.success === false);
+		assert.ok(failed.length >= 1, "expected a failed tool call");
+
+		// What the client shows for a failure is `error.message`. pi says why —
+		// here an ENOENT naming the missing path — and a message that only
+		// repeats the tool's name tells the user nothing they did not know.
+		for (const call of failed) {
+			const reported = toolResultText(call);
+			assert.ok(reported.length > 0, `${call.toolName}: no failure text to show`);
+			assert.equal(
+				call.error?.message,
+				reported,
+				`${call.toolName}: error.message should carry what pi reported, not a restatement of the tool name`,
+			);
+		}
+		// The agent recovers and answers, so the turn itself still completes.
+		assert.equal(state.turns[0]?.state, TurnState.Complete);
+	});
+
+	it("abort: ends the turn as cancelled", () => {
+		const { state } = get("abort");
+		assert.equal(state.turns[0]?.state, TurnState.Cancelled);
+	});
+
+	it("steering: the injected message becomes its own turn", () => {
+		const { fixture, state } = get("steering");
+		const injectedUserMessages = fixture.events.filter(
+			(event) => event.type === "message_start" && (event as { message?: { role?: string } }).message?.role === "user",
+		).length;
+		assert.ok(injectedUserMessages >= 2, "expected the steering message to appear mid-run");
+
+		// pi stores an injected message as an ordinary user message, with
+		// nothing marking it as steering — so a rebuild from disk necessarily
+		// makes it a turn. The live path matches, or the same conversation would
+		// render differently before and after a reload.
+		assert.equal(state.turns.length, injectedUserMessages);
+		assert.match(must(state.turns.at(-1)).message.text, /Stop counting/);
+	});
+});