gsd-pi 2.57.0-dev.f22a903 → 2.58.0-dev.778d6ac

package/src/resources/extensions/shared/tests/ask-user-freetext.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Tests for ask-user-questions free-text input behavior.
+ *
+ * Bug #2715: The ask-user-questions UI lacks free-text input and can trap
+ * users in a loop when the agent needs an explanation rather than a fixed
+ * choice.
+ *
+ * These tests exercise the RPC fallback path (ctx.ui.select) in
+ * ask-user-questions.ts to ensure that selecting "None of the above"
+ * triggers a follow-up free-text input prompt via ctx.ui.input().
+ */
+
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+// The ask-user-questions extension registers a tool via pi.registerTool().
+// We capture that registration and call execute() directly with a mock context.
+import AskUserQuestions from "../../ask-user-questions.js";
+
+interface CapturedTool {
+	name: string;
+	execute: (...args: any[]) => Promise<any>;
+}
+
+function captureTool(): CapturedTool {
+	let captured: CapturedTool | null = null;
+	const fakePi = {
+		registerTool(tool: any) {
+			captured = { name: tool.name, execute: tool.execute };
+		},
+	};
+	AskUserQuestions(fakePi as any);
+	if (!captured) throw new Error("No tool registered");
+	return captured;
+}
+
+function makeQuestion(id: string, options: string[]) {
+	return {
+		id,
+		header: id,
+		question: `Pick for ${id}`,
+		options: options.map((label) => ({ label, description: `Desc for ${label}` })),
+	};
+}
+
+function makeMockCtx(opts: {
+	selectReturns: (string | string[] | undefined)[];
+	inputReturns?: (string | undefined)[];
+}) {
+	let selectCallIdx = 0;
+	let inputCallIdx = 0;
+	const selectCalls: { title: string; options: string[] }[] = [];
+	const inputCalls: { title: string; placeholder?: string }[] = [];
+
+	return {
+		ctx: {
+			hasUI: true,
+			ui: {
+				custom: () => undefined, // force RPC fallback
+				select: async (title: string, options: string[], selectOpts?: any) => {
+					selectCalls.push({ title, options });
+					return opts.selectReturns[selectCallIdx++];
+				},
+				input: async (title: string, placeholder?: string) => {
+					inputCalls.push({ title, placeholder });
+					return (opts.inputReturns ?? [])[inputCallIdx++];
+				},
+			},
+		},
+		selectCalls,
+		inputCalls,
+	};
+}
+
+describe("ask-user-questions RPC fallback free-text", () => {
+	it("prompts for free-text input when user selects 'None of the above'", async () => {
+		const tool = captureTool();
+		const { ctx, selectCalls, inputCalls } = makeMockCtx({
+			selectReturns: ["None of the above"],
+			inputReturns: ["I need to explain my reasoning"],
+		});
+
+		const params = {
+			questions: [makeQuestion("q1", ["Option A", "Option B"])],
+		};
+
+		const result = await tool.execute("call-1", params, undefined, undefined, ctx);
+
+		// The select should have been called with "None of the above" appended
+		assert.equal(selectCalls.length, 1);
+		assert.ok(
+			selectCalls[0].options.includes("None of the above"),
+			"select options should include 'None of the above'",
+		);
+
+		// A follow-up input() call should have been made to collect free text
+		assert.equal(inputCalls.length, 1, "should call ctx.ui.input() for free-text after 'None of the above'");
+
+		// The result should include the user's free-text note
+		const text = result.content[0]?.text;
+		assert.ok(text, "result should have text content");
+		const parsed = JSON.parse(text);
+		assert.ok(
+			parsed.answers.q1,
+			"answer for q1 should exist",
+		);
+		const q1Answers = parsed.answers.q1.answers;
+		assert.ok(
+			q1Answers.some((a: string) => a.includes("I need to explain my reasoning")),
+			"answer should include the free-text explanation",
+		);
+	});
+
+	it("does NOT prompt for free-text when user selects a normal option", async () => {
+		const tool = captureTool();
+		const { ctx, inputCalls } = makeMockCtx({
+			selectReturns: ["Option A"],
+		});
+
+		const params = {
+			questions: [makeQuestion("q1", ["Option A", "Option B"])],
+		};
+
+		const result = await tool.execute("call-2", params, undefined, undefined, ctx);
+
+		// No input() call should have been made
+		assert.equal(inputCalls.length, 0, "should NOT call ctx.ui.input() for a normal option");
+
+		const text = result.content[0]?.text;
+		const parsed = JSON.parse(text);
+		assert.deepStrictEqual(parsed.answers.q1.answers, ["Option A"]);
+	});
+
+	it("handles cancelled free-text input gracefully", async () => {
+		const tool = captureTool();
+		const { ctx, inputCalls } = makeMockCtx({
+			selectReturns: ["None of the above"],
+			inputReturns: [undefined], // user cancelled the input
+		});
+
+		const params = {
+			questions: [makeQuestion("q1", ["Option A", "Option B"])],
+		};
+
+		const result = await tool.execute("call-3", params, undefined, undefined, ctx);
+
+		// Input should still have been called
+		assert.equal(inputCalls.length, 1, "should call ctx.ui.input() even if user cancels");
+
+		// Result should still contain "None of the above" without a note
+		const text = result.content[0]?.text;
+		assert.ok(text, "result should have text content");
+		const parsed = JSON.parse(text);
+		assert.deepStrictEqual(parsed.answers.q1.answers, ["None of the above"]);
+	});
+});

package/src/resources/skills/create-gsd-extension/SKILL.md

@@ -7,9 +7,11 @@ description: Create, debug, and iterate on GSD extensions (TypeScript modules th
 
 **Extensions are TypeScript modules** that hook into GSD's runtime (built on pi). They export a default function receiving `ExtensionAPI` and use it to subscribe to events, register tools/commands/shortcuts, and interact with the session.
 
-**GSD extension paths:**
-- Global extensions: `~/.gsd/agent/extensions/*.ts` or `~/.gsd/agent/extensions/*/index.ts`
-- Project-local extensions: `.gsd/extensions/*.ts` or `.gsd/extensions/*/index.ts`
+**GSD extension paths (community/user-installed extensions):**
+- Global: `~/.pi/agent/extensions/*.ts` or `~/.pi/agent/extensions/*/index.ts`
+- Project-local: `.gsd/extensions/*.ts` or `.gsd/extensions/*/index.ts`
+
+Note: `~/.gsd/agent/extensions/` is reserved for bundled extensions synced from the gsd-pi package. Community extensions placed there are silently ignored by the loader.
 
 **The three primitives:**
 1. **Events** — Listen and react (`pi.on("event", handler)`). Can block tool calls, modify messages, inject context.

package/src/resources/skills/create-gsd-extension/references/key-rules-gotchas.md

@@ -26,11 +26,12 @@ Non-negotiable rules and common gotchas when building GSD extensions.
 </common_patterns>
 
 <gsd_paths>
-**GSD extension paths:**
-- Global: `~/.gsd/agent/extensions/*.ts`
-- Global (subdir): `~/.gsd/agent/extensions/*/index.ts`
+**GSD extension paths (community/user-installed extensions):**
+- Global: `~/.pi/agent/extensions/*.ts`
+- Global (subdir): `~/.pi/agent/extensions/*/index.ts`
 - Project-local: `.gsd/extensions/*.ts`
 - Project-local (subdir): `.gsd/extensions/*/index.ts`
 
-The upstream pi docs reference `~/.pi` paths — GSD uses `~/.gsd` everywhere instead.
+Note: `~/.gsd/agent/extensions/` is reserved for bundled extensions synced from the gsd-pi package.
+Community extensions placed there are silently ignored by the loader.
 </gsd_paths>

package/src/resources/skills/create-gsd-extension/workflows/add-capability.md

@@ -14,7 +14,7 @@ Read the reference file for the specific capability being added:
 ## Step 1: Identify the Extension
 
 Locate the existing extension file. Check:
-- `~/.gsd/agent/extensions/` (global)
+- `~/.pi/agent/extensions/` (global community extensions)
 - `.gsd/extensions/` (project-local)
 
 Read the current extension code to understand its structure.
@@ -28,7 +28,7 @@ If the extension needs new imports, add them at the top of the file.
 ## Step 3: Handle Structural Changes
 
 **Single file → Directory**: If the extension is outgrowing a single file:
-1. Create `~/.gsd/agent/extensions/my-extension/`
+1. Create `~/.pi/agent/extensions/my-extension/`
 2. Move the file to `index.ts`
 3. Extract helpers to separate files
 

package/src/resources/skills/create-gsd-extension/workflows/create-extension.md

@@ -12,7 +12,7 @@
 ## Step 1: Determine Scope and Placement
 
 Ask the user:
-- **Global** (`~/.gsd/agent/extensions/`) — Available in all GSD sessions
+- **Global** (`~/.pi/agent/extensions/`) — Available in all GSD sessions
 - **Project-local** (`.gsd/extensions/`) — Available only in this project
 
 ## Step 2: Determine Extension Capabilities
@@ -36,12 +36,12 @@ Identify what the extension needs from the user's description:
 
 **Single file** — for small extensions (1-2 tools/commands, simple hooks):
 ```
-~/.gsd/agent/extensions/my-extension.ts
+~/.pi/agent/extensions/my-extension.ts
 ```
 
 **Directory with index.ts** — for multi-file extensions:
 ```
-~/.gsd/agent/extensions/my-extension/
+~/.pi/agent/extensions/my-extension/
 ├── index.ts
 ├── tools.ts
 └── utils.ts
@@ -49,7 +49,7 @@ Identify what the extension needs from the user's description:
 
 **Package with dependencies** — when npm packages are needed:
 ```
-~/.gsd/agent/extensions/my-extension/
+~/.pi/agent/extensions/my-extension/
 ├── package.json
 ├── src/index.ts
 └── node_modules/

package/src/resources/skills/create-gsd-extension/workflows/debug-extension.md

@@ -32,12 +32,14 @@ gsd -e ./path/to/extension.ts
 
 ## Step 3: Verify File Location
 
-Extensions must be in auto-discovery paths:
-- `~/.gsd/agent/extensions/*.ts`
-- `~/.gsd/agent/extensions/*/index.ts`
+Community extensions must be in auto-discovery paths:
+- `~/.pi/agent/extensions/*.ts`
+- `~/.pi/agent/extensions/*/index.ts`
 - `.gsd/extensions/*.ts`
 - `.gsd/extensions/*/index.ts`
 
+Note: `~/.gsd/agent/extensions/` is reserved for bundled extensions synced from the gsd-pi package.
+
 The file must `export default function(pi: ExtensionAPI) { ... }`.
 
 ## Step 4: Check for Common Mistakes