gsd-pi 2.58.0 → 2.59.0-dev.3de3832

package/packages/pi-coding-agent/src/core/extensions/extension-sort.ts

@@ -0,0 +1,137 @@
+// GSD-2 — Extension Sort: Topological dependency ordering
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import { readManifestFromEntryPath } from "./extension-manifest.js";
+
+export interface SortWarning {
+	declaringId: string;
+	missingId: string;
+	message: string;
+}
+
+export interface SortResult {
+	sortedPaths: string[];
+	warnings: SortWarning[];
+}
+
+/**
+ * Sort extension entry paths in topological dependency-first order using Kahn's BFS algorithm.
+ *
+ * - Extensions without manifests are prepended in input order.
+ * - Missing dependencies produce a structured warning but do not block loading.
+ * - Cycles produce warnings; cycle participants are appended alphabetically.
+ * - Self-dependencies are silently ignored.
+ */
+export function sortExtensionPaths(paths: string[]): SortResult {
+	const warnings: SortWarning[] = [];
+	const pathsWithoutId: string[] = [];
+	const idToPath = new Map<string, string>();
+
+	// Step 1: Build ID map
+	for (const p of paths) {
+		const manifest = readManifestFromEntryPath(p);
+		if (!manifest) {
+			pathsWithoutId.push(p);
+		} else {
+			idToPath.set(manifest.id, p);
+		}
+	}
+
+	// Step 2: Build graph — inDegree and dependents adjacency
+	const inDegree = new Map<string, number>();
+	const dependents = new Map<string, string[]>(); // dep → [ids that depend on dep]
+
+	for (const id of idToPath.keys()) {
+		if (!inDegree.has(id)) inDegree.set(id, 0);
+		if (!dependents.has(id)) dependents.set(id, []);
+	}
+
+	for (const [id, entryPath] of idToPath) {
+		const manifest = readManifestFromEntryPath(entryPath);
+		const rawDeps = manifest?.dependencies?.extensions ?? [];
+		const deps = Array.isArray(rawDeps) ? rawDeps : [];
+
+		for (const depId of deps) {
+			// Silently ignore self-deps
+			if (depId === id) continue;
+
+			if (!idToPath.has(depId)) {
+				// Missing dependency — warn and skip edge
+				warnings.push({
+					declaringId: id,
+					missingId: depId,
+					message: `Extension '${id}' declares dependency '${depId}' which is not installed — loading anyway`,
+				});
+				continue;
+			}
+
+			// Valid edge: id depends on depId → increment inDegree[id], add id to dependents[depId]
+			inDegree.set(id, (inDegree.get(id) ?? 0) + 1);
+			const depDependents = dependents.get(depId) ?? [];
+			depDependents.push(id);
+			dependents.set(depId, depDependents);
+		}
+	}
+
+	// Step 3: Kahn's algorithm — start with nodes that have inDegree 0
+	const sorted: string[] = [];
+	// Ready queue: IDs with inDegree 0, maintained in alphabetical order
+	const ready: string[] = [...idToPath.keys()]
+		.filter((id) => inDegree.get(id) === 0)
+		.sort();
+
+	while (ready.length > 0) {
+		const id = ready.shift()!;
+		sorted.push(idToPath.get(id)!);
+
+		const deps = dependents.get(id) ?? [];
+		for (const depId of deps) {
+			const newDegree = (inDegree.get(depId) ?? 0) - 1;
+			inDegree.set(depId, newDegree);
+			if (newDegree === 0) {
+				// Insert into ready queue maintaining alphabetical order
+				const insertIdx = ready.findIndex((r) => r > depId);
+				if (insertIdx === -1) {
+					ready.push(depId);
+				} else {
+					ready.splice(insertIdx, 0, depId);
+				}
+			}
+		}
+	}
+
+	// Step 4: Cycle handling — any remaining IDs with inDegree > 0
+	const cycleIds = [...idToPath.keys()]
+		.filter((id) => (inDegree.get(id) ?? 0) > 0)
+		.sort();
+
+	if (cycleIds.length > 0) {
+		const cycleSet = new Set(cycleIds);
+
+		for (const id of cycleIds) {
+			const entryPath = idToPath.get(id)!;
+			const manifest = readManifestFromEntryPath(entryPath);
+			const rawDeps = manifest?.dependencies?.extensions ?? [];
+			const deps = Array.isArray(rawDeps) ? rawDeps : [];
+
+			for (const depId of deps) {
+				if (depId === id) continue;
+				if (!cycleSet.has(depId)) continue;
+
+				// Both id and depId are in cycle — emit warning
+				warnings.push({
+					declaringId: id,
+					missingId: depId,
+					message: `Extension '${id}' and '${depId}' form a dependency cycle — loading both anyway (alphabetical order)`,
+				});
+			}
+
+			sorted.push(entryPath);
+		}
+	}
+
+	return {
+		sortedPaths: [...pathsWithoutId, ...sorted],
+		warnings,
+	};
+}

