@yahyahammad/venastine 0.2.0 → 0.3.8

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 (129) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +233 -94
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +277 -43
  12. package/agents/tui_commands.py +7 -12
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +158 -20
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1238 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +830 -66
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +1516 -440
  38. package/core/memory.py +120 -8
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +158 -26
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1671 -199
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +7 -12
  70. package/package.json +234 -4
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +51 -2
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +353 -17
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +368 -35
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +347 -30
  118. package/tui/app.py +4645 -438
  119. package/tui/app.tcss +185 -2
  120. package/tui/commands.py +10 -154
  121. package/tui/diffs.py +286 -265
  122. package/tui/hosted_driver.py +102 -0
  123. package/tui/markdown.py +60 -10
  124. package/tui/meters.py +103 -7
  125. package/tui/screens.py +346 -92
  126. package/tui/themes.py +59 -19
  127. package/tui/widgets.py +1575 -111
  128. package/SECURITY.md +0 -88
  129. package/THIRD_PARTY_NOTICES.md +0 -100
package/core/memory.py CHANGED
@@ -14,7 +14,9 @@ Neutral shapes stored in self._messages:
14
14
  assistant: {"role": "assistant", "text": "...", "tool_calls": [
15
15
  {"id": "...", "name": "...", "input": {...}}, ...]}
16
16
  tool: {"role": "tool", "tool_call_id": "...", "content": "..."}
17
- (one entry per individual tool result)
17
+ (one entry per individual tool result; plus "images": [
18
+ {"media_type": "...", "data": "<base64>"}, ...] only when a
19
+ tool attached one -- ROADMAP_v3 §81)
18
20
 
19
21
  PERSISTENCE, AND WHY THERE'S NO NORMALIZATION STEP HERE:
20
22
  Each add_* method passes storage.save_message() only the PAYLOAD that
@@ -45,9 +47,18 @@ from typing import Optional
45
47
  from uuid import UUID
46
48
 
47
49
  from storage import (
48
- create_thread, get_thread, save_message, get_session_history,
49
- update_thread_extra, latest_checkpoint, pinned_through,
50
- message_ids_from, set_pinned, turn_start_ids, THREAD_KIND_CHAT,
50
+ THREAD_KIND_CHAT,
51
+ create_thread,
52
+ get_session_history,
53
+ get_thread,
54
+ latest_checkpoint,
55
+ mark_turn_failed,
56
+ message_ids_from,
57
+ pinned_through,
58
+ save_message,
59
+ set_pinned,
60
+ turn_start_ids,
61
+ update_thread_extra,
51
62
  )
52
63
 
53
64
  # ROADMAP_v2 §21 (M8). How a compaction summary is introduced to the model.
@@ -70,9 +81,32 @@ SUMMARY_PREFIX = (
70
81
  )
71
82
 
72
83
 
84
+ def _require_harness_record(harness) -> None:
85
+ if not isinstance(harness, dict) or not harness.get("kind"):
86
+ raise ValueError(
87
+ "a harness message needs its record -- a dict with a `kind` -- "
88
+ "or it is indistinguishable from something the person wrote")
89
+
90
+
91
+ def append_harness_row(thread_id: UUID, text: str, harness: dict) -> None:
92
+ """ROADMAP_v3 §49 (SS6). The same row `add_harness_message` writes, for a
93
+ thread no ConversationMemory in this process holds.
94
+
95
+ The quit path needs it: a session belongs to the thread that STARTED it,
96
+ which need not be the one on screen, and building a ConversationMemory
97
+ just to append one row would load and derive that thread's whole view to
98
+ throw it away. Like every writer here, it knows no SQL.
99
+ """
100
+ _require_harness_record(harness)
101
+ save_message(thread_id, role="user", content=text, harness=harness)
102
+
103
+
73
104
  class ConversationMemory:
