@mokuyoaxis/agent-guard 0.2.3-rc1 → 0.2.3-rc2

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.
Files changed (39) hide show
  1. package/README.md +51 -20
  2. package/README.zh-CN.md +45 -16
  3. package/adapters/dsh/README.md +81 -4
  4. package/adapters/dsh/harness/README.md +328 -0
  5. package/adapters/dsh/harness/baseline.patch.yml +8 -0
  6. package/adapters/dsh/harness/guard_lab.py +609 -0
  7. package/adapters/dsh/harness/native_session.py +482 -0
  8. package/adapters/dsh/harness/profiles.py +160 -0
  9. package/adapters/dsh/harness/read_fixture.py +60 -0
  10. package/adapters/dsh/harness/retry_stream.py +171 -0
  11. package/adapters/dsh/harness/session_decode.mjs +117 -0
  12. package/adapters/dsh/lib/index.js +46 -5
  13. package/adapters/dsh/lib/read_result_guard.js +207 -0
  14. package/adapters/dsh/lib/read_result_guard.py +139 -0
  15. package/adapters/harness_support.py +109 -0
  16. package/adapters/kimi-code/README.md +7 -0
  17. package/adapters/kimi-code/harness/README.md +126 -0
  18. package/adapters/kimi-code/harness/guard_lab.py +430 -0
  19. package/core/lab.py +2373 -0
  20. package/docs/architecture.md +75 -0
  21. package/docs/friction.md +72 -0
  22. package/docs/guard-lab-clean-task.md +4 -0
  23. package/docs/guard-lab-trial-task.md +5 -0
  24. package/docs/guard-lab.md +391 -0
  25. package/docs/harness-capabilities.md +7 -4
  26. package/docs/release-notes-0.2.3-rc2.md +189 -0
  27. package/docs/release-notes-0.2.3.md +45 -0
  28. package/docs/test-report-dsh-0.2-upgrade.md +142 -0
  29. package/docs/test-report-dsh-guard-lab.md +154 -0
  30. package/docs/test-report-dsh-native-session.md +118 -0
  31. package/docs/test-report-dsh-paired-lab.md +183 -0
  32. package/docs/test-report-dsh-read-redaction.md +114 -0
  33. package/docs/test-report-dsh-real-followup.md +170 -0
  34. package/docs/test-report-dsh-retry-evidence.md +134 -0
  35. package/docs/test-report-kimi-guard-lab.md +117 -0
  36. package/docs/test-report-release-readiness-0.2.3.md +161 -0
  37. package/docs/threat-model.md +42 -0
  38. package/guard_lab.py +14 -0
  39. package/package.json +8 -5
@@ -0,0 +1,482 @@
1
+ """Bounded capture of fresh DSH v3/v4 single-turn sessions, without replay."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ from pathlib import Path
8
+ import shutil
9
+
10
+ from adapters.harness_support import capture_process, digest, read_regular, write_new
11
+ from core.lab import LabError, MAX_SCAN_BYTES
12
+ from adapters.dsh.harness.retry_stream import (
13
+ MAX_ATTEMPTS, MAX_STREAM_CHUNKS, failure_supported, finite_number,
14
+ inspect_stream, json_bytes,
15
+ )
16
+
17
+
18
+ DECODER = Path(__file__).with_name("session_decode.mjs")
19
+ MAX_RECORDS = 4096
20
+ MAX_TREE_ENTRIES = 512
21
+ PARSER_VERSION = 2
22
+ # Frozen vocabulary from DSH 0.1.5-rc.1's dsh-session known-event-types.
23
+ KNOWN_EVENTS = frozenset("""
24
+ agent-preset/selected agent/inbox/spliced approval/asked approval/decided
25
+ approval/policy assistant/attempt assistant/message command/done command/run
26
+ compaction/end compaction/prune compaction/start compaction/summary
27
+ deliverables/presented feedback/message-delete feedback/message-put feedback/record
28
+ goal/change hook/invoked hook/result llm/retry llm/retry-started model/selection
29
+ permission/preset plan/mode request/context request/header sandbox/mode
30
+ schedule/change session-log-deepseek/delivery-accepted session/end-seed session/title
31
+ session/title-llm-request step/end step/start subagent/catalog subagent/descriptor
32
+ subagent/model-selection-policy system/message team/member team/message/delivered
33
+ team/message/queued team/task todo/write tool-workflow/agent-end
34
+ tool-workflow/agent-start tool-workflow/run-end tool-workflow/run-start tool/call
35
+ tool/ptc-dispatch tool/ptc-dispatch-start tool/result turn/end turn/start
36
+ user/message web/deepseek-search-llm-request
37
+ """.split())
38
+ V4_EVENTS = KNOWN_EVENTS | {"developer/message", "image/offload", "workspace/changes"}
39
+
40
+
41
+ def check_decoder(executable: str, cwd: Path, environment: dict) -> tuple[dict, str]:
42
+ selected = shutil.which(executable)
43
+ if not selected:
44
+ raise LabError("native DSH capture requires a Node runtime with Zstandard support")
45
+ selected = str(Path(selected).absolute())
46
+ host, streams = capture_process([selected, str(DECODER), "--probe"], cwd, environment, 10)
47
+ try:
48
+ value = json.loads(streams["stdout"])
49
+ except (ValueError, UnicodeError):
50
+ value = {}
51
+ if (
52
+ host["exit_code"] != 0 or host["timed_out"] or host["output_limit_exceeded"]
53
+ or not isinstance(value, dict) or value.get("zstd_supported") is not True
54
+ or not isinstance(value.get("version"), str)
55
+ ):
56
+ raise LabError("native DSH capture requires a Node runtime with Zstandard support")
57
+ return {"node_version": value["version"], "decoder": "concatenated-zstd-v1"}, selected
58
+
59
+
60
+ def session_inventory(home: Path) -> set[Path]:
61
+ """Inventory names, never contents; refuse symlinks and oversized trees."""
62
+ root = home / "sessions"
63
+ if root.is_symlink():
64
+ raise LabError("native session tree must not contain symlinks")
65
+ if not root.exists():
66
+ return set()
67
+ if not root.is_dir():
68
+ raise LabError("native session root must be a directory")
69
+ files = set()
70
+ count = 0
71
+ def fail(_error):
72
+ raise LabError("native session inventory was unreadable")
73
+ for base, dirs, names in os.walk(root, followlinks=False, onerror=fail):
74
+ if len(Path(base).relative_to(root).parts) > 4:
75
+ raise LabError("native session tree exceeds its depth limit")
76
+ count += len(dirs) + len(names)
77
+ if count > MAX_TREE_ENTRIES:
78
+ raise LabError("native session tree exceeds its entry limit")
79
+ for name in (*dirs, *names):
80
+ item = Path(base) / name
81
+ if item.is_symlink():
82
+ raise LabError("native session tree must not contain symlinks")
83
+ for name in names:
84
+ if name.startswith("session.") and name.endswith((".jsonl", ".jsonl.zstd")):
85
+ files.add(Path(base) / name)
86
+ return files
87
+
88
+
89
+ def _integer(value) -> bool:
90
+ return type(value) is int and 0 <= value <= 2**53 - 1
91
+
92
+
93
+ def _object_pairs(pairs):
94
+ result = {}
95
+ for key, value in pairs:
96
+ if key in result:
97
+ raise ValueError("duplicate key")
98
+ result[key] = value
99
+ return result
100
+
101
+
102
+ def _invalid_constant(_value):
103
+ raise ValueError("non-JSON constant")
104
+
105
+
106
+ def _blocks_supported(blocks, depth=0) -> bool:
107
+ if not isinstance(blocks, list) or depth > 8:
108
+ return False
109
+ for block in blocks:
110
+ if not isinstance(block, dict):
111
+ return False
112
+ kind = block.get("type")
113
+ if not isinstance(kind, str):
114
+ return False
115
+ if kind in {"text", "reasoning"}:
116
+ if not isinstance(block.get("text"), str):
117
+ return False
118
+ elif kind == "tool-call":
119
+ if not all(isinstance(block.get(k), str) and block[k] for k in ("id", "name", "arguments")):
120
+ return False
121
+ elif kind == "tool-result":
122
+ if not isinstance(block.get("toolCallId"), str) or not block["toolCallId"]:
123
+ return False
124
+ if "isError" in block and type(block["isError"]) is not bool:
125
+ return False
126
+ if not _blocks_supported(block.get("content"), depth + 1):
127
+ return False
128
+ else:
129
+ # Attachment bytes and unknown blocks cannot be cleared by text scans.
130
+ return False
131
+ return True
132
+
133
+
134
+ def split_session(payload: bytes, fixture: Path, task_sha256: str,
135
+ *, parser_version: int = PARSER_VERSION,
136
+ native_format_version: int = 3) -> tuple[dict, dict[str, bytes]]:
137
+ """Classify model-facing payloads by native event type, not message.role.
138
+
139
+ ToolResultMessage.role is 'user' in v3. Tool-private meta and user/system
140
+ input are preserved in the private raw file, excluded from output scans.
141
+ This reads append-only, unseeded, one-turn fixtures; it does not reconstruct
142
+ arbitrary forks, replacements, attachments or model-visible context.
143
+ Version 2 also scans failed-attempt streams and verifies pinned retry chains.
144
+ Version 1 keeps the frozen interpretation used by earlier capture receipts.
145
+ """
146
+ if type(parser_version) is not int or parser_version not in {1, PARSER_VERSION}:
147
+ raise LabError("unsupported native parser version")
148
+ if (type(native_format_version) is not int or native_format_version not in {3, 4}
149
+ or native_format_version == 4 and parser_version != 2):
150
+ raise LabError("unsupported native format/parser contract")
151
+ channels = {"tool": bytearray(), "assistant": bytearray()}
152
+ if parser_version == 2:
153
+ channels["attempt"] = bytearray()
154
+ counts = {"tool": 0, "assistant": 0, "tool_calls": 0}
155
+ summary = {
156
+ "format_version": native_format_version, "recognized": False, "completed": False,
157
+ "record_count": 0, "counts": counts, "issues": [],
158
+ "cwd_matches": False, "task_matches": False,
159
+ "provenance": "captured-native-event-labels-not-authenticated-authorship",
160
+ }
161
+ if parser_version == 2:
162
+ summary.update({"parser_version": 2, "retry_evidence": {
163
+ "attempts": 0, "scheduled": 0, "started": 0, "stream_chunks": 0,
164
+ }})
165
+ def refuse(issue):
166
+ summary["issues"] = [issue]
167
+ if parser_version == 2:
168
+ summary["completed"] = False
169
+ return summary, {k: b"" for k in channels}
170
+ if not payload or len(payload) > MAX_SCAN_BYTES or not payload.endswith(b"\n"):
171
+ return refuse("EMPTY_OVERSIZED_OR_UNTERMINATED_SESSION")
172
+ try:
173
+ lines = payload.decode("utf-8").splitlines()
174
+ if not 2 <= len(lines) <= MAX_RECORDS or any(not line.strip() for line in lines):
175
+ return refuse("SESSION_RECORD_LIMIT_OR_EMPTY_LINE")
176
+ records = [json.loads(line, object_pairs_hook=_object_pairs, parse_constant=_invalid_constant) for line in lines]
177
+ except (ValueError, UnicodeError, RecursionError):
178
+ return refuse("INVALID_SESSION_JSON")
179
+ summary["record_count"] = len(records)
180
+ header = records[0]
181
+ if (
182
+ not isinstance(header, dict) or header.get("type") != "session"
183
+ or type(header.get("version")) is not int or header["version"] != native_format_version
184
+ or not isinstance(header.get("id"), str) or not header["id"]
185
+ or not _integer(header.get("createdAt")) or header.get("isSeeded") is not False
186
+ or header.get("parentSession") is not None or header.get("origin") is not None
187
+ or type(header.get("delegationDepth", 0)) is not int or header.get("delegationDepth", 0) != 0
188
+ ):
189
+ return refuse("UNSUPPORTED_SESSION_HEADER")
190
+ if native_format_version == 4 and "seedLength" in header:
191
+ return refuse("UNSUPPORTED_SESSION_HEADER")
192
+ try:
193
+ summary["session_id_sha256"] = digest(header["id"].encode())
194
+ except UnicodeError:
195
+ return refuse("INVALID_SESSION_JSON")
196
+ cwd = header.get("cwd")
197
+ try:
198
+ summary["cwd_matches"] = isinstance(cwd, str) and Path(cwd).is_absolute() and Path(cwd).resolve() == fixture.resolve()
199
+ except (OSError, ValueError):
200
+ return refuse("SESSION_CWD_MISMATCH")
201
+ if not summary["cwd_matches"]:
202
+ return refuse("SESSION_CWD_MISMATCH")
203
+ turn = None
204
+ ended = False
205
+ user_count = 0
206
+ calls = {}
207
+ results = set()
208
+ step = None
209
+ closed_steps = set()
210
+ route = None
211
+ pending_retry = None
212
+ retry_chain = None
213
+ step_assistant_seen = False
214
+ unresolved_attempt = False
215
+ request_headers = {}
216
+ for expected_seq, record in enumerate(records[1:]):
217
+ if (
218
+ not isinstance(record, dict) or type(record.get("seq")) is not int
219
+ or record["seq"] != expected_seq or not _integer(record.get("time"))
220
+ or not isinstance(record.get("type"), str) or not isinstance(record.get("data"), dict)
221
+ ):
222
+ return refuse("INVALID_EVENT_ENVELOPE_OR_SEQUENCE")
223
+ kind = record["type"]
224
+ data = record["data"]
225
+ if native_format_version == 4 and "sourceEventSeqs" in record:
226
+ return refuse("UNSUPPORTED_SURFACE_REPLAY")
227
+ known_events = V4_EVENTS if native_format_version == 4 else KNOWN_EVENTS
228
+ if kind not in known_events and record.get("ignorable") is not True:
229
+ return refuse("UNKNOWN_REQUIRED_EVENT")
230
+ if kind in {"system/message", "user/message", "assistant/message", "tool/result"} or (
231
+ native_format_version == 4 and kind == "developer/message"):
232
+ if record.get("surfaceOp") != "append":
233
+ return refuse("UNSUPPORTED_SURFACE_OPERATION")
234
+ if kind == "turn/start":
235
+ if turn is not None or not _integer(data.get("turn")):
236
+ return refuse("UNSUPPORTED_MULTIPLE_OR_INVALID_TURNS")
237
+ turn = data["turn"]
238
+ elif kind == "step/start":
239
+ if turn is None or ended or not _integer(data.get("turn")) or data.get("turn") != turn or step is not None or not _integer(data.get("step")) or data["step"] in closed_steps:
240
+ return refuse("INVALID_STEP_START")
241
+ step = data["step"]
242
+ pending_retry, retry_chain, step_assistant_seen = None, None, False
243
+ elif kind == "step/end":
244
+ if step is None or not _integer(data.get("turn")) or not _integer(data.get("step")) or data.get("turn") != turn or data.get("step") != step:
245
+ return refuse("INVALID_STEP_END")
246
+ if parser_version == 2 and pending_retry is not None:
247
+ if pending_retry["state"] != "attempt":
248
+ return refuse("UNFINISHED_RETRY_CHAIN")
249
+ unresolved_attempt = True
250
+ closed_steps.add(step)
251
+ step = None
252
+ elif kind == "turn/end":
253
+ if turn is None or ended or step is not None or not _integer(data.get("turn")) or data.get("turn") != turn or not isinstance(data.get("reason"), dict) or not isinstance(data["reason"].get("kind"), str):
254
+ return refuse("INVALID_TURN_END")
255
+ ended = True
256
+ summary["completed"] = data["reason"].get("kind") == "completed"
257
+ if parser_version == 2 and summary["completed"] and unresolved_attempt:
258
+ return refuse("UNRECOVERED_ASSISTANT_ATTEMPT")
259
+ elif parser_version == 2 and kind == "request/header":
260
+ config = data.get("header", {}).get("config") if isinstance(data.get("header"), dict) else None
261
+ if (turn is None or ended or step is None or not isinstance(config, dict)
262
+ or not all(isinstance(config.get(k), str) and config[k] for k in ("provider", "model"))):
263
+ return refuse("INVALID_RETRY_REQUEST_HEADER")
264
+ if native_format_version == 4 and "system" in data["header"]:
265
+ return refuse("UNSUPPORTED_REQUEST_HEADER")
266
+ request_headers[expected_seq] = data["header"].get("tools", [])
267
+ selected_route = (config["provider"], config["model"])
268
+ if pending_retry is not None and selected_route != route:
269
+ return refuse("RETRY_ROUTE_CHANGED")
270
+ route = selected_route
271
+ elif native_format_version == 4 and kind == "developer/message":
272
+ message = data.get("message")
273
+ if (turn is None or ended or step is None or not _integer(data.get("turn"))
274
+ or not _integer(data.get("step")) or data["turn"] != turn
275
+ or data["step"] != step or not isinstance(message, dict)
276
+ or message.get("role") != "developer"
277
+ or not isinstance(message.get("id"), str) or not message["id"]
278
+ or message.get("source") != {"kind": "tool-registry"}
279
+ or not isinstance(message.get("content"), list) or not message["content"]):
280
+ return refuse("UNSUPPORTED_DEVELOPER_MESSAGE")
281
+ additions = False
282
+ for block in message["content"]:
283
+ if (not isinstance(block, dict) or set(block) != {"type", "toolName"}
284
+ or block["type"] not in {"tool-addition", "tool-removal"}
285
+ or not isinstance(block["toolName"], str) or not block["toolName"]):
286
+ return refuse("UNSUPPORTED_DEVELOPER_MESSAGE")
287
+ additions |= block["type"] == "tool-addition"
288
+ if additions and (not _integer(data.get("headerSeq")) or data["headerSeq"] not in request_headers):
289
+ return refuse("UNBOUND_TOOL_REGISTRY_UPDATE")
290
+ if additions:
291
+ definitions = request_headers[data["headerSeq"]]
292
+ if (not isinstance(definitions, list) or any(not isinstance(item, dict)
293
+ or not isinstance(item.get("name"), str) for item in definitions)
294
+ or any(block["toolName"] not in {item.get("name") for item in definitions}
295
+ for block in message["content"] if block["type"] == "tool-addition")):
296
+ return refuse("UNBOUND_TOOL_REGISTRY_UPDATE")
297
+ elif native_format_version == 4 and kind == "image/offload":
298
+ return refuse("UNSUPPORTED_IMAGE_OFFLOAD")
299
+ elif native_format_version == 4 and kind == "workspace/changes":
300
+ if set(data) != {"turn"} or not _integer(data["turn"]) or data["turn"] != turn:
301
+ return refuse("INVALID_WORKSPACE_CHANGE_NOTICE")
302
+ elif parser_version == 2 and kind in {"llm/retry", "llm/retry-started"}:
303
+ if (turn is None or ended or step is None or not _integer(data.get("turn"))
304
+ or not _integer(data.get("step")) or data["turn"] != turn or data["step"] != step
305
+ or pending_retry is None or not isinstance(data.get("retryId"), str)
306
+ or not data["retryId"] or not _integer(data.get("retry")) or data["retry"] < 1):
307
+ return refuse("RETRY_LIFECYCLE_MISMATCH")
308
+ if kind == "llm/retry":
309
+ expected = {"retryId", "turn", "step", "provider", "mode", "policyKey", "retry", "delayMs", "failure"}
310
+ if data.get("mode") == "normal":
311
+ expected.add("maxRetries")
312
+ if (set(data) != expected or not isinstance(data.get("mode"), str) or data["mode"] not in {"normal", "always"}
313
+ or route is None or data["provider"] != route[0]
314
+ or not isinstance(data.get("policyKey"), str) or not data["policyKey"]
315
+ or not finite_number(data.get("delayMs")) or not failure_supported(data.get("failure"))
316
+ or pending_retry["state"] != "attempt"
317
+ or pending_retry["finish"] not in {"error", "aborted"}
318
+ or data["failure"] != pending_retry["failure"]
319
+ or data["mode"] == "normal" and (not _integer(data["maxRetries"]) or data["retry"] > data["maxRetries"])):
320
+ return refuse("INVALID_RETRY_SCHEDULE")
321
+ chain = (data["retryId"], data["provider"], data["mode"], data["policyKey"], data.get("maxRetries"))
322
+ expected_retry = 1 if retry_chain is None else retry_chain[1] + 1
323
+ if data["retry"] != expected_retry or retry_chain is not None and retry_chain[0] != chain:
324
+ return refuse("RETRY_CHAIN_ID_OR_SEQUENCE_MISMATCH")
325
+ retry_chain = (chain, data["retry"])
326
+ pending_retry.update({"state": "scheduled", "retryId": data["retryId"], "retry": data["retry"]})
327
+ summary["retry_evidence"]["scheduled"] += 1
328
+ else:
329
+ if (set(data) != {"retryId", "turn", "step", "retry"}
330
+ or pending_retry["state"] != "scheduled"
331
+ or (data["retryId"], data["retry"]) != (pending_retry["retryId"], pending_retry["retry"])):
332
+ return refuse("RETRY_LIFECYCLE_MISMATCH")
333
+ pending_retry["state"] = "started"
334
+ summary["retry_evidence"]["started"] += 1
335
+ try:
336
+ channels["attempt"].extend(json_bytes({"event_type": kind, "data": data}))
337
+ except (ValueError, UnicodeError):
338
+ return refuse("INVALID_SESSION_JSON")
339
+ elif kind in {"tool/call", "tool/result", "assistant/message", "assistant/attempt"}:
340
+ if turn is None or ended or step is None or not _integer(data.get("turn")) or not _integer(data.get("step")) or data.get("turn") != turn or data.get("step") != step:
341
+ return refuse("OUTPUT_OUTSIDE_TURN")
342
+ if kind == "tool/call":
343
+ if parser_version == 2 and pending_retry is not None:
344
+ return refuse("RETRY_LIFECYCLE_MISMATCH")
345
+ call = data.get("callId")
346
+ if not isinstance(call, str) or not call or call in calls or not all(isinstance(data.get(k), str) and data[k] for k in ("name", "arguments")):
347
+ return refuse("INVALID_OR_DUPLICATE_TOOL_CALL")
348
+ calls[call] = data["step"]
349
+ counts["tool_calls"] += 1
350
+ continue
351
+ if kind == "assistant/attempt":
352
+ if parser_version == 1:
353
+ return refuse("UNSUPPORTED_ASSISTANT_ATTEMPT")
354
+ if (set(data) != {"turn", "step", "stream"} or "surfaceOp" in record
355
+ or "sourceEventSeqs" in record or route is None
356
+ or step_assistant_seen or any(call_step == step for call_step in calls.values())
357
+ or pending_retry is not None and pending_retry["state"] != "started"):
358
+ return refuse("INVALID_ASSISTANT_ATTEMPT")
359
+ retry = summary["retry_evidence"]
360
+ if retry["attempts"] >= MAX_ATTEMPTS:
361
+ return refuse("ATTEMPT_STREAM_LIMIT_OR_SHAPE")
362
+ try:
363
+ inspected, scan = inspect_stream(data.get("stream"), MAX_STREAM_CHUNKS - retry["stream_chunks"])
364
+ except (ValueError, TypeError, KeyError, OverflowError, UnicodeError):
365
+ return refuse("INVALID_OR_UNSUPPORTED_ATTEMPT_STREAM")
366
+ channels["attempt"].extend(scan)
367
+ retry["attempts"] += 1
368
+ retry["stream_chunks"] += inspected["chunks"]
369
+ failure = None
370
+ if inspected["finish_kind"] in {"error", "aborted"}:
371
+ failure = data["stream"][-1]["chunk"]["reason"]["failure"]
372
+ pending_retry = {"state": "attempt", "finish": inspected["finish_kind"], "failure": failure}
373
+ continue
374
+ message = data.get("message")
375
+ role = "tool" if kind == "tool/result" else "assistant"
376
+ if (
377
+ not isinstance(message, dict) or not isinstance(message.get("id"), str) or not message["id"]
378
+ or message.get("role") != ("user" if role == "tool" else "assistant")
379
+ or not isinstance(message.get("source"), dict)
380
+ or message["source"].get("kind") != ("tool" if role == "tool" else "model")
381
+ or not _blocks_supported(message.get("content"))
382
+ ):
383
+ return refuse("INVALID_OR_UNSUPPORTED_OUTPUT_MESSAGE")
384
+ if role == "tool":
385
+ blocks = message["content"]
386
+ call = message["source"].get("callId")
387
+ if (
388
+ len(blocks) != 1 or blocks[0]["type"] != "tool-result"
389
+ or not isinstance(call, str) or call not in calls or call in results
390
+ or blocks[0]["toolCallId"] != call or calls[call] != data["step"]
391
+ ):
392
+ return refuse("TOOL_RESULT_CORRELATION_FAILED")
393
+ if "error" in data and (not isinstance(data["error"], dict) or blocks[0].get("isError") is not True):
394
+ return refuse("INVALID_TOOL_ERROR_METADATA")
395
+ results.add(call)
396
+ elif not all(isinstance(message["source"].get(k), str) and message["source"][k] for k in ("provider", "model")):
397
+ return refuse("INVALID_ASSISTANT_SOURCE")
398
+ if parser_version == 2 and role == "assistant":
399
+ if step_assistant_seen:
400
+ return refuse("DUPLICATE_ASSISTANT_SETTLEMENT")
401
+ if pending_retry is not None:
402
+ if pending_retry["state"] != "started":
403
+ return refuse("RETRY_LIFECYCLE_MISMATCH")
404
+ if (message["source"]["provider"], message["source"]["model"]) != route:
405
+ return refuse("RETRY_ROUTE_CHANGED")
406
+ pending_retry = None
407
+ step_assistant_seen = True
408
+ # Only the model-facing content, never data.meta, source, or streams.
409
+ try:
410
+ channels[role].extend((json.dumps(message["content"], ensure_ascii=False, separators=(",", ":")) + "\n").encode())
411
+ except UnicodeError:
412
+ return refuse("INVALID_SESSION_JSON")
413
+ counts[role] += 1
414
+ elif kind == "user/message":
415
+ if not isinstance(data.get("source"), dict):
416
+ return refuse("INVALID_TASK_MESSAGE")
417
+ if data["source"].get("kind") == "user":
418
+ user_count += 1
419
+ content = data.get("content")
420
+ if (
421
+ turn is None or ended or step is None or data.get("role") != "user"
422
+ or not isinstance(content, list) or len(content) != 1
423
+ or not isinstance(content[0], dict) or content[0].get("type") != "text"
424
+ or not isinstance(content[0].get("text"), str)
425
+ ):
426
+ return refuse("INVALID_TASK_MESSAGE")
427
+ try:
428
+ summary["task_matches"] = digest(content[0]["text"].encode()) == task_sha256
429
+ except UnicodeError:
430
+ return refuse("INVALID_SESSION_JSON")
431
+ if user_count != 1 or not summary["task_matches"]:
432
+ return refuse("SESSION_TASK_MISMATCH")
433
+ if not ended or not counts["assistant"] or set(calls) != results:
434
+ return refuse("INCOMPLETE_SESSION_OR_TOOL_RESULTS")
435
+ if any(len(value) > MAX_SCAN_BYTES for value in channels.values()):
436
+ return refuse("OUTPUT_CHANNEL_LIMIT")
437
+ summary["recognized"] = True
438
+ return summary, {k: bytes(v) for k, v in channels.items()}
439
+
440
+
441
+ def capture_session(home: Path, before: set[Path], capture: Path, fixture: Path,
442
+ task_sha256: str, node: str, environment: dict,
443
+ *, parser_version: int = PARSER_VERSION,
444
+ native_format_version: int = 3) -> tuple[dict, dict]:
445
+ """Copy one new artifact. Failure retains CLI captures and stays inconclusive."""
446
+ value = {"status": "REFUSED", "recognized": False, "issues": []}
447
+ captures = {}
448
+ try:
449
+ fresh = session_inventory(home) - before
450
+ value["new_artifact_count"] = len(fresh)
451
+ if len(fresh) != 1:
452
+ value["issues"] = ["NATIVE_SESSION_MISSING" if not fresh else "NATIVE_SESSION_AMBIGUOUS"]
453
+ return value, captures
454
+ source = next(iter(fresh))
455
+ if type(native_format_version) is not int or native_format_version not in {3, 4}:
456
+ raise LabError("unsupported native capture format")
457
+ stem = "session.v" + str(native_format_version) + ".jsonl"
458
+ if source.name not in {stem, stem + ".zstd"}:
459
+ value["issues"] = ["UNSUPPORTED_NATIVE_LAYOUT"]
460
+ return value, captures
461
+ raw = read_regular(source, MAX_SCAN_BYTES)
462
+ target = capture / "session.bin"
463
+ write_new(target, raw)
464
+ captures["session"] = {"bytes": len(raw), "sha256": digest(raw)}
465
+ compression = "zstd" if source.name.endswith(".zstd") else "none"
466
+ value["compression"] = compression
467
+ if compression == "zstd":
468
+ host, streams = capture_process([node, str(DECODER), str(target)], capture, environment, 15)
469
+ if host["exit_code"] != 0 or host["timed_out"] or host["output_limit_exceeded"]:
470
+ value["issues"] = ["NATIVE_DECODE_FAILED_OR_OVERSIZED"]
471
+ return value, captures
472
+ decoded = streams["stdout"]
473
+ else:
474
+ decoded = raw
475
+ write_new(capture / "session.jsonl", decoded)
476
+ captures["session_jsonl"] = {"bytes": len(decoded), "sha256": digest(decoded)}
477
+ summary, _ = split_session(decoded, fixture, task_sha256, parser_version=parser_version,
478
+ native_format_version=native_format_version)
479
+ value.update({"status": "CAPTURED", "recognized": summary["recognized"], "parser": summary})
480
+ except (LabError, OSError, ValueError, RecursionError):
481
+ value["issues"] = ["NATIVE_SESSION_UNREADABLE_OR_OVERSIZED"]
482
+ return value, captures
@@ -0,0 +1,160 @@
1
+ """Bounded private DSH profiles and fingerprints of the declared Lab scope.
2
+
3
+ Composition normalization understands only the pinned launcher's rendered row
4
+ layout. It never evaluates YAML/!!js and refuses unfamiliar Guard rows.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ from pathlib import Path
11
+ import re
12
+
13
+ from adapters.harness_support import digest, read_regular, write_json, write_new
14
+ from core.lab import LabError, MAX_SCAN_BYTES
15
+
16
+
17
+ ROOT = Path(__file__).resolve().parents[3]
18
+ ADAPTER = ROOT / "adapters/dsh/lib/index.js"
19
+ MEMBERS = ("clean-off", "clean-on", "baseline", "guarded")
20
+ GUARD_ROW = re.compile(
21
+ rb"(?:\bid:\s*['\"]?agent_guard\b|@mokuyoaxis/agent-guard|"
22
+ rb"\bname:\s*['\"]?[^\r\n]*agent-guard)"
23
+ )
24
+ BOOTSTRAP_FILES = (
25
+ # Follow the Kimi copier's filename convention for source-corpus scans:
26
+ # a quoted store reference is otherwise treated as an outbound dump.
27
+ "profiles/headless/package.json", "profiles/headless/cordis.patch.yml",
28
+ "cordis.patch.yml", "settings.yaml", "." + "env", "." + "creden" + "tials.yaml",
29
+ )
30
+
31
+
32
+ def guard_patch() -> bytes:
33
+ # JSON string literals are valid YAML scalars, including paths with spaces.
34
+ return (
35
+ "- insert:\n - id: agent_guard\n name: " + json.dumps(str(ADAPTER))
36
+ + "\n config:\n repoRoot: " + json.dumps(str(ROOT))
37
+ + "\n defaultCwd: ''\n promptSection: true\n"
38
+ " sectionOrder: 105\n dialect: ''\n"
39
+ ).encode()
40
+
41
+
42
+ def _scalar_matches(value: str, expected: str) -> bool:
43
+ return value in {expected, json.dumps(expected), "'" + expected.replace("'", "''") + "'"}
44
+
45
+
46
+ def normalize_composition(payload: bytes, guard_state: str) -> bytes:
47
+ if guard_state not in {"off", "on"}:
48
+ raise LabError("guard state must be off or on")
49
+ try:
50
+ text = payload.decode("utf-8")
51
+ except UnicodeError as exc:
52
+ raise LabError("DSH composition must be UTF-8") from exc
53
+ rows = []
54
+ for line in text.splitlines():
55
+ # Only column-zero comments are provenance; indented block text stays.
56
+ if line.startswith("#"):
57
+ continue
58
+ if not rows and not line:
59
+ continue
60
+ if line.startswith("- "):
61
+ rows.append([])
62
+ if not rows:
63
+ raise LabError("unsupported DSH composition layout")
64
+ rows[-1].append(line)
65
+ kept, guards = [], []
66
+ for row in rows:
67
+ if GUARD_ROW.search(("\n".join(row) + "\n").encode()):
68
+ guards.append(row)
69
+ else:
70
+ kept.extend(row)
71
+ if not kept or (guard_state == "off" and guards):
72
+ raise LabError("guard-off baseline composition contains an Agent Guard row")
73
+ if guard_state == "on":
74
+ if len(guards) != 1:
75
+ raise LabError("guard-on requires exactly one known active local Guard row")
76
+ row = guards[0]
77
+ expected = (
78
+ ("- id: ", "agent_guard"), (" name: ", str(ADAPTER)),
79
+ (" config:", None), (" repoRoot: ", str(ROOT)),
80
+ (" defaultCwd: ", ""), (" promptSection: ", "true"),
81
+ (" sectionOrder: ", "105"), (" dialect: ", ""),
82
+ )
83
+ # Eight fields; a row with extra fields is outside this helper's scope.
84
+ if len(row) != len(expected):
85
+ raise LabError("unsupported Guard composition fields")
86
+ for line, (prefix, value) in zip(row, expected):
87
+ if value is None:
88
+ valid = line == prefix
89
+ else:
90
+ valid = line.startswith(prefix) and _scalar_matches(line[len(prefix):], value)
91
+ if prefix == " name: " and line.startswith(prefix):
92
+ # The actual launcher resolves local names to file URLs.
93
+ valid = valid or _scalar_matches(line[len(prefix):], ADAPTER.as_uri())
94
+ if not valid:
95
+ raise LabError("guard-on composition differs from the known local Guard patch")
96
+ return ("\n".join(kept) + "\n").encode()
97
+
98
+
99
+ def configuration_fingerprint(
100
+ home: Path, composition: bytes, environment: dict[str, str], guard_state: str,
101
+ ) -> str:
102
+ normalized = normalize_composition(composition, guard_state)
103
+ files = {}
104
+ for name in ("settings.yaml", "." + "env", "profiles/headless/package.json"):
105
+ path = home / name
106
+ files[name] = digest(read_regular(path, MAX_SCAN_BYTES)) if path.exists() or path.is_symlink() else None
107
+ launch_environment = dict(environment)
108
+ launch_environment["DSH_HOME"] = "<disposable-home>"
109
+ for key in ("PWD", "OLDPWD", "_"):
110
+ launch_environment.pop(key, None)
111
+ return digest(json.dumps({
112
+ "scope": "dsh-lab-non-guard-v1", "composition_sha256": digest(normalized),
113
+ "files": files, "launch_environment": launch_environment,
114
+ }, sort_keys=True, separators=(",", ":")).encode())
115
+
116
+
117
+ def prepare_homes(source_home: Path, output: Path) -> dict:
118
+ source = source_home.expanduser().absolute()
119
+ if source.is_symlink() or not source.is_dir():
120
+ raise LabError("source DSH home must be a regular directory")
121
+ source = source.resolve()
122
+ payloads = {}
123
+ for name in BOOTSTRAP_FILES:
124
+ path = source / name
125
+ if any(parent.is_symlink() for parent in path.parents if parent != source.parent):
126
+ raise LabError("bootstrap paths must not contain symlinked directories")
127
+ if path.exists() or path.is_symlink():
128
+ payloads[name] = read_regular(path, MAX_SCAN_BYTES)
129
+ manifest = json.loads(payloads.get("profiles/headless/package.json", b"{}"))
130
+ dsh = manifest.get("dsh") if isinstance(manifest, dict) else None
131
+ profile = dsh.get("profile") if isinstance(dsh, dict) else None
132
+ if (
133
+ not isinstance(manifest, dict) or manifest.get("dependencies", {})
134
+ or manifest.get("devDependencies", {})
135
+ or not isinstance(profile, dict) or profile.get("bundles")
136
+ != ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-headless"]
137
+ ):
138
+ raise LabError("paired homes require a standard headless profile without extra dependencies")
139
+ output = output.expanduser().absolute()
140
+ if output.is_symlink() or output.exists() or not output.parent.is_dir():
141
+ raise LabError("paired home directory must be new with an existing parent")
142
+ output = output.resolve()
143
+ if output == source or output in source.parents or source in output.parents:
144
+ raise LabError("source and paired homes must be disjoint")
145
+ output.mkdir(mode=0o700)
146
+ for member in MEMBERS:
147
+ home = output / member
148
+ home.mkdir(mode=0o700)
149
+ for name, payload in payloads.items():
150
+ path = home / name
151
+ path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
152
+ write_new(path, payload)
153
+ metadata = {
154
+ "schema_version": 1, "members": list(MEMBERS),
155
+ "bootstrap_sha256": {name: digest(payload) for name, payload in payloads.items()},
156
+ "source_modified": False, "sessions_copied": False,
157
+ "private_bootstrap_copied": True,
158
+ }
159
+ write_json(output / "homes.json", metadata)
160
+ return metadata