"""IPC message envelope: schema, versioning, validation. V3 deliberately uses NO network sockets. Internal communication between the background controller, the launcher, and hook processes inside a target project happens through per-session files under /sessions//: status.json - latest process status (atomic replace, JSON) metrics.jsonl - appended performance/GPU metric records (JSON lines) commands.jsonl- controller -> process commands (e.g. graceful stop) session.json - immutable session descriptor written at launch Rationale vs Windows Named Pipes: zero dependencies (no pywin32), survives process crashes (the file IS the state), human-inspectable for diagnostics, and trivially portable for tests. The transport is wrapped behind LocalChannel so a future release can swap in named pipes or a public SDK without touching callers. """ from __future__ import annotations import json import secrets import time from dataclasses import dataclass, asdict, field from typing import Any, Dict, Optional PROTOCOL_VERSION = 1 # V7 protocol extension (additive, backward compatible): # - envelope format is UNCHANGED (protocol stays 1; old readers ignore # unknown command types instead of failing) # - the command allowlist gains the V7 control set used by the Accelerator # server and the trainer-side Integration SDK: # set_parameter - hot-reload/safe-boundary parameter change (with ack) # validate_change - run a controlled A/B window for a level-2 proposal # request_pause / request_resume - only if the trainer supports pause # graceful_stop - finish current batch, checkpoint, exit cleanly # ping - liveness probe (SDK must answer with an ack) V7_COMMANDS = { "set_parameter", "validate_change", "request_pause", "request_resume", "graceful_stop", "ping", } VALID_COMMANDS = {"stop", "gc_cache", "status", "report"} | V7_COMMANDS @dataclass class Envelope: """Every IPC message. `type` selects the payload contract.""" type: str ts: float = field(default_factory=time.time) protocol: int = PROTOCOL_VERSION session_id: Optional[str] = None payload: Dict[str, Any] = field(default_factory=dict) def to_json(self) -> str: return json.dumps(asdict(self), ensure_ascii=False, default=str) @classmethod def from_json(cls, raw: str) -> "Envelope": d = json.loads(raw) if not isinstance(d, dict) or "type" not in d: raise ValueError("invalid envelope: missing 'type'") if int(d.get("protocol", 0)) > PROTOCOL_VERSION: raise ValueError(f"envelope protocol {d.get('protocol')} newer than supported {PROTOCOL_VERSION}") payload = d.get("payload") if payload is not None and not isinstance(payload, dict): raise ValueError("envelope payload must be a mapping") return cls( type=str(d["type"]), ts=float(d.get("ts", time.time())), protocol=int(d.get("protocol", PROTOCOL_VERSION)), session_id=d.get("session_id"), payload=payload or {}, ) def new_session_id() -> str: """Collision-safe session id (timestamp prefix + 48 bits of entropy).""" return f"{int(time.time() * 1000):x}-{secrets.token_hex(6)}" def validate_command(cmd: str) -> bool: return cmd in VALID_COMMANDS