74
105
  def __init__(self, thread_id: Optional[UUID] = None,
75
- kind: str = THREAD_KIND_CHAT) -> None:
106
+ kind: str = THREAD_KIND_CHAT, *,
107
+ parent_thread_id: Optional[UUID] = None,
108
+ parent_call_id: Optional[str] = None,
109
+ agent_name: Optional[str] = None) -> None:
76
110
  """`kind` (§27 T1) says what a NEW thread is, and is forwarded to
77
111
  storage.create_thread and nowhere else.
78
112
 
@@ -81,13 +115,26 @@ class ConversationMemory:
81
115
  data exists -- that boundary is storage.py's. Ignored when
82
116
  `thread_id` is given, because resuming does not reclassify: a
83
117
  thread's kind was decided when it was created.
118
+
119
+ The three lineage arguments (§47) are forwarded the same way and
120
+ are ignored on a resume for the same reason: who spawned a thread
121
+ was settled when it was created, and reopening it settles nothing.
122
+ Keyword-only, so a caller that does not know it is creating a
123
+ child cannot say it is by filling a positional slot.
84
124
  """
85
125
  # Session-scoped billing (#4): zero on EVERY construction, fresh or
86
126
  # resumed -- see record_billed for why this one is deliberately not
87
127
  # extra_data like its neighbour.
88
128
  self.billed_tokens = 0
129
+ # ROADMAP_v3 §81 (IM3). Images a tool attached for a call whose
130
+ # result has not been written yet, keyed by the call's id.
131
+ # add_tool_result takes them into the row it writes; nothing else
132
+ # reads this, and it is never persisted on its own.
133
+ self._pending_images: dict[str, list] = {}
89
134
  if thread_id is None:
90
- self.thread_id = create_thread(kind=kind)
135
+ self.thread_id = create_thread(
136
+ kind=kind, parent_thread_id=parent_thread_id,
137
+ parent_call_id=parent_call_id, agent_name=agent_name)
91
138
  self._messages: list[dict] = []
92
139
  self._extra: dict = {}
93
140
  self._kind = kind
@@ -305,11 +352,49 @@ class ConversationMemory:
305
352
  else:
306
353
  self._extra[key] = value
307
354
 
355
+ def mark_turn_failed(self, error: str) -> None:
356
+ """Batch 91. Record that the run this thread's newest user message
357
+ started FAILED, and why -- write-through, like every add_* method.
358
+
359
+ On the user row because that is what names the turn; see
360
+ storage.MessageLog.error for why it is a column and not a row. The
361
+ in-memory entry carries it too, for §44's reason on `thinking`: a
362
+ live turn and a resumed one must hand every reader the same shape,
363
+ and a resumed thread gets the key from storage._to_neutral. Nothing
364
+ that builds a request reads it -- _messages_for_provider takes a user
365
+ row's `content` alone.
366
+ """
367
+ mark_turn_failed(self.thread_id, error)
368
+ for entry in reversed(self._messages):
369
+ if entry.get("role") == "user":
370
+ entry["error"] = error
371
+ break
372
+
308
373
  def add_user_message(self, text: str) -> None:
309
374
  entry = {"role": "user", "content": text}
310
375
  self._messages.append(entry)
311
376
  save_message(self.thread_id, role="user", content=text)
312
377
 
378
+ def add_harness_message(self, text: str, harness: dict) -> None:
379
+ """ROADMAP_v3 §49 (SS5). A message the HARNESS wrote to start a turn --
380
+ a background session's result, or the record that one was killed --
381
+ write-through like every add_* method.
382
+
383
+ A user-role entry, because that is the only shape the model can be
384
+ handed between turns (storage.MessageLog.harness says why), marked so
385
+ replay and the compactor can tell it from the person. Nothing that
386
+ builds a request reads the mark, and it never carries a tool_call_id.
387
+
388
+ The record is REQUIRED. A harness message without one would be a
389
+ user message the harness wrote and nobody could tell apart -- the
390
+ exact confusion M8 names for the compaction summary.
391
+ """
392
+ _require_harness_record(harness)
393
+ entry = {"role": "user", "content": text, "harness": harness}
394
+ self._messages.append(entry)
395
+ save_message(self.thread_id, role="user", content=text,
396
+ harness=harness)
397
+
313
398
  def add_assistant_message(self, response) -> None:
