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/hook.py ADDED
@@ -0,0 +1,1009 @@
1
+ """The provider client's HTTP client, replaced by one that records, replays or passes each call
2
+ through (S1). Anything it cannot read or does not record passes through (A-floor)."""
3
+
4
+ import asyncio
5
+ import contextlib
6
+ import dataclasses
7
+ import importlib
8
+ import json
9
+ import time
10
+ import weakref
11
+ from collections.abc import Callable
12
+ from concurrent.futures import Future
13
+ from dataclasses import dataclass
14
+ from datetime import UTC
15
+ from typing import Any
16
+
17
+ import httpx2
18
+ from httpx2._client import ClientState
19
+
20
+ from . import background
21
+ from .cache import MAX_HELD, ObjectCache
22
+ from .cache_key import cache_key
23
+ from .config import DISABLED_FALSE, DISABLED_TRUE, MODES, Config, read_config
24
+ from .events import EventQueue
25
+ from .log import warn, warn_once
26
+ from .playback import aplayback, parse_document, playback
27
+ from .providers import ends_with_tool_result, is_retry, provider_of, will_be_retried
28
+ from .recorder import Call, record_astream, record_stream
29
+ from .replay import Choice, Question, choose_by_position, choose_step, start_loads
30
+ from .rules import Rules, RulesHolder
31
+ from .server import (
32
+ REJECTED_RULES,
33
+ START_TIMEOUT_S,
34
+ UNREACHABLE,
35
+ UNUSABLE_RULES,
36
+ Decision,
37
+ Pin,
38
+ fetch_mode,
39
+ fetch_rules,
40
+ queue_upload,
41
+ send_events,
42
+ start_trace,
43
+ )
44
+ from .trace import Trace, TraceSelector
45
+
46
+ PRODUCTION_OR_LIMIT = ("production", "plan-limit")
47
+ DROPPED = ("content-encoding", "content-length", "transfer-encoding")
48
+ INTERNAL_ERROR = "the SDK hit an internal error, so this call is not recorded"
49
+
50
+ # A pin outlives any one client, so what is said about it once per process, and the folder and
51
+ # capture ids the pinned trace was last seen with, are kept per process (by cache directory).
52
+ _process_say = warn_once()
53
+ _pinned_objects: dict[str, tuple[str, list[str]]] = {}
54
+
55
+
56
+ def effective_mode(config: Config, decision: Decision, say: Callable[[str], None]) -> str:
57
+ """R1: disabled, then a server `off` that is not a toggle, then the env var, then the
58
+ server, then auto."""
59
+ if config.disabled:
60
+ return "off"
61
+ if decision.reachable and decision.mode == "off" and decision.off_reason in PRODUCTION_OR_LIMIT:
62
+ say(f"capture is off ({decision.off_reason})")
63
+ return "off"
64
+ return config.mode or (decision.mode if decision.reachable and decision.mode else "auto")
65
+
66
+
67
+ _NEW_TOKEN = (
68
+ "The token is expired, revoked or wrong: make a new one on the console's Access tokens page "
69
+ "and set AGENT_DEV_LABS_TOKEN to it."
70
+ )
71
+ TOKEN_REJECTED_AUTO = (
72
+ f"the server rejected the token (401), so this call is not recorded. {_NEW_TOKEN}"
73
+ )
74
+ TOKEN_REJECTED_STRICT = (
75
+ f"the server rejected the token (401), so this call did not go to the provider. {_NEW_TOKEN}"
76
+ )
77
+
78
+
79
+ ENV_HOW_TO = "To record it, run with `AGENT_DEV_LABS_MODE=auto` or `capture`."
80
+ # A replay-only token must never capture (C4) and a service token has no toggle (M17), so the
81
+ # env var is not suggested here.
82
+ SERVER_HOW_TO = (
83
+ "The server set replay: the console or devkit toggle, the environment's default, or a "
84
+ "`replay-only` token. To record it, switch the toggle or the environment to auto or capture, "
85
+ "with a token that can capture."
86
+ )
87
+
88
+
89
+ def miss_message(reason: str, from_env: bool) -> str:
90
+ """The strict-replay miss with how to record it (S7). Words match `missMessage` in
91
+ sdks/js/src/report.ts; change the two together."""
92
+ sentence = reason if reason.endswith(".") else f"{reason}."
93
+ unsent = "" if "did not go to the provider" in reason else " It did not go to the provider."
94
+ return f"{sentence}{unsent} {ENV_HOW_TO if from_env else SERVER_HOW_TO}"
95
+
96
+
97
+ def replay_miss(detail: str, request: httpx2.Request) -> httpx2.Response:
98
+ """A 424 the provider SDKs do not retry, so the app sees the miss at once instead of
99
+ "Connection error"."""
100
+ return httpx2.Response(
101
+ 424,
102
+ headers={"x-should-retry": "false"},
103
+ json={"error": {"message": f"Agent Dev Labs replay mode: {detail}"}},
104
+ request=request,
105
+ )
106
+
107
+
108
+ @dataclass
109
+ class Prepared:
110
+ call: Call
111
+ close: Callable[[], None]
112
+ is_stream: bool
113
+
114
+
115
+ @dataclass
116
+ class Plan(Prepared):
117
+ decision: Decision
118
+ mode: str
119
+
120
+
121
+ @dataclass(frozen=True)
122
+ class Action:
123
+ """What route decides for a call: `pass`, `capture`, `replay` (with its choice) or
124
+ `unanswered` (`miss` or `error`, with the reason)."""
125
+
126
+ kind: str
127
+ choice: Choice | None = None
128
+ status: str = ""
129
+ reason: str = ""
130
+
131
+
132
+ class Core:
133
+ """The state one wrapped client keeps, and everything about a call that is the same whether
134
+ the client is sync or async."""
135
+
136
+ def __init__(self, config: Config):
137
+ self.config = config
138
+ self.say = warn_once()
139
+ self.cache = ObjectCache(config.cache_dir)
140
+ self.events = EventQueue(lambda batch: send_events(config, batch))
141
+ self._flushed_at_end: weakref.WeakSet[Trace] = weakref.WeakSet()
142
+ self._told_past_end: weakref.WeakSet[Trace] = weakref.WeakSet()
143
+ self.rules = RulesHolder(lambda: fetch_rules(config))
144
+ self.selector = TraceSelector(self._start_trace)
145
+ quiet = config.disabled or config.mode == "off"
146
+ if not config.token and not quiet:
147
+ self.say("AGENT_DEV_LABS_TOKEN is not set, so calls are not recorded")
148
+ self.active = bool(config.token) and not quiet
149
+
150
+ def _held_ids(self, first_key: str) -> list[str]:
151
+ try:
152
+ return self.cache.held(first_key)
153
+ except OSError:
154
+ return []
155
+
156
+ def _start_trace(self, first_key: str) -> Decision:
157
+ own = self._held_ids(first_key)
158
+ previous = _pinned_objects.get(self.config.cache_dir)
159
+ pinned = self._held_ids(previous[0]) if previous and previous[0] != first_key else []
160
+ cached = list(dict.fromkeys([*pinned, *own]))[:MAX_HELD]
161
+ decision = start_trace(self.config, first_key, cached)
162
+ self._evict_unnamed(first_key, own, decision)
163
+ self._track_pinned(first_key, previous, decision)
164
+ return decision
165
+
166
+ def _evict_unnamed(self, first_key: str, own: list[str], decision: Decision) -> None:
167
+ """L5: the server's answer lists every object it still names, so a held one it leaves out
168
+ was deleted. A grouped start lists only that group's traces, so it names too little to
169
+ judge by."""
170
+ if not decision.reachable or decision.mode == "off" or self.config.group:
171
+ return
172
+ pin = decision.pin
173
+ named = {
174
+ capture.capture_id
175
+ for variation in decision.variations
176
+ for capture in variation.captures
177
+ }
178
+ if pin and pin.first_cache_key == first_key:
179
+ named |= {capture.capture_id for capture in pin.captures}
180
+ self._remove_unnamed(first_key, own, named)
181
+
182
+ def _track_pinned(
183
+ self, first_key: str, previous: tuple[str, list[str]] | None, decision: Decision
184
+ ) -> None:
185
+ """L5 for a pin that moved or was removed: of the folder it was last seen in, only the
186
+ objects it named are its to evict; the rest belongs to traces that start there."""
187
+ if not decision.reachable or decision.mode == "off":
188
+ return
189
+ pin = decision.pin
190
+ current = (pin.first_cache_key, [c.capture_id for c in pin.captures]) if pin else None
191
+ if previous and previous[0] != first_key:
192
+ still_named = set(current[1]) if current and current[0] == previous[0] else set()
193
+ self._remove_unnamed(previous[0], previous[1], still_named)
194
+ if current:
195
+ _pinned_objects[self.config.cache_dir] = current
196
+ else:
197
+ _pinned_objects.pop(self.config.cache_dir, None)
198
+
199
+ def _remove_unnamed(self, folder: str, held: list[str], named: set[str]) -> None:
200
+ for capture_id in held:
201
+ if capture_id not in named:
202
+ background.run(lambda capture_id=capture_id: self._remove(folder, capture_id))
203
+
204
+ def _remove(self, folder: str, capture_id: str) -> None:
205
+ with contextlib.suppress(OSError):
206
+ self.cache.remove(folder, capture_id)
207
+
208
+ def body_of(self, request: httpx2.Request) -> dict[str, Any] | None:
209
+ """The JSON object of a call to a recorded endpoint; None for any other call."""
210
+ if not self.active or not provider_of(str(request.url), request.method):
211
+ return None
212
+ try:
213
+ body = json.loads(request.content)
214
+ except (httpx2.RequestNotRead, ValueError):
215
+ body = None
216
+ if not isinstance(body, dict):
217
+ self.say("a request body could not be read, so this call is not recorded")
218
+ return None
219
+ return body
220
+
221
+ def rules_for(self, request: httpx2.Request, body: dict[str, Any]) -> Future[Rules | None]:
222
+ """The rules come first: they change the hash."""
223
+ return self.rules.get(self.selector.will_start(self._starts_trace(request, body)))
224
+
225
+ @staticmethod
226
+ def _starts_trace(request: httpx2.Request, body: dict[str, Any]) -> bool:
227
+ return not ends_with_tool_result(body) and not is_retry(request.headers)
228
+
229
+ def wants_mode(self, rules: Any) -> bool:
230
+ """Whether the server's mode is still worth asking: it answered the rules with an error or
231
+ rules we cannot use, and no env var already decides (R1)."""
232
+ return rules == UNUSABLE_RULES and not self.config.mode
233
+
234
+ def read_mode(self, started_at: float) -> Decision | None:
235
+ return fetch_mode(self.config, started_at)
236
+
237
+ def unruled(
238
+ self,
239
+ request: httpx2.Request,
240
+ body: dict[str, Any],
241
+ rules: Any,
242
+ server: Decision | None = None,
243
+ ) -> httpx2.Response | None:
244
+ """No rules, so no hash: replay mode fails the call and any other mode lets it go to the
245
+ provider unrecorded. `rules` says why: the server refused the token, was unreachable or
246
+ answered with something unusable, in which case `server` is its mode, read alone."""
247
+ rejected = rules == REJECTED_RULES
248
+ if not rejected:
249
+ self.say("the project rules could not be fetched, so this call is not recorded")
250
+ mode = effective_mode(self.config, server or UNREACHABLE, self.say)
251
+ if rejected:
252
+ return self._token_rejected(mode, request)
253
+ if mode != "replay":
254
+ return None
255
+ model = body.get("model") or ""
256
+ if server:
257
+ return self.missed(
258
+ f"the project rules for model {model} could not be fetched, so the call has no "
259
+ "cache key",
260
+ request,
261
+ )
262
+ return self.missed(
263
+ f"the server could not be reached to fetch the project rules for model {model}", request
264
+ )
265
+
266
+ def missed(self, reason: str, request: httpx2.Request) -> httpx2.Response:
267
+ """A strict-replay miss: the 424, and the same words said once in the log."""
268
+ message = miss_message(reason, self.config.mode == "replay")
269
+ self.say(f"replay mode: {message}")
270
+ return replay_miss(message, request)
271
+
272
+ def _token_rejected(self, mode: str, request: httpx2.Request) -> httpx2.Response | None:
273
+ if mode != "replay":
274
+ self.say(TOKEN_REJECTED_AUTO)
275
+ return None
276
+ self.say(f"replay mode: {TOKEN_REJECTED_STRICT}")
277
+ return replay_miss(TOKEN_REJECTED_STRICT, request)
278
+
279
+ def prepare(
280
+ self, request: httpx2.Request, body: dict[str, Any], rules: Rules
281
+ ) -> Prepared | None:
282
+ """Everything worked out before the call goes out; the call counts as open on its trace
283
+ from here until whoever answers it runs `close` (S4)."""
284
+ try:
285
+ provider = provider_of(str(request.url), request.method)
286
+ key = cache_key(provider, body, rules)
287
+ retry = is_retry(request.headers)
288
+ # A retry of a failed attempt belongs to the trace and the step of that attempt.
289
+ trace = self.selector.select(key, self._starts_trace(request, body))
290
+ if trace not in self._flushed_at_end:
291
+ self._flushed_at_end.add(trace)
292
+ trace.on_end(self.events.flush)
293
+ call = Call(
294
+ trace=trace,
295
+ step=trace.repeat_step() if retry else trace.next_step(),
296
+ cache_key=key,
297
+ provider=provider,
298
+ model=str(body.get("model") or ""),
299
+ request=body,
300
+ group=self.config.group,
301
+ rules=rules,
302
+ )
303
+ return Prepared(call, trace.open(), body.get("stream") is True)
304
+ except Exception:
305
+ self.say(INTERNAL_ERROR)
306
+ return None
307
+
308
+ def plan(self, prepared: Prepared, decision: Decision) -> Plan:
309
+ if decision.reachable:
310
+ self.rules.note_version(decision.rules_version)
311
+ mode = effective_mode(self.config, decision, self.say)
312
+ return Plan(prepared.call, prepared.close, prepared.is_stream, decision, mode)
313
+
314
+ def action(self, plan: Plan) -> Action:
315
+ call, decision, mode = plan.call, plan.decision, plan.mode
316
+ if not decision.reachable and decision.rejected:
317
+ if mode != "replay":
318
+ self.say(TOKEN_REJECTED_AUTO)
319
+ return Action("pass")
320
+ self.say(f"replay mode: {TOKEN_REJECTED_STRICT}")
321
+ return Action("unreachable", reason=TOKEN_REJECTED_STRICT)
322
+ if not decision.reachable:
323
+ if mode != "replay":
324
+ return Action("pass")
325
+ reason = f"the server could not be reached to look up cache key {call.cache_key}"
326
+ return Action("unreachable", reason=reason)
327
+ if mode == "off":
328
+ return Action("pass")
329
+ pin = self._pin_in_use(plan)
330
+ if mode == "capture":
331
+ return Action("capture")
332
+ start_loads(
333
+ call.trace,
334
+ decision if pin else dataclasses.replace(decision, pin=None),
335
+ self.cache,
336
+ self.say,
337
+ )
338
+ if pin:
339
+ return self._pinned_action(plan, pin)
340
+ question = Question(call.step, call.cache_key, call.provider, call.model, plan.is_stream)
341
+ choice = choose_step(decision.variations, call.trace.variation, question, mode == "replay")
342
+ if choice.kind == "past-the-end":
343
+ if mode == "auto":
344
+ return Action("capture")
345
+ reason = f"no capture for cache key {call.cache_key} at step {call.step}"
346
+ return Action("unanswered", status="miss", reason=self._in_group(plan, reason))
347
+ if choice.kind == "none":
348
+ return Action("unanswered", status="miss", reason=self._in_group(plan, choice.reason))
349
+ return Action("replay", choice)
350
+
351
+ def _pin_in_use(self, plan: Plan) -> Pin | None:
352
+ """The pin answers only in auto, or in a replay the server chose; the env var's capture
353
+ and strict replay ignore it, and say so once."""
354
+ pin = plan.decision.pin
355
+ if pin is None:
356
+ return None
357
+ if plan.mode == "capture":
358
+ _process_say(
359
+ f"your pin on trace {pin.trace_id} is inactive in capture mode. "
360
+ "Calls match normally."
361
+ )
362
+ return None
363
+ if self.config.mode == "replay":
364
+ _process_say(
365
+ f"your pin on trace {pin.trace_id} is inactive in strict replay. "
366
+ "Calls match normally."
367
+ )
368
+ return None
369
+ since = pin.set_at.astimezone(UTC).strftime("%Y-%m-%d %H:%M")
370
+ _process_say(
371
+ f"trace {pin.trace_id} is pinned in this environment (since {since} UTC), so every "
372
+ "call replays its next step. Unpin it on the console's Traces page."
373
+ )
374
+ return pin
375
+
376
+ def _pinned_action(self, plan: Plan, pin: Pin) -> Action:
377
+ call = plan.call
378
+ question = Question(call.step, call.cache_key, call.provider, call.model, plan.is_stream)
379
+ choice = choose_by_position(pin, question)
380
+ if choice.kind == "past-the-end":
381
+ steps = len(pin.captures)
382
+ ran = f"pinned trace {pin.trace_id} has {steps} {'step' if steps == 1 else 'steps'}."
383
+ if plan.mode == "auto":
384
+ reason = f"{ran} Call {call.step} went to the provider and was not captured."
385
+ else:
386
+ reason = f"{ran} Call {call.step} was not answered and did not go to the provider."
387
+ if plan.mode == "auto" and call.trace not in self._told_past_end:
388
+ self._told_past_end.add(call.trace)
389
+ warn(reason)
390
+ return Action("unanswered", status="miss", reason=reason)
391
+ if choice.kind == "none":
392
+ self.say(choice.reason)
393
+ return Action("unanswered", status="miss", reason=choice.reason)
394
+ return Action("replay", choice)
395
+
396
+ def stream_mismatch(self, plan: Plan, choice: Choice, recorded) -> Action | None:
397
+ """A pinned step answers a call of either stream setting only when it recorded an error."""
398
+ if not choice.pinned or recorded.ending.kind == "error":
399
+ return None
400
+ if recorded.is_stream == plan.is_stream:
401
+ return None
402
+ reason = (
403
+ f"pinned trace {choice.trace_id} step {choice.capture.step} was recorded "
404
+ f"{'streamed' if recorded.is_stream else 'not streamed'}, the call is "
405
+ f"{'streamed' if plan.is_stream else 'not streamed'}"
406
+ )
407
+ self.say(reason)
408
+ return Action("unanswered", status="miss", reason=reason)
409
+
410
+ def _in_group(self, plan: Plan, reason: str) -> str:
411
+ group = self.config.group
412
+ if not group:
413
+ return reason
414
+ if plan.decision.reachable and plan.decision.group_exists is False:
415
+ return f"group {group} doesn't exist in this project"
416
+ return f"no recording for {plan.call.cache_key} in group {group}"
417
+
418
+ def load_failed(self, plan: Plan, choice: Choice) -> Action:
419
+ capture_id = choice.capture.capture_id
420
+ reason = (
421
+ f"the stored capture {capture_id} for cache key {plan.call.cache_key} "
422
+ "could not be loaded"
423
+ )
424
+ return Action("unanswered", status="error", reason=reason)
425
+
426
+ def recorded_for(self, plan: Plan, choice: Choice, document: str):
427
+ """Opens the document and moves the trace onto the replayed variation; returns the
428
+ recording and how fast to play it."""
429
+ recorded = parse_document(document)
430
+ speed = self.config.replay_speed
431
+ if speed is None:
432
+ speed = 1.0 if recorded.is_stream else float("inf")
433
+ if not choice.pinned:
434
+ if choice.drift:
435
+ self.say(choice.drift)
436
+ plan.call.trace.follow(choice.variation, choice.trace_id)
437
+ return recorded, speed
438
+
439
+ def emit(
440
+ self,
441
+ call: Call,
442
+ status: str,
443
+ started_at: float,
444
+ capture_id: str | None = None,
445
+ trace_id: str | None = None,
446
+ drift: bool = False,
447
+ ) -> None:
448
+ event = {
449
+ "status": status,
450
+ "cache_key": call.cache_key,
451
+ "latency_ms": round((time.perf_counter() - started_at) * 1000),
452
+ "trace_id": trace_id or call.trace.id,
453
+ }
454
+ if capture_id:
455
+ event["capture_id"] = capture_id
456
+ if drift:
457
+ event["drift"] = True
458
+ self.events.add(event)
459
+
460
+ def deliverer(self, plan: Plan, started_at: float) -> Callable[[str | None], None]:
461
+ """Run by the recorder when the capture is built or dropped: uploads it, and closes the
462
+ call either way. The event follows the upload's answer, so the trace and the capture both
463
+ exist when it lands; the call stays open until the event is queued."""
464
+
465
+ def uploaded(capture_id: str | None) -> None:
466
+ try:
467
+ self.emit(plan.call, "capture", started_at, capture_id)
468
+ finally:
469
+ plan.close()
470
+
471
+ def deliver(document: str | None) -> None:
472
+ if document is None:
473
+ plan.close()
474
+ return
475
+ queue_upload(self.config, document, uploaded)
476
+
477
+ return deliver
478
+
479
+
480
+ def is_event_stream(response: httpx2.Response) -> bool:
481
+ return "text/event-stream" in response.headers.get("content-type", "")
482
+
483
+
484
+ def recorded_response(
485
+ upstream: httpx2.Response, request: httpx2.Request, stream: httpx2.SyncByteStream
486
+ ) -> httpx2.Response:
487
+ """The provider's answer with our copying stream as its body. The stream yields decoded
488
+ bytes, so the encoding and length headers no longer describe it."""
489
+ headers = [(k, v) for k, v in upstream.headers.multi_items() if k.lower() not in DROPPED]
490
+ return httpx2.Response(
491
+ upstream.status_code,
492
+ headers=headers,
493
+ stream=stream,
494
+ request=request,
495
+ extensions=upstream.extensions,
496
+ )
497
+
498
+
499
+ class _Unused(httpx2.BaseTransport, httpx2.AsyncBaseTransport):
500
+ """The hook sends through the SDK's own client; this one only keeps httpx2 from building a
501
+ transport nothing uses."""
502
+
503
+ def handle_request(self, request): # pragma: no cover
504
+ raise RuntimeError("the Agent Dev Labs hook sends through the provider client")
505
+
506
+ async def handle_async_request(self, request): # pragma: no cover
507
+ raise RuntimeError("the Agent Dev Labs hook sends through the provider client")
508
+
509
+
510
+ class _CopyingStream(httpx2.SyncByteStream):
511
+ def __init__(self, chunks, upstream: httpx2.Response, deliver: Callable[[str | None], None]):
512
+ self._chunks = chunks
513
+ self._upstream = upstream
514
+ self._deliver = deliver
515
+ self._started = False
516
+
517
+ def __iter__(self):
518
+ self._started = True
519
+ yield from self._chunks
520
+
521
+ def close(self) -> None:
522
+ if self._started:
523
+ self._chunks.close()
524
+ else:
525
+ # A generator that never ran has no recording to cancel.
526
+ self._deliver(None)
527
+ self._upstream.close()
528
+
529
+
530
+ class _CopyingAsyncStream(httpx2.AsyncByteStream):
531
+ def __init__(self, chunks, upstream: httpx2.Response, deliver: Callable[[str | None], None]):
532
+ self._chunks = chunks
533
+ self._upstream = upstream
534
+ self._deliver = deliver
535
+ self._started = False
536
+
537
+ async def __aiter__(self):
538
+ self._started = True
539
+ async for chunk in self._chunks:
540
+ yield chunk
541
+
542
+ async def aclose(self) -> None:
543
+ if self._started:
544
+ await self._chunks.aclose()
545
+ else:
546
+ self._deliver(None)
547
+ await self._upstream.aclose()
548
+
549
+
550
+ class SyncHook(httpx2.Client):
551
+ def __init__(self, inner: httpx2.Client, core: Core):
552
+ super().__init__(transport=_Unused(), timeout=inner.timeout)
553
+ self._inner = inner
554
+ self._core = core
555
+
556
+ def build_request(self, *args: Any, **kwargs: Any) -> httpx2.Request:
557
+ return self._inner.build_request(*args, **kwargs)
558
+
559
+ @property
560
+ def is_closed(self) -> bool:
561
+ return self._inner.is_closed
562
+
563
+ def close(self) -> None:
564
+ self._inner.close()
565
+ super().close()
566
+
567
+ def send(self, request: httpx2.Request, **kwargs: Any) -> httpx2.Response:
568
+ body = self._core.body_of(request)
569
+ if body is None:
570
+ return self._inner.send(request, **kwargs)
571
+ started_at = time.monotonic()
572
+ try:
573
+ rules = self._core.rules_for(request, body).result()
574
+ except Exception:
575
+ rules = None
576
+ if not isinstance(rules, dict):
577
+ server = self._core.read_mode(started_at) if self._core.wants_mode(rules) else None
578
+ return self._core.unruled(request, body, rules, server) or self._inner.send(
579
+ request, **kwargs
580
+ )
581
+ prepared = self._core.prepare(request, body, rules)
582
+ if prepared is None:
583
+ return self._inner.send(request, **kwargs)
584
+ try:
585
+ decision = prepared.call.trace.get_decision()
586
+ except Exception:
587
+ prepared.close()
588
+ self._core.say(INTERNAL_ERROR)
589
+ return self._inner.send(request, **kwargs)
590
+ plan = self._core.plan(prepared, decision)
591
+ try:
592
+ return self._route(plan, request, kwargs)
593
+ except BaseException:
594
+ plan.close()
595
+ raise
596
+
597
+ def _route(self, plan: Plan, request: httpx2.Request, kwargs: dict[str, Any]):
598
+ action = self._core.action(plan)
599
+ if action.kind == "replay":
600
+ replayed = self._replay(plan, action.choice, request, kwargs)
601
+ if isinstance(replayed, httpx2.Response):
602
+ return replayed
603
+ action = replayed or self._core.load_failed(plan, action.choice)
604
+ if action.kind == "unreachable":
605
+ plan.close()
606
+ return self._core.missed(action.reason, request)
607
+ if action.kind == "pass":
608
+ return self._pass_through(plan, request, kwargs)
609
+ if action.kind == "capture":
610
+ return self._capture(plan, request, kwargs)
611
+ return self._unanswered(plan, action, request, kwargs)
612
+
613
+ def _pass_through(self, plan: Plan, request, kwargs):
614
+ try:
615
+ return self._inner.send(request, **kwargs)
616
+ finally:
617
+ plan.close()
618
+
619
+ def _sent(self, call: Call, request, **kwargs) -> httpx2.Response:
620
+ """The provider SDK retries a dropped connection, and the retry reuses this step."""
621
+ try:
622
+ return self._inner.send(request, **kwargs)
623
+ except BaseException:
624
+ call.trace.release_step(call.step)
625
+ raise
626
+
627
+ def _unanswered(self, plan: Plan, action: Action, request, kwargs):
628
+ started_at = time.perf_counter()
629
+ try:
630
+ if plan.mode == "replay":
631
+ self._core.emit(plan.call, action.status, started_at)
632
+ return self._core.missed(action.reason, request)
633
+ upstream = self._sent(plan.call, request, **kwargs)
634
+ if not will_be_retried(upstream):
635
+ self._core.emit(plan.call, action.status, started_at)
636
+ return upstream
637
+ finally:
638
+ plan.close()
639
+
640
+ def _replay(
641
+ self, plan: Plan, choice: Choice, request, kwargs
642
+ ) -> httpx2.Response | Action | None:
643
+ started_at = time.perf_counter()
644
+ capture_id = choice.capture.capture_id
645
+ try:
646
+ future = plan.call.trace.loads.get(capture_id)
647
+ document = None
648
+ if future is not None:
649
+ try:
650
+ document = future.result(START_TIMEOUT_S)
651
+ except TimeoutError:
652
+ document = None
653
+ if document is None:
654
+ return None
655
+ recorded, speed = self._core.recorded_for(plan, choice, document)
656
+ mismatch = self._core.stream_mismatch(plan, choice, recorded)
657
+ if mismatch is not None:
658
+ return mismatch
659
+
660
+ def on_end() -> None:
661
+ pinned_id = choice.trace_id if choice.pinned else None
662
+ self._core.emit(
663
+ plan.call,
664
+ "hit",
665
+ started_at,
666
+ capture_id,
667
+ pinned_id,
668
+ drift=choice.drift is not None,
669
+ )
670
+ plan.close()
671
+
672
+ response = playback(recorded, speed, on_end, request)
673
+ if not kwargs.get("stream"):
674
+ response.read()
675
+ return response
676
+ except Exception:
677
+ self._core.say("a stored capture could not be replayed")
678
+ return None
679
+
680
+ def _capture(self, plan: Plan, request, kwargs):
681
+ started_at = time.perf_counter()
682
+ try:
683
+ upstream = self._sent(plan.call, request, **{**kwargs, "stream": True})
684
+ except BaseException:
685
+ plan.close()
686
+ raise
687
+ wants_stream = bool(kwargs.get("stream"))
688
+ try:
689
+ if will_be_retried(upstream):
690
+ plan.call.trace.release_step(plan.call.step)
691
+ plan.close()
692
+ return self._unrecorded(upstream, wants_stream)
693
+ response = self._record(plan, upstream, request, started_at)
694
+ except Exception:
695
+ self._core.say(INTERNAL_ERROR)
696
+ plan.close()
697
+ return self._unrecorded(upstream, wants_stream)
698
+ if not wants_stream:
699
+ response.read()
700
+ return response
701
+
702
+ @staticmethod
703
+ def _unrecorded(upstream: httpx2.Response, wants_stream: bool) -> httpx2.Response:
704
+ if not wants_stream:
705
+ upstream.read()
706
+ return upstream
707
+
708
+ def _record(self, plan: Plan, upstream, request, started_at: float) -> httpx2.Response:
709
+ call = dataclasses.replace(plan.call, started_at=started_at)
710
+ deliver = self._core.deliverer(plan, started_at)
711
+ chunks = record_stream(
712
+ call, upstream.iter_bytes(), deliver, upstream.status_code, is_event_stream(upstream)
713
+ )
714
+ return recorded_response(upstream, request, _CopyingStream(chunks, upstream, deliver))
715
+
716
+
717
+ class AsyncHook(httpx2.AsyncClient):
718
+ def __init__(self, inner: httpx2.AsyncClient, core: Core):
719
+ super().__init__(transport=_Unused(), timeout=inner.timeout)
720
+ self._inner = inner
721
+ self._core = core
722
+ self._loop: asyncio.AbstractEventLoop | None = None
723
+
724
+ def build_request(self, *args: Any, **kwargs: Any) -> httpx2.Request:
725
+ return self._inner.build_request(*args, **kwargs)
726
+
727
+ @property
728
+ def is_closed(self) -> bool:
729
+ return self._inner.is_closed
730
+
731
+ def __del__(self) -> None:
732
+ """The provider SDK closes its HTTP client when it is collected, by a task on the loop
733
+ running then. If this client's connections belong to a loop that has ended, that task
734
+ fails and prints. Marking the inner client closed first leaves its sockets to be freed."""
735
+ loop = getattr(self, "_loop", None)
736
+ if loop is None or self._inner.is_closed:
737
+ return
738
+ try:
739
+ running = asyncio.get_running_loop()
740
+ except RuntimeError:
741
+ running = None
742
+ if running is not loop:
743
+ self._inner._state = ClientState.CLOSED
744
+
745
+ async def aclose(self) -> None:
746
+ await self._inner.aclose()
747
+ await super().aclose()
748
+
749
+ async def send(self, request: httpx2.Request, **kwargs: Any) -> httpx2.Response:
750
+ self._loop = asyncio.get_running_loop()
751
+ body = self._core.body_of(request)
752
+ if body is None:
753
+ return await self._inner.send(request, **kwargs)
754
+ started_at = time.monotonic()
755
+ try:
756
+ # Shielded: a cancelled call must not cancel the fetch other calls share.
757
+ rules = await asyncio.shield(asyncio.wrap_future(self._core.rules_for(request, body)))
758
+ except Exception:
759
+ rules = None
760
+ if not isinstance(rules, dict):
761
+ server = None
762
+ if self._core.wants_mode(rules):
763
+ # Off the loop, as the rules are fetched, so the read never blocks the app (S16).
764
+ read = background.run_apart(lambda: self._core.read_mode(started_at))
765
+ with contextlib.suppress(Exception):
766
+ server = await asyncio.shield(asyncio.wrap_future(read))
767
+ return self._core.unruled(request, body, rules, server) or await self._inner.send(
768
+ request, **kwargs
769
+ )
770
+ prepared = self._core.prepare(request, body, rules)
771
+ if prepared is None:
772
+ return await self._inner.send(request, **kwargs)
773
+ try:
774
+ decision = await prepared.call.trace.aget_decision()
775
+ except Exception:
776
+ prepared.close()
777
+ self._core.say(INTERNAL_ERROR)
778
+ return await self._inner.send(request, **kwargs)
779
+ except BaseException:
780
+ prepared.close()
781
+ raise
782
+ plan = self._core.plan(prepared, decision)
783
+ try:
784
+ return await self._route(plan, request, kwargs)
785
+ except BaseException:
786
+ plan.close()
787
+ raise
788
+
789
+ async def _route(self, plan: Plan, request: httpx2.Request, kwargs: dict[str, Any]):
790
+ action = self._core.action(plan)
791
+ if action.kind == "replay":
792
+ replayed = await self._replay(plan, action.choice, request, kwargs)
793
+ if isinstance(replayed, httpx2.Response):
794
+ return replayed
795
+ action = replayed or self._core.load_failed(plan, action.choice)
796
+ if action.kind == "unreachable":
797
+ plan.close()
798
+ return self._core.missed(action.reason, request)
799
+ if action.kind == "pass":
800
+ return await self._pass_through(plan, request, kwargs)
801
+ if action.kind == "capture":
802
+ return await self._capture(plan, request, kwargs)
803
+ return await self._unanswered(plan, action, request, kwargs)
804
+
805
+ async def _pass_through(self, plan: Plan, request, kwargs):
806
+ try:
807
+ return await self._inner.send(request, **kwargs)
808
+ finally:
809
+ plan.close()
810
+
811
+ async def _sent(self, call: Call, request, **kwargs) -> httpx2.Response:
812
+ try:
813
+ return await self._inner.send(request, **kwargs)
814
+ except BaseException:
815
+ call.trace.release_step(call.step)
816
+ raise
817
+
818
+ async def _unanswered(self, plan: Plan, action: Action, request, kwargs):
819
+ started_at = time.perf_counter()
820
+ try:
821
+ if plan.mode == "replay":
822
+ self._core.emit(plan.call, action.status, started_at)
823
+ return self._core.missed(action.reason, request)
824
+ upstream = await self._sent(plan.call, request, **kwargs)
825
+ if not will_be_retried(upstream):
826
+ self._core.emit(plan.call, action.status, started_at)
827
+ return upstream
828
+ finally:
829
+ plan.close()
830
+
831
+ async def _replay(
832
+ self, plan: Plan, choice: Choice, request, kwargs
833
+ ) -> httpx2.Response | Action | None:
834
+ started_at = time.perf_counter()
835
+ capture_id = choice.capture.capture_id
836
+ try:
837
+ future = plan.call.trace.loads.get(capture_id)
838
+ document = None
839
+ if future is not None:
840
+ try:
841
+ # Shielded: giving up on a slow object must not cancel its background load.
842
+ document = await asyncio.wait_for(
843
+ asyncio.shield(asyncio.wrap_future(future)), START_TIMEOUT_S
844
+ )
845
+ except TimeoutError:
846
+ document = None
847
+ if document is None:
848
+ return None
849
+ recorded, speed = self._core.recorded_for(plan, choice, document)
850
+ mismatch = self._core.stream_mismatch(plan, choice, recorded)
851
+ if mismatch is not None:
852
+ return mismatch
853
+
854
+ def on_end() -> None:
855
+ pinned_id = choice.trace_id if choice.pinned else None
856
+ self._core.emit(
857
+ plan.call,
858
+ "hit",
859
+ started_at,
860
+ capture_id,
861
+ pinned_id,
862
+ drift=choice.drift is not None,
863
+ )
864
+ plan.close()
865
+
866
+ response = await aplayback(recorded, speed, on_end, request)
867
+ if not kwargs.get("stream"):
868
+ await response.aread()
869
+ return response
870
+ except Exception:
871
+ self._core.say("a stored capture could not be replayed")
872
+ return None
873
+
874
+ async def _capture(self, plan: Plan, request, kwargs):
875
+ started_at = time.perf_counter()
876
+ try:
877
+ upstream = await self._sent(plan.call, request, **{**kwargs, "stream": True})
878
+ except BaseException:
879
+ plan.close()
880
+ raise
881
+ wants_stream = bool(kwargs.get("stream"))
882
+ try:
883
+ if will_be_retried(upstream):
884
+ plan.call.trace.release_step(plan.call.step)
885
+ plan.close()
886
+ return await self._unrecorded(upstream, wants_stream)
887
+ response = self._record(plan, upstream, request, started_at)
888
+ except Exception:
889
+ self._core.say(INTERNAL_ERROR)
890
+ plan.close()
891
+ return await self._unrecorded(upstream, wants_stream)
892
+ if not wants_stream:
893
+ await response.aread()
894
+ return response
895
+
896
+ @staticmethod
897
+ async def _unrecorded(upstream: httpx2.Response, wants_stream: bool) -> httpx2.Response:
898
+ if not wants_stream:
899
+ await upstream.aread()
900
+ return upstream
901
+
902
+ def _record(self, plan: Plan, upstream, request, started_at: float) -> httpx2.Response:
903
+ call = dataclasses.replace(plan.call, started_at=started_at)
904
+ deliver = self._core.deliverer(plan, started_at)
905
+ chunks = record_astream(
906
+ call, upstream.aiter_bytes(), deliver, upstream.status_code, is_event_stream(upstream)
907
+ )
908
+ return recorded_response(upstream, request, _CopyingAsyncStream(chunks, upstream, deliver))
909
+
910
+
911
+ _left_alone: weakref.WeakSet = weakref.WeakSet()
912
+
913
+
914
+ def _http_client_kind(client: Any) -> str | None:
915
+ """ "sync" or "async" when the provider client still holds the HTTP client its SDK built
916
+ (S1); None for any other: a user's own client, with its own proxy, certificates or
917
+ transport, is not ours to replace."""
918
+ sdk = type(client).__module__.split(".")[0]
919
+ if sdk not in ("openai", "anthropic"):
920
+ return None
921
+ try:
922
+ base = importlib.import_module(f"{sdk}._base_client")
923
+ except ImportError:
924
+ return None
925
+ http = getattr(client, "_client", None)
926
+ if type(http) is getattr(base, "SyncHttpxClientWrapper", None):
927
+ return "sync"
928
+ if type(http) is getattr(base, "AsyncHttpxClientWrapper", None):
929
+ return "async"
930
+ return None
931
+
932
+
933
+ _say_unwrappable = warn_once()
934
+ _say_typo = warn_once()
935
+
936
+
937
+ def _warn_about_typos(config: Config) -> None:
938
+ """A mistyped variable is never silently ignored. A disabled SDK, or one with no token, does
939
+ nothing, so it only says the kill switch was misread."""
940
+ if config.unknown_disabled is not None:
941
+ accepted = _list([*DISABLED_TRUE, *DISABLED_FALSE])
942
+ _say_typo(
943
+ f'AGENT_DEV_LABS_DISABLED "{config.unknown_disabled}" is not {accepted}; the SDK is off'
944
+ )
945
+ if config.unknown_mode is not None and not config.disabled and config.token:
946
+ _say_typo(
947
+ f'AGENT_DEV_LABS_MODE "{config.unknown_mode}" is not {_list(MODES)}; running as auto'
948
+ )
949
+
950
+
951
+ def _list(items: tuple[str, ...] | list[str]) -> str:
952
+ """ "a, b or c" the way the warnings read."""
953
+ return f"{', '.join(items[:-1])} or {items[-1]}"
954
+
955
+
956
+ def wrap(client: Any, http_client: httpx2.Client | httpx2.AsyncClient | None = None) -> Any:
957
+ """Returns the provider client with Agent Dev Labs under its HTTP client. An app with its
958
+ own HTTP client (a proxy, custom TLS) passes the same one here and keeps using it. A client
959
+ whose own HTTP client is not passed is returned as it is, with one warning; in replay mode
960
+ that is an error, because its calls would go to the provider."""
961
+ config = read_config()
962
+ if isinstance(getattr(client, "_client", None), (SyncHook, AsyncHook)):
963
+ return client
964
+ _warn_about_typos(config)
965
+ kind = _passed_http_client_kind(client, http_client) or _http_client_kind(client)
966
+ if kind is None:
967
+ _leave_alone(client, config)
968
+ return client
969
+ core = Core(config)
970
+ inner = http_client if http_client is not None else client._client
971
+ hook = SyncHook(inner, core) if kind == "sync" else AsyncHook(inner, core)
972
+ try:
973
+ return client.with_options(http_client=hook)
974
+ except Exception as error: # A-floor: a provider SDK change must not fail the app
975
+ _say_unwrappable(
976
+ f"could not wrap this client, so its calls are not recorded ({type(error).__name__})"
977
+ )
978
+ return client
979
+
980
+
981
+ def _passed_http_client_kind(client: Any, http_client: Any) -> str | None:
982
+ if http_client is None:
983
+ return None
984
+ kind = "async" if isinstance(http_client, httpx2.AsyncClient) else "sync"
985
+ expected = httpx2.AsyncClient if kind == "async" else httpx2.Client
986
+ if not isinstance(http_client, expected) or not isinstance(
987
+ getattr(client, "_client", None), expected
988
+ ):
989
+ raise TypeError(
990
+ "wrap(client, http_client=...) needs the same kind of httpx2 client as the provider "
991
+ "client: httpx2.Client for a sync one, httpx2.AsyncClient for an async one"
992
+ )
993
+ return kind
994
+
995
+
996
+ def _leave_alone(client: Any, config: Config) -> None:
997
+ if config.disabled or config.mode == "off":
998
+ return
999
+ if config.mode == "replay":
1000
+ raise RuntimeError(
1001
+ "Agent Dev Labs replay mode: wrap() cannot reach this client's HTTP client, so its "
1002
+ "calls would go to the provider. Pass its client to wrap(client, http_client=...)."
1003
+ )
1004
+ if client not in _left_alone:
1005
+ _left_alone.add(client)
1006
+ warn(
1007
+ "this client has its own HTTP client, so its calls are not recorded "
1008
+ "(pass its client to wrap(client, http_client=...))"
1009
+ )