claude-dev-env 8.111.4 → 8.112.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/.agents/skills/build-eval/evals/review/README.md +2 -2
  2. package/.agents/skills/build-eval/evals/review/review_eval_support/account.py +166 -0
  3. package/.agents/skills/build-eval/evals/review/review_eval_support/config/constants.py +26 -0
  4. package/.agents/skills/build-eval/evals/review/review_eval_support/execution.py +8 -0
  5. package/.agents/skills/build-eval/evals/review/test_run.py +261 -0
  6. package/_shared/advisor/reference/astra-rung.md +13 -5
  7. package/_shared/advisor/scripts/codex_astra_advisor.py +31 -8
  8. package/_shared/advisor/scripts/codex_astra_preflight.py +70 -14
  9. package/_shared/advisor/scripts/config/advisor_scripts_constants/astra_advisor_constants.py +7 -0
  10. package/_shared/advisor/scripts/tests/test_codex_astra_advisor.py +266 -2
  11. package/_shared/advisor/scripts/tests/test_codex_astra_preflight.py +114 -8
  12. package/_shared/pr-loop/scripts/check_convergence.py +5 -1
  13. package/_shared/pr-loop/scripts/codex_review_account.py +180 -0
  14. package/_shared/pr-loop/scripts/codex_review_scripts_constants/account_constants.py +28 -0
  15. package/_shared/pr-loop/scripts/codex_review_scripts_constants/run_constants.py +3 -1
  16. package/_shared/pr-loop/scripts/run_codex_review.py +144 -15
  17. package/_shared/pr-loop/scripts/test_check_convergence_codex.py +3 -3
  18. package/_shared/pr-loop/scripts/test_codex_review_account.py +355 -0
  19. package/_shared/pr-loop/scripts/test_run_codex_review.py +507 -6
  20. package/docs/account-broker.md +6 -4
  21. package/docs/codex-accounts.md +57 -16
  22. package/docs/rule-guides/question-presentation.md +4 -0
  23. package/docs/second-claude-account.md +1 -1
  24. package/hooks/blocking/final_reply_gate.py +59 -3
  25. package/hooks/blocking/open_tasks_transcript.py +18 -0
  26. package/hooks/blocking/test_final_reply_gate.py +160 -0
  27. package/hooks/features/conduct-gates.md +1 -4
  28. package/hooks/hooks.json +0 -10
  29. package/hooks/hooks_constants/final_reply_gate_constants.py +16 -0
  30. package/hooks/hooks_constants/open_tasks_stop_gate_constants.py +9 -0
  31. package/package.json +1 -1
  32. package/rules/question-presentation.md +1 -1
  33. package/scripts/account_broker.py +122 -27
  34. package/scripts/account_broker_support.py +54 -3
  35. package/scripts/codex_account_choice.py +12 -8
  36. package/scripts/codex_account_chooser.py +110 -0
  37. package/scripts/codex_account_meters.py +43 -4
  38. package/scripts/codex_plan_rules.py +156 -0
  39. package/scripts/dev_env_scripts_constants/account_broker_constants.py +41 -42
  40. package/scripts/dev_env_scripts_constants/codex_account_constants.py +62 -2
  41. package/scripts/dev_env_scripts_constants/test_account_broker_constants.py +359 -2
  42. package/scripts/dev_env_scripts_constants/test_codex_account_constants.py +213 -14
  43. package/scripts/policy_lint/adapter_configuration.py +0 -5
  44. package/scripts/policy_lint/config/constants.py +0 -1
  45. package/scripts/test_account_broker.py +1913 -526
  46. package/scripts/test_account_broker_support.py +77 -0
  47. package/scripts/test_codex_account_meters.py +95 -0
  48. package/scripts/tests/test_adapter_configuration.py +0 -8
  49. package/hooks/blocking/merge_over_review_offer_gate.py +0 -114
  50. package/hooks/blocking/test_merge_over_review_offer_gate.py +0 -138
  51. package/hooks/hooks_constants/merge_over_review_offer_gate_constants.py +0 -34
