Skip to content

hoatv2211/GameStudio-CodexKIT / skills/studio-goal-progress

studio-goal-progress

Verified

Use when a KIT-managed Codex or Hermes Goal needs evidence-backed percentage, ETA range, live read-only progress views, or portable append-only progress recovery.

scripts/goal_progress_core.py

View on GitHub
# Generated by scripts/sync_skill_resources.py. Do not edit manually.

from __future__ import annotations

import hashlib
import json
import re
import statistics
from datetime import datetime, timezone


class GoalProgressError(ValueError):
    pass


STATE_CHANGING_EVENTS = frozenset(
    {
        "plan.revised",
        "packet.started",
        "packet.waiting_input",
        "packet.resumed",
        "packet.blocked",
        "packet.failed",
        "packet.retry_started",
        "packet.verified",
        "goal.completed",
        "goal.cancelled",
    }
)

PACKET_TRANSITIONS = {
    "packet.started": ({"queued"}, "running"),
    "packet.waiting_input": ({"running"}, "waiting_input"),
    "packet.resumed": ({"waiting_input"}, "running"),
    "packet.blocked": ({"running", "waiting_input"}, "blocked"),
    "packet.failed": ({"running"}, "failed"),
    "packet.retry_started": ({"blocked", "failed"}, "running"),
    "packet.verified": ({"running"}, "verified"),
}

EVENT_SOURCES = frozenset({"kit_workflow", "codex_app_server", "operator_note"})
EVENT_TYPES = frozenset(
    {
        "goal.started",
        *STATE_CHANGING_EVENTS,
        "evidence.observed",
        "context.refreshed",
        "runtime.heartbeat",
    }
)
PACKET_STATES = frozenset(
    {"queued", "running", "waiting_input", "blocked", "failed", "verified", "skipped"}
)
INFORMATIONAL_SOURCES = frozenset({"codex_app_server", "operator_note"})
GOAL_WORKFLOW_ID = "studio-goal-progress"
GOAL_OWNER = "main-thread"

MANIFEST_KEYS = frozenset(
    {
        "schema_version",
        "goal_id",
        "title",
        "repository_root",
        "repository_snapshot",
        "created_at",
        "plan_version",
        "scope",
        "do_not_touch",
        "packets",
        "final_verification_required",
        "runtime_bindings",
        "timing_policy",
    }
)
MANIFEST_REQUIRED_KEYS = MANIFEST_KEYS - {"runtime_bindings"}
PACKET_KEYS = frozenset(
    {
        "id",
        "workflow_id",
        "owner",
        "objective",
        "progress_weight",
        "dependencies",
        "completion_criteria",
        "required_evidence",
        "estimate_seconds",
        "owned_paths",
        "excluded_paths",
    }
)
PACKET_REQUIRED_KEYS = PACKET_KEYS - {"estimate_seconds"}
EVENT_KEYS = frozenset(
    {
        "schema_version",
        "event_id",
        "goal_id",
        "plan_version",
        "sequence",
        "emitted_at",
        "writer_epoch_id",
        "monotonic_offset_ms",
        "source",
        "event_type",
        "packet_id",
        "payload",
        "authority",
        "summary",
        "evidence",
        "raw_log_ref",
        "record_hash",
    }
)
AUTHORITY_KEYS = frozenset(
    {
        "kind",
        "id",
        "workflow_id",
        "owner",
        "runtime_binding",
        "packet_id",
        "expected_prior_state",
    }
)
EVIDENCE_KEYS = frozenset(
    {"id", "label", "kind", "summary", "command", "exit_code", "artifact_path", "sha256"}
)
CONTEXT_FACT_FIELDS = (
    "blockers",
    "failures",
    "changed_files",
    "decisions",
    "commands",
    "timing",
    "evidence_labels",
    "indivisible_paths",
)
CONTEXT_FACT_KEYS = frozenset(CONTEXT_FACT_FIELDS)
CONTEXT_FAILURE_KEYS = frozenset({"summary", "command", "artifact_path"})
CONTEXT_MAX_ITEMS = 20
CONTEXT_TEXT_LIMIT = 500
SHA256_PATTERN = re.compile(r"^[a-f0-9]{64}$")
UTC_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$")
CONTROL_CHARACTERS = re.compile(r"[\x00-\x08\x0b-\x1f\x7f]")
SECRET_ASSIGNMENT = re.compile(
    r"\b(?:authorization\s*(?:=|:)\s*(?:bearer\s+)?|"
    r"(?:api[-_.]?key|client[-_.]?secret|access[-_.]?token|"
    r"aws[-_.]?secret[-_.]?access[-_.]?key|key|token|password|passwd|secret)"
    r"\s*(?:=|:)\s*)"
    r"(?:\"[^\"]*\"|'[^']*'|\S+)",
    re.IGNORECASE,
)

VERIFICATION_CONTRACT_FIELDS = frozenset(
    {
        "workflow_id",
        "owner",
        "objective",
        "progress_weight",
        "dependencies",
        "completion_criteria",
        "required_evidence",
        "owned_paths",
        "excluded_paths",
    }
)


def canonical_json(value: object) -> str:
    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=True)


def sha256_json(value: object, *, omit: frozenset[str] = frozenset()) -> str:
    payload = value
    if isinstance(value, dict) and omit:
        payload = {key: item for key, item in value.items() if key not in omit}
    return hashlib.sha256(canonical_json(payload).encode("utf-8")).hexdigest()


def _fail(message: str) -> None:
    raise GoalProgressError(message)


def _exact_keys(value: object, expected: frozenset[str], name: str) -> dict[str, object]:
    if not isinstance(value, dict):
        _fail(f"{name} must be an object")
    actual = frozenset(value)
    if actual != expected:
        missing = sorted(expected - actual)
        extra = sorted(actual - expected)
        _fail(f"{name} keys mismatch; missing={missing}, extra={extra}")
    return value


def _object_with_keys(
    value: object,
    *,
    required: frozenset[str],
    allowed: frozenset[str],
    name: str,
) -> dict[str, object]:
    if not isinstance(value, dict):
        _fail(f"{name} must be an object")
    actual = frozenset(value)
    missing = required - actual
    extra = actual - allowed
    if missing or extra:
        _fail(f"{name} keys mismatch; missing={sorted(missing)}, extra={sorted(extra)}")
    return value


