Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
Rust ai-agentsai-gatewayclaude-codecodexcoding-agentcost-optimizationdeepseekllm-gatewayllm-routerlocal-firstmodel-routingrusttask-routingtauri
#!/usr/bin/env python3
"""Create or verify a deterministic HiRoute standalone user-install archive."""
import argparse
import gzip
import hashlib
import io
import json
from pathlib import Path
import platform
import re
import tarfile
import struct
REPO = Path(__file__).resolve().parent.parent
SCHEMA = "hiroute.standalone-package/v1"
TARGETS = {
"x86_64-unknown-linux-gnu",
"aarch64-unknown-linux-gnu",
"x86_64-apple-darwin",
"aarch64-apple-darwin",
"x86_64-pc-windows-msvc",
"aarch64-pc-windows-msvc",
}
PORTABLE = re.compile(r"^[A-Za-z0-9._-]+$")
HEX_SHA256 = re.compile(r"^[a-fA-F0-9]{64}$")
MAX_ARCHIVE = 1024 * 1024 * 1024
NOTICE_FILES = {
"THIRD-PARTY-LICENSES.txt",
"third-party-licenses.json",
}
EXPECTED_FILES = {
"bin/hiroute",
"bin/hirouted",
"libexec/cliproxyapi",
"licenses/CLIProxyAPI-LICENSE",
"licenses/HiRoute-LICENSE",
"licenses/THIRD-PARTY-LICENSES.txt",
"licenses/third-party-licenses.json",
"skills/hiroute-management/SKILL.md",
"docs/standalone-cli.md",
}
def executable_names(target):
suffix = ".exe" if target.endswith("-pc-windows-msvc") else ""
return {"hiroute": "bin/hiroute" + suffix,
"hirouted": "bin/hirouted" + suffix,
"cpa": "libexec/cliproxyapi" + suffix}
def expected_files(target):
names = executable_names(target)
return (EXPECTED_FILES - {"bin/hiroute", "bin/hirouted", "libexec/cliproxyapi"}) | set(names.values())
def console_name(name):
return (isinstance(name, str) and len(name) <= 240 and name.startswith("console/")
and all(re.fullmatch(r"[[email protected]]+", part) and part not in {".", ".."}
for part in name.split("/")))
def valid_inventory(names, target):
base = expected_files(target)
extra = set(names) - base
# V1 archives without console files remain readable during upgrades.
return (base <= set(names) and len(extra) <= 2048
and (not extra or "console/index.html" in extra)
and all(console_name(name) for name in extra))
def console_payload(directory):
if directory.is_symlink() or not directory.is_dir():
raise ValueError("console assets must be a real directory")
result = {}
for path in sorted(directory.rglob("*")):
if path.is_symlink():
raise ValueError("console assets cannot contain links")
if path.is_dir():
continue
name = "console/" + path.relative_to(directory).as_posix()
if not console_name(name) or len(result) >= 2048:
raise ValueError("console asset inventory is invalid")
source = checked_source(path)
if source.stat().st_size > 16 * 1024 * 1024:
raise ValueError("console asset exceeds its size bound")
result[name] = source
if "console/index.html" not in result or sum(path.stat().st_size for path in result.values()) > 64 * 1024 * 1024:
raise ValueError("console assets are incomplete or too large")
return result
def verify_windows_image(path, target):
with Path(path).open("rb") as stream:
verify_windows_stream(stream, target)
def verify_windows_stream(stream, target):
header = stream.read(64)
if len(header) != 64 or header[:2] != b"MZ":
raise ValueError("Windows executable is not a PE image")
offset = struct.unpack_from("<I", header, 0x3C)[0]
if not 64 <= offset <= 16 * 1024 * 1024:
raise ValueError("Windows PE header offset is invalid")
stream.seek(offset)
pe = stream.read(6)
machine = {"x86_64-pc-windows-msvc": 0x8664, "aarch64-pc-windows-msvc": 0xAA64}[target]
if len(pe) != 6 or pe[:4] != b"PE\0\0" or struct.unpack_from("<H", pe, 4)[0] != machine:
raise ValueError("Windows PE image architecture differs from package target")
def load_json_bytes(value):
def unique(pairs):
result = {}
for key, item in pairs:
if key in result:
raise ValueError(f"duplicate JSON key: {key}")
result[key] = item
return result
return json.loads(value, object_pairs_hook=unique)
def digest(path):
value = hashlib.sha256()
with path.open("rb") as stream:
for chunk in iter(lambda: stream.read(1024 * 1024), b""):
value.update(chunk)
return value.hexdigest()
def host_target():
machine = {"AMD64": "x86_64", "ARM64": "aarch64", "arm64": "aarch64"}.get(
platform.machine(), platform.machine()
)
system = {"Linux": "unknown-linux-gnu", "Darwin": "apple-darwin", "Windows": "pc-windows-msvc"}.get(
platform.system()
)
if not system:
raise ValueError("unsupported standalone packaging platform")
return f"{machine}-{system}"
def checked_source(path, executable=False):
if path.is_symlink():
raise ValueError(f"package source is not a regular file: {path}")
path = path.resolve(strict=True)
if not path.is_file():
raise ValueError(f"package source is not a regular file: {path}")
mode = path.stat().st_mode
if platform.system() != "Windows" and mode & 0o022:
raise ValueError(f"package source is group/world writable: {path}")
if executable and platform.system() != "Windows" and not mode & 0o111:
raise ValueError(f"package source is not executable: {path}")
return path
def validate_notices(directory):
if directory.is_symlink() or not directory.is_dir():
raise ValueError("third-party notices must be a directory")
actual = {path.name for path in directory.iterdir() if path.is_file()}
if (
actual != NOTICE_FILES
or any(path.is_symlink() or not path.is_file() for path in directory.iterdir())
):
raise ValueError("third-party notice inventory is incomplete")
manifest = load_json_bytes((directory / "third-party-licenses.json").read_bytes())
if (
not isinstance(manifest, dict)
or set(manifest) != {"schema", "inputs", "packages", "documents"}
or manifest.get("schema") != "hiroute.third-party-licenses/v1"
or not isinstance(manifest.get("inputs"), dict)
or not isinstance(manifest.get("packages"), list)
or not manifest["packages"]
or not isinstance(manifest.get("documents"), list)
or not manifest["documents"]
or not (directory / "THIRD-PARTY-LICENSES.txt").read_text(encoding="utf-8").strip()
):
raise ValueError("third-party notice manifest is invalid")
return directory
def payload(args, notices):
skill = checked_source(REPO / "assets/skills/hiroute-management/SKILL.md")
names = executable_names(args.target)
guide = "standalone-windows.md" if args.target.endswith("-pc-windows-msvc") else "standalone-cli.md"
files = {
names["hiroute"]: checked_source(args.hiroute, not args.target.endswith("-pc-windows-msvc")),
names["hirouted"]: checked_source(args.hirouted, not args.target.endswith("-pc-windows-msvc")),
names["cpa"]: checked_source(args.cpa_binary, not args.target.endswith("-pc-windows-msvc")),
"licenses/CLIProxyAPI-LICENSE": checked_source(args.cpa_license),
"licenses/HiRoute-LICENSE": checked_source(REPO / "LICENSE"),
"skills/hiroute-management/SKILL.md": skill,
"docs/standalone-cli.md": checked_source(REPO / "docs" / guide),
}
for name in sorted(NOTICE_FILES):
files[f"licenses/{name}"] = checked_source(notices / name)
if getattr(args, "console_assets", None) is not None:
files.update(console_payload(args.console_assets))
if args.target.endswith("-pc-windows-msvc"):
for key in names.values():
verify_windows_image(files[key], args.target)
return files
def deterministic_archive(destination, files):
destination.parent.mkdir(parents=True, exist_ok=True)
buffer = io.BytesIO()
with tarfile.open(fileobj=buffer, mode="w", format=tarfile.PAX_FORMAT) as archive:
for relative, source in sorted(files.items()):
data = source.read_bytes()
info = tarfile.TarInfo(relative)
info.size = len(data)
info.mode = 0o755 if relative.startswith(("bin/", "libexec/")) else 0o644
info.mtime = 0
info.uid = info.gid = 0
info.uname = info.gname = ""
archive.addfile(info, io.BytesIO(data))
with destination.open("wb") as raw:
with gzip.GzipFile(filename="", mode="wb", fileobj=raw, mtime=0) as compressed:
compressed.write(buffer.getvalue())
def build(args):
if args.target not in TARGETS:
raise ValueError("unsupported standalone target")
if (
not PORTABLE.fullmatch(args.version)
or len(args.version) > 64
or not PORTABLE.fullmatch(args.revision)
or len(args.revision) > 128
or not args.cpa_version
or len(args.cpa_version) > 128
or any(ord(value) < 0x20 for value in args.cpa_version)
):
raise ValueError("version and revision must be portable identifiers")
files = payload(args, validate_notices(args.notices.resolve()))
name = f"hiroute-{args.version}-{args.revision[:12]}-{args.target}.tar.gz"
archive = args.output.resolve() / name
deterministic_archive(archive, files)
manifest = {
"schema": SCHEMA,
"version": args.version,
"revision": args.revision,
"target": args.target,
"archive": {
"filename": archive.name,
"sha256": digest(archive),
"size": archive.stat().st_size,
},
"files": {
relative: {
"sha256": digest(source),
"size": source.stat().st_size,
"mode": "executable"
if relative.startswith(("bin/", "libexec/"))
else "read_only",
}
for relative, source in sorted(files.items())
},
"cpa": {
"version": args.cpa_version,
"sha256": digest(files[executable_names(args.target)["cpa"]]),
},
"distribution": "integration-candidate",
}
manifest_path = archive.with_suffix(archive.suffix + ".json")
manifest_path.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n")
verify(manifest_path, archive)
print(json.dumps({"archive": str(archive), "manifest": str(manifest_path)}, sort_keys=True))
def safe_members(archive, expected):
result = {}
with tarfile.open(archive, "r:gz") as bundle:
for member in bundle:
if len(result) >= len(expected):
raise ValueError("archive contains an unsafe or duplicate entry")
path = Path(member.name)
if (
not member.isfile()
or path.is_absolute()
or ".." in path.parts
or member.name in result
or member.name not in expected
or member.size != expected[member.name]["size"]
):
raise ValueError("archive contains an unsafe or duplicate entry")
stream = bundle.extractfile(member)
if stream is None:
raise ValueError("archive entry is unreadable")
data = stream.read(member.size + 1)
if len(data) != member.size:
raise ValueError("archive entry differs from its bounded manifest size")
result[member.name] = (data, member.mode & 0o777)
return result
def verify(manifest_path, archive_path):
manifest = load_json_bytes(Path(manifest_path).read_bytes())
archive = Path(archive_path)
if (
not isinstance(manifest, dict)
or set(manifest)
!= {"schema", "version", "revision", "target", "archive", "files", "cpa", "distribution"}
or manifest.get("schema") != SCHEMA
or manifest.get("target") not in TARGETS
or not isinstance(manifest.get("version"), str)
or not PORTABLE.fullmatch(manifest.get("version", ""))
or len(manifest["version"]) > 64
or not isinstance(manifest.get("revision"), str)
or not PORTABLE.fullmatch(manifest.get("revision", ""))
or len(manifest["revision"]) > 128
or manifest.get("distribution") != "integration-candidate"
or not isinstance(manifest.get("files"), dict)
or not valid_inventory(manifest["files"], manifest["target"])
or not isinstance(manifest.get("archive"), dict)
or set(manifest["archive"]) != {"filename", "sha256", "size"}
or not isinstance(manifest.get("cpa"), dict)
or set(manifest["cpa"]) != {"version", "sha256"}
):
raise ValueError("standalone manifest is invalid")
expected_archive = manifest.get("archive", {})
if (
not isinstance(expected_archive.get("filename"), str)
or not expected_archive["filename"]
or len(expected_archive["filename"]) > 240
or expected_archive["filename"] in {".", ".."}
or Path(expected_archive["filename"]).name != expected_archive["filename"]
or not expected_archive["filename"].endswith(".tar.gz")
or archive.name != expected_archive.get("filename")
or not isinstance(expected_archive.get("sha256"), str)
or not HEX_SHA256.fullmatch(expected_archive["sha256"])
or type(expected_archive.get("size")) is not int
or not 0 < expected_archive["size"] <= MAX_ARCHIVE
or archive.stat().st_size != expected_archive.get("size")
or digest(archive) != expected_archive.get("sha256")
):
raise ValueError("standalone archive digest differs from manifest")
total = 0
for name, facts in manifest["files"].items():
expected_mode = "executable" if name.startswith(("bin/", "libexec/")) else "read_only"
if (
not isinstance(facts, dict)
or set(facts) != {"sha256", "size", "mode"}
or not isinstance(facts.get("sha256"), str)
or not HEX_SHA256.fullmatch(facts["sha256"])
or type(facts.get("size")) is not int
or facts["size"] < 0
or facts.get("mode") != expected_mode
):
raise ValueError(f"standalone manifest entry is invalid: {name}")
total += facts["size"]
if total > MAX_ARCHIVE:
raise ValueError("standalone manifest payload is too large")
members = safe_members(archive, manifest["files"])
if set(members) != set(manifest["files"]):
raise ValueError("standalone archive inventory differs from manifest")
for name, facts in manifest["files"].items():
expected_mode = "executable" if name.startswith(("bin/", "libexec/")) else "read_only"
data, mode = members[name]
if (
hashlib.sha256(data).hexdigest() != facts.get("sha256")
or len(data) != facts.get("size")
or mode != (0o755 if expected_mode == "executable" else 0o644)
):
raise ValueError(f"standalone archive entry differs from manifest: {name}")
if manifest["target"].endswith("-pc-windows-msvc") and name in executable_names(manifest["target"]).values():
verify_windows_stream(io.BytesIO(data), manifest["target"])
if (
not isinstance(manifest["cpa"].get("version"), str)
or not manifest["cpa"]["version"]
or len(manifest["cpa"]["version"]) > 128
or any(ord(value) < 0x20 for value in manifest["cpa"]["version"])
or not isinstance(manifest["cpa"].get("sha256"), str)
or not HEX_SHA256.fullmatch(manifest["cpa"]["sha256"])
or manifest["cpa"]["sha256"] != manifest["files"][executable_names(manifest["target"])["cpa"]]["sha256"]
):
raise ValueError("CPA identity differs from archive inventory")
return manifest
def parser():
result = argparse.ArgumentParser()
sub = result.add_subparsers(dest="command", required=True)
create = sub.add_parser("build")
create.add_argument("--version", required=True)
create.add_argument("--revision", required=True)
create.add_argument("--target", default=host_target())
create.add_argument("--hiroute", type=Path, required=True)
create.add_argument("--hirouted", type=Path, required=True)
create.add_argument("--cpa-binary", type=Path, required=True)
create.add_argument("--cpa-version", required=True)
create.add_argument("--cpa-license", type=Path, required=True)
create.add_argument("--notices", type=Path, required=True)
create.add_argument("--console-assets", type=Path, required=True)
create.add_argument("--output", type=Path, required=True)
check = sub.add_parser("verify")
check.add_argument("manifest", type=Path)
check.add_argument("archive", type=Path)
return result
def main():
args = parser().parse_args()
if args.command == "build":
build(args)
else:
manifest = verify(args.manifest, args.archive)
print(json.dumps({"version": manifest["version"], "target": manifest["target"]}))
if __name__ == "__main__":
main()