diff --git a/README.md b/README.md index 0c98ef9..c2424d7 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ By default claudetm uses the global `~/.claude/.credentials.json` session. **Pro There are two profile types: - **`oauth`** — an isolated Claude Code config home. Each profile gets its own credentials directory under `~/.claudetm/profiles//`, so two subscriptions never clobber each other. -- **`api-key`** — a direct API key + base URL (e.g. z.ai / GLM via an Anthropic-compatible endpoint), injected as `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`. It can also carry **per-tier model and context-window overrides** so claudetm routes every complexity level to a model the endpoint actually serves. +- **`api-key`** — a direct API key + base URL (e.g. z.ai / GLM via an Anthropic-compatible endpoint), injected as `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`. It can also carry **per-tier model overrides** so claudetm routes every complexity level to a model the endpoint actually serves. Context-window values are also accepted, but are currently inert metadata: they do not control runtime compaction or grant context. ```bash # Create an oauth profile and log into it (opens claude in its isolated dir) @@ -95,8 +95,9 @@ CLAUDETM_API_KEY=sk-... claudetm profile add zai --type api-key \ --base-url https://api.z.ai/api/anthropic # An api-key profile against a custom endpoint: name a model for each tier -# (and optionally its context size in tokens). Tiers you omit inherit from a -# family neighbour, so naming just opus/sonnet/haiku covers every task. +# and optionally record context-window metadata (currently inert). Model tiers +# you omit inherit from a family neighbour, so naming just opus/sonnet/haiku +# covers every task. # # --model-opus coding tasks (complex implementation) — the smart tier # --model-sonnet general tasks (balanced) @@ -312,7 +313,7 @@ claudetm --init-config claudetm --show-config ``` -This creates `.claude-task-master/config.json`. The smartest tier (`opus`) defaults to **Claude Opus 5** (`claude-opus-5`), whose context window is **1M tokens natively** — so `context_windows.opus` defaults to `1000000`. (There is no `claude-opus-5[1m]` model ID; that suffix is a Claude Code CLI convention and 404s against the API.) Override the model by editing the `"opus"` key or setting `CLAUDETM_MODEL_OPUS`; drop `context_windows.opus` to `200000` if your account is capped at standard context. A separate opt-in `fable` tier defaults to **Claude Fable 5** (`claude-fable-5`, premium-priced at 2x Opus) — mirroring Claude Code's `ANTHROPIC_DEFAULT_FABLE_MODEL`; override via the `"fable"` key or `CLAUDETM_MODEL_FABLE`. No task routes to it by default; set `CLAUDETM_MODEL_OPUS=claude-fable-5` to run the smartest tier on Fable. +This creates `.claude-task-master/config.json`. The smartest tier (`opus`) defaults to **Claude Opus 5** (`claude-opus-5`), whose context window is **1M tokens natively** — so `context_windows.opus` defaults to `1000000` as metadata only, with no runtime compaction effect. (There is no `claude-opus-5[1m]` model ID; that suffix is a Claude Code CLI convention and 404s against the API.) Override the model by editing the `"opus"` key or setting `CLAUDETM_MODEL_OPUS`; changing `context_windows.opus` does not change the context available to your account. A separate opt-in `fable` tier defaults to **Claude Fable 5** (`claude-fable-5`, premium-priced at 2x Opus) — mirroring Claude Code's `ANTHROPIC_DEFAULT_FABLE_MODEL`; override via the `"fable"` key or `CLAUDETM_MODEL_FABLE`. No task routes to it by default; set `CLAUDETM_MODEL_OPUS=claude-fable-5` to run the smartest tier on Fable. ```json { @@ -342,15 +343,9 @@ This creates `.claude-task-master/config.json`. The smartest tier (`opus`) defau } ``` -> **Note:** `context_windows` only drives claudetm's **auto-compact threshold** — it does not grant a bigger window. Over-stating a window means compaction fires too late and the session overflows; under-stating it just compacts early, which is harmless. So the defaults are deliberately conservative, and only `opus` claims 1M: +> **Note:** `context_windows` and `CLAUDETM_CONTEXT_*` are **currently inert metadata** retained for compatibility. Values can still be loaded from configuration, emitted by profiles, and read by the context-window helper, but they do not drive runtime auto-compaction, prevent context overflow, or grant a larger context window. Actual context limits and compaction behavior depend on Claude Code/SDK and the provider, not these settings. > -> | Tier | Default | Why | -> |---|---|---| -> | `opus` | 1000000 | Opus is upgraded to 1M automatically on Max/Team/Enterprise. **On Pro that upgrade is billed to usage credits** — set `200000` if you don't buy them. | -> | `sonnet` | 200000 | Conservative. On a subscription the 1M window is the paid extra, so this only goes to `1000000` once you've confirmed your account actually serves it. | -> | `haiku` | 200000 | Haiku 4.5's real window. | -> -> Two setups cap 1M-capable models at 200K regardless of plan, and want `200000` for every tier: an LLM gateway (`ANTHROPIC_BASE_URL` pointing somewhere Claude Code can't verify 1M support) and `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`. +> Existing configurations such as the following remain accepted, but changing these values for an account tier or gateway has no runtime compaction effect: > ```json > "context_windows": { > "opus": 200000, @@ -374,7 +369,7 @@ The config file sets these environment variables before Python starts: | `models.fable` | `CLAUDETM_MODEL_FABLE` | Model for fable tier (opt-in, premium) | | `models.haiku` | `CLAUDETM_MODEL_HAIKU` | Model for haiku tier | | `models.sonnet_1m` | `CLAUDETM_MODEL_SONNET_1M` | Model for debugging/QA tier (big context) | -| `context_windows.*` | `CLAUDETM_CONTEXT_{OPUS,FABLE,SONNET,HAIKU,SONNET_1M}` | Context window per tier (tokens) | +| `context_windows.*` | `CLAUDETM_CONTEXT_{OPUS,FABLE,SONNET,HAIKU,SONNET_1M}` | Currently inert per-tier metadata (tokens); does not control runtime compaction or grant context | | `git.target_branch` | `CLAUDETM_TARGET_BRANCH` | Target branch for PRs | Precedence (highest first): real environment variables, then the **active profile** (api-key/oauth profiles supply these same keys), then the config file. diff --git a/src/claude_task_master/core/agent_models.py b/src/claude_task_master/core/agent_models.py index 0cf4b7a..3f1fde9 100644 --- a/src/claude_task_master/core/agent_models.py +++ b/src/claude_task_master/core/agent_models.py @@ -1,11 +1,10 @@ """Agent Models - Enums, constants, and utility functions for model configuration. This module contains: -- ModelType: Available Claude models (Sonnet, Opus, Haiku, Sonnet 1M) +- ModelType: Available Claude models (Sonnet, Opus, Fable, Haiku, Sonnet 1M) - TaskComplexity: Task complexity levels for dynamic model selection, including get_model_name_for_complexity for name-based model routing -- ToolConfig: Tool configurations for different execution phases (now config-backed) -- MODEL_CONTEXT_WINDOWS: Model context window sizes +- MODEL_CONTEXT_WINDOWS: Retained context-window metadata defaults - parse_task_complexity: Parse complexity tags from task descriptions - get_tools_for_phase: Get tool list for a phase from global config """ @@ -104,27 +103,25 @@ def get_model_name_for_complexity(cls, complexity: TaskComplexity) -> ModelType: # Constants # ============================================================================= -# Model context window sizes (tokens) for auto-compact threshold calculation. -# These are defaults; users can override via config.json "context_windows" section. -# Opus 5 and Sonnet 5 both report a 1M context window from the Models API. -# Note: The Agent SDK handles the `context-1m-2025-08-07` beta header internally. -# These values are only used to calculate when to trigger context compaction. -# See: https://platform.claude.com/docs/en/build-with-claude/context-windows +# Retained context-window metadata defaults (tokens) for get_context_window. +# The helper can read config.json "context_windows" overrides, but has no runtime +# compaction caller. These values do not set compaction thresholds or select a +# larger SDK window; they are retained for compatibility. MODEL_CONTEXT_WINDOWS = { - ModelType.OPUS: 1_000_000, # Claude Opus 5: 1M context (native, per Models API) - ModelType.FABLE: 1_000_000, # Claude Fable 5: 1M context (default, no beta gate) - ModelType.SONNET: 1_000_000, # Claude Sonnet 5: 1M context (beta, tier 4+) - ModelType.HAIKU: 200_000, # Claude Haiku 4.5: 200K context - ModelType.SONNET_1M: 1_000_000, # Sonnet with 1M context (always 1M) + ModelType.OPUS: 1_000_000, + ModelType.FABLE: 1_000_000, + ModelType.SONNET: 1_000_000, + ModelType.HAIKU: 200_000, + ModelType.SONNET_1M: 1_000_000, } -# Standard context windows (for users below tier 4) +# Legacy standard-window metadata, retained for compatibility; also inert at runtime. MODEL_CONTEXT_WINDOWS_STANDARD = { ModelType.OPUS: 200_000, - ModelType.FABLE: 1_000_000, # Fable 5's 1M window is the default, not tier-gated + ModelType.FABLE: 1_000_000, ModelType.SONNET: 200_000, ModelType.HAIKU: 200_000, - ModelType.SONNET_1M: 1_000_000, # Always 1M — that's the point + ModelType.SONNET_1M: 1_000_000, } # Fallback model mapping: if primary model unavailable, try fallback @@ -190,14 +187,17 @@ def get_context_window( model: ModelType, config: ClaudeTaskMasterConfig | None = None, ) -> int: - """Get context window size for a model, reading from config if available. + """Read retained context-window metadata, using config when supplied. + + This compatibility helper has no runtime compaction caller. Its return value + does not set a compaction threshold or select the SDK's context window. Args: model: The model type. config: Optional config object. If None, uses hardcoded defaults. Returns: - Context window size in tokens. + Context-window metadata in tokens, not a runtime capacity guarantee. """ if config is not None: context_map = { @@ -211,8 +211,8 @@ def get_context_window( return MODEL_CONTEXT_WINDOWS[model] -# Default compact threshold as percentage of context window -DEFAULT_COMPACT_THRESHOLD_PERCENT = 0.85 # Compact at 85% usage +# Legacy compact-threshold constant, retained for compatibility and unused at runtime. +DEFAULT_COMPACT_THRESHOLD_PERCENT = 0.85 # ============================================================================= diff --git a/src/claude_task_master/core/config.py b/src/claude_task_master/core/config.py index 1265c73..a6fbfe4 100644 --- a/src/claude_task_master/core/config.py +++ b/src/claude_task_master/core/config.py @@ -117,49 +117,39 @@ class GitConfig(BaseModel): class ContextWindowsConfig(BaseModel): - """Context window sizes per model (in tokens). + """Retained context-window metadata per model (in tokens). - Controls the max context window size used for auto-compact threshold calculation. - - These only drive *when claudetm compacts* -- they do not grant a larger window. So - the bias is deliberate: under-stating a window compacts early (harmless), over-stating - it compacts too late and overflows the session. Defaults track a Claude Code - subscription, the auth path claudetm runs on: - - - ``opus`` -- 1M. Automatically upgraded on Max/Team/Enterprise with no extra - configuration. **On Pro this requires usage credits**; set 200000 there. - - ``sonnet`` -- 200K, the conservative default. Raise to 1000000 only once you have - confirmed your account actually serves Sonnet at 1M. - - ``haiku`` -- 200K, which is Haiku 4.5's real window. - - Two setups budget 1M-capable models at 200K regardless of plan, and want 200000 for - every tier here: an LLM gateway (``ANTHROPIC_BASE_URL`` pointing somewhere Claude Code - cannot verify 1M support) and ``CLAUDE_CODE_DISABLE_1M_CONTEXT=1``. + Values remain loadable from configuration and ``CLAUDETM_CONTEXT_*`` environment + variables, including those emitted by profiles, and readable by ``get_context_window``. + They are currently inert for runtime compaction and window selection: changing them + does not set a compaction threshold, prevent context overflow, or grant a larger + SDK context window. Defaults and keys are retained for compatibility. """ opus: int = Field( default=1_000_000, - description="Opus context window size in tokens. 1000000 matches the automatic " - "1M upgrade on Max/Team/Enterprise; set to 200000 on Pro (1M needs usage credits " - "there) or behind an LLM gateway.", + description="Opus context-window metadata in tokens; currently inert for runtime " + "compaction and SDK window selection.", ) fable: int = Field( default=1_000_000, - description="Fable context window size in tokens. Claude Fable 5 is 1M by default.", + description="Fable context-window metadata in tokens; currently inert for runtime " + "compaction and SDK window selection.", ) sonnet: int = Field( default=200_000, - description="Sonnet context window size in tokens. 200000 is the conservative " - "default (1M on a subscription is billed to usage credits); raise to 1000000 " - "only once you have confirmed your account serves Sonnet at 1M.", + description="Sonnet context-window metadata in tokens; currently inert for runtime " + "compaction and SDK window selection.", ) haiku: int = Field( default=200_000, - description="Haiku context window size in tokens.", + description="Haiku context-window metadata in tokens; currently inert for runtime " + "compaction and SDK window selection.", ) sonnet_1m: int = Field( default=1_000_000, - description="Sonnet 1M context window size in tokens. Always 1M.", + description="Sonnet 1M context-window metadata in tokens; currently inert for runtime " + "compaction and SDK window selection.", ) @@ -251,7 +241,8 @@ class ClaudeTaskMasterConfig(BaseModel): ) context_windows: ContextWindowsConfig = Field( default_factory=ContextWindowsConfig, - description="Context window sizes per model (tokens). Set to 200000 if not on tier 4+.", + description="Retained context-window metadata per model (tokens); currently inert for " + "runtime compaction and SDK window selection.", ) git: GitConfig = Field( default_factory=GitConfig, diff --git a/src/claude_task_master/core/profiles.py b/src/claude_task_master/core/profiles.py index a053d2c..deccedb 100644 --- a/src/claude_task_master/core/profiles.py +++ b/src/claude_task_master/core/profiles.py @@ -14,9 +14,10 @@ - ``api-key`` - a direct API key + base URL injected as ``ANTHROPIC_API_KEY`` / ``ANTHROPIC_BASE_URL`` (e.g. z.ai / GLM via an Anthropic-compatible endpoint). May also carry per-tier ``models`` (opus/sonnet/haiku/sonnet_1m/fable -> a - provider-valid model id) and ``context_windows`` overrides; tiers the profile - omits inherit from a family neighbour so a partial profile still routes every - complexity level to a model the endpoint actually serves. + provider-valid model id); omitted model tiers inherit from a family neighbour + so a partial profile still routes every complexity level to a model the + endpoint actually serves. ``context_windows`` metadata also supports family + fallback, but is currently inert for runtime compaction and window selection. The registry lives in ``~/.claudetm/profiles.json`` (override the base directory with the ``CLAUDETM_HOME`` env var). The active profile is a single pointer, @@ -111,10 +112,11 @@ class Profile(BaseModel): default=None, description="Model name overrides (opus, sonnet, fable, haiku, sonnet_1m → custom IDs).", ) - # Optional context window overrides (in tokens) + # Optional context-window metadata (tokens), retained for compatibility. context_windows: dict[str, int] | None = Field( default=None, - description="Context window sizes per model (opus, sonnet, fable, haiku, sonnet_1m → tokens).", + description="Context-window metadata per model (tokens); currently inert for runtime " + "compaction and SDK window selection.", ) def validate_for_type(self) -> None: @@ -235,13 +237,11 @@ def env_for_profile(profile: Profile) -> dict[str, str]: if value: env[env_var] = value - # Context window overrides (tokens). Read by the config loader to size the - # auto-compact threshold per tier. As with models, a partial mapping still - # covers every tier via family fallback (sonnet_1m <- sonnet <- opus, - # fable <- opus <- sonnet). This matters for custom endpoints whose real - # context is far below the Claude defaults: without it claudetm assumes - # e.g. 1M for sonnet_1m and never compacts before the provider's smaller - # limit is hit ("The model has reached its context window limit"). + # Context-window metadata (tokens) is emitted as CLAUDETM_CONTEXT_* and + # loaded into config. Missing sonnet_1m/fable values use family fallback + # (sonnet_1m <- sonnet <- opus, fable <- opus <- sonnet). These values are + # currently inert for runtime compaction and SDK window selection; emission + # and loading do not set a compaction threshold or prevent context overflow. if profile.context_windows: ctx = dict(profile.context_windows) if not ctx.get("sonnet_1m"): @@ -452,7 +452,8 @@ def add( api_key: API key (required for ``api-key`` profiles). base_url: Anthropic-compatible base URL (``api-key`` profiles). models: Optional model name overrides (e.g., {"opus": "glm-5.2[1m]", "sonnet": "glm-4.7"}). - context_windows: Optional context window sizes per model (in tokens). + context_windows: Optional context-window metadata per model (tokens), currently + inert for runtime compaction and SDK window selection. Returns: The created profile. diff --git a/tests/core/test_profiles.py b/tests/core/test_profiles.py index 1d4e8cd..18fe4f4 100644 --- a/tests/core/test_profiles.py +++ b/tests/core/test_profiles.py @@ -253,10 +253,11 @@ def test_context_windows_emitted(self) -> None: assert env["CLAUDETM_CONTEXT_SONNET"] == "128000" def test_context_family_fallback_covers_all_tiers(self) -> None: - """sonnet_1m/fable context inherit their family neighbour so claudetm - compacts in time on custom endpoints whose real context is below the - Claude defaults (otherwise it assumes 1M and never compacts before the - provider's smaller limit -> 'context window limit' crash).""" + """sonnet_1m/fable context env values inherit from sonnet/opus respectively. + + This asserts environment-value propagation, not overflow prevention: + context_windows remains currently inert for runtime compaction. + """ p = Profile( name="zai", type="api-key",