"""Deterministic evidence and completion contracts for agent runs.""" from __future__ import annotations import hashlib import json import re from dataclasses import asdict, dataclass, field from enum import Enum from pathlib import Path from typing import Any, Iterable, Mapping, Sequence from src.agent_runtime.identity import artifact_identity, artifact_version, executable_words, is_test_command, is_validation_command def workspace_artifact_is_usable(path: Path) -> bool: """Reject empty files and obvious text placeholders with binary suffixes.""" try: if not path.is_file() or path.stat().st_size <= 0: return False suffix = path.suffix.casefold() header = path.read_bytes()[:32] except OSError: return False signatures = { ".png": (b"\x89PNG\r\n\x1a\n",), ".jpg": (b"\xff\xd8\xff",), ".jpeg": (b"\xff\xd8\xff",), ".gif": (b"GIF87a", b"GIF89a"), ".pdf": (b"%PDF-",), ".bmp": (b"BM",), ".tif": (b"II*\x00", b"MM\x00*"), ".tiff": (b"II*\x00", b"MM\x00*"), ".webm": (b"\x1aE\xdf\xa3",), ".wav": (b"RIFF",), ".docx": (b"PK\x03\x04",), ".xlsx": (b"PK\x03\x04",), ".pptx": (b"PK\x03\x04",), } if suffix in signatures: if not any(header.startswith(signature) for signature in signatures[suffix]): return False if suffix == ".wav" and header[8:12] != b"WAVE": return False elif suffix == ".webp": if not (header.startswith(b"RIFF") and header[8:12] == b"WEBP"): return False elif suffix in {".mp4", ".mov", ".m4v"}: if len(header) < 12 or header[4:8] != b"ftyp": return False return True class EvidenceKind(str, Enum): TOOL_RESULT = "tool_result" ARTIFACT_MUTATION = "artifact_mutation" ARTIFACT_VALIDATION = "artifact_validation" VERIFIER_RESULT = "verifier_result" MEDIA_INGRESS = "media_ingress" class CompletionStatus(str, Enum): VERIFIED = "verified" SATISFIED = "satisfied" UNVERIFIED = "unverified" FAILED = "failed" BLOCKED = "blocked" EXHAUSTED = "exhausted" AWAITING_USER = "awaiting_user" @dataclass(frozen=True) class CompletionRequirements: required_artifacts: tuple[str, ...] = () verifier_required: bool = False executable_verifier_available: bool = False verifier_commands: tuple[str, ...] = () # Host workspace used by unattended/native runs. When supplied, a # successful tool event is not enough: the declared artifact must also # exist in this workspace at completion time. workspace_root: str = "" def to_dict(self) -> dict[str, Any]: data = asdict(self) data["required_artifacts"] = list(self.required_artifacts) data["verifier_commands"] = list(self.verifier_commands) return data @dataclass(frozen=True) class EvidenceEvent: event_id: str kind: EvidenceKind success: bool authoritative: bool round: int | None = None tool: str = "" artifact_path: str = "" exit_code: int | None = None command_sha256: str = "" output_sha256: str = "" detail: str = "" action_id: str = "" execution_id: str = "" artifact_id: str = "" verification_id: str = "" def to_dict(self) -> dict[str, Any]: data = asdict(self) data["kind"] = self.kind.value return data EXTERNAL_EFFECT_UNVERIFIED = "an external operation's resulting state was not independently verified" @dataclass(frozen=True) class CompletionDecision: status: CompletionStatus can_complete: bool reason: str evidence_ids: tuple[str, ...] = () missing_artifacts: tuple[str, ...] = () def to_dict(self) -> dict[str, Any]: data = asdict(self) data["status"] = self.status.value data["evidence_ids"] = list(self.evidence_ids) data["missing_artifacts"] = list(self.missing_artifacts) return data _ARTIFACT_PATH = r"(?:/|\./|\.\./)?[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)*\.[A-Za-z0-9]{1,12}" _ARTIFACT_REQUEST_RE = re.compile( rf"\b(?:writ(?:e|ten)|creat(?:e|ed)|make|made|sav(?:e|ed)|produc(?:e|ed)|" rf"generat(?:e|ed)|export(?:ed)?|edit(?:ed)?|modif(?:y|ied)|updat(?:e|ed)|" rf"fix(?:ed)?|put|plac(?:e|ed))\b" rf"[^\n]{{0,80}}?(?P{_ARTIFACT_PATH})", re.IGNORECASE, ) _OUTPUT_PATH_RE = re.compile( rf"\b(?:output|artifact)(?:\s+(?:file|path))?\b[^\n]{{0,40}}?(?P{_ARTIFACT_PATH})", re.IGNORECASE, ) _EXPLICIT_OUTPUT_FILE_RE = re.compile( rf"\b(?:to|at|as|into)\s+(?:the\s+|a\s+)?(?:single\s+)?(?:file|path)\s+(?P{_ARTIFACT_PATH})", re.IGNORECASE, ) _NAMED_OUTPUT_FILE_RE = re.compile( rf"\b(?:in|into)\s+(?:a|the)\s+file\s+(?:called|named)\s+(?P{_ARTIFACT_PATH})", re.IGNORECASE, ) _EXPLICIT_OUTPUT_DIRECTORY_RE = re.compile( r"\b(?:sav(?:e|ed)|writ(?:e|ten)|creat(?:e|ed)|make|made|produc(?:e|ed)|" r"generat(?:e|ed)|export(?:ed)?|put|plac(?:e|ed))\b" r"[^\n]{0,100}?\b(?:in|into|to|under|inside)\s+" r"[`'\"]?(?P/(?:[A-Za-z0-9_.-]+/)*[A-Za-z0-9_.-]+/?)" r"(?=[`'\"\s.,;:]|$)", re.IGNORECASE, ) _LOCALIZED_OUTPUT_DIRECTORY_RE = re.compile( r"(?:保存(?:到|至|入)?|创建|生成|输出(?:到|至|入)?)" r"[^\n]{0,80}?" r"[`'\"]?(?P/(?:[A-Za-z0-9_.-]+/)*[A-Za-z0-9_.-]+/)" r"(?=[`'\"\s.,;:，。；：]|$)", re.IGNORECASE, ) _LOCALIZED_ARTIFACT_REQUEST_RE = re.compile( rf"(?:保存(?:为|到)?|写入|创建|生成|输出(?:为|到)?|" rf"保存|書き込|作成|生成|出力|저장|작성|생성|출력)" rf"[^\n]{{0,80}}?(?P{_ARTIFACT_PATH})", re.IGNORECASE, ) _TEST_COMMAND_RE = re.compile( r"(?:^|[;&|\s])(?:pytest|python(?:3)?\s+-m\s+pytest|npm\s+(?:run\s+)?test|" r"pnpm\s+test|yarn\s+test|make\s+test|cargo\s+test|go\s+test|" r"/(?:tests?|verifier)/[^\s;&|]+)", re.IGNORECASE, ) _MUTATION_COMMAND_RE = re.compile( r"(?:\b(?:write_file|edit_file|apply_patch|touch|tee|cp|mv|mkdir|ln|install)\b|" r"\b(?:ffmpeg|sox)\b[^\n;&|]*(?:/workspace/|\.(?:mp4|webm|mov|mkv|avi|mp3|wav|m4a|aac|flac|ogg|opus)\b)|" r"\bsed\s+-[A-Za-z]*i[A-Za-z]*(?:\.[^\s;&|]+)?\b|\bperl\s+-p?i(?:[A-Za-z]*)?\b|" r"(?:^|\s)>{1,2}\s*|" r"\.(?:save|savefig|write_text|write_bytes|to_csv|to_json|to_excel|to_parquet|" r"to_html|to_markdown|to_pickle|to_feather|mkdir|symlink_to|rename|replace|" r"unlink)\s*\(|" r"\b(?:os\.(?:makedirs|mkdir|rename|replace|remove|unlink|symlink)|" r"shutil\.(?:copy|copy2|copyfile|copytree|move))\s*\(|" r"\bopen\s*\([^\n]{0,240}?[\"'](?:w|a|x)[+b]?[\"'])", re.IGNORECASE, ) _VALIDATION_COMMAND_RE = re.compile( r"(?:\btest\s+-[efsd]\b|\b(?:cat|head|tail|stat|wc|jq|cmp|diff)\b|" r"(?:^|[;&|\s])(?:coqc|gcc|g\+\+|clang|clang\+\+|javac|rustc)\b|" r"(?:^|[;&|\s])(?:cargo\s+(?:build|check)|go\s+build|npm\s+(?:run\s+)?build|" r"pnpm\s+build|yarn\s+build)\b|" r"\.read_(?:text|bytes)\s*\(|\bopen\s*\([^\n]{0,240}?[\"']r[+b]?[\"'])", re.IGNORECASE, ) def command_is_validation(command: str) -> bool: """Return whether a shell command provides executable verification evidence.""" value = str(command or "") return is_validation_command(_command_text(value)) def command_is_test(command: str) -> bool: """Return whether a shell command executes a recognized test runner.""" return is_test_command(_command_text(str(command or ""))) def _clean_path(value: str) -> str: return str(value or "").strip().strip("`'\"").rstrip(".,;:)") def _is_prose_abbreviation(value: str) -> bool: return _clean_path(value).lower() in {"e.g", "i.e"} def _artifact_match_is_negated(instruction: str, match: re.Match[str]) -> bool: """Reject paths attached to an explicitly negated mutation verb.""" prefix = instruction[max(0, match.start() - 32):match.start()] return bool(re.search(r"(?:do\s+not|don't|must\s+not|never)\s+$", prefix, re.IGNORECASE)) def _artifact_match_is_callable(instruction: str, match: re.Match[str], path: str) -> bool: """Reject dotted callable names such as ``json.dumps(...)`` as artifacts.""" if "/" in path or "\\" in path: return False if instruction[match.end("path"):].startswith("("): return True # Procedural prompts often name existence helpers without parentheses, # e.g. "verify with os.path.exists or ls". They are code references, not # output filenames, even though the generic path regex sees an extension. return bool(re.fullmatch(r"(?:os\.path|pathlib\.Path|Path)\.[A-Za-z_]\w*", path)) def _artifact_match_is_email_host(instruction: str, match: re.Match[str]) -> bool: """Reject the domain portion of an email address as an output path.""" start = match.start("path") prefix = instruction[max(0, start - 80):start] return bool(re.search(r"[A-Za-z0-9_.+-]+@$", prefix)) def _workspace_path_identity(value: str) -> str: """Return a stable identity for native workspace path aliases.""" path = _clean_path(value).replace("\\", "/") for prefix in ("/tmp_workspace/", "/workspace/"): if path.startswith(prefix): return path[len(prefix):] return path def _known_input_is_explicit_mutation_target(instruction: str, path: str) -> bool: """Preserve a known input only when the user explicitly asks to edit it. Input descriptions commonly say that a file is "saved in" or is a "post-write checklist". Those phrases must not turn read-only evidence into a required output artifact. Direct edit/update requests remain supported. """ escaped = re.escape(_clean_path(path)) active_edit = rf"(? Iterable[tuple[str, str]]: """Yield original statements and their reportable prose, with quotes masked. Mask before splitting so punctuation inside an example cannot change the scope of the surrounding sentence. Inline code identifiers stay visible. """ def mask(match: re.Match[str]) -> str: value = match.group() # Quotation marks around an artifact identify a target, rather than # quote a report. Keep that target available for exact path matching. if value[0] in {'"', "'"} and re.fullmatch(_ARTIFACT_PATH, value[1:-1]): return ' ' + value[1:-1] + ' ' return re.sub(r'[^\n]', ' ', value) masked = re.sub( r'```[\s\S]*?```|~~~[\s\S]*?~~~|"[^"\n]*"|(? start: yield text[start:end], masked[start:end].replace('`', '') start = end if start < len(text): yield text[start:], masked[start:].replace('`', '') def _execution_obligation(requirements: CompletionRequirements) -> bool: """A derived view of the existing contract, never a separate declaration.""" return bool(requirements.required_artifacts or requirements.verifier_required or requirements.executable_verifier_available or requirements.verifier_commands) def infer_completion_requirements( instruction: str, *, executable_verifier_available: bool = False, verifier_commands: Sequence[str] = (), known_input_paths: Sequence[str] = (), ) -> CompletionRequirements: """Infer only explicitly requested output/edit paths from an instruction.""" # Explanations can contain imperative examples. Their embedded actions # are not requests to execute those actions. Keep independent requests in # other statements, and keep explicitly supplied verifier requirements. explanatory_request = re.compile( r'^\s*(?:please\s+|(?:can|could|would)\s+you\s+)?' r'(?:explain|describe|summari[sz]e|teach|discuss|' r'show\s+(?:me\s+)?(?:an?\s+)?example|how\b)', re.I) text = ''.join(scoped for _, scoped in _unquoted_statements(str(instruction or '')) if not explanatory_request.search(scoped)) paths: list[str] = [] for pattern in ( _ARTIFACT_REQUEST_RE, _OUTPUT_PATH_RE, _EXPLICIT_OUTPUT_FILE_RE, _NAMED_OUTPUT_FILE_RE, _LOCALIZED_ARTIFACT_REQUEST_RE, _EXPLICIT_OUTPUT_DIRECTORY_RE, _LOCALIZED_OUTPUT_DIRECTORY_RE, ): for match in pattern.finditer(text): path = _clean_path(match.group("path")) if _artifact_match_is_negated(text, match): continue if _artifact_match_is_callable(text, match, path): continue if _artifact_match_is_email_host(text, match): continue if path and not _is_prose_abbreviation(path) and path not in paths: paths.append(path) paths = [path.rstrip("/") if path != "/" else path for path in paths] paths = list(dict.fromkeys(paths)) input_identities = { _workspace_path_identity(path) for path in known_input_paths if _clean_path(path) } if input_identities: paths = [ path for path in paths if _workspace_path_identity(path) not in input_identities or _known_input_is_explicit_mutation_target(text, path) ] # When the instruction names an absolute output directory and then gives # relative example filenames (for example ``1.tex, 2.tex, ...``), the # directory is the actual completion contract. Treating the first example # filename as a root-level required artifact causes false blocked runs and # can provoke destructive repair calls outside the output directory. explicit_directories = [ path for path in paths if path.startswith("/") and not Path(path).suffix ] if explicit_directories: paths = [ path for path in paths if path in explicit_directories or any(path.startswith(directory.rstrip("/") + "/") for directory in explicit_directories) ] explicit_files = [path for path in paths if Path(path).suffix] if explicit_files: paths = [ path for path in paths if path not in explicit_directories or not any(file.startswith(path.rstrip("/") + "/") for file in explicit_files) ] cleaned_verifier_commands = tuple(dict.fromkeys( str(command or "").strip() for command in verifier_commands if str(command or "").strip() )) explicit_test_request = re.search( r'(?:^|[.;\n]|\b(?:and|then))\s*' r'(?:please\s+|(?:can|could|would)\s+you\s+)?' r'(?:run|execute)\s+(?:(?:the|all|a|full)\s+)*' r'(?:tests?\b|test\s+suite\b|pytest\b|unittest\b|npm\s+test\b)', text, re.I) verifier_required = executable_verifier_available or bool(cleaned_verifier_commands) or bool( explicit_test_request or (paths and re.search( r"\b(?:then|after(?:wards)?|and)\b[^\n]{0,100}\b(?:test|verify|check|validate)\b", text, re.IGNORECASE, )) ) return CompletionRequirements( required_artifacts=tuple(paths), verifier_required=verifier_required, executable_verifier_available=( executable_verifier_available or bool(cleaned_verifier_commands) or bool(explicit_test_request) ), verifier_commands=cleaned_verifier_commands, ) def requirements_from_runtime_context( context: Mapping[str, Any] | None, *, instruction: str = "", ) -> CompletionRequirements: runtime_context = context or {} known_inputs: list[str] = [] for value in runtime_context.get("input_files") or (): path = _clean_path(str(value or "")) if path: known_inputs.append(path) media_ingress = runtime_context.get("media_ingress") if isinstance(media_ingress, Mapping): for artifact in media_ingress.get("artifacts") or (): if not isinstance(artifact, Mapping): continue path = _clean_path(str(artifact.get("source_path") or "")) if path: known_inputs.append(path) raw = runtime_context.get("completion_requirements") if not isinstance(raw, Mapping): return infer_completion_requirements( instruction, known_input_paths=known_inputs, ) paths = raw.get("required_artifacts") if not isinstance(paths, (list, tuple)): paths = () cleaned = tuple( path for value in paths if (path := _clean_path(str(value or ""))) ) input_identities = { _workspace_path_identity(path) for path in known_inputs } if input_identities: cleaned = tuple( path for path in cleaned if _workspace_path_identity(path) not in input_identities or _known_input_is_explicit_mutation_target(instruction, path) ) verifier_commands = raw.get("verifier_commands") if not isinstance(verifier_commands, (list, tuple)): verifier_commands = () cleaned_verifier_commands = tuple(dict.fromkeys( str(command or "").strip() for command in verifier_commands if str(command or "").strip() )) return CompletionRequirements( required_artifacts=cleaned, verifier_required=bool(raw.get("verifier_required")), executable_verifier_available=( bool(raw.get("executable_verifier_available")) or bool(cleaned_verifier_commands) ), verifier_commands=cleaned_verifier_commands, workspace_root=_clean_path(str(raw.get("workspace_root") or "")), ) def _digest(value: str) -> str: return hashlib.sha256(str(value or "").encode("utf-8", errors="replace")).hexdigest() def _path_is_mentioned(command: str, required_path: str) -> bool: command = str(command or "") path = _clean_path(required_path) if not path: return False return path in command or Path(path).name in command def _artifact_path_matches_required(artifact_path: str, required_path: str, workspace: str = "") -> bool: artifact = str(artifact_path or '').strip() required = _clean_path(required_path) if not artifact or not required: return False return artifact_identity(artifact, workspace) == artifact_identity(required, workspace) def _explicit_tool_paths(tool: str, command: str) -> list[str]: if tool == "write_file": try: args = json.loads(command or "{}") except (TypeError, json.JSONDecodeError): args = None if isinstance(args, Mapping): path = str(args.get("path") or "").strip() return [path] if path else [] # Keep compatibility with the legacy ``path\ncontent`` transport. path = (str(command or "").splitlines()[0] if command else "").strip() return [path] if path else [] if tool == "edit_file": try: args = json.loads(command or "{}") except (TypeError, json.JSONDecodeError): return [] path = str(args.get("path") or "").strip() if isinstance(args, dict) else "" return [path] if path else [] if tool == "apply_patch": try: args = json.loads(command or "{}") except (TypeError, json.JSONDecodeError): args = None if isinstance(args, Mapping): patch = args.get("patch") command = patch if isinstance(patch, str) else "" return [ match.group(1).strip() for match in re.finditer(r"^\*\*\* (?:Add|Update|Delete) File:\s*(.+)$", command or "", re.MULTILINE) if _clean_path(match.group(1)) ] if tool == "inspect_media": try: args = json.loads(command or "{}") except (TypeError, json.JSONDecodeError): return [] path = ( _clean_path(str(args.get("output_path") or "")) if isinstance(args, dict) else "" ) paths = [path] if path else [] if isinstance(args, dict) and isinstance(args.get("exports"), list): for item in args["exports"]: if not isinstance(item, dict): continue export_path = _clean_path(str(item.get("output_path") or "")) if export_path and export_path not in paths: paths.append(export_path) return paths if tool == "private_browser": try: args = json.loads(command or "{}") except (TypeError, json.JSONDecodeError): return [] if not isinstance(args, Mapping): return [] action = str(args.get("action") or "").strip().lower() if action == "screenshot": path = _clean_path(str(args.get("path") or "")) return [path] if path else [] if action != "batch" or not isinstance(args.get("commands"), list): return [] paths: list[str] = [] for item in args["commands"]: if isinstance(item, Mapping): item_action = str(item.get("action") or "").strip().lower() item_path = item.get("path") elif isinstance(item, (list, tuple)) and item: item_action = str(item[0] or "").strip().lower() item_path = item[1] if len(item) > 1 else "" else: continue if item_action != "screenshot": continue path = _clean_path(str(item_path or "")) if path and path not in paths: paths.append(path) return paths return [] def _command_text(value: str) -> str: text = str(value or "").strip() if not text.startswith("{"): return text try: payload = json.loads(text) except (TypeError, json.JSONDecodeError): return text if not isinstance(payload, Mapping): return text for key in ("command", "cmd", "shell"): command = payload.get(key) if isinstance(command, str) and command.strip(): return command.strip() return text def _matches_declared_verifier(command: str, expected: Sequence[str]) -> bool: actual = executable_words(_command_text(command)) if not actual: return False return any( normalized == actual for item in expected if (normalized := executable_words(str(item or ""))) ) def command_has_mutation_effect(command: str) -> bool: """Return whether a shell or Python command visibly mutates workspace state.""" return bool(_MUTATION_COMMAND_RE.search(_command_text(command))) def _event_id(payload: Mapping[str, Any], occurrence: int) -> str: canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str) return "ev-" + _digest(f"{occurrence}:{canonical}")[:16] class EvidenceLedger: def __init__(self, requirements: CompletionRequirements | None = None) -> None: self.requirements = requirements or CompletionRequirements() self.events: list[EvidenceEvent] = [] self._verification_versions: dict[str, str] = {} self._verification_versions_captured = False # Retain receipt command identity privately for presentation matching; # model prose and client dictionaries never populate this evidence. self._verifier_commands: dict[str, tuple[str, ...]] = {} # Wave 4 effect assessments from the run's journal, plus the journal # order of actions so receipt evidence and effects share one ordering. self.effects: list[dict[str, Any]] = [] self._action_order: dict[str, int] = {} def record_effects(self, entries: Iterable[Mapping[str, Any]], action_order: Mapping[str, int], partial_reads: Iterable[str] = ()) -> None: """Consume server-derived effect assessments (never model/client data). ``partial_reads`` names read actions whose admitted observation was partial (offset/limit, truncation or extraction): such a read cannot validate omitted content, so its validation event is not authoritative. """ from dataclasses import replace from src.agent_runtime.effects import EffectAssessment self.effects = [dict(entry) for entry in entries if isinstance(entry, Mapping) and isinstance(entry.get("assessment"), EffectAssessment)] self._action_order = {str(k): v for k, v in action_order.items() if type(v) is int} partial = set(partial_reads) self.events = [replace(event, authoritative=False, detail="partial read; omitted content is unvalidated") if event.kind == EvidenceKind.ARTIFACT_VALIDATION and event.tool == "read_file" and event.action_id in partial else event for event in self.events] def _last_success_ordinal(self, required: str) -> int: return max((self._action_order.get(event.action_id, 0) for event in self.events if event.kind == EvidenceKind.ARTIFACT_MUTATION and event.authoritative and event.success and _artifact_path_matches_required(event.artifact_path, required, self.requirements.workspace_root)), default=0) def _later_effects(self, required: str) -> list[tuple[dict[str, Any], bool]]: """Effects after the artifact's last successful mutation, with targeting.""" floor = self._last_success_ordinal(required) later = [] for entry in self.effects: ordinal = entry.get("ordinal") if type(ordinal) is not int or ordinal <= floor: continue explicit = any(_artifact_path_matches_required(path, required, self.requirements.workspace_root) for path in entry.get("paths") or ()) if explicit or entry.get("unknown_scope"): later.append((entry, explicit)) return later @staticmethod def _entry_unsettled(entry: Mapping[str, Any], explicit: bool) -> bool: """One effect may have changed state with no settled evidence. Explicit targets are unsettled by unknown/timed-out/cancelled outcomes and by failures after the producer reached its mutation stage (atomic refusals keep the earlier artifact). Unknown-scope effects are unsettled when nothing captured their settlement: cancellation, interruption, or failed process teardown; settled shell/Python changes are already tracked through artifact version capture. """ from src.agent_runtime.effects import CleanupState, ExecutionOutcome unknown = {ExecutionOutcome.ATTEMPTED, ExecutionOutcome.INTERRUPTED, ExecutionOutcome.CANCELLED, ExecutionOutcome.RUNNING} assessment = entry["assessment"] if not assessment.unresolved_impact: return False if assessment.execution in unknown: return True if explicit: return (assessment.execution is ExecutionOutcome.TIMED_OUT or (assessment.execution is ExecutionOutcome.FAILED and bool(entry.get("mutation_attempted")))) return assessment.cleanup is CleanupState.FAILED def _effect_unsettled(self, required: str) -> bool: """A later operation may have partially changed this artifact.""" return any(self._entry_unsettled(entry, explicit) for entry, explicit in self._later_effects(required)) def _current_effects(self) -> list[dict[str, Any]]: """Effects of this journal's own actions, in action order.""" return sorted((entry for entry in self.effects if type(entry.get("ordinal")) is int), key=lambda entry: entry["ordinal"]) def _contradicted_target(self) -> str: """A changed file whose latest effect a fresh readback contradicts. Only the latest effect per target counts: an earlier effect superseded by a later requested write is history, not a contradiction. """ from src.agent_runtime.effects import EffectVerdict latest: dict[str, dict[str, Any]] = {} for entry in self._current_effects(): for path in entry.get("paths") or (): latest[path] = entry return next((path for path, entry in latest.items() if entry["assessment"].verdict is EffectVerdict.CONTRADICTED), "") def unverified_external_effects(self) -> list[dict[str, Any]]: """Executed external effects whose resulting state is not verified. A remote acknowledgement is execution evidence only. Without an admitted independent readback these effects never support a definitive statement that the external state changed. """ from src.agent_runtime.effects import EffectVerdict return [entry for entry in self.effects if entry.get("external") and entry["assessment"].verdict not in {EffectVerdict.VERIFIED, EffectVerdict.NOT_EXECUTED}] def effect_disclosures(self) -> tuple[str, ...]: """Server-authored facts for unverified external effects.""" from src.agent_runtime.effects import ExecutionOutcome facts = [] for entry in self.unverified_external_effects(): tool = str(entry.get("tool") or "external operation") execution = entry["assessment"].execution if execution is ExecutionOutcome.REPORTED_SUCCESS: facts.append(f"External operation {tool} reported success; any external change it made was " "not independently verified.") elif execution is ExecutionOutcome.FAILED: facts.append(f"External operation {tool} reported failure; it may have partially taken effect.") else: facts.append(f"External operation {tool} has an unknown outcome; it may or may not have " "taken effect.") return tuple(dict.fromkeys(facts)) def _effect_contradicted(self, required: str) -> str: """The latest effect targeting the artifact, if fresh readback contradicts it.""" from src.agent_runtime.effects import EffectVerdict targeting = [entry for entry in self.effects if type(entry.get("ordinal")) is int and any(_artifact_path_matches_required(path, required, self.requirements.workspace_root) for path in entry.get("paths") or ())] if not targeting: return "" latest = max(targeting, key=lambda entry: entry["ordinal"])["assessment"] return latest.effect_id if latest.verdict is EffectVerdict.CONTRADICTED else "" @classmethod def from_tool_events( cls, tool_events: Iterable[Mapping[str, Any]], requirements: CompletionRequirements | None = None, ) -> "EvidenceLedger": ledger = cls(requirements) for event in tool_events or []: if isinstance(event, Mapping): ledger.record_tool_event(event) return ledger def _append( self, *, kind: EvidenceKind, success: bool, authoritative: bool, source: Mapping[str, Any], artifact_path: str = "", detail: str = "", ) -> EvidenceEvent: command = str(source.get("command") or "") output = str(source.get("output") or source.get("error") or "") exit_code = source.get("exit_code") if not isinstance(exit_code, int) or isinstance(exit_code, bool): exit_code = None payload = { "kind": kind.value, "round": source.get("round"), "tool": source.get("tool"), "artifact_path": artifact_path, "exit_code": exit_code, "command_sha256": _digest(command), "output_sha256": _digest(output), } action_id = str(source.get('action_id') or '') execution_id = str(source.get('execution_id') or '') if action_id: payload.update(action_id=action_id, execution_id=execution_id) evidence = EvidenceEvent( event_id=_event_id(payload, len(self.events)), kind=kind, success=success, authoritative=authoritative, round=int(source["round"]) if isinstance(source.get("round"), int) else None, tool=str(source.get("tool") or ""), artifact_path=artifact_path, exit_code=exit_code, command_sha256=payload["command_sha256"], output_sha256=payload["output_sha256"], detail=detail, action_id=action_id, execution_id=execution_id, artifact_id=artifact_identity(artifact_path, self.requirements.workspace_root) if artifact_path else '', verification_id=('verification-' + _event_id(payload, len(self.events))) if kind in {EvidenceKind.VERIFIER_RESULT, EvidenceKind.ARTIFACT_VALIDATION} else '', ) self.events.append(evidence) return evidence def record_tool_event(self, event: Mapping[str, Any]) -> None: tool = str(event.get("tool") or "") command = str(event.get("command") or "") exit_code = event.get("exit_code") authoritative = ( isinstance(exit_code, int) and not isinstance(exit_code, bool) and not event.get("blocked") and not event.get("approval_required") and event.get("execution_attempted") is not False ) success = authoritative and exit_code == 0 and not event.get('error') if not authoritative: success = not bool(event.get("error")) self._append( kind=EvidenceKind.TOOL_RESULT, success=success, authoritative=authoritative, source=event, ) explicit_paths = _explicit_tool_paths(tool, command) mutation_paths = list(explicit_paths) observed_changes = event.get('artifact_changes') if isinstance(observed_changes, list) and tool in {'bash', 'python', 'host_shell'}: mutation_paths.extend(path for path in self.requirements.required_artifacts if artifact_identity(path, self.requirements.workspace_root) in observed_changes) elif command_has_mutation_effect(command) and tool not in { "write_file", "edit_file", "apply_patch", "inspect_media", }: mutation_paths.extend( path for path in self.requirements.required_artifacts if _path_is_mentioned(command, path) ) seen_paths: set[str] = set() for path in mutation_paths: path = str(path or '').strip() if not path or path in seen_paths: continue seen_paths.add(path) self._append( kind=EvidenceKind.ARTIFACT_MUTATION, success=success, authoritative=authoritative, source=event, artifact_path=path, ) if tool == "read_file": try: read_args = json.loads(command or "{}") except (TypeError, json.JSONDecodeError): read_args = None read_path = ( str(read_args.get("path") or "").strip() if isinstance(read_args, Mapping) else command.strip() if read_args is None else "" ) if read_path and any( _artifact_path_matches_required(read_path, required, self.requirements.workspace_root) for required in self.requirements.required_artifacts ): self._append( kind=EvidenceKind.ARTIFACT_VALIDATION, success=success, authoritative=authoritative, source=event, artifact_path=read_path, detail="post-write artifact inspection", ) if tool in {"bash", "host_shell"} and (command_is_test(_command_text(command)) or _matches_declared_verifier( command, self.requirements.verifier_commands, )): if authoritative: versions = event.get('artifact_versions') self._verification_versions = dict(versions) if isinstance(versions, Mapping) else {} self._verification_versions_captured = isinstance(versions, Mapping) verifier = self._append( kind=EvidenceKind.VERIFIER_RESULT, success=success, authoritative=authoritative, source=event, detail="executable test/verifier command", ) self._verifier_commands[verifier.event_id] = executable_words(_command_text(command)) elif tool in {"bash", "host_shell"} and is_validation_command(command) and not mutation_paths: for path in self.requirements.required_artifacts: if _path_is_mentioned(command, path): self._append( kind=EvidenceKind.ARTIFACT_VALIDATION, success=success, authoritative=authoritative, source=event, artifact_path=path, ) def _supports_verifier_claim(self, identities: Sequence[str] = (), paths: Sequence[str] = ()) -> bool: """Only the current passing verifier may support its named runner. A test result stays a test result when an unrelated external effect keeps the whole run unverified; it never speaks for that effect. """ if self._evaluate_obligations().status != CompletionStatus.VERIFIED: return False latest = next((event for event in reversed(self.events) if event.kind == EvidenceKind.VERIFIER_RESULT and event.authoritative), None) if latest is None or not latest.success: return False words = self._verifier_commands.get(latest.event_id, ()) names = {Path(words[0]).name} if words else set() if words and re.fullmatch(r'python(?:\d+(?:\.\d+)*)?', Path(words[0]).name) and '-m' in words: module_index = words.index('-m') + 1 if module_index < len(words): names.add(words[module_index]) return (all(identity in names for identity in identities) and all(any(_artifact_path_matches_required(word, path, self.requirements.workspace_root) for word in words) for path in paths)) def _supports_artifact_claim(self, kind: EvidenceKind, paths: Sequence[str]) -> bool: """Match every claimed artifact by identity, never by basename.""" targets = tuple(paths) or self.requirements.required_artifacts if not targets or (not paths and len(targets) != 1): return False if not paths and self.unverified_external_effects(): # An unnamed "I updated it" may mean the external effect. return False for path in targets: matching = [event for event in self.events if event.kind == kind and event.authoritative and _artifact_path_matches_required(event.artifact_path, path, self.requirements.workspace_root)] successful = [event for event in matching if event.success] # Match evaluate(): atomic helper failures preserve the previous # successful artifact; a partial shell/Python failure may not. destructive_failure = bool(matching and not matching[-1].success and matching[-1].tool in {'bash', 'python'}) if not successful or destructive_failure: return False if self.effects and (self._effect_unsettled(path) or self._effect_contradicted(path)): return False return True def record_media_ingress(self, metadata: Mapping[str, Any]) -> None: for artifact in metadata.get("artifacts") or []: if not isinstance(artifact, Mapping): continue source = str(artifact.get("source_path") or "") payload = { "round": 0, "tool": "media_ingress", "command": source, "output": str(artifact.get("source_sha256") or ""), "exit_code": 0, } self._append( kind=EvidenceKind.MEDIA_INGRESS, success=True, authoritative=True, source=payload, artifact_path=source, detail=str(artifact.get("modality") or "media"), ) def evaluate( self, *, exhausted: bool = False, awaiting_user: bool = False, ) -> CompletionDecision: decision = self._evaluate_obligations(exhausted=exhausted, awaiting_user=awaiting_user) if decision.status in {CompletionStatus.VERIFIED, CompletionStatus.SATISFIED} and \ self.unverified_external_effects(): # Reported external execution is not a verified effect: the run # may end, but never as verified or satisfied. return CompletionDecision(CompletionStatus.UNVERIFIED, True, EXTERNAL_EFFECT_UNVERIFIED, decision.evidence_ids, decision.missing_artifacts) return decision def _evaluate_obligations( self, *, exhausted: bool = False, awaiting_user: bool = False, ) -> CompletionDecision: if awaiting_user: return CompletionDecision( CompletionStatus.AWAITING_USER, False, "the run is waiting for user input", ) if exhausted: return CompletionDecision( CompletionStatus.EXHAUSTED, False, "the run exhausted its model-round budget", ) verifier_events = [ event for event in self.events if event.kind == EvidenceKind.VERIFIER_RESULT and event.authoritative ] latest_verifier = verifier_events[-1] if verifier_events else None if latest_verifier is not None and not latest_verifier.success: return CompletionDecision( CompletionStatus.FAILED, False, "the latest executable verifier failed", (latest_verifier.event_id,), ) if latest_verifier and self.requirements.workspace_root: for path in self.requirements.required_artifacts: identity = artifact_identity(path, self.requirements.workspace_root) expected = self._verification_versions.get(identity) if expected in {'unobserved', 'missing-or-unreadable'} or ( expected is None and self._verification_versions_captured ): return CompletionDecision(CompletionStatus.BLOCKED, False, 'artifact version could not be established for verification', (latest_verifier.event_id,)) if expected is not None and expected != artifact_version(path, self.requirements.workspace_root): return CompletionDecision(CompletionStatus.BLOCKED, False, 'artifact content changed after verification', (latest_verifier.event_id,)) for required in self.requirements.required_artifacts if self.effects else (): contradicted = self._effect_contradicted(required) if contradicted: return CompletionDecision(CompletionStatus.FAILED, False, "fresh readback contradicts the requested artifact content", (), (required,)) if self.effects: # Effect obligations hold whether or not artifacts were declared. contradicted = self._contradicted_target() if contradicted: return CompletionDecision(CompletionStatus.FAILED, False, "fresh readback contradicts the requested state of a changed file", (), (contradicted,)) if latest_verifier is not None: floor = self._action_order.get(latest_verifier.action_id, 0) if any(entry["ordinal"] > floor and self._entry_unsettled(entry, bool(entry.get("paths"))) for entry in self._current_effects()): return CompletionDecision( CompletionStatus.BLOCKED, False, "a later operation may have changed state after the latest executable verifier", (latest_verifier.event_id,)) satisfied_ids: list[str] = [] missing: list[str] = [] unsettled: list[str] = [] workspace_root = str(self.requirements.workspace_root or "").strip() for required in self.requirements.required_artifacts: matches = [ event for event in self.events if event.kind == EvidenceKind.ARTIFACT_MUTATION and _artifact_path_matches_required(event.artifact_path, required, self.requirements.workspace_root) ] authoritative = [ event for event in matches if event.authoritative ] latest = authoritative[-1] if authoritative else None successful = [event for event in authoritative if event.success] latest_success = successful[-1] if successful else None # Failed shell/Python mutations may have already truncated or # partially overwritten a file before returning non-zero. Atomic # helper failures (write_file/edit_file/apply_patch) preserve the # last successful artifact and therefore do not erase its evidence. destructive_failure = bool( latest is not None and not latest.success and latest.tool in {"bash", "python"} ) filesystem_missing = False if latest_success is not None and workspace_root: try: root = Path(workspace_root).resolve() identity = artifact_identity(required, workspace_root) candidate = (root / identity.removeprefix('workspace:')).resolve() if identity.startswith('workspace:') else Path(required).resolve() candidate.relative_to(root) filesystem_missing = not workspace_artifact_is_usable(candidate) except (OSError, RuntimeError, ValueError): filesystem_missing = True if latest_success is None or destructive_failure or filesystem_missing: missing.append(required) elif self.effects and self._effect_unsettled(required): # Earlier success is historical; a later possible change to # this artifact has no settled evidence. unsettled.append(required) else: satisfied_ids.append(latest_success.event_id) if missing or unsettled: return CompletionDecision( CompletionStatus.BLOCKED, False, "required artifacts lack successful mutation evidence" if missing else "a later operation may have changed a required artifact without settled evidence", tuple(satisfied_ids), tuple([*missing, *unsettled]), ) latest_mutation_index = max( ( index for index, event in enumerate(self.events) if event.kind == EvidenceKind.ARTIFACT_MUTATION and event.authoritative and event.success ), default=-1, ) latest_verifier_index = ( max( index for index, event in enumerate(self.events) if event is latest_verifier ) if latest_verifier is not None else -1 ) if ( latest_verifier is not None and latest_mutation_index > latest_verifier_index ): return CompletionDecision( CompletionStatus.BLOCKED, False, "the latest executable verifier predates the latest artifact mutation", tuple(satisfied_ids), ) current_validation_ids: list[str] = [] for required in self.requirements.required_artifacts: matching_mutation_indices = [ index for index, event in enumerate(self.events) if event.kind == EvidenceKind.ARTIFACT_MUTATION and event.authoritative and event.success and _artifact_path_matches_required(event.artifact_path, required, self.requirements.workspace_root) ] matching_validations = [ (index, event) for index, event in enumerate(self.events) if event.kind == EvidenceKind.ARTIFACT_VALIDATION and event.authoritative and _artifact_path_matches_required(event.artifact_path, required, self.requirements.workspace_root) ] if not matching_validations: continue latest_validation_index, latest_validation = matching_validations[-1] latest_artifact_mutation_index = max(matching_mutation_indices, default=-1) if latest_validation_index < latest_artifact_mutation_index: # A pre-edit inspection cannot invalidate executable checks # that passed against the later mutation. It still cannot # stand in for current verification when no such check exists. if latest_verifier_index > latest_artifact_mutation_index: continue return CompletionDecision( CompletionStatus.BLOCKED, False, "the latest artifact validation predates the latest artifact mutation", tuple(satisfied_ids), ) if not latest_validation.success: return CompletionDecision( CompletionStatus.FAILED, False, "the latest artifact validation failed", tuple([*satisfied_ids, latest_validation.event_id]), ) current_validation_ids.append(latest_validation.event_id) if self.requirements.verifier_required and latest_verifier is None: if self.requirements.executable_verifier_available: return CompletionDecision(CompletionStatus.BLOCKED, False, 'the request requires an executable verifier result', tuple(satisfied_ids)) validation_ids: list[str] = [] for required in self.requirements.required_artifacts: matching_validation = [ (index, event) for index, event in enumerate(self.events) if event.kind == EvidenceKind.ARTIFACT_VALIDATION and event.authoritative and event.success and _artifact_path_matches_required(event.artifact_path, required, self.requirements.workspace_root) ] latest_validation = matching_validation[-1] if matching_validation else None if latest_validation is None or latest_validation[0] < latest_mutation_index: return CompletionDecision( CompletionStatus.BLOCKED, False, "the request requires verification but no current artifact validation exists", tuple(satisfied_ids), ) validation_ids.append(latest_validation[1].event_id) if not validation_ids: return CompletionDecision( CompletionStatus.BLOCKED, False, "the request requires verification but no executable verifier result exists", tuple(satisfied_ids), ) return CompletionDecision( CompletionStatus.SATISFIED, True, "all declared artifacts have successful mutation and validation evidence", tuple([*satisfied_ids, *validation_ids]), ) if latest_verifier is not None: return CompletionDecision( CompletionStatus.VERIFIED, True, "the latest executable verifier passed", tuple([*satisfied_ids, latest_verifier.event_id]), ) if self.requirements.required_artifacts: return CompletionDecision( CompletionStatus.SATISFIED, True, ( "all declared artifacts have successful mutation and validation evidence" if current_validation_ids else "all declared artifacts have successful execution evidence; no executable verifier was reported" ), tuple([*satisfied_ids, *current_validation_ids]), ) successful = [event.event_id for event in self.events if event.success and event.authoritative] return CompletionDecision( CompletionStatus.UNVERIFIED, True, "no declared artifact or executable verifier was available", tuple(successful[-3:]), ) def to_list(self) -> list[dict[str, Any]]: return [event.to_dict() for event in self.events]