Skip to content

aiskillstore/marketplace / pending/cagdasyurekli/agy-worker

agy-worker

Unverified

Use when Codex or Claude Code should delegate repository exploration or implementation to Google Antigravity CLI (agy), then review, verify, repair, and deliver the result.

FileKindSize
README.mdmarkdown3.7 KB
SKILL.mdskill md12.5 KB
agents/openai.yamlconfig397 B
references/PROJECT_LIFECYCLE_AND_VERIFICATION.mdmarkdown25.6 KB
references/SECURITY_AND_COMPATIBILITY.mdmarkdown16.9 KB
references/TROUBLESHOOTING.mdmarkdown13.3 KB
runtime/agy-worker.shexecutablescript58.1 KB
runtime/delegation-policy.shexecutablescript293 B
runtime/doctor.shexecutablescript16.5 KB
runtime/evidence-report.shexecutablescript267 B
runtime/ground-truth.shexecutablescript2.9 KB
runtime/job.shexecutablescript266 B
runtime/model-selection.shexecutablescript262 B
runtime/qa-gate.shexecutablescript28.7 KB
runtime/schemas/delegation-policy.schema.jsonconfig2.6 KB
runtime/schemas/evidence-receipt.schema.jsonconfig2.5 KB
runtime/schemas/job-state.schema.jsonconfig3.6 KB
runtime/schemas/model-selection.schema.jsonconfig8.3 KB
runtime/schemas/worker-result.provider.schema.jsonconfig2.1 KB
runtime/schemas/worker-result.schema.jsonconfig3.0 KB
runtime/schemas/workflow-state.schema.jsonconfig3.7 KB
runtime/scripts/agy_dispatch.pyexecutablescript344.5 KB
runtime/scripts/agy_dispatch_containment.pyscript51.4 KB
runtime/scripts/agy_dispatch_verification.pyscript33.9 KB
runtime/scripts/agy_dispatch_worktree.pyscript220.6 KB
runtime/scripts/candidate_state.pyexecutablescript47.4 KB
runtime/scripts/delegation_policy.pyexecutablescript12.8 KB
runtime/scripts/evidence_receipt.pyexecutablescript52.9 KB
runtime/scripts/evidence_report.pyexecutablescript17.7 KB
runtime/scripts/job_lifecycle.pyexecutablescript89.0 KB
runtime/scripts/launch_authority.pyscript27.4 KB
runtime/scripts/model_selection.pyexecutablescript38.8 KB
runtime/scripts/transmission_preview.pyexecutablescript744 B
runtime/scripts/validate-envelope.pyexecutablescript6.5 KB
runtime/scripts/workflow.pyexecutablescript89.2 KB
runtime/verify-job.shexecutablescript261 B
runtime/workflow.shexecutablescript239 B
scripts/resolve-pipeline.shexecutablescript5.9 KB
skill-report.jsonconfig552.7 KB

runtime/scripts/evidence_report.py

View on GitHub
#!/usr/bin/env python3
"""Render a compact human report from one validated Evidence Receipt v2.

The stdout-only ``main(argv)`` path returns normally. File-output ``main(argv)``
is process-owning: it keeps signal rollback authority through ``os._exit(0)``.
Invoke file-output mode as a command/subprocess; do not embed it in a host process.
"""

from __future__ import annotations

import argparse
import os
from pathlib import Path
import secrets
import signal
import stat
import sys
from typing import Any, NoReturn

sys.dont_write_bytecode = True
SCRIPTS_ROOT = str(Path(__file__).resolve(strict=True).parent)
if SCRIPTS_ROOT not in sys.path:
    sys.path.insert(0, SCRIPTS_ROOT)

from evidence_receipt import (  # noqa: E402
    ValidationFailure,
    load_schema,
    parse_json_bytes,
    published_bytes,
    read_real_file,
    require_sha,
    sha256_bytes,
    validate_receipt,
)


MAX_REPORT_BYTES = 64 * 1024
SIGNALS = (signal.SIGHUP, signal.SIGINT, signal.SIGTERM)
REPORT_FORMATS = ("text", "json", "markdown", "github-step-summary")


