hoatv2211/GameStudio-CodexKIT / skills/studio-goal-progress
studio-goal-progress
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.3 KB |
| agents/openai.yaml | config | 313 B |
| assets/app.js | script | 13.4 KB |
| assets/index.html | other | 6.4 KB |
| assets/styles.css | other | 9.0 KB |
| references/commands.md | markdown | 5.5 KB |
| schemas/studio-goal-event.schema.json | config | 25.5 KB |
| schemas/studio-goal-manifest.schema.json | config | 5.2 KB |
| schemas/studio-goal-state.schema.json | config | 13.2 KB |
| scripts/goal_progress.py | script | 22.1 KB |
| scripts/goal_progress_app_server.py | script | 5.6 KB |
| scripts/goal_progress_core.py | script | 52.0 KB |
| scripts/goal_progress_server.py | script | 110.9 KB |
| scripts/goal_progress_store.py | script | 26.1 KB |
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,
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 469k | Updated | Claude CodeCodex | Verified | Install |
| 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: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |