@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.
- package/.env.example +19 -14
- package/CONFIG_ARCHITECTURE.md +2002 -0
- package/NOTICE +1 -1
- package/README.md +233 -94
- package/agents/builtin/build.md +73 -0
- package/agents/builtin/general.md +80 -0
- package/agents/builtin/plan.md +23 -5
- package/agents/builtin/test.md +65 -0
- package/agents/builtin/writer.md +67 -0
- package/agents/manager.py +261 -195
- package/agents/subagent_tool.py +277 -43
- package/agents/tui_commands.py +7 -12
- package/bin/venastine.mjs +528 -382
- package/bin/venastine.py +71 -0
- package/cli_commands.py +835 -0
- package/config.py +95 -1198
- package/config.yaml +1090 -0
- package/config_edit.py +1301 -0
- package/config_schema.py +966 -0
- package/config_update.py +749 -0
- package/core/agent_activity.py +158 -20
- package/core/ansi.py +452 -0
- package/core/approval.py +27 -5
- package/core/call_view.py +364 -0
- package/core/cancel.py +121 -0
- package/core/chatgpt_auth.py +747 -0
- package/core/claims_view.py +107 -0
- package/core/client.py +1238 -82
- package/core/commands.py +454 -0
- package/core/compaction.py +830 -66
- package/core/config_loader.py +516 -97
- package/core/connect.py +686 -0
- package/core/events.py +68 -6
- package/core/file_mentions.py +280 -0
- package/core/interaction.py +87 -4
- package/core/line_pattern.py +128 -0
- package/core/loop.py +1516 -440
- package/core/memory.py +120 -8
- package/core/pipeline_models.py +23 -9
- package/core/provider_errors.py +234 -0
- package/core/reasoning/confidence_scoring.py +70 -54
- package/core/reasoning/json_retry.py +19 -1
- package/core/reasoning/orchestrator.py +232 -53
- package/core/reasoning/output_writer.py +90 -31
- package/core/reasoning/payload_validation.py +133 -7
- package/core/reasoning/pipeline_storage.py +427 -361
- package/core/reasoning/review.py +659 -615
- package/core/reasoning/scholar.py +38 -14
- package/core/reasoning/source_corpus.py +110 -4
- package/core/replay.py +158 -26
- package/core/session.py +36 -12
- package/core/session_view.py +259 -0
- package/core/session_wake.py +259 -0
- package/core/shell_sessions.py +1553 -0
- package/core/workspace_trust.py +1 -1
- package/credentials.py +308 -180
- package/database.py +82 -1
- package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
- package/docs/SECURITY.md +108 -0
- package/docs/THIRD_PARTY_NOTICES.md +148 -0
- package/env_secrets.py +118 -77
- package/json_store.py +236 -16
- package/logging_setup.py +121 -11
- package/main.py +1671 -199
- package/mcp_client/client.py +257 -23
- package/mcp_client/config.py +484 -379
- package/mcp_client/registration.py +163 -2
- package/memories/manager.py +15 -0
- package/memories/tui_commands.py +7 -12
- package/package.json +234 -4
- package/project_init/config_files.py +4 -0
- package/project_init/generator.py +201 -37
- package/project_init/manifest.py +418 -406
- package/project_init/tui_commands.py +7 -4
- package/prompts/revalidate.md +1 -1
- package/prompts/revise.md +17 -15
- package/prompts/system_prompts.py +64 -10
- package/providers.json.example +94 -92
- package/pyproject.toml +51 -2
- package/requirements.txt +252 -29
- package/safety/policy_enforcement.py +353 -17
- package/security/askpass.py +419 -0
- package/security/capability.py +37 -7
- package/security/confine.py +484 -0
- package/security/hosted.py +182 -0
- package/security/permissions.py +54 -7
- package/security/posture.py +124 -12
- package/security/protected_paths.py +198 -6
- package/security/sandbox.py +3262 -139
- package/security/secrets.py +855 -0
- package/skills/tui_commands.py +3 -4
- package/storage.py +368 -35
- package/tools/base.py +465 -305
- package/tools/builtin/_math_common.py +306 -16
- package/tools/builtin/_net_common.py +267 -61
- package/tools/builtin/arxiv.py +681 -223
- package/tools/builtin/ask_user.py +231 -213
- package/tools/builtin/discrete_math.py +35 -4
- package/tools/builtin/fetch_url.py +239 -21
- package/tools/builtin/file_ops.py +341 -33
- package/tools/builtin/geometry.py +184 -148
- package/tools/builtin/get_time.py +2 -2
- package/tools/builtin/linear_algebra.py +66 -23
- package/tools/builtin/load_skill.py +10 -0
- package/tools/builtin/logic.py +171 -12
- package/tools/builtin/pin.py +46 -12
- package/tools/builtin/probability_stats.py +224 -228
- package/tools/builtin/project_docs.py +80 -21
- package/tools/builtin/remember.py +21 -4
- package/tools/builtin/shell.py +586 -67
- package/tools/builtin/shell_sessions.py +613 -0
- package/tools/builtin/symbolic_math.py +80 -10
- package/tools/builtin/todo.py +5 -3
- package/tools/builtin/web_search.py +329 -151
- package/tools/context.py +23 -0
- package/tools/isolation.py +387 -314
- package/tools/registry.py +347 -30
- package/tui/app.py +4645 -438
- package/tui/app.tcss +185 -2
- package/tui/commands.py +10 -154
- package/tui/diffs.py +286 -265
- package/tui/hosted_driver.py +102 -0
- package/tui/markdown.py +60 -10
- package/tui/meters.py +103 -7
- package/tui/screens.py +346 -92
- package/tui/themes.py +59 -19
- package/tui/widgets.py +1575 -111
- package/SECURITY.md +0 -88
- 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
|
-
|
|
49
|
-
|
|
50
|
-
|
|
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
|
|
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(
|
|
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,
|
|
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]:
|
package/core/pipeline_models.py
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
"""
|
|
2
2
|
core/pipeline_models.py
|
|
3
3
|
|
|
4
|
-
The
|
|
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
|
-
|
|
23
|
-
RM4's reason: a writer serialising only its own role would
|
|
24
|
-
the
|
|
25
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|