class UsageFailure(ValueError):
    pass


class PublicationFailure(ValueError):
    pass


class Interrupted(BaseException):
    def __init__(self, signal_number: int) -> None:
        self.signal_number = signal_number


class PublishedReport:
    def __init__(
        self,
        parent_fd: int,
        final_name: str,
        identity: tuple[int, int],
        prior_mask: set[int | signal.Signals],
    ) -> None:
        self.parent_fd = parent_fd
        self.final_name = final_name
        self.identity = identity
        self.prior_mask = prior_mask

    def rollback(self) -> None:
        _owned_unlink(self.parent_fd, self.final_name, self.identity)
        os.fsync(self.parent_fd)

    def close(self) -> None:
        if self.parent_fd >= 0:
            os.close(self.parent_fd)
            self.parent_fd = -1


class Parser(argparse.ArgumentParser):
    def error(self, message: str) -> NoReturn:
        del message
        self.print_usage(sys.stderr)
        self.exit(64, "evidence-report: invalid arguments\n")


def one(parser: Parser, values: list[str] | None, flag: str, required: bool) -> str | None:
    if not values:
        if required:
            parser.error(f"{flag} is required")
        return None
    if len(values) != 1:
        parser.error(f"{flag} must be provided exactly once")
    return values[0]


def _yes(value: bool) -> str:
    return "yes" if value else "no"


def build_report(receipt: dict[str, Any]) -> dict[str, Any]:
    """Return the bounded report representation, never the raw receipt."""
    return {
        "caller_selection_bound": "caller_selection" in receipt,
        "envelope_sha256": receipt["envelope_sha256"],
        "final_candidate_state_sha256": receipt["final_candidate_state_sha256"],
        "gate_authority": receipt["gate_authority"],
        "gate_exit": receipt["gate_exit"],
        "gate_outcome": receipt["gate_outcome"],
        "human_review_required_before_acceptance": True,
        "initial_candidate_state_sha256": receipt["initial_candidate_state_sha256"],
        "integrity": {
            "signed": False,
            "tamper_evident": False,
        },
        "kind": "agy-worker-evidence-report",
        "path_policy_sha256": receipt["path_policy_sha256"],
        "resolved_base": receipt["resolved_base"],
        "schema_version": 2,
        "verdict": receipt["verdict"],
        "verification_labels": [entry["label"] for entry in receipt["verifiers"]],
    }


def _safe_markdown_atom(value: str) -> str:
    if not value or any(
        character not in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._-"
        for character in value
    ):
        raise ValidationFailure("report value is not safe for Markdown")
    return value


def _validate_rendered_payload(payload: bytes, output_format: str) -> bytes:
    if not payload or len(payload) > MAX_REPORT_BYTES:
        raise ValidationFailure("rendered report is empty or oversized")
    try:
        text = payload.decode("ascii")
    except UnicodeDecodeError as exc:
        raise ValidationFailure("rendered report is not ASCII") from exc
    if "\r" in text or "\x00" in text or text.startswith("::") or "\n::" in text:
        raise ValidationFailure("rendered report contains workflow-command syntax")
    if output_format in ("markdown", "github-step-summary") and any(
        marker in text for marker in ("](", "<")
    ):
        raise ValidationFailure("rendered report contains unsafe Markdown syntax")
    return payload


def render_json(receipt: dict[str, Any]) -> bytes:
    return published_bytes(build_report(receipt))


def render_text(receipt: dict[str, Any]) -> bytes:
    labels = [entry["label"] for entry in receipt["verifiers"]]
    lines = [
        "Evidence Report v2",
        f"Verdict: {receipt['verdict']}",
        f"Gate outcome: {receipt['gate_outcome']} (exit {receipt['gate_exit']})",
        f"Gate authority: {receipt['gate_authority']}",
        f"Resolved base: {receipt['resolved_base']}",
        f"Envelope SHA-256: {receipt['envelope_sha256']}",
        f"Path policy SHA-256: {receipt['path_policy_sha256']}",
        f"Initial candidate state SHA-256: {receipt['initial_candidate_state_sha256']}",
        f"Final candidate state SHA-256: {receipt['final_candidate_state_sha256']}",
        f"Verification labels ({len(labels)}): {', '.join(labels)}",
        f"Caller selection bound: {_yes('caller_selection' in receipt)}",
        "Integrity: unsigned and not tamper-evident",
        "Human review: required before calling a gate-passed candidate accepted.",
    ]
    return ("\n".join(lines) + "\n").encode("ascii")


