gsd-pi 2.18.0 → 2.20.0

package/README.md

@@ -7,6 +7,7 @@
 [![npm version](https://img.shields.io/npm/v/gsd-pi?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsd-pi)
 [![npm downloads](https://img.shields.io/npm/dm/gsd-pi?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsd-pi)
 [![GitHub stars](https://img.shields.io/github/stars/gsd-build/GSD-2?style=for-the-badge&logo=github&color=181717)](https://github.com/gsd-build/GSD-2)
+[![Discord](https://img.shields.io/badge/Discord-Join%20us-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/gsd)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
 
 The original GSD went viral as a prompt framework for Claude Code. It worked, but it was fighting the tool — injecting prompts through slash commands, hoping the LLM would follow instructions, with no actual control over context windows, sessions, or execution.
@@ -231,6 +232,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd`                  | Step mode — executes one unit at a time, pauses between each    |
 | `/gsd next`             | Explicit step mode (same as bare `/gsd`)                        |
 | `/gsd auto`             | Autonomous mode — researches, plans, executes, commits, repeats |
+| `/gsd quick`            | Execute a quick task with GSD guarantees, skip planning overhead |
 | `/gsd stop`             | Stop auto mode gracefully                                       |
 | `/gsd steer`            | Hard-steer plan documents during execution                      |
 | `/gsd discuss`          | Discuss architecture and decisions (works alongside auto mode)  |
@@ -238,7 +240,9 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd queue`            | Queue future milestones (safe during auto mode)                 |
 | `/gsd prefs`            | Model selection, timeouts, budget ceiling                       |
 | `/gsd migrate`          | Migrate a v1 `.planning` directory to `.gsd` format             |
-| `/gsd doctor`           | Validate `.gsd/` integrity, find and fix issues                 |
+| `/gsd help`             | Categorized command reference for all GSD subcommands           |
+| `/gsd mode`             | Switch workflow mode (solo/team) with coordinated defaults      |
+| `/gsd doctor`           | Runtime health checks with auto-fix for common issues           |
 | `/worktree` (`/wt`)     | Git worktree lifecycle — create, switch, merge, remove          |
 | `/voice`                | Toggle real-time speech-to-text (macOS, Linux)                  |
 | `/exit`                 | Graceful shutdown — saves session state before exiting          |

package/dist/cli.js

@@ -105,8 +105,10 @@ ensureManagedTools(join(agentDir, 'bin'));
 const authStorage = AuthStorage.create(authFilePath);
 loadStoredEnvKeys(authStorage);
 migratePiCredentials(authStorage);
+const modelRegistry = new ModelRegistry(authStorage);
+const settingsManager = SettingsManager.create(agentDir);
 // Run onboarding wizard on first launch (no LLM provider configured)
-if (!isPrintMode && shouldRunOnboarding(authStorage)) {
+if (!isPrintMode && shouldRunOnboarding(authStorage, settingsManager.getDefaultProvider())) {
     await runOnboarding(authStorage);
     // Clean up stdin state left by @clack/prompts.
     // readline.emitKeypressEvents() adds a permanent data listener and
@@ -126,8 +128,6 @@ if (!isPrintMode) {
 if (!isPrintMode && process.stdout.columns && process.stdout.columns < 40) {
     process.stderr.write(chalk.yellow(`[gsd] Terminal width is ${process.stdout.columns} columns (minimum recommended: 40). Output may be unreadable.\n`));
 }
-const modelRegistry = new ModelRegistry(authStorage);
-const settingsManager = SettingsManager.create(agentDir);
 // --list-models: print available models and exit (no TTY needed)
 if (cliFlags.listModels !== undefined) {
     const models = modelRegistry.getAvailable();

package/dist/onboarding.d.ts

@@ -19,9 +19,11 @@ import type { AuthStorage } from '@gsd/pi-coding-agent';
  *
  * Returns false (skip wizard) when:
  * - Any LLM provider is already available via auth.json, env vars, runtime overrides, or fallback auth
+ * - A default provider is already configured in settings (covers extension-based providers
+ *   that may not require credentials in auth.json)
  * - Not a TTY (piped input, subagent, CI)
  */
-export declare function shouldRunOnboarding(authStorage: AuthStorage): boolean;
+export declare function shouldRunOnboarding(authStorage: AuthStorage, settingsDefaultProvider?: string): boolean;
 /**
  * Run the unified onboarding wizard.
  *

package/dist/onboarding.js

@@ -113,11 +113,15 @@ function isCancelError(p, err) {
  *
  * Returns false (skip wizard) when:
  * - Any LLM provider is already available via auth.json, env vars, runtime overrides, or fallback auth
+ * - A default provider is already configured in settings (covers extension-based providers
+ *   that may not require credentials in auth.json)
  * - Not a TTY (piped input, subagent, CI)
  */
-export function shouldRunOnboarding(authStorage) {
+export function shouldRunOnboarding(authStorage, settingsDefaultProvider) {
     if (!process.stdin.isTTY)
         return false;
+    if (settingsDefaultProvider)
+        return false;
     // Check if any LLM provider has credentials
     const hasLlmAuth = LLM_PROVIDER_IDS.some(id => authStorage.hasAuth(id));
     return !hasLlmAuth;
@@ -564,12 +568,13 @@ async function runRemoteQuestionsStep(p, pc, authStorage) {
     // Check existing config
     const hasDiscord = authStorage.has('discord_bot') && !!authStorage.get('discord_bot')?.key;
     const hasSlack = authStorage.has('slack_bot') && !!authStorage.get('slack_bot')?.key;
-    const existingChannel = hasDiscord ? 'Discord' : hasSlack ? 'Slack' : null;
+    const hasTelegram = authStorage.has('telegram_bot') && !!authStorage.get('telegram_bot')?.key;
+    const existingChannel = hasDiscord ? 'Discord' : hasSlack ? 'Slack' : hasTelegram ? 'Telegram' : null;
     const options = [];
     if (existingChannel) {
         options.push({ value: 'keep', label: `Keep current (${existingChannel})`, hint: 'already configured' });
     }
-    options.push({ value: 'discord', label: 'Discord', hint: 'receive questions in a Discord channel' }, { value: 'slack', label: 'Slack', hint: 'receive questions in a Slack channel' }, { value: 'skip', label: 'Skip for now', hint: 'use /gsd remote inside GSD later' });
+    options.push({ value: 'discord', label: 'Discord', hint: 'receive questions in a Discord channel' }, { value: 'slack', label: 'Slack', hint: 'receive questions in a Slack channel' }, { value: 'telegram', label: 'Telegram', hint: 'receive questions via Telegram bot' }, { value: 'skip', label: 'Skip for now', hint: 'use /gsd remote inside GSD later' });
     const choice = await p.select({
         message: 'Set up remote questions? (get notified when GSD needs input)',
         options,
@@ -638,6 +643,74 @@ async function runRemoteQuestionsStep(p, pc, authStorage) {
         p.log.success(`Slack channel: ${pc.green(channelId.trim())}`);
         return 'Slack';
     }
+    if (choice === 'telegram') {
+        const token = await p.password({
+            message: 'Paste your Telegram bot token (from @BotFather):',
+            mask: '●',
+        });
+        if (p.isCancel(token) || !token?.trim())
+            return null;
+        const trimmed = token.trim();
+        if (!/^\d+:[A-Za-z0-9_-]+$/.test(trimmed)) {
+            p.log.warn('Invalid token format — Telegram bot tokens look like 123456789:ABCdefGHI...');
+            return null;
+        }
+        // Validate
+        const s = p.spinner();
+        s.start('Validating Telegram bot token...');
+        try {
+            const res = await fetch(`https://api.telegram.org/bot${trimmed}/getMe`, {
+                signal: AbortSignal.timeout(15_000),
+            });
+            const data = await res.json();
+            if (!data?.ok || !data?.result?.id) {
+                s.stop('Telegram token validation failed');
+                return null;
+            }
+            s.stop(`Telegram bot: ${pc.green(data.result.first_name ?? data.result.username ?? 'bot')}`);
+        }
+        catch {
+            s.stop('Could not reach Telegram API');
+            return null;
+        }
+        authStorage.set('telegram_bot', { type: 'api_key', key: trimmed });
+        process.env.TELEGRAM_BOT_TOKEN = trimmed;
+        const chatId = await p.text({
+            message: 'Paste the Telegram chat ID (e.g. -1001234567890):',
+            validate: (val) => {
+                if (!val || !/^-?\d{5,20}$/.test(val.trim()))
+                    return 'Expected a numeric chat ID (can be negative for groups)';
+            },
+        });
+        if (p.isCancel(chatId) || !chatId)
+            return null;
+        const trimmedChatId = chatId.trim();
+        // Test send
+        const ts = p.spinner();
+        ts.start('Testing message delivery...');
+        try {
+            const res = await fetch(`https://api.telegram.org/bot${trimmed}/sendMessage`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ chat_id: trimmedChatId, text: 'GSD remote questions connected.' }),
+                signal: AbortSignal.timeout(15_000),
+            });
+            const data = await res.json();
+            if (!data?.ok) {
+                ts.stop(`Could not send to chat: ${data?.description ?? 'unknown error'}`);
+                return null;
+            }
+            ts.stop('Test message sent');
+        }
+        catch {
+            ts.stop('Could not reach Telegram API');
+            return null;
+        }
+        const { saveRemoteQuestionsConfig } = await import('./remote-questions-config.js');
+        saveRemoteQuestionsConfig('telegram', trimmedChatId);
+        p.log.success(`Telegram chat: ${pc.green(trimmedChatId)}`);
+        return 'Telegram';
+    }
     return null;
 }
 async function runDiscordChannelStep(p, pc, token) {
@@ -756,6 +829,7 @@ export function loadStoredEnvKeys(authStorage) {
         ['jina', 'JINA_API_KEY'],
         ['slack_bot', 'SLACK_BOT_TOKEN'],
         ['discord_bot', 'DISCORD_BOT_TOKEN'],
+        ['telegram_bot', 'TELEGRAM_BOT_TOKEN'],
         ['groq', 'GROQ_API_KEY'],
         ['ollama-cloud', 'OLLAMA_API_KEY'],
         ['custom-openai', 'CUSTOM_OPENAI_API_KEY'],

package/dist/remote-questions-config.d.ts

@@ -7,4 +7,4 @@
  * but onboarding.ts is compiled by tsc — dynamic imports from compiled
  * JS to uncompiled .ts fail at runtime (#592).
  */
-export declare function saveRemoteQuestionsConfig(channel: "slack" | "discord", channelId: string): void;
+export declare function saveRemoteQuestionsConfig(channel: "slack" | "discord" | "telegram", channelId: string): void;

package/dist/resources/extensions/google-search/index.ts

@@ -68,6 +68,101 @@ async function getClient(): Promise<GoogleGenAIClient> {
 	return client;
 }
 
+/**
+ * Perform a search using OAuth credentials via the Cloud Code Assist API.
+ * This is used as a fallback when GEMINI_API_KEY is not set.
+ */
+async function searchWithOAuth(
+	query: string,
+	accessToken: string,
+	projectId: string,
+	signal?: AbortSignal,
+): Promise<SearchResult> {
+	const model = process.env.GEMINI_SEARCH_MODEL || "gemini-2.5-flash";
+	const url = `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent`;
+
+	const GEMINI_CLI_HEADERS = {
+	        ideType: "IDE_UNSPECIFIED",
+	        platform: "PLATFORM_UNSPECIFIED",
+	        pluginType: "GEMINI",
+	};
+
+	const executeFetch = async (retries = 3): Promise<Response> => {
+	        const response = await fetch(url, {
+	                method: "POST",
+	                headers: {
+	                        Authorization: `Bearer ${accessToken}`,
+	                        "Content-Type": "application/json",
+	                        "User-Agent": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+	                        "X-Goog-Api-Client": "gl-node/22.17.0",
+	                        "Client-Metadata": JSON.stringify(GEMINI_CLI_HEADERS),
+	                },
+	                body: JSON.stringify({
+	                        project: projectId,
+	                        model,
+	                        request: {
+	                                contents: [{ parts: [{ text: query }] }],
+	                                tools: [{ googleSearch: {} }],
+	                        },
+	                }),
+	                signal,
+	        });
+
+	        if (!response.ok && retries > 0 && (response.status === 429 || response.status >= 500)) {
+	                await new Promise((resolve) => setTimeout(resolve, 1000 * (4 - retries)));
+	                return executeFetch(retries - 1);
+	        }
+
+	        return response;
+	};
+
+	const response = await executeFetch();
+
+	if (!response.ok) {
+	        const errorText = await response.text();
+	        throw new Error(`Cloud Code Assist API error (${response.status}): ${errorText}`);
+	}
+
+	// Note: streamGenerateContent returns SSE; for now, we consume all chunks.
+	// For simplicity and to match the previous structure, we'll read to end.
+	const text = await response.text();
+	const jsonLines = text.split("\n")
+	        .filter(l => l.startsWith("data:"))
+	        .map(l => l.slice(5).trim())
+	        .filter(l => l.length > 0);
+
+	let data;
+	if (jsonLines.length > 0) {
+	    // Aggregate chunks if needed, but for now we take the last chunk or assume it's one
+	    data = JSON.parse(jsonLines[jsonLines.length - 1]);
+	} else {
+	    data = JSON.parse(text);
+	}	const candidate = data.response?.candidates?.[0];
+	const answer = candidate?.content?.parts?.find((p: any) => p.text)?.text ?? "";
+	const grounding = candidate?.groundingMetadata;
+
+	const sources: SearchSource[] = [];
+	const seenTitles = new Set<string>();
+	if (grounding?.groundingChunks) {
+		for (const chunk of grounding.groundingChunks) {
+			if (chunk.web) {
+				const title = chunk.web.title ?? "Untitled";
+				if (seenTitles.has(title)) continue;
+				seenTitles.add(title);
+				const domain = chunk.web.domain ?? title;
+				sources.push({
+					title,
+					uri: chunk.web.uri ?? "",
+					domain,
+				});
+			}
+		}
+	}
+
+	const searchQueries = grounding?.webSearchQueries ?? [];
+	return { answer, sources, searchQueries, cached: false };
+}
+
 // ── In-session cache ─────────────────────────────────────────────────────────
 
 const resultCache = new Map<string, SearchResult>();
@@ -87,7 +182,7 @@ export default function (pi: ExtensionAPI) {
 			"Returns an AI-synthesized answer grounded in Google Search results, plus source URLs. " +
 			"Use this when you need current information from the web: recent events, documentation, " +
 			"product details, technical references, news, etc. " +
-			"Requires GEMINI_API_KEY. Alternative to Brave-based search tools for users with Google Cloud credits.",
+			"Requires GEMINI_API_KEY or Google login. Alternative to Brave-based search tools.",
 		promptSnippet: "Search the web via Google Search to get current information with sources",
 		promptGuidelines: [
 			"Use google_search when you need up-to-date web information that isn't in your training data.",
@@ -109,17 +204,33 @@ export default function (pi: ExtensionAPI) {
 			),
 		}),
 
-		async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
 			const startTime = Date.now();
 			const maxSources = Math.min(Math.max(params.maxSources ?? 5, 1), 10);
 
-			// Check for API key
+			// Check for credentials
+			let oauthToken: string | undefined;
+			let projectId: string | undefined;
+
 			if (!process.env.GEMINI_API_KEY) {
+				const oauthRaw = await ctx.modelRegistry.getApiKeyForProvider("google-gemini-cli");
+				if (oauthRaw) {
+					try {
+						const parsed = JSON.parse(oauthRaw);
+						oauthToken = parsed.token;
+						projectId = parsed.projectId;
+					} catch {
+						// Fall through to error
+					}
+				}
+			}
+
+			if (!process.env.GEMINI_API_KEY && (!oauthToken || !projectId)) {
 				return {
 					content: [
 						{
 							type: "text",
-							text: "Error: GEMINI_API_KEY is not set. Please set this environment variable to use Google Search.\n\nExample: export GEMINI_API_KEY=your_key",
+							text: "Error: No authentication found for Google Search. Please set GEMINI_API_KEY or log in via Google.\n\nExample: export GEMINI_API_KEY=your_key or use /login google",
 						},
 					],
 					isError: true,
@@ -128,7 +239,7 @@ export default function (pi: ExtensionAPI) {
 						sourceCount: 0,
 						cached: false,
 						durationMs: Date.now() - startTime,
-						error: "auth_error: GEMINI_API_KEY not set",
+						error: "auth_error: No credentials set",
 					} as SearchDetails,
 				};
 			}
@@ -152,49 +263,52 @@ export default function (pi: ExtensionAPI) {
 			// Call Gemini with Google Search grounding
 			let result: SearchResult;
 			try {
-				const ai = await getClient();
-				const response = await ai.models.generateContent({
-					model: process.env.GEMINI_SEARCH_MODEL || "gemini-2.5-flash",
-					contents: params.query,
-					config: {
-						tools: [{ googleSearch: {} }],
-						abortSignal: signal,
-					},
-				});
-
-				// Extract answer text
-				const answer = response.text ?? "";
-
-				// Extract grounding metadata
-				const candidate = response.candidates?.[0];
-				const grounding = candidate?.groundingMetadata;
-
-				// Parse sources from grounding chunks
-				const sources: SearchSource[] = [];
-				const seenTitles = new Set<string>();
-				if (grounding?.groundingChunks) {
-					for (const chunk of grounding.groundingChunks) {
-						if (chunk.web) {
-							const title = chunk.web.title ?? "Untitled";
-							// Dedupe by title since URIs are redirect URLs that differ per call
-							if (seenTitles.has(title)) continue;
-							seenTitles.add(title);
-							// domain field is not available via Gemini API, use title as fallback
-							// (title is typically the domain name, e.g. "wikipedia.org")
-							const domain = chunk.web.domain ?? title;
-							sources.push({
-								title,
-								uri: chunk.web.uri ?? "",
-								domain,
-							});
+				if (process.env.GEMINI_API_KEY) {
+					const ai = await getClient();
+					const response = await ai.models.generateContent({
+						model: process.env.GEMINI_SEARCH_MODEL || "gemini-2.5-flash",
+						contents: params.query,
+						config: {
+							tools: [{ googleSearch: {} }],
+							abortSignal: signal,
+						},
+					});
+
+					// Extract answer text
+					const answer = response.text ?? "";
+
+					// Extract grounding metadata
+					const candidate = response.candidates?.[0];
+					const grounding = candidate?.groundingMetadata;
+
+					// Parse sources from grounding chunks
+					const sources: SearchSource[] = [];
+					const seenTitles = new Set<string>();
+					if (grounding?.groundingChunks) {
+						for (const chunk of grounding.groundingChunks) {
+							if (chunk.web) {
+								const title = chunk.web.title ?? "Untitled";
+								// Dedupe by title since URIs are redirect URLs that differ per call
+								if (seenTitles.has(title)) continue;
+								seenTitles.add(title);
+								// domain field is not available via Gemini API, use title as fallback
+								// (title is typically the domain name, e.g. "wikipedia.org")
+								const domain = chunk.web.domain ?? title;
+								sources.push({
+									title,
+									uri: chunk.web.uri ?? "",
+									domain,
+								});
+							}
 						}
 					}
-				}
 
-				// Extract search queries Gemini actually performed
-				const searchQueries = grounding?.webSearchQueries ?? [];
-
-				result = { answer, sources, searchQueries, cached: false };
+					// Extract search queries Gemini actually performed
+					const searchQueries = grounding?.webSearchQueries ?? [];
+					result = { answer, sources, searchQueries, cached: false };
+				} else {
+					result = await searchWithOAuth(params.query, oauthToken!, projectId!, signal);
+				}
 			} catch (err: unknown) {
 				const msg = err instanceof Error ? err.message : String(err);
 
@@ -287,9 +401,12 @@ export default function (pi: ExtensionAPI) {
 	// ── Startup notification ─────────────────────────────────────────────────
 
 	pi.on("session_start", async (_event, ctx) => {
-		if (!process.env.GEMINI_API_KEY) {
+		if (process.env.GEMINI_API_KEY) return;
+
+		const hasOAuth = await ctx.modelRegistry.authStorage.hasAuth("google-gemini-cli");
+		if (!hasOAuth) {
 			ctx.ui.notify(
-				"Google Search: No GEMINI_API_KEY set. The google_search tool will not work until this is configured.",
+				"Google Search: No authentication set. Log in via Google or set GEMINI_API_KEY to use google_search.",
 				"warning",
 			);
 		}

package/dist/resources/extensions/gsd/auto-dashboard.ts

@@ -10,7 +10,7 @@ import type { ExtensionContext, ExtensionCommandContext } from "@gsd/pi-coding-a
 import type { GSDState } from "./types.js";
 import { getCurrentBranch } from "./worktree.js";
 import { getActiveHook } from "./post-unit-hooks.js";
-import { getLedger, getProjectTotals, formatCost, formatTokenCount } from "./metrics.js";
+import { getLedger, getProjectTotals, formatCost, formatTokenCount, formatTierSavings } from "./metrics.js";
 import {
   resolveMilestoneFile,
   resolveSliceFile,
@@ -39,6 +39,8 @@ export interface AutoDashboardData {
   projectedRemainingCost?: number;
   /** Whether token profile has been auto-downgraded due to budget prediction */
   profileDowngraded?: boolean;
+  /** Number of pending captures awaiting triage (0 if none or file missing) */
+  pendingCaptureCount: number;
 }
 
 // ─── Unit Description Helpers ─────────────────────────────────────────────────
@@ -239,6 +241,7 @@ export function updateProgressWidget(
   unitId: string,
   state: GSDState,
   accessors: WidgetStateAccessors,
+  tierBadge?: string,
 ): void {
   if (!ctx.hasUI) return;
 
@@ -319,7 +322,8 @@ export function updateProgressWidget(
 
         const target = task ? `${task.id}: ${task.title}` : unitId;
         const actionLeft = `${pad}${theme.fg("accent", "▸")} ${theme.fg("accent", verb)}  ${theme.fg("text", target)}`;
-        const phaseBadge = theme.fg("dim", phaseLabel);
+        const tierTag = tierBadge ? theme.fg("dim", `[${tierBadge}] `) : "";
+        const phaseBadge = `${tierTag}${theme.fg("dim", phaseLabel)}`;
         lines.push(rightAlign(actionLeft, phaseBadge, width));
         lines.push("");
 
@@ -414,6 +418,14 @@ export function updateProgressWidget(
             ? `${modelPhase}${theme.fg("dim", modelDisplay)}`
             : "";
           lines.push(rightAlign(`${pad}${sLeft}`, sRight, width));
+
+          // Dynamic routing savings summary
+          if (mLedger && mLedger.units.some(u => u.tier)) {
+            const savings = formatTierSavings(mLedger.units);
+            if (savings) {
+              lines.push(truncateToWidth(theme.fg("dim", `${pad}${savings}`), width));
+            }
+          }
         }
 
         const hintParts: string[] = [];