agentdevlabs 0.1.0__py3-none-any.whl
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.
- agentdevlabs/__init__.py +7 -0
- agentdevlabs/api_types.py +466 -0
- agentdevlabs/background.py +149 -0
- agentdevlabs/cache.py +113 -0
- agentdevlabs/cache_key.py +69 -0
- agentdevlabs/config.py +95 -0
- agentdevlabs/decrypt.py +18 -0
- agentdevlabs/events.py +93 -0
- agentdevlabs/hook.py +1009 -0
- agentdevlabs/log.py +22 -0
- agentdevlabs/playback.py +173 -0
- agentdevlabs/providers.py +97 -0
- agentdevlabs/recorder.py +226 -0
- agentdevlabs/redact.py +71 -0
- agentdevlabs/replay.py +184 -0
- agentdevlabs/rules.py +55 -0
- agentdevlabs/server.py +446 -0
- agentdevlabs/trace.py +227 -0
- agentdevlabs-0.1.0.dist-info/METADATA +100 -0
- agentdevlabs-0.1.0.dist-info/RECORD +22 -0
- agentdevlabs-0.1.0.dist-info/WHEEL +4 -0
- agentdevlabs-0.1.0.dist-info/licenses/LICENSE +202 -0
agentdevlabs/replay.py
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
import itertools
|
|
2
|
+
import threading
|
|
3
|
+
from collections.abc import Callable
|
|
4
|
+
from concurrent.futures import Future
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
|
|
7
|
+
from .cache import ObjectCache
|
|
8
|
+
from .decrypt import decrypt_object
|
|
9
|
+
from .server import CaptureRef, Decision, Pin, Variation, download_object
|
|
10
|
+
from .trace import Trace
|
|
11
|
+
|
|
12
|
+
Say = Callable[[str], None]
|
|
13
|
+
|
|
14
|
+
DOWNLOADS_AT_ONCE = 4
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
@dataclass(frozen=True)
|
|
18
|
+
class Question:
|
|
19
|
+
step: int
|
|
20
|
+
cache_key: str
|
|
21
|
+
provider: str
|
|
22
|
+
model: str
|
|
23
|
+
is_stream: bool
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass(frozen=True)
|
|
27
|
+
class Choice:
|
|
28
|
+
"""What answers a call: `replay` a stored capture (with a drift note when its key differs;
|
|
29
|
+
`pinned` when the pinned trace answered by position), `none` (nothing stored for this call)
|
|
30
|
+
or `past-the-end` (the recording has no such step)."""
|
|
31
|
+
|
|
32
|
+
kind: str
|
|
33
|
+
capture: CaptureRef | None = None
|
|
34
|
+
variation: int = 0
|
|
35
|
+
trace_id: str = ""
|
|
36
|
+
drift: str | None = None
|
|
37
|
+
reason: str = ""
|
|
38
|
+
pinned: bool = False
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _step_of(variation: Variation | None, step: int) -> CaptureRef | None:
|
|
42
|
+
if variation is None:
|
|
43
|
+
return None
|
|
44
|
+
return next((capture for capture in variation.captures if capture.step == step), None)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def choose_step(
|
|
48
|
+
variations: list[Variation], current: int, question: Question, strict: bool
|
|
49
|
+
) -> Choice:
|
|
50
|
+
"""S7, S8, M10, C13: call n is answered by step n of the variation being followed, else of
|
|
51
|
+
the newest one that has it. An exact cache-key match always replays (the key holds the
|
|
52
|
+
provider); the kind of call matters only for drift."""
|
|
53
|
+
|
|
54
|
+
def replay_of(capture: CaptureRef, index: int, drift: str | None = None) -> Choice:
|
|
55
|
+
return Choice("replay", capture, index, variations[index].trace_id, drift)
|
|
56
|
+
|
|
57
|
+
here = _step_of(variations[current] if current < len(variations) else None, question.step)
|
|
58
|
+
if here is not None and here.cache_key == question.cache_key:
|
|
59
|
+
return replay_of(here, current)
|
|
60
|
+
for index, variation in enumerate(variations):
|
|
61
|
+
there = _step_of(variation, question.step)
|
|
62
|
+
if there is not None and there.cache_key == question.cache_key:
|
|
63
|
+
return replay_of(there, index)
|
|
64
|
+
if here is None:
|
|
65
|
+
return Choice("past-the-end")
|
|
66
|
+
same_call = here.provider == question.provider and here.is_stream == question.is_stream
|
|
67
|
+
if strict or not same_call:
|
|
68
|
+
return Choice("none", reason=f"no capture for cache key {question.cache_key}")
|
|
69
|
+
drift = (
|
|
70
|
+
f"drift at step {question.step}: the call has cache key {question.cache_key}, "
|
|
71
|
+
f"the recording has {here.cache_key}"
|
|
72
|
+
)
|
|
73
|
+
return replay_of(here, current, drift)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def choose_by_position(pin: Pin, question: Question) -> Choice:
|
|
77
|
+
"""Call n is answered by step n of the pinned trace, whatever the request says; only a step
|
|
78
|
+
recorded for another provider or model cannot answer."""
|
|
79
|
+
capture = next((c for c in pin.captures if c.step == question.step), None)
|
|
80
|
+
if capture is None:
|
|
81
|
+
return Choice("past-the-end")
|
|
82
|
+
if capture.provider != question.provider:
|
|
83
|
+
return Choice(
|
|
84
|
+
"none",
|
|
85
|
+
reason=(
|
|
86
|
+
f"pinned trace {pin.trace_id} step {question.step} was recorded for "
|
|
87
|
+
f"{capture.provider}, the call is for {question.provider}"
|
|
88
|
+
),
|
|
89
|
+
)
|
|
90
|
+
if capture.model != question.model:
|
|
91
|
+
return Choice(
|
|
92
|
+
"none",
|
|
93
|
+
reason=(
|
|
94
|
+
f"pinned trace {pin.trace_id} step {question.step} was recorded for model "
|
|
95
|
+
f"{capture.model}, the call is for model {question.model}"
|
|
96
|
+
),
|
|
97
|
+
)
|
|
98
|
+
return Choice("replay", capture, 0, pin.trace_id, pinned=True)
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
@dataclass(frozen=True)
|
|
102
|
+
class Load:
|
|
103
|
+
"""A capture to fetch and the cache folder it lives in: the pinned trace's folder or the
|
|
104
|
+
trace's own."""
|
|
105
|
+
|
|
106
|
+
capture: CaptureRef
|
|
107
|
+
folder: str
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def loads_of(trace: Trace, decision: Decision) -> list[Load]:
|
|
111
|
+
"""The pinned captures first, then the variations', each capture once."""
|
|
112
|
+
loads = []
|
|
113
|
+
if decision.pin:
|
|
114
|
+
loads = [Load(c, decision.pin.first_cache_key) for c in decision.pin.captures]
|
|
115
|
+
loads += [
|
|
116
|
+
Load(capture, trace.first_cache_key)
|
|
117
|
+
for variation in decision.variations
|
|
118
|
+
for capture in variation.captures
|
|
119
|
+
]
|
|
120
|
+
unique: dict[str, Load] = {}
|
|
121
|
+
for load in loads:
|
|
122
|
+
unique.setdefault(load.capture.capture_id, load)
|
|
123
|
+
return list(unique.values())
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def _document_of(trace: Trace, load: Load, cache: ObjectCache, say: Say) -> str | None:
|
|
127
|
+
"""Reads the object from the local cache or the store, opens it, and keeps only ciphertext on
|
|
128
|
+
disk (L2, L3)."""
|
|
129
|
+
capture, first_key = load.capture, load.folder
|
|
130
|
+
key = trace.keys.get(capture.capture_id)
|
|
131
|
+
if key is None or trace.ended:
|
|
132
|
+
return None
|
|
133
|
+
stored = cache.read(first_key, capture.capture_id)
|
|
134
|
+
if stored is not None:
|
|
135
|
+
try:
|
|
136
|
+
return decrypt_object(stored, key, capture.capture_id)
|
|
137
|
+
except Exception:
|
|
138
|
+
cache.remove(first_key, capture.capture_id)
|
|
139
|
+
say("a cached capture failed its integrity check and was deleted")
|
|
140
|
+
return None
|
|
141
|
+
if not capture.download_url:
|
|
142
|
+
return None
|
|
143
|
+
sealed = download_object(capture.download_url)
|
|
144
|
+
document = decrypt_object(sealed, key, capture.capture_id)
|
|
145
|
+
try:
|
|
146
|
+
cache.write(first_key, capture.capture_id, sealed)
|
|
147
|
+
except OSError:
|
|
148
|
+
say("a capture could not be written to the local cache")
|
|
149
|
+
return document
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def _load_one(trace: Trace, load: Load, cache: ObjectCache, say: Say) -> str | None:
|
|
153
|
+
try:
|
|
154
|
+
return _document_of(trace, load, cache, say)
|
|
155
|
+
except Exception:
|
|
156
|
+
say("a stored capture could not be loaded")
|
|
157
|
+
return None
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
def start_loads(trace: Trace, decision: Decision, cache: ObjectCache, say: Say) -> None:
|
|
161
|
+
"""Starts once per trace, right after trace start: every variation's objects load in the
|
|
162
|
+
background, four at a time on daemon threads of their own, so a later call replays from
|
|
163
|
+
memory and no upload or event job holds a download back. The keys move from the decision into
|
|
164
|
+
the trace, which drops them at its end (S8)."""
|
|
165
|
+
if trace.ended or trace.loads:
|
|
166
|
+
return
|
|
167
|
+
trace.keys.update(decision.keys)
|
|
168
|
+
decision.keys.clear()
|
|
169
|
+
queue = loads_of(trace, decision)
|
|
170
|
+
futures: dict[str, Future] = {load.capture.capture_id: Future() for load in queue}
|
|
171
|
+
trace.loads.update(futures)
|
|
172
|
+
pending = iter(queue)
|
|
173
|
+
take = threading.Lock()
|
|
174
|
+
|
|
175
|
+
def work() -> None:
|
|
176
|
+
while True:
|
|
177
|
+
with take:
|
|
178
|
+
load = next(pending, None)
|
|
179
|
+
if load is None:
|
|
180
|
+
return
|
|
181
|
+
futures[load.capture.capture_id].set_result(_load_one(trace, load, cache, say))
|
|
182
|
+
|
|
183
|
+
for _ in itertools.islice(range(DOWNLOADS_AT_ONCE), len(queue)):
|
|
184
|
+
threading.Thread(target=work, name="agentdevlabs-download", daemon=True).start()
|
agentdevlabs/rules.py
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
"""The project's rules for the process (S6): `ignore` and `mask` change the cache key, the two
|
|
2
|
+
redact lists only the upload copy. One fetch is shared by concurrent calls; a failed fetch is not
|
|
3
|
+
kept, so the next trace asks again. A different version seen at trace start means the next trace
|
|
4
|
+
fetches again."""
|
|
5
|
+
|
|
6
|
+
import threading
|
|
7
|
+
from collections.abc import Callable
|
|
8
|
+
from concurrent.futures import Future
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
from . import background
|
|
12
|
+
|
|
13
|
+
Rules = dict[str, Any]
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class RulesHolder:
|
|
17
|
+
def __init__(self, load: Callable[[], Rules | str | None]):
|
|
18
|
+
self._load = load
|
|
19
|
+
self._lock = threading.Lock()
|
|
20
|
+
self._future: Future[Rules | str | None] | None = None
|
|
21
|
+
self._stale = False
|
|
22
|
+
|
|
23
|
+
def get(self, starts_trace: bool) -> Future[Rules | str | None]:
|
|
24
|
+
"""`starts_trace` is whether this call opens a trace: rules never change in the middle of
|
|
25
|
+
one."""
|
|
26
|
+
with self._lock:
|
|
27
|
+
if self._stale and starts_trace:
|
|
28
|
+
self._future = None
|
|
29
|
+
self._stale = False
|
|
30
|
+
if self._future is None:
|
|
31
|
+
self._future = background.run_apart(self._fetch)
|
|
32
|
+
return self._future
|
|
33
|
+
|
|
34
|
+
def note_version(self, version: int | float | None) -> None:
|
|
35
|
+
with self._lock:
|
|
36
|
+
held = self._held()
|
|
37
|
+
if held is not None and version is not None and version != held["rules_version"]:
|
|
38
|
+
self._stale = True
|
|
39
|
+
|
|
40
|
+
def _held(self) -> Rules | None:
|
|
41
|
+
future = self._future
|
|
42
|
+
if future is None or not future.done() or future.exception() is not None:
|
|
43
|
+
return None
|
|
44
|
+
rules = future.result()
|
|
45
|
+
return rules if isinstance(rules, dict) else None
|
|
46
|
+
|
|
47
|
+
def _fetch(self) -> Rules | str | None:
|
|
48
|
+
rules = None
|
|
49
|
+
try:
|
|
50
|
+
rules = self._load()
|
|
51
|
+
finally:
|
|
52
|
+
if not isinstance(rules, dict):
|
|
53
|
+
with self._lock:
|
|
54
|
+
self._future = None
|
|
55
|
+
return rules
|
agentdevlabs/server.py
ADDED
|
@@ -0,0 +1,446 @@
|
|
|
1
|
+
import re
|
|
2
|
+
import threading
|
|
3
|
+
import time
|
|
4
|
+
from collections.abc import Callable
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
from datetime import UTC, datetime
|
|
7
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
8
|
+
from typing import Any, Literal
|
|
9
|
+
|
|
10
|
+
import httpx2
|
|
11
|
+
|
|
12
|
+
from . import background
|
|
13
|
+
from .config import MODES, Config
|
|
14
|
+
from .log import warn, warn_once
|
|
15
|
+
|
|
16
|
+
START_TIMEOUT_S = 2.0
|
|
17
|
+
UPLOAD_TIMEOUT_S = 30.0
|
|
18
|
+
DOWNLOAD_TIMEOUT_S = 30.0
|
|
19
|
+
MAX_PENDING_BYTES = 64 * 1024 * 1024
|
|
20
|
+
EVENTS_RETRY_DELAY_S = 0.25
|
|
21
|
+
|
|
22
|
+
# Ids go into a path of the local cache, so anything but a UUID is refused (never `../..`).
|
|
23
|
+
UUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass(frozen=True)
|
|
27
|
+
class CaptureRef:
|
|
28
|
+
capture_id: str
|
|
29
|
+
step: int
|
|
30
|
+
cache_key: str
|
|
31
|
+
provider: str
|
|
32
|
+
model: str
|
|
33
|
+
is_stream: bool
|
|
34
|
+
download_url: str | None
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass(frozen=True)
|
|
38
|
+
class Variation:
|
|
39
|
+
"""Variations come newest first, as trace start lists them."""
|
|
40
|
+
|
|
41
|
+
trace_id: str
|
|
42
|
+
captures: list[CaptureRef]
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
@dataclass(frozen=True)
|
|
46
|
+
class Pin:
|
|
47
|
+
"""The trace this developer pinned in this environment; its steps answer every call by
|
|
48
|
+
position."""
|
|
49
|
+
|
|
50
|
+
trace_id: str
|
|
51
|
+
first_cache_key: str
|
|
52
|
+
set_at: datetime
|
|
53
|
+
captures: list[CaptureRef]
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
@dataclass(frozen=True)
|
|
57
|
+
class Decision:
|
|
58
|
+
reachable: bool
|
|
59
|
+
# The server refused the token (401), which is not the same as being unreachable.
|
|
60
|
+
rejected: bool = False
|
|
61
|
+
mode: str | None = None
|
|
62
|
+
off_reason: str | None = None
|
|
63
|
+
variations: list[Variation] = field(default_factory=list)
|
|
64
|
+
# Base64url capture keys by capture id; the trace drops them when it ends (S8).
|
|
65
|
+
keys: dict[str, str] = field(default_factory=dict)
|
|
66
|
+
# Whether the requested group exists; None when no group was asked for.
|
|
67
|
+
group_exists: bool | None = None
|
|
68
|
+
# The version of the project's rules the server holds; None when it did not say.
|
|
69
|
+
rules_version: int | float | None = None
|
|
70
|
+
pin: Pin | None = None
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
UNREACHABLE = Decision(reachable=False)
|
|
74
|
+
REJECTED = Decision(reachable=False, rejected=True)
|
|
75
|
+
REJECTED_RULES = "rejected"
|
|
76
|
+
# An answer we cannot use (a 5xx, not JSON, or rules `parse_rules` refuses): the server is there,
|
|
77
|
+
# so its mode is still worth asking (S6, S10).
|
|
78
|
+
UNUSABLE_RULES = "unusable"
|
|
79
|
+
|
|
80
|
+
_expiry_warned = warn_once()
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def _warn_before_expiry(response: httpx2.Response) -> None:
|
|
84
|
+
"""The header crosses a trust boundary: only a value that parses as a date warns, once per
|
|
85
|
+
date per process."""
|
|
86
|
+
expires = _parse_time(response.headers.get("agent-dev-labs-token-expires-at"))
|
|
87
|
+
if expires is None:
|
|
88
|
+
return
|
|
89
|
+
day = expires.astimezone(UTC).strftime("%Y-%m-%d")
|
|
90
|
+
_expiry_warned(
|
|
91
|
+
f"the token expires on {day} UTC. Make a new one on the console's Access tokens page "
|
|
92
|
+
"before then."
|
|
93
|
+
)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def _is_text(value: Any) -> bool:
|
|
97
|
+
return isinstance(value, str)
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def _is_number(value: Any) -> bool:
|
|
101
|
+
return isinstance(value, int | float) and not isinstance(value, bool)
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def _parse_capture(raw: Any) -> CaptureRef | None:
|
|
105
|
+
if not isinstance(raw, dict):
|
|
106
|
+
return None
|
|
107
|
+
capture_id = raw.get("capture_id")
|
|
108
|
+
download_url = raw.get("download_url")
|
|
109
|
+
valid = (
|
|
110
|
+
_is_text(capture_id)
|
|
111
|
+
and UUID.match(capture_id)
|
|
112
|
+
and _is_number(raw.get("step"))
|
|
113
|
+
and _is_text(raw.get("cache_key"))
|
|
114
|
+
and _is_text(raw.get("provider"))
|
|
115
|
+
and _is_text(raw.get("model"))
|
|
116
|
+
and isinstance(raw.get("is_stream"), bool)
|
|
117
|
+
and _is_text(raw.get("key"))
|
|
118
|
+
and (_is_text(download_url) or download_url is None)
|
|
119
|
+
)
|
|
120
|
+
if not valid:
|
|
121
|
+
return None
|
|
122
|
+
return CaptureRef(
|
|
123
|
+
capture_id=capture_id,
|
|
124
|
+
step=int(raw["step"]),
|
|
125
|
+
cache_key=raw["cache_key"],
|
|
126
|
+
provider=raw["provider"],
|
|
127
|
+
model=raw["model"],
|
|
128
|
+
is_stream=raw["is_stream"],
|
|
129
|
+
download_url=download_url,
|
|
130
|
+
)
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def _parse_captures(raw_captures: Any, keys: dict[str, str]) -> list[CaptureRef] | None:
|
|
134
|
+
"""The captures of one trace, with their keys added to `keys`; None on the wrong shape."""
|
|
135
|
+
if not isinstance(raw_captures, list):
|
|
136
|
+
return None
|
|
137
|
+
captures = []
|
|
138
|
+
for raw in raw_captures:
|
|
139
|
+
capture = _parse_capture(raw)
|
|
140
|
+
if capture is None:
|
|
141
|
+
return None
|
|
142
|
+
captures.append(capture)
|
|
143
|
+
keys[capture.capture_id] = raw["key"]
|
|
144
|
+
return captures
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def _parse_time(value: Any) -> datetime | None:
|
|
148
|
+
if not _is_text(value):
|
|
149
|
+
return None
|
|
150
|
+
try:
|
|
151
|
+
return datetime.fromisoformat(value.replace("Z", "+00:00"))
|
|
152
|
+
except ValueError:
|
|
153
|
+
return None
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def parse_pin(raw: Any, keys: dict[str, str]) -> Pin | None:
|
|
157
|
+
if not isinstance(raw, dict) or not _is_text(raw.get("trace_id")):
|
|
158
|
+
return None
|
|
159
|
+
set_at = _parse_time(raw.get("set_at"))
|
|
160
|
+
captures = _parse_captures(raw.get("captures"), keys)
|
|
161
|
+
if not UUID.match(raw["trace_id"]) or not _is_text(raw.get("first_cache_key")):
|
|
162
|
+
return None
|
|
163
|
+
if set_at is None or captures is None:
|
|
164
|
+
return None
|
|
165
|
+
return Pin(raw["trace_id"], raw["first_cache_key"], set_at, captures)
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def parse_decision(body: Any) -> Decision:
|
|
169
|
+
"""The response comes from our server across a trust boundary: anything of the wrong shape
|
|
170
|
+
counts as unreachable."""
|
|
171
|
+
if not isinstance(body, dict) or body.get("mode") not in MODES:
|
|
172
|
+
return UNREACHABLE
|
|
173
|
+
traces = body.get("traces")
|
|
174
|
+
if not isinstance(traces, list):
|
|
175
|
+
return UNREACHABLE
|
|
176
|
+
variations: list[Variation] = []
|
|
177
|
+
keys: dict[str, str] = {}
|
|
178
|
+
for trace in traces:
|
|
179
|
+
if not isinstance(trace, dict) or not _is_text(trace.get("trace_id")):
|
|
180
|
+
return UNREACHABLE
|
|
181
|
+
captures = _parse_captures(trace.get("captures"), keys)
|
|
182
|
+
if not UUID.match(trace["trace_id"]) or captures is None:
|
|
183
|
+
return UNREACHABLE
|
|
184
|
+
variations.append(Variation(trace_id=trace["trace_id"], captures=captures))
|
|
185
|
+
pin = None
|
|
186
|
+
if body.get("pin") is not None:
|
|
187
|
+
pin = parse_pin(body["pin"], keys)
|
|
188
|
+
if pin is None:
|
|
189
|
+
return UNREACHABLE
|
|
190
|
+
off_reason = body.get("off_reason")
|
|
191
|
+
group_exists = body.get("group_exists")
|
|
192
|
+
rules_version = body.get("rules_version")
|
|
193
|
+
return Decision(
|
|
194
|
+
reachable=True,
|
|
195
|
+
mode=body["mode"],
|
|
196
|
+
off_reason=off_reason if _is_text(off_reason) else None,
|
|
197
|
+
variations=variations,
|
|
198
|
+
keys=keys,
|
|
199
|
+
group_exists=group_exists if isinstance(group_exists, bool) else None,
|
|
200
|
+
rules_version=rules_version if _is_number(rules_version) else None,
|
|
201
|
+
pin=pin,
|
|
202
|
+
)
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def _all_text(value: Any) -> bool:
|
|
206
|
+
return isinstance(value, list) and all(_is_text(item) for item in value)
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
def _compiles(pattern: str) -> bool:
|
|
210
|
+
try:
|
|
211
|
+
re.compile(pattern)
|
|
212
|
+
except (re.error, OverflowError):
|
|
213
|
+
return False
|
|
214
|
+
return True
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
def parse_rules(body: Any) -> dict[str, Any] | None:
|
|
218
|
+
"""The four lists and their version, or None when the answer is of the wrong shape or a
|
|
219
|
+
pattern does not compile: two machines must never hash with different rule sets."""
|
|
220
|
+
if not isinstance(body, dict) or not _is_number(body.get("rules_version")):
|
|
221
|
+
return None
|
|
222
|
+
lists = ("ignore", "mask", "redact_fields", "redact_patterns")
|
|
223
|
+
if not all(_all_text(body.get(name)) for name in lists):
|
|
224
|
+
return None
|
|
225
|
+
if not all(_compiles(pattern) for pattern in [*body["mask"], *body["redact_patterns"]]):
|
|
226
|
+
return None
|
|
227
|
+
return {**{name: body[name] for name in lists}, "rules_version": body["rules_version"]}
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
def sdk_header() -> str:
|
|
231
|
+
try:
|
|
232
|
+
return f"python/{version('agentdevlabs')}"
|
|
233
|
+
except PackageNotFoundError:
|
|
234
|
+
# Run from a source tree that was never installed; the SDK must still send (S10).
|
|
235
|
+
return "python/unknown"
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
SDK_HEADER = sdk_header()
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
def _auth_headers(config: Config) -> dict[str, str]:
|
|
242
|
+
"""Sent on every request to our API and nowhere else: the token, and which SDK and version
|
|
243
|
+
sent it, as a User-Agent does. Nothing about the app or its user."""
|
|
244
|
+
return {"authorization": f"Bearer {config.token}", "agent-dev-labs-sdk": SDK_HEADER}
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
def _headers(config: Config, content_type: str) -> dict[str, str]:
|
|
248
|
+
return {**_auth_headers(config), "content-type": content_type}
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
# Our own clients, never the wrapped ones, so our own calls are never recorded.
|
|
252
|
+
_client = httpx2.Client()
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
def start_trace(config: Config, first_cache_key: str, cached: list[str]) -> Decision:
|
|
256
|
+
try:
|
|
257
|
+
response = _client.post(
|
|
258
|
+
f"{config.api_url}/v1/traces/start",
|
|
259
|
+
headers=_headers(config, "application/json"),
|
|
260
|
+
json={
|
|
261
|
+
"first_cache_key": first_cache_key,
|
|
262
|
+
"cached": cached,
|
|
263
|
+
**({"group": config.group} if config.group else {}),
|
|
264
|
+
},
|
|
265
|
+
timeout=START_TIMEOUT_S,
|
|
266
|
+
)
|
|
267
|
+
_warn_before_expiry(response)
|
|
268
|
+
if response.status_code == 401:
|
|
269
|
+
return REJECTED
|
|
270
|
+
if not response.is_success:
|
|
271
|
+
return UNREACHABLE
|
|
272
|
+
return parse_decision(response.json())
|
|
273
|
+
except (httpx2.HTTPError, ValueError):
|
|
274
|
+
return UNREACHABLE
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
def fetch_rules(config: Config) -> dict[str, Any] | str | None:
|
|
278
|
+
"""Same budget and same fallback as trace start: None means treat the server as
|
|
279
|
+
unreachable, `REJECTED_RULES` that it refused the token and `UNUSABLE_RULES` that it answered
|
|
280
|
+
with an error or rules we cannot use."""
|
|
281
|
+
try:
|
|
282
|
+
response = _client.get(
|
|
283
|
+
f"{config.api_url}/v1/project-rules",
|
|
284
|
+
headers=_auth_headers(config),
|
|
285
|
+
timeout=START_TIMEOUT_S,
|
|
286
|
+
)
|
|
287
|
+
except httpx2.HTTPError:
|
|
288
|
+
return None
|
|
289
|
+
_warn_before_expiry(response)
|
|
290
|
+
if response.status_code == 401:
|
|
291
|
+
return REJECTED_RULES
|
|
292
|
+
if response.status_code >= 500:
|
|
293
|
+
return UNUSABLE_RULES
|
|
294
|
+
if not response.is_success:
|
|
295
|
+
return None
|
|
296
|
+
try:
|
|
297
|
+
return parse_rules(response.json()) or UNUSABLE_RULES
|
|
298
|
+
except ValueError:
|
|
299
|
+
return UNUSABLE_RULES
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
def fetch_mode(config: Config, started_at: float) -> Decision | None:
|
|
303
|
+
"""The server's mode as trace start would resolve it, read alone because the rules failed and
|
|
304
|
+
trace start needs the cache key they shape. It gets only what is left of the rules fetch's
|
|
305
|
+
budget (`started_at` is when that fetch began, on the monotonic clock); None means the read
|
|
306
|
+
failed, which is an unreachable server (S10)."""
|
|
307
|
+
left = START_TIMEOUT_S - (time.monotonic() - started_at)
|
|
308
|
+
if left <= 0:
|
|
309
|
+
return None
|
|
310
|
+
try:
|
|
311
|
+
response = _client.get(
|
|
312
|
+
f"{config.api_url}/v1/mode", headers=_auth_headers(config), timeout=left
|
|
313
|
+
)
|
|
314
|
+
_warn_before_expiry(response)
|
|
315
|
+
body = response.json() if response.is_success else None
|
|
316
|
+
except (httpx2.HTTPError, ValueError):
|
|
317
|
+
return None
|
|
318
|
+
if not isinstance(body, dict) or body.get("mode") not in MODES:
|
|
319
|
+
return None
|
|
320
|
+
off_reason = body.get("off_reason")
|
|
321
|
+
return Decision(
|
|
322
|
+
reachable=True,
|
|
323
|
+
mode=body["mode"],
|
|
324
|
+
off_reason=off_reason if isinstance(off_reason, str) else None,
|
|
325
|
+
)
|
|
326
|
+
|
|
327
|
+
|
|
328
|
+
def download_object(url: str) -> bytes:
|
|
329
|
+
response = _client.get(url, timeout=DOWNLOAD_TIMEOUT_S)
|
|
330
|
+
response.raise_for_status()
|
|
331
|
+
return response.content
|
|
332
|
+
|
|
333
|
+
|
|
334
|
+
_pending_bytes = 0
|
|
335
|
+
_pending_lock = threading.Lock()
|
|
336
|
+
|
|
337
|
+
Outcome = Literal["stored", "retry", "dropped"]
|
|
338
|
+
|
|
339
|
+
|
|
340
|
+
def _error_detail(response: httpx2.Response) -> object:
|
|
341
|
+
"""The `detail` of an error answer; None when the body is not JSON or has none."""
|
|
342
|
+
try:
|
|
343
|
+
answer = response.json()
|
|
344
|
+
except ValueError:
|
|
345
|
+
return None
|
|
346
|
+
return answer.get("detail") if isinstance(answer, dict) else None
|
|
347
|
+
|
|
348
|
+
|
|
349
|
+
_scope_warned = warn_once()
|
|
350
|
+
_REPLAY_ONLY_WARNING = (
|
|
351
|
+
"a capture was not stored: this token can only replay. "
|
|
352
|
+
"Unset AGENT_DEV_LABS_MODE, or use a token that can capture."
|
|
353
|
+
)
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
def _attempt_upload(config: Config, document: str) -> tuple[Outcome, str | None]:
|
|
357
|
+
try:
|
|
358
|
+
response = _client.post(
|
|
359
|
+
f"{config.api_url}/v1/captures",
|
|
360
|
+
headers=_headers(config, "application/x-ndjson"),
|
|
361
|
+
content=document.encode("utf-8"),
|
|
362
|
+
timeout=UPLOAD_TIMEOUT_S,
|
|
363
|
+
)
|
|
364
|
+
except httpx2.HTTPError:
|
|
365
|
+
return "retry", None
|
|
366
|
+
if response.is_success:
|
|
367
|
+
return "stored", _answered_capture_id(response)
|
|
368
|
+
detail = _error_detail(response) if response.status_code >= 400 else None
|
|
369
|
+
# A 409 `capture-exists` means the server holds this capture; any other 409 (`trace-conflict`)
|
|
370
|
+
# does not.
|
|
371
|
+
if response.status_code == 409 and detail == "capture-exists":
|
|
372
|
+
return "stored", None
|
|
373
|
+
if response.status_code >= 500:
|
|
374
|
+
return "retry", None
|
|
375
|
+
if response.status_code == 403 and detail == "token-scope-insufficient":
|
|
376
|
+
_scope_warned(_REPLAY_ONLY_WARNING)
|
|
377
|
+
else:
|
|
378
|
+
warn(f"a capture was not stored (the server answered {response.status_code})")
|
|
379
|
+
return "dropped", None
|
|
380
|
+
|
|
381
|
+
|
|
382
|
+
def _answered_capture_id(response: httpx2.Response) -> str | None:
|
|
383
|
+
try:
|
|
384
|
+
answer = response.json()
|
|
385
|
+
except ValueError:
|
|
386
|
+
return None
|
|
387
|
+
capture_id = answer.get("capture_id") if isinstance(answer, dict) else None
|
|
388
|
+
return capture_id if isinstance(capture_id, str) else None
|
|
389
|
+
|
|
390
|
+
|
|
391
|
+
def queue_upload(config: Config, document: str, on_done: Callable[[str | None], None]) -> None:
|
|
392
|
+
"""Queues the upload on the worker, then calls `on_done` there with the id the server gave
|
|
393
|
+
the stored capture, or None when it gave none or stored nothing. The 64 MiB cap counts
|
|
394
|
+
captures from the moment they wait, since the worker sends them one at a time. The app never
|
|
395
|
+
waits on this (C9, F5)."""
|
|
396
|
+
global _pending_bytes
|
|
397
|
+
size = len(document.encode("utf-8"))
|
|
398
|
+
with _pending_lock:
|
|
399
|
+
if _pending_bytes + size > MAX_PENDING_BYTES:
|
|
400
|
+
warn("a capture was dropped: too many uploads are waiting")
|
|
401
|
+
on_done(None)
|
|
402
|
+
return
|
|
403
|
+
_pending_bytes += size
|
|
404
|
+
background.run(lambda: on_done(_upload_and_release(config, document, size)))
|
|
405
|
+
|
|
406
|
+
|
|
407
|
+
def _upload_and_release(config: Config, document: str, size: int) -> str | None:
|
|
408
|
+
global _pending_bytes
|
|
409
|
+
try:
|
|
410
|
+
return _upload(config, document)
|
|
411
|
+
finally:
|
|
412
|
+
with _pending_lock:
|
|
413
|
+
_pending_bytes -= size
|
|
414
|
+
|
|
415
|
+
|
|
416
|
+
def _upload(config: Config, document: str) -> str | None:
|
|
417
|
+
"""One retry covers a blip; a second failure drops the capture."""
|
|
418
|
+
outcome, capture_id = _attempt_upload(config, document)
|
|
419
|
+
if outcome == "retry":
|
|
420
|
+
outcome, capture_id = _attempt_upload(config, document)
|
|
421
|
+
if outcome == "retry":
|
|
422
|
+
warn("a capture was dropped: the server could not be reached or kept failing")
|
|
423
|
+
return capture_id
|
|
424
|
+
|
|
425
|
+
|
|
426
|
+
def _attempt_events(config: Config, events: list[dict[str, Any]]) -> bool:
|
|
427
|
+
try:
|
|
428
|
+
response = _client.post(
|
|
429
|
+
f"{config.api_url}/v1/events",
|
|
430
|
+
headers=_headers(config, "application/json"),
|
|
431
|
+
json={"events": events},
|
|
432
|
+
timeout=UPLOAD_TIMEOUT_S,
|
|
433
|
+
)
|
|
434
|
+
except httpx2.HTTPError:
|
|
435
|
+
return False
|
|
436
|
+
return response.status_code < 500
|
|
437
|
+
|
|
438
|
+
|
|
439
|
+
def send_events(config: Config, events: list[dict[str, Any]]) -> None:
|
|
440
|
+
"""One retry covers a blip; after that the batch is dropped. Events are never worth slowing
|
|
441
|
+
the app (OP3)."""
|
|
442
|
+
if _attempt_events(config, events):
|
|
443
|
+
return
|
|
444
|
+
time.sleep(EVENTS_RETRY_DELAY_S)
|
|
445
|
+
if not _attempt_events(config, events):
|
|
446
|
+
warn("call events were dropped: the server kept failing")
|