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,385 @@
1
+ """
2
+ Evidence points the agent's code wires itself (ADR-0038, ADR-0039): `guardrail` wraps a guardrail
3
+ function, or guards a block, so the heartbeat can say whether the guardrail ran.
4
+
5
+ Each evidence point and target the registry gives for the manifest is `not_wired` until the agent
6
+ creates its wrapper, `wired` from then on, and `fired` in a window where it was called. A point the
7
+ code never wires is reported `not_wired`, never passed.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import functools
13
+ import inspect
14
+ import json
15
+ import logging
16
+ import re
17
+ from collections import deque
18
+ import threading
19
+ from datetime import datetime, timezone
20
+ from typing import Any, Callable, Deque, Dict, List, Optional, Tuple
21
+
22
+ from .agentspec_contract import AgentSpecContract, Collector, Origin, Point, Source, State
23
+ from .manifest_hash import canonical_manifest_sha256
24
+
25
+ CONTRACT = AgentSpecContract()
26
+ GUARDRAIL = Point.guardrail.value
27
+ TOOL = Point.tool.value
28
+ MCP_CLIENT = Point.mcpClient.value
29
+ LOGGING = Point.logging.value
30
+ MEMORY_WRITE = Point.memoryWrite.value
31
+ VECTOR_STORE = Point.vectorStore.value
32
+ MCP_LIST, MCP_CALL = CONTRACT.evidencePoints[MCP_CLIENT] # the contract names the two targets: list, then call
33
+ SCRUB, TTL, AUDIT = CONTRACT.evidencePoints[MEMORY_WRITE] # memory writes: scrub, TTL, audit entry
34
+ (NAMESPACE,) = CONTRACT.evidencePoints[VECTOR_STORE]
35
+
36
+ _Key = Tuple[str, str]
37
+ _default: Optional["EvidencePoints"] = None
38
+
39
+
40
+ def _now() -> datetime:
41
+ return datetime.now(timezone.utc)
42
+
43
+
44
+ def _rfc3339(moment: datetime) -> str:
45
+ return moment.strftime("%Y-%m-%dT%H:%M:%S.") + f"{moment.microsecond // 1000:03d}Z"
46
+
47
+
48
+ class _Calls:
49
+ """Calls of one point in the window: the total, and only the last few timestamps."""
50
+
51
+ def __init__(self) -> None:
52
+ self.total = 0
53
+ self.counts = {"pass": 0, "fail": 0, "not_verifiable": 0}
54
+ self.last: Deque[Tuple[datetime, Optional[str], str, Optional[Dict[str, str]], int]] = deque(
55
+ maxlen=CONTRACT.evidencePointRecordLimit
56
+ )
57
+
58
+ def add(self, at: datetime, subject: Optional[str], status: str, reason: Optional[Dict[str, str]]) -> None:
59
+ self.total += 1
60
+ self.counts[status] += 1
61
+ self.last.append((at, subject, status, reason, self.total)) # the total at the call orders it within the window
62
+
63
+ def subtract(self, shipped_counts: Dict[str, int], shipped_total: int) -> None:
64
+ """Drop what a heartbeat shipped; calls recorded after it was taken stay."""
65
+ for status, n in shipped_counts.items():
66
+ self.counts[status] -= n
67
+ self.total -= shipped_total
68
+ kept = ((a, b, c, d, e - shipped_total) for a, b, c, d, e in self.last if e > shipped_total)
69
+ self.last = deque(kept, maxlen=self.last.maxlen)
70
+
71
+
72
+ class Shipped:
73
+ """What one heartbeat carried: the counts per point and the end of its window; `subtract()` removes exactly this."""
74
+
75
+ def __init__(self, counts: Dict[_Key, Tuple[Dict[str, int], int]], window_end: datetime) -> None:
76
+ self.counts = counts
77
+ self.window_end = window_end
78
+
79
+
80
+ class EvidencePoints:
81
+ """Per-agent state of the wired evidence points; the reporter reads it for each heartbeat."""
82
+
83
+ def __init__(self, manifest: Dict[str, Any]) -> None:
84
+ self._manifest_sha256 = canonical_manifest_sha256(manifest)
85
+ self._applicable = self._applicable_points(manifest)
86
+ self._memory = (manifest.get("spec") or {}).get("memory") or {}
87
+ self._mcp_servers = [s.get("name") for s in self._stdio_servers(manifest.get("spec") or {})]
88
+ self._lock = threading.Lock()
89
+ self._wired: set[_Key] = set()
90
+ self._calls = self._empty_window()
91
+ self._window_start = _now()
92
+
93
+ @staticmethod
94
+ def _stdio_servers(spec: Dict[str, Any]) -> List[Dict[str, Any]]:
95
+ return [s for s in (spec.get("mcp") or {}).get("servers") or [] if s.get("transport") == "stdio"]
96
+
97
+ @classmethod
98
+ def _declared_targets(cls, manifest: Dict[str, Any]) -> Dict[str, set]:
99
+ """Point -> the targets this manifest declares something for (a guardrail direction, local tools, stdio MCP, structured logs)."""
100
+ spec = manifest.get("spec") or {}
101
+ guardrails = spec.get("guardrails") or {}
102
+ stdio_mcp = bool(cls._stdio_servers(spec))
103
+ local_tools = any(t.get("type") == "function" for t in spec.get("tools") or [])
104
+ logging_spec = (spec.get("observability") or {}).get("logging")
105
+ structured_logs = logging_spec is not None and logging_spec.get("structured", True) is not False
106
+ return {
107
+ MEMORY_WRITE: cls._memory_write_targets(spec.get("memory") or {}),
108
+ VECTOR_STORE: {NAMESPACE} if ((spec.get("memory") or {}).get("vector") or {}).get("namespace") else set(),
109
+ GUARDRAIL: {t for t in CONTRACT.evidencePoints[GUARDRAIL] if guardrails.get(t)},
110
+ TOOL: set(CONTRACT.evidencePoints[TOOL]) if local_tools else set(),
111
+ MCP_CLIENT: set(CONTRACT.evidencePoints[MCP_CLIENT]) if stdio_mcp else set(),
112
+ LOGGING: set(CONTRACT.evidencePoints[LOGGING]) if structured_logs else set(),
113
+ }
114
+
115
+ @staticmethod
116
+ def _memory_write_targets(memory: Dict[str, Any]) -> set:
117
+ """scrub: PII fields declared; ttl: a TTL declared on a backend; audit: long-term memory with the audit log on."""
118
+ hygiene = memory.get("hygiene") or {}
119
+ targets = set()
120
+ if hygiene.get("piiScrubFields"):
121
+ targets.add(SCRUB)
122
+ declared_ttls = [(memory.get("shortTerm") or {}).get("ttlSeconds"), (memory.get("longTerm") or {}).get("ttlDays")]
123
+ if any(ttl is not None for ttl in declared_ttls): # ttlSeconds: 0 is session-scoped retention, still a declared TTL
124
+ targets.add(TTL)
125
+ if memory.get("longTerm") and hygiene.get("auditLog") is True:
126
+ targets.add(AUDIT)
127
+ return targets
128
+
129
+ @classmethod
130
+ def _applicable_points(cls, manifest: Dict[str, Any]) -> Dict[_Key, str]:
131
+ """(point, target) -> rule id, for every point the registry lists for a rule this manifest declares."""
132
+ declared = cls._declared_targets(manifest)
133
+ applicable: Dict[_Key, str] = {}
134
+ for point, targets in CONTRACT.evidencePoints.items():
135
+ for target, rule_id in targets.items():
136
+ listed = any(s.point and s.point.value == point for s in CONTRACT.ruleEvidence[rule_id].sources)
137
+ if listed and target in declared.get(point, set()):
138
+ applicable[(point, target)] = rule_id
139
+ return applicable
140
+
141
+ def memory_spec(self) -> Dict[str, Any]:
142
+ return self._memory
143
+
144
+ def applies(self, point: str, target: str) -> bool:
145
+ return (point, target) in self._applicable
146
+
147
+ def declared_mcp_servers(self) -> List[str]:
148
+ return list(self._mcp_servers)
149
+
150
+ def _empty_window(self) -> Dict[_Key, "_Calls"]:
151
+ return {key: _Calls() for key in self._applicable}
152
+
153
+ def register(self, point: str, target: str) -> None:
154
+ with self._lock:
155
+ self._wired.add((point, target))
156
+
157
+ def record_call(
158
+ self, point: str, target: str, subject: Optional[str] = None,
159
+ status: str = "pass", reason: Optional[Dict[str, str]] = None,
160
+ ) -> None:
161
+ """A call of the point; `status` is pass, fail or not_verifiable, and the last two carry a `reason`."""
162
+ if status != "pass" and not reason:
163
+ raise ValueError(f"record_call: a {status} call of {point}:{target} needs a reason")
164
+ with self._lock:
165
+ if (point, target) in self._applicable:
166
+ self._calls[(point, target)].add(_now(), subject, status, reason)
167
+
168
+ def snapshot(self, ttl_seconds: int) -> List[Dict[str, Any]]:
169
+ """Aggregates of the window since the last snapshot, then start the next window."""
170
+ with self._lock:
171
+ window_end = _now()
172
+ aggregates = self._aggregates(ttl_seconds, window_end)
173
+ self._calls = self._empty_window()
174
+ self._window_start = window_end
175
+ return aggregates
176
+
177
+ def begin_ship(self, ttl_seconds: int) -> Tuple[List[Dict[str, Any]], "Shipped"]:
178
+ """Aggregates of the window to send, which stays until `subtract()` acknowledges the returned `Shipped`."""
179
+ with self._lock:
180
+ window_end = _now()
181
+ aggregates = self._aggregates(ttl_seconds, window_end)
182
+ counts = {key: (dict(c.counts), c.total) for key, c in self._calls.items()}
183
+ return aggregates, Shipped(counts, window_end)
184
+
185
+ def subtract(self, shipped: "Shipped") -> None:
186
+ """Remove an acknowledged window: calls made after it was taken stay, and the next window starts where it ended."""
187
+ with self._lock:
188
+ for key, (counts, total) in shipped.counts.items():
189
+ self._calls[key].subtract(counts, total)
190
+ self._window_start = shipped.window_end
191
+
192
+ def _aggregates(self, ttl_seconds: int, window_end: datetime) -> List[Dict[str, Any]]:
193
+ window = {"start": _rfc3339(self._window_start), "end": _rfc3339(window_end)}
194
+ return [self._aggregate(key, rule_id, window, ttl_seconds) for key, rule_id in self._applicable.items()]
195
+
196
+ def _aggregate(self, key: _Key, rule_id: str, window: Dict[str, str], ttl_seconds: int) -> Dict[str, Any]:
197
+ point, target = key
198
+ calls = self._calls[key]
199
+ state = State.fired if calls.total else State.wired if key in self._wired else State.not_wired
200
+ records = [
201
+ {
202
+ "checkId": subject or f"{point}:{target}", "ruleId": rule_id, "status": status,
203
+ **({"reason": reason} if reason else {}),
204
+ "source": Source.sdk_observed.value, "origin": Origin.in_process.value,
205
+ "collector": Collector.sdk.value, "observedAt": _rfc3339(at),
206
+ "window": window, "ttlSeconds": ttl_seconds, "sampleSize": calls.total,
207
+ "traceIds": [], "manifestSha256": self._manifest_sha256,
208
+ }
209
+ for at, subject, status, reason, _ in calls.last
210
+ ]
211
+ # A guardrail call proves it ran where it is wired, whether it blocked or allowed the input.
212
+ return {"point": point, "target": target, "state": state.value, "counts": dict(calls.counts), "records": records}
213
+
214
+
215
+ class _Guardrail:
216
+ """Decorator and context manager returned by `guardrail`; creating it registers the point."""
217
+
218
+ def __init__(self, points: EvidencePoints, target: str) -> None:
219
+ self._points = points
220
+ self._target = target
221
+ points.register(GUARDRAIL, target)
222
+
223
+ def _fired(self) -> None:
224
+ self._points.record_call(GUARDRAIL, self._target)
225
+
226
+ def __enter__(self) -> "_Guardrail":
227
+ self._fired()
228
+ return self
229
+
230
+ def __exit__(self, *exc_info: Any) -> None:
231
+ return None
232
+
233
+ def __call__(self, fn: Callable[..., Any]) -> Callable[..., Any]:
234
+ return _call_wrapper(fn, self._fired)
235
+
236
+
237
+ def _default_points(name: str) -> EvidencePoints:
238
+ if _default is None:
239
+ raise RuntimeError(
240
+ f"{name}: no AgentSpecReporter exists yet — create one first "
241
+ "(AgentSpecReporter.from_yaml('agent.yaml'))"
242
+ )
243
+ return _default
244
+
245
+
246
+ def _call_wrapper(fn: Callable[..., Any], fire: Callable[[], None]) -> Callable[..., Any]:
247
+ """`fn` with `fire()` called before every call, sync or async; a raising `fn` still counts as called."""
248
+ if inspect.iscoroutinefunction(fn):
249
+ @functools.wraps(fn)
250
+ async def awrapper(*args: Any, **kwargs: Any) -> Any:
251
+ fire()
252
+ return await fn(*args, **kwargs)
253
+ return awrapper
254
+
255
+ @functools.wraps(fn)
256
+ def wrapper(*args: Any, **kwargs: Any) -> Any:
257
+ fire()
258
+ return fn(*args, **kwargs)
259
+ return wrapper
260
+
261
+
262
+ def set_default(points: EvidencePoints) -> None:
263
+ """The reporter created last is the one `guardrail` reports to."""
264
+ global _default
265
+ _default = points
266
+
267
+
268
+ def guardrail(target: str) -> _Guardrail:
269
+ """
270
+ Wrap a guardrail function (`@guardrail("input")`) or a block (`with guardrail("output"):`).
271
+
272
+ `target` is `input` or `output`: the guardrails the agent declares in spec.guardrails.
273
+ """
274
+ points = _default_points("guardrail")
275
+ valid = list(CONTRACT.evidencePoints[GUARDRAIL])
276
+ if target not in valid:
277
+ raise ValueError(f"guardrail: unknown target {target!r}; use one of {', '.join(valid)}")
278
+ return _Guardrail(points, target)
279
+
280
+
281
+ def _slugify(name: str) -> str:
282
+ return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")
283
+
284
+
285
+ def tool(name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
286
+ """Wrap a local tool function (`@tool("search")`); each call is a TOOL-01 record naming the tool."""
287
+ points = _default_points("tool")
288
+ target = next(iter(CONTRACT.evidencePoints[TOOL]))
289
+ points.register(TOOL, target)
290
+ subject = f"{TOOL}:{_slugify(name)}" # same id as toolCheckId in packages/sdk/src/health/tool-check-id.ts
291
+ return lambda fn: _call_wrapper(fn, lambda: points.record_call(TOOL, target, subject))
292
+
293
+
294
+ class _McpClient:
295
+ """Delegating proxy around a stdio MCP client session: `list_tools` and `call_tool` are recorded."""
296
+
297
+ def __init__(self, points: EvidencePoints, session: Any, server: str) -> None:
298
+ self._points = points
299
+ self._session = session
300
+ self._server = server
301
+ for target in CONTRACT.evidencePoints[MCP_CLIENT]:
302
+ points.register(MCP_CLIENT, target)
303
+
304
+ async def list_tools(self, *args: Any, **kwargs: Any) -> Any:
305
+ self._points.record_call(MCP_CLIENT, MCP_LIST, f"mcp:{self._server}:{MCP_LIST}")
306
+ return await self._session.list_tools(*args, **kwargs)
307
+
308
+ async def call_tool(self, name: str, *args: Any, **kwargs: Any) -> Any:
309
+ self._points.record_call(MCP_CLIENT, MCP_CALL, f"mcp:{self._server}:{MCP_CALL}:{name}")
310
+ return await self._session.call_tool(name, *args, **kwargs)
311
+
312
+ def __getattr__(self, attr: str) -> Any:
313
+ return getattr(self._session, attr)
314
+
315
+
316
+ def mcp_client(session: Any, server: str) -> _McpClient:
317
+ """Wrap a stdio MCP client session; `server` is its name in spec.mcp.servers."""
318
+ points = _default_points("mcp_client")
319
+ declared = points.declared_mcp_servers()
320
+ if server not in declared:
321
+ raise ValueError(
322
+ f"mcp_client: {server!r} is not a stdio server in spec.mcp.servers; declared: {', '.join(declared) or 'none'}"
323
+ )
324
+ return _McpClient(points, session, server)
325
+
326
+
327
+ class _JsonFormatter(logging.Formatter):
328
+ def format(self, record: logging.LogRecord) -> str:
329
+ line = {
330
+ "time": _rfc3339(datetime.fromtimestamp(record.created, timezone.utc)),
331
+ "level": record.levelname, "logger": record.name, "message": record.getMessage(),
332
+ }
333
+ if record.exc_info:
334
+ line["exception"] = self.formatException(record.exc_info)
335
+ if record.stack_info:
336
+ line["stack"] = self.formatStack(record.stack_info)
337
+ return json.dumps(line)
338
+
339
+
340
+ def _propagated_stream_handlers(logger: logging.Logger) -> List[logging.StreamHandler]:
341
+ """Stream handlers a record of `logger` reaches: its own, then each ancestor's while it propagates."""
342
+ found: List[logging.StreamHandler] = []
343
+ current: Optional[logging.Logger] = logger
344
+ while current is not None:
345
+ found += [h for h in current.handlers if isinstance(h, logging.StreamHandler)]
346
+ current = current.parent if current.propagate else None
347
+ return found
348
+
349
+
350
+ def _record_after_write(handler: logging.Handler, points: EvidencePoints, target: str) -> None:
351
+ """Record each line once the handler has written it: a write that fails (`handleError`) proves nothing."""
352
+ handler._agentspec_logging = (points, target) # a second call only retargets the points
353
+ if getattr(handler, "_agentspec_wrapped", False):
354
+ return
355
+ handler._agentspec_wrapped = True
356
+ emit, handle_error = handler.emit, handler.handleError
357
+
358
+ def checked_emit(record: logging.LogRecord) -> None:
359
+ failed = []
360
+ handler.handleError = lambda r: (failed.append(r), handle_error(r))[1]
361
+ try:
362
+ emit(record)
363
+ finally:
364
+ handler.handleError = handle_error
365
+ if not failed:
366
+ wired_points, wired_target = handler._agentspec_logging
367
+ wired_points.record_call(LOGGING, wired_target, f"{LOGGING}:{record.name}")
368
+
369
+ handler.emit = checked_emit
370
+
371
+
372
+ def structured_logging(logger: Optional[logging.Logger] = None, stream: Any = None) -> None:
373
+ """Make the stream handlers `logger` (default: root) logs through emit JSON, adding one on `stream` if there is none; each line is OBS-02 evidence."""
374
+ points = _default_points("structured_logging")
375
+ target = next(iter(CONTRACT.evidencePoints[LOGGING]))
376
+ logger = logger or logging.getLogger()
377
+ formatter = _JsonFormatter()
378
+ handlers = _propagated_stream_handlers(logger)
379
+ if not handlers:
380
+ handlers = [logging.StreamHandler(stream)]
381
+ logger.addHandler(handlers[0])
382
+ for handler in handlers:
383
+ handler.setFormatter(formatter)
384
+ _record_after_write(handler, points, target)
385
+ points.register(LOGGING, target)
@@ -0,0 +1,36 @@
1
+ """
2
+ Manifest loader — reads agent.yaml with PyYAML.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from typing import Any, Dict
8
+
9
+ import re
10
+
11
+ import yaml
12
+
13
+
14
+ class _JsonSchemaLoader(yaml.SafeLoader):
15
+ """Scalars resolve as js-yaml's JSON_SCHEMA does (what `agentspec register` hashes): `yes` and dates stay strings."""
16
+
17
+
18
+ _JSON_SCALARS = {
19
+ "tag:yaml.org,2002:bool": (r"^(?:true|false)$", "tf"),
20
+ "tag:yaml.org,2002:null": (r"^null$", "n"),
21
+ "tag:yaml.org,2002:int": (r"^-?(?:0|[1-9][0-9]*)$", "-0123456789"),
22
+ "tag:yaml.org,2002:float": (r"^-?(?:0|[1-9][0-9]*)(?:\.[0-9]*)?(?:[eE][-+]?[0-9]+)?$", "-0123456789"),
23
+ }
24
+
25
+ _JsonSchemaLoader.yaml_implicit_resolvers = {}
26
+ for _tag, (_pattern, _first) in _JSON_SCALARS.items():
27
+ _JsonSchemaLoader.add_implicit_resolver(_tag, re.compile(_pattern), list(_first))
28
+
29
+
30
+ def load_manifest(path: str) -> Dict[str, Any]:
31
+ """Load and parse an agent.yaml file. Returns the raw manifest dict."""
32
+ with open(path, "r", encoding="utf-8") as f:
33
+ data = yaml.load(f, Loader=_JsonSchemaLoader) # noqa: S506 - a SafeLoader subclass
34
+ if not isinstance(data, dict):
35
+ raise ValueError(f"agent.yaml at {path!r} must be a YAML mapping")
36
+ return data
@@ -0,0 +1,52 @@
1
+ """Canonical manifest hash: sha256 of the manifest as written in agent.yaml, as canonical JSON.
2
+
3
+ Same rules as the CLI's `canonicalJson` and the control plane's `canonical_json`; all three run
4
+ test/fixtures/manifest-hash.json (the control plane does not depend on this package, so each keeps its own copy). Evidence records carry it as `manifestSha256`.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import hashlib
10
+ import json
11
+ from decimal import Decimal
12
+ from typing import Any
13
+
14
+
15
+ def _es_number(value: int | float) -> str:
16
+ """A number as ECMAScript's Number::toString prints it (what JSON.stringify emits)."""
17
+ if value == 0:
18
+ return "0"
19
+ sign, digits_tuple, exponent = Decimal(repr(float(value))).as_tuple()
20
+ digits = "".join(map(str, digits_tuple)).rstrip("0") or "0"
21
+ n = len(digits_tuple) + exponent # value = 0.<digits> * 10**n
22
+ k = len(digits)
23
+ if k <= n <= 21:
24
+ body = digits + "0" * (n - k)
25
+ elif 0 < n <= 21:
26
+ body = digits[:n] + "." + digits[n:]
27
+ elif -6 < n <= 0:
28
+ body = "0." + "0" * -n + digits
29
+ else:
30
+ e = n - 1
31
+ mantissa = digits if k == 1 else digits[0] + "." + digits[1:]
32
+ body = f"{mantissa}e{'+' if e >= 0 else '-'}{abs(e)}"
33
+ return ("-" if sign else "") + body
34
+
35
+
36
+ def _canonical_json(value: Any) -> str:
37
+ if value is None:
38
+ return "null"
39
+ if isinstance(value, bool):
40
+ return "true" if value else "false"
41
+ if isinstance(value, (int, float)):
42
+ return _es_number(value)
43
+ if isinstance(value, str):
44
+ return json.dumps(value, ensure_ascii=False)
45
+ if isinstance(value, list):
46
+ return "[" + ",".join(_canonical_json(v) for v in value) + "]"
47
+ members = sorted(value.items(), key=lambda kv: kv[0].encode("utf-16-be"))
48
+ return "{" + ",".join(f"{json.dumps(k, ensure_ascii=False)}:{_canonical_json(v)}" for k, v in members) + "}"
49
+
50
+
51
+ def canonical_manifest_sha256(manifest: dict[str, Any]) -> str:
52
+ return hashlib.sha256(_canonical_json(manifest).encode("utf-8")).hexdigest()