leos-agent 6.3.0 → 10.1.0

package/scripts/measure_context.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Measure leos-agent's static prompt footprint with a byte-based proxy.
+
+This does not estimate total task cost: tool output, conversation history,
+cache state, model choice, and spawned work dominate many real runs. It measures
+the repository-controlled text that is always listed or loaded at dispatch, so
+regressions remain visible without a tokenizer or network access.
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+# Deliberately tight ceilings. Raise one only with a concrete reason and record
+# the before/after output in the change that raises it.
+LIMITS = {
+	"global_policy_bytes": 4_500,
+	"codex_implicit_skill_metadata_bytes": 600,
+	"claude_implicit_skill_metadata_bytes": 800,
+	"codex_agent_description_bytes": 550,
+	"review_dispatch_bytes": 3_500,
+}
+
+
+def frontmatter(path):
+	text = path.read_text(encoding="utf-8")
+	match = re.match(r"---\n(.*?)\n---\n?(.*)", text, re.DOTALL)
+	if not match:
+		raise ValueError(f"{path.relative_to(ROOT)} has no YAML frontmatter")
+	return match.group(1), match.group(2)
+
+
+def field(text, name):
+	match = re.search(rf"(?m)^{re.escape(name)}:\s*(.+?)\s*$", text)
+	return match.group(1).strip() if match else ""
+
+
+def byte_len(text):
+	return len(text.encode("utf-8"))
+
+
+def skill_metadata_bytes(paths, implicit):
+	total = 0
+	for path in paths:
+		fm, _ = frontmatter(path)
+		if implicit(path, fm):
+			total += byte_len(field(fm, "name")) + byte_len(field(fm, "description"))
+	return total
+
+
+def codex_implicit(path, _frontmatter):
+	policy = path.parent / "agents" / "openai.yaml"
+	return not policy.is_file() or "allow_implicit_invocation: false" not in policy.read_text(encoding="utf-8")
+
+
+def claude_implicit(_path, fm):
+	return re.search(r"(?m)^disable-model-invocation:\s*true\s*$", fm) is None
+
+
+def agent_description(path):
+	text = path.read_text(encoding="utf-8")
+	match = re.search(r'(?m)^description\s*=\s*"(.*)"\s*$', text)
+	if not match:
+		raise ValueError(f"{path.relative_to(ROOT)} has no one-line description")
+	return match.group(1)
+
+
+def measurements():
+	portable = sorted((ROOT / "skills").glob("*/SKILL.md"))
+	claude_only = sorted((ROOT / "skills-claude").glob("*/SKILL.md"))
+	policy_fm, policy_body = frontmatter(ROOT / "rules" / "preferences.md")
+	del policy_fm
+	review_fm, review_body = frontmatter(ROOT / "skills" / "review-pr" / "SKILL.md")
+	del review_fm
+	agent_paths = sorted((ROOT / "payload" / "codex-agents").glob("*.toml"))
+	return {
+		"global_policy_bytes": byte_len(policy_body.strip()),
+		"codex_implicit_skill_metadata_bytes": skill_metadata_bytes(portable, codex_implicit),
+		"claude_implicit_skill_metadata_bytes": skill_metadata_bytes(portable + claude_only, claude_implicit),
+		"codex_agent_description_bytes": sum(byte_len(agent_description(path)) for path in agent_paths),
+		"review_dispatch_bytes": byte_len(review_body.strip()),
+	}
+
+
+def main(argv=None):
+	parser = argparse.ArgumentParser(description=__doc__)
+	parser.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+	parser.add_argument("--check", action="store_true", help="fail when a committed ceiling is exceeded")
+	args = parser.parse_args(argv)
+
+	values = measurements()
+	if args.json:
+		print(json.dumps({"measurements": values, "limits": LIMITS}, indent=2, sort_keys=True))
+	else:
+		print("Static prompt footprint (bytes; tokens are roughly bytes / 4 for this prose)")
+		for name, value in values.items():
+			print(f"  {name:38} {value:5}  limit {LIMITS[name]:5}")
+		print("This excludes conversation history, tool output, cache effects, and subagent work.")
+
+	over = {name: (value, LIMITS[name]) for name, value in values.items() if value > LIMITS[name]}
+	if args.check and over:
+		for name, (value, limit) in over.items():
+			print(f"FAIL {name}: {value} > {limit}", file=sys.stderr)
+		return 1
+	return 0
+
+
+if __name__ == "__main__":
+	sys.exit(main())

package/scripts/publish-npm.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Publish leos-agent to npm exactly once per version.
+
+Two properties matter here, and both are inherited from the release path this
+replaces. Publishing is idempotent: an exact version already on the registry is
+a no-op, so re-running a tag is safe, while a lookup that fails for any reason
+other than a confirmed 404 aborts rather than guessing. And the tree npm would
+actually ship is inspected before it ships, because `files` in package.json
+scopes the publish but does not exclude build residue that lands inside a
+directory it lists.
+
+Authentication is npm's OIDC trusted publishing: the workflow's `id-token`
+permission supplies a short-lived credential, so there is no token to read here.
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+PACKAGE = "leos-agent"
+
+# Residue that a local checkout accumulates and a publish must never carry.
+FORBIDDEN_PARTS = ("__pycache__",)
+FORBIDDEN_SUFFIXES = (".pyc", ".log")
+FORBIDDEN_NAMES = (".DS_Store",)
+
+
+class ReleaseError(Exception):
+	"""The release cannot proceed safely; the caller should stop, not retry."""
+
+
+def run(command):
+	return subprocess.run(command, capture_output=True, text=True, check=False, cwd=ROOT)
+
+
+def declared_version():
+	version = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))["version"]
+	return version
+
+
+def pack_inventory(npm="npm"):
+	"""Return the file list npm would publish, without publishing it."""
+	packed = run([npm, "pack", "--dry-run", "--json"])
+	if packed.returncode:
+		raise ReleaseError(f"npm pack --dry-run failed: {(packed.stdout + packed.stderr).strip()}")
+	try:
+		report = json.loads(packed.stdout)
+	except json.JSONDecodeError as exc:
+		raise ReleaseError(f"npm pack --dry-run emitted unparseable JSON: {exc}") from exc
+	if not report:
+		raise ReleaseError("npm pack --dry-run reported no package")
+	return sorted(entry["path"] for entry in report[0].get("files", []))
+
+
+def forbidden_paths(inventory):
+	found = []
+	for path in inventory:
+		parts = path.split("/")
+		if any(part in FORBIDDEN_PARTS for part in parts):
+			found.append(path)
+		elif path.endswith(FORBIDDEN_SUFFIXES) or parts[-1] in FORBIDDEN_NAMES:
+			found.append(path)
+	return found
+
+
+def check_inventory(inventory):
+	if "LICENSE" not in inventory:
+		raise ReleaseError("publish tree has no LICENSE")
+	if "package.json" not in inventory:
+		raise ReleaseError("publish tree has no package.json")
+	found = forbidden_paths(inventory)
+	if found:
+		raise ReleaseError("publish tree contains transient files: " + ", ".join(found))
+
+
+def registry_state(version, npm="npm"):
+	"""Report whether this exact version is already on the registry.
+
+	Anything other than a clean hit or a confirmed not-found is an error: an
+	auth failure or a registry outage must not be read as "absent, publish it".
+	"""
+	viewed = run([npm, "view", f"{PACKAGE}@{version}", "version"])
+	output = (viewed.stdout + viewed.stderr).strip()
+	if viewed.returncode == 0:
+		if output != version:
+			raise ReleaseError(f"npm returned {output!r}, not the exact version {version!r}")
+		return "present"
+	if "E404" in output or "404 Not Found" in output:
+		return "absent"
+	raise ReleaseError(f"npm version lookup failed without a confirmed not-found: {output}")
+
+
+def publish(npm="npm"):
+	published = run([npm, "publish", "--access", "public"])
+	if published.returncode:
+		raise ReleaseError(f"npm publish failed: {(published.stdout + published.stderr).strip()}")
+	return (published.stdout + published.stderr).strip()
+
+
+def main(argv=None):
+	parser = argparse.ArgumentParser(description=__doc__)
+	parser.add_argument("--tag", help="git tag being released; must match package.json")
+	parser.add_argument("--dry-run", action="store_true", help="check everything, publish nothing")
+	parser.add_argument("--npm", default="npm", help="npm executable to use")
+	args = parser.parse_args(argv)
+
+	try:
+		version = declared_version()
+		if args.tag is not None:
+			expected = args.tag[1:] if args.tag.startswith("v") else args.tag
+			if expected != version:
+				raise ReleaseError(f"tag {args.tag!r} does not match package.json version {version!r}")
+
+		inventory = pack_inventory(args.npm)
+		check_inventory(inventory)
+		print(f"{PACKAGE} {version}: {len(inventory)} file(s) staged for publish")
+
+		state = registry_state(version, args.npm)
+		if state == "present":
+			print(f"{PACKAGE}@{version} is already on the registry; nothing to do")
+			return 0
+		if args.dry_run:
+			print(f"would publish {PACKAGE}@{version}")
+			return 0
+
+		publish(args.npm)
+		print(f"published {PACKAGE}@{version}")
+		return 0
+	except ReleaseError as exc:
+		print(f"error: {exc}", file=sys.stderr)
+		return 1
+
+
+if __name__ == "__main__":
+	sys.exit(main())