@@ -0,0 +1,156 @@
1
+ """Plan, credit and floor rules for one Codex account's meters.
2
+
3
+ ::
4
+
5
+ free plan, any room, any credits -> no tier
6
+ unlisted plan, any room, any credits -> no tier
7
+ pro plan, session 5%, week 80% -> luna
8
+ team plan, 40% left -> normal
9
+
10
+ Only a plan on the paid list is chosen. A plan the broker does not list is
11
+ refused the way a missing plan is.
12
+
13
+ This module imports only the Codex constants, so the broker's shared module can
14
+ import it without a cycle.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import os
20
+ from typing import TYPE_CHECKING
21
+
22
+ from dev_env_scripts_constants.codex_account_constants import (
23
+ ALL_CODEX_WEEKLY_FLOOR_DISABLED_TRUTHY_VALUES,
24
+ ALL_FREE_PLAN_TYPES,
25
+ ALL_PAID_PLAN_TYPES,
26
+ ALL_PRO_PLAN_TYPES,
27
+ CODEX_WEEKLY_FLOOR_DISABLED_ENVIRONMENT_VARIABLE,
28
+ FREE_PLAN_REASON_TEMPLATE,
29
+ LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT,
30
+ LUNA_TIER_STOP_PERCENT_LEFT,
31
+ NORMAL_TIER_MINIMUM_PERCENT_LEFT,
32
+ PRO_PLAN_STOP_PERCENT_LEFT,
33
+ TIER_LUNA,
34
+ TIER_NORMAL,
35
+ UNKNOWN_PLAN_REASON_TEMPLATE,
36
+ )
37
+
38
+ if TYPE_CHECKING:
39
+ from dev_env_scripts_constants.account_broker_constants import Meters
40
+
41
+
42
+ def is_codex_weekly_floor_disabled() -> bool:
43
+ setting = os.environ.get(CODEX_WEEKLY_FLOOR_DISABLED_ENVIRONMENT_VARIABLE, "")
44
+ return setting.strip().lower() in ALL_CODEX_WEEKLY_FLOOR_DISABLED_TRUTHY_VALUES
45
+
46
+
47
+ def plan_type_key(meters: Meters | None) -> str | None:
48
+ if meters is None or meters.plan_type is None:
49
+ return None
50
+ return meters.plan_type.strip().casefold()
51
+
52
+
53
+ def is_free_plan(meters: Meters | None) -> bool:
54
+ return plan_type_key(meters) in ALL_FREE_PLAN_TYPES
55
+
56
+
57
+ def is_pro_plan(meters: Meters | None) -> bool:
58
+ return plan_type_key(meters) in ALL_PRO_PLAN_TYPES
59
+
60
+
61
+ def is_paid_plan(meters: Meters | None) -> bool:
62
+ return plan_type_key(meters) in ALL_PAID_PLAN_TYPES
63
+
64
+
65
+ def is_unknown_plan(meters: Meters | None) -> bool:
66
+ """Tell whether a read meter names a plan that is neither listed as paid nor free.
67
+
68
+ Args:
69
+ meters: The account's meters, or None when they could not be read.
70
+
71
+ Returns:
72
+ True when the meters are read and the plan is missing, blank, unknown or
73
+ any name the broker does not list.
74
+ """
75
+ if meters is None:
76
+ return False
77
+ return not is_paid_plan(meters) and not is_free_plan(meters)
78
+
79
+
80
+ def is_refused_plan(meters: Meters | None) -> bool:
81
+ """Tell whether a read meter names a plan the broker never chooses.
82
+
83
+ Args:
84
+ meters: The account's meters, or None when they could not be read.
85
+
86
+ Returns:
87
+ True when the meters are read and the plan is not on the paid list.
88
+ """
89
+ return meters is not None and not is_paid_plan(meters)
90
+
91
+
92
+ def refusal_text(account_name: str, meters: Meters | None) -> str | None:
93
+ """Name why an account on a refused plan is never chosen.
94
+
95
+ Args:
96
+ account_name: The account's name.
97
+ meters: The account's meters, or None when they could not be read.
98
+
99
+ Returns:
100
+ The free-plan text for the free plan, the no-known-plan text for a
101
+ missing, blank, unknown or unlisted plan, or None for a paid plan.
102
+ """
103
+ if is_free_plan(meters):
104
+ return FREE_PLAN_REASON_TEMPLATE.format(name=account_name)
105
+ if is_unknown_plan(meters):
106
+ return UNKNOWN_PLAN_REASON_TEMPLATE.format(name=account_name)
107
+ return None
108
+
109
+
110
+ def _is_at_or_under_floor(room: float | None, floor: float) -> bool:
111
+ return room is not None and room <= floor
112
+
113
+
114
+ def codex_blocking_flags(meters: Meters) -> tuple[bool, bool]:
115
+ """Tell which windows keep an account out of the luna tier.
116
+
117
+ Args:
118
+ meters: The account's read meters.
119
+
120
+ Returns:
121
+ A pair of flags for the session window and the weekly window.
122
+ """
123
+ if meters.has_spendable_credits:
124
+ return False, False
125
+ if is_pro_plan(meters):
126
+ return (
127
+ _is_at_or_under_floor(meters.session_percent_left, PRO_PLAN_STOP_PERCENT_LEFT),
128
+ _is_at_or_under_floor(meters.weekly_percent_left, PRO_PLAN_STOP_PERCENT_LEFT),
129
+ )
130
+ return (
131
+ meters.session_percent_left is not None
132
+ and meters.session_percent_left < LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT,
133
+ _is_at_or_under_floor(meters.weekly_percent_left, LUNA_TIER_STOP_PERCENT_LEFT)
134
+ and not is_codex_weekly_floor_disabled(),
135
+ )
136
+
137
+
138
+ def codex_tier(meters: Meters | None) -> str | None:
139
+ """Pick the tier one account's meters allow.
140
+
141
+ Args:
142
+ meters: The account's meters, or None when they could not be read.
143
+
144
+ Returns:
145
+ The normal or luna tier, or None when the account cannot run.
146
+ """
147
+ if meters is None or meters.tightest_percent_left is None or is_refused_plan(meters):
148
+ return None
149
+ if (
150
+ meters.has_spendable_credits
151
+ or meters.tightest_percent_left > NORMAL_TIER_MINIMUM_PERCENT_LEFT
152
+ ):
153
+ return TIER_NORMAL
154
+ if not any(codex_blocking_flags(meters)):
155
+ return TIER_LUNA
156
+ return None
@@ -20,16 +20,15 @@ from dev_env_scripts_constants.claude_account_constants import (
20
20
  SECOND_SESSION_USED_CEILING_PERCENT,
21
21
  SECOND_WEEKLY_USED_CEILING_PERCENT,
22
22
  )
23
+ from dev_env_scripts_constants.claude_chain_usage_constants import NO_ACCESS_TOKEN_ERROR_TEMPLATE
23
24
  from dev_env_scripts_constants.codex_account_constants import (
24
- ALL_PRO_PLAN_TYPES,
25
25
  CODEX_ACCOUNT_PROFILES_ENVIRONMENT_VARIABLE,
26
26
  CODEX_HOME_ENVIRONMENT_VARIABLE,
27
27
  CODEX_PROFILES_ROOT_ENVIRONMENT_VARIABLE,
28
+ CODEX_WEEKLY_FLOOR_DISABLED_ENVIRONMENT_VARIABLE,
28
29
  LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT,
29
30
  LUNA_TIER_STOP_PERCENT_LEFT,
30
- MAIN_CODEX_HOME_DIRECTORY_NAME,
31
31
  NORMAL_TIER_MINIMUM_PERCENT_LEFT,
32
- TIER_LUNA,
33
32
  TIER_NORMAL,
34
33
  )
35
34
  from dev_env_scripts_constants.shared_tree_constants import (
@@ -38,8 +37,11 @@ from dev_env_scripts_constants.shared_tree_constants import (
38
37
  CONSTANTS_PACKAGE_ANCHOR_DEPTH,
39
38
  PR_LOOP_DIRECTORY_NAME,
40
39
  )
40
+ from codex_plan_rules import codex_blocking_flags, is_pro_plan, refusal_text
41
41
  from shared_tree_paths import resolve_shared_scripts_directory
42
42
 
43
+ ALL_CHOOSE_AND_CHECK_ACTIONS = ("choose", "check")
44
+
43
45
  ALL_CLAUDE_FLOORS = {
44
46
  "main_weekly_used_ceiling": MAIN_WEEKLY_USED_CEILING_PERCENT,
45
47
  "main_session_used_ceiling": MAIN_SESSION_USED_CEILING_PERCENT,
@@ -62,6 +64,17 @@ METER_RATE_LIMIT_COOLDOWN_SECONDS = 300.0
62
64
  WAIT_EXIT_CODE = 3
63
65
  COMMAND_MISSING_EXIT_CODE = 127
64
66
  TIMEOUT_EXIT_CODE = 124
67
+ NO_USABLE_ACCOUNT_EXIT_CODE = 4
68
+ NO_USABLE_ACCOUNT_STATUS = "no_usable_account"
69
+ NO_USABLE_REASON_SEPARATOR = "; "
70
+ SIGN_IN_FAILED_STATUS = "sign_in_failed"
71
+ ALL_SIGN_IN_FAILURE_SIGNATURES: tuple[str, ...] = (
72
+ "stored token expired",
73
+ "authorization failed",
74
+ "organization has status: canceled",
75
+ )
76
+ """Case-insensitive substrings that mark a failed Claude run as a sign-in failure of its account."""
77
+ NO_USABLE_TOKEN_REASON_PREFIX = NO_ACCESS_TOKEN_ERROR_TEMPLATE.partition("{")[0]
65
78
  REPORT_INDENT_SPACES = 2
66
79
  PLACEHOLDER_NAME_SLOT = "{name}"
67
80
  BROKER_STATE_DIRECTORY_NAME = "account-broker"
@@ -73,9 +86,10 @@ ALL_ACCOUNT_ENVIRONMENT_VARIABLES = (
73
86
  CODEX_HOME_ENVIRONMENT_VARIABLE,
74
87
  CODEX_ACCOUNT_PROFILES_ENVIRONMENT_VARIABLE,
75
88
  CODEX_PROFILES_ROOT_ENVIRONMENT_VARIABLE,
89
+ CODEX_WEEKLY_FLOOR_DISABLED_ENVIRONMENT_VARIABLE,
76
90
  PROFILES_ROOT_ENVIRONMENT_VARIABLE,
77
91
  )
78
- """Variables that point the account tools at a developer's own account roots, Codex home and Codex roster."""
92
+ """Variables that point the account tools at a developer's own account roots, Codex home and Codex roster, or lift the Codex weekly floor."""
79
93
  ALL_BATCH_FILE_EXTENSIONS = frozenset({".bat", ".cmd"})
