From e2f89448c52e00a0131e8cbc100a0e22d1520f85 Mon Sep 17 00:00:00 2001 From: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> Date: Wed, 18 Nov 2026 14:59:18 +0800 Subject: [PATCH] refactor(turn-driver): slim topology and capture and eliminate Any Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com> --- .../turn_driver/decision_capture.py | 557 +++++++------- .../subagent_execution_topology.py | 697 +++++------------- 2 files changed, 479 insertions(+), 775 deletions(-) diff --git a/loopx/control_plane/turn_driver/decision_capture.py b/loopx/control_plane/turn_driver/decision_capture.py index 472584e727..f9be17afe1 100644 --- a/loopx/control_plane/turn_driver/decision_capture.py +++ b/loopx/control_plane/turn_driver/decision_capture.py @@ -1,30 +1,72 @@ """Private original-capture and presentation IO; TS owns binding validation.""" from __future__ import annotations -from typing import Any, cast - +from collections.abc import Callable, Iterable, Mapping, Sequence +from dataclasses import dataclass import hashlib import json import os +from pathlib import Path import socket import stat import tempfile -from collections.abc import Callable, Mapping -from dataclasses import dataclass -from pathlib import Path -from ..quota.turn_envelope import bind_turn_decision_capture -from ..quota.error_codes import QuotaCommandValidationError from ..content_digest import BARE_SHA256_PATTERN +from ..quota.error_codes import QuotaCommandValidationError +from ..quota.turn_envelope import bind_turn_decision_capture from .native_context_profile import ( - NATIVE_CONTEXT_PAGE_BYTES as NATIVE_CONTEXT_PAGE_BYTES, - NATIVE_CONTEXT_PAGE_OUTPUT_BYTES as NATIVE_CONTEXT_PAGE_OUTPUT_BYTES, - NATIVE_CONTEXT_LARGE_OUTPUT_BYTES as NATIVE_CONTEXT_LARGE_OUTPUT_BYTES, NATIVE_CONTEXT_HISTORY_TOKENS as NATIVE_CONTEXT_HISTORY_TOKENS, + NATIVE_CONTEXT_LARGE_OUTPUT_BYTES as NATIVE_CONTEXT_LARGE_OUTPUT_BYTES, NATIVE_CONTEXT_OUTPUT_ENV as NATIVE_CONTEXT_OUTPUT_ENV, + NATIVE_CONTEXT_PAGE_BYTES as NATIVE_CONTEXT_PAGE_BYTES, + NATIVE_CONTEXT_PAGE_OUTPUT_BYTES as NATIVE_CONTEXT_PAGE_OUTPUT_BYTES, native_context_page_budget as native_context_page_budget, ) +Payload = dict[str, object] +PayloadView = Mapping[str, object] + + +def _as_mapping(value: object) -> PayloadView: + return value if isinstance(value, Mapping) else {} + + +def _read_physical_bytes( + value: str, *, max_bytes: int, private_uid: int | None, + symlink_error: str, size_error: str, private_error: str, + stat_size_error: str | None = None, exact_size: bool = False, +) -> tuple[Path, bytes]: + path = Path(value).expanduser().absolute() + # Parent aliases such as macOS /tmp are normal capture locations. + # Resolve those once, but never follow a substituted final file. + path = path.parent.resolve(strict=True) / path.name + if path.is_symlink(): + raise ValueError(symlink_error) + with os.fdopen(open_regular_capture(path), "rb") as stream: + info = os.fstat(stream.fileno()) + if info.st_size > max_bytes: + raise ValueError(stat_size_error or size_error) + if private_uid is not None and (info.st_uid != private_uid or info.st_mode & 0o077): + raise ValueError(private_error) + raw = stream.read(info.st_size + 1 if exact_size else max_bytes + 1) + if len(raw) > max_bytes or (exact_size and len(raw) != info.st_size): + raise ValueError(size_error) + return path, raw + + +def _lookup_path(root: object, path: Iterable[object], *, missing_message: str | None = None) -> object: + value = root + for key in path: + if isinstance(value, Mapping) and type(key) is str and key in value: + value = value[key] + elif isinstance(value, list) and type(key) is int and 0 <= key < len(value): + value = value[key] + elif missing_message is not None: + raise ValueError(missing_message) + else: + raise KeyError(key) + return value + def private_capture_supported() -> bool: """Whether this host has the POSIX identity needed for private capture IO.""" @@ -37,18 +79,20 @@ def private_capture_uid() -> int: POSIX mode bits cannot establish Windows privacy. Check before creating or reading private captures, and before evaluating bounded settlement commands. """ - if not private_capture_supported(): + getuid = getattr(os, "getuid", None) if os.name == "posix" else None + uid = getuid() if callable(getuid) else None + if not isinstance(uid, int): raise ValueError("private capture validation is unsupported on this platform; " "use the same Turn command without --max-page-output-bytes") - return cast(int, getattr(os, "getuid")()) + return uid -def _decision_json(payload: Mapping[str, Any]) -> str: +def _decision_json(payload: PayloadView) -> str: return json.dumps(dict(payload), ensure_ascii=False, separators=(",", ":"), allow_nan=False) + "\n" def write_decision_capture( - path: Path, payload: Mapping[str, Any], *, publish: Callable[[str, Path], None] = os.link, + path: Path, payload: PayloadView, *, publish: Callable[[str, Path], None] = os.link, ) -> str: """Publish complete private JSON once and return its exact byte digest. @@ -75,13 +119,9 @@ def open_regular_capture(path: Path) -> int: descriptor identity also rejects substituted entries on hosts without O_NOFOLLOW. Callers retain their own size and privacy checks. """ - descriptor = os.open( - path, - os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0), - ) + descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0)) try: - opened = os.fstat(descriptor) - entry = os.lstat(path) + opened, entry = os.fstat(descriptor), os.lstat(path) if not stat.S_ISREG(opened.st_mode): raise ValueError("capture must be a regular file") if stat.S_ISLNK(entry.st_mode): @@ -103,12 +143,12 @@ def read_turn_observation_text(path: Path) -> str: class StagedTurnDecisionCapture: """Validated private IO, published only after the native start is admitted.""" - plan: dict[str, Any] + plan: Payload path: Path - observation: dict[str, Any] + observation: Payload existed: bool - def publish(self) -> dict[str, Any]: + def publish(self) -> Payload: if self.path.is_symlink(): raise ValueError("Turn decision capture must not be a symlink") if self.path.exists(): @@ -117,12 +157,10 @@ def publish(self) -> dict[str, Any]: text = read_turn_observation_text(self.path) # Compact objects start with a quoted key (or are empty). Pretty # captures can go straight to their order-independent comparison. - compact = text.startswith('{"') or text == "{}\n" - if not compact or text != _decision_json(self.observation): - current = json.loads(text) - if (json.dumps(current, sort_keys=True, allow_nan=False) - != json.dumps(self.observation, sort_keys=True, allow_nan=False)): - raise ValueError("Turn decision capture changed before publication") + if (not (text.startswith('{"') or text == "{}\n") or text != _decision_json(self.observation)) and ( + json.dumps(json.loads(text), sort_keys=True, allow_nan=False) + != json.dumps(self.observation, sort_keys=True, allow_nan=False)): + raise ValueError("Turn decision capture changed before publication") elif self.existed: raise ValueError("Original Turn decision capture is missing; restore the original observation") else: @@ -130,15 +168,16 @@ def publish(self) -> dict[str, Any]: write_decision_capture(self.path, self.observation) return self.plan - def publish_for_host( - self, request: Mapping[str, Any], - ) -> tuple[dict[str, Any], dict[str, Any]]: + def publish_for_host(self, request: PayloadView) -> tuple[Payload, Payload]: """Install the published original input without changing recovery bindings.""" plan = self.publish() - from ..quota.turn_envelope import COMPLETE_TURN_PLAN_SCHEMA_VERSION, turn_plan_host_source + from ..quota.turn_envelope import ( + COMPLETE_TURN_HOST_REQUEST_SCHEMA, COMPLETE_TURN_PLAN_SCHEMA_VERSION, + LOOPX_TURN_HOST_REQUEST_SCHEMA, captured_turn_host_input, turn_plan_host_source, + ) if plan.get("schema_version") == COMPLETE_TURN_PLAN_SCHEMA_VERSION: - bound_request = {**request, **turn_plan_host_source(plan)} + bound_request: Payload = {**request, **turn_plan_host_source(plan)} bound_request.pop("turn_envelope", None) return plan, bound_request bound_request = {**request, "turn_envelope": plan["turn_envelope"]} @@ -148,16 +187,12 @@ def publish_for_host( else: # Only an original historical absence can clear the current input. bound_request.pop("work_contract", None) - from ..quota.turn_envelope import COMPLETE_TURN_HOST_REQUEST_SCHEMA, captured_turn_host_input - if request.get("schema_version") == COMPLETE_TURN_HOST_REQUEST_SCHEMA: if "work_contract" in plan: - bound_request = captured_turn_host_input(bound_request) + bound_request = dict(captured_turn_host_input(bound_request)) else: # The immutable original observation, not a bad current source, # owns restoration of a historical request version. - from ..quota.turn_envelope import LOOPX_TURN_HOST_REQUEST_SCHEMA - bound_request["schema_version"] = LOOPX_TURN_HOST_REQUEST_SCHEMA bound_request.pop("source_decision_hash", None) bound_request.pop("detail_ref", None) @@ -165,8 +200,7 @@ def publish_for_host( def stage_turn_decision_capture( - plan: Mapping[str, Any], *, journal_path: Path, - decision: Mapping[str, Any] | None, existing_journal: bool, + plan: PayloadView, *, journal_path: Path, decision: PayloadView | None, existing_journal: bool, ) -> StagedTurnDecisionCapture: """Validate under the journal lock before admission, without publishing IO. @@ -177,10 +211,10 @@ def stage_turn_decision_capture( from ..quota.turn_envelope import COMPLETE_TURN_PLAN_SCHEMA_VERSION, turn_plan_host_source current = plan.get("schema_version") == COMPLETE_TURN_PLAN_SCHEMA_VERSION - envelope = turn_plan_host_source(plan) if current else plan["turn_envelope"] - transaction = plan["transaction"] + envelope = _as_mapping(turn_plan_host_source(plan) if current else plan["turn_envelope"]) + transaction = _as_mapping(plan["transaction"]) path = journal_path.parent / "decisions" / journal_path.name - capture = envelope.get("detail_ref", {}).get("captured_decision") + capture = _as_mapping(envelope.get("detail_ref")).get("captured_decision") if existing_journal and not capture: raise ValueError("This Turn journal has no original decision capture; preserve it and " "recover its pending effects before starting a fresh Turn") @@ -188,7 +222,8 @@ def stage_turn_decision_capture( raise ValueError("Turn decision capture must not be a symlink") existed = path.exists() if existed: - observation = json.loads(read_turn_observation_text(path)) + loaded = json.loads(read_turn_observation_text(path)) + observation: Payload = dict(loaded) if isinstance(loaded, Mapping) else {} elif existing_journal or capture: raise ValueError("Original Turn decision capture is missing; restore the original " "observation, do not rerun the guard to replace it") @@ -198,18 +233,17 @@ def stage_turn_decision_capture( observation = dict(decision) from ...command_invocation import current_loopx_cli_argv + turn_key = str(transaction["turn_key"]) bound = bind_turn_decision_capture( observation, None if current else envelope, captured_decision_path=str(path), - turn_instance_id=str(transaction.get("turn_instance_id") or transaction["turn_key"]), - turn_key=transaction["turn_key"], + turn_instance_id=str(transaction.get("turn_instance_id") or turn_key), turn_key=turn_key, # New journals have a real immutable source and executable reader. # Legacy journals retain their recorded delivery/recovery route. reader_argv=current_loopx_cli_argv() if not existing_journal else None, - complete_host_request={key: value for key, value in envelope.items() if key != "work_contract"} - if current else None, + complete_host_request=({k: v for k, v in envelope.items() if k != "work_contract"} if current else None), ) - restored = ({**plan, **{key: bound[key] for key in ("source_decision_hash", "detail_ref")}} - if current else {**plan, "turn_envelope": bound}) + restored: Payload = ({**plan, "source_decision_hash": bound["source_decision_hash"], "detail_ref": bound["detail_ref"]} + if current else {**plan, "turn_envelope": bound}) if observation.get("schema_version") == "loopx_turn_envelope_v1": restored["work_contract"] = observation else: @@ -220,12 +254,11 @@ def stage_turn_decision_capture( def prepare_turn_decision_capture( - plan: Mapping[str, Any], *, journal_path: Path, - decision: Mapping[str, Any] | None, existing_journal: bool, -) -> dict[str, Any]: + plan: PayloadView, *, journal_path: Path, decision: PayloadView | None, existing_journal: bool, +) -> Payload: """Retain the existing immediate publication API for original-capture callers.""" - return stage_turn_decision_capture(plan, journal_path=journal_path, - decision=decision, existing_journal=existing_journal).publish() + return stage_turn_decision_capture( + plan, journal_path=journal_path, decision=decision, existing_journal=existing_journal).publish() _HANDOFF_CAPTURE_ROOT_LIMIT = 4096 @@ -248,13 +281,13 @@ def bind_handoff_capture_root(socket_path: str, capture_root: Path) -> None: def _validate_handoff_capture_root(endpoint: Path, requested_root: Path) -> None: try: - with os.fdopen(open_regular_capture(_handoff_capture_root_file(endpoint)), "rb") as stream: - metadata = os.fstat(stream.fileno()) - if metadata.st_uid != os.getuid() or metadata.st_mode & 0o077: - raise ValueError("capture root binding must be private to the Host user") - bound_root = stream.read(_HANDOFF_CAPTURE_ROOT_LIMIT + 1) - if not bound_root or len(bound_root) > _HANDOFF_CAPTURE_ROOT_LIMIT: - raise ValueError("invalid capture root binding size") + _, bound_root = _read_physical_bytes( + str(_handoff_capture_root_file(endpoint)), max_bytes=_HANDOFF_CAPTURE_ROOT_LIMIT, + private_uid=os.getuid(), symlink_error="capture root binding must not be a symlink", + size_error="invalid capture root binding size", + private_error="capture root binding must be private to the Host user") + if not bound_root: + raise ValueError("invalid capture root binding size") except FileNotFoundError: return # Earlier Hosts still validate the capture when accepting it. except (OSError, ValueError) as exc: @@ -267,19 +300,16 @@ def _validate_handoff_capture_root(endpoint: Path, requested_root: Path) -> None if bound_root != os.fsencode(requested_root): raise QuotaCommandValidationError( "decision handoff capture root differs from the current Host wake; no guard was run. " - "Use the --decision-output-root named by the current wake." - ) + "Use the --decision-output-root named by the current wake.") def validate_handoff_socket(value: str, *, capture_root: Path | None = None) -> Path: """A caller-owned local transport.""" path = Path(value) try: - if (os.name != "posix" or not hasattr(socket, "AF_UNIX") or not path.is_absolute() or - path.resolve(strict=True) != path or - not stat.S_ISSOCK(path.stat().st_mode) or - path.parent.stat().st_mode & 0o077 or - path.stat().st_uid != os.getuid()): + if (os.name != "posix" or not hasattr(socket, "AF_UNIX") or not path.is_absolute() + or path.resolve(strict=True) != path or not stat.S_ISSOCK(path.stat().st_mode) + or path.parent.stat().st_mode & 0o077 or path.stat().st_uid != os.getuid()): raise OSError("expected a same-user socket in a private physical directory") except FileNotFoundError as exc: # A resumed session can remember an earlier wake's private endpoint. @@ -288,8 +318,7 @@ def validate_handoff_socket(value: str, *, capture_root: Path | None = None) -> "invalid decision handoff socket: the endpoint no longer exists; it belonged " "to a Host wake that has ended. No guard was run. Rerun with the " "--decision-output-root and --decision-handoff-socket named by the current " - "wake, or without both when the current wake names none" - ) from exc + "wake, or without both when the current wake names none") from exc except OSError as exc: raise QuotaCommandValidationError(f"invalid decision handoff socket: {exc}") from exc if capture_root is not None: @@ -359,17 +388,13 @@ def validate_handoff_socket(value: str, *, capture_root: Path | None = None) -> ) -def context_capture_read_command(path: Path, digest: str, *, offset: int = 0, - page_bytes: int | None = None, - max_page_output_bytes: int | None = None, - select: list[str] | None = None, - selection_sha256: str | None = None, - list_fields: bool = False, - list_depth: int | None = None, - initial_read: bool = False, - reference_file: Path | None = None, - reader_argv: list[str] | None = None, - compact: bool = False) -> str: +def context_capture_read_command( + path: Path, digest: str, *, offset: int = 0, page_bytes: int | None = None, + max_page_output_bytes: int | None = None, select: list[str] | None = None, + selection_sha256: str | None = None, list_fields: bool = False, list_depth: int | None = None, + initial_read: bool = False, reference_file: Path | None = None, + reader_argv: list[str] | None = None, compact: bool = False, +) -> str: from ...command_invocation import loopx_cli_argv from ...install_contract import render_host_cli_command @@ -378,43 +403,38 @@ def context_capture_read_command(path: Path, digest: str, *, offset: int = 0, if max_page_output_bytes is None: max_page_output_bytes = NATIVE_CONTEXT_PAGE_OUTPUT_BYTES route = reader_argv if reader_argv is not None else loopx_cli_argv() - return render_host_cli_command([*route, "--format", "json", "quota", "context-read", + return render_host_cli_command([ + *route, "--format", "json", "quota", "context-read", *(["--reference-file", str(reference_file)] if reference_file is not None else ["--capture-file", str(path), "--capture-sha256", digest]), *(["--offset", str(offset)] if offset or not compact else []), *(["--page-bytes", str(page_bytes)] if page_bytes is not None else []), - *(["--initial-read"] if initial_read else []), - *(["--list"] if list_fields else []), + *(["--initial-read"] if initial_read else []), *(["--list"] if list_fields else []), *(["--list-depth", str(list_depth)] if list_depth is not None else []), - *(argument for pointer in select or [] for argument in ("--select", pointer)), + *(arg for pointer in select or [] for arg in ("--select", pointer)), *(["--selection-sha256", selection_sha256] if selection_sha256 is not None else []), - *(["--max-page-output-bytes", str(max_page_output_bytes)] if max_page_output_bytes is not None else [])]) + *(["--max-page-output-bytes", str(max_page_output_bytes)] if max_page_output_bytes is not None else []), + ]) -def write_context_read_reference(path: Path, digest: str, *, selection: dict[str, Any] | None = None, - navigation: dict[str, Any] | None = None, observed_read: dict[str, Any] | None = None, - selection_paths: list[list[str | int]] | None = None, - reference_file: Path | None = None, - reader_argv: list[str] | None = None) -> Path: +def write_context_read_reference( + path: Path, digest: str, *, selection: PayloadView | None = None, navigation: PayloadView | None = None, + observed_read: PayloadView | None = None, selection_paths: Sequence[Sequence[str | int]] | None = None, + reference_file: Path | None = None, reader_argv: list[str] | None = None, +) -> Path: """Immutable reader IO metadata. A short filename locates the document; only its complete stored digests are checked. A collision or replaced document fails closed, never overwrites. """ - payload: dict[str, Any] = {"schema_version": "context_capture_read_reference_v1", "path": str(path), "sha256": digest} - if reader_argv is not None: - payload["reader_argv"] = reader_argv - if selection is not None: - payload["selection"] = selection - if navigation is not None: - payload["navigation"] = navigation - if observed_read is not None: - payload["observed_read"] = observed_read + payload: Payload = {"schema_version": "context_capture_read_reference_v1", "path": str(path), "sha256": digest, **{ + k: v for k, v in (("reader_argv", reader_argv), ("selection", selection), + ("navigation", navigation), ("observed_read", observed_read)) if v is not None}} if selection is not None and selection_paths is not None: from ..effect_runtime import MAX_REQUEST_BYTES # A large descriptor can still use the older selector replay route. - with_paths = {**payload, "selection_paths": selection_paths} + with_paths: Payload = {**payload, "selection_paths": selection_paths} if len(_decision_json(with_paths).encode("utf-8")) <= MAX_REQUEST_BYTES: payload = with_paths suffix = ("." + hashlib.sha256(json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()).hexdigest()[:16] @@ -426,44 +446,35 @@ def write_context_read_reference(path: Path, digest: str, *, selection: dict[str write_decision_capture(reference, payload) except FileExistsError: existing = read_context_read_reference(str(reference))[1] - if existing["path"] != payload["path"]: + existing_path = existing.get("path") + if isinstance(existing_path, str) and existing_path != payload["path"]: # Readers resolve parent aliases, while retaining the exact leaf. # Compare that same spelling without rewriting immutable metadata # or treating a different leaf (including a hardlink) as identical. - original = Path(existing["path"]).expanduser().absolute() - current = path.expanduser().absolute() - if original.parent.resolve(strict=True) / original.name == current.parent.resolve(strict=True) / current.name: + orig, curr = Path(existing_path).expanduser().absolute(), path.expanduser().absolute() + if orig.parent.resolve(strict=True) / orig.name == curr.parent.resolve(strict=True) / curr.name: existing["path"] = payload["path"] if json.dumps(existing, sort_keys=True) != json.dumps(payload, sort_keys=True): raise ValueError("original reader reference changed; restore it without rerunning admission") from None return reference -def read_context_read_reference(value: str) -> tuple[Path, dict[str, Any]]: +def read_context_read_reference(value: str) -> tuple[Path, Payload]: """Read one private physical descriptor; the caller verifies capture bytes.""" from ..effect_runtime import MAX_REQUEST_BYTES - uid = private_capture_uid() - path = Path(value).expanduser().absolute() - path = path.parent.resolve(strict=True) / path.name - if path.is_symlink(): - raise ValueError("reader reference must be a physical file, not a symlink") - descriptor = open_regular_capture(path) - with os.fdopen(descriptor, "rb") as stream: - info = os.fstat(stream.fileno()) - if (info.st_uid != uid or info.st_mode & 0o077 - or info.st_size > MAX_REQUEST_BYTES): - raise ValueError("reader reference must be a private regular file owned by this user") - raw = stream.read(MAX_REQUEST_BYTES + 1) - if len(raw) > MAX_REQUEST_BYTES: - raise ValueError("reader reference exceeds the existing transport limit") + path, raw = _read_physical_bytes(value, max_bytes=MAX_REQUEST_BYTES, private_uid=private_capture_uid(), + symlink_error="reader reference must be a physical file, not a symlink", + size_error="reader reference exceeds the existing transport limit", + private_error="reader reference must be a private regular file owned by this user", + stat_size_error="reader reference must be a private regular file owned by this user") payload = json.loads(raw) if (not isinstance(payload, dict) or payload.get("schema_version") != "context_capture_read_reference_v1" or not isinstance(payload.get("path"), str) or not isinstance(payload.get("sha256"), str) or BARE_SHA256_PATTERN.fullmatch(payload["sha256"]) is None or ("selection" in payload and not isinstance(payload["selection"], dict)) - or ("selection_paths" in payload and ( - "selection" not in payload or not isinstance(payload["selection_paths"], list)))): + or ("selection_paths" in payload + and ("selection" not in payload or not isinstance(payload["selection_paths"], list)))): raise ValueError("reader reference is incomplete or unsupported") if "reader_argv" in payload: from ...command_invocation import validate_context_reader_route @@ -474,28 +485,18 @@ def read_context_read_reference(value: str) -> tuple[Path, dict[str, Any]]: return path, payload -def read_context_capture_file(value: str, digest: str, *, private: bool = False) -> tuple[Path, bytes, dict[str, Any]]: +def read_context_capture_file(value: str, digest: str, *, private: bool = False) -> tuple[Path, bytes, Payload]: """One bounded physical-file/hash check for readers and native observations.""" from ..effect_runtime import MAX_REQUEST_BYTES if not isinstance(digest, str) or BARE_SHA256_PATTERN.fullmatch(digest) is None or not value: raise ValueError("context-read requires the original capture file and its exact SHA-256") - uid = private_capture_uid() if private else None - path = Path(value).expanduser().absolute() - # Parent aliases such as macOS /tmp are normal capture locations. - # Resolve those once, but never follow a substituted final file. - path = path.parent.resolve(strict=True) / path.name - if path.is_symlink(): - raise ValueError("context-read requires the physical original capture path, not a symlink") - descriptor = open_regular_capture(path) - with os.fdopen(descriptor, "rb") as stream: - metadata = os.fstat(stream.fileno()) - if metadata.st_size > MAX_REQUEST_BYTES: - raise ValueError("capture must be a regular JSON file within the existing transport size limit") - if private and (metadata.st_uid != uid or metadata.st_mode & 0o077): - raise ValueError("native context requires a private capture owned by this user") - raw = stream.read(metadata.st_size + 1) - if len(raw) != metadata.st_size or hashlib.sha256(raw).hexdigest() != digest: + path, raw = _read_physical_bytes(value, max_bytes=MAX_REQUEST_BYTES, + private_uid=(private_capture_uid() if private else None), + symlink_error="context-read requires the physical original capture path, not a symlink", + size_error="capture must be a regular JSON file within the existing transport size limit", + private_error="native context requires a private capture owned by this user", exact_size=True) + if hashlib.sha256(raw).hexdigest() != digest: raise ValueError("capture digest mismatch; restore the original capture, do not rerun admission") payload = json.loads(raw.decode("utf-8")) if not isinstance(payload, dict): @@ -503,7 +504,7 @@ def read_context_capture_file(value: str, digest: str, *, private: bool = False) return path, raw, payload -def capture_page_range(page: dict[str, Any], *, raw: bytes, digest: str) -> tuple[int, int] | None: +def capture_page_range(page: PayloadView, *, raw: bytes, digest: str) -> tuple[int, int] | None: """Verify reported page bytes, independently of a host's retention claim.""" if ("selection_sha256" in page or "selected_pointers" in page or page.get("schema_version") != "context_capture_page_v1" or page.get("sha256") != digest): @@ -515,16 +516,16 @@ def capture_page_range(page: dict[str, Any], *, raw: bytes, digest: str) -> tupl end = start + len(data) if (page.get("total_bytes") != len(raw) or end > len(raw) or not data or page.get("eof") is not (end == len(raw)) - or page.get("next_offset") != (None if end == len(raw) else end) - or raw[start:end] != data): + or page.get("next_offset") != (None if end == len(raw) else end) or raw[start:end] != data): # Valid page JSON and a correct cursor can still carry the wrong body. return None return start, end -def capture_context_projection(payload: dict[str, Any], *, directory: Path, - read_guidance: str = CONTEXT_CAPTURE_READ_GUIDANCE, - filename: str = "projection.json") -> dict[str, Any]: +def capture_context_projection( + payload: PayloadView, *, directory: Path, read_guidance: str = CONTEXT_CAPTURE_READ_GUIDANCE, + filename: str = "projection.json", +) -> Payload: """Save the full projection independently of the optional presentation codec.""" from ...command_invocation import current_loopx_cli_argv @@ -535,17 +536,16 @@ def capture_context_projection(payload: dict[str, Any], *, directory: Path, return { "path": str(projection), "sha256": digest, "instruction": "Complete JSON for this captured view. Use it when required content is missing or uncertain; " - "compaction alone does not require replay within an existing work Turn. " - + read_guidance, + "compaction alone does not require replay within an existing work Turn. " + read_guidance, "command": context_capture_read_command(projection, digest, reader_argv=current_loopx_cli_argv()), } -def capture_progressive_context(payload: dict[str, Any], *, directory: Path, - surface: str = "quota_packet", - selection_command_args_template: str | None = None, - captured_decision: dict[str, str] | None = None, - replan_reader_argv: list[str] | None = None) -> tuple[dict[str, Any], dict[str, Any]]: +def capture_progressive_context( + payload: PayloadView, *, directory: Path, surface: str = "quota_packet", + selection_command_args_template: str | None = None, captured_decision: Mapping[str, str] | None = None, + replan_reader_argv: list[str] | None = None, +) -> tuple[PayloadView, Payload]: """Publish the complete current source before optional stateless presentation. The typed owner applies the shrink guard. This neither creates a native @@ -555,26 +555,25 @@ def capture_progressive_context(payload: dict[str, Any], *, directory: Path, from ..quota.turn_envelope import prepare_progressive_context source = capture_context_projection(payload, directory=directory) + optional: Payload = {k: v for k, v in ( + ("selection_command_args_template", selection_command_args_template), + ("captured_decision", dict(captured_decision) if captured_decision is not None else None), + ("replan_reader_argv", replan_reader_argv), + ) if v is not None} transaction = prepare_progressive_context(payload, surface=surface, source_reference={ - **{key: source[key] for key in ("path", "sha256")}, - **({"selection_command_args_template": selection_command_args_template} - if selection_command_args_template is not None else {}), - **({"captured_decision": captured_decision} if captured_decision is not None else {}), - **({"replan_reader_argv": replan_reader_argv} if replan_reader_argv is not None else {}), - "source_path": source["path"], - "command_template": source["command"] + " --select ''", - }) + "path": source["path"], "sha256": source["sha256"], "source_path": source["path"], + "command_template": f"{source['command']} --select ''", **optional}) if not transaction["projected"]: return payload, source - required = transaction["context"] + raw_required = transaction["context"] + required: Payload = dict(raw_required) if isinstance(raw_required, Mapping) else {} return required, capture_context_projection(required, directory=directory, filename="required-context.json") def project_captured_context( - payload: dict[str, Any], *, directory: Path | None, request: dict[str, Any] | None, - goal_id: str, agent_id: str, surface: str, capture_id: str, - captured_recovery: dict[str, Any] | None = None, -) -> dict[str, Any]: + payload: Payload, *, directory: Path | None, request: PayloadView | None, + goal_id: str, agent_id: str, surface: str, capture_id: str, captured_recovery: PayloadView | None = None, +) -> Payload: """Adapt an admitted capture to the shared TS presentation owner. The caller-owned rendezvous may supply a continuity observation. It must @@ -591,30 +590,28 @@ def project_captured_context( from ..quota.turn_envelope import prepare_context_delivery try: - recovery = captured_recovery if captured_recovery is not None else capture_context_projection( - payload, directory=directory) + recovery = (dict(captured_recovery) if captured_recovery is not None + else capture_context_projection(payload, directory=directory)) scope = request.get("scope") if not isinstance(scope, dict) or scope.get("goal_id") != goal_id or scope.get("agent_id") != agent_id: return payload - retained = request.get("retained") - continuity = request.get("continuity") + raw_opts = {k: request.get(k) for k in ("baseline", "retained", "continuity")} if "native_input" in request: from .codex_input_trace import codex_context_in_active_input # An optional native observation can only narrow the caller's # retention claim. It never mints an ACK or enables tracing, and a # malformed/stale observation must not fall back to that claim. - observation, baseline = request["native_input"], request.get("baseline") - native_session = scope.get("session_id") - if (not isinstance(observation, dict) or not isinstance(baseline, dict) - or not isinstance(native_session, str) - or not codex_context_in_active_input(observation, baseline=baseline, - session_id=native_session)): - retained = None - continuity = None - delivery = prepare_context_delivery(payload, scope=scope, - capture_id=capture_id, surface=surface, - baseline=request.get("baseline"), retained=retained, continuity=continuity) + obs, native_session, raw_base = request["native_input"], scope.get("session_id"), raw_opts["baseline"] + if (not isinstance(obs, dict) or not isinstance(raw_base, dict) or not isinstance(native_session, str) + or not codex_context_in_active_input(obs, baseline=raw_base, session_id=native_session)): + raw_opts["retained"] = raw_opts["continuity"] = None + if any(val is not None and not isinstance(val, Mapping) for val in raw_opts.values()): + return payload + opts = {k: val if isinstance(val, Mapping) else None for k, val in raw_opts.items()} + delivery = dict(prepare_context_delivery( + payload, scope=scope, capture_id=capture_id, surface=surface, + baseline=opts["baseline"], retained=opts["retained"], continuity=opts["continuity"])) delivery["recovery"] = recovery return delivery except (OSError, ValueError, TypeError, EffectRuntimeRemoteError, EffectRuntimeStartupError): @@ -623,21 +620,19 @@ def project_captured_context( return payload -def context_index_fields(payload: dict[str, Any], children: list[dict[str, Any]]) -> list[dict[str, Any]]: +def context_index_fields(payload: PayloadView, children: Sequence[PayloadView]) -> list[Payload]: """Serialize metadata for TS-verified addresses, preserving Python JSON values.""" - fields = [] + fields: list[Payload] = [] for child in children: - value: Any = payload - for key in child["path"]: - value = value[key] - field = {"pointer": child["pointer"], "type": - "object" if isinstance(value, dict) else "array" if isinstance(value, list) - else "null" if value is None else "boolean" if isinstance(value, bool) - else "string" if isinstance(value, str) else "number", - "bytes": len(json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode("utf-8"))} - if isinstance(value, (dict, list)): - field["count"] = len(value) - fields.append(field) + raw_path = child["path"] + assert isinstance(raw_path, Iterable) and not isinstance(raw_path, (str, bytes)) + value = _lookup_path(payload, raw_path) + kind = ("object" if isinstance(value, dict) else "array" if isinstance(value, list) + else "null" if value is None else "boolean" if isinstance(value, bool) + else "string" if isinstance(value, str) else "number") + fields.append({"pointer": child["pointer"], "type": kind, + "bytes": len(json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode("utf-8")), + **({"count": len(value)} if isinstance(value, (dict, list)) else {})}) return fields @@ -645,47 +640,49 @@ def _pointer_token(key: str | int) -> str: return str(key).replace("~", "~0").replace("/", "~1") -def context_selection_transport(payload: dict[str, Any], select: list[str] | None, *, - list_fields: bool, list_depth: int | None) -> dict[str, Any]: +def context_selection_transport( + payload: Payload, select: list[str] | None, *, list_fields: bool, list_depth: int | None, +) -> Payload: """Supply the address shape for the TS selector. Values are read from the verified original.""" # Root discovery also derives initial navigation from real decision values. - if not select or list_fields and "" in select: + if not select or list_fields and "" in select or not all(isinstance(pointer, str) for pointer in select): return payload - # Leave malformed requests to the typed owner, including error ordering. - if not all(isinstance(pointer, str) for pointer in select): - return payload - - paths: dict[str | None, Any] = {} + paths: dict[str | None, object] = {} for pointer in select: branch = paths for token in pointer.split("/")[1:]: - branch = branch.setdefault(token, {}) + if isinstance(nxt := branch.setdefault(token, {}), dict): + branch = nxt # None cannot collide with a JSON object key (including the empty key). branch[None] = True - - result: dict[str, Any] = {} - pending: list[tuple[Any, Any, dict[str | None, Any], int]] = [(payload, result, paths, 0)] + result: Payload = {} + pending: list[tuple[Mapping[str, object] | list[object], Payload | list[object], dict[str | None, object], int]] = [ + (payload, result, paths, 0)] while pending: source, target, branch, depth = pending.pop() if list_fields and None in branch: depth = max(depth, list_depth or 1) if depth <= 0 and not any(key is not None for key in branch): continue - for key, value in source.items() if isinstance(source, dict) else enumerate(source): + for key, value in (source.items() if isinstance(source, Mapping) else enumerate(source)): token = _pointer_token(key) if depth <= 0 and token not in branch: continue if isinstance(value, (dict, list)): - subtree = branch.get(token, {}) + raw_sub = branch.get(token) # Length matters when validating array indices or listing children. - child: Any = {} if isinstance(value, dict) else [0] * len(value) - target[key] = child - pending.append((value, child, subtree, depth - 1)) + child: Payload | list[object] = {} if isinstance(value, dict) else [0] * len(value) + pending.append((value, child, raw_sub if isinstance(raw_sub, dict) else {}, depth - 1)) + entry: object = child else: # Every scalar has the same address behavior. A one-byte marker # also prevents short scalar arrays growing during transport. # Original types, precision and byte counts stay at the renderer. - target[key] = 0 + entry = 0 + if isinstance(target, dict) and isinstance(key, str): + target[key] = entry + elif isinstance(target, list) and isinstance(key, int): + target[key] = entry return result @@ -696,15 +693,18 @@ def context_selection_transport(payload: dict[str, Any], select: list[str] | Non ) -def _first_read_goal_text(payload: dict[str, Any], path: list[Any], value: Any) -> str | None: +def _first_read_goal_text(payload: PayloadView, path: Sequence[object], value: object) -> str | None: # Only render the typed selector's registered Goal text leaf. The source, # enclosing containers, exact detail reads and unknown shapes stay literal. - if (not isinstance(value, str) or path[:4] != _GOAL_SOURCE_PREFIX - or len(path) != 7 or type(path[4]) is not int or path[5:] != ["content", "text"]): + if (not isinstance(value, str) or list(path[:4]) != _GOAL_SOURCE_PREFIX + or len(path) != 7 or type(path[4]) is not int or list(path[5:]) != ["content", "text"]): return None - interaction = payload["interaction_contract"] - source = interaction["agent_channel"]["work_context"]["sources"][path[4]] - content = source["content"] + interaction = _as_mapping(payload.get("interaction_contract")) + sources = _as_mapping(_as_mapping(interaction.get("agent_channel")).get("work_context")).get("sources") + if not isinstance(sources, list) or not (0 <= path[4] < len(sources)): + return None + source = _as_mapping(sources[path[4]]) + content = _as_mapping(source.get("content")) if (interaction.get("schema_version") != "loopx_interaction_contract_v0" or source.get("source") != "goal_state" or content.get("ok") is False or content.get("read_complete") is False or not content.get("state_file") @@ -717,26 +717,21 @@ def _first_read_goal_text(payload: dict[str, Any], path: list[Any], value: Any) return text if text is not None and len(value) - len(text) > len(_GOAL_NARRATIVE_PRESENTATION) + 96 else None -def _context_selection_bytes(payload: dict[str, Any], selections: list[dict[str, Any]], - *, list_fields: bool, list_depth: int | None, - present_goal_narrative: bool, - text_append: dict[str, Any] | None = None) -> tuple[bytes, list[str]]: +def _context_selection_bytes( + payload: PayloadView, selections: Sequence[PayloadView], *, list_fields: bool, list_depth: int | None, + present_goal_narrative: bool, text_append: PayloadView | None = None, +) -> tuple[bytes, list[str]]: """Render TS-verified addresses from the original, digest-checked values.""" if text_append is not None and (list_fields or not isinstance(text_append, dict)): raise ValueError("observed text append requires a selected value") - views: list[dict[str, Any]] = [] + views: list[Payload] = [] presented: list[str] = [] append_rendered = False for item in selections: - selected: Any = payload - path, pointer = item["path"], item["pointer"] - for key in path: - if type(key) is str and isinstance(selected, dict) and key in selected: - selected = selected[key] - elif type(key) is int and isinstance(selected, list) and 0 <= key < len(selected): - selected = selected[key] - else: - raise ValueError("selected address does not match the original capture") + path, pointer = item["path"], str(item["pointer"]) + assert isinstance(path, Iterable) and not isinstance(path, (str, bytes)) + path_list = list(path) + selected = _lookup_path(payload, path_list, missing_message="selected address does not match the original capture") if text_append is not None and pointer == text_append.get("pointer"): prefix = text_append.get("prefix_bytes") raw_text = selected.encode("utf-8") if isinstance(selected, str) else b"" @@ -747,57 +742,62 @@ def _context_selection_bytes(payload: dict[str, Any], selections: list[dict[str, presented.append(pointer) append_rendered = True elif list_fields: - views.append({"pointer": pointer, "fields": context_index_fields(payload, item["children"])}) + raw_children = item["children"] + children = [c for c in raw_children if isinstance(c, Mapping)] if isinstance(raw_children, Sequence) else [] + views.append({"pointer": pointer, "fields": context_index_fields(payload, children)}) else: - text = _first_read_goal_text(payload, path, selected) if present_goal_narrative else None - if text is None: - views.append({"pointer": pointer, "value": selected}) - else: + text = _first_read_goal_text(payload, path_list, selected) if present_goal_narrative else None + views.append({"pointer": pointer, "value": selected} if text is None + else {"pointer": pointer, "value": text, "presentation": _GOAL_NARRATIVE_PRESENTATION}) + if text is not None: presented.append(pointer) - views.append({"pointer": pointer, "value": text, "presentation": _GOAL_NARRATIVE_PRESENTATION}) if text_append is not None and not append_rendered: raise ValueError("observed text append does not match a selected value") - view_options = {"list_depth": list_depth} if list_depth is not None and list_depth != 1 else {} + opts = {"list_depth": list_depth} if list_depth is not None and list_depth != 1 else {} raw = json.dumps({"schema_version": "context_capture_index_v1" if list_fields else "context_capture_selection_v1", - "selections": views, **view_options}, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8") + b"\n" + "selections": views, **opts}, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8") + b"\n" return raw, presented -def context_selection_binding(select: list[str], *, list_fields: bool, list_depth: int | None, - sha256: str, presented: bool = False) -> dict[str, Any]: +def context_selection_binding( + select: list[str], *, list_fields: bool, list_depth: int | None, sha256: str, presented: bool = False, +) -> Payload: return {"select": select, "initial_read": False, "list_fields": list_fields, "list_depth": list_depth, - "sha256": sha256, **({"present_goal_narrative": True} if presented else {})} + "sha256": sha256, **({"present_goal_narrative": True} if presented else {})} -def initial_context_selection_bytes(payload: dict[str, Any], selections: list[dict[str, Any]], *, - text_append: dict[str, Any] | None = None) -> tuple[bytes, list[str]]: +def initial_context_selection_bytes( + payload: PayloadView, selections: Sequence[PayloadView], *, text_append: PayloadView | None = None, +) -> tuple[bytes, list[str]]: return _context_selection_bytes(payload, selections, list_fields=False, list_depth=None, - present_goal_narrative=True, text_append=text_append) + present_goal_narrative=True, text_append=text_append) -def write_initial_context_read_reference(path: Path, digest: str, payload: dict[str, Any], - selections: list[dict[str, Any]], *, - observed_read: dict[str, Any] | None = None) -> tuple[Path, bytes]: +def write_initial_context_read_reference( + path: Path, digest: str, payload: PayloadView, selections: Sequence[PayloadView], + *, observed_read: PayloadView | None = None, +) -> tuple[Path, bytes]: """Pin the shared rendered selection and return its exact rendered bytes.""" - text_append = observed_read.get("text_append") if observed_read else None - raw, presented = initial_context_selection_bytes(payload, selections, text_append=text_append) - reference = write_context_read_reference(path, digest, - selection=context_selection_binding([item["pointer"] for item in selections], list_fields=False, - list_depth=None, sha256=hashlib.sha256(raw).hexdigest(), presented=bool(presented)), - selection_paths=[item["path"] for item in selections], - observed_read=observed_read) + raw_append = observed_read.get("text_append") if observed_read else None + raw, presented = initial_context_selection_bytes( + payload, selections, text_append=(raw_append if isinstance(raw_append, Mapping) else None)) + selection_paths = [[k for k in rp if type(k) in (str, int)] for item in selections + if isinstance(rp := item.get("path"), Sequence) and not isinstance(rp, (str, bytes))] + reference = write_context_read_reference( + path, digest, selection_paths=selection_paths, observed_read=observed_read, + selection=context_selection_binding([str(item["pointer"]) for item in selections], list_fields=False, + list_depth=None, sha256=hashlib.sha256(raw).hexdigest(), presented=bool(presented))) return reference, raw -def _pinned_selection_plan(select: list[str] | None, paths: list[list[str | int]]) -> dict[str, Any]: +def _pinned_selection_plan(select: list[str] | None, paths: Sequence[Sequence[str | int]]) -> Payload: """Replay TypeScript's resolved addresses from the existing reader reference.""" if (not isinstance(select, list) or not select or len(select) != len(paths) or not all(isinstance(pointer, str) for pointer in select) or len(set(select)) != len(select)): raise ValueError("reader selection paths do not match its pinned addresses") - selections = [] + selections: list[Payload] = [] for pointer, path in zip(select, paths, strict=True): - if (not isinstance(path, list) - or not all(type(key) in (str, int) for key in path) + if (not isinstance(path, list) or not all(type(key) in (str, int) for key in path) or pointer != "".join("/" + _pointer_token(key) for key in path)): raise ValueError("reader selection paths do not match its pinned addresses") selections.append({"pointer": pointer, "path": path}) @@ -808,13 +808,11 @@ class ContextSelectionDigestChanged(ValueError): """The rendered selection no longer matches its recorded digest.""" -def context_selection_view(payload: dict[str, Any], *, select: list[str] | None, - initial_read: bool, list_fields: bool, list_depth: int | None, - expected_sha256: str | None, preserve_selection_order: bool = False, - present_goal_narrative: bool | None = None, - selection_paths: list[list[str | int]] | None = None, - text_append: dict[str, Any] | None = None, - ) -> tuple[dict[str, Any], bytes | None, str | None]: +def context_selection_view( + payload: Payload, *, select: list[str] | None, initial_read: bool, list_fields: bool, list_depth: int | None, + expected_sha256: str | None, preserve_selection_order: bool = False, present_goal_narrative: bool | None = None, + selection_paths: Sequence[Sequence[str | int]] | None = None, text_append: PayloadView | None = None, +) -> tuple[Payload, bytes | None, str | None]: """Render the digest-pinned view from a new or previously resolved plan.""" if text_append is not None and (initial_read or list_fields or expected_sha256 is None): raise ValueError("observed text append requires a pinned value selection") @@ -825,28 +823,29 @@ def context_selection_view(payload: dict[str, Any], *, select: list[str] | None, else: from ..quota.turn_envelope import _turn_envelope_result - context = payload if initial_read else context_selection_transport( + context: Payload = payload if initial_read else context_selection_transport( payload, select, list_fields=list_fields, list_depth=list_depth) - selection = {"initial_read": True} if initial_read else {"select": select} - depth = {"list_depth": list_depth} if list_depth is not None else {} - order = {"preserve_selection_order": True} if preserve_selection_order else {} - plan = _turn_envelope_result("context_select", context=context, list_fields=list_fields, - recover_selection_errors=not initial_read, **selection, **depth, **order) + plan_args: Payload = {**({"initial_read": True} if initial_read else {"select": select}), + **({"list_depth": list_depth} if list_depth is not None else {})} + plan = dict(_turn_envelope_result("context_select", context=context, list_fields=list_fields, + recover_selection_errors=not initial_read, **plan_args, + **({"preserve_selection_order": True} if preserve_selection_order else {}))) if plan.get("rejected_selection"): return plan, None, None presentation = initial_read if present_goal_narrative is None else present_goal_narrative - def render(plan: dict[str, Any], present: bool) -> tuple[bytes, str, list[str]]: - raw, displayed = _context_selection_bytes(payload, plan["selections"], list_fields=list_fields, - list_depth=list_depth, present_goal_narrative=present, text_append=text_append) + def render(rendered_plan: PayloadView, present: bool) -> tuple[bytes, str, list[str]]: + raw_sels = rendered_plan.get("selections") + sels = [s for s in raw_sels if isinstance(s, Mapping)] if isinstance(raw_sels, Sequence) else [] + raw, displayed = _context_selection_bytes(payload, sels, list_fields=list_fields, list_depth=list_depth, + present_goal_narrative=present, text_append=text_append) return raw, hashlib.sha256(raw).hexdigest(), displayed raw, digest, displayed = render(plan, presentation) if selection_paths is None and preserve_selection_order and expected_sha256 != digest: # Historical explicit references may pin canonical output despite # retaining caller order. Only the same source and addresses can replay. - plan = _turn_envelope_result("context_select", context=context, - list_fields=list_fields, **selection, **depth) + plan = dict(_turn_envelope_result("context_select", context=context, list_fields=list_fields, **plan_args)) raw, digest, displayed = render(plan, presentation) if (expected_sha256 is not None and expected_sha256 != digest and initial_read and present_goal_narrative is None and displayed): diff --git a/loopx/control_plane/turn_driver/subagent_execution_topology.py b/loopx/control_plane/turn_driver/subagent_execution_topology.py index 99b4d5effa..6c3af1f144 100644 --- a/loopx/control_plane/turn_driver/subagent_execution_topology.py +++ b/loopx/control_plane/turn_driver/subagent_execution_topology.py @@ -1,14 +1,16 @@ from __future__ import annotations +from collections.abc import Iterable, Mapping, Sequence import hashlib import json import re -from collections.abc import Mapping, Sequence -from typing import Any from ..agent_context import envelope_agent_context from ..runtime.public_safety import validate_public_safe_value +Payload = dict[str, object] +PayloadView = Mapping[str, object] + SUBAGENT_EXECUTION_TOPOLOGY_SCHEMA_VERSION = "subagent_execution_topology_v0" SUBAGENT_HOST_EXECUTION_RECEIPT_SCHEMA_VERSION = ( @@ -88,31 +90,31 @@ def __init__(self, *, reason_code: str, detail: str) -> None: super().__init__(f"{reason_code}: {detail}") -def subagent_execution_topology( - plan: Mapping[str, Any], -) -> Mapping[str, Any] | None: +def subagent_execution_topology(plan: PayloadView) -> PayloadView | None: topology = plan.get("subagent_execution_topology") return topology if isinstance(topology, Mapping) else None -def subagent_host_result_fields(plan: Mapping[str, Any]) -> frozenset[str]: - return ( - HOST_RESULT_FIELDS - if subagent_execution_topology(plan) is not None - else frozenset() - ) +def subagent_host_result_fields(plan: PayloadView) -> frozenset[str]: + return HOST_RESULT_FIELDS if subagent_execution_topology(plan) is not None else frozenset() -def _mapping(value: Any) -> dict[str, Any]: +def _mapping(value: object) -> Payload: return dict(value) if isinstance(value, Mapping) else {} -def _opaque_ref( - value: Any, - *, - field: str, - required: bool = True, -) -> str | None: +def _string_list(value: object) -> list[str]: + if isinstance(value, Sequence) and not isinstance(value, (str, bytes)): + return [str(item) for item in value] + return [] + + +def _require_packet(condition: bool, detail: str) -> None: + if not condition: + raise ChildExecutionTopologyError(reason_code="child_task_packet_incomplete", detail=detail) + + +def _opaque_ref(value: object, *, field: str, required: bool = True) -> str | None: if value is None or value == "": text = "" elif not isinstance(value, str): @@ -125,18 +127,12 @@ def _opaque_ref( return None validate_public_safe_value(text, path=field) if not _OPAQUE_REF.fullmatch(text): - raise ValueError( - f"{field} must be an opaque 1-192 character public-safe reference" - ) + raise ValueError(f"{field} must be an opaque 1-192 character public-safe reference") return text def _opaque_refs( - value: Any, - *, - field: str, - limit: int, - allowed: frozenset[str] | None = None, + value: object, *, field: str, limit: int, allowed: frozenset[str] | None = None ) -> list[str]: if not isinstance(value, list): raise ValueError(f"{field} must be a list") @@ -153,52 +149,28 @@ def _opaque_refs( return sorted(result) -def _digest(value: Mapping[str, Any]) -> str: +def _canonical_sha256(value: PayloadView) -> str: return hashlib.sha256( - json.dumps( - dict(value), - ensure_ascii=True, - sort_keys=True, - separators=(",", ":"), - ).encode("utf-8") - ).hexdigest()[:16] - - -def _sha256_ref(value: Mapping[str, Any]) -> str: - return "sha256:" + hashlib.sha256( - json.dumps( - dict(value), - ensure_ascii=True, - sort_keys=True, - separators=(",", ":"), - ).encode("utf-8") + json.dumps(dict(value), ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode("utf-8") ).hexdigest() def subagent_bundle_id(*, turn_key: str) -> str: - return "bundle_" + _digest({"turn_key": turn_key}) + return "bundle_" + _canonical_sha256({"turn_key": turn_key})[:16] def subagent_lane_id(*, bundle_id: str, todo_id: str) -> str: - return "lane_" + _digest({"bundle_id": bundle_id, "todo_id": todo_id}) + return "lane_" + _canonical_sha256({"bundle_id": bundle_id, "todo_id": todo_id})[:16] -def _required_text(value: Any, *, field: str) -> str: +def _required_text(value: object, *, field: str) -> str: text = str(value or "").strip() - if not text: - raise ChildExecutionTopologyError( - reason_code="child_task_packet_incomplete", - detail=f"{field} is required before child launch", - ) + _require_packet(bool(text), f"{field} is required before child launch") return text -def _child_guard_policy(brief: Mapping[str, Any]) -> dict[str, Any]: - if brief.get("child_guard_policy") != "prevention_first_v0": - raise ChildExecutionTopologyError( - reason_code="child_task_packet_incomplete", - detail="child_guard_policy is missing or not fail-local", - ) +def _child_guard_policy(brief: PayloadView) -> Payload: + _require_packet(brief.get("child_guard_policy") == "prevention_first_v0", "child_guard_policy is missing or not fail-local") return { "schema_version": CHILD_EXECUTION_GUARD_SCHEMA_VERSION, "pre_spawn": "require_complete_task_packet", @@ -210,73 +182,37 @@ def _child_guard_policy(brief: Mapping[str, Any]) -> dict[str, Any]: } -def _child_context_contract(operation: Mapping[str, Any]) -> dict[str, Any]: - mode = _required_text( - operation.get("recommended_context"), - field="recommended_context", - ) +def _child_context_contract(operation: PayloadView) -> Payload: + mode = _required_text(operation.get("recommended_context"), field="recommended_context") available_contexts = operation.get("available_contexts") - if not isinstance(available_contexts, list): - raise ChildExecutionTopologyError( - reason_code="child_task_packet_incomplete", - detail="available_contexts must be explicit", - ) - if mode not in CHILD_CONTEXT_MODES: - raise ChildExecutionTopologyError( - reason_code="child_task_packet_incomplete", - detail="recommended_context is unsupported", - ) - if mode not in available_contexts: - raise ChildExecutionTopologyError( - reason_code="child_task_packet_incomplete", - detail="recommended_context is not available on the selected host", - ) - return { - "mode": mode, - "inheritance": CHILD_CONTEXT_INHERITANCE[mode], - } + _require_packet(isinstance(available_contexts, list), "available_contexts must be explicit") + _require_packet(mode in CHILD_CONTEXT_MODES, "recommended_context is unsupported") + assert isinstance(available_contexts, list) + _require_packet(mode in available_contexts, "recommended_context is not available on the selected host") + return {"mode": mode, "inheritance": CHILD_CONTEXT_INHERITANCE[mode]} def _child_task_packet( - *, - operation: Mapping[str, Any], - brief: Mapping[str, Any], - todo_id: str, - source_state_ref: str, - allowed_effect_classes: Sequence[str], - workspace_requirement: str, - workspace_ref: str | None, -) -> dict[str, Any]: + *, operation: PayloadView, brief: PayloadView, todo_id: str, source_state_ref: str, + allowed_effect_classes: Sequence[str], workspace_requirement: str, workspace_ref: str | None, +) -> Payload: required_capabilities = brief.get("required_capabilities") required_write_scopes = brief.get("required_write_scopes") acceptance = brief.get("acceptance") - if not isinstance(required_capabilities, list): - raise ChildExecutionTopologyError( - reason_code="child_task_packet_incomplete", - detail="required_capabilities must be explicit", - ) - if not isinstance(required_write_scopes, list): - raise ChildExecutionTopologyError( - reason_code="child_task_packet_incomplete", - detail="required_write_scopes must be explicit", - ) - if ( - not isinstance(acceptance, list) - or not acceptance - or not all(isinstance(item, str) and item.strip() for item in acceptance) - ): - raise ChildExecutionTopologyError( - reason_code="child_task_packet_incomplete", - detail="acceptance must be a non-empty string list", - ) + _require_packet(isinstance(required_capabilities, list), "required_capabilities must be explicit") + _require_packet(isinstance(required_write_scopes, list), "required_write_scopes must be explicit") + _require_packet( + isinstance(acceptance, list) and bool(acceptance) + and all(isinstance(item, str) and bool(item.strip()) for item in acceptance), + "acceptance must be a non-empty string list", + ) + assert isinstance(required_capabilities, list) + assert isinstance(required_write_scopes, list) + assert isinstance(acceptance, list) validation_declared = brief.get("validation_declared") is True - validation = { + validation: Payload = { "declared": validation_declared, - "authority_ref": ( - f"todo:{todo_id}:completion_validation" - if validation_declared - else None - ), + "authority_ref": f"todo:{todo_id}:completion_validation" if validation_declared else None, "execution_owner": "registered_parent", "command_disclosed": False, "label": str(brief.get("validation_label") or "").strip() or None, @@ -284,82 +220,46 @@ def _child_task_packet( "registered parent runs declared todo completion validation; " "child reports relevant validation evidence" if validation_declared - else _required_text( - brief.get("validation_policy"), - field="validation_policy", - ) + else _required_text(brief.get("validation_policy"), field="validation_policy") ), } execution_policy = brief.get("execution_policy") - task_packet = { + task_packet: Payload = { "schema_version": CHILD_EXECUTION_TASK_PACKET_SCHEMA_VERSION, "todo_id": todo_id, "objective": _required_text(brief.get("objective"), field="objective"), - "action_kind": _required_text( - brief.get("action_kind"), - field="action_kind", - ), + "action_kind": _required_text(brief.get("action_kind"), field="action_kind"), "target_key": str(brief.get("target_key") or "").strip() or None, - "deliverable": ( - "held_workspace_change_with_evidence" - if required_write_scopes - else "public_safe_evidence" - ), - "acceptance": [item.strip() for item in acceptance], + "deliverable": "held_workspace_change_with_evidence" if required_write_scopes else "public_safe_evidence", + "acceptance": [str(item).strip() for item in acceptance], "context_refs": [ _required_text(brief.get("authority_artifact"), field="authority_artifact"), _required_text(brief.get("latest_state_ref"), field="latest_state_ref"), source_state_ref, ], - "task_domain": _required_text( - brief.get("task_domain"), - field="task_domain", - ), + "task_domain": _required_text(brief.get("task_domain"), field="task_domain"), "task_repository": str(brief.get("task_repository") or "").strip() or None, "allowed_capabilities": list(required_capabilities), "allowed_write_scopes": list(required_write_scopes), "allowed_effect_classes": list(allowed_effect_classes), - "forbidden_effect_classes": sorted( - KNOWN_EFFECT_CLASSES - set(allowed_effect_classes) - ), + "forbidden_effect_classes": sorted(KNOWN_EFFECT_CLASSES - set(allowed_effect_classes)), "workspace_requirement": workspace_requirement, "workspace_ref": workspace_ref, "context": _child_context_contract(operation), - "execution_budget": ( - dict(execution_policy) if isinstance(execution_policy, Mapping) else {} - ), - "output_contract": _required_text( - brief.get("expected_output"), - field="expected_output", - ), - "acceptance_mode": ( - "parent_validation_then_review" - if validation["declared"] - else "parent_review_only" - ), + "execution_budget": dict(execution_policy) if isinstance(execution_policy, Mapping) else {}, + "output_contract": _required_text(brief.get("expected_output"), field="expected_output"), + "acceptance_mode": "parent_validation_then_review" if validation["declared"] else "parent_review_only", "validation": validation, "guard": _child_guard_policy(brief), } - if not task_packet["execution_budget"]: - raise ChildExecutionTopologyError( - reason_code="child_task_packet_incomplete", - detail="execution_policy must define the child budget", - ) + _require_packet(bool(task_packet["execution_budget"]), "execution_policy must define the child budget") validate_public_safe_value(task_packet, path="child_task_packet") return task_packet -def _child_pre_spawn_rejection( - operation: Mapping[str, Any], - *, - reason_code: str, -) -> dict[str, Any]: +def _child_pre_spawn_rejection(operation: PayloadView, *, reason_code: str) -> Payload: try: - todo_id = _opaque_ref( - operation.get("todo_id"), - field="pre_spawn_rejection.todo_id", - required=False, - ) + todo_id = _opaque_ref(operation.get("todo_id"), field="pre_spawn_rejection.todo_id", required=False) except ValueError: todo_id = None return { @@ -376,48 +276,28 @@ def _child_pre_spawn_rejection( def _child_execution_lane( - operation: Mapping[str, Any], - *, - bundle_id: str, - source_state_ref: str, -) -> dict[str, Any]: - todo_id = _opaque_ref( - operation.get("todo_id"), - field="topology.lanes[].todo_id", - ) + operation: PayloadView, *, bundle_id: str, source_state_ref: str +) -> Payload: + todo_id = _opaque_ref(operation.get("todo_id"), field="topology.lanes[].todo_id") assert todo_id is not None brief = _mapping(operation.get("brief")) write_scopes = brief.get("required_write_scopes") has_workspace_write = isinstance(write_scopes, list) and bool(write_scopes) required_capabilities = brief.get("required_capabilities") - uses_network = ( - isinstance(required_capabilities, list) - and "network" in required_capabilities - ) - effect_boundary = ( - "held_workspace_write" if has_workspace_write else "held_evidence_only" - ) + uses_network = isinstance(required_capabilities, list) and "network" in required_capabilities + effect_boundary = "held_workspace_write" if has_workspace_write else "held_evidence_only" allowed_effect_classes = ["local_read"] if uses_network: allowed_effect_classes.append("network_read") if has_workspace_write: allowed_effect_classes.append("held_workspace_write") - lane_id = subagent_lane_id( - bundle_id=bundle_id, - todo_id=todo_id, - ) + lane_id = subagent_lane_id(bundle_id=bundle_id, todo_id=todo_id) workspace_ref = f"workspace:{lane_id}" if has_workspace_write else None - workspace_requirement = ( - "independent_git_worktree" if has_workspace_write else "not_required" - ) + workspace_requirement = "independent_git_worktree" if has_workspace_write else "not_required" task_packet = _child_task_packet( - operation=operation, - brief=brief, - todo_id=todo_id, - source_state_ref=source_state_ref, + operation=operation, brief=brief, todo_id=todo_id, source_state_ref=source_state_ref, allowed_effect_classes=allowed_effect_classes, - workspace_requirement=workspace_requirement, - workspace_ref=workspace_ref, + workspace_requirement=workspace_requirement, workspace_ref=workspace_ref, ) return { "lane_id": lane_id, @@ -429,33 +309,21 @@ def _child_execution_lane( "workspace_requirement": workspace_requirement, "workspace_ref": workspace_ref, "task_packet": task_packet, - "task_packet_digest": _sha256_ref(task_packet), + "task_packet_digest": "sha256:" + _canonical_sha256(task_packet), } def build_subagent_execution_topology( - *, - turn_envelope: Mapping[str, Any], - child_operations: Sequence[Mapping[str, Any]], - turn_key: str, - source_state_ref: str, -) -> dict[str, Any] | None: + *, turn_envelope: PayloadView, child_operations: Sequence[PayloadView], + turn_key: str, source_state_ref: str, +) -> Payload | None: if not child_operations: return None orchestration = _mapping(turn_envelope.get("task_orchestration_contract")) - if ( - orchestration.get("schema_version") != "task_orchestration_contract_v2" - or orchestration.get("mode") != "adaptive" - ): + if orchestration.get("schema_version") != "task_orchestration_contract_v2" or orchestration.get("mode") != "adaptive": return None - normalized_source_state_ref = _opaque_ref( - source_state_ref, - field="topology.source_state_ref", - ) - goal_id = _opaque_ref( - turn_envelope.get("goal_id"), - field="topology.goal_id", - ) + normalized_source_state_ref = _opaque_ref(source_state_ref, field="topology.source_state_ref") + goal_id = _opaque_ref(turn_envelope.get("goal_id"), field="topology.goal_id") coordinator_agent_id = _opaque_ref( orchestration.get("coordinator_agent_id") or turn_envelope.get("agent_id"), field="topology.coordinator_agent_id", @@ -467,42 +335,25 @@ def build_subagent_execution_topology( configured_max_children = orchestration.get("max_children") max_children = ( configured_max_children - if isinstance(configured_max_children, int) - and not isinstance(configured_max_children, bool) + if isinstance(configured_max_children, int) and not isinstance(configured_max_children, bool) and configured_max_children > 0 else len(child_operations) ) - lanes: list[dict[str, Any]] = [] - pre_spawn_rejections: list[dict[str, Any]] = [] + lanes: list[Payload] = [] + pre_spawn_rejections: list[Payload] = [] allowed_effect_classes: set[str] = set() for operation in child_operations: if len(lanes) >= max_children: - pre_spawn_rejections.append( - _child_pre_spawn_rejection( - operation, - reason_code="child_capacity_exceeded", - ) - ) + pre_spawn_rejections.append(_child_pre_spawn_rejection(operation, reason_code="child_capacity_exceeded")) continue try: - lane = _child_execution_lane( - operation, - bundle_id=bundle_id, - source_state_ref=normalized_source_state_ref, - ) + lane = _child_execution_lane(operation, bundle_id=bundle_id, source_state_ref=normalized_source_state_ref) except (ChildExecutionTopologyError, ValueError): - pre_spawn_rejections.append( - _child_pre_spawn_rejection( - operation, - reason_code="child_task_packet_incomplete", - ) - ) + pre_spawn_rejections.append(_child_pre_spawn_rejection(operation, reason_code="child_task_packet_incomplete")) continue - allowed_effect_classes.update(lane["allowed_effect_classes"]) + allowed_effect_classes.update(_string_list(lane.get("allowed_effect_classes"))) lanes.append(lane) - rationale_codes = ( - ["admitted_ephemeral_child_lanes"] if lanes else ["parent_serial_fallback"] - ) + rationale_codes = ["admitted_ephemeral_child_lanes"] if lanes else ["parent_serial_fallback"] if pre_spawn_rejections: rationale_codes.append("child_launch_rejected") return { @@ -520,50 +371,42 @@ def build_subagent_execution_topology( }, "rationale_codes": rationale_codes, "lanes": lanes, - **( - {"pre_spawn_rejections": pre_spawn_rejections} - if pre_spawn_rejections - else {} - ), + **({"pre_spawn_rejections": pre_spawn_rejections} if pre_spawn_rejections else {}), } def bind_child_operations_to_topology( - child_operations: Sequence[Mapping[str, Any]], - topology: Mapping[str, Any] | None, -) -> list[dict[str, Any]]: + child_operations: Sequence[PayloadView], topology: PayloadView | None, +) -> list[Payload]: if not topology: return [dict(operation) for operation in child_operations] + raw_lanes = topology.get("lanes") lanes_by_todo = { str(lane.get("todo_id") or ""): lane - for lane in topology.get("lanes") or [] + for lane in (raw_lanes if isinstance(raw_lanes, Iterable) and not isinstance(raw_lanes, (str, bytes, Mapping)) else ()) if isinstance(lane, Mapping) } - bound_operations: list[dict[str, Any]] = [] + bound_operations: list[Payload] = [] for operation in child_operations: lane = _mapping(lanes_by_todo.get(str(operation.get("todo_id") or ""))) if not lane: continue - bound_operations.append( - { - **dict(operation), - "bundle_id": topology.get("bundle_id"), - "lane_id": lane.get("lane_id"), - "execution_kind": lane.get("execution_kind"), - "source_state_ref": topology.get("source_state_ref"), - "task_packet_digest": lane.get("task_packet_digest"), - "task_packet": _mapping(lane.get("task_packet")), - "effect_boundary": lane.get("effect_boundary"), - "workspace_ref": lane.get("workspace_ref"), - } - ) + bound_operations.append({ + **dict(operation), + "bundle_id": topology.get("bundle_id"), + "lane_id": lane.get("lane_id"), + "execution_kind": lane.get("execution_kind"), + "source_state_ref": topology.get("source_state_ref"), + "task_packet_digest": lane.get("task_packet_digest"), + "task_packet": _mapping(lane.get("task_packet")), + "effect_boundary": lane.get("effect_boundary"), + "workspace_ref": lane.get("workspace_ref"), + }) return bound_operations -def subagent_host_request_projection( - plan: Mapping[str, Any], -) -> dict[str, Any]: - projection: dict[str, Any] = {} +def subagent_host_request_projection(plan: PayloadView) -> Payload: + projection: Payload = {} context = plan.get("delegation_context") if isinstance(context, Mapping): projection["delegation_context"] = dict(context) @@ -576,55 +419,27 @@ def subagent_host_request_projection( return projection -def child_execution_receipts_json_schema() -> dict[str, Any]: - opaque_ref = { - "type": "string", - "pattern": OPAQUE_REF_PATTERN, - "maxLength": 192, - } - nullable_ref = { - "anyOf": [ - dict(opaque_ref), - {"type": "null"}, - ] - } - properties = { - "schema_version": { - "type": "string", - "enum": [SUBAGENT_HOST_EXECUTION_RECEIPT_SCHEMA_VERSION], - }, +def child_execution_receipts_json_schema() -> Payload: + opaque_ref: Payload = {"type": "string", "pattern": OPAQUE_REF_PATTERN, "maxLength": 192} + def string_enum(values: Iterable[str]) -> Payload: + return {"type": "string", "enum": sorted(values)} + + properties: Payload = { + "schema_version": string_enum([SUBAGENT_HOST_EXECUTION_RECEIPT_SCHEMA_VERSION]), "bundle_id": dict(opaque_ref), "lane_id": dict(opaque_ref), "goal_id": dict(opaque_ref), "todo_id": dict(opaque_ref), - "execution_kind": { - "type": "string", - "enum": sorted(EXECUTION_KINDS), - }, + "execution_kind": string_enum(EXECUTION_KINDS), "runtime_id": dict(opaque_ref), "worker_ref": dict(opaque_ref), "source_state_ref": dict(opaque_ref), "task_packet_digest": dict(opaque_ref), - "context_mode": { - "type": "string", - "enum": sorted(CHILD_CONTEXT_MODES), - }, - "workspace_ref": nullable_ref, - "status": { - "type": "string", - "enum": sorted(RECEIPT_STATUSES), - }, - "effect_classes": { - "type": "array", - "items": {"type": "string", "enum": sorted(KNOWN_EFFECT_CLASSES)}, - "maxItems": MAX_EFFECT_CLASSES, - }, - "evidence_refs": { - "type": "array", - "items": dict(opaque_ref), - "minItems": 1, - "maxItems": MAX_EVIDENCE_REFS, - }, + "context_mode": string_enum(CHILD_CONTEXT_MODES), + "workspace_ref": {"anyOf": [dict(opaque_ref), {"type": "null"}]}, + "status": string_enum(RECEIPT_STATUSES), + "effect_classes": {"type": "array", "items": string_enum(KNOWN_EFFECT_CLASSES), "maxItems": MAX_EFFECT_CLASSES}, + "evidence_refs": {"type": "array", "items": dict(opaque_ref), "minItems": 1, "maxItems": MAX_EVIDENCE_REFS}, "raw_transcript_copied": {"type": "boolean", "enum": [False]}, } return { @@ -639,112 +454,71 @@ def child_execution_receipts_json_schema() -> dict[str, Any]: } -def normalize_subagent_host_execution_receipts( - value: Any, -) -> list[dict[str, Any]]: +def normalize_subagent_host_execution_receipts(value: object) -> list[Payload]: if value is None: return [] if not isinstance(value, list): raise ValueError("child_execution_receipts must be a list") if len(value) > MAX_CHILD_EXECUTION_RECEIPTS: - raise ValueError( - "child_execution_receipts accepts at most " - f"{MAX_CHILD_EXECUTION_RECEIPTS} items" - ) - receipts: list[dict[str, Any]] = [] + raise ValueError(f"child_execution_receipts accepts at most {MAX_CHILD_EXECUTION_RECEIPTS} items") + receipts: list[Payload] = [] for index, raw in enumerate(value): field = f"child_execution_receipts[{index}]" if not isinstance(raw, Mapping): raise ValueError(f"{field} must be an object") - unknown = sorted(set(raw) - _RECEIPT_FIELDS) + raw_keys = {str(key) for key in raw} + unknown = sorted(raw_keys - _RECEIPT_FIELDS) if unknown: - raise ValueError( - f"{field} contains unsupported fields: {', '.join(unknown)}" - ) - missing = sorted(_RECEIPT_FIELDS - set(raw)) + raise ValueError(f"{field} contains unsupported fields: {', '.join(unknown)}") + missing = sorted(_RECEIPT_FIELDS - raw_keys) if missing: raise ValueError(f"{field} is missing fields: {', '.join(missing)}") - if ( - raw.get("schema_version") - != SUBAGENT_HOST_EXECUTION_RECEIPT_SCHEMA_VERSION - ): + if raw.get("schema_version") != SUBAGENT_HOST_EXECUTION_RECEIPT_SCHEMA_VERSION: raise ValueError(f"{field} has an unsupported schema_version") - execution_kind = str(raw.get("execution_kind") or "").strip() - if execution_kind not in EXECUTION_KINDS: - raise ValueError(f"{field}.execution_kind is unsupported") - context_mode = str(raw.get("context_mode") or "").strip() - if context_mode not in CHILD_CONTEXT_MODES: - raise ValueError(f"{field}.context_mode is unsupported") - status = str(raw.get("status") or "").strip() - if status not in RECEIPT_STATUSES: - raise ValueError(f"{field}.status is unsupported") - raw_transcript_copied = raw.get("raw_transcript_copied") - if raw_transcript_copied is not False: + enums: dict[str, str] = {} + for key, allowed in ( + ("execution_kind", EXECUTION_KINDS), + ("context_mode", CHILD_CONTEXT_MODES), + ("status", RECEIPT_STATUSES), + ): + parsed = str(raw.get(key) or "").strip() + if parsed not in allowed: + raise ValueError(f"{field}.{key} is unsupported") + enums[key] = parsed + if raw.get("raw_transcript_copied") is not False: raise ValueError(f"{field}.raw_transcript_copied must be false") - receipt = { + receipt: Payload = { "schema_version": SUBAGENT_HOST_EXECUTION_RECEIPT_SCHEMA_VERSION, - "bundle_id": _opaque_ref( - raw.get("bundle_id"), - field=f"{field}.bundle_id", - ), + "bundle_id": _opaque_ref(raw.get("bundle_id"), field=f"{field}.bundle_id"), "lane_id": _opaque_ref(raw.get("lane_id"), field=f"{field}.lane_id"), "goal_id": _opaque_ref(raw.get("goal_id"), field=f"{field}.goal_id"), "todo_id": _opaque_ref(raw.get("todo_id"), field=f"{field}.todo_id"), - "execution_kind": execution_kind, - "runtime_id": _opaque_ref( - raw.get("runtime_id"), - field=f"{field}.runtime_id", - ), - "worker_ref": _opaque_ref( - raw.get("worker_ref"), - field=f"{field}.worker_ref", - ), - "source_state_ref": _opaque_ref( - raw.get("source_state_ref"), - field=f"{field}.source_state_ref", - ), - "task_packet_digest": _opaque_ref( - raw.get("task_packet_digest"), - field=f"{field}.task_packet_digest", - ), - "context_mode": context_mode, - "workspace_ref": _opaque_ref( - raw.get("workspace_ref"), - field=f"{field}.workspace_ref", - required=False, - ), - "status": status, + "execution_kind": enums["execution_kind"], + "runtime_id": _opaque_ref(raw.get("runtime_id"), field=f"{field}.runtime_id"), + "worker_ref": _opaque_ref(raw.get("worker_ref"), field=f"{field}.worker_ref"), + "source_state_ref": _opaque_ref(raw.get("source_state_ref"), field=f"{field}.source_state_ref"), + "task_packet_digest": _opaque_ref(raw.get("task_packet_digest"), field=f"{field}.task_packet_digest"), + "context_mode": enums["context_mode"], + "workspace_ref": _opaque_ref(raw.get("workspace_ref"), field=f"{field}.workspace_ref", required=False), + "status": enums["status"], "effect_classes": _opaque_refs( - raw.get("effect_classes"), - field=f"{field}.effect_classes", - limit=MAX_EFFECT_CLASSES, - allowed=KNOWN_EFFECT_CLASSES, + raw.get("effect_classes"), field=f"{field}.effect_classes", + limit=MAX_EFFECT_CLASSES, allowed=KNOWN_EFFECT_CLASSES, ), "evidence_refs": _opaque_refs( - raw.get("evidence_refs"), - field=f"{field}.evidence_refs", - limit=MAX_EVIDENCE_REFS, + raw.get("evidence_refs"), field=f"{field}.evidence_refs", limit=MAX_EVIDENCE_REFS, ), "raw_transcript_copied": False, } validate_public_safe_value( - { - key: item - for key, item in receipt.items() - if key != "raw_transcript_copied" - }, - path=field, + {key: item for key, item in receipt.items() if key != "raw_transcript_copied"}, path=field ) receipts.append(receipt) return receipts def _lane_reason_codes( - *, - topology: Mapping[str, Any], - lane: Mapping[str, Any], - receipt: Mapping[str, Any], - duplicate_count: int, + *, topology: PayloadView, lane: PayloadView, receipt: PayloadView, duplicate_count: int ) -> list[str]: reasons: list[str] = [] if duplicate_count: @@ -761,31 +535,20 @@ def _lane_reason_codes( reasons.append("source_state_stale") if receipt.get("task_packet_digest") != lane.get("task_packet_digest"): reasons.append("task_packet_mismatch") - expected_context_mode = _mapping( - _mapping(lane.get("task_packet")).get("context") - ).get("mode") + expected_context_mode = _mapping(_mapping(lane.get("task_packet")).get("context")).get("mode") if receipt.get("context_mode") != expected_context_mode: reasons.append("context_mode_mismatch") - allowed_effects = set(lane.get("allowed_effect_classes") or []) - if any( - effect not in allowed_effects for effect in receipt.get("effect_classes") or [] - ): + allowed_effects = set(_string_list(lane.get("allowed_effect_classes"))) + if any(effect not in allowed_effects for effect in _string_list(receipt.get("effect_classes"))): reasons.append("side_effect_boundary_exceeded") if receipt.get("status") == "completed" and not receipt.get("evidence_refs"): reasons.append("aggregate_settlement_without_lane_evidence") - if ( - lane.get("workspace_requirement") == "independent_git_worktree" - and receipt.get("workspace_ref") != lane.get("workspace_ref") - ): + if lane.get("workspace_requirement") == "independent_git_worktree" and receipt.get("workspace_ref") != lane.get("workspace_ref"): reasons.append("workspace_mismatch") return sorted(set(reasons)) -def _lane_status( - receipt: Mapping[str, Any] | None, - *, - reason_codes: Sequence[str], -) -> str: +def _lane_status(receipt: PayloadView | None, *, reason_codes: Sequence[str]) -> str: if receipt is None or receipt.get("status") == "running": return "incomplete" if reason_codes: @@ -798,25 +561,18 @@ def _lane_status( def _lane_reconciliation( - *, - topology: Mapping[str, Any], - lane: Mapping[str, Any], - observed: Sequence[Mapping[str, Any]], -) -> tuple[dict[str, Any], list[dict[str, Any]]]: + *, topology: PayloadView, lane: PayloadView, observed: Sequence[PayloadView] +) -> tuple[Payload, list[Payload]]: receipt = observed[0] if observed else None duplicate_receipts = [dict(item) for item in observed[1:]] reason_codes = ( ["worker_receipt_missing"] if receipt is None - else _lane_reason_codes( - topology=topology, - lane=lane, - receipt=receipt, - duplicate_count=len(duplicate_receipts), - ) + else _lane_reason_codes(topology=topology, lane=lane, receipt=receipt, duplicate_count=len(duplicate_receipts)) ) status = _lane_status(receipt, reason_codes=reason_codes) - result = { + quarantined = status in {"drifted", "rejected", "cancelled"} + result: Payload = { "lane_id": str(lane.get("lane_id") or ""), "todo_id": lane.get("todo_id"), "execution_kind": lane.get("execution_kind"), @@ -824,118 +580,79 @@ def _lane_reconciliation( "reason_codes": reason_codes, "receipt_present": receipt is not None, "evidence_disposition": ( - "quarantined" - if status in {"drifted", "rejected", "cancelled"} - else "candidate" - if status == "incomplete" - else "candidate_for_parent_acceptance" + "quarantined" if quarantined else "candidate" if status == "incomplete" else "candidate_for_parent_acceptance" ), "recommended_child_action": ( - "stop_child" - if status in {"drifted", "rejected", "cancelled"} - else "wait_for_child" - if status == "incomplete" - else "return_to_parent" + "stop_child" if quarantined else "wait_for_child" if status == "incomplete" else "return_to_parent" ), "parent_blocked": False, "parent_continuation": "continue", - "fallback_actions": list( - _mapping(_mapping(lane.get("task_packet")).get("guard")).get( - "fallback_actions" - ) - or [] - ), + "fallback_actions": _string_list(_mapping(_mapping(lane.get("task_packet")).get("guard")).get("fallback_actions")), } if receipt is not None: - result.update( - { - "worker_ref": receipt.get("worker_ref"), - "workspace_ref": receipt.get("workspace_ref"), - "effect_classes": list(receipt.get("effect_classes") or []), - ( - "quarantined_evidence_refs" - if status in {"drifted", "rejected", "cancelled"} - else "candidate_evidence_refs" - ): list(receipt.get("evidence_refs") or []), - } - ) + result.update({ + "worker_ref": receipt.get("worker_ref"), + "workspace_ref": receipt.get("workspace_ref"), + "effect_classes": _string_list(receipt.get("effect_classes")), + "quarantined_evidence_refs" if quarantined else "candidate_evidence_refs": _string_list( + receipt.get("evidence_refs") + ), + }) return result, duplicate_receipts -def _orphaned_receipt_projection( - receipt: Mapping[str, Any], - *, - unadmitted: bool, -) -> dict[str, Any]: +def _orphaned_receipt_projection(receipt: PayloadView, *, unadmitted: bool) -> Payload: return { "lane_id": str(receipt.get("lane_id") or "") or None, "worker_ref": receipt.get("worker_ref"), - "reason_codes": ( - ["unadmitted_child_spawn", "orphaned_worker_result"] - if unadmitted - else ["orphaned_worker_result"] - ), + "reason_codes": ["unadmitted_child_spawn", "orphaned_worker_result"] if unadmitted else ["orphaned_worker_result"], "evidence_disposition": "quarantined", "recommended_child_action": "stop_child", "parent_blocked": False, "parent_continuation": "continue", "fallback_actions": list(CHILD_FALLBACK_ACTIONS), - "quarantined_evidence_refs": list(receipt.get("evidence_refs") or []), + "quarantined_evidence_refs": _string_list(receipt.get("evidence_refs")), } def reconcile_subagent_execution( - topology: Mapping[str, Any] | None, - receipts: Sequence[Mapping[str, Any]], -) -> dict[str, Any] | None: + topology: PayloadView | None, receipts: Sequence[PayloadView] +) -> Payload | None: if not topology and not receipts: return None + raw_lanes = (topology or {}).get("lanes") planned_lanes = [ dict(lane) - for lane in (topology or {}).get("lanes") or [] + for lane in (raw_lanes if isinstance(raw_lanes, Iterable) and not isinstance(raw_lanes, (str, bytes, Mapping)) else ()) if isinstance(lane, Mapping) ] - receipts_by_lane: dict[str, list[dict[str, Any]]] = {} + receipts_by_lane: dict[str, list[Payload]] = {} for receipt in receipts: - receipts_by_lane.setdefault(str(receipt.get("lane_id") or ""), []).append( - dict(receipt) - ) - lane_results: list[dict[str, Any]] = [] - status_counts = { - "aligned": 0, - "incomplete": 0, - "rejected": 0, - "cancelled": 0, - "drifted": 0, - } - duplicate_receipts: list[dict[str, Any]] = [] + receipts_by_lane.setdefault(str(receipt.get("lane_id") or ""), []).append(dict(receipt)) + lane_results: list[Payload] = [] + status_counts = {"aligned": 0, "incomplete": 0, "rejected": 0, "cancelled": 0, "drifted": 0} + duplicate_receipts: list[Payload] = [] for lane in planned_lanes: lane_id = str(lane.get("lane_id") or "") observed = receipts_by_lane.pop(lane_id, []) - lane_result, duplicates = _lane_reconciliation( - topology=topology or {}, - lane=lane, - observed=observed, - ) + lane_result, duplicates = _lane_reconciliation(topology=topology or {}, lane=lane, observed=observed) lane_results.append(lane_result) duplicate_receipts.extend(duplicates) status_counts[str(lane_result["status"])] += 1 orphaned_receipts = [ _orphaned_receipt_projection(receipt, unadmitted=True) - for lane_id, lane_receipts in sorted(receipts_by_lane.items()) + for _lane_id, lane_receipts in sorted(receipts_by_lane.items()) for receipt in lane_receipts ] - orphaned_receipts.extend( - _orphaned_receipt_projection(receipt, unadmitted=False) - for receipt in duplicate_receipts - ) + orphaned_receipts.extend(_orphaned_receipt_projection(receipt, unadmitted=False) for receipt in duplicate_receipts) orphaned_count = len(orphaned_receipts) + raw_rejections = (topology or {}).get("pre_spawn_rejections") pre_spawn_rejections = [ dict(item) - for item in (topology or {}).get("pre_spawn_rejections") or [] + for item in (raw_rejections if isinstance(raw_rejections, Iterable) and not isinstance(raw_rejections, (str, bytes, Mapping)) else ()) if isinstance(item, Mapping) ] - payload = { + payload: Payload = { "schema_version": SUBAGENT_CONTROL_PLANE_RECONCILIATION_SCHEMA_VERSION, "bundle_id": (topology or {}).get("bundle_id"), "topology_present": bool(topology), @@ -969,9 +686,7 @@ def reconcile_subagent_execution( "drifted" if status_counts["drifted"] or orphaned_count else "guarded" - if pre_spawn_rejections - or status_counts["rejected"] - or status_counts["cancelled"] + if pre_spawn_rejections or status_counts["rejected"] or status_counts["cancelled"] else "incomplete" if status_counts["incomplete"] else "reconciled" @@ -992,23 +707,15 @@ def reconcile_subagent_execution( def observe_subagent_host_result( - plan: Mapping[str, Any], - result: Mapping[str, Any], - normalized: dict[str, Any], - errors: list[str], + plan: PayloadView, result: PayloadView, normalized: Payload, errors: list[str] ) -> None: try: - receipts = normalize_subagent_host_execution_receipts( - result.get("child_execution_receipts") - ) + receipts = normalize_subagent_host_execution_receipts(result.get("child_execution_receipts")) except ValueError as exc: errors.append(str(exc)) receipts = [] - topology = ( - plan.get("subagent_execution_topology") - if isinstance(plan.get("subagent_execution_topology"), Mapping) - else None - ) + raw_topology = plan.get("subagent_execution_topology") + topology = raw_topology if isinstance(raw_topology, Mapping) else None if receipts: normalized["child_execution_receipts"] = receipts reconciliation = reconcile_subagent_execution(topology, receipts) @@ -1025,14 +732,12 @@ def observe_subagent_host_result( normalized["agent_context"] = context -def subagent_execution_payload_projection( - journal: Mapping[str, Any], -) -> dict[str, Any]: +def subagent_execution_payload_projection(journal: PayloadView) -> Payload: host_result = _mapping(journal.get("host_result")) reconciliation = host_result.get("subagent_reconciliation") if not isinstance(reconciliation, Mapping): return {} - projection = {"subagent_reconciliation": dict(reconciliation)} + projection: Payload = {"subagent_reconciliation": dict(reconciliation)} context = host_result.get("agent_context") if isinstance(context, Mapping): projection["agent_context"] = dict(context)