314
399
  """
315
400
  Takes the NORMALIZED ModelResponse from
@@ -356,14 +441,41 @@ class ConversationMemory:
356
441
  thinking=thinking,
357
442
  )
358
443
 
444
+ def attach_image(self, tool_call_id: str, media_type: str,
445
+ data: str) -> None:
446
+ """ROADMAP_v3 §81 (IM3). Hold an image for the result of
447
+ `tool_call_id`, to be written WITH that result's row.
448
+
449
+ The bytes reach the thread this way rather than inside the tool's
450
+ result dict, and that is the design: a result passes the output
451
+ redactor, the tool_result event and every shell's transcript, all of
452
+ which read text. A base64 payload run through the secret patterns can
453
+ be altered -- and an altered image is one the provider rejects -- so
454
+ the exemption from redaction is structural: the bytes never enter
455
+ that path. Only first-party code holding this object can attach; an
456
+ MCP server's result is a dict and cannot.
457
+
458
+ `data` is base64. Nothing is written here: a call that never gets a
459
+ result row never gets its image either.
460
+ """
461
+ self._pending_images.setdefault(tool_call_id, []).append(
462
+ {"media_type": media_type, "data": data})
463
+
359
464
  def add_tool_result(self, tool_call_id: str, result: dict) -> None:
360
465
  result_text = str(result)
361
466
  entry = {"role": "tool", "tool_call_id": tool_call_id, "content": result_text}
467
+ # §81 (IM2). Taken whatever the result says: the tool attaches only
468
+ # on its success path, immediately before returning, so an image
469
+ # pending here belongs to this result.
470
+ images = self._pending_images.pop(tool_call_id, None)
471
+ if images:
472
+ entry["images"] = images
362
473
  self._messages.append(entry)
363
474
  # Persist only the result string. tool_call_id already has its
364
475
  # own column (passed below) -- it doesn't need to also be
365
- # duplicated inside content.
366
- save_message(self.thread_id, role="tool", content=result_text, tool_call_id=tool_call_id)
476
+ # duplicated inside content. The images have their own column too.
477
+ save_message(self.thread_id, role="tool", content=result_text,
478
+ tool_call_id=tool_call_id, images=images)
367
479
 
368
480
  @property
369
481
  def messages(self) -> list[dict]:
@@ -1,7 +1,7 @@
1
1
  """
2
2
  core/pipeline_models.py
3
3
 
4
- The two pipeline model roles that are not the session model, remembered.
4
+ The model roles that are not the session model, remembered.
5
5
 
6
6
  ROADMAP_v2 §45 (SQ7). A research run reaches for three models: the
7
7
  generator (the session pair, `/model`), the CRITIC that grounds and
@@ -19,10 +19,10 @@ import — WS6's argument for `core/model_windows.py`, unchanged, and §25's
19
19
  lesson about a capability the pipeline could not reach. It is equally not
20
20
  `core/session.py`, whose contract is that nothing there reaches disk.
21
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
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
26
  which part in a run — and `model_windows.py` is next door as the example
27
27
  of when a second file is right instead (it holds a different kind of fact,
28
28
  keyed on a pair rather than naming one).
@@ -40,6 +40,17 @@ this harness's embedding calls — claim text and fetched page text — at a
40
40
  provider of its choosing. `embedder_model` and `critic_model` are
41
41
  therefore rejected there BY NAME, like `ensemble_models`, and this
42
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).
43
54
  """
44
55
 
45
56
  import logging
@@ -61,10 +72,12 @@ STORE_VERSION = 1
61
72
  # stored: a typo'd `/embeder` writing a key nothing reads would look like
62
73
  # it worked and change nothing, which is the failure mode this whole
63
74
  # module exists to remove for CRITIC_MODEL.
64
- ROLES = ("critic", "embedder")
75
+ ROLES = ("critic", "embedder", "subagent")
65
76
 
66
- # Which config.py constant answers when the store is silent.
67
- _FALLBACK_ATTR = {"critic": "CRITIC_MODEL", "embedder": "EMBEDDER_MODEL"}
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}
68
81
 
69
82
 
70
83
  def store_path() -> str:
@@ -137,7 +150,8 @@ def resolve(role: str) -> Optional[dict]:
137
150
  chosen = remembered(role)
138
151
  if chosen is not None:
139
152
  return chosen
140
- fallback = getattr(config, _FALLBACK_ATTR[role], None)
153
+ attr = _FALLBACK_ATTR[role]
154
+ fallback = getattr(config, attr, None) if attr else None
141
155
  return fallback if _valid(fallback) else None
142
156
 
143
157
 
@@ -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