80
94
  CMD_SHELL_METACHARACTERS = "&|<>^%!\"\r\n"
81
95
  CLAUDE_BINARY_NAME = "claude"
@@ -207,12 +221,21 @@ class Meters:
207
221
  weekly_percent_left: float | None
208
222
  weekly_resets_at: datetime | None
209
223
  plan_type: str | None = None
224
+ has_credits: bool = False
225
+ is_credits_unlimited: bool = False
226
+ credit_balance: float | None = None
210
227
 
211
228
  @property
212
229
  def tightest_percent_left(self) -> float | None:
213
230
  all_percentages = (self.session_percent_left, self.weekly_percent_left)
214
231
  return min((each_percent for each_percent in all_percentages if each_percent is not None), default=None)
215
232
 
233
+ @property
234
+ def has_spendable_credits(self) -> bool:
235
+ if self.is_credits_unlimited:
236
+ return True
237
+ return self.has_credits and self.credit_balance is not None and self.credit_balance > 0
238
+
216
239
 
217
240
  @dataclass(frozen=True)
218
241
  class Reading:
@@ -282,22 +305,6 @@ def _claude_blocking_flags(meters: Meters, is_main: bool) -> tuple[bool, bool]:
282
305
  )
283
306
 
284
307
 
285
- def _codex_tier(meters: Meters | None) -> str | None:
286
- if meters is None or meters.tightest_percent_left is None:
287
- return None
288
- if meters.tightest_percent_left > ALL_CODEX_FLOORS["normal_minimum_left"]:
289
- return "normal"
290
- if (
291
- meters.tightest_percent_left > ALL_CODEX_FLOORS["luna_stop_left"]
292
- and (
293
- meters.session_percent_left is None
294
- or meters.session_percent_left >= ALL_CODEX_FLOORS["luna_short_minimum_left"]
295
- )
296
- ):
297
- return "luna"
298
- return None
299
-
300
-
301
308
  def _account_reset(reading: Reading, is_spent: bool = False) -> datetime | None:
