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.
- agentspec_sdk/__init__.py +19 -0
- agentspec_sdk/agentspec_contract.py +522 -0
- agentspec_sdk/evidence_points.py +385 -0
- agentspec_sdk/manifest.py +36 -0
- agentspec_sdk/manifest_hash.py +52 -0
- agentspec_sdk/memory_points.py +359 -0
- agentspec_sdk/reporter.py +319 -0
- agentspec_sdk/types.py +33 -0
- agentspec_sdk-0.5.0.dist-info/METADATA +75 -0
- agentspec_sdk-0.5.0.dist-info/RECORD +11 -0
- agentspec_sdk-0.5.0.dist-info/WHEEL +4 -0
|
@@ -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()
|