feat: add cost policy support and refresh model catalog for GitHub AI Credits billing

[melodiouscode]

feat: add cost policy support and refresh model catalog for GitHub AI Credits billing

Summary

This PR proposes adding cost policy support and a refreshed model catalog to align with GitHub Copilot's AI Credits billing transition.

What changes

• New model catalog (packages/squad-sdk/src/config/models.ts): Updated to current active GitHub models across three categories — Lightweight, Versatile, and Powerful — with accurate pricing and included: true flags for zero-credit models (gpt-4.1, gpt-5-mini).

• Cost policy configuration (packages/squad-sdk/src/config/schema.ts): New costPolicy field on ModelSelectionConfig with maxCategory (hard ceiling) and preferIncluded (zero-credit preference) options.

• Two-phase model selection (packages/squad-sdk/src/agents/model-selector.ts): Post-resolution policy veto step that:

  • Warn-and-allows explicit user overrides above the ceiling (Layer 0/1)
  • Automatically downgrades implicit selections (Layer 2/3/4) to the best in-ceiling model
  • Prunes fallback chains to respect the active ceiling

• Updated coordinator governance (all squad.agent.md templates): New model catalog, decision tree documentation, and cost policy conversation phrases.

• New test coverage: est/cost-policy.test.ts removed (broken stub), est/model-selector-policy.test.ts covers the two-phase resolution logic.

• Changeset: @bradygaster/squad-sdk minor bump, @bradygaster/squad-cli patch bump.

Motivation

GitHub Copilot is transitioning to AI Credits billing. Teams need a way to:

• Set a cost ceiling to prevent runaway spend on Powerful models
• Prefer zero-credit included models when acceptable for the task
• Get transparent warnings when explicit overrides exceed the ceiling

Testing

215 test files / 6099 tests passing. Build and lint clean.

[primetimetank21]

From Earl's Squad:

Picking this up since #1080 is still open. Worth noting for context: the earlier implementation in #1089 was self-closed by its author (@melodiouscode) on 2026-06-02 — it wasn't maintainer-rejected. It was a strong first pass and a lot of the shape here is reusable; we'd be building on that groundwork rather than starting cold.

There's also meaningful overlap with #1183 (catalog drift + dynamic discovery). Rather than solve them twice, we'd like to treat #1080 and #1183 together — a single catalog reconciliation that carries the cost-policy work.

Proposed approach — small, wired, test-first, in ~3 focused PRs:

• Catalog refresh. Update model IDs/tiers and, importantly, remove currently-dead IDs from the fallback chains (e.g. gpt-4.1, gemini-3-pro-preview, claude-sonnet-4, gpt-5.1*/gpt-5.2*) that no longer resolve and just burn retry slots. Independently valuable; directly addresses Refresh squad.agent.md model catalog + dynamic catalog discovery #1183's drift.
• Cost policy. A maxCategory ceiling that's actually wired through the spawn/lifecycle path (with the warning surfaced, and a fail-closed path when nothing fits), plus a squad models refresh diagnostic command to show what resolves right now (aligned with @diberry's framing, and @tamirdresher's ask to surface pruned-vs-added).
• Docs/template/skill sync, kept isolated from the code changes.

A few design choices we'd propose:

• No hardcoded per-token pricing — the current values have already drifted, and the surface (cache-write, long-context, promo tiers) isn't representable as flat constants. Source pricing best-effort from the public github/docs models-and-pricing.yml (fetchable auth-free), not compiled into the catalog.
• Keep two separate axes: Squad's quality tier (premium/standard/fast) and GitHub's billing category (lightweight/versatile/powerful) — don't conflate them.
• Drop the included/zero-credit concept — there's no machine-readable source for it and no zero-credit models under current AI-Credits billing.
• Category source — we'd take the authenticated Copilot models API (model_picker_category) as the source of truth for a model's billing category, falling back to the docs YAML (auth-free) when a token isn't available. That resolves the couple of spots where the two disagree (e.g. claude-haiku-4.5, gpt-5.4) in favor of the picker's live value.

We're considering opening a PR to refresh the catalog first — updating the model IDs/tiers and pruning the dead fallback entries. It's low-risk, fixes a live routing issue, and is independent of the policy work, so we'd land it on its own and follow up with the cost policy. Happy to hold for a combined review instead if you'd prefer — just let us know.

Thoughts welcome.

[melodiouscode]

Happy to re-open or contribute anything I can @primetimetank21. I didn't have the time to deal with the PR hygine at the time sadly, and didn't want to leave the PR hanging.

[tamirdresher]

Thanks @primetimetank21 I like the direction. Will spend some time reviewing this tomorrow

[tamirdresher]

@melodiouscode — related to this catalog/billing work: PR #1448 just merged to dev, adding per-agent context tier selection (default vs long_context/1M). It infers each model's supported tiers dynamically from billing.tokenPrices.longContext, so it plugs into the same billing signal you're refreshing here. Would appreciate a look to confirm it plays well with the catalog-refresh direction — squad config context-tier is the entry point.