302
309
  meters = reading.meters
303
310
  if meters is None:
@@ -307,10 +314,7 @@ def _account_reset(reading: Reading, is_spent: bool = False) -> datetime | None:
307
314
  if reading.account.product is Product.CLAUDE:
308
315
  all_blocking_flags = _claude_blocking_flags(meters, reading.account.is_main)
309
316
  else:
310
- all_blocking_flags = (
311
- meters.session_percent_left is not None and meters.session_percent_left < ALL_CODEX_FLOORS["luna_short_minimum_left"],
312
- _is_at_or_under(meters.weekly_percent_left, ALL_CODEX_FLOORS["luna_stop_left"]),
313
- )
317
+ all_blocking_flags = codex_blocking_flags(meters)
314
318
  all_resets = (meters.session_resets_at, meters.weekly_resets_at)
315
319
  all_blocking_resets = [reset for is_blocking, reset in zip(all_blocking_flags, all_resets) if is_blocking]
316
320
  all_known_resets = [reset for reset in all_blocking_resets if reset is not None]
@@ -322,8 +326,8 @@ def _account_reset(reading: Reading, is_spent: bool = False) -> datetime | None:
322
326
  def _rank_key(reading: Reading) -> tuple[bool, int, bool, float]:
323
327
  room = reading.meters.tightest_percent_left if reading.meters else None