package/packages/pi-coding-agent/src/core/extensions/index.ts

@@ -2,6 +2,10 @@
  * Extension system for lifecycle events and custom tools.
  */
 
+export type { ExtensionManifest } from "./extension-manifest.js";
+export { readManifest, readManifestFromEntryPath } from "./extension-manifest.js";
+export type { SortResult, SortWarning } from "./extension-sort.js";
+export { sortExtensionPaths } from "./extension-sort.js";
 export type { SlashCommandInfo, SlashCommandLocation, SlashCommandSource } from "../slash-commands.js";
 export {
 	createExtensionRuntime,

package/packages/pi-coding-agent/src/core/extensions/loader.ts

@@ -941,6 +941,11 @@ function discoverExtensionsInDir(dir: string): string[] {
 
 /**
  * Discover and load extensions from standard locations.
+ *
+ * @deprecated Use DefaultResourceLoader.reload() instead — this function is
+ * not called in the GSD loading flow. Extension discovery happens through
+ * DefaultPackageManager.resolve() → addAutoDiscoveredResources(). Kept for
+ * backwards compatibility with direct pi-coding-agent consumers.
  */
 export async function discoverAndLoadExtensions(
 	configuredPaths: string[],

package/packages/pi-coding-agent/src/core/image-overflow-recovery.test.ts

@@ -0,0 +1,228 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	isImageDimensionError,
+	MANY_IMAGE_MAX_DIMENSION,
+	downsizeConversationImages,
+} from "./image-overflow-recovery.js";
+import type { Message } from "@gsd/pi-ai";
+
+// ─── isImageDimensionError ────────────────────────────────────────────────────
+
+describe("isImageDimensionError", () => {
+	it("returns true for Anthropic many-image dimension error", () => {
+		const errorMessage =
+			'Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.125.content.38.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels"}}';
+		assert.equal(isImageDimensionError(errorMessage), true);
+	});
+
+	it("returns true for bare dimension exceed message", () => {
+		const errorMessage =
+			"image dimensions exceed max allowed size for many-image requests: 2000 pixels";
+		assert.equal(isImageDimensionError(errorMessage), true);
+	});
+
+	it("returns false for unrelated 400 error", () => {
+		const errorMessage =
+			'Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"max_tokens: 4096 > 2048"}}';
+		assert.equal(isImageDimensionError(errorMessage), false);
+	});
+
+	it("returns false for rate limit error", () => {
+		assert.equal(isImageDimensionError("429 rate limit exceeded"), false);
+	});
+
+	it("returns false for empty string", () => {
+		assert.equal(isImageDimensionError(""), false);
+	});
+
+	it("returns false for undefined", () => {
+		assert.equal(isImageDimensionError(undefined), false);
+	});
+});
+
+// ─── MANY_IMAGE_MAX_DIMENSION ─────────────────────────────────────────────────
+
+describe("MANY_IMAGE_MAX_DIMENSION", () => {
+	it("is less than 2000 (the API-enforced limit)", () => {
+		assert.ok(MANY_IMAGE_MAX_DIMENSION < 2000);
+	});
+
+	it("is a positive integer", () => {
+		assert.ok(MANY_IMAGE_MAX_DIMENSION > 0);
+		assert.equal(MANY_IMAGE_MAX_DIMENSION, Math.floor(MANY_IMAGE_MAX_DIMENSION));
+	});
+});
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+function makeUserMsg(content: Message["content"] & any): Message {
+	return { role: "user", content, timestamp: Date.now() } as Message;
+}
+
+function makeAssistantMsg(text: string): Message {
+	return {
+		role: "assistant",
+		content: [{ type: "text", text }],
+		api: "anthropic-messages",
+		provider: "anthropic",
+		model: "claude-opus-4-6",
+		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+		stopReason: "stop",
+		timestamp: Date.now(),
+	} as Message;
+}
+
+function makeToolResultMsg(images: number): Message {
+	const content: any[] = [];
+	for (let i = 0; i < images; i++) {
+		content.push({ type: "image", data: `img${i}`, mimeType: "image/png" });
+	}
+	return {
+		role: "toolResult",
+		toolCallId: `tc${Math.random()}`,
+		toolName: "screenshot",
+		content,
+		isError: false,
+		timestamp: Date.now(),
+	} as Message;
+}
+
+// ─── downsizeConversationImages ───────────────────────────────────────────────
+
+describe("downsizeConversationImages", () => {
+	it("counts images in user and toolResult messages", () => {
+		const messages: Message[] = [
+			makeUserMsg([
+				{ type: "image", data: "img1", mimeType: "image/png" },
+				{ type: "image", data: "img2", mimeType: "image/png" },
+			]),
+			makeAssistantMsg("I see them"),
+			makeToolResultMsg(1),
+		];
+
+		const result = downsizeConversationImages(messages);
+		assert.equal(result.imageCount, 3);
+	});
+
+	it("returns processed=false when no images present", () => {
+		const messages: Message[] = [
+			makeUserMsg("just text"),
+			makeAssistantMsg("reply"),
+		];
+
+		const result = downsizeConversationImages(messages);
+		assert.equal(result.imageCount, 0);
+		assert.equal(result.processed, false);
+	});
+
+	it("returns processed=false when image count <= RECENT_IMAGES_TO_KEEP", () => {
+		const messages: Message[] = [
+			makeUserMsg([
+				{ type: "image", data: "img1", mimeType: "image/png" },
+			]),
+			makeAssistantMsg("got it"),
+		];
+
+		const result = downsizeConversationImages(messages);
+		assert.equal(result.imageCount, 1);
+		assert.equal(result.processed, false);
+	});
+
+	it("strips older images when many images present, preserves recent ones", () => {
+		const messages: Message[] = [];
+		for (let i = 0; i < 25; i++) {
+			messages.push(
+				makeUserMsg([
+					{ type: "text", text: `message ${i}` },
+					{ type: "image", data: `img${i}`, mimeType: "image/png" },
+				]),
+			);
+			messages.push(makeAssistantMsg(`reply ${i}`));
+		}
+
+		const result = downsizeConversationImages(messages);
+		assert.ok(result.processed);
+		assert.equal(result.imageCount, 25);
+		assert.equal(result.strippedCount, 20); // 25 - 5 recent
+
+		// Count remaining images
+		let remainingImages = 0;
+		for (const msg of messages) {
+			if (msg.role === "assistant") continue;
+			if (typeof msg.content === "string") continue;
+			const arr = msg.content as any[];
+			for (const block of arr) {
+				if (block.type === "image") remainingImages++;
+			}
+		}
+		assert.equal(remainingImages, 5, "Should keep exactly 5 most recent images");
+
+		// The 5 most recent user messages (indices 40,42,44,46,48) should have images
+		for (let i = 20; i < 25; i++) {
+			const userMsg = messages[i * 2]; // user messages at even indices
+			const arr = userMsg.content as any[];
+			const hasImage = arr.some((c: any) => c.type === "image");
+			assert.ok(hasImage, `Recent message ${i} should retain its image`);
+		}
+	});
+
+	it("adds text placeholder when stripping an image", () => {
+		const messages: Message[] = [];
+		for (let i = 0; i < 10; i++) {
+			messages.push(
+				makeUserMsg([
+					{ type: "image", data: `img${i}`, mimeType: "image/jpeg" },
+				]),
+			);
+			messages.push(makeAssistantMsg(`reply ${i}`));
+		}
+
+		downsizeConversationImages(messages);
+
+		// First message's image should have been replaced with text
+		const firstMsg = messages[0];
+		const arr = firstMsg.content as any[];
+		const placeholder = arr.find(
+			(c: any) => c.type === "text" && c.text.includes("[image removed"),
+		);
+		assert.ok(placeholder, "Stripped image should be replaced with text placeholder");
+		assert.ok(
+			placeholder.text.includes("image/jpeg"),
+			"Placeholder should mention original mime type",
+		);
+	});
+
+	it("handles toolResult messages with images", () => {
+		const messages: Message[] = [];
+		for (let i = 0; i < 10; i++) {
+			messages.push(makeToolResultMsg(1));
+			messages.push(makeAssistantMsg(`reply ${i}`));
+		}
+
+		const result = downsizeConversationImages(messages);
+		assert.equal(result.imageCount, 10);
+		assert.equal(result.strippedCount, 5);
+		assert.ok(result.processed);
+	});
+
+	it("handles mixed user and toolResult images", () => {
+		const messages: Message[] = [];
+		for (let i = 0; i < 8; i++) {
+			messages.push(
+				makeUserMsg([
+					{ type: "text", text: `check ${i}` },
+					{ type: "image", data: `uimg${i}`, mimeType: "image/png" },
+				]),
+			);
+			messages.push(makeAssistantMsg(`processing ${i}`));
+			messages.push(makeToolResultMsg(1));
+			messages.push(makeAssistantMsg(`done ${i}`));
+		}
+
+		const result = downsizeConversationImages(messages);
+		// 8 user images + 8 tool result images = 16 total
+		assert.equal(result.imageCount, 16);
+		assert.equal(result.strippedCount, 11); // 16 - 5 recent
+	});
+});

package/packages/pi-coding-agent/src/core/image-overflow-recovery.ts

@@ -0,0 +1,118 @@
+/**
+ * Image overflow recovery for many-image sessions.
+ *
+ * When a conversation accumulates many images (screenshots, file reads, etc.),
+ * the Anthropic API enforces a stricter per-image dimension limit (2000px) for
+ * "many-image requests." This module detects the resulting 400 error and
+ * recovers by stripping older images from the conversation history, preserving
+ * the most recent ones to maintain session continuity.
+ *
+ * @see https://github.com/gsd-build/gsd-2/issues/2874
+ */
+
+import type { Message, ImageContent, TextContent } from "@gsd/pi-ai";
+
+/**
+ * Maximum image dimension (px) that the Anthropic API allows in many-image
+ * requests. Images at or above this size in a large conversation will be
+ * rejected with a 400 error. We use 1568 as the safe ceiling (Anthropic's
+ * recommended max for multi-image requests).
+ */
+export const MANY_IMAGE_MAX_DIMENSION = 1568;
+
+/**
+ * Number of recent images to preserve when stripping old images.
+ * Keeps the most recent screenshots/images so the model retains visual context
+ * for the current task.
+ */
+const RECENT_IMAGES_TO_KEEP = 5;
+
+/**
+ * Regex matching the Anthropic API error for oversized images in many-image requests.
+ */
+const IMAGE_DIMENSION_ERROR_RE =
+	/image.dimensions?.exceed.*max.*allowed.*size.*many.image/i;
+
+/**
+ * Detect whether an error message is the Anthropic "image dimensions exceed max
+ * allowed size for many-image requests" 400 error.
+ */
+export function isImageDimensionError(errorMessage: string | undefined | null): boolean {
+	if (!errorMessage) return false;
+	return IMAGE_DIMENSION_ERROR_RE.test(errorMessage);
+}
+
+export interface DownsizeResult {
+	/** Total number of images found in the conversation */
+	imageCount: number;
+	/** Whether any images were stripped */
+	processed: boolean;
+	/** Number of images that were stripped */
+	strippedCount: number;
+}
+
+/**
+ * Strip older images from conversation messages to recover from many-image
+ * dimension errors. Preserves the N most recent images and replaces older ones
+ * with a text placeholder.
+ *
+ * Mutates messages in place (same pattern as replaceMessages/compaction).
+ *
+ * Accepts Message[] (the LLM message union) so it works with both
+ * agent.state.messages and session entries.
+ */
+export function downsizeConversationImages(messages: Message[]): DownsizeResult {
+	// First pass: collect all image locations (message index + content index)
+	const imageLocations: Array<{ msgIdx: number; contentIdx: number }> = [];
+
+	for (let msgIdx = 0; msgIdx < messages.length; msgIdx++) {
+		const msg = messages[msgIdx];
+		if (msg.role === "assistant") continue;
+
+		// UserMessage can have string content; ToolResultMessage always has array
+		if (msg.role === "user" && typeof msg.content === "string") continue;
+
+		const contentArr = msg.content as (TextContent | ImageContent)[];
+		if (!Array.isArray(contentArr)) continue;
+
+		for (let contentIdx = 0; contentIdx < contentArr.length; contentIdx++) {
+			if (contentArr[contentIdx].type === "image") {
+				imageLocations.push({ msgIdx, contentIdx });
+			}
+		}
+	}
+
+	const imageCount = imageLocations.length;
+	if (imageCount === 0) {
+		return { imageCount: 0, processed: false, strippedCount: 0 };
+	}
+
+	// Determine which images to strip (all except the N most recent)
+	const stripCount = Math.max(0, imageCount - RECENT_IMAGES_TO_KEEP);
+	if (stripCount === 0) {
+		return { imageCount, processed: false, strippedCount: 0 };
+	}
+
+	const toStrip = imageLocations.slice(0, stripCount);
+
+	// Second pass: replace stripped images with text placeholder.
+	// Process in reverse order to maintain content indices.
+	for (let i = toStrip.length - 1; i >= 0; i--) {
+		const { msgIdx, contentIdx } = toStrip[i];
+		const msg = messages[msgIdx];
+		if (msg.role === "assistant") continue;
+		if (msg.role === "user" && typeof msg.content === "string") continue;
+
+		const contentArr = msg.content as (TextContent | ImageContent)[];
+		const imageBlock = contentArr[contentIdx] as ImageContent;
+		const mimeType = imageBlock.mimeType || "image/unknown";
+
+		// Replace the image block with a text placeholder
+		(contentArr as any[])[contentIdx] = {
+			type: "text",
+			text: `[image removed to reduce context size — was ${mimeType}]`,
+		} as TextContent;
+	}
+
+	return { imageCount, processed: true, strippedCount: stripCount };
+}

package/packages/pi-coding-agent/src/core/index.ts

@@ -29,6 +29,7 @@ export {
 	type ExecResult,
 	type Extension,
 	type ExtensionAPI,
+	type ExtensionManifest,
 	type ExtensionCommandContext,
 	type ExtensionContext,
 	type ExtensionError,
@@ -53,6 +54,11 @@ export {
 	type SessionSwitchEvent,
 	type SessionTreeEvent,
 	type ToolCallEvent,
+	readManifest,
+	readManifestFromEntryPath,
+	type SortResult,
+	type SortWarning,
+	sortExtensionPaths,
 	type ToolDefinition,
 	type ToolRenderResultOptions,
 	type ToolResultEvent,

package/packages/pi-coding-agent/src/core/lsp/index.ts

@@ -340,6 +340,9 @@ async function runWorkspaceDiagnostics(
 	const proc = spawn(cmd, cmdArgs, {
 		cwd,
 		stdio: ["ignore", "pipe", "pipe"],
+		// On Windows, project-type commands (tsc, cargo, etc.) may be .cmd
+		// wrappers that need shell resolution to avoid ENOENT/EINVAL (#2854).
+		shell: process.platform === "win32",
 	});
 	const abortHandler = () => {
 		proc.kill();

package/packages/pi-coding-agent/src/core/lsp/lspmux.ts

@@ -90,6 +90,9 @@ async function checkServerRunning(binaryPath: string): Promise<boolean> {
 	try {
 		const proc = spawn(binaryPath, ["status"], {
 			stdio: ["ignore", "pipe", "pipe"],
+			// On Windows, the binary may be a .cmd wrapper requiring shell
+			// resolution to avoid ENOENT/EINVAL (#2854).
+			shell: process.platform === "win32",
 		});
 
 		const exited = await Promise.race([

package/packages/pi-coding-agent/src/core/messages.test.ts

@@ -0,0 +1,114 @@
+/**
+ * messages.test.ts — Tests for convertToLlm custom message handling.
+ *
+ * Reproduction test for #3026: background job completion notifications
+ * delivered as custom messages must be clearly distinguishable from
+ * user-typed input when converted to LLM messages.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { convertToLlm, type CustomMessage } from "./messages.js";
+
+/** Extract the first content block from a message, asserting array content. */
+function firstTextBlock(msg: ReturnType<typeof convertToLlm>[number]) {
+	const { content } = msg;
+	assert.ok(Array.isArray(content), "Expected content to be an array");
+	const block = content[0];
+	assert.ok(typeof block === "object" && block !== null, "Expected first block to be an object");
+	return block;
+}
+
+test("convertToLlm wraps custom messages with system notification prefix", () => {
+	const customMsg: CustomMessage = {
+		role: "custom",
+		customType: "async_job_result",
+		content: "**Background job done: bg_abc123** (sleep 2, 2.1s)\n\ndone",
+		display: true,
+		timestamp: Date.now(),
+	};
+
+	const result = convertToLlm([customMsg]);
+	assert.equal(result.length, 1);
+	assert.equal(result[0].role, "user");
+
+	// The content must include a system notification wrapper so the LLM
+	// does not confuse it with user input (#3026).
+	const text = firstTextBlock(result[0]);
+	assert.equal(text.type, "text");
+	assert.ok(
+		"text" in text && text.text.includes("[system notification"),
+		"Custom message should be wrapped with system notification marker",
+	);
+});
+
+test("convertToLlm wraps custom messages with array content", () => {
+	const customMsg: CustomMessage = {
+		role: "custom",
+		customType: "bg-shell-status",
+		content: [{ type: "text", text: "Background processes:\n  ✓ bg1 dev-server :3000" }],
+		display: false,
+		timestamp: Date.now(),
+	};
+
+	const result = convertToLlm([customMsg]);
+	assert.equal(result.length, 1);
+	assert.equal(result[0].role, "user");
+
+	const text = firstTextBlock(result[0]);
+	assert.equal(text.type, "text");
+	assert.ok(
+		"text" in text && text.text.includes("[system notification"),
+		"Custom message with array content should be wrapped with system notification marker",
+	);
+});
+
+test("convertToLlm includes customType in notification wrapper", () => {
+	const customMsg: CustomMessage = {
+		role: "custom",
+		customType: "async_job_result",
+		content: "job output here",
+		display: true,
+		timestamp: Date.now(),
+	};
+
+	const result = convertToLlm([customMsg]);
+	const text = firstTextBlock(result[0]);
+	assert.ok(
+		"text" in text && text.text.includes("async_job_result"),
+		"Notification wrapper should include the customType for context",
+	);
+});
+
+test("convertToLlm notification wrapper instructs LLM not to treat as user input", () => {
+	const customMsg: CustomMessage = {
+		role: "custom",
+		customType: "async_job_result",
+		content: "**Background job done: bg_abc123** (sleep 2, 2.1s)\n\ndone",
+		display: true,
+		timestamp: Date.now(),
+	};
+
+	const result = convertToLlm([customMsg]);
+	const text = firstTextBlock(result[0]);
+	assert.ok(
+		"text" in text && text.text.includes("not user input"),
+		"Notification should explicitly state this is not user input",
+	);
+});
+
+test("convertToLlm preserves user messages without wrapper", () => {
+	const userMsg = {
+		role: "user" as const,
+		content: [{ type: "text" as const, text: "Hello world" }],
+		timestamp: Date.now(),
+	};
+
+	const result = convertToLlm([userMsg]);
+	assert.equal(result.length, 1);
+	const text = firstTextBlock(result[0]);
+	assert.ok(
+		"text" in text && text.text === "Hello world",
+		"User messages should pass through unchanged",
+	);
+});