ohm41321/luciazero / skills/lucia-relay
lucia-relay
VerifiedTransfer unfinished work and non-obvious knowledge across sessions, agents, people, machines, or harnesses. Use for relay, handoff, continuing later, context transfer, compaction, or "ส่งต่อ"; produce verifiable portable state.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.4 KB |
| scripts/relay.pyexecutable | script | 61.1 KB |
scripts/relay.py
View on GitHub#!/usr/bin/env python3
"""Create, validate, inspect, render, and consume Lucia Relay artifacts."""
from __future__ import annotations
import argparse
import datetime as dt
import hashlib
import html
import json
import os
from pathlib import Path, PurePosixPath
import re
import shlex
import stat
import subprocess
import sys
import tempfile
from typing import Any, Optional
from urllib.parse import urlsplit, urlunsplit
MANIFEST = "LUCIA_RELAY.json"
HUMAN = "LUCIA_RELAY.md"
RECEIPT = "LUCIA_RELAY_RECEIPT.json"
ENVELOPE_KIND = "luciazero-relay-envelope"
MAX_MANIFEST_BYTES = 1024 * 1024
MAX_ENVELOPE_BYTES = 64 * 1024
MAX_HUMAN_BYTES = 2 * 1024 * 1024
MAX_DEPTH = 20
MAX_NODES = 8192
MAX_STRING_BYTES = 64 * 1024
GIT_TIMEOUT_SECONDS = 30
MAX_GIT_OUTPUT_BYTES = 16 * 1024 * 1024
MAX_UNTRACKED_BYTES = 64 * 1024 * 1024
SHA_RE = re.compile(r"\A[0-9a-f]{40}(?:[0-9a-f]{24})?\Z")
SECRET_PATTERNS = (
re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY(?: BLOCK)?-----"),
re.compile(r"\bsk-[A-Za-z0-9_-]{20,}\b"),
re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"),
re.compile(r"\bAKIA[0-9A-Z]{16}\b"),
re.compile(r"\bnpm_[A-Za-z0-9]{30,}\b"),
re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{20,}\b"),
re.compile(r"\bAIza[0-9A-Za-z_-]{30,}\b"),
re.compile(r"\bglpat-[0-9A-Za-z_-]{20,}\b"),
re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,}\b"),
re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/=-]{20,}\b"),
re.compile(r"(?i)\b(?:aws_secret_access_key|secretaccesskey)\s*[:=]\s*[A-Za-z0-9/+=]{40}\b"),
re.compile(r"(?i)\b(?:https?|ssh|postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis)://[^\s/@:]+:[^\s/@]+@"),
re.compile(r"\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b"),
)
POSIX_ABSOLUTE_PATH = re.compile(
r"(?<![A-Za-z0-9+.\-:/~$%])/(?!/)[^\s\"'`<>]+"
)
WINDOWS_ABSOLUTE_PATH = re.compile(r"(?<![A-Za-z0-9])[A-Za-z]:[\\/][^\s\"'`<>]+")
UNC_PATH = re.compile(r"(?<!\\)\\\\[^\\\s\"'`<>]+\\[^\s\"'`<>]+")
HOME_PATH = re.compile(r"(?<![A-Za-z0-9])(?:~|\$HOME|%USERPROFILE%)[\\/][^\s\"'`<>]+")
FILE_URI_PATH = re.compile(r"\bfile:[^\s\"'`<>]+", re.IGNORECASE)
def git_program() -> Optional[str]:
"""git by its full path on Windows, where a bare name is looked for in
the working directory -- the repository being relayed -- before PATH.
Only PATH's absolute entries are searched, and only for a program: a
batch file would need cmd.exe, which searches the working directory too."""
if sys.platform != "win32":
return "git"
exts = [ext for ext in (os.environ.get("PATHEXT") or ".COM;.EXE").split(";")
if ext.lower() in (".com", ".exe")]
for entry in os.environ.get("PATH", "").split(os.pathsep):
entry = entry.strip().strip('"')
if not os.path.splitdrive(entry)[0] or not os.path.isabs(entry):
continue
for ext in exts:
candidate = os.path.join(entry, "git" + ext)
if os.path.isfile(candidate):
return candidate
return None
def git(root: Path, *args: str) -> tuple[int, str]:
program = git_program()
if program is None:
return 127, ""
git_env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
git_env["GIT_TERMINAL_PROMPT"] = "0"
with tempfile.TemporaryFile() as output:
try:
proc = subprocess.run(
[program, "-C", str(root), *args],
stdin=subprocess.DEVNULL,
stdout=output,
stderr=subprocess.DEVNULL,
check=False,
timeout=GIT_TIMEOUT_SECONDS,
env=git_env,
)
except subprocess.TimeoutExpired:
return 124, ""
size = output.tell()
if size > MAX_GIT_OUTPUT_BYTES:
return 125, ""
output.seek(0)
text = output.read().decode("utf-8", errors="surrogateescape").rstrip("\n")
return proc.returncode, text
def repository_snapshot(root: Path) -> dict[str, Any]:
rc, top = git(root, "rev-parse", "--show-toplevel")
if rc != 0:
return {
"head": None,
"branch": None,
"dirty": None,
"diff_sha256": None,
"known_remote_refs": [],
}
repo = Path(top)
snapshot_errors: list[str] = []
head_rc, head = git(repo, "rev-parse", "HEAD")
_, branch = git(repo, "branch", "--show-current")
# the relay's own files sit in --root, which may be below the top level;
# paths below are the top level's, as git prints them from there
try:
prefix = root.resolve().relative_to(repo.resolve()).as_posix()
except ValueError:
prefix = "."
own = tuple(name if prefix == "." else f"{prefix}/{name}" for name in (MANIFEST, HUMAN, RECEIPT))
exclusions = ("--", ".", *(f":(exclude,literal){name}" for name in own))
# --no-renames: a rename lists the name it left as well as the one it took
if head_rc == 0:
modified_rc, raw_modified = git(repo, "diff", "--name-only", "--no-renames", "-z", "HEAD", *exclusions)
diff_rc, diff = git(repo, "diff", "--binary", "HEAD", *exclusions)
if modified_rc != 0 or diff_rc != 0:
snapshot_errors.append("Git diff failed, timed out, or exceeded its output budget")
else:
staged_names_rc, raw_staged = git(repo, "diff", "--cached", "--name-only", "--no-renames", "-z", *exclusions)
unstaged_names_rc, raw_unstaged = git(repo, "diff", "--name-only", "--no-renames", "-z", *exclusions)
raw_modified = raw_staged + raw_unstaged
staged_diff_rc, staged_diff = git(repo, "diff", "--cached", "--binary", "--root", *exclusions)
unstaged_diff_rc, unstaged_diff = git(repo, "diff", "--binary", *exclusions)
if any(rc != 0 for rc in (staged_names_rc, unstaged_names_rc, staged_diff_rc, unstaged_diff_rc)):
snapshot_errors.append("Git diff failed, timed out, or exceeded its output budget")
diff = staged_diff + "\n" + unstaged_diff
untracked_rc, raw_untracked = git(repo, "ls-files", "--others", "--exclude-standard", "-z")
if untracked_rc != 0:
snapshot_errors.append("Git untracked-file scan failed, timed out, or exceeded its output budget")
modified = sorted(set(item for item in raw_modified.split("\0") if item))
untracked = [
item for item in raw_untracked.split("\0")
if item and item not in own
]
digest = hashlib.sha256(diff.encode("utf-8", errors="surrogateescape"))
untracked_bytes = 0
untracked_budget_exhausted = False
for relative in sorted(untracked):
digest.update(b"\0untracked\0" + relative.encode("utf-8", errors="surrogateescape") + b"\0")
candidate = repo / relative
try:
if candidate.is_symlink():
digest.update(b"symlink\0" + os.readlink(candidate).encode("utf-8", errors="surrogateescape"))
elif candidate.is_file() and not untracked_budget_exhausted:
with candidate.open("rb") as handle:
for chunk in iter(lambda: handle.read(1024 * 1024), b""):
untracked_bytes += len(chunk)
if untracked_bytes > MAX_UNTRACKED_BYTES:
snapshot_errors.append("untracked files exceed the fingerprint byte budget")
untracked_budget_exhausted = True
break
digest.update(chunk)
else:
# FIFOs, sockets, and devices must affect the fingerprint but
# must never be opened: reading a FIFO can block forever and a
# device can have side effects or an unbounded stream.
mode = candidate.lstat().st_mode
digest.update(f"special:{mode}".encode())
except OSError as exc:
digest.update(f"unreadable:{exc.errno}".encode())
fingerprint = digest.hexdigest()
known_remote_refs: list[str] = []
if head_rc == 0:
remote_refs_rc, remote_refs = git(
repo,
"for-each-ref",
"--contains=HEAD",
"--format=%(refname)",
"refs/remotes",
)
if remote_refs_rc != 0:
snapshot_errors.append("Git remote-ref scan failed, timed out, or exceeded its output budget")
known_remote_refs = sorted(
ref[len("refs/remotes/") :]
for ref in remote_refs.splitlines()
if ref.startswith("refs/remotes/") and not ref.endswith("/HEAD")
)
return {
"head": head if head_rc == 0 else None,
"branch": branch or "(detached)",
"dirty": bool(modified or untracked),
"diff_sha256": fingerprint,
"known_remote_refs": known_remote_refs,
"files": {"modified": modified, "untracked": untracked},
"_errors": sorted(set(snapshot_errors)),
}
def sanitize_remote_url(value: str) -> Optional[str]:
value = value.strip()
if not value or value.startswith(("/", "./", "../", "~", "file:")):
return None
if re.fullmatch(r"[A-Za-z0-9._-]+@[A-Za-z0-9.-]+:[A-Za-z0-9._/+~-]+", value):
return value
parsed = urlsplit(value)
if parsed.scheme not in ("https", "ssh") or not parsed.hostname:
return None
user = parsed.username if parsed.scheme == "ssh" else None
host = parsed.hostname
try:
port = parsed.port
except ValueError:
return None
if port:
host = f"{host}:{port}"
netloc = f"{user}@{host}" if user else host
return urlunsplit((parsed.scheme, netloc, parsed.path, "", ""))
def git_url_rewrite_error(root: Path, remote_url: str) -> Optional[str]:
rc, rewrites = git(root, "config", "--get-regexp", r"^url\..*\.(insteadOf|pushInsteadOf)$")
if rc not in (0, 1):
return "cannot safely inspect Git URL rewrite rules"
if rc == 0:
for line in rewrites.splitlines():
parts = line.split(None, 1)
if len(parts) == 2 and remote_url.startswith(parts[1]):
return "Git URL rewrite rules apply to the relay repository"
return None
def git_transport_override_error(root: Path, remote_name: str, remote_url: str) -> Optional[str]:
rewrite_error = git_url_rewrite_error(root, remote_url)
if rewrite_error:
return rewrite_error
for key in (
"core.sshCommand",
f"remote.{remote_name}.uploadpack",
f"remote.{remote_name}.receivepack",
):
rc, value = git(root, "config", "--get-all", key)
if rc not in (0, 1):
return f"cannot safely inspect Git transport override {key}"
if rc == 0 and value:
return f"Git transport override {key} applies to the relay repository"
return None
def remote_snapshot(root: Path, head: str, base: str) -> dict[str, Any]:
rc, upstream = git(root, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}")
if rc != 0 or "/" not in upstream:
raise ValueError("cross-machine draft requires a configured upstream branch")
remote_name, branch = upstream.split("/", 1)
remote_ref = f"refs/heads/{branch}"
rc, remote_urls = git(root, "config", "--get-all", f"remote.{remote_name}.url")
configured_urls = [value for value in remote_urls.splitlines() if value]
if rc != 0 or len(configured_urls) != 1:
raise ValueError("cross-machine draft requires exactly one upstream remote URL")
remote_url = configured_urls[0]
sanitized_url = sanitize_remote_url(remote_url)
if sanitized_url is None:
raise ValueError("cross-machine draft requires a portable HTTPS or SSH upstream URL")
rc, push_urls = git(root, "config", "--get-all", f"remote.{remote_name}.pushurl")
if rc not in (0, 1):
raise ValueError("cross-machine draft cannot safely inspect remote push URLs")
if rc == 0 and push_urls:
raise ValueError("cross-machine draft rejects a separate remote push URL")
transport_error = git_transport_override_error(root, remote_name, remote_url)
if transport_error:
raise ValueError(f"cross-machine draft rejects its upstream: {transport_error}")
rc, remote_lines = git(root, "ls-remote", "--exit-code", remote_name, remote_ref)
if rc != 0:
raise ValueError("cross-machine draft cannot verify the upstream ref; push it first")
remote_oid = next(
(line.split("\t", 1)[0] for line in remote_lines.splitlines() if line.endswith("\t" + remote_ref)),
"",
)
if remote_oid != head:
raise ValueError("cross-machine draft HEAD is not the current remote ref; push it first")
transfer_ref = f"refs/tags/lucia-relay-{head}"
rc, transfer_lines = git(root, "ls-remote", remote_name, transfer_ref)
if rc != 0:
raise ValueError("cross-machine draft cannot safely inspect its transfer tag")
transfer_oid = next(
(line.split("\t", 1)[0] for line in transfer_lines.splitlines() if line.endswith("\t" + transfer_ref)),
"",
)
if transfer_oid and transfer_oid != head:
raise ValueError("cross-machine commit-named transfer tag points at another commit")
if not transfer_oid:
rc, _ = git(root, "push", "--porcelain", remote_name, f"{head}:{transfer_ref}")
if rc != 0:
raise ValueError("cross-machine draft could not publish its transfer tag")
rc, transfer_lines = git(root, "ls-remote", "--exit-code", remote_name, transfer_ref)
transfer_oid = next(
(line.split("\t", 1)[0] for line in transfer_lines.splitlines() if line.endswith("\t" + transfer_ref)),
"",
) if rc == 0 else ""
if transfer_oid != head:
raise ValueError("cross-machine transfer ref was not published at HEAD")
rc, base_oid = git(root, "rev-parse", f"{base}^{{commit}}")
if rc != 0 or not SHA_RE.fullmatch(base_oid):
raise ValueError("cross-machine --base must resolve to a commit")
rc, _ = git(root, "merge-base", "--is-ancestor", base_oid, head)
if rc != 0:
raise ValueError("cross-machine --base must be an ancestor of HEAD")
rc, changed = git(root, "diff", "--name-only", "-z", "--no-renames", base_oid, head, "--")
if rc != 0:
raise ValueError("cross-machine draft could not list committed task files")
changed_files = sorted(item for item in changed.split("\0") if item)
return {
"url": sanitized_url,
"name": remote_name,
"ref": transfer_ref,
"oid": transfer_oid,
"source_ref": remote_ref,
"base": base_oid,
"changed_files": changed_files,
}
def envelope_remote_errors(root: Path, data: dict[str, Any]) -> list[str]:
repository = data.get("repository") if isinstance(data.get("repository"), dict) else {}
remote = repository.get("remote") if isinstance(repository.get("remote"), dict) else {}
name, expected_url, ref, oid = (
remote.get("name"), remote.get("url"), remote.get("ref"), remote.get("oid")
)
if not all(nonempty(value) for value in (name, expected_url, ref, oid)):
return ["trusted envelope lacks complete remote metadata"]
rc, configured_urls = git(root, "config", "--get-all", f"remote.{name}.url")
urls = [value for value in configured_urls.splitlines() if value]
if rc != 0 or len(urls) != 1 or sanitize_remote_url(urls[0]) != expected_url:
return ["trusted envelope repository URL no longer matches configured upstream"]
configured_url = urls[0]
transport_error = git_transport_override_error(root, str(name), configured_url)
if transport_error:
return [f"trusted envelope rejects repository transport: {transport_error}"]
rc, push_urls = git(root, "config", "--get-all", f"remote.{name}.pushurl")
if rc not in (0, 1):
return ["trusted envelope cannot safely inspect remote push URLs"]
if rc == 0 and push_urls:
return ["trusted envelope rejects a separate remote push URL"]
rc, remote_lines = git(root, "ls-remote", "--exit-code", str(name), str(ref))
if rc != 0:
return ["trusted envelope cannot reach its recorded remote ref"]
live_oid = next(
(line.split("\t", 1)[0] for line in remote_lines.splitlines() if line.endswith("\t" + str(ref))),
"",
)
if live_oid != oid or oid != repository.get("head"):
return ["trusted envelope remote ref no longer resolves to its recorded HEAD"]
return []
def draft(root: Path, recipient: str, base: Optional[str] = None) -> dict[str, Any]:
snap = repository_snapshot(root)
snapshot_errors = snap.pop("_errors", [])
files = snap.pop("files", {"modified": [], "untracked": []})
schema = 2
if recipient == "cross-machine":
if not base:
raise ValueError("cross-machine draft requires --base <task-base-revision>")
if snapshot_errors:
raise ValueError("; ".join(snapshot_errors))
if snap.get("head") is None or snap.get("dirty") is not False:
raise ValueError("cross-machine draft requires a clean committed worktree")
remote = remote_snapshot(root, str(snap["head"]), base)
snap["remote"] = {
key: remote[key] for key in ("url", "name", "ref", "oid", "source_ref")
}
snap["base"] = remote["base"]
snap["changed_files"] = remote["changed_files"]
files = {"modified": [], "untracked": []}
schema = 3
return {
"schema": schema,
"kind": "luciazero-relay",
"created_at": dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds"),
"route": {"recipient": recipient},
"source": {
"harness": os.environ.get("LUCIAZERO_HARNESS", "unknown"),
"agent": None,
"session": None,
},
"repository": snap,
"goal": "",
"state": {
"done": [],
"in_progress": [],
"next_step": {"kind": "command", "value": ""},
},
"verification": [],
"knowledge": {"read_first": [], "inline": [], "hypotheses": [], "landmines": []},
"files": files,
}
def structure_errors(value: Any) -> list[str]:
errors: list[str] = []
stack = [(value, 0)]
nodes = 0
while stack:
item, depth = stack.pop()
nodes += 1
if nodes > MAX_NODES:
return [f"artifact exceeds {MAX_NODES} values"]
if depth > MAX_DEPTH:
return [f"artifact exceeds nesting depth {MAX_DEPTH}"]
if isinstance(item, str):
try:
encoded = item.encode("utf-8")
except UnicodeEncodeError:
errors.append("artifact contains invalid Unicode surrogate data")
continue
if len(encoded) > MAX_STRING_BYTES:
errors.append(f"artifact string exceeds {MAX_STRING_BYTES} bytes")
elif isinstance(item, dict):
stack.extend((key, depth + 1) for key in item.keys())
stack.extend((nested, depth + 1) for nested in item.values())
elif isinstance(item, list):
stack.extend((nested, depth + 1) for nested in item)
return errors
def load_json_object(path: Path, label: str, max_bytes: int = MAX_MANIFEST_BYTES) -> dict[str, Any]:
if path.is_symlink():
raise ValueError(f"{label} must not be a symlink")
try:
info = path.stat()
if not stat.S_ISREG(info.st_mode):
raise ValueError(f"{label} must be a regular file")
if info.st_size > max_bytes:
raise ValueError(f"{label} exceeds {max_bytes} bytes")
value = json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError as exc:
raise ValueError(f"{label} does not exist") from exc
except (OSError, json.JSONDecodeError, RecursionError) as exc:
raise ValueError(f"cannot read {label}: {exc}") from exc
if not isinstance(value, dict):
raise ValueError(f"{label} must contain a JSON object")
limits = structure_errors(value)
if limits:
raise ValueError(f"{label} {limits[0]}")
return value
def load_manifest(root: Path) -> dict[str, Any]:
path = root / MANIFEST
return load_json_object(path, MANIFEST)
def read_bounded_text(path: Path, label: str, max_bytes: int) -> str:
if path.is_symlink():
raise ValueError(f"{label} must not be a symlink")
try:
info = path.stat()
if not stat.S_ISREG(info.st_mode):
raise ValueError(f"{label} must be a regular file")
if info.st_size > max_bytes:
raise ValueError(f"{label} exceeds {max_bytes} bytes")
return path.read_text(encoding="utf-8")
except FileNotFoundError as exc:
raise ValueError(f"{label} does not exist") from exc
except (OSError, UnicodeError) as exc:
raise ValueError(f"cannot read {label}: {exc}") from exc
def nonempty(value: Any) -> bool:
return isinstance(value, str) and bool(value.strip())
def string_values(value: Any):
stack = [value]
while stack:
item = stack.pop()
if isinstance(item, str):
yield item
elif isinstance(item, dict):
stack.extend(item.values())
elif isinstance(item, list):
stack.extend(item)
def machine_paths(data: dict[str, Any]) -> list[str]:
found: set[str] = set()
for value in string_values(data):
for pattern in (
POSIX_ABSOLUTE_PATH,
WINDOWS_ABSOLUTE_PATH,
UNC_PATH,
HOME_PATH,
FILE_URI_PATH,
):
found.update(match.group(0) for match in pattern.finditer(value))
return sorted(found)
def repo_pointer(value: Any) -> Optional[str]:
if not nonempty(value):
return None
# A short annotation may follow the path, as in
# "docs/lessons.md — quoted delimiters are parser syntax".
candidate = str(value).split(" — ", 1)[0].strip()
path = PurePosixPath(candidate)
if (
not candidate
or "\\" in candidate
or ":" in candidate
or path.is_absolute()
or any(part in ("", ".", "..") for part in path.parts)
):
return None
return candidate
def safe_command_argv(value: Any) -> Optional[list[str]]:
if not nonempty(value) or any(char in str(value) for char in "\r\n"):
return None
try:
argv = shlex.split(str(value))
except ValueError:
return None
# an operator glued to a word (`test;id`, `$(id)`, `>out`) is still one a
# shell would act on, so any token holding one is refused
if not argv or any(char in token for token in argv for char in ";|&<>`$"):
return None
executable = PurePosixPath(argv[0].replace("\\", "/")).name.casefold()
if executable in {"sh", "bash", "zsh", "fish", "cmd", "cmd.exe", "powershell", "pwsh", "env", "xargs"}:
return None
if executable == "git" and any(token == "-c" or token.startswith("--config-env=") for token in argv[1:]):
return None
if executable in {"python", "python3", "node", "ruby", "perl"} and any(
token in ("-c", "-e", "--eval") for token in argv[1:]
):
return None
return argv
def repository_path_error(root: Path, head: str, path: str, base: Optional[str] = None) -> Optional[str]:
if repo_pointer(path) != path:
return f"must be one contained repo-relative path: {path}"
if not SHA_RE.fullmatch(head) or (base is not None and not SHA_RE.fullmatch(base)):
return "cannot be checked without valid immutable repository OIDs"
refs = [head] + ([base] if nonempty(base) else [])
saw_entry = False
for ref in refs:
rc, entry = git(root, "ls-tree", str(ref), "--", path)
if rc != 0 or not entry:
continue
saw_entry = True
metadata = entry.split("\t", 1)[0].split()
if len(metadata) < 2 or metadata[1] != "blob" or metadata[0] == "120000":
return f"must resolve to a regular tracked blob: {path}"
return None
if not saw_entry:
return f"is not present in the relay base or HEAD: {path}"
return None
def cross_machine_repository_errors(root: Path, data: dict[str, Any]) -> list[str]:
route = data.get("route") if isinstance(data.get("route"), dict) else {}
if route.get("recipient") != "cross-machine":
return []
repository = data.get("repository") if isinstance(data.get("repository"), dict) else {}
head = repository.get("head")
base = repository.get("base")
knowledge = data.get("knowledge") if isinstance(data.get("knowledge"), dict) else {}
read_first = knowledge.get("read_first")
if not isinstance(read_first, list):
return []
errors: list[str] = []
for index, item in enumerate(read_first):
path = repo_pointer(item)
if path is None:
errors.append(
f"knowledge.read_first[{index}] must start with one repo-relative path; move prose or local knowledge to knowledge.inline"
)
continue
if not nonempty(head):
errors.append(f"knowledge.read_first[{index}] cannot be checked without repository.head")
continue
problem = repository_path_error(root, str(head), path)
if problem:
errors.append(f"knowledge.read_first[{index}] {problem}")
changed = repository.get("changed_files")
if isinstance(changed, list):
for index, item in enumerate(changed):
if not isinstance(item, str):
continue
problem = repository_path_error(root, str(head), item, str(base) if nonempty(base) else None)
if problem:
errors.append(f"repository.changed_files[{index}] {problem}")
return errors
def receiver_repository_url_error(root: Path, trusted_url: str) -> Optional[str]:
rc, names = git(root, "remote")
if rc != 0:
return "receiver cannot inspect configured Git remotes"
for name in names.splitlines():
rc, configured_values = git(root, "config", "--get-all", f"remote.{name}.url")
configured = [value for value in configured_values.splitlines() if value]
if rc == 0 and configured == [trusted_url]:
transport_error = git_transport_override_error(root, name, trusted_url)
if transport_error:
return f"receiver rejects trusted repository transport: {transport_error}"
push_rc, push_urls = git(root, "config", "--get-all", f"remote.{name}.pushurl")
if push_rc not in (0, 1):
return "receiver cannot safely inspect trusted remote push URLs"
if push_rc == 0 and push_urls:
return "receiver trusted Git remote has a separate push URL"
return None
return "receiver clone has no Git remote matching the trusted repository URL"
def validate(data: dict[str, Any]) -> tuple[list[str], list[str]]:
errors: list[str] = []
warnings: list[str] = []
schema = data.get("schema")
if type(schema) is not int or schema not in (1, 2, 3):
errors.append("schema must equal 1, 2, or 3")
if data.get("kind") != "luciazero-relay":
errors.append("kind must equal luciazero-relay")
recipient = None
route = data.get("route")
if schema in (2, 3):
if not isinstance(route, dict):
errors.append("route must be an object")
else:
recipient = route.get("recipient")
if recipient not in ("same-machine", "cross-machine"):
errors.append("route.recipient must be same-machine or cross-machine")
elif schema == 1:
warnings.append(
"legacy schema 1 has no recipient location; treat it as same-machine and create a new relay before routing cross-machine"
)
if not nonempty(data.get("created_at")):
errors.append("created_at is required")
else:
try:
created = dt.datetime.fromisoformat(str(data["created_at"]).replace("Z", "+00:00"))
if created.tzinfo is None:
errors.append("created_at must include a timezone")
except ValueError:
errors.append("created_at must be ISO-8601")
if not nonempty(data.get("goal")):
errors.append("goal is required")
state = data.get("state")
if not isinstance(state, dict):
errors.append("state must be an object")
else:
for key in ("done", "in_progress"):
if not isinstance(state.get(key), list):
errors.append(f"state.{key} must be an array")
next_step = state.get("next_step")
if not isinstance(next_step, dict):
errors.append("state.next_step must be an object")
else:
if next_step.get("kind") not in ("command", "edit", "decision"):
errors.append("state.next_step.kind must be command, edit, or decision")
if not nonempty(next_step.get("value")):
errors.append("state.next_step.value must be one literal next action")
verification = data.get("verification")
if not isinstance(verification, list):
errors.append("verification must be an array")
else:
for index, item in enumerate(verification):
prefix = f"verification[{index}]"
if not isinstance(item, dict):
errors.append(f"{prefix} must be an object")
continue
if not nonempty(item.get("command")):
errors.append(f"{prefix}.command is required")
elif schema == 3 and recipient == "cross-machine" and safe_command_argv(item.get("command")) is None:
errors.append(f"{prefix}.command must be one argv-safe command without shell operators")
if not isinstance(item.get("exit_code"), int):
errors.append(f"{prefix}.exit_code must be an integer")
if not nonempty(item.get("decisive_line")):
errors.append(f"{prefix}.decisive_line is required")
if not nonempty(item.get("run_at")):
errors.append(f"{prefix}.run_at is required")
else:
try:
run_at = dt.datetime.fromisoformat(str(item["run_at"]).replace("Z", "+00:00"))
if run_at.tzinfo is None:
errors.append(f"{prefix}.run_at must include a timezone")
except ValueError:
errors.append(f"{prefix}.run_at must be ISO-8601")
knowledge = data.get("knowledge")
if not isinstance(knowledge, dict):
errors.append("knowledge must be an object")
else:
for key in ("read_first", "hypotheses", "landmines"):
if not isinstance(knowledge.get(key), list):
errors.append(f"knowledge.{key} must be an array")
inline = knowledge.get("inline")
if schema in (2, 3) and not isinstance(inline, list):
errors.append("knowledge.inline must be an array")
elif isinstance(inline, list):
for index, item in enumerate(inline):
prefix = f"knowledge.inline[{index}]"
if not isinstance(item, dict):
errors.append(f"{prefix} must be an object")
continue
if not nonempty(item.get("label")) or not nonempty(item.get("content")):
errors.append(f"{prefix} requires label and content")
hypotheses = knowledge.get("hypotheses")
if isinstance(hypotheses, list):
for index, item in enumerate(hypotheses):
prefix = f"knowledge.hypotheses[{index}]"
if not isinstance(item, dict):
errors.append(f"{prefix} must be an object")
continue
if not all(nonempty(item.get(key)) for key in ("id", "claim", "evidence")):
errors.append(f"{prefix} requires id, claim, and evidence")
if item.get("status") not in ("untested", "supported", "refuted"):
errors.append(f"{prefix}.status must be untested, supported, or refuted")
source = data.get("source")
if not isinstance(source, dict) or not nonempty(source.get("harness")):
errors.append("source.harness is required")
repository = data.get("repository")
if not isinstance(repository, dict):
errors.append("repository must be an object")
else:
for key in ("head", "branch", "dirty", "diff_sha256"):
if key not in repository:
errors.append(f"repository.{key} is required")
if schema in (2, 3):
known_remote_refs = repository.get("known_remote_refs")
if not isinstance(known_remote_refs, list):
errors.append("repository.known_remote_refs must be an array")
elif not all(nonempty(ref) for ref in known_remote_refs):
errors.append("repository.known_remote_refs entries must be non-empty strings")
if schema == 3:
base = repository.get("base")
changed_files = repository.get("changed_files")
remote = repository.get("remote")
if not nonempty(base) or not SHA_RE.fullmatch(str(base)):
errors.append("repository.base must be an immutable commit OID")
if not isinstance(changed_files, list) or not all(
isinstance(path, str) and repo_pointer(path) == path for path in changed_files
):
errors.append("repository.changed_files must contain repo-relative paths")
if not isinstance(remote, dict):
errors.append("repository.remote must be an object")
else:
url = remote.get("url")
if not nonempty(url) or sanitize_remote_url(str(url)) != url:
errors.append("repository.remote.url must be a sanitized portable HTTPS or SSH URL")
if not nonempty(remote.get("name")):
errors.append("repository.remote.name is required")
if not nonempty(remote.get("ref")) or not str(remote.get("ref")).startswith(("refs/heads/", "refs/tags/")):
errors.append("repository.remote.ref must be a full heads/tags ref")
if not nonempty(remote.get("source_ref")) or not str(remote.get("source_ref")).startswith("refs/heads/"):
errors.append("repository.remote.source_ref must be a full branch ref")
if not nonempty(remote.get("oid")) or not SHA_RE.fullmatch(str(remote.get("oid"))):
errors.append("repository.remote.oid must be an immutable commit OID")
if remote.get("oid") != repository.get("head"):
errors.append("repository.remote.oid must equal repository.head")
files = data.get("files")
if not isinstance(files, dict):
errors.append("files must be an object")
else:
for key in ("modified", "untracked"):
if not isinstance(files.get(key), list):
errors.append(f"files.{key} must be an array")
elif not all(isinstance(path, str) and repo_pointer(path) == path for path in files.get(key)):
errors.append(f"files.{key} must contain repo-relative paths")
serialized = json.dumps(data, ensure_ascii=False)
if any(pattern.search(serialized) for pattern in SECRET_PATTERNS):
errors.append("possible secret or private key detected; remove it before routing")
local_paths = machine_paths(data)
if schema == 3 and recipient != "cross-machine":
errors.append("schema 3 route.recipient must be cross-machine")
if recipient == "cross-machine" or schema == 3:
if schema != 3:
errors.append("cross-machine relay requires schema 3; re-draft it after push")
if local_paths:
errors.append(
"cross-machine relay contains machine-only paths: "
+ ", ".join(local_paths[:3])
+ (" ..." if len(local_paths) > 3 else "")
+ "; use pushed repo-relative paths or copy the knowledge into knowledge.inline"
)
if isinstance(repository, dict):
if repository.get("dirty") is True:
errors.append(
"cross-machine relay cannot depend on a dirty worktree; commit and push task files, then keep machine-local knowledge in knowledge.inline"
)
if schema == 3 and isinstance(files, dict) and (files.get("modified") or files.get("untracked")):
errors.append("cross-machine schema 3 files.modified/untracked must be empty after commit")
if not isinstance(verification, list) or not verification:
errors.append("cross-machine relay requires at least one verification entry")
if isinstance(knowledge, dict) and not any(
knowledge.get(key) for key in ("read_first", "inline", "hypotheses", "landmines")
):
errors.append("cross-machine relay requires portable knowledge")
elif schema == 1 and local_paths:
warnings.append("legacy relay contains a machine-specific path and is not portable cross-machine")
return errors, warnings
def markdown_text(value: Any) -> str:
"""Render untrusted text as Markdown text, never as Markdown structure."""
escaped = html.escape(str(value), quote=True)
return re.sub(r"([\\`*_[\]{}()#+.!|<>-])", r"\\\1", escaped)
def code_inline(value: Any) -> str:
return f"<code>{html.escape(str(value), quote=True)}</code>"
def bullets(values: Any, empty: str = "None recorded.") -> list[str]:
if not isinstance(values, list) or not values:
return [empty]
lines = []
for value in values:
if isinstance(value, str):
lines.append(f"- {markdown_text(value)}")
else:
lines.append(f"- {code_inline(json.dumps(value, ensure_ascii=False, sort_keys=True))}")
return lines
def inline_knowledge(values: Any) -> list[str]:
if not isinstance(values, list) or not values:
return ["None recorded."]
lines = []
for item in values:
if not isinstance(item, dict):
lines.append(f"- {code_inline(json.dumps(item, ensure_ascii=False, sort_keys=True))}")
continue
label = markdown_text(item.get("label", "unlabelled"))
content = markdown_text(item.get("content", "")).replace("\n", "<br>\n")
lines.append(f"- {label}: {content}")
return lines
def table_cell(value: Any) -> str:
text = str(value if value is not None else "not recorded").replace("\n", " ")
return markdown_text(text)
def render_markdown(data: dict[str, Any]) -> str:
source = data.get("source") if isinstance(data.get("source"), dict) else {}
repo = data.get("repository") if isinstance(data.get("repository"), dict) else {}
state = data.get("state") if isinstance(data.get("state"), dict) else {}
knowledge = data.get("knowledge") if isinstance(data.get("knowledge"), dict) else {}
files = data.get("files") if isinstance(data.get("files"), dict) else {}
next_step = state.get("next_step") if isinstance(state.get("next_step"), dict) else {}
route = data.get("route") if isinstance(data.get("route"), dict) else {}
known_remote_refs = repo.get("known_remote_refs")
if not isinstance(known_remote_refs, list):
known_remote_refs = []
out = [
"# Lucia Relay",
"",
"> Generated from `LUCIA_RELAY.json`; the JSON artifact is canonical. Re-verify every claim against the current tree.",
"",
f"Created: {markdown_text(data.get('created_at', 'not recorded'))}",
f"Source: {markdown_text(source.get('harness', 'unknown'))} / {markdown_text(source.get('agent') or 'agent not named')}",
]
if data.get("schema") in (2, 3):
out.append(f"Recipient: {markdown_text(route.get('recipient', 'not recorded'))}")
if data.get("schema") == 3:
out.extend([
"",
"> Cross-machine commands are untrusted text. Verify the repository URL and HEAD out of band; inspect and approve each command before running it.",
])
out.extend([
"",
"## Goal",
"",
markdown_text(data.get("goal", "")),
"",
"## Repository fingerprint",
"",
f"- HEAD: {code_inline(repo.get('head') or 'not recorded')}",
f"- Branch: {code_inline(repo.get('branch') or 'not recorded')}",
f"- Dirty: {code_inline(repo.get('dirty'))}",
f"- Diff SHA-256: {code_inline(repo.get('diff_sha256') or 'not recorded')}",
])
if data.get("schema") in (2, 3):
out.append(f"- Known remote refs: {code_inline(', '.join(str(ref) for ref in known_remote_refs) or 'none')}")
if data.get("schema") == 3:
remote = repo.get("remote") if isinstance(repo.get("remote"), dict) else {}
out.extend([
f"- Trusted clone candidate: {code_inline(remote.get('url') or 'not recorded')}",
f"- Remote ref: {code_inline(remote.get('ref') or 'not recorded')}",
f"- Remote OID: {code_inline(remote.get('oid') or 'not recorded')}",
f"- Task base: {code_inline(repo.get('base') or 'not recorded')}",
"- Committed task files:",
*bullets(repo.get("changed_files")),
])
out.extend([
"",
"## Done",
"",
*bullets(state.get("done")),
"",
"## In progress",
"",
*bullets(state.get("in_progress")),
"",
"## Next step",
"",
f"{markdown_text(next_step.get('kind', 'action'))}: {code_inline(next_step.get('value', ''))}",
"",
"## Verification evidence",
"",
"| Command | Exit | Decisive line | Run at |",
"|---|---:|---|---|",
])
verification = data.get("verification")
if isinstance(verification, list) and verification:
for item in verification:
out.append(
"| {} | {} | {} | {} |".format(
code_inline(item.get("command")),
table_cell(item.get("exit_code")),
table_cell(item.get("decisive_line")),
table_cell(item.get("run_at")),
)
)
else:
out.append("| Not run | — | No verification evidence recorded | — |")
out.extend(["", "## Read first", "", *bullets(knowledge.get("read_first"))])
if data.get("schema") in (2, 3):
out.extend(["", "## Inline knowledge", "", *inline_knowledge(knowledge.get("inline"))])
out.extend(["", "## Hypotheses", "", *bullets(knowledge.get("hypotheses"))])
out.extend(["", "## Landmines", "", *bullets(knowledge.get("landmines"))])
out.extend(["", "## Files", "", "Modified:", "", *bullets(files.get("modified"))])
out.extend(["", "Untracked:", "", *bullets(files.get("untracked")), ""])
return "\n".join(out)
def inspect(
root: Path,
data: dict[str, Any],
check_human: bool = False,
expected_recipient: Optional[str] = None,
trusted_head: Optional[str] = None,
trusted_manifest_sha256: Optional[str] = None,
trusted_repository_url: Optional[str] = None,
receiver_context: bool = False,
) -> dict[str, Any]:
errors, warnings = validate(data)
if check_human:
human = root / HUMAN
try:
actual = read_bounded_text(human, HUMAN, MAX_HUMAN_BYTES)
except ValueError as exc:
errors.append(str(exc))
else:
if actual != render_markdown(data):
errors.append(f"{HUMAN} does not match {MANIFEST}; regenerate it before trusting or consuming the relay")
current = repository_snapshot(root)
for snapshot_error in current.pop("_errors", []):
errors.append(snapshot_error)
errors.extend(cross_machine_repository_errors(root, data))
recorded = data.get("repository") if isinstance(data.get("repository"), dict) else {}
route = data.get("route") if isinstance(data.get("route"), dict) else {}
recipient = route.get("recipient")
trust_required = False
cross_receiver = receiver_context and (data.get("schema") == 3 or recipient == "cross-machine")
if cross_receiver and expected_recipient is None:
errors.append("receiver must declare --expected-recipient cross-machine")
trust_required = True
if expected_recipient is not None and recipient != expected_recipient:
errors.append(
f"receiver expected recipient {expected_recipient}, artifact declares {recipient or 'none'}"
)
if receiver_context and (expected_recipient == "cross-machine" or data.get("schema") == 3):
if data.get("schema") != 3:
errors.append("receiver refuses legacy schema for cross-machine transfer")
if not nonempty(trusted_head) or not SHA_RE.fullmatch(str(trusted_head)):
errors.append("receiver must supply --trusted-head from a trusted channel")
trust_required = True
elif recorded.get("head") != trusted_head:
errors.append("artifact HEAD does not match receiver-supplied trusted HEAD")
if not nonempty(trusted_manifest_sha256) or not re.fullmatch(
r"[0-9a-f]{64}", str(trusted_manifest_sha256)
):
errors.append("receiver must supply --trusted-manifest-sha256 from a trusted channel")
trust_required = True
else:
try:
actual_digest = manifest_sha256(root)
except ValueError as exc:
errors.append(str(exc))
else:
if actual_digest != trusted_manifest_sha256:
errors.append("artifact does not match receiver-supplied trusted manifest digest")
recorded_remote = recorded.get("remote") if isinstance(recorded.get("remote"), dict) else {}
if not nonempty(trusted_repository_url) or sanitize_remote_url(str(trusted_repository_url)) != trusted_repository_url:
errors.append("receiver must supply --trusted-repository-url from a trusted channel")
trust_required = True
elif recorded_remote.get("url") != trusted_repository_url:
errors.append("artifact repository URL does not match receiver-supplied trusted URL")
else:
remote_error = receiver_repository_url_error(root, str(trusted_repository_url))
if remote_error:
errors.append(remote_error)
if route.get("recipient") == "cross-machine":
if current.get("dirty") is True:
errors.append("current cross-machine worktree is dirty; create a fresh relay after committing")
compared = ("head", "dirty", "diff_sha256") if data.get("schema") == 3 and recipient == "cross-machine" \
else ("head", "branch", "dirty", "diff_sha256")
drift_fields = [key for key in compared if recorded.get(key) != current.get(key)]
if route.get("recipient") == "cross-machine" and drift_fields:
errors.append(
"cross-machine relay repository fingerprint is stale; create a fresh relay from the clean pushed tree"
)
age_days = None
try:
created = dt.datetime.fromisoformat(str(data.get("created_at", "")).replace("Z", "+00:00"))
age_days = max(0, (dt.datetime.now(dt.timezone.utc) - created.astimezone(dt.timezone.utc)).days)
except (ValueError, TypeError):
pass
state = data.get("state") if isinstance(data.get("state"), dict) else {}
return {
"valid": not errors,
"errors": errors,
"warnings": warnings,
"age_days": age_days,
"repository_drift": bool(drift_fields),
"drift_fields": drift_fields,
"recorded_repository": recorded,
"current_repository": current,
"next_step": state.get("next_step"),
"trust_required": trust_required,
"recipient": (
data.get("route", {}).get("recipient")
if isinstance(data.get("route"), dict)
else "legacy / same-machine only"
),
}
def manifest_sha256(root: Path) -> str:
path = root / MANIFEST
if path.is_symlink():
raise ValueError(f"{MANIFEST} must not be a symlink")
try:
info = path.stat()
if not stat.S_ISREG(info.st_mode):
raise ValueError(f"{MANIFEST} must be a regular file")
if info.st_size > MAX_MANIFEST_BYTES:
raise ValueError(f"{MANIFEST} exceeds {MAX_MANIFEST_BYTES} bytes")
payload = path.read_bytes()
except FileNotFoundError as exc:
raise ValueError(f"{MANIFEST} does not exist") from exc
except OSError as exc:
raise ValueError(f"cannot read {MANIFEST}: {exc}") from exc
return hashlib.sha256(payload).hexdigest()
def outside_root_error(root: Path, path: Path, label: str) -> Optional[str]:
"""A file under the relay root travelled with the artifact, so it is not
a trusted channel and must not be produced or consumed as one."""
try:
resolved = path.resolve()
except OSError as exc:
return f"cannot resolve {label}: {exc}"
if resolved == root or root in resolved.parents:
return f"{label} must live outside the relay root {root}"
return None
def refuse_existing_manifest(root: Path) -> None:
path = root / MANIFEST
if path.is_symlink() or path.exists():
raise ValueError(f"{MANIFEST} already exists; consume or remove it before drafting a new relay")
def write_manifest(root: Path, data: dict[str, Any]) -> Path:
path = root / MANIFEST
refuse_existing_manifest(root)
try:
# Exclusive create: a symlink planted between the check and the write
# fails here instead of being followed.
with path.open("x", encoding="utf-8") as handle:
handle.write(json.dumps(data, ensure_ascii=False, indent=2) + "\n")
except FileExistsError as exc:
raise ValueError(f"{MANIFEST} already exists; consume or remove it before drafting a new relay") from exc
except OSError as exc:
raise ValueError(f"cannot write {MANIFEST}: {exc}") from exc
return path
def write_human(root: Path, data: dict[str, Any]) -> Path:
human = root / HUMAN
if human.is_symlink():
raise ValueError(f"{HUMAN} must not be a symlink")
try:
human.write_text(render_markdown(data), encoding="utf-8")
except OSError as exc:
raise ValueError(f"cannot write {HUMAN}: {exc}") from exc
return human
def envelope_payload(root: Path, data: dict[str, Any]) -> dict[str, Any]:
repository = data.get("repository") if isinstance(data.get("repository"), dict) else {}
remote = repository.get("remote") if isinstance(repository.get("remote"), dict) else {}
return {
"schema": 1,
"kind": ENVELOPE_KIND,
"repository_url": remote.get("url"),
"remote_ref": remote.get("ref"),
"trusted_head": repository.get("head"),
"trusted_manifest_sha256": manifest_sha256(root),
}
def write_envelope(root: Path, payload: dict[str, Any], out: Path) -> Path:
problem = outside_root_error(root, out, "--envelope-out")
if problem:
raise ValueError(problem)
if out.is_symlink() or out.exists():
raise ValueError(f"--envelope-out already exists; send or remove {out} before writing a new envelope")
try:
# Exclusive create, like the manifest: an envelope that has not been
# sent yet must not be replaced by a later relay's digest.
with out.open("x", encoding="utf-8") as handle:
handle.write(json.dumps(payload, ensure_ascii=False, indent=2) + "\n")
except FileExistsError as exc:
raise ValueError(f"--envelope-out already exists; send or remove {out} before writing a new envelope") from exc
except OSError as exc:
raise ValueError(f"cannot write --envelope-out: {exc}") from exc
return out
def load_trusted_envelope(root: Path, path: Path) -> dict[str, str]:
"""Read the three receiver-trusted values from an envelope file.
The path is always explicit; nothing is discovered. A file under the relay
root arrived with the artifact and is refused, because the envelope only
means something when it came through an authenticated channel.
"""
label = "trusted envelope"
problem = outside_root_error(root, path, label)
if problem:
raise ValueError(f"{problem}; a file that arrived with the artifact is not a trusted channel")
data = load_json_object(path, label, MAX_ENVELOPE_BYTES)
if data.get("kind") != ENVELOPE_KIND or type(data.get("schema")) is not int or data.get("schema") != 1:
raise ValueError(f"{label} must declare kind {ENVELOPE_KIND} and schema 1")
values: dict[str, str] = {}
for key in ("trusted_head", "trusted_manifest_sha256", "repository_url"):
if not nonempty(data.get(key)):
raise ValueError(f"{label} lacks {key}")
values[key] = str(data[key])
return values
def add_receiver_arguments(command: argparse.ArgumentParser) -> None:
command.add_argument("--expected-recipient", choices=("same-machine", "cross-machine"))
command.add_argument("--trusted-head")
command.add_argument("--trusted-manifest-sha256")
command.add_argument("--trusted-repository-url")
command.add_argument(
"--trusted-envelope",
metavar="PATH",
help="read the three trusted values from an envelope file received through an authenticated channel; "
"the file must live outside --root and implies --expected-recipient cross-machine",
)
def parser() -> argparse.ArgumentParser:
top = argparse.ArgumentParser(description=__doc__)
sub = top.add_subparsers(dest="command", required=True)
draft_command = sub.add_parser("draft")
draft_command.add_argument("--root", default=".")
draft_command.add_argument(
"--recipient",
default="same-machine",
choices=("same-machine", "cross-machine"),
help="where the receiver will consume this relay (default: same-machine for legacy callers)",
)
draft_command.add_argument("--base", help="task base revision; required for cross-machine")
draft_command.add_argument(
"--write",
action="store_true",
help=f"write {MANIFEST} into --root instead of printing it; refuses to replace an existing one",
)
for name in ("render", "validate", "envelope", "finalize", "inspect"):
command = sub.add_parser(name)
command.add_argument("--root", default=".")
if name == "finalize":
command.add_argument(
"--envelope-out",
metavar="PATH",
help="cross-machine only: also write the trusted envelope to this path outside --root",
)
if name == "inspect":
command.add_argument("--json", action="store_true")
add_receiver_arguments(command)
consume = sub.add_parser("consume")
consume.add_argument("--root", default=".")
consume.add_argument("--verified", action="store_true")
add_receiver_arguments(consume)
return top
def main() -> int:
args = parser().parse_args()
root = Path(args.root).resolve()
if args.command == "draft":
try:
if args.write:
# Refuse before a cross-machine draft publishes its transfer tag.
refuse_existing_manifest(root)
data = draft(root, args.recipient, args.base)
if args.write:
print(f"WROTE {write_manifest(root, data)}")
return 0
except ValueError as exc:
print(f"relay: {exc}", file=sys.stderr)
return 1
print(json.dumps(data, ensure_ascii=False, indent=2))
return 0
try:
data = load_manifest(root)
except ValueError as exc:
print(f"relay: {exc}", file=sys.stderr)
return 1
receiver_context = args.command in ("inspect", "consume")
expected_recipient = getattr(args, "expected_recipient", None)
trusted_head = getattr(args, "trusted_head", None)
trusted_manifest_sha256 = getattr(args, "trusted_manifest_sha256", None)
trusted_repository_url = getattr(args, "trusted_repository_url", None)
trusted_envelope = getattr(args, "trusted_envelope", None)
if trusted_envelope is not None:
if any(value is not None for value in (trusted_head, trusted_manifest_sha256, trusted_repository_url)):
print("relay: pass --trusted-envelope or the three --trusted-* flags, not both", file=sys.stderr)
return 1
if expected_recipient == "same-machine":
print("relay: --trusted-envelope is a cross-machine channel; drop --expected-recipient same-machine", file=sys.stderr)
return 1
try:
trusted = load_trusted_envelope(root, Path(trusted_envelope))
except ValueError as exc:
print(f"relay: {exc}", file=sys.stderr)
return 1
expected_recipient = "cross-machine"
trusted_head = trusted["trusted_head"]
trusted_manifest_sha256 = trusted["trusted_manifest_sha256"]
trusted_repository_url = trusted["repository_url"]
result = inspect(
root,
data,
check_human=receiver_context or args.command == "envelope",
expected_recipient=expected_recipient,
trusted_head=trusted_head,
trusted_manifest_sha256=trusted_manifest_sha256,
trusted_repository_url=trusted_repository_url,
receiver_context=receiver_context,
)
if args.command == "validate":
for message in result["errors"]:
print(f"ERROR {message}", file=sys.stderr)
for message in result["warnings"]:
print(f"WARN {message}", file=sys.stderr)
if result["valid"]:
print(f"VALID luciazero-relay schema={data.get('schema')}")
return 0 if result["valid"] else 1
if args.command == "render":
if not result["valid"]:
for message in result["errors"]:
print(f"ERROR {message}", file=sys.stderr)
return 1
try:
human = write_human(root, data)
except ValueError as exc:
print(f"relay: {exc}", file=sys.stderr)
return 1
for message in result["warnings"]:
print(f"WARN {message}", file=sys.stderr)
print(f"WROTE {human}")
return 0
if args.command == "envelope":
result["errors"].extend(envelope_remote_errors(root, data))
result["valid"] = not result["errors"]
if not result["valid"] or data.get("schema") != 3 or result["recipient"] != "cross-machine":
for message in result["errors"]:
print(f"ERROR {message}", file=sys.stderr)
print("relay: trusted envelope requires a valid rendered cross-machine schema 3 relay", file=sys.stderr)
return 1
print(json.dumps(envelope_payload(root, data), ensure_ascii=False, indent=2))
return 0
if args.command == "finalize":
# validate, regenerate the human view, and for cross-machine print the
# trusted envelope: one command, one error report.
cross_machine = data.get("schema") == 3 and result["recipient"] == "cross-machine"
envelope_out = Path(args.envelope_out) if args.envelope_out else None
if envelope_out is not None:
problem = outside_root_error(root, envelope_out, "--envelope-out")
if not cross_machine:
problem = "--envelope-out needs a cross-machine schema 3 relay"
if problem:
print(f"relay: {problem}", file=sys.stderr)
return 1
if not result["valid"]:
for message in result["errors"]:
print(f"ERROR {message}", file=sys.stderr)
return 1
try:
print(f"WROTE {write_human(root, data)}")
except ValueError as exc:
print(f"relay: {exc}", file=sys.stderr)
return 1
for message in result["warnings"]:
print(f"WARN {message}", file=sys.stderr)
if not cross_machine:
return 0
remote_errors = envelope_remote_errors(root, data)
if remote_errors:
for message in remote_errors:
print(f"ERROR {message}", file=sys.stderr)
print("relay: trusted envelope requires the pushed remote ref to still resolve to HEAD", file=sys.stderr)
return 1
payload = envelope_payload(root, data)
print(json.dumps(payload, ensure_ascii=False, indent=2))
if envelope_out is not None:
try:
print(f"WROTE {write_envelope(root, payload, envelope_out)}")
except ValueError as exc:
print(f"relay: {exc}", file=sys.stderr)
return 1
return 0
if args.command == "inspect":
if args.json:
print(json.dumps(result, ensure_ascii=False, indent=2))
else:
print(f"Relay: {'valid' if result['valid'] else 'invalid'}, age={result['age_days']}d")
print(f"Recipient: {result['recipient']}")
print(f"Repository drift: {'yes' if result['repository_drift'] else 'no'}")
if result["drift_fields"]:
print("Changed fingerprint fields: " + ", ".join(result["drift_fields"]))
print("Next: " + json.dumps(result["next_step"], ensure_ascii=False))
for message in result["warnings"]:
print(f"WARN {message}")
for message in result["errors"]:
print(f"ERROR {message}")
if result["valid"]:
return 0
return 2 if result["trust_required"] else 1
if not result["valid"]:
print("relay: refuse to consume an invalid relay", file=sys.stderr)
return 2 if result["trust_required"] else 1
if not args.verified:
print("relay: refuse to consume without --verified after re-running evidence", file=sys.stderr)
return 2
for name in (RECEIPT, HUMAN, MANIFEST):
path = root / name
if path.exists() or path.is_symlink():
path.unlink()
print(f"CONSUMED {path}")
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |