This repository has been archived on 2026-10-29. You can view files and clone it, but you cannot make any changes to its state, such as pushing and creating new issues, pull requests or comments.
Epiphany/tools/epiphany_gui_action.py
2026-04-30 12:43:56 +01:00

1109 lines
45 KiB
Python

from __future__ import annotations
import argparse
import hashlib
from copy import deepcopy
from datetime import datetime
from datetime import timezone
import json
import os
import subprocess
import time
from pathlib import Path
from typing import Any
from epiphany_agent_telemetry import write_transcript_telemetry
from epiphany_mvp_status import DEFAULT_APP_SERVER
from epiphany_mvp_status import collect_status
from epiphany_mvp_status import render_status
from epiphany_mvp_status import sanitize_for_operator
from epiphany_phase5_smoke import AppServerClient
from epiphany_phase5_smoke import ROOT
from epiphany_phase6_reorient_launch_smoke import BINDING_ID as REORIENT_BINDING_ID
from epiphany_unity_bridge import bridge_guidance as unity_bridge_guidance
DEFAULT_CODEX_HOME = ROOT / ".epiphany-gui" / "codex-home"
DEFAULT_ARTIFACT_ROOT = ROOT / ".epiphany-gui" / "actions"
TERMINAL_ROLE_STATUSES = {"completed", "failed", "cancelled"}
TERMINAL_REORIENT_STATUSES = {"completed", "failed", "cancelled"}
def run_git(cwd: Path, *args: str) -> dict[str, Any]:
try:
completed = subprocess.run(
["git", *args],
cwd=cwd,
capture_output=True,
check=False,
encoding="utf-8",
errors="replace",
)
except OSError as error:
return {"ok": False, "error": str(error), "args": list(args)}
return {
"ok": completed.returncode == 0,
"returncode": completed.returncode,
"args": list(args),
"stdout": completed.stdout.strip(),
"stderr": completed.stderr.strip(),
}
def git_diff_hash(cwd: Path) -> dict[str, Any]:
diff = run_git(cwd, "diff", "--binary")
if not diff.get("ok"):
return diff
text = str(diff.get("stdout") or "")
return {
"ok": True,
"sha256": hashlib.sha256(text.encode("utf-8", errors="replace")).hexdigest(),
"bytes": len(text.encode("utf-8", errors="replace")),
}
def git_snapshot(cwd: Path) -> dict[str, Any]:
return {
"head": run_git(cwd, "rev-parse", "--short", "HEAD"),
"branch": run_git(cwd, "branch", "--show-current"),
"status": run_git(cwd, "status", "--short", "--branch"),
"changedFiles": run_git(cwd, "diff", "--name-only"),
"untrackedFiles": run_git(cwd, "ls-files", "--others", "--exclude-standard"),
"diffStat": run_git(cwd, "diff", "--stat"),
"diffHash": git_diff_hash(cwd),
}
def split_git_lines(value: Any) -> list[str]:
text = str(value or "").strip()
return [line for line in text.splitlines() if line.strip()]
def normalize_repo_path(path: str) -> str:
return path.strip().replace("\\", "/")
def parse_review_file_note(note: str) -> list[str]:
if ":" not in note:
return []
_, raw_paths = note.split(":", 1)
paths: list[str] = []
for raw_path in raw_paths.split(","):
path = normalize_repo_path(raw_path)
if not path or path.lower() in {"none", "unknown files"} or "*" in path:
continue
paths.append(path)
return paths
def parent_path(path: str) -> str:
normalized = normalize_repo_path(path)
if "/" not in normalized:
return ""
return normalized.rsplit("/", 1)[0]
def is_under(path: str, root: str) -> bool:
normalized = normalize_repo_path(path)
if not root:
return "/" not in normalized
return normalized == root or normalized.startswith(f"{root}/")
def review_untracked_files(
*,
changed_files: list[str],
new_untracked_files: list[str],
after_untracked: set[str],
active_review_files: list[str] | None = None,
) -> list[str]:
active_review_file_set = {
normalize_repo_path(path)
for path in active_review_files or []
if normalize_repo_path(path)
}
review_roots = {
parent_path(path)
for path in [*changed_files, *new_untracked_files, *active_review_file_set]
if path
}
if not review_roots:
return sorted(new_untracked_files)
return sorted(
path
for path in after_untracked
if path in new_untracked_files
or path in active_review_file_set
or any(is_under(path, root) for root in review_roots)
)
def git_change_summary(
before: dict[str, Any],
after: dict[str, Any],
*,
active_review_files: list[str] | None = None,
) -> dict[str, Any]:
before_status = set(str(nested_get(before, "status", "stdout") or "").splitlines())
after_status = set(str(nested_get(after, "status", "stdout") or "").splitlines())
added_status = sorted(after_status - before_status)
removed_status = sorted(before_status - after_status)
before_changed_files = split_git_lines(nested_get(before, "changedFiles", "stdout"))
changed_files = split_git_lines(nested_get(after, "changedFiles", "stdout"))
before_untracked = set(split_git_lines(nested_get(before, "untrackedFiles", "stdout")))
after_untracked = set(split_git_lines(nested_get(after, "untrackedFiles", "stdout")))
new_untracked_files = sorted(after_untracked - before_untracked)
active_review_files = sorted(
{
normalize_repo_path(path)
for path in active_review_files or []
if normalize_repo_path(path)
}
)
untracked_files = review_untracked_files(
changed_files=changed_files,
new_untracked_files=new_untracked_files,
after_untracked=after_untracked,
active_review_files=active_review_files,
)
workspace_files = sorted({*changed_files, *untracked_files})
ignored_untracked_count = max(0, len(after_untracked) - len(set(untracked_files)))
before_diff_stat = str(nested_get(before, "diffStat", "stdout") or "").strip()
diff_stat = str(nested_get(after, "diffStat", "stdout") or "").strip()
before_diff_hash = nested_get(before, "diffHash", "sha256")
after_diff_hash = nested_get(after, "diffHash", "sha256")
if isinstance(before_diff_hash, str) and isinstance(after_diff_hash, str):
tracked_diff_changed = before_diff_hash != after_diff_hash
else:
tracked_diff_changed = before_changed_files != changed_files or before_diff_stat != diff_stat
workspace_changed = bool(
added_status or removed_status or new_untracked_files or tracked_diff_changed
)
return {
"workspaceChanged": workspace_changed,
"dirtyWorkspace": bool(changed_files or after_untracked or diff_stat),
"trackedDiffPresent": bool(changed_files or diff_stat),
"trackedDiffChanged": tracked_diff_changed,
"beforeChangedFiles": before_changed_files,
"changedFiles": changed_files,
"untrackedFiles": untracked_files,
"newUntrackedFiles": new_untracked_files,
"activeReviewFiles": active_review_files,
"workspaceFiles": workspace_files,
"ignoredUntrackedFileCount": ignored_untracked_count,
"statusAdded": added_status,
"statusRemoved": removed_status,
"diffStat": diff_stat,
}
def render_implementation_audit(result: dict[str, Any]) -> str:
changed_files = result.get("changedFiles")
if not isinstance(changed_files, list):
changed_files = []
status_added = result.get("statusAdded")
if not isinstance(status_added, list):
status_added = []
status_removed = result.get("statusRemoved")
if not isinstance(status_removed, list):
status_removed = []
untracked_files = result.get("untrackedFiles")
if not isinstance(untracked_files, list):
untracked_files = []
new_untracked_files = result.get("newUntrackedFiles")
if not isinstance(new_untracked_files, list):
new_untracked_files = []
active_review_files = result.get("activeReviewFiles")
if not isinstance(active_review_files, list):
active_review_files = []
ignored_untracked_count = result.get("ignoredUntrackedFileCount")
if not isinstance(ignored_untracked_count, int):
ignored_untracked_count = 0
workspace_files = result.get("workspaceFiles")
if not isinstance(workspace_files, list):
workspace_files = []
outcome = (
"reviewable new workspace diff"
if result.get("workspaceChanged")
else "no new workspace diff"
)
next_action = (
"Review the changed files before accepting this implementation slice."
if result.get("workspaceChanged")
else "Stop and review this as an implementation-lane failure before rerunning; the worker completed without changing the target workspace further."
)
return "\n".join(
[
"# Implementation Audit",
"",
f"Outcome: {outcome}",
f"Dirty workspace present: {bool(result.get('dirtyWorkspace'))}",
f"Tracked diff present: {bool(result.get('trackedDiffPresent'))}",
f"Tracked diff changed this turn: {bool(result.get('trackedDiffChanged'))}",
"",
"Changed files:",
*(f"- {path}" for path in changed_files),
*([] if changed_files else ["- none"]),
"",
"Untracked files:",
*(f"- {path}" for path in untracked_files),
*([] if untracked_files else ["- none"]),
"",
"New untracked files this turn:",
*(f"- {path}" for path in new_untracked_files),
*([] if new_untracked_files else ["- none"]),
"",
"Carried review files from Epiphany scratch:",
*(f"- {path}" for path in active_review_files),
*([] if active_review_files else ["- none"]),
"",
f"Ignored unrelated untracked files: {ignored_untracked_count}",
"",
"Workspace files needing review:",
*(f"- {path}" for path in workspace_files),
*([] if workspace_files else ["- none"]),
"",
"Git status delta:",
*(f"- added: {line}" for line in status_added),
*(f"- removed: {line}" for line in status_removed),
*([] if status_added or status_removed else ["- none"]),
"",
f"Next action: {next_action}",
"",
]
)
def nested_get(value: dict[str, Any], *keys: str) -> Any:
current: Any = value
for key in keys:
if not isinstance(current, dict):
return None
current = current.get(key)
return current
def active_review_files_from_status(status: dict[str, Any]) -> list[str]:
state = nested_get(status, "read", "thread", "epiphanyState")
if not isinstance(state, dict):
return []
scratch = state.get("scratch")
if not isinstance(scratch, dict):
return []
notes = scratch.get("notes")
if not isinstance(notes, list):
return []
files: list[str] = []
for note in notes:
if not isinstance(note, str):
continue
if note.startswith(
(
"Tracked files:",
"Review untracked files:",
"Untracked files:",
"New untracked files this turn:",
)
):
files.extend(parse_review_file_note(note))
return sorted(set(files))
def unity_guidance(cwd: Path) -> str:
return unity_bridge_guidance(cwd, ROOT)
def first_present(value: dict[str, Any], *paths: tuple[str, ...]) -> Any:
for path in paths:
item = nested_get(value, *path)
if item not in (None, "", []):
return item
return None
def summarized_recent_evidence(state: dict[str, Any], limit: int = 8) -> list[str]:
recent = state.get("recent_evidence")
if not isinstance(recent, list):
return []
lines: list[str] = []
for item in recent[:limit]:
if not isinstance(item, dict):
continue
summary = item.get("summary")
if not isinstance(summary, str) or not summary.strip():
continue
evidence_id = item.get("id", "unknown")
kind = item.get("kind", "unknown")
status = item.get("status", "unknown")
lines.append(f"- {evidence_id} [{kind}/{status}]: {summary}")
return lines
def build_implementation_prompt(status: dict[str, Any], cwd: Path) -> str:
operator_status = sanitize_for_operator(status)
state = first_present(
operator_status,
("read", "thread", "epiphanyState"),
("scene", "scene", "epiphanyState"),
)
if not isinstance(state, dict):
state = {}
coordinator = operator_status.get("coordinator")
if not isinstance(coordinator, dict):
coordinator = {}
crrc = nested_get(operator_status, "crrc", "decision")
if not isinstance(crrc, dict):
crrc = {}
checkpoint = first_present(
state,
("graph_checkpoint",),
("graphCheckpoint",),
)
if not isinstance(checkpoint, dict):
checkpoint = {}
frontier = first_present(state, ("graph_frontier",), ("graphFrontier",))
if not isinstance(frontier, dict):
frontier = {}
scratch = state.get("scratch")
if not isinstance(scratch, dict):
scratch = {}
evidence_lines = summarized_recent_evidence(state)
if not evidence_lines:
evidence_lines = ["- none recorded"]
active_node_ids = frontier.get("active_node_ids") or frontier.get("activeNodeIds") or []
if isinstance(active_node_ids, list):
active_node_text = ", ".join(str(item) for item in active_node_ids)
else:
active_node_text = str(active_node_ids or "none")
return f"""You are the Epiphany implementation agent for this repository.
Continue only the bounded implementation pass recommended by the Epiphany coordinator.
Coordinator:
- action: {coordinator.get("action")}
- target role: {coordinator.get("targetRole")}
- reason: {coordinator.get("reason")}
Checkpoint:
- id: {checkpoint.get("checkpoint_id") or checkpoint.get("checkpointId")}
- summary: {checkpoint.get("summary")}
- frontier: {active_node_text}
Continuity:
- next action: {crrc.get("nextAction") or nested_get(operator_status, "reorient", "decision", "nextAction")}
- scratch: {scratch.get("summary")}
Accepted evidence:
{chr(10).join(evidence_lines)}
Implementation rules:
- Do not read sealed transcript artifacts or raw specialist result payloads.
- Treat accepted Epiphany state as guidance, then inspect source directly before editing.
- Environment guardrails:
{unity_guidance(cwd)}
- Make a bounded first pass: design or implement a parallel compute-backed gravity height producer that preserves the current `_NebulaSurfaceHeight`, `_GridTransform`, and Slime `Heightmap` contracts before changing shader consumers.
- This is an implementation turn, not a planning turn. Leave a concrete source diff unless direct source evidence proves the bounded pass is impossible.
- If there is no implementation diff yet, prefer a small reversible compatibility scaffold over another explanation. A valid first diff may be a source-local contract/scaffold for a compute-backed gravity height producer that runs beside the camera path and does not rewire consumers yet.
- A previous supervised implementation attempt already performed source-only inspection and left no diff. Do not repeat that pattern. Reuse the accepted checkpoint and inspect only what you need to place the smallest safe scaffold.
- A good minimal patch shape is a disabled/parallel gravity heightfield compatibility producer or contract in the rendering layer, plus any tiny supporting compute-shader stub needed to express the intended data path. Preserve legacy texture names and do not rewire consumers in this pass.
- Before stopping, check `git status --short`. If it still shows no source diff, continue implementing unless you have found a specific source contradiction or missing dependency that makes even the compatibility scaffold unsafe.
- Do not attempt the full fog/froxel migration in this pass unless the compatibility producer and contract evidence are already in place.
- Keep the change reviewable. Update or add source-local notes/tests if the repo has an established place for them.
- If the source contradicts the checkpoint, stop and explain the contradiction instead of tower-building.
"""
def implementation_no_diff_patch(
status: dict[str, Any],
*,
artifact_dir: Path,
implementation_result: dict[str, Any],
) -> dict[str, Any] | None:
operator_status = sanitize_for_operator(status)
state = first_present(
operator_status,
("read", "thread", "epiphanyState"),
("scene", "scene", "epiphanyState"),
)
if not isinstance(state, dict):
return None
checkpoint = first_present(
state,
("investigation_checkpoint",),
("investigationCheckpoint",),
)
if not isinstance(checkpoint, dict):
return None
evidence_id = f"ev-implementation-no-diff-{artifact_dir.name}"
observation_id = f"obs-implementation-no-diff-{artifact_dir.name}"
updated_checkpoint = deepcopy(checkpoint)
updated_checkpoint["disposition"] = "regather_required"
updated_checkpoint["summary"] = (
"Implementation turn completed with no new workspace diff; the current "
"checkpoint is insufficient to drive the coding lane safely."
)
updated_checkpoint["next_action"] = (
"Review the no-diff implementation audit, then repair the implementation "
"lane through modeling or reorientation before continuing code work."
)
evidence_ids = updated_checkpoint.get("evidence_ids")
if not isinstance(evidence_ids, list):
evidence_ids = []
if evidence_id not in evidence_ids:
evidence_ids = [*evidence_ids, evidence_id]
updated_checkpoint["evidence_ids"] = evidence_ids
return {
"investigationCheckpoint": updated_checkpoint,
"observations": [
{
"id": observation_id,
"summary": (
"The implementation lane completed a bounded turn but left "
"no new tracked or untracked workspace delta, so continuation "
"needs review or checkpoint repair."
),
"source_kind": "implementation",
"status": "blocked",
"evidence_ids": [evidence_id],
}
],
"evidence": [
{
"id": evidence_id,
"kind": "implementation-audit",
"status": "blocked",
"summary": (
"continueImplementation produced no new workspace diff "
f"(trackedDiffPresent={bool(implementation_result.get('trackedDiffPresent'))}); "
f"artifact={artifact_dir.name}."
),
}
],
}
def implementation_diff_patch(
*,
artifact_dir: Path,
implementation_result: dict[str, Any],
) -> dict[str, Any]:
evidence_id = f"ev-implementation-diff-{artifact_dir.name}"
observation_id = f"obs-implementation-diff-{artifact_dir.name}"
workspace_files = implementation_result.get("workspaceFiles")
if not isinstance(workspace_files, list):
workspace_files = []
changed_files = implementation_result.get("changedFiles")
if not isinstance(changed_files, list):
changed_files = []
untracked_files = implementation_result.get("untrackedFiles")
if not isinstance(untracked_files, list):
untracked_files = []
new_untracked_files = implementation_result.get("newUntrackedFiles")
if not isinstance(new_untracked_files, list):
new_untracked_files = []
ignored_untracked_count = implementation_result.get("ignoredUntrackedFileCount")
if not isinstance(ignored_untracked_count, int):
ignored_untracked_count = 0
file_text = ", ".join(str(path) for path in workspace_files[:12]) or "unknown files"
code_refs = [
{
"path": str(path),
"note": "Changed by bounded continueImplementation evidence-gathering turn.",
}
for path in workspace_files[:20]
]
summary = (
"continueImplementation produced a reviewable workspace diff "
f"(trackedDiffPresent={bool(implementation_result.get('trackedDiffPresent'))}); "
f"artifact={artifact_dir.name}; files={file_text}."
)
return {
"observations": [
{
"id": observation_id,
"summary": (
"The implementation lane produced a bounded workspace diff "
"from the current accepted modeling checkpoint; verification "
"should review the changed files before implementation continues."
),
"source_kind": "implementation",
"status": "accepted",
"evidence_ids": [evidence_id],
"code_refs": code_refs,
}
],
"evidence": [
{
"id": evidence_id,
"kind": "implementation-audit",
"status": "ok",
"summary": summary,
"code_refs": code_refs,
}
],
"scratch": {
"summary": (
"Implementation produced a reviewable diff; next safe move is "
"verification of the changed workspace files, including untracked files."
),
"next_probe": "Run verification/review against the implementation diff before continuing.",
"notes": [
f"Tracked files: {', '.join(str(path) for path in changed_files) or 'none'}",
f"Untracked files: {', '.join(str(path) for path in untracked_files) or 'none'}",
f"New untracked files this turn: {', '.join(str(path) for path in new_untracked_files) or 'none'}",
f"Ignored unrelated untracked files: {ignored_untracked_count}",
],
},
}
def wait_for_role_result(
client: AppServerClient,
*,
thread_id: str,
role_id: str,
timeout_seconds: int,
poll_seconds: float,
) -> dict[str, Any]:
deadline = time.time() + timeout_seconds
latest: dict[str, Any] | None = None
while time.time() < deadline:
latest = client.send(
"thread/epiphany/roleResult",
{"threadId": thread_id, "roleId": role_id},
)
assert latest is not None
if latest.get("status") in TERMINAL_ROLE_STATUSES:
return latest
time.sleep(poll_seconds)
assert latest is not None
return latest
def wait_for_reorient_result(
client: AppServerClient,
*,
thread_id: str,
timeout_seconds: int,
poll_seconds: float,
) -> dict[str, Any]:
deadline = time.time() + timeout_seconds
latest: dict[str, Any] | None = None
while time.time() < deadline:
latest = client.send(
"thread/epiphany/reorientResult",
{"threadId": thread_id, "bindingId": REORIENT_BINDING_ID},
)
assert latest is not None
if latest.get("status") in TERMINAL_REORIENT_STATUSES:
return latest
time.sleep(poll_seconds)
assert latest is not None
return latest
def checkpoint_patch(cwd: Path) -> dict[str, Any]:
generated_at = datetime.now(timezone.utc).isoformat()
return {
"objective": "Reach a testable Epiphany MVP through the local GUI/operator workflow.",
"activeSubgoalId": "epiphany-gui-mvp",
"subgoals": [
{
"id": "epiphany-gui-mvp",
"title": "Make the Epiphany GUI usable for local operator testing",
"status": "active",
"summary": "The operator can prepare durable state, inspect coordinator guidance, and launch/read fixed specialist lanes without terminal work.",
}
],
"graphs": {
"architecture": {
"nodes": [
{
"id": "gui-operator-console",
"title": "Tauri/React operator console",
"purpose": "Human-facing surface for status, artifacts, and bounded lane actions.",
"code_refs": [
{
"path": "apps/epiphany-gui/src/App.tsx",
"start_line": 1,
"end_line": 1,
"symbol": "App",
}
],
},
{
"id": "gui-action-bridge",
"title": "GUI action bridge",
"purpose": "Python bridge that invokes fixed app-server Epiphany lane APIs and writes auditable artifacts.",
"code_refs": [
{
"path": "tools/epiphany_gui_action.py",
"start_line": 1,
"end_line": 1,
"symbol": "run_action",
}
],
},
{
"id": "app-server-epiphany-control-plane",
"title": "App-server Epiphany control plane",
"purpose": "Typed state, coordinator, CRRC, role, reorient, and job surfaces used by the GUI.",
"code_refs": [
{
"path": "vendor/codex/codex-rs/app-server/src/codex_message_processor.rs",
"start_line": 1,
"end_line": 1,
"symbol": "thread/epiphany",
}
],
},
]
},
"dataflow": {
"nodes": [
{
"id": "operator-action-flow",
"title": "Operator action flow",
"purpose": "GUI button -> Tauri command -> Python bridge -> app-server API -> artifact bundle -> refreshed GUI status.",
}
]
},
"links": [
{
"dataflow_node_id": "operator-action-flow",
"architecture_node_id": "gui-operator-console",
"relationship": "operator-surface",
},
{
"dataflow_node_id": "operator-action-flow",
"architecture_node_id": "gui-action-bridge",
"relationship": "bridge",
},
{
"dataflow_node_id": "operator-action-flow",
"architecture_node_id": "app-server-epiphany-control-plane",
"relationship": "control-plane",
},
],
},
"graphFrontier": {
"active_node_ids": [
"gui-operator-console",
"gui-action-bridge",
"app-server-epiphany-control-plane",
],
"dirty_paths": [],
},
"graphCheckpoint": {
"checkpoint_id": f"gui-operator-{int(time.time())}",
"graph_revision": 1,
"summary": "GUI-prepared checkpoint for local Epiphany MVP operator testing.",
"frontier_node_ids": [
"gui-operator-console",
"gui-action-bridge",
"app-server-epiphany-control-plane",
],
},
"investigationCheckpoint": {
"checkpoint_id": f"ix-gui-operator-{int(time.time())}",
"kind": "source_gathering",
"disposition": "resume_ready",
"focus": "Validate the GUI operator loop against the fixed Epiphany lane APIs.",
"summary": "The GUI is the operator surface; app-server typed state remains the source of truth.",
"next_action": "Use the GUI to run coordinator plan, launch/read specialist lanes, and inspect written artifacts.",
"captured_at_turn_id": f"gui-prepare-{int(time.time())}",
"code_refs": [
{
"path": "apps/epiphany-gui/src/App.tsx",
"start_line": 1,
"end_line": 1,
"symbol": "App",
},
{
"path": "tools/epiphany_gui_action.py",
"start_line": 1,
"end_line": 1,
"symbol": "run_action",
},
],
},
"scratch": {
"summary": "Prepared from the GUI so the operator has a durable thread before launching fixed lanes.",
"current_focus": "Test the local GUI MVP workflow end to end.",
"next_action": "Run coordinator guidance, then launch/read modeling, verification, or reorient lanes as recommended.",
"updated_at": generated_at,
"cwd": str(cwd),
},
"churn": {
"understanding_status": "ready",
"diff_pressure": "low",
"graph_freshness": "fresh",
"unexplained_writes": 0,
},
}
def write_json(path: Path, value: Any) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
def write_text(path: Path, value: str) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(value, encoding="utf-8")
def state_revision(status: dict[str, Any]) -> int | None:
state = status.get("read", {}).get("thread", {}).get("epiphanyState")
if isinstance(state, dict):
revision = state.get("revision")
if isinstance(revision, int):
return revision
scene_revision = status.get("scene", {}).get("scene", {}).get("revision")
return scene_revision if isinstance(scene_revision, int) else None
def require_thread_id(thread_id: str | None, action: str) -> str:
if not thread_id:
raise ValueError(f"{action} requires a persistent thread id")
return thread_id
def is_unresumable_empty_thread_error(error: RuntimeError) -> bool:
message = str(error)
return "no rollout found for thread id" in message or "thread not loaded" in message
def run_action(args: argparse.Namespace) -> dict[str, Any]:
thread_id = args.thread_id or ""
if args.action != "prepareCheckpoint":
thread_id = require_thread_id(args.thread_id, args.action)
codex_home = args.codex_home.resolve()
artifact_dir = args.artifact_root.resolve() / f"{args.action}-{time.time_ns()}-{os.getpid()}"
transcript_path = artifact_dir / "transcript.jsonl"
stderr_path = artifact_dir / "server.stderr.log"
telemetry_path = artifact_dir / "agent-function-telemetry.json"
cwd = args.cwd.resolve()
codex_home.mkdir(parents=True, exist_ok=True)
artifact_dir.mkdir(parents=True, exist_ok=True)
with AppServerClient(args.app_server.resolve(), codex_home, transcript_path, stderr_path) as client:
client.send(
"initialize",
{
"clientInfo": {
"name": "epiphany-gui-action",
"title": "Epiphany GUI Action",
"version": "0.1.0",
},
"capabilities": {"experimentalApi": True},
},
)
client.send("initialized", expect_response=False)
if args.action == "prepareCheckpoint":
if args.thread_id:
try:
client.send("thread/resume", {"threadId": args.thread_id})
except RuntimeError as error:
if not is_unresumable_empty_thread_error(error):
raise
thread_id = ""
if not thread_id:
started = client.send("thread/start", {"cwd": str(cwd), "ephemeral": False})
if started is None:
raise RuntimeError("thread/start returned no response")
thread_id = started["thread"]["id"]
before = collect_status(client, thread_id=thread_id, cwd=cwd, ephemeral=True)
revision = state_revision(before)
response = client.send(
"thread/epiphany/update",
{
"threadId": thread_id,
"expectedRevision": revision if revision is not None else 0,
"patch": checkpoint_patch(cwd),
},
)
summary = "Prepared durable Epiphany checkpoint."
else:
client.send("thread/resume", {"threadId": thread_id})
before = collect_status(client, thread_id=thread_id, cwd=cwd, ephemeral=False)
revision = state_revision(before)
if args.action in {"launchModeling", "launchVerification"}:
role_id = "modeling" if args.action == "launchModeling" else "verification"
payload: dict[str, Any] = {
"threadId": thread_id,
"roleId": role_id,
"maxRuntimeSeconds": args.max_runtime_seconds,
}
if revision is not None:
payload["expectedRevision"] = revision
launch = client.send("thread/epiphany/roleLaunch", payload)
if args.wait:
result = wait_for_role_result(
client,
thread_id=thread_id,
role_id=role_id,
timeout_seconds=args.timeout_seconds,
poll_seconds=args.poll_seconds,
)
response = {"launch": launch, "result": result}
summary = f"Launched {role_id} role worker and waited for a reviewable result."
else:
response = launch
summary = f"Launched {role_id} role worker without waiting."
elif args.action in {"readModelingResult", "readVerificationResult"}:
role_id = "modeling" if args.action == "readModelingResult" else "verification"
response = client.send(
"thread/epiphany/roleResult", {"threadId": thread_id, "roleId": role_id}
)
summary = f"Read {role_id} role result."
elif args.action == "acceptModeling":
if revision is None:
raise ValueError("acceptModeling requires ready Epiphany state with a revision")
response = client.send(
"thread/epiphany/roleAccept",
{
"threadId": thread_id,
"roleId": "modeling",
"expectedRevision": revision,
},
)
summary = "Accepted reviewed modeling graph/checkpoint patch."
elif args.action == "acceptVerification":
if revision is None:
raise ValueError("acceptVerification requires ready Epiphany state with a revision")
response = client.send(
"thread/epiphany/roleAccept",
{
"threadId": thread_id,
"roleId": "verification",
"expectedRevision": revision,
},
)
summary = "Accepted reviewed verification finding."
elif args.action == "launchReorient":
payload = {"threadId": thread_id, "maxRuntimeSeconds": args.max_runtime_seconds}
if revision is not None:
payload["expectedRevision"] = revision
launch = client.send("thread/epiphany/reorientLaunch", payload)
if args.wait:
result = wait_for_reorient_result(
client,
thread_id=thread_id,
timeout_seconds=args.timeout_seconds,
poll_seconds=args.poll_seconds,
)
response = {"launch": launch, "result": result}
summary = "Launched fixed reorient-worker and waited for a reviewable result."
else:
response = launch
summary = "Launched fixed reorient-worker without waiting."
elif args.action == "readReorientResult":
response = client.send(
"thread/epiphany/reorientResult",
{"threadId": thread_id, "bindingId": REORIENT_BINDING_ID},
)
summary = "Read reorient-worker result."
elif args.action == "acceptReorient":
if revision is None:
raise ValueError("acceptReorient requires ready Epiphany state with a revision")
response = client.send(
"thread/epiphany/reorientAccept",
{
"threadId": thread_id,
"expectedRevision": revision,
"bindingId": REORIENT_BINDING_ID,
"updateScratch": True,
"updateInvestigationCheckpoint": True,
},
)
summary = "Accepted reviewed reorientation finding."
elif args.action == "continueImplementation":
coordinator = before.get("coordinator")
if not isinstance(coordinator, dict):
raise ValueError("continueImplementation requires coordinator status")
if coordinator.get("action") != "continueImplementation" and not args.force:
raise ValueError(
"coordinator is not recommending continueImplementation "
f"(got {coordinator.get('action')!r})"
)
pre_git = git_snapshot(cwd)
prompt = build_implementation_prompt(before, cwd)
write_text(artifact_dir / "implementation-prompt.md", prompt)
turn = client.send(
"turn/start",
{
"threadId": thread_id,
"cwd": str(cwd),
"sandboxPolicy": {
"type": "workspaceWrite",
"writableRoots": [str(cwd)],
"readOnlyAccess": {"type": "fullAccess"},
"networkAccess": False,
"excludeTmpdirEnvVar": False,
"excludeSlashTmp": False,
},
"input": [
{
"type": "text",
"text": prompt,
"textElements": [],
}
],
},
)
completed = client.wait_for_notification(
"turn/completed", timeout=args.timeout_seconds
)
post_git = git_snapshot(cwd)
implementation_result = git_change_summary(
pre_git,
post_git,
active_review_files=active_review_files_from_status(before),
)
write_json(artifact_dir / "git-before.json", pre_git)
write_json(artifact_dir / "git-after.json", post_git)
write_json(artifact_dir / "implementation-result.json", implementation_result)
write_text(
artifact_dir / "implementation-audit.md",
render_implementation_audit(implementation_result),
)
update_status = collect_status(client, thread_id=thread_id, cwd=cwd, ephemeral=False)
update_revision = state_revision(update_status)
response = {
"turn": turn,
"completed": sanitize_for_operator(completed),
"preGit": pre_git,
"postGit": post_git,
"implementationResult": implementation_result,
}
if implementation_result["workspaceChanged"]:
diff_patch = implementation_diff_patch(
artifact_dir=artifact_dir,
implementation_result=implementation_result,
)
if update_revision is not None:
write_json(artifact_dir / "implementation-state-patch.json", diff_patch)
diff_update = client.send(
"thread/epiphany/update",
{
"threadId": thread_id,
"expectedRevision": update_revision,
"patch": diff_patch,
},
)
write_json(artifact_dir / "implementation-state-update.json", diff_update)
response["implementationUpdate"] = sanitize_for_operator(diff_update)
summary = (
"Ran bounded implementation turn and produced a reviewable workspace diff."
)
else:
no_diff_patch = implementation_no_diff_patch(
before,
artifact_dir=artifact_dir,
implementation_result=implementation_result,
)
if no_diff_patch is not None and revision is not None:
write_json(artifact_dir / "no-diff-state-patch.json", no_diff_patch)
no_diff_update = client.send(
"thread/epiphany/update",
{
"threadId": thread_id,
"expectedRevision": update_revision
if update_revision is not None
else revision,
"patch": no_diff_patch,
},
)
write_json(artifact_dir / "no-diff-state-update.json", no_diff_update)
response["noDiffUpdate"] = sanitize_for_operator(no_diff_update)
summary = (
"Ran bounded implementation turn, but it produced no new workspace diff."
)
if response.get("noDiffUpdate"):
summary += " Marked the checkpoint for repair before retry."
else:
raise ValueError(f"unsupported GUI action: {args.action}")
assert response is not None
after = collect_status(client, thread_id=thread_id, cwd=cwd, ephemeral=True)
operator_before = sanitize_for_operator(before)
operator_response = sanitize_for_operator(response)
operator_after = sanitize_for_operator(after)
write_json(artifact_dir / "before-status.json", operator_before)
write_json(artifact_dir / "action-response.json", operator_response)
write_json(artifact_dir / "after-status.json", operator_after)
write_text(artifact_dir / "after-status.txt", render_status(operator_after))
result = {
"action": args.action,
"artifactPath": str(artifact_dir),
"summary": summary,
"threadId": thread_id,
"response": operator_response,
"sealedArtifactManifest": [
{
"path": "transcript.jsonl",
"reason": "sealed JSON-RPC audit trail; do not read during normal supervision",
},
{
"path": "server.stderr.log",
"reason": "sealed app-server diagnostics; inspect only for explicit debugging",
},
],
"telemetryPath": str(telemetry_path),
}
write_json(artifact_dir / "gui-action-summary.json", result)
write_transcript_telemetry(transcript_path, telemetry_path)
return result
def main() -> int:
parser = argparse.ArgumentParser(description="Run one bounded Epiphany GUI action.")
parser.add_argument("--app-server", type=Path, default=DEFAULT_APP_SERVER)
parser.add_argument("--codex-home", type=Path, default=DEFAULT_CODEX_HOME)
parser.add_argument("--cwd", type=Path, default=ROOT)
parser.add_argument("--thread-id")
parser.add_argument("--artifact-root", type=Path, default=DEFAULT_ARTIFACT_ROOT)
parser.add_argument("--max-runtime-seconds", type=int, default=180)
parser.add_argument("--timeout-seconds", type=int, default=300)
parser.add_argument("--poll-seconds", type=float, default=5.0)
parser.add_argument("--wait", action=argparse.BooleanOptionalAction, default=True)
parser.add_argument(
"--action",
required=True,
choices=[
"launchModeling",
"readModelingResult",
"acceptModeling",
"launchVerification",
"readVerificationResult",
"acceptVerification",
"launchReorient",
"readReorientResult",
"acceptReorient",
"continueImplementation",
"prepareCheckpoint",
],
)
parser.add_argument(
"--force",
action="store_true",
help="Allow continueImplementation even when the coordinator is not recommending it.",
)
args = parser.parse_args()
print(json.dumps(run_action(args), indent=2, ensure_ascii=False))
return 0
if __name__ == "__main__":
raise SystemExit(main())