docs(budget-model): rewrite README and JSDoc for nested auth shape

- README usage examples updated from `{ model, apiKey }` to `{ model, auth }`
  with `{ ...auth }` spread idiom.
- New section documenting both forms of `modelOverride` (string vs object),
  including the auth-bypass use case.
- Restored JSDoc on `BudgetModel` interface explaining the spread pattern.
- Expanded `findBudgetModel` JSDoc to describe override semantics.
- Added auth.test.ts case for object form with empty auth (`auth: {}`),
  confirming SDK-resolved-credentials use case isn't rejected.

Author: mgabor3141

.changeset/align-pi-versions.md

@@ -0,0 +1,12 @@
+---
+"pi-bash-bg": patch
+"pi-bash-trim": patch
+"pi-desktop-notify": patch
+"pi-enclave": patch
+"pi-jujutsu": patch
+"pi-no-soft-cursor": patch
+---
+
+Align `@mariozechner/pi-coding-agent` (and `@mariozechner/pi-tui` for `pi-no-soft-cursor`) `devDependency` to `^0.63.0`.
+
+`devDependency`-only update; no runtime change. Published `dist/*.d.ts` may reference newer upstream types from pi 0.63 (e.g. the `signal` property on `ExtensionContext`), so consumers writing extensions against these packages should be on pi ≥ 0.63 to match. Required to keep `tsup --dts` working alongside `pi-budget-model`, which now depends on the 0.63 registry API.

packages/budget-model/README.md

@@ -13,29 +13,44 @@ npm install pi-budget-model
 ## Usage
 
 ```typescript
+import { completeSimple } from "@mariozechner/pi-ai";
 import { findBudgetModel, NoBudgetModelError } from "pi-budget-model";
 
 // Simple — cheapest in same provider, latest major version
-const { model, apiKey } = await findBudgetModel(ctx);
+const { model, auth } = await findBudgetModel(ctx);
 
-// Cross-provider — cheapest across all providers with an API key
-const { model, apiKey } = await findBudgetModel(ctx, {
+// `auth` is `{ apiKey?: string; headers?: Record<string, string> }`, ready to
+// spread into pi-ai's stream/completeSimple options.
+await completeSimple(model, ctx, { ...auth, signal });
+
+// Cross-provider — cheapest across all providers with usable auth
+const { model, auth } = await findBudgetModel(ctx, {
   strategy: "any-provider",
 });
 
 // Include previous major version (often much cheaper)
-const { model, apiKey } = await findBudgetModel(ctx, {
+const { model, auth } = await findBudgetModel(ctx, {
   majorVersions: 2,    // latest + previous major version
   costRatio: 0.5,      // must be ≤ half the active model's cost
 });
 
 // Pin a specific model, skip auto-selection
-const { model, apiKey } = await findBudgetModel(ctx, {
+const { model, auth } = await findBudgetModel(ctx, {
   modelOverride: "anthropic/claude-haiku-4-5",
 });
 
+// Pin a model AND supply credentials directly, bypassing the registry's auth
+// resolution. Use as an escape hatch when the registry's auth pipeline
+// misbehaves for your provider.
+const { model, auth } = await findBudgetModel(ctx, {
+  modelOverride: {
+    model: "openai/gpt-4o-mini",
+    auth: { apiKey: process.env.OPENAI_API_KEY },
+  },
+});
+
 // Only free models
-const { model, apiKey } = await findBudgetModel(ctx, {
+const { model, auth } = await findBudgetModel(ctx, {
   costRatio: 0,
 });
 ```
@@ -67,7 +82,7 @@ When the active model is already the cheapest (like Haiku 4.5), you can widen th
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `modelOverride` | `"provider/model-id"` | — | Pin a specific model, bypassing auto-selection entirely |
+| `modelOverride` | `"provider/model-id"` \| `{ model, auth }` | — | Pin a specific model, bypassing auto-selection entirely |
 | `strategy` | `"same-provider"` \| `"any-provider"` | `"same-provider"` | Where to search for budget models |
 | `costRatio` | `0`–`1` | `0.5` | Max cost as fraction of active model (0 = free only) |
 | `majorVersions` | `0`, `1`, `2`, ... | `1` | How many major versions to search (1 = latest, 2 = latest + previous, 0 = all) |
@@ -76,9 +91,12 @@ Options are validated at runtime with [valibot](https://valibot.dev). Invalid va
 
 ### `modelOverride`
 
-When set, **all other options are ignored**. The model is resolved directly from the registry by provider and ID — no strategy, cost ratio, or version filtering applies. Throws `NoBudgetModelError` if the model doesn't exist or has no API key.
+When set, **all other options are ignored**. The model is resolved directly from the registry by provider and ID — no strategy, cost ratio, or version filtering applies. Throws `NoBudgetModelError` if the model doesn't exist in the registry.
+
+Two forms:
 
-This is useful for pinning a known-good model in config files, or for testing.
+- **String** `"provider/model-id"`: registry resolves both the model metadata and the auth credentials. Use this for pinning a known-good model in config files or for testing.
+- **Object** `{ model: "provider/model-id", auth: { apiKey?, headers? } }`: registry resolves the model metadata via `find()`, but auth is taken straight from the option — the registry's auth pipeline (`getApiKeyAndHeaders`) is not invoked. Use this as an escape hatch when the registry's auth resolution misbehaves for your provider, or to inject credentials from a non-pi source.
 
 ### Reusable options schema
 
@@ -104,7 +122,7 @@ For `same-provider` (default):
 3. Find the cheapest model(s) by input cost
 4. Verify the cheapest is within the cost ratio vs the active model
 5. Among ties: higher version numbers win, aliases preferred over dated snapshots
-6. Return the first candidate with an available API key
+6. Return the first candidate the registry can authenticate (any `ok: true` result, including header-only and SDK-resolved auth)
 
 For `any-provider`: same steps but across all providers, grouped independently per provider then merged.
 
@@ -114,7 +132,7 @@ Throws `NoBudgetModelError` when no suitable model is found. The error includes
 
 ```typescript
 try {
-  const { model, apiKey } = await findBudgetModel(ctx);
+  const { model, auth } = await findBudgetModel(ctx);
 } catch (err) {
   if (err instanceof NoBudgetModelError) {
     err.reason;          // why it failed

packages/budget-model/src/index.ts

@@ -66,7 +66,17 @@ export const BudgetModelOptions = v.object({
 });
 export type BudgetModelOptions = v.InferOutput<typeof BudgetModelOptions>;
 
-/** A model selected for a background task, plus the auth material needed to call it. */
+/**
+ * A model selected for a background task, plus the auth material needed to call it.
+ *
+ * `auth` is the same shape `pi-ai`'s `StreamOptions` accepts. The intended call
+ * pattern is to spread it directly:
+ *
+ * ```ts
+ * const { model, auth } = await findBudgetModel(ctx);
+ * await completeSimple(model, ctx, { ...auth, signal, maxTokens });
+ * ```
+ */
 export interface BudgetModel {
 	model: Model<Api>;
 	auth: BudgetModelAuth;
@@ -131,8 +141,18 @@ export class NoBudgetModelError extends Error {
 /**
  * Find the cheapest available model for background tasks.
  *
+ * If `options.modelOverride` is set, selection is skipped:
+ * - String form `"provider/model-id"`: registry resolves both model and auth.
+ * - Object form `{ model, auth }`: registry resolves only the model metadata
+ *   via `find()`; auth is taken from the option, bypassing the registry's
+ *   auth pipeline. Useful as an escape hatch when registry auth misbehaves.
+ *
+ * Otherwise the configured `strategy` (`"same-provider"` or `"any-provider"`)
+ * walks candidate models cheapest-first, gated by `costRatio` against the
+ * active model, and returns the first candidate the registry can authenticate.
+ *
  * @param ctx - Extension context
- * @param options - Strategy, cost ratio, and major version depth (validated at runtime)
+ * @param options - Strategy, cost ratio, major version depth, and optional override (validated at runtime)
  * @throws NoBudgetModelError if no suitable model is found
  */
 export async function findBudgetModel(ctx: ExtensionContext, options?: BudgetModelOptions): Promise<BudgetModel> {

packages/budget-model/test/auth.test.ts

@@ -170,6 +170,28 @@ describe("findBudgetModel modelOverride object form", () => {
 		).rejects.toThrow(/not found in registry/);
 	});
 
+	it("accepts an empty auth object (caller defers auth to ambient credentials)", async () => {
+		// `BudgetModelAuth` has both fields optional. A caller using SDK-resolved
+		// credentials (e.g. AWS Bedrock with profile-based auth) may legitimately
+		// supply `auth: {}` — the downstream provider in pi-ai handles auth itself.
+		// We assert that's not rejected.
+		const all = await loadModels();
+		const override = all[0];
+		const ctx = makeCtx(
+			all,
+			() => {
+				throw new Error("registry auth pipeline must not be invoked for object-form modelOverride");
+			},
+			undefined,
+		);
+
+		const result = await findBudgetModel(ctx, {
+			modelOverride: { model: `${String(override.provider)}/${override.id}`, auth: {} },
+		});
+
+		expect(result.auth).toEqual({});
+	});
+
 	it("string form still works (registry resolves both model and auth)", async () => {
 		const all = await loadModels();
 		const override = all[0];