def render_markdown(receipt: dict[str, Any], *, step_summary: bool = False) -> bytes:
    labels = [_safe_markdown_atom(entry["label"]) for entry in receipt["verifiers"]]
    label_text = ", ".join(f"`{label}`" for label in labels)
    heading = "# Evidence Report v2 (GitHub Step Summary)" if step_summary else "# Evidence Report v2"
    lines = [
        heading,
        "",
        f"- Verdict: `{_safe_markdown_atom(receipt['verdict'])}`",
        f"- Gate outcome: `{_safe_markdown_atom(receipt['gate_outcome'])}` (exit `{receipt['gate_exit']}`)",
        f"- Gate authority: `{_safe_markdown_atom(receipt['gate_authority'])}`",
        f"- Resolved base: `{_safe_markdown_atom(receipt['resolved_base'])}`",
        f"- Envelope SHA-256: `{_safe_markdown_atom(receipt['envelope_sha256'])}`",
        f"- Path policy SHA-256: `{_safe_markdown_atom(receipt['path_policy_sha256'])}`",
        f"- Initial candidate state SHA-256: `{_safe_markdown_atom(receipt['initial_candidate_state_sha256'])}`",
        f"- Final candidate state SHA-256: `{_safe_markdown_atom(receipt['final_candidate_state_sha256'])}`",
        f"- Verification labels ({len(labels)}): {label_text}",
        f"- Caller selection bound: **{_yes('caller_selection' in receipt)}**",
        "- Integrity: **unsigned and not tamper-evident**",
        "",
        "> Human review is required before calling a gate-passed candidate accepted.",
    ]
    return ("\n".join(lines) + "\n").encode("ascii")


def _read_bound_json(path: Path, label: str) -> Any:
    return parse_json_bytes(read_real_file(path, label), label)


def validate_bindings(
    receipt: dict[str, Any],
    *,
    envelope: str | None,
    selection: str | None,
    initial_digest: str | None,
    final_digest: str | None,
) -> None:
    if envelope is not None:
        if sha256_bytes(read_real_file(Path(envelope), "bound envelope")) != receipt["envelope_sha256"]:
            raise ValidationFailure("bound envelope digest does not match receipt")
    if selection is not None:
        if _read_bound_json(Path(selection), "bound selection") != receipt.get("caller_selection"):
            raise ValidationFailure("bound selection does not match receipt")
    if initial_digest is not None:
        require_sha(initial_digest, "bound initial state digest")
        if initial_digest != receipt["initial_candidate_state_sha256"]:
            raise ValidationFailure("bound initial state digest does not match receipt")
    if final_digest is not None:
        require_sha(final_digest, "bound final state digest")
        if final_digest != receipt["final_candidate_state_sha256"]:
            raise ValidationFailure("bound final state digest does not match receipt")


def _canonical_parent(target: Path) -> tuple[Path, str]:
    if not target.is_absolute() or "\n" in str(target) or "\r" in str(target):
        raise UsageFailure("--output must be one canonical absolute path")
    if target.exists() or target.is_symlink():
        raise UsageFailure("--output must name a new path and never overwrites")
    parent = target.parent
    if not parent.is_dir() or parent.is_symlink():
        raise UsageFailure("--output parent must be one real directory")
    canonical = Path(os.path.realpath(parent))
    if Path(os.path.realpath(target)) != canonical / target.name or target.name in ("", ".", ".."):
        raise UsageFailure("--output path must be canonical")
    return canonical, target.name


def _owned_unlink(parent_fd: int, name: str, identity: tuple[int, int]) -> None:
    try:
        current = os.stat(name, dir_fd=parent_fd, follow_symlinks=False)
    except FileNotFoundError:
        return
    if stat.S_ISREG(current.st_mode) and (current.st_dev, current.st_ino) == identity:
        os.unlink(name, dir_fd=parent_fd)


