@ikon85/agent-workflow-kit 0.28.0 → 0.29.0

package/scripts/codex_proc.py

@@ -0,0 +1,602 @@
+#!/usr/bin/env python3
+"""Run one Codex round in an owned process group and classify its result."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import re
+import selectors
+import secrets
+import signal
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+
+REDACTIONS = (
+    (re.compile(r"(?i)(token|api[_-]?key|password)=\S+"), r"\1=[REDACTED]"),
+    (re.compile(r"(?i)bearer\s+\S+"), "Bearer [REDACTED]"),
+)
+CANCEL_REQUESTED = False
+HEARTBEAT_INTERVAL_SECONDS = 0.1
+CANCEL_WAIT_SECONDS = 2.0
+OWNERSHIP_TOKEN = re.compile(r"^[0-9a-f]{64}$")
+LEASE_DIR_NAME = "round.lease"
+LEASE_OWNER_NAME = "owner.json"
+
+
+def request_cancel(_signum: int, _frame: object) -> None:
+    global CANCEL_REQUESTED
+    CANCEL_REQUESTED = True
+
+
+def atomic_write(path: Path, text: str) -> None:
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    with temporary.open("w", encoding="utf-8") as handle:
+        os.chmod(temporary, 0o600)
+        handle.write(text)
+        handle.flush()
+        os.fsync(handle.fileno())
+    os.replace(temporary, path)
+    fsync_directory(path.parent)
+
+
+def exclusive_write(path: Path, text: str) -> None:
+    descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(text)
+            handle.flush()
+            os.fsync(handle.fileno())
+    except BaseException:
+        path.unlink(missing_ok=True)
+        raise
+    fsync_directory(path.parent)
+
+
+def fsync_directory(path: Path) -> None:
+    descriptor = os.open(path, os.O_RDONLY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def remove_durable(path: Path) -> None:
+    path.unlink(missing_ok=True)
+    fsync_directory(path.parent)
+
+
+def read_object(path: Path) -> dict | None:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def publish_runtime(state_dir: Path, token: str, round_number: int, phase: str) -> None:
+    atomic_write(
+        state_dir / "runtime.json",
+        json.dumps({
+            "token": token,
+            "round": round_number,
+            "phase": phase,
+            "heartbeat": time.time(),
+        }, sort_keys=True) + "\n",
+    )
+
+
+def lease_dir(state_dir: Path) -> Path:
+    return state_dir / LEASE_DIR_NAME
+
+
+def lease_owner(state_dir: Path) -> dict | None:
+    return read_object(lease_dir(state_dir) / LEASE_OWNER_NAME)
+
+
+def valid_owner(owner: dict | None) -> bool:
+    if not owner:
+        return False
+    token = owner.get("token")
+    round_number = owner.get("round")
+    return bool(
+        isinstance(token, str) and OWNERSHIP_TOKEN.fullmatch(token)
+        and isinstance(round_number, int) and not isinstance(round_number, bool)
+        and round_number >= 1
+    )
+
+
+def acquire_lease_for_state(state_dir: Path, fallback_round: int | None = None) -> str | None:
+    lease = lease_dir(state_dir)
+    try:
+        lease.mkdir(mode=0o700)
+    except (FileExistsError, FileNotFoundError):
+        return None
+    try:
+        try:
+            round_number = int((state_dir / "next-round").read_text(encoding="utf-8").strip())
+        except (FileNotFoundError, OSError, UnicodeDecodeError, ValueError):
+            if fallback_round is None:
+                raise
+            round_number = fallback_round
+        if round_number < 1:
+            raise ValueError
+        token = secrets.token_hex(32)
+        atomic_write(
+            lease / LEASE_OWNER_NAME,
+            json.dumps({
+                "token": token,
+                "round": round_number,
+                "acquiredAt": time.time(),
+            }, sort_keys=True) + "\n",
+        )
+        fsync_directory(state_dir)
+        return token
+    except (FileNotFoundError, OSError, UnicodeDecodeError, ValueError):
+        shutil.rmtree(lease, ignore_errors=True)
+        return None
+    except BaseException:
+        shutil.rmtree(lease, ignore_errors=True)
+        raise
+
+
+def release_lease_for_state(state_dir: Path, token: str) -> bool:
+    lease = lease_dir(state_dir)
+    owner = lease_owner(state_dir)
+    if not valid_owner(owner) or owner.get("token") != token:
+        return False
+    try:
+        remove_durable(lease / LEASE_OWNER_NAME)
+        lease.rmdir()
+        fsync_directory(state_dir)
+    except OSError:
+        return False
+    return True
+
+
+def remove_runtime_if_owned(state_dir: Path, token: str, round_number: int) -> bool:
+    runtime_path = state_dir / "runtime.json"
+    runtime = read_object(runtime_path)
+    if not runtime or runtime.get("token") != token or runtime.get("round") != round_number:
+        return False
+    remove_durable(runtime_path)
+    return True
+
+
+def matching_cancel_request(state_dir: Path, token: str, round_number: int) -> bool:
+    request = read_object(state_dir / "cancel.request")
+    return bool(
+        request
+        and request.get("token") == token
+        and request.get("round") == round_number
+    )
+
+
+def redact(data: bytes) -> bytes:
+    text = data.decode("utf-8", errors="replace")
+    for pattern, replacement in REDACTIONS:
+        text = pattern.sub(replacement, text)
+    return text.encode()
+
+
+def terminate_group(process: subprocess.Popen[bytes]) -> None:
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    deadline = time.monotonic() + 0.3
+    while time.monotonic() < deadline:
+        try:
+            os.killpg(process.pid, 0)
+        except ProcessLookupError:
+            return
+        time.sleep(0.02)
+    try:
+        os.killpg(process.pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+
+
+def parse_events(stdout: bytes) -> tuple[bool, str | None, str | None]:
+    malformed = False
+    thread_id = None
+    verdict = None
+    for raw_line in stdout.decode("utf-8", errors="replace").splitlines():
+        if not raw_line.strip():
+            continue
+        try:
+            event = json.loads(raw_line)
+        except json.JSONDecodeError:
+            malformed = True
+            continue
+        if not isinstance(event, dict):
+            malformed = True
+            continue
+        event_type = event.get("type")
+        if not isinstance(event_type, str):
+            malformed = True
+            continue
+        if "item" in event and not isinstance(event["item"], dict):
+            malformed = True
+            continue
+        item = event.get("item", {})
+        if "item" in event and not isinstance(item.get("type"), str):
+            malformed = True
+            continue
+        if event_type == "thread.started":
+            candidate = event.get("thread_id")
+            if not isinstance(candidate, str):
+                malformed = True
+            else:
+                thread_id = candidate
+        if event_type == "item.completed" and item.get("type") == "agent_message":
+            candidate = item.get("text")
+            if not isinstance(candidate, str):
+                malformed = True
+            else:
+                verdict = candidate or None
+    return malformed, thread_id, verdict
+
+
+def has_valid_thread_start(stdout: bytes) -> bool:
+    _, thread_id, _ = parse_events(stdout)
+    return thread_id is not None
+
+
+def classification(reason: str | None, returncode: int, stdout: bytes) -> dict:
+    malformed, thread_id, verdict = parse_events(stdout)
+    signal_name = signal.Signals(-returncode).name if returncode < 0 else None
+    if reason == "cancelled":
+        status = "CANCELLED"
+    elif reason == "hung":
+        status = "HUNG"
+    elif reason == "timeout":
+        status = "TIMEOUT"
+    elif returncode < 0:
+        status = "SIGNALLED"
+    elif returncode != 0:
+        status = "EXEC_FAILED"
+    elif malformed:
+        status = "MALFORMED-JSON"
+    elif not thread_id:
+        status = "NO-THREAD"
+    elif not verdict:
+        status = "NO-VERDICT"
+    else:
+        status = "OK"
+    return {
+        "status": status,
+        "threadId": thread_id,
+        "verdict": verdict,
+        "originalExitStatus": returncode if returncode >= 0 else None,
+        "signal": signal_name,
+    }
+
+
+def drain_process(args: argparse.Namespace, process: subprocess.Popen[bytes],
+                  token: str) -> tuple[bytes, int, str | None]:
+    selector = selectors.DefaultSelector()
+    buffers = {"stdout": bytearray(), "stderr": bytearray()}
+    stdout_path = Path(args.state_dir) / f"round-{args.round}.stdout.jsonl"
+    stderr_path = Path(args.state_dir) / f"round-{args.round}.stderr.log"
+    state_dir = Path(args.state_dir)
+    started_at = time.monotonic()
+    last_pre_thread_activity = started_at
+    last_heartbeat = 0.0
+    saw_thread = False
+    reason = None
+    terminated = False
+    with stdout_path.open("xb") as stdout_file, stderr_path.open("xb") as stderr_file:
+        for stream, name in ((process.stdout, "stdout"), (process.stderr, "stderr")):
+            os.set_blocking(stream.fileno(), False)
+            selector.register(stream, selectors.EVENT_READ, name)
+        while selector.get_map():
+            now = time.monotonic()
+            if now - last_heartbeat >= HEARTBEAT_INTERVAL_SECONDS:
+                publish_runtime(state_dir, token, args.round, "running")
+                last_heartbeat = now
+            if matching_cancel_request(state_dir, token, args.round) or CANCEL_REQUESTED:
+                reason = "cancelled"
+            elif now - started_at >= args.timeout:
+                reason = "timeout"
+            elif not saw_thread and now - last_pre_thread_activity >= args.probe_timeout:
+                reason = "hung"
+            if reason and not terminated:
+                terminate_group(process)
+                terminated = True
+            for key, _ in selector.select(timeout=0.03):
+                try:
+                    chunk = os.read(key.fileobj.fileno(), 65_536)
+                except BlockingIOError:
+                    continue
+                if not chunk:
+                    selector.unregister(key.fileobj)
+                    continue
+                if not saw_thread:
+                    last_pre_thread_activity = time.monotonic()
+                buffers[key.data].extend(chunk)
+                if key.data == "stdout":
+                    stdout_file.write(chunk)
+                    if has_valid_thread_start(bytes(buffers["stdout"])):
+                        saw_thread = True
+            if process.poll() is not None and not selector.get_map():
+                break
+        stderr_file.write(redact(bytes(buffers["stderr"])))
+        stdout_file.flush()
+        stderr_file.flush()
+        os.fsync(stdout_file.fileno())
+        os.fsync(stderr_file.fileno())
+        return bytes(buffers["stdout"]), process.wait(), reason
+
+
+def settle_before_publication(args: argparse.Namespace, token: str,
+                              reason: str | None) -> str | None:
+    state_dir = Path(args.state_dir)
+    publish_runtime(state_dir, token, args.round, "settling")
+    marker = os.environ.get("CODEX_EXEC_TEST_SETTLE_MARKER")
+    if marker:
+        atomic_write(Path(marker), token + "\n")
+        deadline = time.monotonic() + 2.0
+        while time.monotonic() < deadline:
+            publish_runtime(state_dir, token, args.round, "settling")
+            if matching_cancel_request(state_dir, token, args.round) or CANCEL_REQUESTED:
+                return "cancelled"
+            time.sleep(0.02)
+    if matching_cancel_request(state_dir, token, args.round) or CANCEL_REQUESTED:
+        return "cancelled"
+    return reason
+
+
+def publish_result(args: argparse.Namespace, token: str, result: dict) -> None:
+    state_dir = Path(args.state_dir)
+    if result.get("threadId"):
+        atomic_write(state_dir / "thread-id", result["threadId"] + "\n")
+    atomic_write(state_dir / "next-round", f"{args.round + 1}\n")
+    result_path = state_dir / f"round-{args.round}.result.json"
+    exclusive_write(result_path, json.dumps(result, sort_keys=True) + "\n")
+    atomic_write(state_dir / "latest", result_path.name + "\n")
+    if not remove_runtime_if_owned(state_dir, token, args.round):
+        raise RuntimeError("runtime ownership changed before terminal publication")
+    print(json.dumps(result, sort_keys=True), flush=True)
+
+
+def run_round(args: argparse.Namespace) -> int:
+    state_dir = Path(args.state_dir)
+    command = args.command[1:] if args.command[:1] == ["--"] else args.command
+    if not command:
+        raise SystemExit("process command is required")
+    prompt_path = state_dir / f"round-{args.round}.prompt.txt"
+    if prompt_path.exists():
+        raise SystemExit(f"round {args.round} already exists")
+    prompt_path.write_bytes(Path(args.prompt_file).read_bytes())
+    signal.signal(signal.SIGINT, request_cancel)
+    signal.signal(signal.SIGTERM, request_cancel)
+    token = args.lease_token
+    owner = lease_owner(state_dir)
+    if not valid_owner(owner) or owner.get("token") != token or owner.get("round") != args.round:
+        raise SystemExit("round lease ownership mismatch")
+    if (state_dir / "runtime.json").exists():
+        raise SystemExit("run already has an active runtime")
+    with prompt_path.open("rb") as prompt:
+        process = subprocess.Popen(
+            command,
+            stdin=prompt,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            start_new_session=True,
+        )
+        try:
+            pid_marker = os.environ.get("CODEX_EXEC_TEST_CHILD_PID_FILE")
+            if pid_marker:
+                atomic_write(Path(pid_marker), f"{process.pid}\n")
+            if os.environ.get("CODEX_EXEC_TEST_RUNTIME_WRITE_FAIL") == "1":
+                raise OSError("injected runtime publication failure")
+            publish_runtime(state_dir, token, args.round, "running")
+            stdout, returncode, reason = drain_process(args, process, token)
+        except BaseException:
+            terminate_group(process)
+            process.wait()
+            remove_runtime_if_owned(state_dir, token, args.round)
+            raise
+    reason = settle_before_publication(args, token, reason)
+    result = classification(reason, returncode, stdout)
+    result.update({
+        "runId": (state_dir / "run-id").read_text().strip(),
+        "stateDir": str(state_dir),
+        "round": args.round,
+        "profile": args.profile,
+        "sandbox": args.sandbox,
+    })
+    publish_result(args, token, result)
+    return 0 if result["status"] == "OK" else 1
+
+
+def lease_acquire(args: argparse.Namespace) -> int:
+    state_dir = Path(args.state_dir)
+    token = acquire_lease_for_state(state_dir)
+    if not token:
+        return 1
+    print(token, flush=True)
+    return 0
+
+
+def lease_release(args: argparse.Namespace) -> int:
+    if os.environ.get("CODEX_EXEC_TEST_LEASE_RELEASE_FAIL") == "1":
+        return 1
+    return 0 if release_lease_for_state(Path(args.state_dir), args.token) else 1
+
+
+def abort_claim(args: argparse.Namespace) -> int:
+    state_dir = Path(args.state_dir)
+    deadline = time.monotonic() + CANCEL_WAIT_SECONDS
+    while time.monotonic() < deadline:
+        runtime_path = state_dir / "runtime.json"
+        runtime = read_object(runtime_path)
+        runtime_is_live = live_runtime(
+            runtime_path, time.time(), CANCEL_WAIT_SECONDS,
+        )
+        token = None if runtime_is_live else acquire_lease_for_state(state_dir)
+        if token:
+            print(token, flush=True)
+            return 0
+        ownership = runtime or lease_owner(state_dir)
+        if not valid_owner(ownership):
+            time.sleep(0.02)
+            continue
+        token = ownership["token"]
+        round_number = ownership["round"]
+        atomic_write(
+            state_dir / "cancel.request",
+            json.dumps({
+                "token": token,
+                "round": round_number,
+                "requestedAt": time.time(),
+            }, sort_keys=True) + "\n",
+        )
+        time.sleep(0.02)
+    return 1
+
+
+def live_lease(state_dir: Path, now: float, stale_seconds: float) -> bool:
+    owner = lease_owner(state_dir)
+    if not valid_owner(owner):
+        return False
+    acquired_at = owner.get("acquiredAt")
+    if not isinstance(acquired_at, (int, float)) or isinstance(acquired_at, bool):
+        return False
+    return math.isfinite(acquired_at) and 0 <= now - acquired_at < stale_seconds
+
+
+def claim_cleanup_lease(state_dir: Path, now: float, stale_seconds: float) -> str | None:
+    token = acquire_lease_for_state(state_dir, fallback_round=1)
+    if token:
+        return token
+    if live_lease(state_dir, now, stale_seconds):
+        return None
+    if live_runtime(state_dir / "runtime.json", now, stale_seconds):
+        return None
+    lease = lease_dir(state_dir)
+    quarantine = state_dir / f".stale-lease.{secrets.token_hex(8)}"
+    try:
+        lease.rename(quarantine)
+    except (FileNotFoundError, OSError):
+        return None
+    try:
+        return acquire_lease_for_state(state_dir, fallback_round=1)
+    finally:
+        shutil.rmtree(quarantine, ignore_errors=True)
+
+
+def live_runtime(runtime_path: Path, now: float, stale_seconds: float) -> bool:
+    runtime = read_object(runtime_path)
+    if not runtime:
+        return False
+    token = runtime.get("token")
+    round_number = runtime.get("round")
+    phase = runtime.get("phase")
+    heartbeat = runtime.get("heartbeat")
+    return bool(
+        isinstance(token, str) and OWNERSHIP_TOKEN.fullmatch(token)
+        and isinstance(round_number, int) and not isinstance(round_number, bool) and round_number >= 1
+        and phase in {"running", "settling"}
+        and isinstance(heartbeat, (int, float)) and not isinstance(heartbeat, bool)
+        and math.isfinite(heartbeat)
+        and 0 <= now - heartbeat < stale_seconds
+    )
+
+
+def cleanup(args: argparse.Namespace) -> int:
+    if not math.isfinite(args.stale_seconds) or args.stale_seconds <= 0 or args.max_delete < 0:
+        return 2
+    root = Path(args.state_root)
+    now = time.time()
+    removed = 0
+    candidates = []
+    for state_dir in root.glob("codex-exec.*"):
+        try:
+            candidates.append((state_dir.stat().st_mtime, state_dir))
+        except FileNotFoundError:
+            continue
+    candidates.sort(key=lambda candidate: candidate[0])
+    marker = os.environ.get("CODEX_EXEC_TEST_CLEANUP_PAUSE_MARKER")
+    if marker:
+        atomic_write(Path(marker), "listed\n")
+        time.sleep(0.3)
+    for _, state_dir in candidates:
+        if removed >= args.max_delete:
+            break
+        try:
+            preclaim_mtime = state_dir.stat().st_mtime
+            if now - preclaim_mtime < args.stale_seconds:
+                continue
+        except (FileNotFoundError, OSError):
+            continue
+        token = claim_cleanup_lease(state_dir, now, args.stale_seconds)
+        if not token:
+            continue
+        deleted = False
+        try:
+            try:
+                valid = (state_dir / "run-id").read_text().strip() == state_dir.name.removeprefix("codex-exec.")
+            except (FileNotFoundError, OSError):
+                continue
+            protected = (
+                (state_dir / "debug-retain").exists()
+                or live_runtime(state_dir / "runtime.json", time.time(), args.stale_seconds)
+            )
+            if valid and now - preclaim_mtime >= args.stale_seconds and not protected:
+                try:
+                    shutil.rmtree(state_dir)
+                except FileNotFoundError:
+                    continue
+                deleted = True
+                removed += 1
+        finally:
+            if not deleted and state_dir.exists():
+                release_lease_for_state(state_dir, token)
+    return 0
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser()
+    commands = root.add_subparsers(dest="action", required=True)
+    run = commands.add_parser("run")
+    run.add_argument("--state-dir", required=True)
+    run.add_argument("--round", required=True, type=int)
+    run.add_argument("--profile", required=True)
+    run.add_argument("--sandbox", required=True)
+    run.add_argument("--timeout", required=True, type=float)
+    run.add_argument("--probe-timeout", required=True, type=float)
+    run.add_argument("--prompt-file", required=True)
+    run.add_argument("--lease-token", required=True)
+    run.add_argument("command", nargs=argparse.REMAINDER)
+    acquire = commands.add_parser("lease-acquire")
+    acquire.add_argument("--state-dir", required=True)
+    release = commands.add_parser("lease-release")
+    release.add_argument("--state-dir", required=True)
+    release.add_argument("--token", required=True)
+    stop = commands.add_parser("abort-claim")
+    stop.add_argument("--state-dir", required=True)
+    stale = commands.add_parser("cleanup")
+    stale.add_argument("--state-root", required=True)
+    stale.add_argument("--stale-seconds", required=True, type=float)
+    stale.add_argument("--max-delete", required=True, type=int)
+    return root
+
+
+if __name__ == "__main__":
+    parsed = parser().parse_args()
+    actions = {
+        "run": run_round,
+        "lease-acquire": lease_acquire,
+        "lease-release": lease_release,
+        "abort-claim": abort_claim,
+        "cleanup": cleanup,
+    }
+    sys.exit(actions[parsed.action](parsed))

package/scripts/find-by-marker.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Find GitHub issues by one allowlisted, exact-value identity marker."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from board_config import ConfigError, load_board_config  # noqa: E402
+from marker_lib import (  # noqa: E402
+    UnknownMarkerKind, find_by_marker, reconcile_after_create,
+)
+
+GH_TIMEOUT_SECONDS = 30
+
+
+def _gh(args: list[str]) -> str:
+    try:
+        result = subprocess.run(
+            ["gh", *args], capture_output=True, text=True,
+            timeout=GH_TIMEOUT_SECONDS,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise RuntimeError(
+            f"gh api timed out after {GH_TIMEOUT_SECONDS}s") from exc
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or "gh api failed")
+    return result.stdout
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Find issues carrying an exact allowlisted identity marker")
+    parser.add_argument("--kind", required=True, help="marker kind")
+    parser.add_argument("--slug", required=True, help="exact marker value")
+    parser.add_argument("--created", type=int,
+                        help="post-create reconciliation for this issue number")
+    return parser
+
+
+def main(argv: list[str] | None = None, *, repo: str | None = None,
+         gh: Callable[[list[str]], str] = _gh) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        target_repo = repo or load_board_config()["repo"]
+        if args.created is None:
+            result = find_by_marker(target_repo, args.kind, args.slug, gh)
+        else:
+            result = reconcile_after_create(
+                target_repo, args.kind, args.slug, args.created, gh)
+    except UnknownMarkerKind as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except (ConfigError, RuntimeError, ValueError, json.JSONDecodeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps(result, separators=(",", ":")))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())