def _integer(value: object, name: str, *, minimum: int | None = None) -> int:
    if isinstance(value, bool) or not isinstance(value, int):
        _fail(f"{name} must be an integer")
    if minimum is not None and value < minimum:
        _fail(f"{name} must be at least {minimum}")
    return value


def _text(value: object, name: str) -> str:
    if not isinstance(value, str) or not value.strip():
        _fail(f"{name} must be a non-empty string")
    return value


def _text_list(value: object, name: str, *, nonempty: bool = False) -> list[str]:
    if not isinstance(value, list) or (nonempty and not value):
        _fail(f"{name} must be {'a non-empty ' if nonempty else 'an '}array")
    for index, item in enumerate(value):
        _text(item, f"{name}[{index}]")
    return value


def _runtime_binding(value: object, name: str) -> dict[str, object]:
    binding = _exact_keys(value, frozenset({"kind", "id"}), name)
    if binding["kind"] not in {"codex_thread", "hermes_session"}:
        _fail(f"{name}.kind must be codex_thread or hermes_session")
    _text(binding["id"], f"{name}.id")
    return binding


def _validate_evidence(value: object, name: str) -> dict[str, object]:
    evidence = _exact_keys(value, EVIDENCE_KEYS, name)
    _text(evidence["id"], f"{name}.id")
    if evidence["label"] not in {"Verified", "Snapshot", "Unverified", "BLOCKED"}:
        _fail(f"{name}.label is invalid")
    kind = evidence["kind"]
    _text(evidence["summary"], f"{name}.summary")
    if kind == "command":
        _text(evidence["command"], f"{name}.command")
        _integer(evidence["exit_code"], f"{name}.exit_code")
        if evidence["artifact_path"] is not None or evidence["sha256"] is not None:
            _fail(f"{name} command evidence cannot contain artifact fields")
    elif kind == "artifact":
        if evidence["command"] is not None or evidence["exit_code"] is not None:
            _fail(f"{name} artifact evidence cannot contain command fields")
        _text(evidence["artifact_path"], f"{name}.artifact_path")
        if not isinstance(evidence["sha256"], str) or not SHA256_PATTERN.fullmatch(
            evidence["sha256"]
        ):
            _fail(f"{name}.sha256 must be a lowercase SHA-256")
    else:
        _fail(f"{name}.kind is invalid")
    return evidence


def _context_text(value: object, name: str) -> str:
    text = _text(value, name)
    if len(text) > CONTEXT_TEXT_LIMIT:
        _fail(f"{name} exceeds {CONTEXT_TEXT_LIMIT} characters")
    sanitized, warnings = sanitize_summary(text, limit=CONTEXT_TEXT_LIMIT)
    if warnings or sanitized != text:
        _fail(f"{name} must be sanitized before submission")
    return text


def _context_text_list(value: object, name: str) -> list[str]:
    if not isinstance(value, list):
        _fail(f"{name} must be an array")
    if len(value) > CONTEXT_MAX_ITEMS:
        _fail(f"{name} exceeds {CONTEXT_MAX_ITEMS} items")
    return [_context_text(item, f"{name}[{index}]") for index, item in enumerate(value)]


def _validate_context_payload(value: object, name: str) -> dict[str, object]:
    payload = _exact_keys(value, CONTEXT_FACT_KEYS, name)
    for field in (
        "blockers",
        "changed_files",
        "decisions",
        "commands",
        "timing",
        "indivisible_paths",
    ):
        _context_text_list(payload[field], f"{name}.{field}")
    labels = _context_text_list(payload["evidence_labels"], f"{name}.evidence_labels")
    if any(label not in {"Verified", "Snapshot", "Unverified", "BLOCKED"} for label in labels):
        _fail(f"{name}.evidence_labels contains an invalid evidence label")
    failures = payload["failures"]
    if not isinstance(failures, list):
        _fail(f"{name}.failures must be an array")
    if len(failures) > CONTEXT_MAX_ITEMS:
        _fail(f"{name}.failures exceeds {CONTEXT_MAX_ITEMS} items")
    for index, failure in enumerate(failures):
        item = _object_with_keys(
            failure,
            required=frozenset({"summary"}),
            allowed=CONTEXT_FAILURE_KEYS,
            name=f"{name}.failures[{index}]",
        )
        _context_text(item["summary"], f"{name}.failures[{index}].summary")
        for field in ("command", "artifact_path"):
            if field in item:
                _context_text(item[field], f"{name}.failures[{index}].{field}")
    return payload


def validate_manifest(manifest: dict[str, object]) -> None:
    value = _object_with_keys(
        manifest,
        required=MANIFEST_REQUIRED_KEYS,
        allowed=MANIFEST_KEYS,
        name="manifest",
    )
    if value["schema_version"] != 1 or isinstance(value["schema_version"], bool):
        _fail("manifest.schema_version must equal integer 1")
    _text(value["goal_id"], "manifest.goal_id")
    _text(value["title"], "manifest.title")
    _text(value["repository_root"], "manifest.repository_root")
    snapshot = _text(value["repository_snapshot"], "manifest.repository_snapshot")
    if not re.fullmatch(r"[A-Za-z0-9._-]+@[a-f0-9]{40}", snapshot):
        _fail("manifest.repository_snapshot is invalid")
    created_at = _text(value["created_at"], "manifest.created_at")
    if not UTC_PATTERN.fullmatch(created_at):
        _fail("manifest.created_at must be a UTC Z timestamp")
    _integer(value["plan_version"], "manifest.plan_version", minimum=1)
    _text_list(value["scope"], "manifest.scope", nonempty=True)
    _text_list(value["do_not_touch"], "manifest.do_not_touch")
    _text_list(
        value["final_verification_required"],
        "manifest.final_verification_required",
        nonempty=True,
    )
    final_requirements = value["final_verification_required"]
    if len(final_requirements) != len(set(final_requirements)):
        _fail("manifest.final_verification_required contains duplicate tokens")

    bindings = value.get("runtime_bindings", [])
    if not isinstance(bindings, list):
        _fail("manifest.runtime_bindings must be an array")
    for index, binding in enumerate(bindings):
        _runtime_binding(binding, f"manifest.runtime_bindings[{index}]")

    timing = _exact_keys(
        value["timing_policy"],
        frozenset({"max_active_timed_packets"}),
        "manifest.timing_policy",
    )
    maximum = _integer(
        timing["max_active_timed_packets"],
        "manifest.timing_policy.max_active_timed_packets",
        minimum=1,
    )
    if maximum != 1:
        _fail("manifest.timing_policy.max_active_timed_packets must equal 1")

    packets = value["packets"]
    if not isinstance(packets, list) or not packets:
        _fail("manifest.packets must be a non-empty array")
    packet_ids: set[str] = set()
    dependencies_by_id: dict[str, list[str]] = {}
    for index, item in enumerate(packets):
        packet = _object_with_keys(
            item,
            required=PACKET_REQUIRED_KEYS,
            allowed=PACKET_KEYS,
            name=f"manifest.packets[{index}]",
        )
        packet_id = _text(packet["id"], f"manifest.packets[{index}].id")
        if packet_id in packet_ids:
            _fail(f"duplicate packet id: {packet_id}")
        packet_ids.add(packet_id)
        _text(packet["workflow_id"], f"manifest.packets[{index}].workflow_id")
        _text(packet["owner"], f"manifest.packets[{index}].owner")
        _text(packet["objective"], f"manifest.packets[{index}].objective")
        _integer(packet["progress_weight"], f"manifest.packets[{index}].progress_weight", minimum=1)
        dependencies = _text_list(packet["dependencies"], f"manifest.packets[{index}].dependencies")
        if len(dependencies) != len(set(dependencies)):
            _fail(f"manifest.packets[{index}].dependencies contains duplicates")
        dependencies_by_id[packet_id] = dependencies
        _text_list(
            packet["completion_criteria"],
            f"manifest.packets[{index}].completion_criteria",
            nonempty=True,
        )
        _text_list(
            packet["required_evidence"],
            f"manifest.packets[{index}].required_evidence",
            nonempty=True,
        )
        estimate_value = packet.get("estimate_seconds")
        if estimate_value is not None:
            estimate = _exact_keys(
                estimate_value,
                frozenset({"low", "high"}),
                f"manifest.packets[{index}].estimate_seconds",
            )
            low = _integer(
                estimate["low"],
                f"manifest.packets[{index}].estimate_seconds.low",
                minimum=0,
            )
            high = _integer(
                estimate["high"],
                f"manifest.packets[{index}].estimate_seconds.high",
                minimum=0,
            )
            if low > high:
                _fail(
                    f"manifest.packets[{index}].estimate_seconds.low must be less than or equal to "
                    f"manifest.packets[{index}].estimate_seconds.high"
                )
        _text_list(packet["owned_paths"], f"manifest.packets[{index}].owned_paths")
        _text_list(packet["excluded_paths"], f"manifest.packets[{index}].excluded_paths")

    for packet_id, dependencies in dependencies_by_id.items():
        for dependency in dependencies:
            if dependency not in packet_ids:
                _fail(f"missing dependency {dependency} for packet {packet_id}")

    visiting: set[str] = set()
    visited: set[str] = set()

    def visit(packet_id: str) -> None:
        if packet_id in visiting:
            _fail(f"dependency cycle includes packet {packet_id}")
        if packet_id in visited:
            return
        visiting.add(packet_id)
        for dependency in dependencies_by_id[packet_id]:
            visit(dependency)
        visiting.remove(packet_id)
        visited.add(packet_id)

    for packet_id in dependencies_by_id:
        visit(packet_id)