324
328
  priority = reading.account.priority
325
- is_pro_plan = reading.meters is not None and reading.meters.plan_type in ALL_PRO_PLAN_TYPES
326
- return (priority is None, priority or 0, not is_pro_plan, -(room if room is not None else -1.0))
329
+ is_pro_plan_account = is_pro_plan(reading.meters)
330
+ return (priority is None, priority or 0, not is_pro_plan_account, -(room if room is not None else -1.0))
327
331
 
328
332
 
329
333
  def _claude_has_room(reading: Reading) -> bool:
@@ -350,22 +354,6 @@ def _choose_claude(all_available: Sequence[Reading], preferred_command: str | No
350
354
  return Decision("run", chosen.account, None, room_text, TIER_NORMAL)
351
355
 
352
356
 
353
- def _choose_codex(all_available: Sequence[Reading]) -> Decision | None:
354
- all_candidates = sorted(all_available, key=_rank_key)
355
- for each_tier in (TIER_NORMAL, TIER_LUNA):
356
- chosen = _choose_codex_tier(all_candidates, each_tier)
357
- if chosen is not None:
358
- return chosen
359
- return None
360
-
361
-
362
- def _choose_codex_tier(all_candidates: Sequence[Reading], tier: str) -> Decision | None:
363
- for each_reading in all_candidates:
364
- if _codex_tier(each_reading.meters) == tier:
365
- return Decision("run", each_reading.account, None, f"{each_reading.account.name} has {each_reading.meters.tightest_percent_left:g}% left", tier)
366
- return None
367
-
368
-
369
357
  @dataclass(frozen=True)
370
358
  class _RetryTime:
371
359
  at: datetime
@@ -378,9 +366,18 @@ def _unreadable_text(reading: Reading) -> str:
378
366
  return f"{reading.account.name} ({reading.unread_reason})"
379
367
 
380
368
 
369
+ def _refusal_text(reading: Reading) -> str | None:
370
+ if reading.account.product is not Product.CODEX:
371
+ return None
372
+ return refusal_text(reading.account.name, reading.meters)
373
+
374
+
381
375
  def _room_text(reading: Reading, is_spent: bool) -> str:
382
376
  if is_spent or reading.meters is None:
383
377
  return f"{reading.account.name} spent"
378
+ refusal = _refusal_text(reading)
379
+ if refusal is not None:
380
+ return refusal
384
381
  percent_left = reading.meters.tightest_percent_left
385
382
  if percent_left is None:
386
383
  return f"{reading.account.name} percent left unread"
@@ -407,6 +404,8 @@ def _wait_decision(
407
404
  next_check = _RetryTime(now + timedelta(hours=1), is_known_reset=False)
408
405
  all_retry_times = []
409
406
  for each_reading in all_readings:
407
+ if _refusal_text(each_reading) is not None:
408
+ continue
410
409
  is_spent = each_reading.account in all_spent_accounts
411
410
  spent_reset = all_spent_resets.get(each_reading.account) if is_spent else None
412
411
  known_reset = spent_reset or _account_reset(each_reading, is_spent)
@@ -2,7 +2,9 @@
2
2
 
3
3
  Each account signs in under its own Codex home. The picker reads every
4
4
  account's rate-limit windows through ``codex app-server`` and names the account
5
- a job runs on, trying the accounts in roster order.
5
+ a job runs on. Codex accounts carry no priority, so the picker ranks Pro plan
6
+ accounts first, then the accounts with the most room, and roster order breaks
7
+ only an exact tie.
6
8
  """
7
9
 
8
10
  from __future__ import annotations
@@ -10,7 +12,11 @@ from __future__ import annotations
10
12
  from dev_env_scripts_constants.claude_account_constants import LauncherProgram
11
13
 
12
14
  ALL_CODEX_ACCOUNT_NAMES: tuple[str, ...] = ("codex-1", "codex-2", "codex-3", "codex-4")
13
- """Fallback Codex accounts, in try order, when no account list is saved or set."""
15
+ """Fallback Codex accounts for ``sync`` when no list names an account.
16
+
17
+ ``choose`` and ``check`` fall back to them only when ``CODEX_ACCOUNT_PROFILES`` holds
18
+ only separators and no saved list names an account.
19
+ """
14
20
 
15
21
  CODEX_ACCOUNT_PROFILES_ENVIRONMENT_VARIABLE: str = "CODEX_ACCOUNT_PROFILES"
16
22
  """Environment variable naming the account list, comma-separated, over the saved file."""
@@ -113,12 +119,54 @@ NORMAL_TIER_MINIMUM_PERCENT_LEFT: float = 10.0
113
119
  LUNA_TIER_STOP_PERCENT_LEFT: float = 1.0
114
120
  """A Luna fallback job stops once its account is at or below this percent left."""
115
121
 
122
+ CODEX_WEEKLY_FLOOR_DISABLED_ENVIRONMENT_VARIABLE: str = "CODEX_WEEKLY_FLOOR_DISABLED"
123
+ """Environment variable that, when truthy, lifts the Luna stop for the weekly window."""
124
+
125
+ ALL_CODEX_WEEKLY_FLOOR_DISABLED_TRUTHY_VALUES: frozenset[str] = frozenset({"1", "true", "yes", "on"})
126
+ """Case-insensitive settings of the weekly-floor variable that turn the switch on."""
127
+
116
128
  LUNA_TIER_SHORT_WINDOW_MINIMUM_PERCENT_LEFT: float = 20.0
117
129
  """An account with a window shorter than a week runs Luna only with this much of it left."""
118
130
 
119
131
  ALL_PRO_PLAN_TYPES: frozenset[str] = frozenset({"pro", "prolite", "promax"})
120
132
  """Plan types of a personal Codex Pro subscription. The broker tries these accounts first."""
121
133
 
134
+ PRO_PLAN_STOP_PERCENT_LEFT: float = 0.0
135
+ """A Pro plan account without credits stops only once one of its windows has no room left."""
136
+
137
+ ALL_OTHER_PAID_PLAN_TYPES: frozenset[str] = frozenset({"team", "plus", "business", "enterprise", "edu"})
138
+ """Plan types of a paid Codex account that is not on a Pro plan."""
139
+
140
+ ALL_PAID_PLAN_TYPES: frozenset[str] = ALL_PRO_PLAN_TYPES | ALL_OTHER_PAID_PLAN_TYPES
141
+ """Every plan type the broker may choose, in lowercase. A plan outside this set is never chosen, whatever its room or credits. That covers a free, missing, blank or ``unknown`` plan and any name the broker does not list."""
142
+
143
+ ALL_FREE_PLAN_TYPES: frozenset[str] = frozenset({"free"})
144
+ """Plan types of a free Codex account. The broker never chooses one, and a wait reason names the free plan apart from an unlisted one."""
145
+
146
+ CREDITS_KEY: str = "credits"
147
+ """Key under ``rateLimits`` that holds the account's credits."""
148
+
149
+ HAS_CREDITS_KEY: str = "hasCredits"
150
+ """Key under ``credits`` that is true while the account holds credits."""
151
+
152
+ UNLIMITED_CREDITS_KEY: str = "unlimited"
153
+ """Key under ``credits`` that is true while the account's credits have no cap."""
154
+
155
+ CREDIT_BALANCE_KEY: str = "balance"
156
+ """Key under ``credits`` that holds the credit balance, usually as a decimal string."""
157
+
158
+ FREE_PLAN_REASON_TEMPLATE: str = "{name} is on a free plan and is never chosen"
159
+ """Wait-reason text for an account the broker skips because it is on a free plan."""
160
+
161
+ UNKNOWN_PLAN_REASON_TEMPLATE: str = "{name} reports no known plan and is never chosen"
162
+ """Wait-reason text for an account the broker skips because its plan is missing, blank, unknown or not a listed paid plan."""
163
+
164
+ CREDITS_REASON_TEMPLATE: str = "{name} has {percent:g}% left and credits"
165
+ """Run-reason text for an account that runs on credits while its plan windows are at or under the bar."""
166
+
167
+ NAMED_HOME_REASON_TEMPLATE: str = "{name} is the named home and runs whatever room it has left"
168
+ """Run-reason text for a named home on a paid plan that no tier would otherwise allow, so it runs on the lowest tier."""
169
+
122
170
  WEEKLY_WINDOW_MINUTES: int = 10080
123
171
  """Length of the weekly window. Any shorter window is a short window, such as 5 hours."""
124
172
 
@@ -134,6 +182,18 @@ TIER_LUNA: str = "luna"
134
182
  TIER_WAIT: str = "wait"
135
183
  """Picker answer: no account has room, so the job waits."""
136
184
 
185
+ ALL_TIERS_BEST_FIRST: tuple[str, ...] = (TIER_NORMAL, TIER_LUNA)
186
+ """Tiers a Codex choice can run on, best first. A caller that requires one tier accepts the ones before it too."""
187
+
188
+ REQUIRE_TIER_ARGUMENT: str = "--require-tier"
189
+ """Broker argument that names the tier a Codex choice must reach, or the broker waits."""
190
+
191
+ HOME_CODEX_ONLY_MESSAGE: str = "--home applies to the codex product only"
192
+ """Error text when ``--home`` names a home for the Claude product."""
193
+
194
+ HOME_WITH_SPENT_MESSAGE: str = "--home cannot be used with --spent"
195
+ """Error text when one command judges a single home and also marks accounts spent."""
196
+
137
197
  ALL_CODEX_BINARY_CANDIDATE_RELATIVE_PARTS: tuple[tuple[str, ...], ...] = (
138
198
  ("AppData", "Local", "Programs", "OpenAI", "Codex", "bin", "codex.exe"),
139
199
  )