gsd-pi 2.78.0 → 2.78.1-dev.82bcf6b71

package/src/resources/extensions/ollama/index.ts

@@ -119,17 +119,31 @@ export default function ollama(pi: ExtensionAPI) {
 		// In headless/auto mode, await the probe so the fallback resolver can
 		// see Ollama before the first LLM call (#3531 race condition).
 		// In interactive mode, keep it async for fast startup.
+		// Surface probe failures under GSD_DEBUG so users can diagnose silent
+		// "Ollama is missing from /model" reports without patching dist/. The
+		// probe still soft-fails (registration is best-effort) — we just stop
+		// dropping the error on the floor. See #4982.
+		const debugOllama = (where: string, error: unknown): void => {
+			if (process.env.GSD_DEBUG) {
+				const msg = error instanceof Error ? error.message : String(error);
+				process.stderr.write(`[ollama] ${where} probe failed: ${msg}\n`);
+			}
+		};
+
 		if (!ctx.hasUI) {
 			try {
 				await probeAndRegister(pi);
-			} catch { /* non-fatal */ }
+			} catch (error) {
+				debugOllama("headless", error);
+			}
 		} else {
 			probeAndRegister(pi)
 				.then((found) => {
 					ctx.ui.setStatus("ollama", found ? "Ollama" : undefined);
 				})
-				.catch(() => {
+				.catch((error) => {
 					ctx.ui.setStatus("ollama", undefined);
+					debugOllama("interactive", error);
 				});
 		}
 	});

package/src/resources/extensions/ollama/model-capabilities.ts

@@ -56,10 +56,44 @@ const KNOWN_MODELS: Array<[pattern: string, caps: ModelCapability]> = [
 	["llama2", { contextWindow: 4096, maxTokens: 4096, ollamaOptions: { num_ctx: 4096 } }],
 
 	// ─── Qwen family ────────────────────────────────────────────────────
+	// Long-variant entries MUST appear before the bare `qwen3` base —
+	// `baseName.startsWith(pattern)` returns true for `qwen3.5`/`qwen3-coder`/
+	// `qwen3-next` against `qwen3`, and the first match wins (#4991).
+	// ref: qwen3-next 1M ctx — https://qwen.ai/blog?id=qwen3-next
+	["qwen3-next", { contextWindow: 1048576, maxTokens: 32768, ollamaOptions: { num_ctx: 1048576 } }],
+	// ref: qwen3-coder 256K ctx — https://qwenlm.github.io/blog/qwen3-coder/
+	["qwen3-coder", { contextWindow: 262144, maxTokens: 32768, ollamaOptions: { num_ctx: 262144 } }],
+	// ref: qwen3.5 / qwen3.6 1M ctx — Ollama Cloud release notes
+	["qwen3.6", { contextWindow: 1048576, maxTokens: 32768, ollamaOptions: { num_ctx: 1048576 } }],
+	["qwen3.5", { contextWindow: 1048576, maxTokens: 32768, ollamaOptions: { num_ctx: 1048576 } }],
 	["qwen3", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }],
 	["qwen2.5", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }],
 	["qwen2", { contextWindow: 131072, maxTokens: 32768, ollamaOptions: { num_ctx: 131072 } }],
 
+	// ─── GLM family (Z.ai, Ollama Cloud) ────────────────────────────────
+	// ref: glm 4.6 / 5.x 200K ctx — https://docs.z.ai/devpack/using5.1
+	// Long-variant entries before bare `glm-5` / `glm-4` would-be bases to
+	// avoid prefix shadowing (#4991).
+	["glm-5.1", { contextWindow: 204800, maxTokens: 16384, ollamaOptions: { num_ctx: 204800 } }],
+	["glm-5", { contextWindow: 204800, maxTokens: 16384, ollamaOptions: { num_ctx: 204800 } }],
+	["glm-4.6", { contextWindow: 204800, maxTokens: 16384, ollamaOptions: { num_ctx: 204800 } }],
+	["glm-4", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }],
+
+	// ─── Kimi K2 (Moonshot, Ollama Cloud) ──────────────────────────────
+	// ref: kimi-k2 256K ctx — https://platform.moonshot.ai/docs
+	// Same shadowing concern: kimi-k2-thinking and kimi-k2.{5,6} must
+	// match before any future bare `kimi-k2` entry (#4991).
+	["kimi-k2-thinking", { contextWindow: 262144, maxTokens: 16384, ollamaOptions: { num_ctx: 262144 } }],
+	["kimi-k2.6", { contextWindow: 262144, maxTokens: 16384, ollamaOptions: { num_ctx: 262144 } }],
+	["kimi-k2.5", { contextWindow: 262144, maxTokens: 16384, ollamaOptions: { num_ctx: 262144 } }],
+	["kimi-k2", { contextWindow: 262144, maxTokens: 16384, ollamaOptions: { num_ctx: 262144 } }],
+
+	// ─── MiniMax M2 (Ollama Cloud) ─────────────────────────────────────
+	// ref: minimax-m2 1M ctx — https://www.minimax.io/news/minimax-m2
+	["minimax-m2.7", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
+	["minimax-m2.5", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
+	["minimax-m2", { contextWindow: 1048576, maxTokens: 16384, ollamaOptions: { num_ctx: 1048576 } }],
+
 	// ─── Gemma family ───────────────────────────────────────────────────
 	["gemma3", { contextWindow: 131072, maxTokens: 16384, ollamaOptions: { num_ctx: 131072 } }],
 	["gemma2", { contextWindow: 8192, maxTokens: 8192, ollamaOptions: { num_ctx: 8192 } }],

package/src/resources/extensions/ollama/ollama-client.ts

@@ -19,8 +19,45 @@ import type {
 import { parseNDJsonStream } from "./ndjson-stream.js";
 
 const DEFAULT_HOST = "http://localhost:11434";
-const PROBE_TIMEOUT_MS = 1500;
-const REQUEST_TIMEOUT_MS = 10000;
+const DEFAULT_PROBE_TIMEOUT_MS = 1500;
+const DEFAULT_REQUEST_TIMEOUT_MS = 10000;
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+/**
+ * Parse a positive integer from an environment variable, falling back to
+ * `fallback` when the var is unset, empty, non-numeric, zero, or negative.
+ *
+ * Defensive parsing: a typo like `OLLAMA_PROBE_TIMEOUT_MS=abc` or
+ * `OLLAMA_PROBE_TIMEOUT_MS=0` should not silently disable the timeout —
+ * fall back to the documented default instead.
+ */
+export function envPositiveInt(name: string, fallback: number): number {
+	const raw = process.env[name];
+	if (!raw) return fallback;
+	const parsed = Number.parseInt(raw, 10);
+	if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+	return Math.min(parsed, MAX_TIMER_DELAY_MS);
+}
+
+/**
+ * Effective probe timeout for the startup `isRunning()` health check.
+ * Override with `OLLAMA_PROBE_TIMEOUT_MS=<ms>` for slower networks (LAN
+ * Ollama hosts, cloud endpoints, contended cold starts).
+ *
+ * Resolved at call time — tests and downstream callers can mutate
+ * `process.env` between invocations and pick up the new value.
+ */
+export function getProbeTimeoutMs(): number {
+	return envPositiveInt("OLLAMA_PROBE_TIMEOUT_MS", DEFAULT_PROBE_TIMEOUT_MS);
+}
+
+/**
+ * Effective per-request timeout for REST calls. Override with
+ * `OLLAMA_REQUEST_TIMEOUT_MS=<ms>`.
+ */
+export function getRequestTimeoutMs(): number {
+	return envPositiveInt("OLLAMA_REQUEST_TIMEOUT_MS", DEFAULT_REQUEST_TIMEOUT_MS);
+}
 
 /**
  * Get the Ollama host URL from OLLAMA_HOST or default.
@@ -57,7 +94,7 @@ function withAuth(options: RequestInit = {}): RequestInit {
 	};
 }
 
-async function fetchWithTimeout(url: string, options: RequestInit = {}, timeoutMs = REQUEST_TIMEOUT_MS): Promise<Response> {
+async function fetchWithTimeout(url: string, options: RequestInit = {}, timeoutMs = getRequestTimeoutMs()): Promise<Response> {
 	const controller = new AbortController();
 	const timeout = setTimeout(() => controller.abort(), timeoutMs);
 	try {
@@ -77,7 +114,7 @@ export async function isRunning(): Promise<boolean> {
 		const host = getOllamaHost();
 		const isCloud = host.includes("ollama.com") || host.includes("cloud");
 		const probeUrl = isCloud ? `${host}/api/tags` : `${host}/`;
-		const timeout = isCloud ? REQUEST_TIMEOUT_MS : PROBE_TIMEOUT_MS;
+		const timeout = isCloud ? getRequestTimeoutMs() : getProbeTimeoutMs();
 		const response = await fetchWithTimeout(probeUrl, isCloud ? { method: "GET" } : {}, timeout);
 		return response.ok;
 	} catch {

package/src/resources/extensions/ollama/tests/model-capabilities.test.ts

@@ -84,6 +84,102 @@ describe("getModelCapabilities", () => {
 	});
 });
 
+// ─── Ordering / prefix-shadowing regression (#4991) ──────────────────────────
+//
+// The lookup is a linear scan over KNOWN_MODELS using `baseName.startsWith(pattern)`.
+// Cloud and long-variant model names share prefixes with their base families,
+// so the longer entries MUST appear earlier in the table — otherwise a base
+// like `qwen3` shadows `qwen3-coder`/`qwen3-next`/`qwen3.5` and the picker
+// reports the wrong context window. These tests pin the ordering.
+
+describe("getModelCapabilities — long-variant overrides aren't shadowed (#4991)", () => {
+	it("qwen3-coder reports 256K, not the qwen3 131K", () => {
+		const caps = getModelCapabilities("qwen3-coder:480b");
+		assert.equal(caps.contextWindow, 262144);
+		assert.equal(caps.ollamaOptions?.num_ctx, 262144);
+	});
+
+	it("qwen3-coder-next still resolves via the qwen3-coder entry", () => {
+		const caps = getModelCapabilities("qwen3-coder-next");
+		assert.equal(caps.contextWindow, 262144);
+	});
+
+	it("qwen3-next:80b reports 1M, not the qwen3 131K", () => {
+		const caps = getModelCapabilities("qwen3-next:80b");
+		assert.equal(caps.contextWindow, 1048576);
+	});
+
+	it("qwen3.5 / qwen3.6 cloud variants report 1M", () => {
+		assert.equal(getModelCapabilities("qwen3.5:397b").contextWindow, 1048576);
+		assert.equal(getModelCapabilities("qwen3.6:cloud").contextWindow, 1048576);
+	});
+
+	it("base qwen3 still resolves to its 131K entry", () => {
+		const caps = getModelCapabilities("qwen3:8b");
+		assert.equal(caps.contextWindow, 131072);
+	});
+
+	it("glm-5.1:cloud reports 200K", () => {
+		const caps = getModelCapabilities("glm-5.1:cloud");
+		assert.equal(caps.contextWindow, 204800);
+	});
+
+	it("glm-4.6:cloud reports 200K", () => {
+		const caps = getModelCapabilities("glm-4.6:cloud");
+		assert.equal(caps.contextWindow, 204800);
+	});
+
+	it("glm-4 base still resolves to its 131K entry", () => {
+		const caps = getModelCapabilities("glm-4:9b");
+		assert.equal(caps.contextWindow, 131072);
+	});
+
+	it("kimi-k2-thinking reports 256K (not shadowed by kimi-k2)", () => {
+		const caps = getModelCapabilities("kimi-k2-thinking");
+		assert.equal(caps.contextWindow, 262144);
+	});
+
+	it("kimi-k2.5:cloud and kimi-k2.6:cloud both report 256K", () => {
+		assert.equal(getModelCapabilities("kimi-k2.5:cloud").contextWindow, 262144);
+		assert.equal(getModelCapabilities("kimi-k2.6:cloud").contextWindow, 262144);
+	});
+
+	it("kimi-k2 base resolves to 256K", () => {
+		const caps = getModelCapabilities("kimi-k2:cloud");
+		assert.equal(caps.contextWindow, 262144);
+	});
+
+	it("minimax-m2.5:cloud and minimax-m2.7:cloud report 1M", () => {
+		assert.equal(getModelCapabilities("minimax-m2.5:cloud").contextWindow, 1048576);
+		assert.equal(getModelCapabilities("minimax-m2.7:cloud").contextWindow, 1048576);
+	});
+
+	it("minimax-m2 base resolves to 1M", () => {
+		const caps = getModelCapabilities("minimax-m2:cloud");
+		assert.equal(caps.contextWindow, 1048576);
+	});
+
+	it("ollamaOptions.num_ctx mirrors contextWindow for all new entries", () => {
+		// Inference time: num_ctx is what gets sent to Ollama on each chat.
+		// If contextWindow is right but num_ctx is stale, the model still
+		// gets truncated. Pin both sides.
+		for (const name of [
+			"qwen3-next:80b",
+			"qwen3-coder:480b",
+			"glm-5.1:cloud",
+			"kimi-k2-thinking",
+			"minimax-m2.7:cloud",
+		]) {
+			const caps = getModelCapabilities(name);
+			assert.equal(
+				caps.ollamaOptions?.num_ctx,
+				caps.contextWindow,
+				`${name}: num_ctx (${caps.ollamaOptions?.num_ctx}) must equal contextWindow (${caps.contextWindow})`,
+			);
+		}
+	});
+});
+
 // ─── estimateContextFromParams ───────────────────────────────────────────────
 
 describe("estimateContextFromParams", () => {

package/src/resources/extensions/ollama/tests/ollama-client-timeout-env.test.ts

@@ -0,0 +1,147 @@
+// GSD2 — Tests for OLLAMA_PROBE_TIMEOUT_MS / OLLAMA_REQUEST_TIMEOUT_MS env vars (#5003 / #4982)
+//
+// Pinned defaults: 1500 ms probe, 10 000 ms request. The defaults must be
+// preserved when the env var is unset, empty, non-numeric, zero, or negative
+// so a typo or fat-fingered value can't silently disable the timeout. When
+// the env var is set to a valid positive integer it overrides the default.
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+	envPositiveInt,
+	getProbeTimeoutMs,
+	getRequestTimeoutMs,
+	MAX_TIMER_DELAY_MS,
+} from "../ollama-client.js";
+
+const PROBE_VAR = "OLLAMA_PROBE_TIMEOUT_MS";
+const REQUEST_VAR = "OLLAMA_REQUEST_TIMEOUT_MS";
+
+function withEnv(name: string, value: string | undefined, run: () => void): void {
+	const prior = process.env[name];
+	if (value === undefined) {
+		delete process.env[name];
+	} else {
+		process.env[name] = value;
+	}
+	try {
+		run();
+	} finally {
+		if (prior === undefined) {
+			delete process.env[name];
+		} else {
+			process.env[name] = prior;
+		}
+	}
+}
+
+describe("envPositiveInt — defensive fallback", () => {
+	it("returns fallback when var is unset", () => {
+		withEnv("__GSD_TEST_INT__", undefined, () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 42);
+		});
+	});
+
+	it("returns fallback when var is empty string", () => {
+		withEnv("__GSD_TEST_INT__", "", () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 42);
+		});
+	});
+
+	it("returns fallback when var is non-numeric", () => {
+		withEnv("__GSD_TEST_INT__", "abc", () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 42);
+		});
+	});
+
+	it("returns fallback when var is zero (would silently disable timeout)", () => {
+		withEnv("__GSD_TEST_INT__", "0", () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 42);
+		});
+	});
+
+	it("returns fallback when var is negative", () => {
+		withEnv("__GSD_TEST_INT__", "-100", () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 42);
+		});
+	});
+
+	it("returns parsed value when var is a positive integer", () => {
+		withEnv("__GSD_TEST_INT__", "5000", () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 5000);
+		});
+	});
+
+	it("parses leading digits and discards trailing junk (parseInt semantics)", () => {
+		withEnv("__GSD_TEST_INT__", "1500ms", () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), 1500);
+		});
+	});
+
+	it("clamps values above MAX_TIMER_DELAY_MS to prevent setTimeout overflow", () => {
+		withEnv("__GSD_TEST_INT__", String(MAX_TIMER_DELAY_MS + 1), () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), MAX_TIMER_DELAY_MS);
+		});
+	});
+
+	it("accepts MAX_TIMER_DELAY_MS exactly", () => {
+		withEnv("__GSD_TEST_INT__", String(MAX_TIMER_DELAY_MS), () => {
+			assert.equal(envPositiveInt("__GSD_TEST_INT__", 42), MAX_TIMER_DELAY_MS);
+		});
+	});
+});
+
+describe("getProbeTimeoutMs — OLLAMA_PROBE_TIMEOUT_MS override", () => {
+	beforeEach(() => {
+		delete process.env[PROBE_VAR];
+	});
+	afterEach(() => {
+		delete process.env[PROBE_VAR];
+	});
+
+	it("defaults to 1500 ms when unset", () => {
+		assert.equal(getProbeTimeoutMs(), 1500);
+	});
+
+	it("honours a positive override", () => {
+		process.env[PROBE_VAR] = "5000";
+		assert.equal(getProbeTimeoutMs(), 5000);
+	});
+
+	it("falls back to 1500 ms on a zero override (typo guard)", () => {
+		process.env[PROBE_VAR] = "0";
+		assert.equal(getProbeTimeoutMs(), 1500);
+	});
+
+	it("re-reads the env var on every call", () => {
+		process.env[PROBE_VAR] = "2000";
+		assert.equal(getProbeTimeoutMs(), 2000);
+		process.env[PROBE_VAR] = "8000";
+		assert.equal(getProbeTimeoutMs(), 8000);
+		delete process.env[PROBE_VAR];
+		assert.equal(getProbeTimeoutMs(), 1500);
+	});
+});
+
+describe("getRequestTimeoutMs — OLLAMA_REQUEST_TIMEOUT_MS override", () => {
+	beforeEach(() => {
+		delete process.env[REQUEST_VAR];
+	});
+	afterEach(() => {
+		delete process.env[REQUEST_VAR];
+	});
+
+	it("defaults to 10 000 ms when unset", () => {
+		assert.equal(getRequestTimeoutMs(), 10000);
+	});
+
+	it("honours a positive override", () => {
+		process.env[REQUEST_VAR] = "30000";
+		assert.equal(getRequestTimeoutMs(), 30000);
+	});
+
+	it("falls back to 10 000 ms on non-numeric input", () => {
+		process.env[REQUEST_VAR] = "thirty-seconds";
+		assert.equal(getRequestTimeoutMs(), 10000);
+	});
+});

package/src/resources/extensions/slash-commands/create-extension.ts

@@ -221,41 +221,38 @@ function sendPrompt(description: string, result: RoundResult, pi: ExtensionAPI):
 		: "";
 
 	const docHints: string[] = [
-		"- `~/.gsd/agent/docs/extending-pi/01-what-are-extensions.md` — capabilities overview",
-		"- `~/.gsd/agent/docs/extending-pi/03-getting-started.md` — minimal extension, hot reload",
-		"- `~/.gsd/agent/docs/extending-pi/08-extensioncontext-what-you-can-access.md` — ExtensionContext API",
-		"- `~/.gsd/agent/docs/extending-pi/09-extensionapi-what-you-can-do.md` — ExtensionAPI: registration, messaging",
-		"- `~/.gsd/agent/docs/extending-pi/22-key-rules-gotchas.md` — must-read rules before shipping",
+		"- `docs/extension-sdk/README.md` — overview, quick start, directory layout",
+		"- `docs/extension-sdk/api-reference.md` — ExtensionAPI and ExtensionContext surfaces",
+		"- `docs/extension-sdk/building-extensions.md` — tools, commands, events, UI, state",
+		"- `docs/extension-sdk/rules.md` — non-negotiable rules and gotchas",
 	];
 
 	if (uiSelected.includes("custom component")) {
-		docHints.push("- `~/.gsd/agent/docs/extending-pi/12-custom-ui-visual-components.md` — dialogs, widgets, overlays");
-		docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md` — ctx.ui.custom() API");
-		docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md` — Text, Box, SelectList");
-		docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md` — Key, matchesKey");
-		docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md` — truncation, width rules");
-		docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md` — step-by-step guide");
-		docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md` — pitfalls");
+		docHints.push("- `docs/extension-sdk/building-extensions.md#custom-components` — ctx.ui.custom() API");
+		docHints.push("- `docs/dev/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md` — step-by-step component guide");
+		docHints.push("- `docs/dev/pi-ui-tui/07-built-in-components-the-building-blocks.md` — Text, Box, SelectList");
+		docHints.push("- `docs/dev/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md` — Key, matchesKey");
+		docHints.push("- `docs/dev/pi-ui-tui/10-line-width-the-cardinal-rule.md` — truncation, width rules");
 	} else if (uiSelected.includes("Dialogs")) {
-		docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/04-built-in-dialog-methods.md` — select, confirm, input, editor");
+		docHints.push("- `docs/extension-sdk/building-extensions.md#built-in-dialogs` — select, confirm, input");
 	} else if (uiSelected.includes("Status")) {
-		docHints.push("- `~/.gsd/agent/docs/pi-ui-tui/05-persistent-ui-elements.md` — status, widgets, footer, header");
+		docHints.push("- `docs/extension-sdk/building-extensions.md#persistent-ui-elements` — status, widgets");
 	}
 
 	if (uiSelected.includes("tool") || result.answers["purpose"]) {
-		docHints.push("- `~/.gsd/agent/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md` — renderCall / renderResult");
+		docHints.push("- `docs/dev/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md` — renderCall / renderResult");
 	}
 
 	if (eventsSelected && !eventsSelected.includes("standalone")) {
-		docHints.push("- `~/.gsd/agent/docs/extending-pi/07-events-the-nervous-system.md` — all events reference");
+		docHints.push("- `docs/dev/extending-pi/07-events-the-nervous-system.md` — all events reference");
 	}
 
 	if (eventsSelected.includes("context / prompt")) {
-		docHints.push("- `~/.gsd/agent/docs/extending-pi/15-system-prompt-modification.md` — system prompt hooks");
+		docHints.push("- `docs/dev/extending-pi/15-system-prompt-modification.md` — system prompt hooks");
 	}
 
 	if (persistenceSelected.includes("session")) {
-		docHints.push("- `~/.gsd/agent/docs/extending-pi/13-state-management-persistence.md` — pi.appendEntry, session state");
+		docHints.push("- `docs/extension-sdk/building-extensions.md#state-management` — state reconstruction, appendEntry");
 	}
 
 	const prompt = `Create a new pi extension based on this description:
@@ -270,13 +267,30 @@ ${docHints.join("\n")}
 
 ## Output
 
-Write the complete implementation as a single self-contained extension file:
-
-\`~/.gsd/agent/extensions/<kebab-case-name>.ts\`
-
-Then register it in the main extensions index:
+Write the complete implementation as a directory-based extension:
+
+\`~/.gsd/agent/extensions/<kebab-case-name>/index.ts\`
+\`~/.gsd/agent/extensions/<kebab-case-name>/extension-manifest.json\`
+
+The manifest must follow this format:
+\`\`\`json
+{
+  "id": "<kebab-case-name>",
+  "name": "<Human Name>",
+  "version": "1.0.0",
+  "description": "<one-line description>",
+  "tier": "community",
+  "requires": { "platform": ">=2.29.0" },
+  "provides": {
+    "tools": ["<tool_names_registered>"],
+    "commands": ["<command_names_registered>"],
+    "hooks": ["<event_names_subscribed>"],
+    "shortcuts": ["<shortcut_keys_registered>"]
+  }
+}
+\`\`\`
 
-\`~/.gsd/agent/extensions/index.ts\` — import and call the new extension's default export alongside existing ones
+Only include non-empty arrays in \`provides\`. See \`docs/extension-sdk/manifest-spec.md\` for the full spec.
 
 ## Rules you must follow exactly