def _pending_signal() -> int | None:
    if not hasattr(signal, "sigpending"):
        return None
    pending = sorted(set(signal.sigpending()).intersection(SIGNALS))
    return pending[0] if pending else None


def _restore_mask_preserving(
    prior_mask: set[int | signal.Signals], first_signal: int | None, *, raise_after: bool = True
) -> None:
    pending = _pending_signal()
    if first_signal is None:
        first_signal = pending
    handlers = {number: signal.getsignal(number) for number in SIGNALS}
    for number in SIGNALS:
        signal.signal(number, signal.SIG_IGN)
    signal.pthread_sigmask(signal.SIG_SETMASK, prior_mask)
    for number, handler in handlers.items():
        signal.signal(number, handler)
    if first_signal is not None and raise_after:
        raise Interrupted(first_signal)


def _completion_checkpoint() -> None:
    """Test-only callable seam; production has no environment or CLI override."""


def _before_atomic_exit_checkpoint() -> None:
    """Test-only callable seam after unmasking and before process exit."""


def _atomic_success_exit() -> NoReturn:
    os._exit(0)


def _complete_published_success(publication: PublishedReport) -> NoReturn:
    # Keep the rollback handlers and the inode-pinned parent descriptor alive until
    # the process is gone. A signal pending before this transition is delivered by
    # the unmask; a signal after it either runs the handler or loses the race to
    # process termination. There is no ignored-signal or normal-return window.
    signal.pthread_sigmask(signal.SIG_SETMASK, publication.prior_mask)
    _before_atomic_exit_checkpoint()
    _atomic_success_exit()


def publish_new(target: Path, payload: bytes) -> PublishedReport:
    prior_mask = signal.pthread_sigmask(signal.SIG_BLOCK, SIGNALS)
    parent_fd = -1
    final_name = ""
    temporary = ""
    descriptor = -1
    identity: tuple[int, int] | None = None
    final_identity: tuple[int, int] | None = None
    try:
        parent, final_name = _canonical_parent(target)
        parent_fd = os.open(parent, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
        temporary = f".{final_name}.evidence-report.{secrets.token_hex(12)}.tmp"
        descriptor = os.open(
            temporary,
            os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
            0o600,
            dir_fd=parent_fd,
        )
        os.fchmod(descriptor, 0o600)
        view = memoryview(payload)
        while view:
            written = os.write(descriptor, view)
            if written <= 0:
                raise PublicationFailure("report write failed")
            view = view[written:]
        os.fsync(descriptor)
        metadata = os.fstat(descriptor)
        identity = (metadata.st_dev, metadata.st_ino)
        os.close(descriptor)
        descriptor = -1
        os.link(
            temporary,
            final_name,
            src_dir_fd=parent_fd,
            dst_dir_fd=parent_fd,
            follow_symlinks=False,
        )
        final_identity = identity
        linked = os.stat(final_name, dir_fd=parent_fd, follow_symlinks=False)
        if (linked.st_dev, linked.st_ino) != identity or stat.S_IMODE(linked.st_mode) != 0o600:
            raise PublicationFailure("published report identity changed")
        os.fsync(parent_fd)
        os.unlink(temporary, dir_fd=parent_fd)
        identity = None
        os.fsync(parent_fd)
        assert final_identity is not None
        return PublishedReport(parent_fd, final_name, final_identity, prior_mask)
    except BaseException as error:
        first_signal = error.signal_number if isinstance(error, Interrupted) else None
        cleanup_failed = False
        if descriptor >= 0:
            try:
                os.close(descriptor)
            except OSError:
                cleanup_failed = True
        for name, owned_identity in ((final_name, final_identity), (temporary, identity)):
            if parent_fd >= 0 and name and owned_identity is not None:
                try:
                    _owned_unlink(parent_fd, name, owned_identity)
                except OSError:
                    cleanup_failed = True
        if parent_fd >= 0:
            try:
                os.fsync(parent_fd)
            except OSError:
                cleanup_failed = True
        if parent_fd >= 0:
            os.close(parent_fd)
            parent_fd = -1
        _restore_mask_preserving(prior_mask, first_signal)
        if cleanup_failed:
            raise PublicationFailure("report cleanup failed") from error
        raise


def run(arguments: list[str]) -> PublishedReport | None:
    parser = Parser(prog="evidence-report.sh")
    parser.add_argument("--receipt", action="append")
    parser.add_argument("--format", action="append", choices=REPORT_FORMATS)
    parser.add_argument("--output", action="append")
    parser.add_argument("--envelope", action="append")
    parser.add_argument("--selection", action="append")
    parser.add_argument("--initial-state-digest", action="append")
    parser.add_argument("--final-state-digest", action="append")
    parsed = parser.parse_args(arguments)
    receipt_path = one(parser, parsed.receipt, "--receipt", True)
    output_format = one(parser, parsed.format, "--format", True)
    output_path = one(parser, parsed.output, "--output", False)
    envelope = one(parser, parsed.envelope, "--envelope", False)
    selection = one(parser, parsed.selection, "--selection", False)
    initial_digest = one(parser, parsed.initial_state_digest, "--initial-state-digest", False)
    final_digest = one(parser, parsed.final_state_digest, "--final-state-digest", False)
    assert receipt_path is not None and output_format is not None
    runtime_root = Path(__file__).resolve(strict=True).parent.parent
    schema = load_schema(runtime_root / "schemas/evidence-receipt.schema.json")
    receipt = validate_receipt(
        _read_bound_json(Path(receipt_path), "receipt"),
        schema,
    )
    validate_bindings(
        receipt,
        envelope=envelope,
        selection=selection,
        initial_digest=initial_digest,
        final_digest=final_digest,
    )
    if output_format == "text":
        payload = render_text(receipt)
    elif output_format == "json":
        payload = render_json(receipt)
    else:
        payload = render_markdown(
            receipt, step_summary=output_format == "github-step-summary"
        )
    payload = _validate_rendered_payload(payload, output_format)
    if output_path is None:
        sys.stdout.buffer.write(payload)
        sys.stdout.buffer.flush()
    else:
        return publish_new(Path(output_path), payload)
    return None


def main(argv: list[str] | None = None) -> int:
    entry_mask = signal.pthread_sigmask(signal.SIG_BLOCK, SIGNALS)
    previous = {number: signal.getsignal(number) for number in SIGNALS}
    disarmed = False
    publication: PublishedReport | None = None

    def interrupt(number: int, _frame: Any) -> None:
        raise Interrupted(number)

    try:
        for number in SIGNALS:
            signal.signal(number, interrupt)
        signal.pthread_sigmask(signal.SIG_SETMASK, entry_mask)
        publication = run(list(sys.argv[1:] if argv is None else argv))
        if publication is not None:
            _completion_checkpoint()
            _complete_published_success(publication)
        return 0
    except Interrupted as exc:
        blocked = signal.pthread_sigmask(signal.SIG_BLOCK, SIGNALS)
        restore_mask = blocked
        if publication is not None and publication.parent_fd >= 0:
            restore_mask = publication.prior_mask
            try:
                publication.rollback()
            finally:
                publication.close()
        _restore_mask_preserving(
            restore_mask, exc.signal_number, raise_after=False
        )
        print("evidence-report: interrupted", file=sys.stderr)
        return 128 + exc.signal_number
    except UsageFailure as exc:
        print(f"evidence-report: {exc}", file=sys.stderr)
        return 64
    except ValidationFailure:
        print("evidence-report: receipt or trusted binding is invalid", file=sys.stderr)
        return 1
    except (OSError, PublicationFailure):
        print("evidence-report: output publication failed", file=sys.stderr)
        return 74
    finally:
        if not disarmed:
            signal.pthread_sigmask(signal.SIG_BLOCK, SIGNALS)
            for number, handler in previous.items():
                signal.signal(number, handler)
            signal.pthread_sigmask(signal.SIG_SETMASK, entry_mask)


if __name__ == "__main__":
    raise SystemExit(main())
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall