gsd-pi 2.71.0-dev.e17e0ce → 2.72.0-dev.de4c4b3

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

@@ -0,0 +1,85 @@
+/**
+ * Regression test for the #unconfigured-models fix: findInitialModel() must
+ * skip the saved default when its provider has no working auth, rather than
+ * returning an unusable model that every selector surface would display as
+ * "current".
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { findInitialModel } from "./model-resolver.js";
+
+function fakeRegistry(options: {
+	models: Array<{ provider: string; id: string }>;
+	readyProviders: Set<string>;
+}) {
+	const fullModels = options.models.map((m) => ({
+		...m,
+		name: m.id,
+		api: "anthropic-messages",
+		baseUrl: "",
+		reasoning: false,
+		input: ["text"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 128_000,
+		maxTokens: 4096,
+	}));
+	const available = fullModels.filter((m) => options.readyProviders.has(m.provider));
+	return {
+		find(provider: string, id: string) {
+			return fullModels.find((m) => m.provider === provider && m.id === id);
+		},
+		getAvailable() {
+			return available;
+		},
+		isProviderRequestReady(provider: string) {
+			return options.readyProviders.has(provider);
+		},
+	};
+}
+
+test("findInitialModel skips saved default when provider has no auth", async () => {
+	// User saved xai/grok-4 as default, but XAI_API_KEY is unset so xai is
+	// in the registry but not ready. Previously findInitialModel() step 3
+	// returned xai anyway — now it must fall through to step 4 and pick
+	// an available model.
+	const registry = fakeRegistry({
+		models: [
+			{ provider: "xai", id: "grok-4-fast-non-reasoning" },
+			{ provider: "anthropic", id: "claude-opus-4-6" },
+		],
+		readyProviders: new Set(["anthropic"]),
+	});
+
+	const result = await findInitialModel({
+		scopedModels: [],
+		isContinuing: false,
+		defaultProvider: "xai",
+		defaultModelId: "grok-4-fast-non-reasoning",
+		modelRegistry: registry as any,
+	});
+
+	assert.ok(result.model, "a model must be returned");
+	assert.equal(result.model!.provider, "anthropic", "unauth'd saved default must be skipped");
+});
+
+test("findInitialModel keeps saved default when provider has auth", async () => {
+	const registry = fakeRegistry({
+		models: [
+			{ provider: "anthropic", id: "claude-opus-4-6" },
+			{ provider: "openai", id: "gpt-5.4" },
+		],
+		readyProviders: new Set(["anthropic", "openai"]),
+	});
+
+	const result = await findInitialModel({
+		scopedModels: [],
+		isContinuing: false,
+		defaultProvider: "openai",
+		defaultModelId: "gpt-5.4",
+		modelRegistry: registry as any,
+	});
+
+	assert.equal(result.model?.provider, "openai");
+	assert.equal(result.model?.id, "gpt-5.4");
+});

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

@@ -171,6 +171,25 @@ describe("RetryHandler — long-context entitlement 429 (#2803)", () => {
 			const retryStart = emittedEvents.find((e) => e.type === "auto_retry_start");
 			assert.ok(retryStart, "Regular 429 should enter backoff retry");
 		});
+
+		it("classifies OpenRouter credit affordability errors as quota_exhausted", async () => {
+			const { deps, emittedEvents } = createMockDeps({
+				model: createMockModel("openrouter", "openai/gpt-5-pro"),
+				markUsageLimitReachedResult: false,
+				fallbackResult: null,
+			});
+
+			const handler = new RetryHandler(deps);
+			const msg = errorMessage(
+				"402 This request requires more credits, or fewer max_tokens. You requested up to 32000 tokens, but can only afford 329.",
+			);
+
+			const result = await handler.handleRetryableError(msg);
+
+			assert.equal(result, true, "affordability error should trigger credit-aware retry");
+			const retryStart = emittedEvents.find((e) => e.type === "auto_retry_start");
+			assert.ok(retryStart, "Expected immediate retry after reducing max tokens");
+		});
 	});
 
 	describe("long-context model downgrade", () => {
@@ -271,6 +290,61 @@ describe("RetryHandler — long-context entitlement 429 (#2803)", () => {
 		});
 	});
 
+	describe("credit-aware maxTokens retry", () => {
+		it("reduces maxTokens on same model when provider reports affordable cap", async () => {
+			const expensiveModel = createMockModel("openrouter", "openai/gpt-5-pro");
+			expensiveModel.maxTokens = 128000;
+
+			const { deps, emittedEvents, onModelChangeFn } = createMockDeps({
+				model: expensiveModel,
+				markUsageLimitReachedResult: false,
+				fallbackResult: null,
+			});
+
+			const handler = new RetryHandler(deps);
+			const msg = errorMessage(
+				"402 This request requires more credits, or fewer max_tokens. You requested up to 32000 tokens, but can only afford 329.",
+			);
+
+			const result = await handler.handleRetryableError(msg);
+			assert.equal(result, true, "should retry after reducing maxTokens");
+
+			const setModelCalls = (deps.agent.setModel as any).mock.calls;
+			assert.equal(setModelCalls.length, 1, "should apply one model downgrade");
+			const downgraded = setModelCalls[0].arguments[0] as Model<Api>;
+			assert.equal(downgraded.provider, "openrouter");
+			assert.equal(downgraded.id, "openai/gpt-5-pro");
+			assert.equal(downgraded.maxTokens, 297, "expected affordability cap with safety buffer");
+
+			assert.equal(onModelChangeFn.mock.calls.length, 1, "should notify about model update");
+			const switchEvent = emittedEvents.find((e) => e.type === "fallback_provider_switch");
+			assert.ok(switchEvent, "should emit model-adjustment event");
+			assert.ok(
+				String(switchEvent?.reason || "").includes("credit-aware retry"),
+				"switch reason should mention credit-aware retry",
+			);
+		});
+
+		it("does not mark credentials in cooldown for affordability quota errors", async () => {
+			const expensiveModel = createMockModel("openrouter", "openai/gpt-5-pro");
+			expensiveModel.maxTokens = 128000;
+
+			const { deps, markUsageLimitReached } = createMockDeps({
+				model: expensiveModel,
+				markUsageLimitReachedResult: false,
+				fallbackResult: null,
+			});
+
+			const handler = new RetryHandler(deps);
+			const msg = errorMessage(
+				"402 This request requires more credits, or fewer max_tokens. You requested up to 32000 tokens, but can only afford 329.",
+			);
+
+			await handler.handleRetryableError(msg);
+			assert.equal(markUsageLimitReached.mock.calls.length, 0, "quota error should skip credential cooldown");
+		});
+	});
+
 	describe("isRetryableError", () => {
 		it("considers long-context entitlement error as retryable", () => {
 			const { deps } = createMockDeps();
@@ -291,6 +365,15 @@ describe("RetryHandler — long-context entitlement 429 (#2803)", () => {
 			);
 			assert.equal(handler.isRetryableError(msg), false);
 		});
+
+		it("considers OpenRouter affordability credit errors as retryable", () => {
+			const { deps } = createMockDeps();
+			const handler = new RetryHandler(deps);
+			const msg = errorMessage(
+				"402 This request requires more credits, or fewer max_tokens. You requested up to 32000 tokens, but can only afford 329.",
+			);
+			assert.equal(handler.isRetryableError(msg), true);
+		});
 	});
 
 	describe("third-party block claude-code fallback (#3772)", () => {

package/packages/pi-coding-agent/src/core/retry-handler.ts

@@ -116,7 +116,7 @@ export class RetryHandler {
 		// generated error from getApiKey() when credentials are in a backoff window.
 		// Re-entering the retry handler for that message creates a cascade of empty
 		// error entries in the session file, breaking resume (#3429).
-		return /overloaded|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|terminated|retry delay|network.?(?:is\s+)?unavailable|credentials.*expired|extra usage is required|(?:out of|no) extra usage|third.party.*draw from extra|third.party.*not.*available/i.test(
+		return /overloaded|rate.?limit|too many requests|402|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|terminated|retry delay|network.?(?:is\s+)?unavailable|credentials.*expired|requires more credits|can only afford|insufficient credits|not enough credits|extra usage is required|(?:out of|no) extra usage|third.party.*draw from extra|third.party.*not.*available/i.test(
 			err,
 		);
 	}
@@ -158,6 +158,14 @@ export class RetryHandler {
 			const isRateLimit = errorType === "rate_limit";
 			const isQuotaError = errorType === "quota_exhausted";
 
+			// Credit-aware retry (OpenRouter-style 402 affordability errors):
+			// when provider reports "can only afford N", lower maxTokens and retry
+			// on the same model before rotating credentials/providers.
+			if (isQuotaError) {
+				const adjusted = this._tryAffordableMaxTokensRetry(message, retryGeneration);
+				if (adjusted) return true;
+			}
+
 			// Credential rotation — only for transient rate limits (#3430).
 			// Quota errors ("Extra usage is required") are account-level billing
 			// gates; rotating to another credential on the same account won't help
@@ -409,12 +417,63 @@ export class RetryHandler {
 		// Long-context entitlement errors are billing gates, not transient rate limits.
 		// Must be checked before the generic 429/rate_limit regex.
 		if (/extra usage is required|long context required/i.test(err)) return "quota_exhausted";
+		if (/requires more credits|can only afford|insufficient credits|not enough credits|credit balance/i.test(err))
+			return "quota_exhausted";
 		if (/quota|billing|exceeded.*limit|usage.*limit/i.test(err)) return "quota_exhausted";
 		if (/rate.?limit|too many requests|429/i.test(err)) return "rate_limit";
 		if (/500|502|503|504|server.?error|internal.?error|service.?unavailable/i.test(err)) return "server_error";
 		return "unknown";
 	}
 
+	/**
+	 * Attempt a same-model retry by reducing maxTokens when provider reports
+	 * an affordability cap (e.g., "can only afford 329").
+	 */
+	private _tryAffordableMaxTokensRetry(message: AssistantMessage, retryGeneration: number): boolean {
+		const currentModel = this._deps.getModel();
+		if (!currentModel || !message.errorMessage) return false;
+
+		// Example: "can only afford 329"
+		const match = message.errorMessage.match(/can only afford\s+([\d,]+)/i);
+		if (!match?.[1]) return false;
+
+		const affordable = Number.parseInt(match[1].replace(/,/g, ""), 10);
+		if (!Number.isFinite(affordable) || affordable <= 0) return false;
+
+		// Leave a small buffer so slight input variance doesn't immediately re-fail.
+		const safetyBuffer = Math.min(64, Math.max(16, Math.floor(affordable * 0.1)));
+		const targetMaxTokens = Math.max(64, affordable - safetyBuffer);
+		const downgradedMaxTokens = Math.min(currentModel.maxTokens, targetMaxTokens);
+		if (downgradedMaxTokens >= currentModel.maxTokens) return false;
+
+		const downgradedModel = {
+			...currentModel,
+			maxTokens: downgradedMaxTokens,
+		};
+
+		this._deps.agent.setModel(downgradedModel);
+		this._deps.onModelChange(downgradedModel);
+		this._removeLastAssistantError();
+
+		this._deps.emit({
+			type: "fallback_provider_switch",
+			from: `${currentModel.provider}/${currentModel.id} (maxTokens=${currentModel.maxTokens})`,
+			to: `${downgradedModel.provider}/${downgradedModel.id} (maxTokens=${downgradedModel.maxTokens})`,
+			reason: `credit-aware retry: provider affordable cap ${affordable} tokens`,
+		});
+
+		this._deps.emit({
+			type: "auto_retry_start",
+			attempt: this._retryAttempt + 1,
+			maxAttempts: this._deps.settingsManager.getRetrySettings().maxRetries,
+			delayMs: 0,
+			errorMessage: `${message.errorMessage} (reducing max tokens)`,
+		});
+
+		this._scheduleContinue(retryGeneration);
+		return true;
+	}
+
 	/**
 	 * Attempt to downgrade a long-context model (e.g. claude-opus-4-6[1m]) to its
 	 * base model (claude-opus-4-6) when the account lacks the long-context billing

package/packages/pi-coding-agent/src/modes/interactive/components/model-selector.ts

@@ -120,7 +120,12 @@ export class ModelSelectorComponent extends Container implements Focusable {
 		this.settingsManager = settingsManager;
 		this.modelRegistry = modelRegistry;
 		this.scopedModels = scopedModels;
-		this.scope = scopedModels.length > 0 ? "scoped" : "all";
+		// Only land in "scoped" view when at least one scoped model has working
+		// auth — otherwise the user would see an empty picker (#unconfigured-models).
+		const hasReadyScopedModel = scopedModels.some((scoped) =>
+			modelRegistry.isProviderRequestReady(scoped.model.provider),
+		);
+		this.scope = hasReadyScopedModel ? "scoped" : "all";
 		this.onSelectCallback = onSelect;
 		this.onCancelCallback = onCancel;
 
@@ -215,12 +220,16 @@ export class ModelSelectorComponent extends Container implements Focusable {
 		}
 
 		this.allModels = this.sortModelsWithinProvider(models);
+		// Scoped models must also be filtered by provider readiness so users
+		// can't pick a scoped model whose provider has no API key / OAuth.
 		this.scopedModelItems = this.sortModelsWithinProvider(
-			this.scopedModels.map((scoped) => ({
-				provider: scoped.model.provider,
-				id: scoped.model.id,
-				model: scoped.model,
-			})),
+			this.scopedModels
+				.filter((scoped) => this.modelRegistry.isProviderRequestReady(scoped.model.provider))
+				.map((scoped) => ({
+					provider: scoped.model.provider,
+					id: scoped.model.id,
+					model: scoped.model,
+				})),
 		);
 		this.activeModels = this.scope === "scoped" ? this.scopedModelItems : this.allModels;
 		this.filteredModels = this.activeModels;

package/packages/pi-coding-agent/src/modes/interactive/controllers/model-controller.ts

@@ -52,7 +52,12 @@ export async function findExactModelMatch(host: any, searchTerm: string): Promis
 
 export async function getModelCandidates(host: any): Promise<Model<any>[]> {
 	if (host.session.scopedModels.length > 0) {
-		return host.session.scopedModels.map((scoped: any) => scoped.model);
+		// Filter scoped models by provider auth readiness so callers like
+		// findExactModelMatch can't resolve a scoped-but-unconfigured model.
+		const registry = host.session.modelRegistry;
+		return host.session.scopedModels
+			.filter((scoped: any) => registry.isProviderRequestReady(scoped.model.provider))
+			.map((scoped: any) => scoped.model);
 	}
 
 	host.session.modelRegistry.refresh();

package/pkg/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittercowboy/gsd",
-  "version": "2.71.0",
+  "version": "2.72.0",
   "piConfig": {
     "name": "gsd",
     "configDir": ".gsd"

package/src/resources/agents/debugger.md

@@ -0,0 +1,58 @@
+---
+name: debugger
+description: Hypothesis-driven bug investigation with root cause analysis
+model: sonnet
+---
+
+You are a debugger. Investigate bugs using a systematic, hypothesis-driven approach. Your goal is to find the root cause, not just suppress symptoms.
+
+## Process
+
+1. **Reproduce**: Understand the symptoms — what happens vs. what should happen
+2. **Hypothesize**: List 2-3 most likely causes based on symptoms
+3. **Investigate**: For each hypothesis, gather evidence (read code, check logs, trace execution)
+4. **Narrow**: Eliminate hypotheses that don't match the evidence
+5. **Root cause**: Identify the actual cause with file:line references
+6. **Fix**: Propose the minimal change that addresses the root cause
+
+## Investigation Tools
+
+- Read source files at specific line ranges
+- Grep for error messages, function names, variable usage
+- Check git blame for recent changes to suspect areas
+- Read test files to understand expected behavior
+- Run tests to reproduce failures
+
+## Output Format
+
+## Symptoms
+
+What's happening vs. what's expected.
+
+## Hypotheses
+
+1. **[hypothesis]** — why this could be the cause
+2. **[hypothesis]** — why this could be the cause
+
+## Investigation
+
+### Hypothesis 1: [name]
+
+Evidence gathered, files read, what was found.
+**Verdict:** Confirmed / Eliminated — reason.
+
+### Hypothesis 2: [name]
+
+(same structure)
+
+## Root Cause
+
+**File:** `path/to/file.ts:42`
+**Cause:** Clear explanation of the bug.
+**Why it wasn't caught:** Missing test, edge case, etc.
+
+## Recommended Fix
+
+```typescript
+// minimal fix with explanation
+```

package/src/resources/agents/doc-writer.md

@@ -0,0 +1,43 @@
+---
+name: doc-writer
+description: Documentation generation from code — API docs, inline comments, READMEs
+model: sonnet
+---
+
+You are a documentation specialist. You read code and produce clear, accurate documentation. You write for the reader, not the author — explain what they need to know to use or maintain the code.
+
+## Process
+
+1. Read the code thoroughly — understand what it does, not just how
+2. Identify the audience — users (API docs), maintainers (inline docs), or newcomers (guides)
+3. Write documentation that answers the reader's actual questions
+4. Verify accuracy — every code reference must match the current implementation
+
+## Documentation Types
+
+- **API docs**: Function signatures, parameters, return values, examples, error cases
+- **Inline comments**: Explain *why*, not *what* — the code shows what, comments explain intent
+- **Module docs**: What this module does, its public API, and how it fits in the architecture
+- **Guides**: Step-by-step instructions for common tasks with working examples
+
+## Quality Rules
+
+- Every claim must be verifiable against the current code
+- Examples must be working code, not pseudocode
+- Don't document the obvious — focus on non-obvious behavior, gotchas, and edge cases
+- Keep it concise — more docs isn't better docs
+- Use the project's existing documentation style and format
+
+## Output Format
+
+## Documentation Plan
+
+What to document and for whom.
+
+## Documentation
+
+(The actual documentation content, formatted appropriately for its type)
+
+## Accuracy Check
+
+Files referenced and verified against current implementation.

package/src/resources/agents/git-ops.md

@@ -0,0 +1,56 @@
+---
+name: git-ops
+description: Conflict resolution, rebase strategy, PR preparation, and changelog generation
+model: sonnet
+---
+
+You are a git operations specialist. You handle merge conflicts, plan rebase strategies, prepare pull requests, and generate changelogs. You understand git internals well enough to choose the right strategy for each situation.
+
+## Capabilities
+
+### Conflict Resolution
+- Analyze conflict markers and understand both sides' intent
+- Choose the correct resolution based on code context, not just recency
+- Verify resolved code compiles and tests pass
+
+### Rebase Strategy
+- Assess whether rebase or merge is appropriate for the situation
+- Plan interactive rebase sequences (squash, reorder, edit)
+- Handle complex rebase conflicts with minimal manual intervention
+
+### PR Preparation
+- Write clear PR titles and descriptions from commit history
+- Organize commits into logical, reviewable units
+- Ensure CI checks will pass before pushing
+
+### Changelog Generation
+- Extract user-facing changes from commit messages and code diffs
+- Categorize changes (features, fixes, breaking changes)
+- Write changelog entries for the target audience (users, not developers)
+
+## Process
+
+1. Assess the git state — branches, commits, conflicts, divergence
+2. Determine the goal — clean history, resolved conflicts, PR ready
+3. Plan the steps — in order, with rollback points
+4. Execute carefully — verify after each step
+5. Confirm the result — clean history, passing tests
+
+## Output Format
+
+## Git State
+
+Current branch, commits, conflicts, or divergence summary.
+
+## Strategy
+
+What to do and why this approach.
+
+## Steps
+
+1. Command or action — with expected outcome
+2. Command or action — with verification
+
+## Result
+
+Final state after operations complete.