agentspec-sdk 0.5.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.
@@ -0,0 +1,359 @@
1
+ """
2
+ memory_write and vector_store evidence points (ADR-0038, ADR-0039).
3
+
4
+ `memory_write` returns the LangGraph checkpointer or Store it is given, with its writes scrubbed of
5
+ the PII fields the manifest declares, given the declared TTL where the backend can apply it, and
6
+ audited. Each write is a record for MEM-01 (scrub), MEM-02 (TTL) and MEM-03 (audit entry).
7
+ `vector_store` wraps a vector store client; each call is a MEM-04 record carrying its namespace.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import contextlib
13
+ import contextvars
14
+ import functools
15
+ import inspect
16
+ import json
17
+ import logging
18
+ import re
19
+ from typing import Any, Callable, Dict, Iterator, Optional, Tuple
20
+
21
+ from .evidence_points import (
22
+ AUDIT, CONTRACT, MEMORY_WRITE, NAMESPACE, SCRUB, TTL, VECTOR_STORE,
23
+ EvidencePoints, _default_points,
24
+ )
25
+
26
+ AUDIT_LOGGER = logging.getLogger("agentspec.memory.audit")
27
+ REDACTED = "[REDACTED]"
28
+ TTL_APPLIED, TTL_PASSED_THROUGH, TTL_UNSUPPORTED = "applied", "passed-through", "unsupported"
29
+ _NOT_VERIFIABLE_CODE = "instrumentation_unavailable"
30
+ _WRONG_NAMESPACE_CODE = "undeclared_namespace"
31
+ _NO_NAMESPACE_CODE = "no_evidence"
32
+ for _code in (_NOT_VERIFIABLE_CODE, _WRONG_NAMESPACE_CODE, _NO_NAMESPACE_CODE):
33
+ assert _code in CONTRACT.reasonCodes, f"contract.reasonCodes lacks {_code!r}"
34
+
35
+ # Regex baseline for the entity names spec.memory.hygiene.piiScrubFields uses; other names match by key only.
36
+ _PATTERNS: Dict[str, "re.Pattern[str]"] = {
37
+ "email": re.compile(r"[\w.+-]+@[\w-]+(?:\.[\w-]+)+"),
38
+ "ssn": re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),
39
+ "credit_card": re.compile(r"\b(?:\d[ -]?){13,16}\b"),
40
+ "iban": re.compile(r"\b[A-Z]{2}\d{2}[A-Z0-9]{11,30}\b"),
41
+ "phone_number": re.compile(r"\+\d[\d ().-]{7,}\d|\(?\b\d{3}\)?[ .-]\d{3}[ .-]\d{4}\b"), # an international +, or a 3-3-4 layout: not dates or ids
42
+ "ip_address": re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b"),
43
+ }
44
+
45
+
46
+ def scrub(value: Any, fields: Tuple[str, ...], by_value: bool = True) -> Tuple[Any, int]:
47
+ """
48
+ `value` with the declared PII fields redacted, and how many were. Dict, list and tuple containers
49
+ and pydantic models (LangChain messages) keep their shape and type, every other object is left as it is; a new structure is returned, the
50
+ argument is never mutated. Everything under a dict key or model field named as a declared field is redacted; a string is
51
+ also searched for the declared fields that have a pattern when `by_value`.
52
+ """
53
+ wanted = {f.lower() for f in fields}
54
+ patterns = [p for name, p in _PATTERNS.items() if name in wanted] if by_value else []
55
+
56
+ def walk(node: Any, declared: bool = False) -> Tuple[Any, int]:
57
+ """`declared`: the node sits under a declared field, so every leaf in it is redacted."""
58
+ if isinstance(node, dict):
59
+ out, found = {}, 0
60
+ for key, child in node.items():
61
+ out[key], n = walk(child, declared or (isinstance(key, str) and key.lower() in wanted))
62
+ found += n
63
+ return out, found
64
+ if type(node) in (list, tuple):
65
+ walked = [walk(child, declared) for child in node]
66
+ return type(node)(w[0] for w in walked), sum(w[1] for w in walked)
67
+ if hasattr(node, "model_copy") and hasattr(node, "model_fields_set"):
68
+ return walk_model(node, declared) # a LangChain message or another pydantic model: copied, type kept
69
+ if declared and not isinstance(node, (dict, list, tuple)) and node is not None:
70
+ return REDACTED, 1
71
+ if isinstance(node, str):
72
+ found = 0
73
+ for pattern in patterns:
74
+ node, n = pattern.subn(REDACTED, node)
75
+ found += n
76
+ return node, found
77
+ return node, 0
78
+
79
+ def walk_model(node: Any, declared: bool) -> Tuple[Any, int]:
80
+ changes, found = {}, 0
81
+ for name in type(node).model_fields:
82
+ child = getattr(node, name, None)
83
+ new, n = walk(child, declared or name.lower() in wanted)
84
+ if n:
85
+ changes[name], found = new, found + n
86
+ return (node.model_copy(update=changes) if changes else node), found
87
+
88
+ return walk(value)
89
+
90
+
91
+ _inside: contextvars.ContextVar[bool] = contextvars.ContextVar("agentspec_memory_write_inside", default=False)
92
+
93
+
94
+ @contextlib.contextmanager
95
+ def _outermost() -> Iterator[bool]:
96
+ """True for the outermost write only: a backend's `aput` that calls its own `put` is one write, not two."""
97
+ if _inside.get():
98
+ yield False
99
+ return
100
+ token = _inside.set(True)
101
+ try:
102
+ yield True
103
+ finally:
104
+ _inside.reset(token)
105
+
106
+
107
+ class _Writes:
108
+ """What one wrapped backend does on a write; the checkpointer and Store proxies share it."""
109
+
110
+ def __init__(self, points: EvidencePoints, kind: str, fields: Tuple[str, ...], ttl_seconds: Optional[int]) -> None:
111
+ self.points = points
112
+ self.kind = kind
113
+ self.fields = fields
114
+ self.ttl_seconds = ttl_seconds
115
+
116
+ @staticmethod
117
+ def capped(requested: Optional[float], declared: float) -> float:
118
+ """The declared TTL, or the caller's own when it is shorter: a write never outlives the declared retention."""
119
+ return declared if requested is None or requested > declared else requested
120
+
121
+ def scrubbed(self, value: Any, by_value: bool = True) -> Tuple[Any, int]:
122
+ return scrub(value, self.fields, by_value) if self.fields else (value, 0)
123
+
124
+ def record(self, operation: str, scrubbed: int, ttl: Optional[str]) -> None:
125
+ """One write: the MEM-01 record, the MEM-02 record when a TTL is declared, the audit entry and MEM-03 record."""
126
+ subject = f"memory:{self.kind}:{operation}"
127
+ self.points.record_call(MEMORY_WRITE, SCRUB, subject)
128
+ if ttl is not None:
129
+ applied = ttl != TTL_UNSUPPORTED
130
+ self.points.record_call(
131
+ MEMORY_WRITE, TTL, f"{subject}:ttl={ttl}", "pass" if applied else "not_verifiable",
132
+ None if applied else {"code": _NOT_VERIFIABLE_CODE, "detail": f"the {self.kind} backend cannot apply a TTL"},
133
+ )
134
+ if self.points.applies(MEMORY_WRITE, AUDIT):
135
+ AUDIT_LOGGER.info(json.dumps({
136
+ "event": "memory.write", "backend": self.kind, "operation": operation,
137
+ "scrubbed": scrubbed, "ttl": ttl,
138
+ }))
139
+ if AUDIT_LOGGER.isEnabledFor(logging.INFO) and AUDIT_LOGGER.hasHandlers():
140
+ self.points.record_call(MEMORY_WRITE, AUDIT, subject)
141
+ else: # Python's default logging drops INFO: the entry went nowhere, so it proves nothing
142
+ self.points.record_call(
143
+ MEMORY_WRITE, AUDIT, subject, "not_verifiable",
144
+ {"code": _NOT_VERIFIABLE_CODE, "detail": f"no log output receives INFO from {AUDIT_LOGGER.name!r}; configure logging"},
145
+ )
146
+
147
+
148
+ def _accepts_ttl(fn: Callable[..., Any]) -> bool:
149
+ try:
150
+ return "ttl" in inspect.signature(fn).parameters
151
+ except (TypeError, ValueError):
152
+ return False
153
+
154
+
155
+ class _CheckpointerWrites:
156
+ """Overrides of a LangGraph checkpointer's writes; `_agentspec` holds the `_Writes`."""
157
+
158
+ def _prepare(self, method: str, kwargs: Dict[str, Any]) -> Optional[str]:
159
+ """Hand the declared TTL to a write that accepts one: a checkpointer has no per-item TTL otherwise."""
160
+ writes: _Writes = self._agentspec
161
+ if writes.ttl_seconds is None:
162
+ return None
163
+ if writes.ttl_seconds == 0: # session-scoped retention: no per-item expiry to forward
164
+ return TTL_UNSUPPORTED
165
+ if _accepts_ttl(getattr(super(), method)):
166
+ kwargs["ttl"] = writes.capped(kwargs.get("ttl"), writes.ttl_seconds)
167
+ return TTL_PASSED_THROUGH
168
+ return TTL_UNSUPPORTED
169
+
170
+ def _scrub_checkpoint(self, checkpoint: Any, metadata: Any) -> Tuple[Any, Any, int]:
171
+ values, n = self._agentspec.scrubbed(checkpoint.get("channel_values"))
172
+ meta, m = self._agentspec.scrubbed(metadata, by_value=False) # metadata keeps its ids and counters: by key only
173
+ return {**checkpoint, "channel_values": values}, meta, n + m
174
+
175
+ def _scrub_pending(self, pending: Any) -> Tuple[list, int]:
176
+ """Pending writes are (channel, value): a channel named as a declared field is redacted whole."""
177
+ scrubbed = [(channel, *self._agentspec.scrubbed({channel: value})) for channel, value in pending]
178
+ return [(channel, one[channel]) for channel, one, _ in scrubbed], sum(n for _, _, n in scrubbed)
179
+
180
+ def put(self, config, checkpoint, metadata, new_versions, *args, **kwargs):
181
+ with _outermost() as outer:
182
+ if not outer:
183
+ return super().put(config, checkpoint, metadata, new_versions, *args, **kwargs)
184
+ checkpoint, metadata, n = self._scrub_checkpoint(checkpoint, metadata)
185
+ ttl = self._prepare("put", kwargs)
186
+ result = super().put(config, checkpoint, metadata, new_versions, *args, **kwargs)
187
+ self._agentspec.record("put", n, ttl)
188
+ return result
189
+
190
+ def put_writes(self, config, pending, task_id, *args, **kwargs):
191
+ with _outermost() as outer:
192
+ if not outer:
193
+ return super().put_writes(config, pending, task_id, *args, **kwargs)
194
+ pending, n = self._scrub_pending(pending)
195
+ ttl = self._prepare("put_writes", kwargs)
196
+ result = super().put_writes(config, pending, task_id, *args, **kwargs)
197
+ self._agentspec.record("put_writes", n, ttl)
198
+ return result
199
+
200
+ async def aput(self, config, checkpoint, metadata, new_versions, *args, **kwargs):
201
+ with _outermost() as outer:
202
+ if not outer:
203
+ return await super().aput(config, checkpoint, metadata, new_versions, *args, **kwargs)
204
+ checkpoint, metadata, n = self._scrub_checkpoint(checkpoint, metadata)
205
+ ttl = self._prepare("aput", kwargs)
206
+ result = await super().aput(config, checkpoint, metadata, new_versions, *args, **kwargs)
207
+ self._agentspec.record("put", n, ttl)
208
+ return result
209
+
210
+ async def aput_writes(self, config, pending, task_id, *args, **kwargs):
211
+ with _outermost() as outer:
212
+ if not outer:
213
+ return await super().aput_writes(config, pending, task_id, *args, **kwargs)
214
+ pending, n = self._scrub_pending(pending)
215
+ ttl = self._prepare("aput_writes", kwargs)
216
+ result = await super().aput_writes(config, pending, task_id, *args, **kwargs)
217
+ self._agentspec.record("put_writes", n, ttl)
218
+ return result
219
+
220
+
221
+ class _StoreWrites:
222
+ """Overrides of a LangGraph Store's `batch` and `abatch`, which `put`, `aput` and `delete` go through."""
223
+
224
+ def _prepare(self, ops: Any) -> Tuple[list, list]:
225
+ """The ops with each put's value scrubbed and TTL set, and one (scrubbed, ttl state) per put."""
226
+ writes: _Writes = self._agentspec
227
+ prepared, puts = [], []
228
+ for op in ops:
229
+ if getattr(op, "value", None) is None or not hasattr(op, "_replace"):
230
+ prepared.append(op)
231
+ continue
232
+ value, n = writes.scrubbed(op.value)
233
+ changes: Dict[str, Any] = {"value": value}
234
+ ttl = None
235
+ if writes.ttl_seconds is not None:
236
+ supported = bool(getattr(self, "supports_ttl", False)) and writes.ttl_seconds > 0
237
+ if supported:
238
+ changes["ttl"] = writes.capped(getattr(op, "ttl", None), writes.ttl_seconds / 60) # the Store takes minutes
239
+ ttl = TTL_APPLIED if supported else TTL_UNSUPPORTED
240
+ prepared.append(op._replace(**changes))
241
+ puts.append((n, ttl))
242
+ return prepared, puts
243
+
244
+ def batch(self, ops):
245
+ with _outermost() as outer:
246
+ if not outer:
247
+ return super().batch(ops)
248
+ prepared, puts = self._prepare(ops)
249
+ result = super().batch(prepared)
250
+ for n, ttl in puts:
251
+ self._agentspec.record("put", n, ttl)
252
+ return result
253
+
254
+ async def abatch(self, ops):
255
+ with _outermost() as outer:
256
+ if not outer:
257
+ return await super().abatch(ops)
258
+ prepared, puts = self._prepare(ops)
259
+ result = await super().abatch(prepared)
260
+ for n, ttl in puts:
261
+ self._agentspec.record("put", n, ttl)
262
+ return result
263
+
264
+
265
+ def _proxy(backend: Any, mixin: type, writes: _Writes) -> Any:
266
+ """`backend` with the mixin's methods first: a subclass instance (LangGraph checks isinstance) sharing the backend's state."""
267
+ proxy_class = type(f"AgentSpec{type(backend).__name__}", (mixin, type(backend)), {})
268
+ proxy = object.__new__(proxy_class)
269
+ if hasattr(backend, "__dict__"):
270
+ proxy.__dict__ = backend.__dict__
271
+ for klass in type(backend).__mro__: # classes with __slots__ keep their state there
272
+ for slot in getattr(klass, "__slots__", ()):
273
+ if slot not in ("__dict__", "__weakref__") and hasattr(backend, slot):
274
+ setattr(proxy, slot, getattr(backend, slot))
275
+ proxy._agentspec = writes
276
+ return proxy
277
+
278
+
279
+ def memory_write(backend: Any) -> Any:
280
+ """
281
+ Wrap a LangGraph checkpointer or Store (`graph = builder.compile(checkpointer=memory_write(saver))`).
282
+
283
+ Its writes are scrubbed of `spec.memory.hygiene.piiScrubFields`, given the declared TTL where the
284
+ backend can apply it, and audited when `hygiene.auditLog` is true. A checkpointer is the
285
+ short-term memory (`shortTerm.ttlSeconds`), a Store the long-term one (`longTerm.ttlDays`).
286
+ """
287
+ points = _default_points("memory_write")
288
+ memory = points.memory_spec()
289
+ fields = tuple((memory.get("hygiene") or {}).get("piiScrubFields") or ())
290
+ if hasattr(backend, "put_writes"):
291
+ kind, ttl, mixin = "checkpointer", (memory.get("shortTerm") or {}).get("ttlSeconds"), _CheckpointerWrites
292
+ elif hasattr(backend, "batch"):
293
+ days = (memory.get("longTerm") or {}).get("ttlDays")
294
+ kind, ttl, mixin = "store", None if days is None else days * 24 * 60 * 60, _StoreWrites
295
+ else:
296
+ raise TypeError(f"memory_write: {type(backend).__name__} is neither a checkpointer (put_writes) nor a Store (batch)")
297
+ for target in CONTRACT.evidencePoints[MEMORY_WRITE]:
298
+ points.register(MEMORY_WRITE, target)
299
+ return _proxy(backend, mixin, _Writes(points, kind, fields, ttl))
300
+
301
+
302
+ class _VectorStore:
303
+ """Delegating proxy around a vector store client: each public call records the namespace it used."""
304
+
305
+ def __init__(self, points: EvidencePoints, client: Any, namespace: Optional[str]) -> None:
306
+ self._points = points
307
+ self._client = client
308
+ self._namespace = namespace
309
+ self._declared = ((points.memory_spec().get("vector") or {}).get("namespace"))
310
+ points.register(VECTOR_STORE, NAMESPACE)
311
+
312
+ def _used_namespace(self, call: Callable[..., Any], args: Tuple[Any, ...], kwargs: Dict[str, Any]) -> Optional[str]:
313
+ """The namespace the call passes (keyword or positional, even an empty one), else the one the client is bound to."""
314
+ try:
315
+ passed = inspect.signature(call).bind_partial(*args, **kwargs).arguments
316
+ except (TypeError, ValueError): # the signature is unreadable: only a keyword is certain, a positional one is unknown
317
+ passed = kwargs if not args else {"namespace": kwargs.get("namespace")}
318
+ return passed["namespace"] if "namespace" in passed else self._namespace
319
+
320
+ def _record(self, used: Optional[str]) -> None:
321
+ if used is None:
322
+ self._points.record_call(
323
+ VECTOR_STORE, NAMESPACE, None, "not_verifiable",
324
+ {"code": _NO_NAMESPACE_CODE, "detail": "the call names no namespace; bind the client to one"},
325
+ )
326
+ elif used == self._declared:
327
+ self._points.record_call(VECTOR_STORE, NAMESPACE, f"vector:{used}")
328
+ else:
329
+ self._points.record_call(
330
+ VECTOR_STORE, NAMESPACE, f"vector:{used}", "fail",
331
+ {"code": _WRONG_NAMESPACE_CODE, "detail": f"namespace {used!r} is not the declared {self._declared!r}"},
332
+ )
333
+
334
+ def __getattr__(self, name: str) -> Any:
335
+ attr = getattr(self._client, name)
336
+ if name.startswith("_") or not callable(attr):
337
+ return attr
338
+ if inspect.iscoroutinefunction(attr):
339
+ @functools.wraps(attr)
340
+ async def acall(*args: Any, **kwargs: Any) -> Any:
341
+ self._record(self._used_namespace(attr, args, kwargs))
342
+ return await attr(*args, **kwargs)
343
+ return acall
344
+
345
+ @functools.wraps(attr)
346
+ def call(*args: Any, **kwargs: Any) -> Any:
347
+ self._record(self._used_namespace(attr, args, kwargs))
348
+ return attr(*args, **kwargs)
349
+ return call
350
+
351
+
352
+ def vector_store(client: Any, namespace: Optional[str] = None) -> _VectorStore:
353
+ """
354
+ Wrap a vector store client; each call is a MEM-04 record naming its namespace.
355
+
356
+ The namespace is the call's `namespace=` argument, else `namespace` here (a client bound to one
357
+ namespace); MEM-04 passes when it is `spec.memory.vector.namespace`.
358
+ """
359
+ return _VectorStore(_default_points("vector_store"), client, namespace)
@@ -0,0 +1,319 @@
1
+ """
2
+ AgentSpecReporter — Python agent-side SDK module.
3
+
4
+ Runs live health checks and optionally self-reports to the AgentSpec control
5
+ plane via startPushMode(). Works in both sync and async environments:
6
+
7
+ - Sync (no running event loop): uses threading.Timer (daemon) so the process
8
+ can still exit cleanly.
9
+ - Async (running event loop detected): uses asyncio.create_task().
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import asyncio
15
+ import json
16
+ import math
17
+ import os
18
+ import threading
19
+ from datetime import datetime, timezone
20
+ from typing import Any, Callable, Dict, Optional
21
+
22
+ import httpx
23
+
24
+ from .agentspec_contract import AgentSpecContract
25
+ from .evidence_points import EvidencePoints, Shipped, set_default
26
+ from .manifest import load_manifest
27
+ from .types import HealthCheck, HealthReport
28
+
29
+
30
+ CONTRACT = AgentSpecContract()
31
+ MAX_HEARTBEAT_BYTES = CONTRACT.heartbeatMaxBytes
32
+
33
+
34
+ def _size(payload: Dict[str, Any]) -> int:
35
+ return len(json.dumps(payload, separators=(",", ":")).encode("utf-8"))
36
+
37
+
38
+ class AgentSpecReporter:
39
+ """Runs health checks and optionally pushes heartbeats to the control plane."""
40
+
41
+ def __init__(self, manifest: Dict[str, Any]) -> None:
42
+ self._manifest = manifest
43
+ self.evidence = EvidencePoints(manifest)
44
+ set_default(self.evidence)
45
+ self._active = False
46
+ self._timer: Optional[threading.Timer] = None
47
+ self._lock = threading.Lock() # guards _generation and _timer; never held across a push
48
+ self._shipping: Optional[Shipped] = None # the window the heartbeat in flight carries
49
+ self._heartbeat_in_flight = False # one POST at a time: the window it carries is already on the wire
50
+ self._generation = 0 # bumped on every start/stop; a timer chain dies when its generation is stale
51
+ self._task: Optional[asyncio.Task[None]] = None
52
+ self._control_plane_url = ""
53
+ self._api_key = ""
54
+ self._interval_seconds = 30
55
+ self._on_error: Optional[Callable[[Exception], None]] = None
56
+
57
+ @classmethod
58
+ def from_yaml(cls, path: str) -> "AgentSpecReporter":
59
+ """Create a reporter from an agent.yaml file path."""
60
+ return cls(manifest=load_manifest(path))
61
+
62
+ # ── Health check ──────────────────────────────────────────────────────────
63
+
64
+ def get_report(self) -> HealthReport:
65
+ """
66
+ Run live health checks and return a HealthReport.
67
+ Phase 4: minimal implementation — env var presence only.
68
+ """
69
+ checks: list[HealthCheck] = []
70
+ passed = 0
71
+ failed = 0
72
+
73
+ # Check model API key env var
74
+ model = self._manifest.get("spec", {}).get("model", {})
75
+ api_key_ref: str = model.get("apiKey", "")
76
+ if api_key_ref.startswith("$env:"):
77
+ env_var = api_key_ref[5:]
78
+ if os.environ.get(env_var):
79
+ checks.append(
80
+ HealthCheck(
81
+ id=f"env:{env_var}",
82
+ category="env",
83
+ status="pass",
84
+ severity="error",
85
+ )
86
+ )
87
+ passed += 1
88
+ else:
89
+ checks.append(
90
+ HealthCheck(
91
+ id=f"env:{env_var}",
92
+ category="env",
93
+ status="fail",
94
+ severity="error",
95
+ message=f"Environment variable {env_var} is not set",
96
+ )
97
+ )
98
+ failed += 1
99
+
100
+ status: str
101
+ if failed > 0:
102
+ status = "unhealthy"
103
+ else:
104
+ status = "healthy"
105
+
106
+ return HealthReport(
107
+ agent_name=self._manifest["metadata"]["name"],
108
+ timestamp=datetime.now(timezone.utc).isoformat(),
109
+ status=status, # type: ignore[arg-type]
110
+ summary={"passed": passed, "failed": failed, "warnings": 0, "skipped": 0},
111
+ checks=checks,
112
+ )
113
+
114
+ def wsgi_app(self) -> Callable[..., Any]:
115
+ """WSGI app serving GET on the contract agent health path; mount it in any WSGI framework (a prefix mount lands in SCRIPT_NAME) or run it with wsgiref."""
116
+
117
+ def app(environ: Dict[str, Any], start_response: Callable[..., Any]) -> list[bytes]:
118
+ if environ.get("SCRIPT_NAME", "") + environ.get("PATH_INFO", "") != CONTRACT.agentPaths.health:
119
+ start_response("404 Not Found", [("Content-Type", "text/plain")])
120
+ return [b"not found"]
121
+ if environ.get("REQUEST_METHOD") != "GET":
122
+ start_response("405 Method Not Allowed", [("Allow", "GET"), ("Content-Type", "text/plain")])
123
+ return [b"method not allowed"]
124
+ body = self.get_report().model_dump_json().encode("utf-8")
125
+ start_response("200 OK", [("Content-Type", "application/json"), ("Content-Length", str(len(body)))])
126
+ return [body]
127
+
128
+ return app
129
+
130
+ # ── Push mode ─────────────────────────────────────────────────────────────
131
+
132
+ def start_push_mode(
133
+ self,
134
+ control_plane_url: Optional[str] = None,
135
+ api_key: str = "",
136
+ interval_seconds: int = 30,
137
+ on_error: Optional[Callable[[Exception], None]] = None,
138
+ ) -> None:
139
+ """
140
+ Start sending heartbeats to the control plane.
141
+
142
+ Auto-detects runtime:
143
+ - Running event loop → asyncio.create_task()
144
+ - No event loop → threading.Timer(daemon=True)
145
+
146
+ control_plane_url falls back to AGENTSPEC_CONTROL_PLANE_URL (injected into the
147
+ agent container by the operator webhook); raises ValueError when neither is set.
148
+
149
+ Idempotent: calling twice has no effect.
150
+ """
151
+ if self._active:
152
+ return
153
+
154
+ control_plane_url = control_plane_url or os.environ.get(CONTRACT.env.controlPlaneUrl)
155
+ if not control_plane_url:
156
+ raise ValueError(
157
+ "start_push_mode: no control plane URL — pass control_plane_url "
158
+ f"or set {CONTRACT.env.controlPlaneUrl}"
159
+ )
160
+ if not api_key:
161
+ raise ValueError("start_push_mode: api_key is required (the per-agent token from POST /api/v1/register)")
162
+
163
+ with self._lock:
164
+ self._active = True
165
+ self._generation += 1
166
+ generation = self._generation
167
+ self._control_plane_url = control_plane_url
168
+ self._api_key = api_key
169
+ self._interval_seconds = interval_seconds
170
+ self._on_error = on_error
171
+
172
+ try:
173
+ asyncio.get_running_loop()
174
+ # Async mode: schedule with asyncio
175
+ self._task = asyncio.create_task(self._async_push_loop())
176
+ except RuntimeError:
177
+ # Sync mode: fire immediately, then use threading.Timer to repeat
178
+ self._fire_and_reschedule(generation)
179
+
180
+ def stop_push_mode(self) -> None:
181
+ """Stop sending heartbeats to the control plane."""
182
+ with self._lock:
183
+ self._active = False
184
+ self._generation += 1
185
+ if self._timer is not None:
186
+ self._timer.cancel()
187
+ self._timer = None
188
+ if self._task is not None:
189
+ self._task.cancel()
190
+ self._task = None
191
+
192
+ def is_push_mode_active(self) -> bool:
193
+ """Returns True if heartbeats are currently being sent."""
194
+ return self._active
195
+
196
+ # ── Internals ─────────────────────────────────────────────────────────────
197
+
198
+ def _fire_and_reschedule(self, generation: int) -> None:
199
+ """Run one push synchronously, then schedule the next via threading.Timer.
200
+
201
+ A callback in flight across stop/start sees a newer generation and ends its chain.
202
+ """
203
+ if generation != self._generation:
204
+ return
205
+ self._push_sync()
206
+ with self._lock: # a stop/start landing between the check and the Timer would orphan a stale timer
207
+ if generation != self._generation:
208
+ return
209
+ self._timer = threading.Timer(self._interval_seconds, self._fire_and_reschedule, args=(generation,))
210
+ self._timer.daemon = True
211
+ self._timer.start()
212
+
213
+ def _heartbeat_payload(self) -> Dict[str, Any]:
214
+ """Heartbeat body: health telemetry plus EvidenceRecord[] and evidence point aggregates; never `gap` (ADR-0008)."""
215
+ points, self._shipping = self.evidence.begin_ship(ttl_seconds=math.ceil(self._interval_seconds * 2))
216
+ payload: Dict[str, Any] = {
217
+ "contract": CONTRACT.version,
218
+ "health": self.get_report().model_dump(),
219
+ "records": [],
220
+ "evidencePoints": points,
221
+ }
222
+ if _size(payload) > MAX_HEARTBEAT_BYTES:
223
+ # Over the limit: keep every point's state and counts, drop the sample records.
224
+ for aggregate in payload["evidencePoints"]:
225
+ aggregate["records"] = []
226
+ return payload
227
+
228
+ def _too_large(self, payload: Dict[str, Any]) -> bool:
229
+ """A heartbeat the control plane would reject (HTTP 413) is not sent; the next one still goes out."""
230
+ size = _size(payload)
231
+ if size <= MAX_HEARTBEAT_BYTES:
232
+ return False
233
+ if self._on_error:
234
+ self._on_error(Exception(f"Heartbeat not sent: {size} bytes exceeds the {MAX_HEARTBEAT_BYTES} byte limit (health data too large)"))
235
+ return True
236
+
237
+ def _heartbeat_answered(self, status_code: int) -> None:
238
+ """A shipped evidence window leaves the SDK only on success; a failed one rides the next heartbeat."""
239
+ if 200 <= status_code < 300: # httpx does not follow redirects: a 3xx never reached the control plane
240
+ self.evidence.subtract(self._shipping)
241
+ elif self._on_error:
242
+ self._on_error(Exception(f"Heartbeat failed: HTTP {status_code}"))
243
+
244
+ def _begin_heartbeat(self) -> bool:
245
+ """Claim the single heartbeat slot; False when a heartbeat is already in flight."""
246
+ with self._lock:
247
+ if self._heartbeat_in_flight:
248
+ return False
249
+ self._heartbeat_in_flight = True
250
+ return True
251
+
252
+ def _end_heartbeat(self) -> None:
253
+ with self._lock:
254
+ self._heartbeat_in_flight = False
255
+
256
+ def _push_sync(self) -> None:
257
+ """Send one heartbeat synchronously via httpx."""
258
+ if not self._begin_heartbeat():
259
+ return
260
+ try:
261
+ self._push_sync_claimed()
262
+ finally:
263
+ self._end_heartbeat()
264
+
265
+ def _push_sync_claimed(self) -> None:
266
+ payload = self._heartbeat_payload()
267
+ if self._too_large(payload):
268
+ return
269
+ try:
270
+ resp = httpx.post(
271
+ f"{self._control_plane_url}{CONTRACT.controlPlanePaths.heartbeat}",
272
+ json=payload,
273
+ headers={
274
+ "Authorization": f"Bearer {self._api_key}",
275
+ "Content-Type": "application/json",
276
+ },
277
+ timeout=10.0,
278
+ )
279
+ self._heartbeat_answered(resp.status_code)
280
+ except Exception as exc:
281
+ if self._on_error:
282
+ msg = str(exc).replace(self._api_key, "[REDACTED]")
283
+ self._on_error(Exception(msg))
284
+
285
+ async def _async_push_loop(self) -> None:
286
+ """Async loop: push, sleep, repeat until stopped."""
287
+ while self._active:
288
+ await self._push_async()
289
+ await asyncio.sleep(self._interval_seconds)
290
+
291
+ async def _push_async(self) -> None:
292
+ """Send one heartbeat asynchronously via httpx."""
293
+ if not self._begin_heartbeat():
294
+ return
295
+ try:
296
+ await self._push_async_claimed()
297
+ finally:
298
+ self._end_heartbeat()
299
+
300
+ async def _push_async_claimed(self) -> None:
301
+ payload = self._heartbeat_payload()
302
+ if self._too_large(payload):
303
+ return
304
+ try:
305
+ async with httpx.AsyncClient() as client:
306
+ resp = await client.post(
307
+ f"{self._control_plane_url}{CONTRACT.controlPlanePaths.heartbeat}",
308
+ json=payload,
309
+ headers={
310
+ "Authorization": f"Bearer {self._api_key}",
311
+ "Content-Type": "application/json",
312
+ },
313
+ timeout=10.0,
314
+ )
315
+ self._heartbeat_answered(resp.status_code)
316
+ except Exception as exc:
317
+ if self._on_error:
318
+ msg = str(exc).replace(self._api_key, "[REDACTED]")
319
+ self._on_error(Exception(msg))