@yahyahammad/venastine 0.2.0 → 0.3.9

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 (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -1,176 +1,190 @@
1
- """
2
- core/pipeline_models.py
3
-
4
- The two pipeline model roles that are not the session model, remembered.
5
-
6
- ROADMAP_v2 §45 (SQ7). A research run reaches for three models: the
7
- generator (the session pair, `/model`), the CRITIC that grounds and
8
- critiques its claims (§11), and — since §45 — the EMBEDDER that scores how
9
- close a source is to the claim it was cited for. Only the first has ever
10
- been reachable without editing installed source. `CRITIC_MODEL` has sat in
11
- `config.py` since §11, which means the routing this project's own
12
- methodology calls essential ("a model checking its own output for errors
13
- shares that model's blind spots") was available only to whoever could edit
14
- the checkout.
15
-
16
- IN `core/`, NOT `tui/preferences.py`, AND THAT IS A LAYERING FACT. The
17
- pipeline reads these and D12 makes the TUI a shell that core must never
18
- import — WS6's argument for `core/model_windows.py`, unchanged, and §25's
19
- lesson about a capability the pipeline could not reach. It is equally not
20
- `core/session.py`, whose contract is that nothing there reaches disk.
21
-
22
- TWO ROLES IN ONE FILE, so both writers read-modify-write. RM4's shape and
23
- RM4's reason: a writer serialising only its own role would silently drop
24
- the other's, each correct in its own test. They are one file rather than
25
- two modules because they are the same KIND of fact — which model plays
26
- which part in a run — and `model_windows.py` is next door as the example
27
- of when a second file is right instead (it holds a different kind of fact,
28
- keyed on a pair rather than naming one).
29
-
30
- PRECEDENCE: THE STORE OUTRANKS `config.py`. The opposite of
31
- `model_windows`, and for the opposite reason — there, a configured value
32
- could be confidently wrong about a deployment, so the person won. Here
33
- `config.py` is the harness's own default and the store is a choice
34
- someone made at a command prompt for this account, which is `/model`
35
- outranking `config.MODEL_NAME` exactly.
36
-
37
- WHY NOT `settings.json`. Choosing a provider is a grant (E2): a project's
38
- settings.json outranks the user's, so a cloned repo could otherwise point
39
- this harness's embedding calls — claim text and fetched page text — at a
40
- provider of its choosing. `embedder_model` and `critic_model` are
41
- therefore rejected there BY NAME, like `ensemble_models`, and this
42
- user-tier store is the route instead.
43
- """
44
-
45
- import logging
46
- import os
47
- from typing import Optional
48
-
49
- import config
50
- from json_store import read_versioned, write_json_atomic
51
-
52
- logger = logging.getLogger(__name__)
53
-
54
- # Bumped when the SHAPE changes. An unknown version reads as an empty
55
- # store, which costs the remembered roles and falls back to config.py --
56
- # there is nothing here that was consented to, so the MCP store's careful
57
- # legacy handling has no counterpart.
58
- STORE_VERSION = 1
59
-
60
- # The roles this store knows. A role outside it is refused rather than
61
- # stored: a typo'd `/embeder` writing a key nothing reads would look like
62
- # it worked and change nothing, which is the failure mode this whole
63
- # module exists to remove for CRITIC_MODEL.
64
- ROLES = ("critic", "embedder")
65
-
66
- # Which config.py constant answers when the store is silent.
67
- _FALLBACK_ATTR = {"critic": "CRITIC_MODEL", "embedder": "EMBEDDER_MODEL"}
68
-
69
-
70
- def store_path() -> str:
71
- # Call time, not import time: tests redirect it, and a moved config
72
- # directory is picked up without a restart. Every sibling store
73
- # resolves theirs the same way.
74
- return os.path.expanduser("~/.config/venastine/pipeline_models.json")
75
-
76
-
77
- def _read_raw() -> dict:
78
- data = read_versioned(store_path(), STORE_VERSION,
79
- "falling back to config.py for pipeline models.")
80
- roles = data.get("roles")
81
- return roles if isinstance(roles, dict) else {}
82
-
83
-
84
- def _write(roles: dict, action: str) -> bool:
85
- """Persist the whole map. True if it reached disk.
86
-
87
- A failure WARNS and returns False rather than raising, matching
88
- model_windows: the TUI routes WARNING+ into the transcript, so someone
89
- whose choice could not be saved is told at the moment they make it
90
- rather than discovering it at the next launch.
91
- """
92
- path = store_path()
93
- try:
94
- write_json_atomic(path, {"version": STORE_VERSION, "roles": roles},
95
- sort_keys=True)
96
- except OSError as exc:
97
- logger.warning("Could not %s the pipeline model in %s (%s).",
98
- action, path, exc)
99
- return False
100
- return True
101
-
102
-
103
- def _valid(entry) -> bool:
104
- """A whole pair or nothing.
105
-
106
- tui/preferences.py's rule, for its reason: a model name means nothing
107
- against the wrong provider, so half a record is no record. A
108
- hand-edited file with only one of the two is ignored rather than
109
- half-applied.
110
- """
111
- return (isinstance(entry, dict)
112
- and isinstance(entry.get("provider_name"), str)
113
- and isinstance(entry.get("model"), str)
114
- and bool(entry["provider_name"]) and bool(entry["model"]))
115
-
116
-
117
- def remembered(role: str) -> Optional[dict]:
118
- """What the user chose for `role`, or None. Ignores config.py."""
119
- entry = _read_raw().get(role)
120
- if not _valid(entry):
121
- return None
122
- return {"provider_name": entry["provider_name"], "model": entry["model"]}
123
-
124
-
125
- def resolve(role: str) -> Optional[dict]:
126
- """The pair actually in force for `role`: the store, else config.py,
127
- else None.
128
-
129
- THE ONE READER FOR THE PIPELINE. `orchestrator` and every shell ask
130
- this rather than reading `config.CRITIC_MODEL` directly, so a
131
- remembered choice reaches the CLI, the TUI and a spawned run alike --
132
- and so there is one precedence rule rather than one per caller.
133
- """
134
- if role not in ROLES:
135
- raise ValueError(f"unknown pipeline model role {role!r}; "
136
- f"expected one of {', '.join(ROLES)}")
137
- chosen = remembered(role)
138
- if chosen is not None:
139
- return chosen
140
- fallback = getattr(config, _FALLBACK_ATTR[role], None)
141
- return fallback if _valid(fallback) else None
142
-
143
-
144
- def remember(role: str, provider_name: str, model: str) -> bool:
145
- """Record a pair for `role`. True if it reached disk."""
146
- if role not in ROLES:
147
- raise ValueError(f"unknown pipeline model role {role!r}; "
148
- f"expected one of {', '.join(ROLES)}")
149
- roles = _read_raw()
150
- roles[role] = {"provider_name": provider_name, "model": model}
151
- return _write(roles, "save")
152
-
153
-
154
- def forget(role: str) -> str:
155
- """Drop `role`'s entry. "removed", "absent" or "failed".
156
-
157
- Three outcomes rather than a bool, following model_windows: the shell
158
- says a different sentence for each, and a failed write reported as
159
- "nothing was set" would be a lie about a file the user can go and
160
- read. Note that "removed" does not mean the role is unset -- config.py
161
- may still answer, and the shell says so.
162
- """
163
- if role not in ROLES:
164
- raise ValueError(f"unknown pipeline model role {role!r}; "
165
- f"expected one of {', '.join(ROLES)}")
166
- roles = _read_raw()
167
- if roles.pop(role, None) is None:
168
- return "absent"
169
- return "removed" if _write(roles, "clear") else "failed"
170
-
171
-
172
- def all_roles() -> dict:
173
- """{role: {"provider_name", "model"}} for every role in force, from
174
- whichever tier answered. For a report."""
175
- return {role: pair for role in ROLES
176
- if (pair := resolve(role)) is not None}
1
+ """
2
+ core/pipeline_models.py
3
+
4
+ The model roles that are not the session model, remembered.
5
+
6
+ ROADMAP_v2 §45 (SQ7). A research run reaches for three models: the
7
+ generator (the session pair, `/model`), the CRITIC that grounds and
8
+ critiques its claims (§11), and — since §45 — the EMBEDDER that scores how
9
+ close a source is to the claim it was cited for. Only the first has ever
10
+ been reachable without editing installed source. `CRITIC_MODEL` has sat in
11
+ `config.py` since §11, which means the routing this project's own
12
+ methodology calls essential ("a model checking its own output for errors
13
+ shares that model's blind spots") was available only to whoever could edit
14
+ the checkout.
15
+
16
+ IN `core/`, NOT `tui/preferences.py`, AND THAT IS A LAYERING FACT. The
17
+ pipeline reads these and D12 makes the TUI a shell that core must never
18
+ import — WS6's argument for `core/model_windows.py`, unchanged, and §25's
19
+ lesson about a capability the pipeline could not reach. It is equally not
20
+ `core/session.py`, whose contract is that nothing there reaches disk.
21
+
22
+ EVERY ROLE IN ONE FILE, so every writer reads, modifies and writes. RM4's
23
+ shape and RM4's reason: a writer serialising only its own role would
24
+ silently drop the others', each correct in its own test. They are one file
25
+ rather than a module each because they are the same KIND of fact — which model plays
26
+ which part in a run — and `model_windows.py` is next door as the example
27
+ of when a second file is right instead (it holds a different kind of fact,
28
+ keyed on a pair rather than naming one).
29
+
30
+ PRECEDENCE: THE STORE OUTRANKS `config.py`. The opposite of
31
+ `model_windows`, and for the opposite reason — there, a configured value
32
+ could be confidently wrong about a deployment, so the person won. Here
33
+ `config.py` is the harness's own default and the store is a choice
34
+ someone made at a command prompt for this account, which is `/model`
35
+ outranking `config.MODEL_NAME` exactly.
36
+
37
+ WHY NOT `settings.json`. Choosing a provider is a grant (E2): a project's
38
+ settings.json outranks the user's, so a cloned repo could otherwise point
39
+ this harness's embedding calls — claim text and fetched page text — at a
40
+ provider of its choosing. `embedder_model` and `critic_model` are
41
+ therefore rejected there BY NAME, like `ensemble_models`, and this
42
+ user-tier store is the route instead.
43
+
44
+ A THIRD ROLE SINCE ROADMAP_v3 §57: `subagent`, set by `/submodel` in
45
+ either shell. It is the model a SPAWNED child runs on when its own file
46
+ pins neither half of a pair (SM6), at every depth and whatever its parent
47
+ runs on (SM7) -- so a cheap child no longer has to run on its parent's
48
+ expensive model. It is the same kind of fact as the other two, which part
49
+ a model plays, and so it shares their file and their read-modify-write.
50
+ It has NO `config.yaml` tier (SM5): `resolve` answers from this store or
51
+ not at all, which is why its `_FALLBACK_ATTR` entry is None rather than a
52
+ constant nobody sets. Nothing else reads it: the compactor, the pipeline
53
+ reviewer and the initializer keep the session model (SM8).
54
+ """
55
+
56
+ import logging
57
+ import os
58
+ from typing import Optional
59
+
60
+ import config
61
+ from json_store import read_versioned, write_json_atomic
62
+
63
+ logger = logging.getLogger(__name__)
64
+
65
+ # Bumped when the SHAPE changes. An unknown version reads as an empty
66
+ # store, which costs the remembered roles and falls back to config.py --
67
+ # there is nothing here that was consented to, so the MCP store's careful
68
+ # legacy handling has no counterpart.
69
+ STORE_VERSION = 1
70
+
71
+ # The roles this store knows. A role outside it is refused rather than
72
+ # stored: a typo'd `/embeder` writing a key nothing reads would look like
73
+ # it worked and change nothing, which is the failure mode this whole
74
+ # module exists to remove for CRITIC_MODEL.
75
+ ROLES = ("critic", "embedder", "subagent")
76
+
77
+ # Which config.py constant answers when the store is silent. None means
78
+ # nothing does: `subagent` is remembered or unset (§57, SM5).
79
+ _FALLBACK_ATTR = {"critic": "CRITIC_MODEL", "embedder": "EMBEDDER_MODEL",
80
+ "subagent": None}
81
+
82
+
83
+ def store_path() -> str:
84
+ # Call time, not import time: tests redirect it, and a moved config
85
+ # directory is picked up without a restart. Every sibling store
86
+ # resolves theirs the same way.
87
+ return os.path.expanduser("~/.config/venastine/pipeline_models.json")
88
+
89
+
90
+ def _read_raw() -> dict:
91
+ data = read_versioned(store_path(), STORE_VERSION,
92
+ "falling back to config.py for pipeline models.")
93
+ roles = data.get("roles")
94
+ return roles if isinstance(roles, dict) else {}
95
+
96
+
97
+ def _write(roles: dict, action: str) -> bool:
98
+ """Persist the whole map. True if it reached disk.
99
+
100
+ A failure WARNS and returns False rather than raising, matching
101
+ model_windows: the TUI routes WARNING+ into the transcript, so someone
102
+ whose choice could not be saved is told at the moment they make it
103
+ rather than discovering it at the next launch.
104
+ """
105
+ path = store_path()
106
+ try:
107
+ write_json_atomic(path, {"version": STORE_VERSION, "roles": roles},
108
+ sort_keys=True)
109
+ except OSError as exc:
110
+ logger.warning("Could not %s the pipeline model in %s (%s).",
111
+ action, path, exc)
112
+ return False
113
+ return True
114
+
115
+
116
+ def _valid(entry) -> bool:
117
+ """A whole pair or nothing.
118
+
119
+ tui/preferences.py's rule, for its reason: a model name means nothing
120
+ against the wrong provider, so half a record is no record. A
121
+ hand-edited file with only one of the two is ignored rather than
122
+ half-applied.
123
+ """
124
+ return (isinstance(entry, dict)
125
+ and isinstance(entry.get("provider_name"), str)
126
+ and isinstance(entry.get("model"), str)
127
+ and bool(entry["provider_name"]) and bool(entry["model"]))
128
+
129
+
130
+ def remembered(role: str) -> Optional[dict]:
131
+ """What the user chose for `role`, or None. Ignores config.py."""
132
+ entry = _read_raw().get(role)
133
+ if not _valid(entry):
134
+ return None
135
+ return {"provider_name": entry["provider_name"], "model": entry["model"]}
136
+
137
+
138
+ def resolve(role: str) -> Optional[dict]:
139
+ """The pair actually in force for `role`: the store, else config.py,
140
+ else None.
141
+
142
+ THE ONE READER FOR THE PIPELINE. `orchestrator` and every shell ask
143
+ this rather than reading `config.CRITIC_MODEL` directly, so a
144
+ remembered choice reaches the CLI, the TUI and a spawned run alike --
145
+ and so there is one precedence rule rather than one per caller.
146
+ """
147
+ if role not in ROLES:
148
+ raise ValueError(f"unknown pipeline model role {role!r}; "
149
+ f"expected one of {', '.join(ROLES)}")
150
+ chosen = remembered(role)
151
+ if chosen is not None:
152
+ return chosen
153
+ attr = _FALLBACK_ATTR[role]
154
+ fallback = getattr(config, attr, None) if attr else None
155
+ return fallback if _valid(fallback) else None
156
+
157
+
158
+ def remember(role: str, provider_name: str, model: str) -> bool:
159
+ """Record a pair for `role`. True if it reached disk."""
160
+ if role not in ROLES:
161
+ raise ValueError(f"unknown pipeline model role {role!r}; "
162
+ f"expected one of {', '.join(ROLES)}")
163
+ roles = _read_raw()
164
+ roles[role] = {"provider_name": provider_name, "model": model}
165
+ return _write(roles, "save")
166
+
167
+
168
+ def forget(role: str) -> str:
169
+ """Drop `role`'s entry. "removed", "absent" or "failed".
170
+
171
+ Three outcomes rather than a bool, following model_windows: the shell
172
+ says a different sentence for each, and a failed write reported as
173
+ "nothing was set" would be a lie about a file the user can go and
174
+ read. Note that "removed" does not mean the role is unset -- config.py
175
+ may still answer, and the shell says so.
176
+ """
177
+ if role not in ROLES:
178
+ raise ValueError(f"unknown pipeline model role {role!r}; "
179
+ f"expected one of {', '.join(ROLES)}")
180
+ roles = _read_raw()
181
+ if roles.pop(role, None) is None:
182
+ return "absent"
183
+ return "removed" if _write(roles, "clear") else "failed"
184
+
185
+
186
+ def all_roles() -> dict:
187
+ """{role: {"provider_name", "model"}} for every role in force, from
188
+ whichever tier answered. For a report."""
189
+ return {role: pair for role in ROLES
190
+ if (pair := resolve(role)) is not None}
@@ -0,0 +1,234 @@
1
+ """
2
+ core/provider_errors.py
3
+
4
+ Which provider failures are worth another attempt, how long to wait before
5
+ it, and the one line that describes a failure (batch 91).
6
+
7
+ WHY THIS IS NOT IN core/client.py. AGENTS.md's ownership table gives
8
+ client.py one call and provider format translation, and says in so many
9
+ words that it does not own retry. The loop owns the attempt; this module
10
+ answers the two questions the attempt asks -- "is this one worth another
11
+ try?" and "how long do I wait?" -- and holds no state of its own.
12
+
13
+ WHY NO SDK IS IMPORTED, HERE OR AT CALL TIME. core/client.py imports each SDK
14
+ lazily inside api_initialization, so a harness configured for one provider
15
+ never loads the other two -- and the suite installs FAKE openai, anthropic,
16
+ google.genai and httpx modules before any test imports anything (the root
17
+ conftest). An isinstance check against a real SDK class would load what
18
+ client.py deliberately does not, and under test would be comparing against
19
+ a fake. So an exception is read by the class names in its MRO and by the
20
+ attributes the SDKs themselves define: `status_code` (openai / anthropic
21
+ APIStatusError), an int `code` (google.genai errors.APIError), `body` (the
22
+ error object an already-open stream carried) and `response.headers`.
23
+
24
+ WHAT COUNTS AS TRANSIENT (owner decision, batch 91):
25
+
26
+ * a connection failure or a timeout -- openai / anthropic
27
+ APIConnectionError and APITimeoutError, an httpx transport error raised
28
+ raw while a stream is being read (and by google-genai, whose transport
29
+ httpx is since 2.x), a requests ConnectionError / Timeout (google-auth's
30
+ token refresh; google-genai 1.0's transport), and the builtin ConnectionError /
31
+ TimeoutError;
32
+ * HTTP 408, 409, 429 and any 5xx -- the statuses the openai and anthropic
33
+ SDKs already retry for themselves before a stream opens;
34
+ * an error event inside a stream that had ALREADY opened with 200. The
35
+ openai SDK raises its base APIError for it, with no status at all;
36
+ anthropic raises APIStatusError carrying the 200 the stream opened with.
37
+ Neither SDK retries it, and that is the gap this module exists for:
38
+ OpenRouter delivered "The service is temporarily unavailable" and
39
+ "Upstream idle timeout exceeded" exactly this way. Retried unless the
40
+ error object itself names a 4xx code or a permanent error type.
41
+
42
+ Everything else is NOT: a bad request, an auth failure or an unknown model
43
+ fails identically on every attempt, and a harness error -- D21's
44
+ RuntimeError, a ValueError from message translation -- is a bug, not
45
+ weather, and retrying it would only delay the traceback.
46
+ """
47
+
48
+ from random import random
49
+ from time import sleep
50
+ from typing import Optional
51
+
52
+ #: Beside any 5xx. The same set the openai and anthropic SDKs retry.
53
+ RETRYABLE_STATUSES = frozenset({408, 409, 429})
54
+
55
+ #: A server's retry-after is honoured up to this, as the SDKs do.
56
+ RETRY_AFTER_CAP_S = 60.0
57
+
58
+ #: Up to a quarter of the delay either way, so parallel siblings that failed
59
+ #: together -- three children of one spawn batch, which is the case that
60
+ #: prompted this -- do not all come back in the same instant.
61
+ JITTER = 0.25
62
+
63
+ #: A transcript line, not a traceback. Long enough for a provider's own
64
+ #: sentence and the error object google-genai folds into its message.
65
+ DESCRIBE_LIMIT = 500
66
+
67
+ _CONNECTION_NAMES = frozenset({
68
+ "APIConnectionError", "APITimeoutError", # openai, anthropic
69
+ "TransportError", "TimeoutException", # httpx: raw mid-stream; google-genai
70
+ "ConnectionError", "Timeout", # requests (google-auth); builtin
71
+ "ChunkedEncodingError", # requests, a body cut off mid-read
72
+ "TimeoutError", # builtin
73
+ })
74
+
75
+ #: Error types an open stream's error object can name. Listed in both
76
+ #: directions rather than inferred from a suffix: openai's "server_error" and
77
+ #: anthropic's "invalid_request_error" share one.
78
+ _TRANSIENT_TYPES = frozenset({
79
+ "overloaded_error", "api_error", "rate_limit_error", "server_error",
80
+ })
81
+ _PERMANENT_TYPES = frozenset({
82
+ "invalid_request_error", "authentication_error", "permission_error",
83
+ "not_found_error", "request_too_large",
84
+ })
85
+
86
+ #: A 200 that failed schema validation is a mismatch between the SDK and the
87
+ #: response, and it will be the same response next time.
88
+ _NEVER_TRANSIENT_NAMES = frozenset({"APIResponseValidationError"})
89
+
90
+
91
+ def _names(exc: BaseException) -> set:
92
+ return {cls.__name__ for cls in type(exc).__mro__}
93
+
94
+
95
+ def _as_status(value) -> Optional[int]:
96
+ if isinstance(value, str) and value.isdigit():
97
+ value = int(value)
98
+ if isinstance(value, int) and not isinstance(value, bool) \
99
+ and 100 <= value < 600:
100
+ return value
101
+ return None
102
+
103
+
104
+ def _retryable_status(status: int) -> bool:
105
+ return status in RETRYABLE_STATUSES or status >= 500
106
+
107
+
108
+ def _status(exc: BaseException, names: set) -> Optional[int]:
109
+ """The HTTP status an exception carries, or None.
110
+
111
+ `code` is read only on something named APIError, because google-genai
112
+ is the one SDK that spells its status that way and the attribute name is
113
+ far too common to trust anywhere else.
114
+ """
115
+ status = _as_status(getattr(exc, "status_code", None))
116
+ if status is None and "APIError" in names:
117
+ status = _as_status(getattr(exc, "code", None))
118
+ return status
119
+
120
+
121
+ def _body_verdict(body) -> Optional[bool]:
122
+ """What an open stream's error object says, or None when it is silent.
123
+
124
+ openai hands over the error object itself (`data["error"]`); anthropic
125
+ hands over the whole event (`{"type": "error", "error": {...}}`), so the
126
+ nested object is preferred when there is one.
127
+ """
128
+ if not isinstance(body, dict):
129
+ return None
130
+ error = body["error"] if isinstance(body.get("error"), dict) else body
131
+ status = _as_status(error.get("code"))
132
+ if status is not None:
133
+ return _retryable_status(status)
134
+ kind = error.get("type")
135
+ if kind in _TRANSIENT_TYPES:
136
+ return True
137
+ if kind in _PERMANENT_TYPES:
138
+ return False
139
+ return None
140
+
141
+
142
+ def is_transient(exc: BaseException) -> bool:
143
+ """Would the same call plausibly succeed if simply made again?"""
144
+ names = _names(exc)
145
+ if names & _NEVER_TRANSIENT_NAMES:
146
+ return False
147
+ if names & _CONNECTION_NAMES:
148
+ return True
149
+ status = _status(exc, names)
150
+ if status is not None and status != 200:
151
+ return _retryable_status(status)
152
+ if "APIError" in names:
153
+ # An error event inside a stream that opened: no status (openai) or
154
+ # the stream's own 200 (anthropic). The provider has said something
155
+ # went wrong mid-generation; unless it also said the request itself
156
+ # is at fault, that is the weather this retry is for.
157
+ return open_stream_error_is_transient(getattr(exc, "body", None))
158
+ return False
159
+
160
+
161
+ def open_stream_error_is_transient(body) -> bool:
162
+ """The open-stream rule above, for a caller holding only the error object.
163
+
164
+ ROADMAP_v3 §83: the ChatGPT plan's `error` event and `response.failed`
165
+ arrive as EVENTS -- the openai SDK raises only on a top-level `error`
166
+ object, which neither has -- so `core/client.py` reads them and asks
167
+ here, rather than keeping a second copy of the rule.
168
+ """
169
+ verdict = _body_verdict(body)
170
+ return True if verdict is None else verdict
171
+
172
+
173
+ def retry_after_s(exc: BaseException) -> Optional[float]:
174
+ """A server's `retry-after`, in seconds, when the failure carried one.
175
+
176
+ Only the delta-seconds form. The HTTP-date form is legal and rare enough
177
+ on these APIs that a date parser here would be code with no caller; an
178
+ unreadable value is simply ignored and the backoff decides.
179
+ """
180
+ headers = getattr(getattr(exc, "response", None), "headers", None)
181
+ if headers is None:
182
+ return None
183
+ try:
184
+ seconds = float(headers.get("retry-after"))
185
+ except (AttributeError, TypeError, ValueError):
186
+ return None
187
+ if seconds < 0:
188
+ return None
189
+ return min(seconds, RETRY_AFTER_CAP_S)
190
+
191
+
192
+ def backoff_delay(retry: int, base_s: float,
193
+ retry_after: Optional[float] = None) -> float:
194
+ """Seconds to wait before retry number `retry` (1-based).
195
+
196
+ `base_s`, doubled for each retry after the first, with JITTER either way
197
+ (owner decision: longer than the SDKs' own half-second start, so a
198
+ temporary rate limit is not met with a burst of attempts).
199
+
200
+ A server's retry-after can make the wait LONGER, never shorter: a
201
+ `retry-after: 0` answering a rate limit is exactly the hammering the
202
+ longer base exists to avoid.
203
+ """
204
+ delay = base_s * (2 ** (retry - 1))
205
+ delay *= 1 + JITTER * (2 * random() - 1)
206
+ if retry_after is not None:
207
+ delay = max(delay, retry_after)
208
+ return delay
209
+
210
+
211
+ def wait(seconds: float) -> None:
212
+ """Sleep before a retry.
213
+
214
+ Through `sleep` bound HERE, so a test patches `core.provider_errors.sleep`
215
+ and reaches nothing else -- AGENTS.md's `from time import monotonic`
216
+ rule: patching the global `time` module froze textual's event loop and
217
+ conftest's `settle` along with it, and the suite hung rather than failed.
218
+ """
219
+ sleep(seconds)
220
+
221
+
222
+ def describe(exc: BaseException) -> str:
223
+ """`Type: message`, on one line -- the ONE spelling of a failure.
224
+
225
+ Shared by the transcript's log handler, the failure stored on a thread
226
+ and the retry warning, so the three never describe the same exception
227
+ three ways. Not redacted: every caller that shows or
228
+ stores it redacts the whole line it is part of.
229
+ """
230
+ text = " ".join(str(exc).split())
231
+ if len(text) > DESCRIBE_LIMIT:
232
+ text = text[:DESCRIBE_LIMIT - 1].rstrip() + "…"
233
+ name = type(exc).__name__
234
+ return f"{name}: {text}" if text else name