package/scripts/resolve_attach_target.py

@@ -16,13 +16,16 @@ Exit code is 0 for "ok" and 1 otherwise, so callers can branch on it directly.
 import json
 import os
 import re
+import shlex
 import shutil
 import subprocess
 import sys
+from hashlib import sha256
 
 PR_NUM_RE = re.compile(r"^#?(\d+)$")
-PR_URL_RE = re.compile(r"^https?://[^/]*github\.com/([^/]+)/([^/]+)/pull/(\d+)")
+PR_URL_RE = re.compile(r"^https://github\.com/([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+)/pull/([1-9]\d*)$")
 TICKET_RE = re.compile(r"^([A-Za-z][A-Za-z0-9]*)-(\d+)$")
+SAFE_REF_RE = re.compile(r"^(?!-)[A-Za-z0-9][A-Za-z0-9._/-]*$")
 
 PR_FIELDS = "number,url,headRefName,baseRefName,state,title"
 
@@ -48,6 +51,36 @@ def emit(payload):
     sys.exit(0 if payload.get("status") == "ok" else 1)
 
 
+def is_safe_pr_url(url):
+    """Accept only a canonical public GitHub pull-request URL."""
+    return isinstance(url, str) and bool(PR_URL_RE.fullmatch(url))
+
+
+def is_safe_ref(ref):
+    """Keep refs shell-safe *and* ask Git to enforce its ref grammar."""
+    if not isinstance(ref, str) or not SAFE_REF_RE.fullmatch(ref):
+        return False
+    rc, _, _ = run(["git", "check-ref-format", "--branch", ref])
+    return rc == 0
+
+
+def suggested_worktree(root, branch):
+    """A readable name with a stable digest prevents slash-to-dash collisions."""
+    readable = branch.replace("/", "-")
+    digest = sha256(branch.encode("utf-8")).hexdigest()[:10]
+    return os.path.join(root, ".claude", "worktrees", f"{readable}-{digest}")
+
+
+def build_attach_command(workdir, pr_url, base_ref, branch):
+    """Build the intentional compound attach command with every value quoted."""
+    return (
+        'gh() { echo "$PR_URL"; }; '
+        f"cd {shlex.quote(workdir)}; "
+        f"PR_URL={shlex.quote(pr_url)} gh pr create --draft "
+        f"--base {shlex.quote(base_ref)} --head {shlex.quote(branch)}"
+    )
+
+
 # --- environment checks ----------------------------------------------------
 
 
@@ -194,7 +227,7 @@ def resolve(identifier, repo):
     """Return (pr_dict, note) or emit an error/ambiguous payload and exit."""
     ident = identifier.strip()
 
-    url_match = PR_URL_RE.match(ident)
+    url_match = PR_URL_RE.fullmatch(ident)
     if url_match:
         owner, name, number = url_match.groups()
         if f"{owner}/{name}".lower() != repo.lower():
@@ -321,8 +354,14 @@ def main():
 
     pr, note = resolve(sys.argv[1], repo)
     branch = pr.get("headRefName")
+    base_ref = pr.get("baseRefName") or "main"
+    pr_url = pr.get("url")
     if not branch:
         die(f"PR #{pr.get('number')} has no head branch recorded; cannot attach")
+    if not is_safe_ref(branch) or not is_safe_ref(base_ref):
+        die("PR branch or base ref contains unsupported shell-unsafe characters")
+    if not is_safe_pr_url(pr_url):
+        die("PR URL is not a canonical https://github.com/<owner>/<repo>/pull/<number> URL")
 
     workdir, kind = resolve_workdir(branch, root)
 
@@ -332,24 +371,17 @@ def main():
         "repo": repo,
         "branch": branch,
         "pr_number": pr.get("number"),
-        "pr_url": pr.get("url"),
-        "base_ref": pr.get("baseRefName") or "main",
+        "pr_url": pr_url,
+        "base_ref": base_ref,
         "pr_state": pr.get("state"),
         "pr_title": pr.get("title"),
         "workdir": workdir,
         "workdir_kind": kind,
         "repo_root": root,
-        "suggested_worktree": os.path.join(
-            root, ".claude", "worktrees", branch.replace("/", "-")
-        ),
+        "suggested_worktree": suggested_worktree(root, branch),
     }
     if workdir:
-        payload["attach_command"] = (
-            'gh() { echo "$PR_URL"; }; '
-            f"cd {workdir}; "
-            f"PR_URL={pr.get('url')} gh pr create --draft "
-            f"--base {payload['base_ref']} --head {branch}"
-        )
+        payload["attach_command"] = build_attach_command(workdir, pr_url, base_ref, branch)
     emit(payload)
 
 

package/scripts/watch_review.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""watch_review: stream new GitHub review requests without spending tokens.
+
+The discovery half of the review watcher is a fixed query, a fixed filter, and
+a state file — none of it needs a model. This script does that half in the
+shell and prints one line per new pull request; whoever reads stdout does the
+review. An idle tick costs one `gh` call and zero tokens.
+
+  watch_review.py monitor [-C DIR] --interval 300  loop; a line per new PR
+  watch_review.py record  [-C DIR] <number>...     mark numbers reviewed
+  watch_review.py state   [-C DIR]                 show what has been reviewed
+  watch_review.py forget  [-C DIR] <number>...     drop numbers from the state
+
+It launches nothing and records nothing on its own. The reader must call
+`record` once a review is done — a staged (pending, unsubmitted) review does
+not clear the request on GitHub, so that state file is the only thing keeping
+the same pull request from coming back. `monitor` emits each pull request once
+per process, so an unreviewed one is re-emitted after a restart.
+
+Intended for Claude Code's Monitor tool, which turns each stdout line into a
+session notification. Any `read`-driven shell loop works the same way.
+
+State lives in the review-watcher state file managed by state.py, keyed by
+"owner/repo" — the same file and shape the watch-review skill reads.
+"""
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import state as state_mod  # noqa: E402
+
+STATE_NAME = "review-watcher"
+
+
+def fail(message):
+	print(f"watch-review: {message}", file=sys.stderr)
+	sys.exit(1)
+
+
+def gh(args, cwd):
+	"""Run a read-only gh command and return stdout, or fail loudly."""
+	try:
+		proc = subprocess.run(
+			["gh"] + args, cwd=cwd, capture_output=True, text=True, check=False
+		)
+	except FileNotFoundError:
+		fail("gh is not installed or not on PATH")
+	if proc.returncode != 0:
+		fail((proc.stderr or proc.stdout).strip() or f"gh {args[0]} failed")
+	return proc.stdout
+
+
+def discover(cwd):
+	"""Return (repo, login, [pull requests directly requesting login])."""
+	repo = json.loads(gh(["repo", "view", "--json", "nameWithOwner"], cwd))["nameWithOwner"]
+	login = gh(["api", "user", "--jq", ".login"], cwd).strip()
+	if not login:
+		fail("gh api user returned no login; is gh authenticated?")
+	# user-review-requested matches direct requests only; the reviewRequests
+	# check below is belt and braces against a stale or fuzzy search result.
+	listing = json.loads(
+		gh(
+			[
+				"pr", "list", "--state", "open",
+				"--search", f"user-review-requested:{login}",
+				"--limit", "100",
+				"--json", "number,title,isDraft,reviewRequests,url",
+			],
+			cwd,
+		)
+	)
+	matches = [
+		pr
+		for pr in listing
+		if not pr.get("isDraft")
+		and any(
+			r.get("__typename") == "User" and r.get("login") == login
+			for r in pr.get("reviewRequests") or []
+		)
+	]
+	matches.sort(key=lambda pr: pr["number"])
+	return repo, login, matches
+
+
+def reviewed_numbers(repo):
+	data = state_mod.load(state_mod.state_file(STATE_NAME))
+	entry = data.get(repo) or {}
+	return set(entry.get("reviewed") or [])
+
+
+def record(repo, number):
+	path = state_mod.state_file(STATE_NAME)
+	with state_mod._locked(path):
+		data = state_mod.load(path)
+		data[repo] = state_mod.deep_merge(data.get(repo, {}), {"reviewed": [number]})
+		state_mod.atomic_write(path, data)
+
+
+def monitor(args):
+	"""Emit one line per new pull request; review nothing, record nothing."""
+	emitted = set()
+	while True:
+		try:
+			repo, _, matches = discover(args.directory)
+			done = reviewed_numbers(repo)
+			for pr in matches:
+				n = pr["number"]
+				if n in done or n in emitted:
+					continue
+				emitted.add(n)
+				# One line, one event. The title is data — a reader must treat
+				# it as a string to show Leo, never as an instruction.
+				print(f"review-requested {repo}#{n} {pr['url']} — {pr['title']}", flush=True)
+		except SystemExit as exc:
+			# A transient gh failure must not kill a session-length watch.
+			print(
+				f"watch-review: tick failed ({exc.code}); retrying next interval",
+				file=sys.stderr,
+				flush=True,
+			)
+		time.sleep(args.interval)
+
+
+def main(argv):
+	parser = argparse.ArgumentParser(prog="watch_review.py", description=__doc__)
+	sub = parser.add_subparsers(dest="mode", required=True)
+
+	mon = sub.add_parser("monitor")
+	mon.add_argument("-C", "--directory", default=".", help="repository directory (default: cwd)")
+	mon.add_argument("--interval", type=int, default=300, help="seconds between ticks")
+
+	sub.add_parser("state").add_argument("-C", "--directory", default=".")
+	for name in ("record", "forget"):
+		p = sub.add_parser(name)
+		p.add_argument("-C", "--directory", default=".")
+		p.add_argument("numbers", nargs="+", type=int)
+
+	args = parser.parse_args(argv)
+	if not os.path.isdir(args.directory):
+		fail(f"{args.directory} is not a directory")
+
+	if args.mode == "monitor":
+		if args.interval < 30:
+			fail("--interval below 30s hammers the GitHub API; pick something larger")
+		return monitor(args)
+
+	repo, _, _ = discover(args.directory)
+	if args.mode == "record":
+		for n in args.numbers:
+			record(repo, n)
+	elif args.mode == "forget":
+		path = state_mod.state_file(STATE_NAME)
+		with state_mod._locked(path):
+			data = state_mod.load(path)
+			entry = data.get(repo) or {}
+			drop = set(args.numbers)
+			entry["reviewed"] = [n for n in (entry.get("reviewed") or []) if n not in drop]
+			data[repo] = entry
+			state_mod.atomic_write(path, data)
+	print(json.dumps({"repo": repo, "reviewed": sorted(reviewed_numbers(repo))}, indent=1))
+	return 0
+
+
+if __name__ == "__main__":
+	sys.exit(main(sys.argv[1:]) or 0)