def validate_accepted_event(event: dict[str, object]) -> None:
    value = _exact_keys(event, EVENT_KEYS, "event")
    if value["schema_version"] != 1 or isinstance(value["schema_version"], bool):
        _fail("event.schema_version must equal integer 1")
    _text(value["event_id"], "event.event_id")
    _text(value["goal_id"], "event.goal_id")
    _integer(value["plan_version"], "event.plan_version", minimum=1)
    _integer(value["sequence"], "event.sequence", minimum=1)
    emitted_at = _text(value["emitted_at"], "event.emitted_at")
    if not UTC_PATTERN.fullmatch(emitted_at):
        _fail("event.emitted_at must be a UTC Z timestamp")
    _text(value["writer_epoch_id"], "event.writer_epoch_id")
    _integer(value["monotonic_offset_ms"], "event.monotonic_offset_ms", minimum=0)
    if value["source"] not in EVENT_SOURCES:
        _fail("event.source is invalid")
    event_type = value["event_type"]
    if event_type not in EVENT_TYPES:
        _fail("event.event_type is invalid")
    _text(value["summary"], "event.summary")
    if value["raw_log_ref"] is not None:
        _text(value["raw_log_ref"], "event.raw_log_ref")
    evidence = value["evidence"]
    if not isinstance(evidence, list):
        _fail("event.evidence must be an array")
    evidence_ids: set[str] = set()
    for index, item in enumerate(evidence):
        record = _validate_evidence(item, f"event.evidence[{index}]")
        evidence_id = str(record["id"])
        if evidence_id in evidence_ids:
            _fail(f"duplicate evidence id in event: {evidence_id}")
        evidence_ids.add(evidence_id)

    record_hash = value["record_hash"]
    if not isinstance(record_hash, str) or not SHA256_PATTERN.fullmatch(record_hash):
        _fail("event.record_hash must be a lowercase SHA-256")
    expected_hash = sha256_json(value, omit=frozenset({"record_hash"}))
    if record_hash != expected_hash:
        _fail("event.record_hash does not match canonical event content")

    payload = value["payload"]
    if not isinstance(payload, dict):
        _fail("event.payload must be an object")

    if event_type == "goal.started":
        _exact_keys(payload, frozenset({"manifest"}), "event.payload")
        if value["packet_id"] is not None or value["authority"] is not None:
            _fail("goal.started must not have packet_id or authority")
        validate_manifest(payload["manifest"])
    elif event_type == "plan.revised":
        _object_with_keys(
            payload,
            required=frozenset(
                {"manifest", "previous_manifest_hash", "new_manifest_hash"}
            ),
            allowed=frozenset(
                {
                    "manifest",
                    "previous_manifest_hash",
                    "new_manifest_hash",
                    "revision_reason",
                    "approval_ref",
                }
            ),
            name="event.payload",
        )
        if value["packet_id"] is not None:
            _fail("plan.revised must not have packet_id")
        validate_manifest(payload["manifest"])
        for hash_name in ("previous_manifest_hash", "new_manifest_hash"):
            if hash_name in payload and (
                not isinstance(payload[hash_name], str)
                or not SHA256_PATTERN.fullmatch(payload[hash_name])
            ):
                _fail(f"event.payload.{hash_name} must be a lowercase SHA-256")
        for text_name in ("revision_reason", "approval_ref"):
            if text_name in payload:
                _text(payload[text_name], f"event.payload.{text_name}")
    elif event_type in PACKET_TRANSITIONS:
        required = {"packet_id", "state"}
        allowed = {"packet_id", "state"}
        if event_type == "packet.verified":
            required.add("evidence_ids")
            allowed.add("evidence_ids")
        _object_with_keys(
            payload,
            required=frozenset(required),
            allowed=frozenset(allowed),
            name="event.payload",
        )
        packet_id = _text(value["packet_id"], "event.packet_id")
        if payload["packet_id"] != packet_id:
            _fail("event.payload.packet_id must match event.packet_id")
        _, result_state = PACKET_TRANSITIONS[event_type]
        if payload["state"] != result_state:
            _fail(f"event.payload.state must be {result_state} for {event_type}")
        if event_type == "packet.verified":
            evidence_ids = _text_list(
                payload["evidence_ids"],
                "event.payload.evidence_ids",
                nonempty=True,
            )
            if len(evidence_ids) != len(set(evidence_ids)):
                _fail("event.payload.evidence_ids contains duplicates")
    elif event_type == "evidence.observed":
        _exact_keys(
            payload,
            frozenset(
                {"workflow_id", "packet_id", "runtime_binding", "required_evidence_kind"}
            ),
            "event.payload",
        )
        _text(payload["workflow_id"], "event.payload.workflow_id")
        packet_id = _text(payload["packet_id"], "event.payload.packet_id")
        if value["packet_id"] != packet_id:
            _fail("event.payload.packet_id must match event.packet_id")
        _runtime_binding(payload["runtime_binding"], "event.payload.runtime_binding")
        _text(payload["required_evidence_kind"], "event.payload.required_evidence_kind")
        if not evidence:
            _fail("evidence.observed must carry evidence")
    elif event_type == "context.refreshed":
        _validate_context_payload(payload, "event.payload")
        if value["source"] != "kit_workflow":
            _fail("context.refreshed must come from kit_workflow")
        if value["packet_id"] is not None or value["authority"] is not None:
            _fail("context.refreshed must not have packet_id or authority")
    elif event_type in {"goal.completed", "goal.cancelled"}:
        required = {"summary"}
        allowed = {"summary", "final_verification_evidence_ids"}
        if event_type == "goal.completed":
            required.add("final_verification_evidence_ids")
        _object_with_keys(
            payload,
            required=frozenset(required),
            allowed=frozenset(allowed),
            name="event.payload",
        )
        if value["packet_id"] is not None:
            _fail(f"{event_type} must not have packet_id")
        _text(payload["summary"], "event.payload.summary")
        if "final_verification_evidence_ids" in payload:
            final_evidence_ids = _text_list(
                payload["final_verification_evidence_ids"],
                "event.payload.final_verification_evidence_ids",
            )
            if len(final_evidence_ids) != len(set(final_evidence_ids)):
                _fail("duplicate final verification evidence IDs are not allowed")

    if value["source"] in INFORMATIONAL_SOURCES:
        authority = value["authority"]
        if authority is not None:
            if not isinstance(authority, dict):
                _fail("event.authority must be null or an object")
            if frozenset(authority) not in {frozenset({"kind", "id"}), AUTHORITY_KEYS}:
                _fail("event.authority keys mismatch")
    elif event_type in STATE_CHANGING_EVENTS:
        authority = _exact_keys(value["authority"], AUTHORITY_KEYS, "event.authority")
        _text(authority["kind"], "event.authority.kind")
        _text(authority["id"], "event.authority.id")
        _text(authority["workflow_id"], "event.authority.workflow_id")
        _text(authority["owner"], "event.authority.owner")
        _runtime_binding(authority["runtime_binding"], "event.authority.runtime_binding")
        _text(authority["packet_id"], "event.authority.packet_id")
        prior = _text(authority["expected_prior_state"], "event.authority.expected_prior_state")
        binding = authority["runtime_binding"]
        if authority["kind"] != binding["kind"] or authority["id"] != binding["id"]:
            _fail("event.authority identity must match runtime_binding")
        if event_type in PACKET_TRANSITIONS and prior not in PACKET_TRANSITIONS[event_type][0]:
            _fail(f"event.authority.expected_prior_state is invalid for {event_type}")
        if event_type in PACKET_TRANSITIONS and authority["packet_id"] != value["packet_id"]:
            _fail("event.authority.packet_id must match event.packet_id")
        if event_type == "plan.revised":
            if authority["packet_id"] != "plan":
                _fail("plan.revised authority packet_id must be plan")
            if authority["workflow_id"] != GOAL_WORKFLOW_ID or authority["owner"] != GOAL_OWNER:
                _fail("plan.revised authority must match goal workflow identity")
        if event_type in {"goal.completed", "goal.cancelled"}:
            if authority["packet_id"] != "goal":
                _fail(f"{event_type} authority packet_id must be goal")
            if authority["workflow_id"] != GOAL_WORKFLOW_ID or authority["owner"] != GOAL_OWNER:
                _fail(f"{event_type} authority must match goal workflow identity")
    elif value["authority"] is not None:
        authority = value["authority"]
        if not isinstance(authority, dict):
            _fail("event.authority must be null or an object")
        if frozenset(authority) not in {frozenset({"kind", "id"}), AUTHORITY_KEYS}:
            _fail("event.authority keys mismatch")


def sanitize_summary(value: str, *, limit: int = 500) -> tuple[str, list[str]]:
    if not isinstance(value, str):
        _fail("summary must be a string")
    _integer(limit, "limit", minimum=1)
    normalized = " ".join(CONTROL_CHARACTERS.sub(" ", value).split())
    warnings: list[str] = []
    if normalized != value:
        warnings.append("normalized-whitespace")
    redacted = SECRET_ASSIGNMENT.sub(lambda match: _redacted_assignment(match.group()), normalized)
    if redacted != normalized:
        normalized = redacted
        warnings.append("redacted-secret")
    stored_limit = min(limit, 500)
    if len(normalized) > stored_limit:
        normalized = normalized[:stored_limit]
        warnings.append("truncated")
    return normalized, warnings


def _redacted_assignment(value: str) -> str:
    separator = ":" if ":" in value and "=" not in value else "="
    spacing = " " if separator == ":" else ""
    return f"{value.split(separator, 1)[0].rstrip()}{separator}{spacing}[REDACTED]"


def _sanitized_event_summary(event: dict[str, object], warnings: list[str]) -> str:
    summary, summary_warnings = sanitize_summary(str(event["summary"]))
    for warning in summary_warnings:
        tagged = f"summary:{warning}"
        if tagged not in warnings:
            warnings.append(tagged)
    return summary


def _relative_mad(values: list[float]) -> float:
    center = statistics.median(values)
    if center == 0:
        return 0.0
    return statistics.median(abs(value - center) for value in values) / abs(center)


def _confidence(ratios: list[float]) -> str:
    if len(ratios) <= 1:
        return "low"
    if len(ratios) <= 4:
        return "medium"
    return "high" if _relative_mad(ratios) <= 0.35 else "medium"


def _eta_pause(packet_states: dict[str, dict[str, object]]) -> str | None:
    if any(bool(state.get("stale")) for state in packet_states.values()):
        return "stale"
    states = {str(state.get("state")) for state in packet_states.values()}
    if "blocked" in states:
        return "blocked"
    if "waiting_input" in states:
        return "waiting_input"
    return None


def _number(value: object) -> float | None:
    if isinstance(value, bool) or not isinstance(value, (int, float)):
        return None
    return float(value)


def calculate_eta(
    manifest: dict[str, object],
    packet_states: dict[str, dict[str, object]],
    completed_timings: list[dict[str, object]],
    *,
    active_packet_count: int,
) -> dict[str, object]:
    """Forecast remaining serial work from writer-stamped active durations only."""
    if active_packet_count > 1:
        return {
            "status": "BLOCKED",
            "reason": "unsupported_parallel_timing",
            "summary": "ETA blocked: unsupported parallel timing.",
        }

    pause_reason = _eta_pause(packet_states)
    if pause_reason is not None:
        return {"status": "Paused", "reason": pause_reason, "summary": "ETA paused"}

    packets = _packet_map(manifest)
    remaining = [
        packet
        for packet_id, packet in packets.items()
        if packet_states.get(packet_id, {}).get("state") not in {"verified", "skipped"}
    ]
    remaining_ranges = []
    missing_remaining_estimate = False
    for packet in remaining:
        estimate = packet.get("estimate_seconds")
        if not isinstance(estimate, dict):
            missing_remaining_estimate = True
            continue
        if int(estimate["low"]) > 0 or int(estimate["high"]) > 0:
            remaining_ranges.append(estimate)
    if not remaining_ranges or missing_remaining_estimate:
        return {"status": "Calculating", "summary": "Calculating..."}

    plan_version = int(manifest["plan_version"])
    ratios: list[float] = []
    warnings: list[str] = []
    saw_prior_plan = False
    discarded_unversioned = False
    discarded_mismatched = False
    for timing in completed_timings:
        if not isinstance(timing, dict):
            continue
        timing_plan = timing.get("plan_version")
        if plan_version > 1:
            if timing_plan is None:
                saw_prior_plan = True
                discarded_unversioned = True
                continue
            if timing_plan != plan_version:
                saw_prior_plan = True
                discarded_mismatched = True
                continue
        if timing.get("cross_epoch_gap") or timing.get("epoch_gap"):
            if "writer-epoch-gap" not in warnings:
                warnings.append("writer-epoch-gap")
            continue
        actual = _number(timing.get("actual_seconds"))
        midpoint = _number(timing.get("estimated_midpoint_seconds"))
        if actual is None or midpoint is None or actual < 0 or midpoint <= 0:
            continue
        ratios.append(actual / midpoint)
    if saw_prior_plan:
        warnings.append("plan-revision-calibration-reset")
    if discarded_unversioned:
        warnings.append("plan-revision-unversioned-timing-discarded")
    if discarded_mismatched:
        warnings.append("plan-revision-mismatched-timing-discarded")

    factor = 1.0 if not ratios else min(3.0, max(0.5, statistics.median(ratios)))
    low_seconds = round(sum(int(item["low"]) for item in remaining_ranges) * factor)
    high_seconds = round(sum(int(item["high"]) for item in remaining_ranges) * factor)
    return {
        "status": "Ready",
        "summary": "ETA recalculated" if saw_prior_plan else "ETA ready",
        "low_seconds": low_seconds,
        "high_seconds": high_seconds,
        "calibration_factor": factor,
        "confidence": _confidence(ratios),
        "warnings": warnings,
    }


def _parse_utc(value: object, name: str) -> datetime:
    if not isinstance(value, str) or not UTC_PATTERN.fullmatch(value):
        _fail(f"{name} must be a UTC Z timestamp")
    return datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)


def derive_stale(
    manifest: dict[str, object],
    events: list[dict[str, object]],
    *,
    now_utc: str,
) -> tuple[bool, str | None]:
    """Derive display staleness from accepted event/heartbeat freshness only."""
    now = _parse_utc(now_utc, "now_utc")
    if not events:
        return False, None
    freshness_events = [
        event
        for event in events
        if event.get("event_type") in STATE_CHANGING_EVENTS | {"goal.started", "runtime.heartbeat"}
    ]
    if not freshness_events:
        return False, None
    latest = max(
        _parse_utc(event.get("emitted_at"), "event.emitted_at")
        for event in freshness_events
    )
    packets = _packet_map(manifest)
    states = {packet_id: "queued" for packet_id in packets}
    for event in events:
        packet_id = event.get("packet_id")
        payload = event.get("payload")
        if (
            event.get("event_type") in PACKET_TRANSITIONS
            and isinstance(packet_id, str)
            and packet_id in states
            and isinstance(payload, dict)
            and isinstance(payload.get("state"), str)
        ):
            states[packet_id] = payload["state"]
    active_packet_id = next(
        (packet_id for packet_id, state in states.items() if state == "running"),
        None,
    )
    high_estimate = 0
    if active_packet_id is not None:
        estimate = packets[active_packet_id].get("estimate_seconds")
        if isinstance(estimate, dict):
            high_estimate = int(estimate["high"])
    freshness_seconds = max(900, high_estimate * 2) if high_estimate > 0 else 1800
    if (now - latest).total_seconds() > freshness_seconds:
        return True, "stale"
    return False, None


def _packet_map(manifest: dict[str, object]) -> dict[str, dict[str, object]]:
    return {str(packet["id"]): packet for packet in manifest["packets"]}  # type: ignore[index]


def _initial_packet_states(manifest: dict[str, object]) -> dict[str, dict[str, object]]:
    return {
        packet_id: {"state": "queued", "attempt": 0}
        for packet_id in _packet_map(manifest)
    }


def _goal_state(packet_states: dict[str, dict[str, object]], terminal: str | None) -> str:
    if terminal is not None:
        return terminal
    states = {str(item["state"]) for item in packet_states.values()}
    if "blocked" in states:
        return "blocked"
    if "failed" in states:
        return "failed"
    if "waiting_input" in states:
        return "waiting_input"
    if states == {"queued"}:
        return "planned"
    return "running"


def _progress(
    manifest: dict[str, object],
    packet_states: dict[str, dict[str, object]],
    completed: bool,
) -> dict[str, object]:
    active = _packet_map(manifest)
    total = sum(int(packet["progress_weight"]) for packet in active.values())
    verified = sum(
        int(active[packet_id]["progress_weight"])
        for packet_id, state in packet_states.items()
        if packet_id in active and state["state"] == "verified"
    )
    percent = round(verified / total * 100, 2)
    return {
        "verified_weight": verified,
        "active_planned_weight": total,
        "percent": percent,
        "display_percent": 100 if completed else min(99, int(percent)),
    }


def _authority_matches_packet(
    authority: dict[str, object],
    packet: dict[str, object],
    packet_id: str,
    manifest: dict[str, object],
) -> None:
    if authority["packet_id"] != packet_id:
        _fail("authority packet_id does not match packet")
    if authority["workflow_id"] != packet["workflow_id"]:
        _fail("authority workflow_id does not match manifest")
    if authority["owner"] != packet["owner"]:
        _fail("authority owner does not match manifest")
    bindings = manifest.get("runtime_bindings", [])
    if bindings and authority["runtime_binding"] not in bindings:
        _fail("authority runtime_binding does not match manifest")


def _authority_matches_goal(
    authority: dict[str, object],
    manifest: dict[str, object],
    target: str,
) -> None:
    if authority["packet_id"] != target:
        _fail(f"authority packet_id must be {target}")
    if authority["workflow_id"] != GOAL_WORKFLOW_ID:
        _fail("authority workflow_id does not match goal progress")
    if authority["owner"] != GOAL_OWNER:
        _fail("authority owner does not match main-thread integration owner")
    bindings = manifest.get("runtime_bindings", [])
    if bindings and authority["runtime_binding"] not in bindings:
        _fail("authority runtime_binding does not match manifest")


def _verified_evidence(
    event: dict[str, object],
    packet: dict[str, object],
    observed: dict[str, dict[str, object]],
) -> None:
    payload = event["payload"]
    authority = event["authority"]
    evidence_ids = payload["evidence_ids"]
    required_kinds = set(packet["required_evidence"])
    matched_kinds: set[str] = set()
    for evidence_id in evidence_ids:
        observation = observed.get(evidence_id)
        if observation is None:
            _fail(f"packet.verified lacks matching evidence: {evidence_id}")
        if observation["workflow_id"] != packet["workflow_id"]:
            _fail("packet.verified evidence has no matching evidence workflow binding")
        if observation["packet_id"] != event["packet_id"]:
            _fail("packet.verified evidence has no matching evidence packet binding")
        if observation["runtime_binding"] != authority["runtime_binding"]:
            _fail("packet.verified evidence has no matching evidence runtime binding")
        record = observation["record"]
        if record["label"] != "Verified":
            _fail("packet.verified evidence must be labeled Verified")
        if record["kind"] == "command" and record["exit_code"] != 0:
            _fail("packet.verified command evidence must have exit_code 0")
        matched_kinds.add(str(observation["required_evidence_kind"]))
    if not required_kinds.issubset(matched_kinds):
        _fail("packet.verified does not satisfy required evidence kinds")


def _final_verification(
    requirements: list[str],
    evidence_ids: list[str],
    event_evidence: dict[str, dict[str, object]],
    latest_evidence: dict[str, dict[str, object]],
    observed_evidence: dict[str, dict[str, object]],
) -> None:
    if len(evidence_ids) != len(set(evidence_ids)):
        _fail("duplicate final verification evidence IDs are not allowed")

    records: dict[str, dict[str, object]] = dict(latest_evidence)
    records.update(event_evidence)
    for evidence_id in evidence_ids:
        record = records.get(evidence_id)
        if record is None or record["label"] != "Verified":
            _fail("goal.completed final verification evidence is missing or not Verified")
        if record["kind"] == "command" and record["exit_code"] != 0:
            _fail("goal.completed final verification command must pass")

    used_ids: set[str] = set()
    for requirement in requirements:
        kind_matches = [
            evidence_id
            for evidence_id in evidence_ids
            if evidence_id in observed_evidence
            and observed_evidence[evidence_id]["required_evidence_kind"] == requirement
        ]
        candidates = kind_matches
        if not candidates:
            candidates = [
                evidence_id
                for evidence_id in evidence_ids
                if evidence_id == requirement and evidence_id in event_evidence
            ]
        if len(candidates) != 1:
            _fail(f"goal.completed final verification requirement is unmatched: {requirement}")
        evidence_id = candidates[0]
        if evidence_id in used_ids:
            _fail("one final verification evidence ID cannot satisfy multiple requirements")
        used_ids.add(evidence_id)


def _empty_context_snapshot() -> dict[str, object]:
    return {field: [] for field in CONTEXT_FACT_FIELDS}


def _copy_context_snapshot(payload: dict[str, object]) -> dict[str, object]:
    snapshot = _empty_context_snapshot()
    for field in CONTEXT_FACT_FIELDS:
        if field == "failures":
            snapshot[field] = [dict(item) for item in payload[field]]  # type: ignore[arg-type]
        else:
            snapshot[field] = list(payload[field])  # type: ignore[arg-type]
    return snapshot


def _manifest_dependencies(manifest: dict[str, object]) -> list[str]:
    dependencies: list[str] = []
    seen: set[str] = set()
    for packet in manifest["packets"]:  # type: ignore[index]
        for dependency in packet["dependencies"]:
            dependency_id = str(dependency)
            if dependency_id not in seen:
                seen.add(dependency_id)
                dependencies.append(dependency_id)
    return dependencies


def reduce_events(events: list[dict[str, object]], *, now_utc: str) -> dict[str, object]:
    if not isinstance(events, list) or not events:
        _fail("events must contain goal.started")
    if not isinstance(now_utc, str) or not UTC_PATTERN.fullmatch(now_utc):
        _fail("now_utc must be a UTC Z timestamp")

    manifest: dict[str, object] | None = None
    manifest_hash: str | None = None
    packet_states: dict[str, dict[str, object]] = {}
    observed_evidence: dict[str, dict[str, object]] = {}
    latest_evidence: dict[str, dict[str, object]] = {}
    revision_history: list[dict[str, object]] = []
    context_snapshot = _empty_context_snapshot()
    seen_events: dict[str, str] = {}
    warnings: list[str] = []
    terminal: str | None = None
    next_action = "Start the first queued packet."
    previous_sequence = 0
    goal_id: str | None = None

    for event in events:
        validate_accepted_event(event)
        event_id = str(event["event_id"])
        event_hash = str(event["record_hash"])
        if event_id in seen_events:
            if seen_events[event_id] == event_hash:
                continue
            _fail(f"conflicting event_id: {event_id}")
        seen_events[event_id] = event_hash

        sequence = int(event["sequence"])
        if sequence <= previous_sequence:
            _fail("event.sequence must increase monotonically")
        previous_sequence = sequence
        event_type = str(event["event_type"])

        if event["source"] in INFORMATIONAL_SOURCES:
            if manifest is not None:
                if event["goal_id"] != goal_id:
                    _fail("informational event.goal_id does not match active goal")
            continue

        if manifest is None:
            if event_type != "goal.started":
                _fail("first authoritative event must be goal.started")
            manifest = event["payload"]["manifest"]
            goal_id = str(manifest["goal_id"])
            if event["goal_id"] != goal_id:
                _fail("goal.started goal_id does not match manifest")
            if event["plan_version"] != manifest["plan_version"]:
                _fail("goal.started plan_version does not match manifest")
            manifest_hash = sha256_json(manifest)
            packet_states = _initial_packet_states(manifest)
            next_action = _sanitized_event_summary(event, warnings)
            continue

        if event["goal_id"] != goal_id:
            _fail("event.goal_id does not match active goal")

        if event_type == "goal.started":
            _fail("goal.started may appear only as the first event")

        if event_type == "plan.revised":
            if terminal is not None:
                _fail("cannot revise a terminal goal")
            new_manifest = event["payload"]["manifest"]
            if event["plan_version"] != int(manifest["plan_version"]) + 1:
                _fail("plan.revised plan_version must increment by one")
            if new_manifest["plan_version"] != event["plan_version"]:
                _fail("plan.revised plan_version does not match manifest")
            if new_manifest["goal_id"] != goal_id:
                _fail("plan.revised goal_id does not match active goal")
            if event["payload"]["previous_manifest_hash"] != manifest_hash:
                _fail("plan.revised previous_manifest_hash does not match current manifest")
            new_hash = sha256_json(new_manifest)
            supplied_new_hash = event["payload"].get("new_manifest_hash")
            if supplied_new_hash is not None and supplied_new_hash != new_hash:
                _fail("plan.revised new_manifest_hash does not match replacement manifest")
            current_goal_state = _goal_state(packet_states, terminal)
            if event["authority"]["expected_prior_state"] != current_goal_state:
                _fail("plan.revised expected_prior_state does not match current goal state")
            _authority_matches_goal(event["authority"], manifest, "plan")
            old_packets = _packet_map(manifest)
            new_packets = _packet_map(new_manifest)
            for packet_id, state in packet_states.items():
                if packet_id not in new_packets or state["state"] != "verified":
                    continue
                if old_packets[packet_id]["progress_weight"] != new_packets[packet_id]["progress_weight"]:
                    _fail(
                        "retained verified packet progress_weight cannot change "
                        "without new verification"
                    )
            retained_states = {
                packet_id: dict(packet_states[packet_id])
                for packet_id in new_packets
                if packet_id in packet_states
                and not (
                    packet_states[packet_id]["state"] == "verified"
                    and any(
                        old_packets[packet_id][field] != new_packets[packet_id][field]
                        for field in VERIFICATION_CONTRACT_FIELDS
                    )
                )
            }
            previous_plan_version = int(manifest["plan_version"])
            manifest = new_manifest
            manifest_hash = new_hash
            packet_states = _initial_packet_states(manifest)
            packet_states.update(retained_states)
            observed_evidence = {}
            context_snapshot = _empty_context_snapshot()
            terminal = None
            payload = event["payload"]
            reason, reason_warnings = sanitize_summary(
                str(payload.get("revision_reason") or "Plan revised.")
            )
            approval, approval_warnings = sanitize_summary(
                str(payload.get("approval_ref") or "Unverified")
            )
            for warning in reason_warnings:
                tagged = f"revision_reason:{warning}"
                if tagged not in warnings:
                    warnings.append(tagged)
            for warning in approval_warnings:
                tagged = f"approval_ref:{warning}"
                if tagged not in warnings:
                    warnings.append(tagged)
            revision_history.append(
                {
                    "event_id": event_id,
                    "sequence": sequence,
                    "previous_plan_version": previous_plan_version,
                    "plan_version": int(manifest["plan_version"]),
                    "revision_reason": reason,
                    "approval_ref": approval,
                    "previous_manifest_hash": str(payload["previous_manifest_hash"]),
                    "new_manifest_hash": new_hash,
                    "progress_recalculated": True,
                    "eta_recalculated": True,
                }
            )
            next_action = _sanitized_event_summary(event, warnings)
            continue

        if event["plan_version"] != manifest["plan_version"]:
            _fail("event.plan_version does not match active manifest")

        if terminal is not None:
            _fail("cannot apply events after a terminal goal event")

        if event_type in PACKET_TRANSITIONS:
            packet_id = str(event["packet_id"])
            packets = _packet_map(manifest)
            if packet_id not in packets:
                _fail(f"unknown packet_id: {packet_id}")
            packet = packets[packet_id]
            authority = event["authority"]
            _authority_matches_packet(authority, packet, packet_id, manifest)
            current_state = str(packet_states[packet_id]["state"])
            expected_prior = str(authority["expected_prior_state"])
            if expected_prior != current_state:
                if current_state == "verified" and event_type == "packet.started":
                    _fail("verified packet can reopen only through a new plan version")
                _fail("event.authority.expected_prior_state does not match current packet state")
            allowed_prior, result_state = PACKET_TRANSITIONS[event_type]
            if current_state not in allowed_prior:
                _fail(f"illegal packet transition from {current_state} via {event_type}")
            if event_type == "packet.started":
                unmet = [
                    dependency
                    for dependency in packet["dependencies"]
                    if packet_states[dependency]["state"] != "verified"
                ]
                if unmet:
                    _fail(f"packet dependencies are not verified: {unmet}")
            if event_type == "packet.verified":
                _verified_evidence(event, packet, observed_evidence)
            packet_states[packet_id]["state"] = result_state
            if event_type in {"packet.started", "packet.retry_started"}:
                packet_states[packet_id]["attempt"] = int(packet_states[packet_id]["attempt"]) + 1
        elif event_type == "evidence.observed":
            packet_id = str(event["packet_id"])
            packet = _packet_map(manifest).get(packet_id)
            if packet is None:
                _fail(f"evidence.observed has no matching evidence packet: {packet_id}")
            payload = event["payload"]
            if payload["workflow_id"] != packet["workflow_id"]:
                _fail("evidence.observed workflow_id does not match manifest")
            bindings = manifest.get("runtime_bindings", [])
            if bindings and payload["runtime_binding"] not in bindings:
                _fail("evidence.observed runtime_binding does not match manifest")
            for item in event["evidence"]:
                evidence_id = str(item["id"])
                existing = observed_evidence.get(evidence_id)
                observation = {
                    "workflow_id": payload["workflow_id"],
                    "packet_id": packet_id,
                    "runtime_binding": payload["runtime_binding"],
                    "required_evidence_kind": payload["required_evidence_kind"],
                    "record": item,
                }
                if existing is not None and existing != observation:
                    _fail(f"conflicting evidence id: {evidence_id}")
                observed_evidence[evidence_id] = observation
        elif event_type == "context.refreshed":
            context_snapshot = _copy_context_snapshot(event["payload"])
        elif event_type == "goal.completed":
            if any(item["state"] != "verified" for item in packet_states.values()):
                _fail("goal.completed requires every active packet to be verified")
            evidence_ids = event["payload"]["final_verification_evidence_ids"]
            event_evidence = {str(item["id"]): item for item in event["evidence"]}
            _final_verification(
                manifest["final_verification_required"],
                evidence_ids,
                event_evidence,
                latest_evidence,
                observed_evidence,
            )
            _authority_matches_goal(event["authority"], manifest, "goal")
            if event["authority"]["expected_prior_state"] != _goal_state(packet_states, None):
                _fail("goal.completed expected_prior_state does not match current goal state")
            terminal = "completed"
        elif event_type == "goal.cancelled":
            current_goal_state = _goal_state(packet_states, None)
            _authority_matches_goal(event["authority"], manifest, "goal")
            if event["authority"]["expected_prior_state"] != current_goal_state:
                _fail("goal.cancelled expected_prior_state does not match current goal state")
            terminal = "cancelled"
        elif event_type not in {"runtime.heartbeat", "goal.started"}:
            _fail(f"unsupported accepted event type: {event_type}")

        for item in event["evidence"]:
            latest_evidence[str(item["id"])] = item
        next_action = _sanitized_event_summary(event, warnings)

    if manifest is None or manifest_hash is None or goal_id is None:
        _fail("events must contain an authoritative goal.started")

    completed = terminal == "completed"
    packets = _packet_map(manifest)
    packet_output = [
        {
            "id": packet_id,
            "status": packet_states[packet_id]["state"],
            "owner": packet["owner"],
            "objective": packet["objective"],
            "progress_weight": packet["progress_weight"],
        }
        for packet_id, packet in packets.items()
    ]
    stale, stale_reason = derive_stale(manifest, events, now_utc=now_utc)
    eta_packet_states = {packet_id: dict(state) for packet_id, state in packet_states.items()}
    if stale:
        for state in eta_packet_states.values():
            state["stale"] = True
    eta = calculate_eta(
        manifest,
        eta_packet_states,
        [],
        active_packet_count=sum(
            state["state"] == "running" for state in packet_states.values()
        ),
    )
    if stale_reason is not None and stale_reason not in warnings:
        warnings.append(stale_reason)
    context_facts = dict(context_snapshot)
    context_facts["dependencies"] = _manifest_dependencies(manifest)
    return {
        "schema_version": 1,
        "goal_id": goal_id,
        "plan_version": manifest["plan_version"],
        "manifest_hash": manifest_hash,
        "goal_state": _goal_state(packet_states, terminal),
        "packets": packet_output,
        "progress": _progress(manifest, packet_states, completed),
        "eta": eta,
        "revision_history": revision_history,
        "context_facts": context_facts,
        "latest_evidence": list(latest_evidence.values()),
        "next_action": next_action,
        "updated_at": now_utc,
        "stale": stale,
        "warnings": warnings,
    }
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: 469kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated 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: 321kUpdated Claude CodeCodexVerifiedInstall