hx-cli 0.2.13__tar.gz → 0.2.14__tar.gz

{hx_cli-0.2.13 → hx_cli-0.2.14}/CHANGELOG.md

@@ -28,6 +28,52 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.14] - 2026-10-04
+
+### Added
+
+- When the installed Claude Code is behind its current release - and so lists older Claude
+  models than your subscription can run - `/model` says so under the list, with the command
+  that updates it (`brew upgrade --cask claude-code` for a Homebrew install, otherwise
+  `claude update`). After updating, the next `/model` lists the new models; no
+  refresh needed.
+
+### Changed
+
+- The model catalogue is refreshed from inside the `/model` picker: press `ctrl+r`. The
+  list updates in place and keeps your filter and selection; the outcome, or why the refresh
+  failed, shows under the list. With no models at all, `/model` now opens anyway and says
+  so, so `ctrl+r` is there to fill it.
+
+### Removed
+
+- `/models refresh`. It sat one letter away from `/model` and did nothing without its one
+  argument; use `ctrl+r` in the `/model` picker.
+
+### Fixed
+
+- On the `claude-code` route, the context window is the one Claude Code reports, not a
+  200k guess: Opus 5.5 runs with 1M. Claude Code lists its models without their sizes, and
+  what it serves depends on the plan, so a model starts at the window it was measured
+  serving on every plan - 1M for Opus 5.5, Sonnet 5.5, Sonnet 5 and Opus 4.7, 200k
+  otherwise - until its first turn reports the real window and maximum output for your
+  account. From then on the context gauge, the compaction threshold, the `/model` picker
+  and later sessions all use it, and a catalogue refresh keeps it.
+- A model Claude Code lists at its long context - Fable 5.1 as `claude-fable-5-1[1m]` -
+  runs at it: `/model` offers `claude-code/claude-fable-5-1[1m]` at 1M, where HX used to
+  drop the `[1m]` and run the model at its standard context.
+- A turn refused because the model, or its 1M context, needs usage credits your Claude plan
+  has off no longer reads "usage limit is reached. It resets at ...": HX says what needs the
+  credits, where to turn them on, and which model runs without them. Once they are on, the
+  next turn runs.
+- After a catalogue refresh (`ctrl+r` in `/model`, or signing in), the session in progress
+  measures its context against the refreshed window, not the one it started with.
+- `/model anthropic` (or typing `anthropic` in the picker) lists the Claude models your Claude
+  Code subscription runs, first, ahead of the per-token OpenRouter ones; `openai` does the same
+  for Codex. Several words match in any order: `/model anthropic sonnet`.
+
+---
+
 ## [0.2.13] - 2026-10-04
 
 ### Added
@@ -833,7 +879,8 @@ First release, published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/)
 - `/configure` and `hx auth` for the OpenRouter key, `hx upgrade` for
   self-update, and `install.sh` bootstrapping uv with a pinned Python.
 
-[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.13...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.14...HEAD
+[0.2.14]: https://github.com/aletisunil/hx/compare/v0.2.13...v0.2.14
 [0.2.13]: https://github.com/aletisunil/hx/compare/v0.2.12...v0.2.13
 [0.2.12]: https://github.com/aletisunil/hx/compare/v0.2.11...v0.2.12
 [0.2.11]: https://github.com/aletisunil/hx/compare/v0.2.10...v0.2.11

{hx_cli-0.2.13 → hx_cli-0.2.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.2.13
+Version: 0.2.14
 Summary: HX - an agent harness for the terminal
 Project-URL: Homepage, https://hx.sunilaleti.dev
 Project-URL: Documentation, https://hx.sunilaleti.dev
@@ -156,7 +156,7 @@ reach it at all.
 
 **Which Codex models you get** is decided by your ChatGPT account, not by HX.
 Signing in fetches the account's own list from the Codex backend, and `/model`
-offers exactly that; `/models refresh` asks again. Entitlement is per model —
+offers exactly that; ctrl+r in `/model` asks again. Entitlement is per model -
 the same `plus` account can run `gpt-5.6-sol` and be refused `gpt-5.3-codex` —
 so a model the picker does not list is one the subscription does not cover.
 
@@ -218,7 +218,7 @@ you to sign in again. On a machine with no browser at all, a session token in
 `HX_DEVIN_API_KEY` or `DEVIN_API_KEY` is used when nothing is saved.
 
 Signing in fetches the account's own model list, and `/model` offers exactly
-that; `/models refresh` asks again. Devin publishes each reasoning depth as a
+that; ctrl+r in `/model` asks again. Devin publishes each reasoning depth as a
 model of its own - Claude Opus 5 High, Claude Opus 5 Max - and HX folds each
 family into one model, so `/effort` picks the depth on Devin exactly as it does
 on Codex. A fast lane or a 1M-context lane stays a separate model, since it
@@ -264,8 +264,15 @@ rest - are removed from its environment; its TLS settings are kept (see
 `claude` other than the one on `PATH`.
 
 `/model` offers the models Claude Code lists for the account, each with the
-efforts it accepts for `/effort`; `/models refresh` asks again. When a usage
-limit is reached, HX says which one and when it resets.
+efforts it accepts for `/effort`; ctrl+r in `/model` asks again. A model Claude
+Code runs at its long context keeps `[1m]` in its id
+(`claude-code/claude-fable-5-1[1m]`), exactly as Claude Code's own `/model` runs
+it. Claude Code lists no context sizes, so a model starts at the window it was
+measured serving on every plan - 1M for Opus 5.5, Sonnet 5.5, Sonnet 5 and Opus
+4.7, otherwise 200k - and from its first turn uses the window Claude Code
+reports for your account. When a usage limit is reached, HX says which one and
+when it resets; when a model or its 1M context needs usage credits your plan
+has off, HX says that instead, and what to pick without them.
 
 **Web search.** Optional, and the one credential that is not a model route.
 It powers two tools:
@@ -421,7 +428,7 @@ be rebound (see [Keybindings](#keybindings)).
 | `ctrl+d` | exit, when the prompt is empty |
 | `shift+tab` | cycle permission mode |
 | `ctrl+p` | command palette |
-| `ctrl+l` | model picker |
+| `ctrl+l` | model picker; inside it, `ctrl+r` fetches the catalogue again |
 | `ctrl+o` | expand tool output (also `ctrl+r`) |
 | `ctrl+t` | show the current plan |
 | `ctrl+x` | copy the selected message to the clipboard |
@@ -527,8 +534,7 @@ silently resolved.
 
 | Command | Does |
 |---|---|
-| `/model [query]` | pick a model; shows context window, price per Mtok, cache support |
-| `/models refresh` | re-fetch the catalogue |
+| `/model [query]` | pick a model; shows context window, price per Mtok, cache support. `ctrl+r` in the picker re-fetches the catalogue |
 | `/effort [level]` | how hard a reasoning model thinks, from the levels it offers |
 | `/configure` | session settings and the API key |
 | `/login [provider]` | sign in to a model route |

{hx_cli-0.2.13 → hx_cli-0.2.14}/README.md

@@ -115,7 +115,7 @@ reach it at all.
 
 **Which Codex models you get** is decided by your ChatGPT account, not by HX.
 Signing in fetches the account's own list from the Codex backend, and `/model`
-offers exactly that; `/models refresh` asks again. Entitlement is per model —
+offers exactly that; ctrl+r in `/model` asks again. Entitlement is per model -
 the same `plus` account can run `gpt-5.6-sol` and be refused `gpt-5.3-codex` —
 so a model the picker does not list is one the subscription does not cover.
 
@@ -177,7 +177,7 @@ you to sign in again. On a machine with no browser at all, a session token in
 `HX_DEVIN_API_KEY` or `DEVIN_API_KEY` is used when nothing is saved.
 
 Signing in fetches the account's own model list, and `/model` offers exactly
-that; `/models refresh` asks again. Devin publishes each reasoning depth as a
+that; ctrl+r in `/model` asks again. Devin publishes each reasoning depth as a
 model of its own - Claude Opus 5 High, Claude Opus 5 Max - and HX folds each
 family into one model, so `/effort` picks the depth on Devin exactly as it does
 on Codex. A fast lane or a 1M-context lane stays a separate model, since it
@@ -223,8 +223,15 @@ rest - are removed from its environment; its TLS settings are kept (see
 `claude` other than the one on `PATH`.
 
 `/model` offers the models Claude Code lists for the account, each with the
-efforts it accepts for `/effort`; `/models refresh` asks again. When a usage
-limit is reached, HX says which one and when it resets.
+efforts it accepts for `/effort`; ctrl+r in `/model` asks again. A model Claude
+Code runs at its long context keeps `[1m]` in its id
+(`claude-code/claude-fable-5-1[1m]`), exactly as Claude Code's own `/model` runs
+it. Claude Code lists no context sizes, so a model starts at the window it was
+measured serving on every plan - 1M for Opus 5.5, Sonnet 5.5, Sonnet 5 and Opus
+4.7, otherwise 200k - and from its first turn uses the window Claude Code
+reports for your account. When a usage limit is reached, HX says which one and
+when it resets; when a model or its 1M context needs usage credits your plan
+has off, HX says that instead, and what to pick without them.
 
 **Web search.** Optional, and the one credential that is not a model route.
 It powers two tools:
@@ -380,7 +387,7 @@ be rebound (see [Keybindings](#keybindings)).
 | `ctrl+d` | exit, when the prompt is empty |
 | `shift+tab` | cycle permission mode |
 | `ctrl+p` | command palette |
-| `ctrl+l` | model picker |
+| `ctrl+l` | model picker; inside it, `ctrl+r` fetches the catalogue again |
 | `ctrl+o` | expand tool output (also `ctrl+r`) |
 | `ctrl+t` | show the current plan |
 | `ctrl+x` | copy the selected message to the clipboard |
@@ -486,8 +493,7 @@ silently resolved.
 
 | Command | Does |
 |---|---|
-| `/model [query]` | pick a model; shows context window, price per Mtok, cache support |
-| `/models refresh` | re-fetch the catalogue |
+| `/model [query]` | pick a model; shows context window, price per Mtok, cache support. `ctrl+r` in the picker re-fetches the catalogue |
 | `/effort [level]` | how hard a reasoning model thinks, from the levels it offers |
 | `/configure` | session settings and the API key |
 | `/login [provider]` | sign in to a model route |

{hx_cli-0.2.13 → hx_cli-0.2.14}/src/hx/__init__.py

@@ -1,5 +1,5 @@
 """HX - an agent harness for the terminal."""
 
-__version__ = "0.2.13"
+__version__ = "0.2.14"
 
 __all__ = ["__version__"]

{hx_cli-0.2.13 → hx_cli-0.2.14}/src/hx/agents/subagent.py

@@ -173,6 +173,7 @@ class SubagentRunner:
             model_info=self.models.get_or_default(model) if self.models else None,
             project_context=self.project_context,
             hooks=self.hooks,
+            models=self.models,
         )
         loop.origin = f"{definition.name} subagent"
         return loop

{hx_cli-0.2.13 → hx_cli-0.2.14}/src/hx/cli.py

@@ -291,13 +291,10 @@ class Runtime:
             self.notices.append(f"Model catalogue refresh failed: {describe(exc)}")
             return
         finally:
-            # The loop resolved its model before the refresh, from the cache
-            # being replaced. Left alone it would gauge against yesterday's
-            # context window and decide image support from a cache that did
-            # not record it - until the user happened to switch models.
-            self.loop.model_info = self.models.get_or_default(self.loop.model)
+            self.loop.catalogue_refreshed()
         for label, error in self.models.subscription_errors():
             self.notices.append(f"Could not list this account's {label} models: {error}")
+        self.notices.extend(self.models.subscription_advice())
 
     async def aclose(self) -> None:
         if self.mcp is not None:
@@ -489,6 +486,7 @@ def build_runtime(parsed: ParsedArgs, *, resume: str | None = None) -> Runtime:
         project_context=project_context,
         instructions=instructions,
         hooks=hooks,
+        models=models,
     )
 
     return Runtime(
@@ -1303,6 +1301,8 @@ def _report_models_after_login(provider_id: str) -> None:
         print(f"Could not refresh the model list: {describe(exc)}", file=sys.stderr)
     for label, error in models.subscription_errors():
         print(f"Could not list this account's {label} models: {error}", file=sys.stderr)
+    for advice in models.subscription_advice():
+        print(advice, file=sys.stderr)
 
     available = [m.id for m in models.all() if m.provider_id == provider_id]
     if not available:

{hx_cli-0.2.13 → hx_cli-0.2.14}/src/hx/core/loop.py

@@ -66,7 +66,7 @@ if TYPE_CHECKING:
     from hx.hooks.engine import HookEngine
     from hx.permissions.engine import PermissionEngine
     from hx.providers.base import Provider
-    from hx.providers.models import ModelInfo
+    from hx.providers.models import ModelInfo, ModelRegistry
     from hx.skills.runtime import ActiveSkills
     from hx.tools.registry import ToolRegistry
 
@@ -107,6 +107,7 @@ class AgentLoop:
         project_context: str | None = None,
         instructions: list[Instructions] | None = None,
         hooks: HookEngine | None = None,
+        models: ModelRegistry | None = None,
     ) -> None:
         self.provider = provider
         self.session = session
@@ -124,6 +125,9 @@ class AgentLoop:
         self.instructions = instructions or []
         """The AGENTS.md files folded into ``project_context``, least specific first."""
         self.hooks = hooks
+        self.models = models
+        """Where a window the backend reports is kept, so the picker and the
+        next session start from it rather than from the catalogue's guess."""
         self._cancelled = False
         self._turn_index = 0
         self._steer: list[UserTurn] = []
@@ -155,6 +159,19 @@ class AgentLoop:
             self.compactor.provider = provider
         return previous
 
+    def catalogue_refreshed(self) -> None:
+        """Re-read the model in force from a catalogue that has just changed.
+
+        It was resolved from the one being replaced. Left alone, the window the
+        gauge and the compaction threshold measure against would stay the old
+        one, and image support would be decided from it, until the user
+        happened to switch models.
+        """
+        if self.models is None:
+            return
+        self.model_info = self.models.get_or_default(self.model)
+        self.session.usage.context_window = self.model_info.context_window
+
     def set_model(self, model_id: str, model_info: ModelInfo | None = None) -> None:
         self.session.meta.model = model_id
         self.model_info = model_info
@@ -450,6 +467,7 @@ class AgentLoop:
                 if isinstance(item, StreamEnd):
                     stop_reason = item.stop_reason
                     usage = item.usage
+                    self._adopt_limits(item)
                     continue
                 if not isinstance(item, StreamDelta):  # pragma: no cover - defensive
                     continue
@@ -581,6 +599,26 @@ class AgentLoop:
         blocks.extend(tool_calls)
         return assistant_message(blocks, model=self.model)
 
+    def _adopt_limits(self, end: StreamEnd) -> None:
+        """Take the window the backend reported over the catalogue's figure.
+
+        Before the usage update that follows, so the gauge it drives - and the
+        compaction threshold measured against the same window - move together.
+        Kept in the catalogue too, by every mode and every subagent alike: a
+        figure only the live session knew would be the guess again next time.
+        """
+        info = self.model_info
+        if info is None or info.id != self.model:
+            return
+        window = end.context_window or info.context_window
+        output = end.max_output_tokens or info.max_output_tokens
+        if (window, output) == (info.context_window, info.max_output_tokens):
+            return
+        self.model_info = replace(info, context_window=window, max_output_tokens=output)
+        self.session.usage.context_window = window
+        if self.models is not None:
+            self.models.adopt_limits(info.id, window, output)
+
     def _record_usage(
         self,
         usage: TurnUsage,

{hx_cli-0.2.13 → hx_cli-0.2.14}/src/hx/providers/base.py

@@ -38,6 +38,11 @@ class StreamDelta:
 class StreamEnd:
     stop_reason: StopReason
     usage: TurnUsage = field(default_factory=TurnUsage)
+    context_window: int | None = None
+    """The model's window as the backend reported it running this turn, when
+    it does. Truer than the catalogue's figure, which for some routes is a
+    guess: Claude Code lists its models without their sizes."""
+    max_output_tokens: int | None = None
 
 
 StreamItem = StreamDelta | StreamEnd

{hx_cli-0.2.13 → hx_cli-0.2.14}/src/hx/providers/claude_code.py

@@ -51,6 +51,7 @@ from hx.core.usage import TurnUsage
 from hx.net import with_tls_hint
 from hx.providers import claude_code_transcript as transcript
 from hx.providers.base import ProviderError, ProviderRequest, StreamDelta, StreamEnd, StreamItem
+from hx.providers.claude_code_catalogue import DATED
 from hx.providers.claude_code_cli import CliProcess, Exit, ServedTool, ToolServer
 
 PROVIDER_ID = cc_auth.PROVIDER_ID
@@ -435,7 +436,7 @@ class ClaudeCodeProvider:
             frame = await frames.get()
             if isinstance(frame, Exit):
                 conversation.state = State.DEAD
-                raise ProviderError(_exit_message(frame, turn.rate_limit))
+                raise ProviderError(_exit_message(frame, turn.rate_limit, request.model))
             kind = frame.get("type")
             if kind == "stream_event" and frame.get("parent_tool_use_id") is None:
                 for item in turn.consume(frame.get("event") or {}):
@@ -465,7 +466,13 @@ class ClaudeCodeProvider:
                 payload = from_payload(turn)
                 if payload is not None:
                     yield payload
-                yield StreamEnd(turn.stop_reason(), turn.finish_usage(started))
+                window, output = _reported_limits(frame, request.model)
+                yield StreamEnd(
+                    turn.stop_reason(),
+                    turn.finish_usage(started),
+                    context_window=window,
+                    max_output_tokens=output,
+                )
                 return
 
     def _remember(self, conversation: Conversation, turn: _Turn) -> None:
@@ -800,6 +807,30 @@ def _wire_model(model_id: str) -> str:
     return model_id[len(MODEL_PREFIX) :] if model_id.startswith(MODEL_PREFIX) else model_id
 
 
+def _reported_limits(frame: dict[str, Any], model_id: str) -> tuple[int | None, int | None]:
+    """``(contextWindow, maxOutputTokens)`` Claude Code reports for the model run.
+
+    ``modelUsage`` is keyed by the resolved name, and lists every model the
+    turn touched - one Claude Code chose for itself among them - so only the
+    entry for the model asked for is taken. Started by alias (``opus``), that
+    entry cannot be told apart and nothing is taken.
+    """
+    wanted = _wire_model(model_id)
+    usage = frame.get("modelUsage")
+    for name, entry in usage.items() if isinstance(usage, dict) else ():
+        if not isinstance(entry, dict):
+            continue
+        names = {DATED.sub("", str(n)) for n in (name, entry.get("canonicalModel")) if n}
+        if wanted not in names:
+            continue
+        window, output = entry.get("contextWindow"), entry.get("maxOutputTokens")
+        return (
+            window if isinstance(window, int) and window > 0 else None,
+            output if isinstance(output, int) and output > 0 else None,
+        )
+    return None, None
+
+
 def _private_file(text: str) -> Path:
     fd, name = tempfile.mkstemp(prefix="hx-claude-", suffix=".md")
     with os.fdopen(fd, "w", encoding="utf-8") as handle:
@@ -833,7 +864,9 @@ def _startup_failure(message: str, cli: CliProcess) -> str:
     return with_tls_hint(f"Claude Code failed to start: {message}")
 
 
-def _exit_message(frame: Exit, rate_limit: dict[str, Any] | None) -> str:
+def _exit_message(frame: Exit, rate_limit: dict[str, Any] | None, model_id: str) -> str:
+    if _needs_credits(rate_limit, frame.stderr):
+        return _credits_message(model_id, frame.stderr.strip())
     if rate_limit:
         return _limit_message(rate_limit)
     detail = frame.stderr.strip()
@@ -849,6 +882,8 @@ def _result_error(
     errors = frame.get("errors")
     text = "; ".join(str(e) for e in errors) if isinstance(errors, list) and errors else ""
     text = text or str(frame.get("result") or frame.get("subtype") or "unknown error")
+    if _needs_credits(rate_limit, text):
+        return _credits_message(request.model, text)
     if _billed_as_extra_usage(frame, text, rate_limit):
         return _extra_usage_message(request, text)
     if rate_limit or "usage limit" in text.lower() or "out of extra usage" in text.lower():
@@ -858,6 +893,40 @@ def _result_error(
     return with_tls_hint(f"Claude Code: {text.strip()}")
 
 
+def _needs_credits(rate_limit: dict[str, Any] | None, text: str) -> bool:
+    """A turn refused because the model, or its long context, needs usage credits.
+
+    Claude Code reports it as a rejected rate limit, with the billing period's
+    reset beside it, but no usage window is reached: the plan does not include
+    what was asked for, and it fails the same way until credits are turned on.
+    """
+    if (rate_limit or {}).get("errorCode") == "credits_required":
+        return True
+    lowered = text.lower()
+    return "requires usage credits" in lowered or "usage credits required" in lowered
+
+
+def _credits_message(model_id: str, detail: str) -> str:
+    """Said in HX's words alone: Claude Code's own adds a link meant for its
+    CLI and advice for flags HX sets itself."""
+    model = _wire_model(model_id)
+    base = model.removesuffix("[1m]")
+    lowered = detail.lower()
+    # Asked for at 1M, it is the long context that needs them - unless what was
+    # said names the model itself: "Fable 5.1 requires usage credits".
+    names_model = "requires usage credits" in lowered
+    if "1m context" in lowered or "long context" in lowered or (model != base and not names_model):
+        what = f"The 1M context of {base} needs"
+        instead = f"pick {MODEL_PREFIX}{base} for its standard context"
+    else:
+        what = f"{base} needs"
+        instead = "pick another model"
+    return (
+        f"{what} usage credits, which your Claude plan has off - its usage limits are not "
+        f"reached. Turn them on at claude.ai/settings/usage and send again, or {instead}."
+    )
+
+
 def _billed_as_extra_usage(
     frame: dict[str, Any], text: str, rate_limit: dict[str, Any] | None
 ) -> bool: