feat(sdk,cli): thread contextTier through agent spawning pipeline - #1448
Conversation
Adds a contextTier concept (default vs long_context / 1M context window) threaded end-to-end through the SDK and CLI, mirroring the reasoningEffort plumbing from #1148. Models expose supportedContextTiers/defaultContextTier; requests validate and clamp against what a model supports. Adds the 'squad config context-tier' CLI subcommand and coordinator guidance. Closes #1446 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 2 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset file found |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | 0 active Copilot thread(s) resolved (1 outdated skipped) |
| ❌ | CI passing | 1 check(s) failing: test |
Files Changed (19 files, +1041 −9)
| File | +/− |
|---|---|
.changeset/context-tier.md |
+15 −0 |
.github/agents/squad.agent.md |
+27 −0 |
.squad-templates/squad.agent.md |
+27 −0 |
packages/squad-cli/src/cli/commands/config.ts |
+99 −0 |
packages/squad-cli/templates/squad.agent.md.template |
+27 −0 |
packages/squad-sdk/src/adapter/client.ts |
+8 −0 |
packages/squad-sdk/src/adapter/types.ts |
+39 −0 |
packages/squad-sdk/src/agents/charter-compiler.ts |
+32 −1 |
packages/squad-sdk/src/agents/index.ts |
+5 −0 |
packages/squad-sdk/src/agents/lifecycle.ts |
+15 −2 |
packages/squad-sdk/src/builders/index.ts |
+7 −1 |
packages/squad-sdk/src/builders/types.ts |
+7 −1 |
packages/squad-sdk/src/config/models.ts |
+304 −1 |
packages/squad-sdk/src/config/schema.ts |
+3 −0 |
packages/squad-sdk/src/coordinator/fan-out.ts |
+20 −3 |
packages/squad-sdk/src/coordinator/spawn-backend.ts |
+4 −0 |
packages/squad-sdk/templates/squad.agent.md.template |
+27 −0 |
templates/squad.agent.md.template |
+27 −0 |
test/model-preference.test.ts |
+348 −0 |
Total: +1041 −9
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
🟠 Impact Analysis — PR #1448Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affectedci-workflows (1 file)
root (2 files)
squad-cli (2 files)
squad-sdk (12 files)
templates (1 file)
tests (1 file)
|
There was a problem hiding this comment.
Pull request overview
Threads a new context tier (context window size) selection through Squad’s SDK + CLI, mirroring the existing reasoningEffort plumbing so callers can choose between "default" and "long_context" at the model-default and per-agent levels.
Changes:
- Adds
SquadContextTier+SquadSessionConfig.contextTier, and surfaces per-modelsupportedContextTiers/defaultContextTier(inferred from billing). - Threads
contextTierthrough charter parsing/compilation, builders, lifecycle spawning, coordinator fan-out, and spawn backends (including runtimecontext_tiermapping where required). - Adds
squad config context-tier ...CLI support, expands tests, and ships a changeset for SDK + CLI.
Reviewed changes
Copilot reviewed 19 out of 19 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| test/model-preference.test.ts | Adds coverage for reading/writing/resolving/clamping context tier preferences. |
| templates/squad.agent.md.template | Documents per-agent context tier behavior for the coordinator template. |
| packages/squad-sdk/templates/squad.agent.md.template | Mirrors coordinator guidance into SDK templates. |
| packages/squad-cli/templates/squad.agent.md.template | Mirrors coordinator guidance into CLI templates. |
| .squad-templates/squad.agent.md | Updates the source template with context-tier guidance. |
| .github/agents/squad.agent.md | Updates the coordinator agent instructions with context-tier guidance. |
| packages/squad-sdk/src/coordinator/spawn-backend.ts | Passes contextTier through task and session spawn backends (incl. context_tier). |
| packages/squad-sdk/src/coordinator/fan-out.ts | Threads and validates contextTierOverride through fan-out spawn config. |
| packages/squad-sdk/src/config/schema.ts | Extends config schema types with context tier defaults and per-agent overrides. |
| packages/squad-sdk/src/config/models.ts | Adds VALID_CONTEXT_TIERS plus read/write/resolve/clamp helpers for context tier. |
| packages/squad-sdk/src/builders/types.ts | Adds contextTier to defaults and agent definitions. |
| packages/squad-sdk/src/builders/index.ts | Validates contextTier in defineAgent() / defineDefaults(). |
| packages/squad-sdk/src/agents/lifecycle.ts | Threads contextTierOverride into session config for lifecycle-managed spawns. |
| packages/squad-sdk/src/agents/index.ts | Extends AgentCharter and compiler output to include contextTier. |
| packages/squad-sdk/src/agents/charter-compiler.ts | Parses **Context Tier:** and compiles/resolves a context tier preference. |
| packages/squad-sdk/src/adapter/types.ts | Adds the SquadContextTier type and session/model fields for context-tier support. |
| packages/squad-sdk/src/adapter/client.ts | Infers supportedContextTiers from billing token pricing and sets defaultContextTier. |
| packages/squad-cli/src/cli/commands/config.ts | Implements squad config context-tier subcommand (show/set/clear default + per-agent). |
| .changeset/context-tier.md | Declares minor bumps for @bradygaster/squad-sdk and @bradygaster/squad-cli. |
| requested: string | undefined, | ||
| supportedTiers: string[] | undefined, | ||
| modelDefault?: string, | ||
| ): string | undefined { | ||
| if (requested === undefined || requested === null || requested === '') return undefined; |
…rt (addresses PR review) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
Hey @bradygaster — this merged to What shipped: per-agent context tier selection ( E2E-certified: 101/101 preference tests pass; full 11-item matrix verified with real CLI/SDK output across 17 live models. PRODUCTION-SOLID. One honest caveat: squad-wide Optional one-liner if you want the squad-wide default to thread into real spawns: |
Summary
Threads a context tier (context-window) concept end-to-end through the Squad SDK + CLI, exactly mirroring the existing
reasoningEffortplumbing (blueprint: merged PR #1148). The Copilot runtime exposes a per-spawncontext_tier: "default" | "long_context"param — e.g. Opus 4.8 → 264K (default) vs 1M (long_context) — but Squad previously had no way to select it. Now it does, at both the model-default and per-agent-override levels.Closes #1446
Adapter → runtime boundary (the CRITICAL FIRST STEP)
Verified
packages/squad-sdk/src/adapter/client.tsbefore writing the spawn layer.createSessionforwards the entire normalizedSquadSessionConfigto the runtime via wholesale passthrough — socontextTierreaches the runtime automatically once it's a field on the config type. No client.ts spawn-mapping edit was required (this mirrors howreasoningEffortalready flows). The onlyclient.tschange is inlistModels, where each model now advertisessupportedContextTiers/defaultContextTier, inferred frombilling.tokenPrices.longContext.What changed (mirrors #1148 layering)
adapter/types.ts):SquadContextTier = "default" | "long_context";SquadSessionConfig.contextTier?; per-modelsupportedContextTiers?/defaultContextTier?.config/models.ts):defaultContextTier/agentContextTierOverridesconfig,VALID_CONTEXT_TIERS, andread/write/resolve/clamphelpers mirroring the effort resolvers. Unsupported tier clamps to the model default; unknown/unset treated asdefault.config/schema.ts):ModelConfig.defaultContextTier+agentContextTierOverrides;AgentConfig.contextTier.agents/charter-compiler.ts): parses## Model→**Context Tier:**.agents/lifecycle.ts,coordinator/fan-out.ts,coordinator/spawn-backend.ts): threadscontextTierthrough spawn. Task backend uses camelCasecontextTier; session-kickoff backend uses snake_casecontext_tier(the runtime param name).builders/types.ts,builders/index.ts):contextTieron defaults + agent definitions, validated againstVALID_CONTEXT_TIERS.cli/commands/config.ts):squad config context-tier [<tier>] [--agent <name>] [--clear], parallel tosquad config model.test/model-preference.test.ts): newcontextTierdescribe blocks. All 101 tests pass..changeset/context-tier.md):@bradygaster/squad-sdkminor +@bradygaster/squad-climinor.Design notes
EFFORT_RANKanalog.autois a Squad-only stored sentinel meaning "not set" (write helpers accept it;resolveContextTierrejects it and falls through to the model/default). It is not part of the publicSquadContextTierunion..mdtemplates were not given a new session-param bullet, staying faithful to feat(sdk): thread reasoningEffort through agent spawning pipeline #1148 (which also left charters untouched). The compiler still honors a manually-added**Context Tier:**line.This PR edits
.github/agents/squad.agent.md(and the 4 mirrored templates) to add a### Per-Agent Context Tiersection analogous to the reasoning-effort guidance. Becausesquad.agent.mdis the coordinator's own instruction file, any session running before this merges is on stale coordinator instructions — restart your Squad session after merge to pick up the new context-tier routing behavior.Relationship to PR #1444
Orthogonal in concept (that PR refreshes the model-ID catalog / prunes dead fallback chains; this PR adds contextTier plumbing). There is minor file overlap in
config/models.tsandconfig/schema.ts, but in disjoint regions, so conflict risk is low — whoever merges second should rebase. They're actually synergistic: #1444 addsclaude-opus-4.8, which is the model that best demonstrates this feature (264K vs 1M).Verification
npm run build -w packages/squad-sdk✅npm run build -w packages/squad-cli✅npx vitest run test/model-preference.test.ts→ 101 passed ✅Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com