"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/
Python
Add Unreal Insights harness
aimididfef24958d00
diff --git a/.gitignore b/.gitignoreindex 6eb435674..6c533bfad 100644--- a/.gitignore+++ b/.gitignore@@ -81,6 +81,7 @@!/rms/!/renderdoc/!/cloudcompare/+!/unrealinsights/# Step 5: Inside each software dir, ignore everything (including dotfiles)/gimp/*@@ -137,6 +138,8 @@/renderdoc/.*/cloudcompare/*/cloudcompare/.*+/unrealinsights/*+/unrealinsights/.*# Step 6: ...except agent-harness/!/gimp/agent-harness/@@ -168,6 +171,7 @@!/rms/agent-harness/!/renderdoc/agent-harness/!/cloudcompare/agent-harness/+!/unrealinsights/agent-harness/# Step 7: Ignore build artifacts within allowed dirs**/__pycache__/diff --git a/registry.json b/registry.jsonindex b20c870f7..08812d9b5 100644--- a/registry.json+++ b/registry.json@@ -2,7 +2,7 @@"meta": {"repo": "https://github.com/HKUDS/CLI-Anything","description": "CLI-Hub — Agent-native stateful CLI interfaces for softwares, codebases, and Web Services",- "updated": "2026-03-26"+ "updated": "2026-04-15"},"clis": [{@@ -397,6 +397,20 @@"contributor": "levishilf","contributor_url": "https://github.com/levishilf"},+ {+ "name": "unrealinsights",+ "display_name": "Unreal Insights",+ "version": "0.1.0",+ "description": "Windows-first Unreal trace capture orchestration and headless Timing Insights export workflows",+ "requires": "Windows + Unreal Engine 5.5+ installation with UnrealInsights.exe",+ "homepage": "https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-insights-in-unreal-engine",+ "install_cmd": "pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=unrealinsights/agent-harness",+ "entry_point": "cli-anything-unrealinsights",+ "skill_md": "unrealinsights/agent-harness/cli_anything/unrealinsights/skills/SKILL.md",+ "category": "debugging",+ "contributor": "AiMiDi",+ "contributor_url": "https://github.com/AiMiDi"+ },{"name": "videocaptioner","display_name": "VideoCaptioner",diff --git a/unrealinsights/agent-harness/UNREALINSIGHTS.md b/unrealinsights/agent-harness/UNREALINSIGHTS.mdnew file mode 100644index 000000000..d549b74ae--- /dev/null+++ b/unrealinsights/agent-harness/UNREALINSIGHTS.md@@ -0,0 +1,72 @@+# UNREALINSIGHTS.md - Software-Specific SOP++## About Unreal Insights++Unreal Insights is Epic's trace analysis tool for Unreal Engine performance,+profiling, timing, and counter data stored in `.utrace` files.++This harness follows the CLI-Anything rule of using the real backend:++- `UnrealInsights.exe` for headless analysis and CSV/TXT export+- a traced Unreal Engine target executable for capture generation++## Backend Model++### Analysis backend++`UnrealInsights.exe` accepts:++- `-OpenTraceFile=<path>`+- `-NoUI`+- `-AutoQuit`+- `-ABSLOG=<path>`+- `-ExecOnAnalysisCompleteCmd=<command>`++The command may be:++- a direct exporter command such as `TimingInsights.ExportThreads`+- `@=<response-file>` for batch execution++This harness can also ensure an engine-matched analysis backend for custom+source engines by locating or building `Engine/Binaries/Win64/UnrealInsights.exe`.++### Capture backend++UE targets can be launched with:++- `-trace=<channels>`+- `-tracefile=<path>`+- optional `-ExecCmds=<cmd1,cmd2,...>`++This harness supports two v1 launch shapes:++- explicit target executable path+- `--project + --engine-root` convenience mode, which resolves `UnrealEditor.exe`++This harness only supports file-mode capture orchestration in v1.++## CLI Coverage Map++| Feature | CLI Command | Status |+|--------|-------------|--------|+| Resolve Insights binaries | `backend info` | v1 |+| Set current trace | `trace set` | v1 |+| Inspect current trace | `trace info` | v1 |+| Launch traced target | `capture run` | v1 |+| Export threads | `export threads` | v1 |+| Export timers | `export timers` | v1 |+| Export timing events | `export timing-events` | v1 |+| Export timer statistics | `export timer-stats` | v1 |+| Export timer callees | `export timer-callees` | v1 |+| Export counter list | `export counters` | v1 |+| Export counter values | `export counter-values` | v1 |+| Batch response file | `batch run-rsp` | v1 |+| Control live instances | — | future |+| Trace store browsing | — | future |++## Current Limitations++- Windows-first discovery only+- No SessionServices control of already-running UE instances+- No trace store session enumeration+- Capture orchestration assumes the target executable accepts standard UE trace flagsdiff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/README.md b/unrealinsights/agent-harness/cli_anything/unrealinsights/README.mdnew file mode 100644index 000000000..96de51ab6--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/README.md@@ -0,0 +1,167 @@+# cli-anything-unrealinsights++Command-line interface for Unreal Insights trace capture and export workflows.++This harness wraps the real Unreal Engine tools:++- `UnrealInsights.exe` for headless `.utrace` analysis and exporters+- a traced UE/Game executable for file-mode capture generation++## Installation++```bash+cd unrealinsights/agent-harness+pip install -e .+```++## Prerequisites++- Windows+- Unreal Engine 5.5+ installed with `UnrealInsights.exe`+- optional `UnrealTraceServer.exe` for backend reporting++You can point the harness at explicit binaries:++```powershell+$env:UNREALINSIGHTS_EXE='D:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealInsights.exe'+$env:UNREAL_TRACE_SERVER_EXE='D:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealTraceServer.exe'+```++If those are not set, the harness auto-discovers common UE installs under+`<drive>:\Program Files\Epic Games\UE_*`.++## Quick Start++```powershell+# Inspect resolved backend binaries+cli-anything-unrealinsights --json backend info++# Find or build UnrealInsights.exe for a custom engine root+cli-anything-unrealinsights --json backend ensure-insights `+ --engine-root 'D:\code\D5\d5render-ue5_3'++# Bind a trace file for the current session+cli-anything-unrealinsights trace set D:\captures\session.utrace++# Export threads+cli-anything-unrealinsights --json -t D:\captures\session.utrace export threads D:\out\threads.csv++# Export timer statistics for a region+cli-anything-unrealinsights --json -t D:\captures\session.utrace export timer-stats `+ D:\out\timer_stats.csv --threads "GameThread" --timers "*" --region "EXPORT_CAPTURE"++# Execute a response file+cli-anything-unrealinsights --json -t D:\captures\session.utrace batch run-rsp D:\out\export.rsp++# Launch a traced UE target and wait for completion+cli-anything-unrealinsights --json capture run `+ --project 'D:\Projects\MyGame\MyGame.uproject' `+ --engine-root 'D:\Program Files\Epic Games\UE_5.5' `+ --output-trace D:\captures\editor_boot.utrace `+ --channels "default,bookmark" `+ --exec-cmd "Trace.Bookmark BootStart" `+ --wait --timeout 300++# Start REPL (default behavior)+cli-anything-unrealinsights+```++## Command Groups++- `backend`+ - `info`+ - `ensure-insights`+- `trace`+ - `set`+ - `info`+- `capture`+ - `run`+- `export`+ - `threads`+ - `timers`+ - `timing-events`+ - `timer-stats`+ - `timer-callees`+ - `counters`+ - `counter-values`+- `batch`+ - `run-rsp`+- `repl`++## Global Options++- `--json`: machine-readable output+- `--debug`: include traceback details in errors+- `--trace/-t`: current `.utrace` file+- `--insights-exe`: explicit `UnrealInsights.exe` path+- `--trace-server-exe`: explicit `UnrealTraceServer.exe` path++## Engine-Matched Insights++If you need an `UnrealInsights.exe` matching a custom source engine, use:++```powershell+cli-anything-unrealinsights --json backend ensure-insights `+ --engine-root 'D:\code\D5\d5render-ue5_3'+```++Behavior:++- looks for `Engine\Binaries\Win64\UnrealInsights.exe` under the given engine root+- if missing, runs that engine's `Engine\Build\BatchFiles\Build.bat UnrealInsights Win64 Development -WaitMutex`+- returns the resolved path plus the build log path when a build was attempted++## Capture Convenience Layer++`capture run` supports two launch styles:++```powershell+# 1. Convenience mode: infer UnrealEditor.exe from engine root+cli-anything-unrealinsights capture run `+ --project 'D:\Projects\MyGame\MyGame.uproject' `+ --engine-root 'D:\Program Files\Epic Games\UE_5.5'++# 2. Explicit mode: provide the exact executable yourself+cli-anything-unrealinsights capture run `+ 'D:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealEditor.exe' `+ --target-arg 'D:\Projects\MyGame\MyGame.uproject'+```++Notes:++- `--project` prepends the `.uproject` path to the target command line.+- `--engine-root` accepts either the UE install root or its `Engine` subdirectory.+- If `target_exe` is omitted, `capture run` resolves `UnrealEditor.exe` from `--engine-root`.+- The original explicit `target_exe` path remains supported.++## Export Filters++`timing-events` and `timer-stats` support:++- `--columns`+- `--threads`+- `--timers`+- `--start-time`+- `--end-time`+- `--region`++`counter-values` supports:++- `--counter`+- `--columns`+- `--start-time`+- `--end-time`+- `--region`++## Testing++```bash+cd unrealinsights/agent-harness+pytest cli_anything/unrealinsights/tests/test_core.py -v+pytest cli_anything/unrealinsights/tests/test_full_e2e.py -v -s+```++Optional environment variables for E2E coverage:++- `UNREALINSIGHTS_TEST_TRACE`+- `UNREALINSIGHTS_TEST_TARGET_EXE`diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/__init__.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/__init__.pynew file mode 100644index 000000000..9fb92967c--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/__init__.py@@ -0,0 +1,5 @@+"""cli-anything Unreal Insights harness."""++__all__ = ["__version__"]++__version__ = "0.1.0"diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/__main__.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/__main__.pynew file mode 100644index 000000000..a58b161ad--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/__main__.py@@ -0,0 +1,7 @@+"""Module entry point for cli_anything.unrealinsights."""++from cli_anything.unrealinsights.unrealinsights_cli import main+++if __name__ == "__main__":+ main()diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/core/__init__.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/core/__init__.pynew file mode 100644index 000000000..5f4b90c4f--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/core/__init__.py@@ -0,0 +1 @@+"""Core helpers for the Unreal Insights harness."""diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/core/capture.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/core/capture.pynew file mode 100644index 000000000..89e4d3864--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/core/capture.py@@ -0,0 +1,169 @@+"""+Capture orchestration helpers.+"""++from __future__ import annotations++import os+import time+from pathlib import Path+from typing import Sequence++from cli_anything.unrealinsights.utils import unrealinsights_backend as backend++DEFAULT_CHANNELS = "default"+EDITOR_BINARY_NAME = "UnrealEditor.exe"+++def normalize_trace_output_path(+ target_exe: str,+ output_trace: str | None = None,+ current_trace: str | None = None,+ cwd: str | None = None,+) -> str:+ """Resolve the output trace path for a capture workflow."""+ if output_trace:+ path = Path(output_trace).expanduser()+ elif current_trace:+ path = Path(current_trace).expanduser()+ else:+ base_dir = Path(cwd or os.getcwd()).resolve()+ timestamp = time.strftime("%Y%m%d-%H%M%S")+ path = base_dir / f"{Path(target_exe).stem}-{timestamp}.utrace"++ if not path.suffix:+ path = path.with_suffix(".utrace")+ return str(path.resolve())+++def build_exec_cmds_arg(exec_cmds: Sequence[str] | None) -> str | None:+ if not exec_cmds:+ return None+ commands = [cmd.strip() for cmd in exec_cmds if cmd.strip()]+ return ",".join(commands) if commands else None+++def resolve_engine_root(engine_root: str) -> str:+ """Normalize an Unreal Engine installation root."""+ path = Path(engine_root).expanduser().resolve()+ root = path.parent if path.name.lower() == "engine" else path++ if not root.exists():+ raise RuntimeError(f"Engine root not found: {root}")+ if not (root / "Engine").is_dir():+ raise RuntimeError(f"Engine root must contain an Engine directory: {root}")++ return str(root)+++def resolve_editor_target(engine_root: str) -> str:+ """Resolve UnrealEditor.exe from a UE install root or Engine directory."""+ root = Path(resolve_engine_root(engine_root))+ editor = root / "Engine" / "Binaries" / "Win64" / EDITOR_BINARY_NAME+ if not editor.is_file():+ raise RuntimeError(f"UnrealEditor.exe not found under engine root: {root}")+ return str(editor.resolve())+++def resolve_capture_target(+ target_exe: str | None,+ project: str | None = None,+ engine_root: str | None = None,+ target_args: Sequence[str] | None = None,+) -> tuple[str, list[str], dict[str, str | None]]:+ """Resolve the effective target executable and launch args."""+ resolved_project = None+ resolved_engine_root = None+ launch_args = list(target_args or [])++ if project:+ project_path = Path(project).expanduser().resolve()+ if not project_path.is_file():+ raise RuntimeError(f"Project file not found: {project_path}")+ resolved_project = str(project_path)++ if target_exe:+ target_path = Path(target_exe).expanduser().resolve()+ if not target_path.is_file():+ raise RuntimeError(f"Target executable not found: {target_path}")+ resolved_target = str(target_path)+ else:+ if not resolved_project:+ raise RuntimeError("Either target_exe or --project must be provided.")+ if not engine_root:+ raise RuntimeError("--engine-root is required when inferring UnrealEditor.exe from --project.")+ resolved_engine_root = resolve_engine_root(engine_root)+ resolved_target = resolve_editor_target(resolved_engine_root)++ if engine_root and resolved_engine_root is None:+ resolved_engine_root = resolve_engine_root(engine_root)++ if resolved_project and resolved_project not in launch_args:+ launch_args = [resolved_project, *launch_args]++ return resolved_target, launch_args, {+ "project_path": resolved_project,+ "engine_root": resolved_engine_root,+ }+++def build_capture_command(+ target_exe: str,+ output_trace: str,+ channels: str = DEFAULT_CHANNELS,+ exec_cmds: Sequence[str] | None = None,+ target_args: Sequence[str] | None = None,+) -> list[str]:+ """Build the traced target command line."""+ target_path = Path(target_exe).expanduser().resolve()+ if not target_path.is_file():+ raise RuntimeError(f"Target executable not found: {target_path}")++ command = [str(target_path)]+ command.extend(target_args or [])+ command.append(f"-trace={channels}")+ command.append(f"-tracefile={Path(output_trace).expanduser().resolve()}")++ exec_arg = build_exec_cmds_arg(exec_cmds)+ if exec_arg:+ command.append(f"-ExecCmds={exec_arg}")++ return command+++def run_capture(+ target_exe: str,+ output_trace: str,+ channels: str = DEFAULT_CHANNELS,+ exec_cmds: Sequence[str] | None = None,+ target_args: Sequence[str] | None = None,+ wait: bool = False,+ timeout: float | None = None,+) -> dict[str, object]:+ """Launch a traced target executable."""+ backend.ensure_parent_dir(output_trace)+ command = build_capture_command(+ target_exe,+ output_trace=output_trace,+ channels=channels,+ exec_cmds=exec_cmds,+ target_args=target_args,+ )+ result = backend.run_process(command, timeout=timeout, wait=wait)++ trace_path = Path(output_trace).expanduser().resolve()+ trace_exists = trace_path.is_file()+ trace_size = trace_path.stat().st_size if trace_exists else None++ result.update(+ {+ "target_exe": str(Path(target_exe).expanduser().resolve()),+ "target_args": list(target_args or []),+ "trace_path": str(trace_path),+ "channels": channels,+ "trace_exists": trace_exists,+ "trace_size": trace_size,+ "succeeded": bool(trace_exists) if wait else True,+ }+ )+ return resultdiff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/core/export.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/core/export.pynew file mode 100644index 000000000..c587ab5dc--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/core/export.py@@ -0,0 +1,259 @@+"""+Exporter command construction and execution helpers.+"""++from __future__ import annotations++import ctypes+import os+import shlex+from pathlib import Path++from cli_anything.unrealinsights.utils import unrealinsights_backend as backend++EXPORTER_COMMANDS = {+ "threads": "TimingInsights.ExportThreads",+ "timers": "TimingInsights.ExportTimers",+ "timing-events": "TimingInsights.ExportTimingEvents",+ "timer-stats": "TimingInsights.ExportTimerStatistics",+ "timer-callees": "TimingInsights.ExportTimerCallees",+ "counters": "TimingInsights.ExportCounters",+ "counter-values": "TimingInsights.ExportCounterValues",+}+++def _quote(value: str) -> str:+ return f'"{value}"'+++def _is_legacy_unrealinsights(version: str | None) -> bool:+ return bool(version and version.startswith("5.3"))+++def _windows_short_path(path: Path) -> str | None:+ if os.name != "nt":+ return None+ buffer = ctypes.create_unicode_buffer(32768)+ result = ctypes.windll.kernel32.GetShortPathNameW(str(path), buffer, len(buffer))+ if result == 0:+ return None+ return buffer.value+++def _legacy_filename_arg(output_path: str) -> str:+ path = Path(output_path).expanduser().resolve()+ path_str = str(path)+ if " " not in path_str:+ return path_str++ parent = path.parent+ short_parent = _windows_short_path(parent)+ if not short_parent:+ raise RuntimeError(+ f"Legacy UnrealInsights export requires a path without spaces or a resolvable short path: {path}"+ )+ if " " in path.name:+ raise RuntimeError(+ f"Legacy UnrealInsights export does not support spaces in the output filename: {path.name}"+ )+ return str(Path(short_parent) / path.name)+++def build_export_exec_command(+ exporter: str,+ output_path: str,+ *,+ insights_version: str | None = None,+ columns: str | None = None,+ threads: str | None = None,+ timers: str | None = None,+ start_time: float | None = None,+ end_time: float | None = None,+ region: str | None = None,+ counter: str | None = None,+) -> str:+ """Build a TimingInsights exporter command string."""+ if exporter not in EXPORTER_COMMANDS:+ raise RuntimeError(f"Unsupported exporter: {exporter}")++ output_abs = str(Path(output_path).expanduser().resolve())+ if _is_legacy_unrealinsights(insights_version):+ filename_token = _legacy_filename_arg(output_abs)+ else:+ filename_token = _quote(output_abs)++ parts = [EXPORTER_COMMANDS[exporter], filename_token]++ if counter:+ parts.append(f"-counter={_quote(counter)}")+ if columns:+ parts.append(f"-columns={_quote(columns)}")+ if threads:+ parts.append(f"-threads={_quote(threads)}")+ if timers:+ parts.append(f"-timers={_quote(timers)}")+ if start_time is not None:+ parts.append(f"-startTime={start_time}")+ if end_time is not None:+ parts.append(f"-endTime={end_time}")+ if region:+ parts.append(f"-region={_quote(region)}")++ return " ".join(parts)+++def build_rsp_exec_command(rsp_path: str) -> str:+ """Build the response-file execution token."""+ return f"@={Path(rsp_path).expanduser().resolve()}"+++def _path_contains_placeholders(path: Path) -> bool:+ return "{counter}" in path.name or "{region}" in path.name+++def collect_materialized_outputs(output_path: str) -> list[str]:+ """Collect actual output files for a requested exporter path."""+ path = Path(output_path).expanduser().resolve()+ if _path_contains_placeholders(path):+ pattern = path.name.replace("{counter}", "*").replace("{region}", "*")+ return sorted(str(match.resolve()) for match in path.parent.glob(pattern) if match.is_file())+ if path.is_file():+ return [str(path)]+ return []+++def _token_output_path(command_line: str) -> str | None:+ try:+ tokens = shlex.split(command_line, posix=False)+ except ValueError:+ return None+ if len(tokens) < 2:+ return None+ return tokens[1].strip('"')+++def expected_outputs_from_rsp(rsp_path: str) -> list[str]:+ """Read a response file and infer output files from each command line."""+ path = Path(rsp_path).expanduser().resolve()+ outputs: list[str] = []+ if not path.is_file():+ return outputs++ for line in path.read_text(encoding="utf-8", errors="replace").splitlines():+ stripped = line.strip()+ if not stripped or stripped.startswith("#"):+ continue+ output = _token_output_path(stripped)+ if output:+ outputs.append(str(Path(output).expanduser().resolve()))+ return outputs+++def default_log_path(reference_path: str, suffix: str = ".insights.log") -> str:+ path = Path(reference_path).expanduser().resolve()+ return str(path.with_name(f"{path.stem}{suffix}"))+++def _execute_insights(+ insights_exe: str,+ trace_path: str,+ exec_command: str,+ expected_outputs: list[str],+ log_path: str,+) -> dict[str, object]:+ backend.ensure_parent_dir(log_path)+ for output in expected_outputs:+ if "{" not in Path(output).name:+ backend.ensure_parent_dir(output)++ raw_command = backend.build_insights_command_line(insights_exe, trace_path, exec_command, log_path)+ run_result = backend.run_process(+ raw_command,+ wait=True,+ )+ log_info = backend.parse_unreal_log(log_path)++ actual_outputs: list[str] = []+ seen: set[str] = set()+ for output in expected_outputs:+ for match in collect_materialized_outputs(output):+ if match not in seen:+ actual_outputs.append(match)+ seen.add(match)++ run_result.update(+ {+ "trace_path": str(Path(trace_path).expanduser().resolve()),+ "exec_command": exec_command,+ "expected_outputs": expected_outputs,+ "output_files": actual_outputs,+ "log_path": log_info["path"],+ "warnings": log_info["warnings"],+ "errors": log_info["errors"],+ "succeeded": (+ not run_result["timed_out"]+ and run_result["exit_code"] == 0+ and len(actual_outputs) > 0+ ),+ }+ )+ return run_result+++def execute_export(+ insights_exe: str,+ trace_path: str,+ exporter: str,+ output_path: str,+ *,+ insights_version: str | None = None,+ columns: str | None = None,+ threads: str | None = None,+ timers: str | None = None,+ start_time: float | None = None,+ end_time: float | None = None,+ region: str | None = None,+ counter: str | None = None,+ log_path: str | None = None,+) -> dict[str, object]:+ """Execute a single TimingInsights exporter."""+ output_abs = str(Path(output_path).expanduser().resolve())+ resolved_log_path = log_path or default_log_path(output_abs)+ exec_command = build_export_exec_command(+ exporter,+ output_abs,+ insights_version=insights_version,+ columns=columns,+ threads=threads,+ timers=timers,+ start_time=start_time,+ end_time=end_time,+ region=region,+ counter=counter,+ )+ return _execute_insights(+ insights_exe,+ trace_path,+ exec_command=exec_command,+ expected_outputs=[output_abs],+ log_path=resolved_log_path,+ )+++def execute_response_file(+ insights_exe: str,+ trace_path: str,+ rsp_path: str,+ *,+ log_path: str | None = None,+) -> dict[str, object]:+ """Execute a response file batch export."""+ rsp_abs = str(Path(rsp_path).expanduser().resolve())+ resolved_log_path = log_path or default_log_path(rsp_abs)+ return _execute_insights(+ insights_exe,+ trace_path,+ exec_command=build_rsp_exec_command(rsp_abs),+ expected_outputs=expected_outputs_from_rsp(rsp_abs),+ log_path=resolved_log_path,+ )diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/core/session.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/core/session.pynew file mode 100644index 000000000..e6de13ae9--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/core/session.py@@ -0,0 +1,38 @@+"""+In-memory session state for Unreal Insights CLI workflows.+"""++from __future__ import annotations++from dataclasses import dataclass+from pathlib import Path+++@dataclass+class UnrealInsightsSession:+ trace_path: str | None = None+ insights_exe: str | None = None+ trace_server_exe: str | None = None++ def set_trace(self, trace_path: str | None):+ self.trace_path = str(Path(trace_path).expanduser().resolve()) if trace_path else None++ def set_insights_exe(self, path: str | None):+ self.insights_exe = str(Path(path).expanduser().resolve()) if path else None++ def set_trace_server_exe(self, path: str | None):+ self.trace_server_exe = str(Path(path).expanduser().resolve()) if path else None++ def trace_info(self) -> dict[str, object]:+ if self.trace_path is None:+ return {+ "trace_path": None,+ "exists": False,+ }++ path = Path(self.trace_path)+ return {+ "trace_path": str(path),+ "exists": path.is_file(),+ "file_size": path.stat().st_size if path.is_file() else None,+ }diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/skills/SKILL.md b/unrealinsights/agent-harness/cli_anything/unrealinsights/skills/SKILL.mdnew file mode 100644index 000000000..8943b48da--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/skills/SKILL.md@@ -0,0 +1,102 @@+---+name: "cli-anything-unrealinsights"+description: "Capture Unreal Engine traces to .utrace files and export Unreal Insights timing/counter data in headless mode."+---++# cli-anything-unrealinsights++Use this CLI when you need agent-friendly access to Unreal Insights trace capture+and exporter workflows on Windows.++## Prerequisites++- Unreal Engine 5.5+ installed with `UnrealInsights.exe`+- Windows+- Optional explicit env vars:+ - `UNREALINSIGHTS_EXE`+ - `UNREAL_TRACE_SERVER_EXE`+ - `UNREALINSIGHTS_TRACE`++## Core Commands++### Backend discovery++```powershell+cli-anything-unrealinsights --json backend info+```++To use a source-built engine's matching `UnrealInsights.exe`:++```powershell+cli-anything-unrealinsights --json backend ensure-insights `+ --engine-root 'D:\code\D5\d5render-ue5_3'+```++This first looks for `Engine\Binaries\Win64\UnrealInsights.exe` under the+specified engine root, then builds it with that engine's `Build.bat` if needed.++### Trace session state++```powershell+cli-anything-unrealinsights trace set D:\captures\session.utrace+cli-anything-unrealinsights --json trace info+```++### Capture orchestration++```powershell+cli-anything-unrealinsights --json capture run `+ --project 'D:\Projects\MyGame\MyGame.uproject' `+ --engine-root 'D:\Program Files\Epic Games\UE_5.5' `+ --output-trace D:\captures\boot.utrace `+ --channels "default,bookmark" `+ --exec-cmd "Trace.Bookmark BootStart" `+ --wait --timeout 300+```++You can also keep using the explicit form:++```powershell+cli-anything-unrealinsights --json capture run `+ 'D:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealEditor.exe' `+ --target-arg 'D:\Projects\MyGame\MyGame.uproject'+```++### Offline exporters++```powershell+cli-anything-unrealinsights --json -t D:\captures\session.utrace export threads D:\out\threads.csv+cli-anything-unrealinsights --json -t D:\captures\session.utrace export timer-stats D:\out\stats.csv --region "EXPORT_CAPTURE"+cli-anything-unrealinsights --json -t D:\captures\session.utrace export counter-values D:\out\counter_values.csv --counter "*"+```++### Batch response files++```powershell+cli-anything-unrealinsights --json -t D:\captures\session.utrace batch run-rsp D:\out\exports.rsp+```++## JSON Output Guidance++- Prefer `--json` for agent workflows.+- Export commands return:+ - `trace_path`+ - `exec_command`+ - `output_files`+ - `log_path`+ - `exit_code`+ - `warnings`+ - `errors`+ - `succeeded`+- Capture returns:+ - `command`+ - `trace_path`+ - `trace_exists`+ - `trace_size`+ - `pid` or `exit_code`++## Notes++- v1 is Windows-first.+- v1 supports file-mode capture orchestration only.+- v1 does not control already-running UE instances or browse trace stores.diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/tests/TEST.md b/unrealinsights/agent-harness/cli_anything/unrealinsights/tests/TEST.mdnew file mode 100644index 000000000..f9492a3ee--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/tests/TEST.md@@ -0,0 +1,172 @@+# TEST.md - Unreal Insights CLI Test Plan++## Test Inventory Plan++- `test_core.py`: 39 unit tests planned+- `test_full_e2e.py`: 10 E2E tests planned++## Unit Test Plan++### `utils/unrealinsights_backend.py`+- Validate binary discovery precedence: explicit path, env var, then Windows auto-discovery+- Validate missing explicit and env paths fail loudly+- Validate Unreal Insights command construction+- Validate engine-root binary resolution and build orchestration+- Planned tests: 13++### `core/capture.py`+- Validate output trace path normalization+- Validate traced target command construction+- Validate `-ExecCmds=` joining semantics+- Validate `--project + --engine-root` convenience resolution+- Planned tests: 8++### `core/export.py`+- Validate exporter command strings for all supported exporters+- Validate response-file parsing and output inference+- Validate placeholder-aware output collection+- Validate legacy UnrealInsights 5.3 export command compatibility+- Planned tests: 9++### `unrealinsights_cli.py`+- Validate root and group help+- Validate JSON error payloads when trace/backend requirements are missing+- Validate REPL session trace state+- Validate capture convenience-layer argument handling+- Planned tests: 7++## E2E Test Plan++### Prerequisites+- Unreal Engine 5.5+ installed with `UnrealInsights.exe`+- Optional trace file via `UNREALINSIGHTS_TEST_TRACE`+- Optional UE/Game executable via `UNREALINSIGHTS_TEST_TARGET_EXE`++### Workflows to validate+- `backend info` against the local UE install+- Export threads/timers/timing-events/timer-stats/timer-callees/counters/counter-values from a real `.utrace`+- Execute a generated response file containing multiple exporter commands+- Launch a traced target executable in file mode and verify `.utrace` creation++### Output validation+- All `--json` responses parse correctly+- Export commands create non-empty output files and surface log paths+- `batch run-rsp` returns the materialized output list+- `capture run --wait` returns exit status plus `.utrace` file metadata++## Realistic Workflow Scenarios++### Workflow name: `trace_export_bundle`+- Simulates: post-capture analysis of a performance trace+- Operations chained:+ 1. `trace set`+ 2. `export threads`+ 3. `export timer-stats`+ 4. `export counter-values`+ 5. `batch run-rsp`+- Verified:+ - exporter outputs exist+ - response-file execution triggers multiple materialized files+ - JSON payloads include log path and exit code++### Workflow name: `editor_boot_capture`+- Simulates: launching a traced UE executable and recording startup behavior+- Operations chained:+ 1. `capture run`+ 2. `trace info`+ 3. optional exporter pass on the produced trace+- Verified:+ - traced command line contains `-trace=` and `-tracefile=`+ - `.utrace` file is created and has size > 0++## Test Results++### Commands run++```bash+python -m pytest cli_anything/unrealinsights/tests/test_core.py -v --tb=no+python -m pytest cli_anything/unrealinsights/tests/test_full_e2e.py -v -s --tb=no+python -m pip install -e .+cli-anything-unrealinsights --json backend info+```++### Result summary++- `test_core.py`: 39 passed+- `test_full_e2e.py`: 1 passed, 9 skipped+- Manual smoke: installed entrypoint resolved local UE 5.5 binaries successfully++### Coverage notes++- Real export and capture E2E scenarios are env-gated and were skipped because+ `UNREALINSIGHTS_TEST_TRACE` and `UNREALINSIGHTS_TEST_TARGET_EXE` were not set.+- The local Windows auto-discovery path was validated against:+ - `D:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealInsights.exe`+ - `D:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealTraceServer.exe`++### Full pytest output++```text+============================= test session starts =============================+platform win32 -- Python 3.11.9, pytest-9.0.3, pluggy-1.6.0 -- C:\Users\aimidi\AppData\Local\Programs\Python\Python311\python.exe+cachedir: .pytest_cache+rootdir: D:\code\D5\CLI-Anything-unrealinsights\unrealinsights\agent-harness+collecting ... collected 39 items++cli_anything/unrealinsights/tests/test_core.py::TestOutputUtils::test_output_json PASSED [ 3%]+cli_anything/unrealinsights/tests/test_core.py::TestOutputUtils::test_output_table_empty PASSED [ 7%]+cli_anything/unrealinsights/tests/test_core.py::TestOutputUtils::test_format_size PASSED [ 11%]+cli_anything/unrealinsights/tests/test_core.py::TestErrorUtils::test_handle_error PASSED [ 14%]+cli_anything/unrealinsights/tests/test_core.py::TestBackendDiscovery::test_explicit_path_precedence PASSED [ 18%]+cli_anything/unrealinsights/tests/test_core.py::TestBackendDiscovery::test_env_path_precedence PASSED [ 22%]+cli_anything/unrealinsights/tests/test_core.py::TestBackendDiscovery::test_auto_discovery PASSED [ 25%]+cli_anything/unrealinsights/tests/test_core.py::TestBackendDiscovery::test_missing_explicit_path_fails PASSED [ 29%]+cli_anything/unrealinsights/tests/test_core.py::TestBackendDiscovery::test_build_insights_command PASSED [ 33%]+cli_anything/unrealinsights/tests/test_core.py::TestCaptureCore::test_normalize_trace_output_path_prefers_explicit PASSED [ 37%]+cli_anything/unrealinsights/tests/test_core.py::TestCaptureCore::test_build_exec_cmds_arg PASSED [ 40%]+cli_anything/unrealinsights/tests/test_core.py::TestCaptureCore::test_resolve_engine_root_from_engine_subdir PASSED [ 43%]+cli_anything/unrealinsights/tests/test_core.py::TestCaptureCore::test_resolve_editor_target PASSED [ 46%]+cli_anything/unrealinsights/tests/test_core.py::TestCaptureCore::test_resolve_capture_target_from_project_and_engine PASSED [ 50%]+cli_anything/unrealinsights/tests/test_core.py::TestCaptureCore::test_build_capture_command PASSED [ 53%]+cli_anything/unrealinsights/tests/test_core.py::TestExportCore::test_build_export_exec_command[threads-TimingInsights.ExportThreads] PASSED [ 56%]+cli_anything/unrealinsights/tests/test_core.py::TestExportCore::test_build_export_exec_command[timers-TimingInsights.ExportTimers] PASSED [ 59%]+cli_anything/unrealinsights/tests/test_core.py::TestExportCore::test_build_export_exec_command[timing-events-TimingInsights.ExportTimingEvents] PASSED [ 62%]+cli_anything/unrealinsights/tests/test_core.py::TestExportCore::test_build_export_exec_command[timer-stats-TimingInsights.ExportTimerStatistics] PASSED [ 65%]+cli_anything/unrealinsights/tests/test_core.py::TestExportCore::test_build_export_exec_command[timer-callees-TimingInsights.ExportTimerCallees] PASSED [ 68%]+cli_anything/unrealinsights/tests/test_core.py::TestExportCore::test_build_export_exec_command[counters-TimingInsights.ExportCounters] PASSED [ 71%]+cli_anything/unrealinsights/tests/test_core.py::TestExportCore::test_build_export_exec_command[counter-values-TimingInsights.ExportCounterValues] PASSED [ 75%]+cli_anything/unrealinsights/tests/test_core.py::TestExportCore::test_build_rsp_exec_command PASSED [ 78%]+cli_anything/unrealinsights/tests/test_core.py::TestExportCore::test_expected_outputs_from_rsp PASSED [ 81%]+cli_anything/unrealinsights/tests/test_core.py::TestExportCore::test_collect_materialized_outputs_placeholder PASSED [ 84%]+cli_anything/unrealinsights/tests/test_core.py::TestCLIHelp::test_main_help PASSED [ 87%]+cli_anything/unrealinsights/tests/test_core.py::TestCLIHelp::test_group_help PASSED [ 90%]+cli_anything/unrealinsights/tests/test_core.py::TestCLIJsonErrors::test_export_threads_requires_trace PASSED [ 93%]+cli_anything/unrealinsights/tests/test_core.py::TestCLIJsonErrors::test_backend_info_json PASSED [ 96%]+cli_anything/unrealinsights/tests/test_core.py::TestCLIJsonErrors::test_capture_project_requires_engine_root PASSED [ 96%]+cli_anything/unrealinsights/tests/test_core.py::TestREPLSessionState::test_trace_set_then_info_in_repl PASSED [ 99%]+cli_anything/unrealinsights/tests/test_core.py::TestCaptureCLIConvenience::test_capture_run_with_project_and_engine_root PASSED [100%]++============================= 39 passed in 0.52s ==============================++============================= test session starts =============================+platform win32 -- Python 3.11.9, pytest-9.0.3, pluggy-1.6.0 -- C:\Users\aimidi\AppData\Local\Programs\Python\Python311\python.exe+cachedir: .pytest_cache+rootdir: D:\code\D5\CLI-Anything-unrealinsights\unrealinsights\agent-harness+collecting ... [_resolve_cli] Using installed command: C:\Users\aimidi\AppData\Local\Programs\Python\Python311\Scripts\cli-anything-unrealinsights.EXE+[_resolve_cli] Using installed command: C:\Users\aimidi\AppData\Local\Programs\Python\Python311\Scripts\cli-anything-unrealinsights.EXE+[_resolve_cli] Using installed command: C:\Users\aimidi\AppData\Local\Programs\Python\Python311\Scripts\cli-anything-unrealinsights.EXE+collected 10 items++cli_anything/unrealinsights/tests/test_full_e2e.py::TestCLISmoke::test_backend_info PASSED+cli_anything/unrealinsights/tests/test_full_e2e.py::TestExportE2E::test_exporter_creates_output[threads-extra_args0] SKIPPED+cli_anything/unrealinsights/tests/test_full_e2e.py::TestExportE2E::test_exporter_creates_output[timers-extra_args1] SKIPPED+cli_anything/unrealinsights/tests/test_full_e2e.py::TestExportE2E::test_exporter_creates_output[timing-events-extra_args2] SKIPPED+cli_anything/unrealinsights/tests/test_full_e2e.py::TestExportE2E::test_exporter_creates_output[timer-stats-extra_args3] SKIPPED+cli_anything/unrealinsights/tests/test_full_e2e.py::TestExportE2E::test_exporter_creates_output[timer-callees-extra_args4] SKIPPED+cli_anything/unrealinsights/tests/test_full_e2e.py::TestExportE2E::test_exporter_creates_output[counters-extra_args5] SKIPPED+cli_anything/unrealinsights/tests/test_full_e2e.py::TestExportE2E::test_exporter_creates_output[counter-values-extra_args6] SKIPPED+cli_anything/unrealinsights/tests/test_full_e2e.py::TestExportE2E::test_batch_run_rsp SKIPPED+cli_anything/unrealinsights/tests/test_full_e2e.py::TestCaptureE2E::test_capture_run_wait SKIPPED++======================== 1 passed, 9 skipped in 0.85s =========================+```diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/tests/__init__.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/tests/__init__.pynew file mode 100644index 000000000..ed87f3cc2--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/tests/__init__.py@@ -0,0 +1 @@+"""Tests for cli-anything-unrealinsights."""diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/tests/test_core.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/tests/test_core.pynew file mode 100644index 000000000..061a13746--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/tests/test_core.py@@ -0,0 +1,498 @@+"""+Unit tests for Unreal Insights harness modules.+"""++from __future__ import annotations++import json+from pathlib import Path+from unittest.mock import patch++import pytest+from click.testing import CliRunner+++class TestOutputUtils:+ def test_output_json(self):+ import io++ from cli_anything.unrealinsights.utils.output import output_json++ buf = io.StringIO()+ output_json({"ok": True, "value": 42}, file=buf)+ data = json.loads(buf.getvalue())+ assert data["ok"] is True+ assert data["value"] == 42++ def test_output_table_empty(self):+ import io++ from cli_anything.unrealinsights.utils.output import output_table++ buf = io.StringIO()+ output_table([], ["col"], file=buf)+ assert "(no data)" in buf.getvalue()++ def test_format_size(self):+ from cli_anything.unrealinsights.utils.output import format_size++ assert format_size(10) == "10 B"+ assert "KB" in format_size(4096)+++class TestErrorUtils:+ def test_handle_error(self):+ from cli_anything.unrealinsights.utils.errors import handle_error++ result = handle_error(ValueError("bad"))+ assert result["error"] == "bad"+ assert result["type"] == "ValueError"+++def _make_fake_binary(root: Path, binary_name: str) -> Path:+ target = root / "UE_5.5" / "Engine" / "Binaries" / "Win64" / binary_name+ target.parent.mkdir(parents=True, exist_ok=True)+ target.write_text("fake-binary", encoding="utf-8")+ return target+++class TestBackendDiscovery:+ @patch("cli_anything.unrealinsights.utils.unrealinsights_backend._read_windows_product_version", return_value="5.5.4")+ def test_explicit_path_precedence(self, _mock_version, tmp_path, monkeypatch):+ from cli_anything.unrealinsights.utils.unrealinsights_backend import resolve_unrealinsights_exe++ explicit = tmp_path / "explicit" / "UnrealInsights.exe"+ explicit.parent.mkdir(parents=True)+ explicit.write_text("x", encoding="utf-8")++ env_binary = tmp_path / "env" / "UnrealInsights.exe"+ env_binary.parent.mkdir(parents=True)+ env_binary.write_text("x", encoding="utf-8")+ monkeypatch.setenv("UNREALINSIGHTS_EXE", str(env_binary))++ auto_root = tmp_path / "Epic Games"+ _make_fake_binary(auto_root, "UnrealInsights.exe")++ result = resolve_unrealinsights_exe(str(explicit), search_roots=[auto_root])+ assert result["source"] == "explicit"+ assert result["path"] == str(explicit.resolve())++ @patch("cli_anything.unrealinsights.utils.unrealinsights_backend._read_windows_product_version", return_value="5.5.4")+ def test_env_path_precedence(self, _mock_version, tmp_path, monkeypatch):+ from cli_anything.unrealinsights.utils.unrealinsights_backend import resolve_unrealinsights_exe++ env_binary = tmp_path / "env" / "UnrealInsights.exe"+ env_binary.parent.mkdir(parents=True)+ env_binary.write_text("x", encoding="utf-8")+ monkeypatch.setenv("UNREALINSIGHTS_EXE", str(env_binary))++ auto_root = tmp_path / "Epic Games"+ _make_fake_binary(auto_root, "UnrealInsights.exe")++ result = resolve_unrealinsights_exe(search_roots=[auto_root])+ assert result["source"] == "env:UNREALINSIGHTS_EXE"+ assert result["path"] == str(env_binary.resolve())++ @patch("cli_anything.unrealinsights.utils.unrealinsights_backend._read_windows_product_version", return_value="5.5.4")+ def test_auto_discovery(self, _mock_version, tmp_path, monkeypatch):+ from cli_anything.unrealinsights.utils.unrealinsights_backend import resolve_unrealinsights_exe++ monkeypatch.delenv("UNREALINSIGHTS_EXE", raising=False)+ auto_root = tmp_path / "Epic Games"+ auto_binary = _make_fake_binary(auto_root, "UnrealInsights.exe")++ result = resolve_unrealinsights_exe(search_roots=[auto_root])+ assert result["source"].startswith("auto:")+ assert result["path"] == str(auto_binary.resolve())++ def test_missing_explicit_path_fails(self, tmp_path):+ from cli_anything.unrealinsights.utils.unrealinsights_backend import resolve_unrealinsights_exe++ with pytest.raises(RuntimeError):+ resolve_unrealinsights_exe(str(tmp_path / "missing.exe"))++ def test_build_insights_command(self, tmp_path):+ from cli_anything.unrealinsights.utils.unrealinsights_backend import build_insights_command++ command = build_insights_command(+ str(tmp_path / "UnrealInsights.exe"),+ str(tmp_path / "trace.utrace"),+ 'TimingInsights.ExportThreads "D:\\out\\threads.csv"',+ str(tmp_path / "threads.log"),+ )+ assert any(part.startswith("-OpenTraceFile=") for part in command)+ assert any(part.startswith("-ExecOnAnalysisCompleteCmd=") for part in command)++ def test_build_insights_command_line(self, tmp_path):+ from cli_anything.unrealinsights.utils.unrealinsights_backend import build_insights_command_line++ command = build_insights_command_line(+ str(tmp_path / "UnrealInsights.exe"),+ str(tmp_path / "trace.utrace"),+ 'TimingInsights.ExportThreads D:\\out\\threads.csv',+ str(tmp_path / "threads.log"),+ )+ assert "-ExecOnAnalysisCompleteCmd=" in command+ assert command.startswith('"')++ @patch("cli_anything.unrealinsights.utils.unrealinsights_backend._read_windows_product_version", return_value="5.3.0")+ def test_resolve_binary_from_engine_root(self, _mock_version, tmp_path):+ from cli_anything.unrealinsights.utils.unrealinsights_backend import resolve_binary_from_engine_root++ binary = _make_fake_binary(tmp_path, "UnrealInsights.exe")+ result = resolve_binary_from_engine_root("UnrealInsights.exe", str(tmp_path / "UE_5.5"))+ assert result["path"] == str(binary.resolve())+ assert result["source"] == "engine:UE_5.5"++ @patch("cli_anything.unrealinsights.utils.unrealinsights_backend.subprocess.run")+ def test_build_engine_program(self, mock_run, tmp_path):+ from cli_anything.unrealinsights.utils.unrealinsights_backend import build_engine_program++ build_bat = tmp_path / "UE_5.5" / "Engine" / "Build" / "BatchFiles" / "Build.bat"+ build_bat.parent.mkdir(parents=True, exist_ok=True)+ build_bat.write_text("echo build", encoding="utf-8")++ mock_run.return_value = type("Result", (), {"stdout": "ok", "stderr": "", "returncode": 0})()+ result = build_engine_program(str(tmp_path / "UE_5.5"), "UnrealInsights")+ assert result["succeeded"] is True+ assert Path(result["log_path"]).is_file()++ @patch("cli_anything.unrealinsights.utils.unrealinsights_backend._read_windows_product_version", return_value="5.3.0")+ @patch("cli_anything.unrealinsights.utils.unrealinsights_backend.build_engine_program")+ def test_ensure_engine_unrealinsights_builds_when_missing(self, mock_build, _mock_version, tmp_path):+ from cli_anything.unrealinsights.utils.unrealinsights_backend import ensure_engine_unrealinsights++ engine_root = tmp_path / "UE_5.5"+ (engine_root / "Engine" / "Binaries" / "Win64").mkdir(parents=True, exist_ok=True)+ (engine_root / "Engine" / "Build" / "BatchFiles").mkdir(parents=True, exist_ok=True)+ (engine_root / "Engine" / "Build" / "BatchFiles" / "Build.bat").write_text("echo build", encoding="utf-8")+ built_exe = engine_root / "Engine" / "Binaries" / "Win64" / "UnrealInsights.exe"+ built_exe.write_text("x", encoding="utf-8")+ mock_build.return_value = {+ "command": ["Build.bat"],+ "cwd": str(engine_root),+ "log_path": str(engine_root / "build.log"),+ "exit_code": 0,+ "timed_out": False,+ "stdout": "",+ "stderr": "",+ "succeeded": True,+ }++ result = ensure_engine_unrealinsights(str(engine_root))+ assert result["insights"]["path"] == str(built_exe.resolve())++ def test_ensure_engine_unrealinsights_no_build_errors_when_missing(self, tmp_path):+ from cli_anything.unrealinsights.utils.unrealinsights_backend import ensure_engine_unrealinsights++ engine_root = tmp_path / "UE_5.5"+ (engine_root / "Engine" / "Binaries" / "Win64").mkdir(parents=True, exist_ok=True)+ with pytest.raises(RuntimeError):+ ensure_engine_unrealinsights(str(engine_root), build_if_missing=False)+++class TestCaptureCore:+ def test_normalize_trace_output_path_prefers_explicit(self, tmp_path):+ from cli_anything.unrealinsights.core.capture import normalize_trace_output_path++ path = normalize_trace_output_path("game.exe", output_trace=str(tmp_path / "capture"))+ assert path.endswith(".utrace")++ def test_build_exec_cmds_arg(self):+ from cli_anything.unrealinsights.core.capture import build_exec_cmds_arg++ assert build_exec_cmds_arg(["Trace.Bookmark Boot", "Trace.RegionBegin Boot"]) == (+ "Trace.Bookmark Boot,Trace.RegionBegin Boot"+ )++ def test_resolve_engine_root_from_engine_subdir(self, tmp_path):+ from cli_anything.unrealinsights.core.capture import resolve_engine_root++ engine_dir = tmp_path / "UE_5.5" / "Engine"+ engine_dir.mkdir(parents=True)+ assert resolve_engine_root(str(engine_dir)) == str((tmp_path / "UE_5.5").resolve())++ def test_resolve_editor_target(self, tmp_path):+ from cli_anything.unrealinsights.core.capture import resolve_editor_target++ editor = tmp_path / "UE_5.5" / "Engine" / "Binaries" / "Win64" / "UnrealEditor.exe"+ editor.parent.mkdir(parents=True)+ editor.write_text("x", encoding="utf-8")+ assert resolve_editor_target(str(tmp_path / "UE_5.5")) == str(editor.resolve())++ def test_resolve_capture_target_from_project_and_engine(self, tmp_path):+ from cli_anything.unrealinsights.core.capture import resolve_capture_target++ editor = tmp_path / "UE_5.5" / "Engine" / "Binaries" / "Win64" / "UnrealEditor.exe"+ editor.parent.mkdir(parents=True)+ editor.write_text("x", encoding="utf-8")+ project = tmp_path / "Project" / "MyGame.uproject"+ project.parent.mkdir(parents=True)+ project.write_text("{}", encoding="utf-8")++ target_exe, target_args, launch_info = resolve_capture_target(+ None,+ project=str(project),+ engine_root=str(tmp_path / "UE_5.5"),+ target_args=["-game"],+ )+ assert target_exe == str(editor.resolve())+ assert target_args[0] == str(project.resolve())+ assert "-game" in target_args+ assert launch_info["project_path"] == str(project.resolve())++ def test_build_capture_command(self, tmp_path):+ from cli_anything.unrealinsights.core.capture import build_capture_command++ exe = tmp_path / "Game.exe"+ exe.write_text("x", encoding="utf-8")+ trace = tmp_path / "capture.utrace"+ command = build_capture_command(+ str(exe),+ str(trace),+ channels="default,bookmark",+ exec_cmds=["Trace.Bookmark Boot"],+ target_args=["MyGame.uproject", "-game"],+ )+ assert command[0] == str(exe.resolve())+ assert "MyGame.uproject" in command+ assert "-trace=default,bookmark" in command+ assert any(arg.startswith("-tracefile=") for arg in command)+ assert any(arg.startswith("-ExecCmds=") for arg in command)+++class TestExportCore:+ @pytest.mark.parametrize(+ ("exporter", "expected"),+ [+ ("threads", "TimingInsights.ExportThreads"),+ ("timers", "TimingInsights.ExportTimers"),+ ("timing-events", "TimingInsights.ExportTimingEvents"),+ ("timer-stats", "TimingInsights.ExportTimerStatistics"),+ ("timer-callees", "TimingInsights.ExportTimerCallees"),+ ("counters", "TimingInsights.ExportCounters"),+ ("counter-values", "TimingInsights.ExportCounterValues"),+ ],+ )+ def test_build_export_exec_command(self, exporter, expected, tmp_path):+ from cli_anything.unrealinsights.core.export import build_export_exec_command++ command = build_export_exec_command(+ exporter,+ str(tmp_path / f"{exporter}.csv"),+ columns="ThreadId,TimerId" if exporter in ("timing-events", "timer-stats", "counter-values") else None,+ threads="GameThread" if exporter in ("timing-events", "timer-stats", "timer-callees") else None,+ timers="*" if exporter in ("timing-events", "timer-stats", "timer-callees") else None,+ counter="*" if exporter == "counter-values" else None,+ )+ assert command.startswith(expected)++ def test_build_rsp_exec_command(self, tmp_path):+ from cli_anything.unrealinsights.core.export import build_rsp_exec_command++ command = build_rsp_exec_command(str(tmp_path / "exports.rsp"))+ assert command.startswith("@=")++ def test_build_export_exec_command_legacy_53_unquoted_filename(self, tmp_path):+ from cli_anything.unrealinsights.core.export import build_export_exec_command++ command = build_export_exec_command(+ "threads",+ str(tmp_path / "threads.csv"),+ insights_version="5.3.0",+ )+ assert '"{}"'.format(str((tmp_path / "threads.csv").resolve())) not in command+ assert str((tmp_path / "threads.csv").resolve()) in command++ def test_expected_outputs_from_rsp(self, tmp_path):+ from cli_anything.unrealinsights.core.export import expected_outputs_from_rsp++ rsp = tmp_path / "exports.rsp"+ rsp.write_text(+ "\n".join(+ [+ "# comment",+ f'TimingInsights.ExportThreads "{tmp_path / "threads.csv"}"',+ f'TimingInsights.ExportTimers "{tmp_path / "timers.csv"}"',+ ]+ ),+ encoding="utf-8",+ )+ outputs = expected_outputs_from_rsp(str(rsp))+ assert str((tmp_path / "threads.csv").resolve()) in outputs+ assert str((tmp_path / "timers.csv").resolve()) in outputs++ def test_collect_materialized_outputs_placeholder(self, tmp_path):+ from cli_anything.unrealinsights.core.export import collect_materialized_outputs++ (tmp_path / "stats_GameThread.csv").write_text("ok", encoding="utf-8")+ outputs = collect_materialized_outputs(str(tmp_path / "stats_{region}.csv"))+ assert str((tmp_path / "stats_GameThread.csv").resolve()) in outputs+++class TestCLIHelp:+ def test_main_help(self):+ from cli_anything.unrealinsights.unrealinsights_cli import cli++ runner = CliRunner()+ result = runner.invoke(cli, ["--help"])+ assert result.exit_code == 0+ assert "Unreal Insights harness" in result.output++ def test_group_help(self):+ from cli_anything.unrealinsights.unrealinsights_cli import cli++ runner = CliRunner()+ for group in ("backend", "trace", "capture", "export", "batch"):+ result = runner.invoke(cli, [group, "--help"])+ assert result.exit_code == 0, f"{group} help failed"+++class TestCLIJsonErrors:+ @patch("cli_anything.unrealinsights.unrealinsights_cli.resolve_unrealinsights_exe")+ def test_export_threads_requires_trace(self, _mock_resolve):+ from cli_anything.unrealinsights.unrealinsights_cli import cli++ runner = CliRunner()+ result = runner.invoke(cli, ["--json", "export", "threads", "out.csv"])+ assert result.exit_code == 1+ data = json.loads(result.output)+ assert "error" in data++ @patch("cli_anything.unrealinsights.unrealinsights_cli.resolve_unrealinsights_exe")+ @patch("cli_anything.unrealinsights.unrealinsights_cli.resolve_trace_server_exe")+ def test_backend_info_json(self, mock_trace_server, mock_insights):+ from cli_anything.unrealinsights.unrealinsights_cli import cli++ mock_insights.return_value = {+ "available": True,+ "path": "C:/UE/UnrealInsights.exe",+ "source": "explicit",+ "version": "5.5.4",+ "engine_version_hint": "5.5",+ }+ mock_trace_server.return_value = {+ "available": False,+ "path": None,+ "source": "unresolved",+ "version": None,+ "engine_version_hint": None,+ "error": "missing",+ }++ runner = CliRunner()+ result = runner.invoke(cli, ["--json", "backend", "info"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert data["insights"]["path"].endswith("UnrealInsights.exe")++ def test_capture_project_requires_engine_root(self, tmp_path):+ from cli_anything.unrealinsights.unrealinsights_cli import cli++ project = tmp_path / "MyGame.uproject"+ project.write_text("{}", encoding="utf-8")++ runner = CliRunner()+ result = runner.invoke(cli, ["--json", "capture", "run", "--project", str(project)])+ assert result.exit_code == 1+ data = json.loads(result.output)+ assert "engine-root" in data["error"]++ @patch("cli_anything.unrealinsights.unrealinsights_cli.ensure_engine_unrealinsights")+ def test_backend_ensure_insights_json(self, mock_ensure):+ from cli_anything.unrealinsights.unrealinsights_cli import cli++ mock_ensure.return_value = {+ "engine_root": "D:/UE_5.3",+ "insights": {+ "available": True,+ "path": "D:/UE_5.3/Engine/Binaries/Win64/UnrealInsights.exe",+ "source": "engine:UE_5.3",+ "version": "5.3.0",+ "engine_version_hint": None,+ },+ "trace_server": {+ "available": False,+ "path": None,+ "source": "unresolved",+ "version": None,+ "engine_version_hint": None,+ "error": "missing",+ },+ "build_attempted": False,+ "build": None,+ }++ runner = CliRunner()+ result = runner.invoke(cli, ["--json", "backend", "ensure-insights", "--engine-root", "D:/UE_5.3"])+ assert result.exit_code == 0+ data = json.loads(result.output)+ assert data["insights"]["path"].endswith("UnrealInsights.exe")+++class TestREPLSessionState:+ def test_trace_set_then_info_in_repl(self):+ from cli_anything.unrealinsights.unrealinsights_cli import cli++ with patch(+ "cli_anything.unrealinsights.utils.repl_skin.ReplSkin.create_prompt_session",+ return_value=None,+ ):+ runner = CliRunner()+ result = runner.invoke(+ cli,+ input="trace set sample.utrace\ntrace info\nquit\n",+ )+ assert result.exit_code == 0+ assert "sample.utrace" in result.output+++class TestCaptureCLIConvenience:+ @patch("cli_anything.unrealinsights.unrealinsights_cli.run_capture")+ def test_capture_run_with_project_and_engine_root(self, mock_run_capture, tmp_path):+ from cli_anything.unrealinsights.unrealinsights_cli import cli++ editor = tmp_path / "UE_5.5" / "Engine" / "Binaries" / "Win64" / "UnrealEditor.exe"+ editor.parent.mkdir(parents=True)+ editor.write_text("x", encoding="utf-8")+ project = tmp_path / "Project" / "MyGame.uproject"+ project.parent.mkdir(parents=True)+ project.write_text("{}", encoding="utf-8")++ mock_run_capture.return_value = {+ "command": [str(editor.resolve()), str(project.resolve()), "-trace=default"],+ "waited": True,+ "timed_out": False,+ "exit_code": 0,+ "stdout": "",+ "stderr": "",+ "pid": None,+ "target_exe": str(editor.resolve()),+ "target_args": [str(project.resolve())],+ "trace_path": str((tmp_path / "capture.utrace").resolve()),+ "channels": "default",+ "trace_exists": True,+ "trace_size": 10,+ "succeeded": True,+ }++ runner = CliRunner()+ result = runner.invoke(+ cli,+ [+ "--json",+ "capture",+ "run",+ "--project",+ str(project),+ "--engine-root",+ str(tmp_path / "UE_5.5"),+ "--output-trace",+ str(tmp_path / "capture.utrace"),+ "--wait",+ ],+ )+ assert result.exit_code == 0+ mock_run_capture.assert_called_once()+ _, kwargs = mock_run_capture.call_args+ assert kwargs["target_args"][0] == str(project.resolve())diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/tests/test_full_e2e.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/tests/test_full_e2e.pynew file mode 100644index 000000000..de2cb5c9c--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/tests/test_full_e2e.py@@ -0,0 +1,177 @@+"""+End-to-end tests for the Unreal Insights harness.+"""++from __future__ import annotations++import json+import os+import subprocess+import sys+import tempfile+from pathlib import Path++import pytest++HARNESS_ROOT = str(Path(__file__).resolve().parents[3])+TEST_TRACE = os.environ.get("UNREALINSIGHTS_TEST_TRACE", "")+TEST_TARGET_EXE = os.environ.get("UNREALINSIGHTS_TEST_TARGET_EXE", "")++HAS_TRACE = os.path.isfile(TEST_TRACE) if TEST_TRACE else False+HAS_TARGET = os.path.isfile(TEST_TARGET_EXE) if TEST_TARGET_EXE else False+HAS_LOCAL_INSIGHTS = os.path.isfile(+ r"D:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealInsights.exe"+) or bool(os.environ.get("UNREALINSIGHTS_EXE"))++skip_no_trace = pytest.mark.skipif(not HAS_TRACE, reason="UNREALINSIGHTS_TEST_TRACE not set or missing")+skip_no_target = pytest.mark.skipif(not HAS_TARGET, reason="UNREALINSIGHTS_TEST_TARGET_EXE not set or missing")+skip_no_local_ue = pytest.mark.skipif(not HAS_LOCAL_INSIGHTS, reason="No local Unreal Insights install detected")+++def _resolve_cli(name: str):+ """Resolve installed CLI command; falls back to python -m for dev."""+ import shutil++ force = os.environ.get("CLI_ANYTHING_FORCE_INSTALLED", "").strip() == "1"+ path = shutil.which(name)+ if path:+ print(f"[_resolve_cli] Using installed command: {path}")+ return [path]+ if force:+ raise RuntimeError(f"{name} not found in PATH. Install with: pip install -e .")+ print("[_resolve_cli] Falling back to module invocation")+ return [sys.executable, "-m", "cli_anything.unrealinsights.unrealinsights_cli"]+++def _cli_env():+ env = os.environ.copy()+ pythonpath = env.get("PYTHONPATH", "")+ env["PYTHONPATH"] = HARNESS_ROOT if not pythonpath else f"{HARNESS_ROOT}{os.pathsep}{pythonpath}"+ return env+++class TestCLISmoke:+ CLI_BASE = _resolve_cli("cli-anything-unrealinsights")++ def _run(self, args, check=True, timeout=180):+ return subprocess.run(+ self.CLI_BASE + args,+ capture_output=True,+ text=True,+ check=check,+ timeout=timeout,+ env=_cli_env(),+ )++ @skip_no_local_ue+ def test_backend_info(self):+ result = self._run(["--json", "backend", "info"])+ assert result.returncode == 0+ data = json.loads(result.stdout)+ assert data["insights"]["available"] is True+ assert data["insights"]["path"].lower().endswith("unrealinsights.exe")+++@skip_no_trace+class TestExportE2E:+ CLI_BASE = _resolve_cli("cli-anything-unrealinsights")++ def _run(self, args, check=True, timeout=180):+ return subprocess.run(+ self.CLI_BASE + args,+ capture_output=True,+ text=True,+ check=check,+ timeout=timeout,+ env=_cli_env(),+ )++ @pytest.mark.parametrize(+ ("subcommand", "extra_args"),+ [+ ("threads", []),+ ("timers", []),+ ("timing-events", ["--threads", "GameThread", "--timers", "*"]),+ ("timer-stats", ["--threads", "GameThread", "--timers", "*"]),+ ("timer-callees", ["--threads", "GameThread", "--timers", "*"]),+ ("counters", []),+ ("counter-values", ["--counter", "*"]),+ ],+ )+ def test_exporter_creates_output(self, subcommand, extra_args):+ with tempfile.TemporaryDirectory() as tmpdir:+ output = os.path.join(tmpdir, f"{subcommand}.csv")+ result = self._run(+ ["--json", "-t", TEST_TRACE, "export", subcommand, output, *extra_args],+ check=False,+ )+ if result.returncode != 0:+ pytest.skip(f"{subcommand} exporter failed for supplied trace")+ data = json.loads(result.stdout)+ assert data["output_files"]+ for path in data["output_files"]:+ assert os.path.isfile(path)+ assert os.path.getsize(path) > 0++ def test_batch_run_rsp(self):+ with tempfile.TemporaryDirectory() as tmpdir:+ threads = os.path.join(tmpdir, "threads.csv")+ timers = os.path.join(tmpdir, "timers.csv")+ rsp = os.path.join(tmpdir, "exports.rsp")+ Path(rsp).write_text(+ "\n".join(+ [+ f'TimingInsights.ExportThreads "{threads}"',+ f'TimingInsights.ExportTimers "{timers}"',+ ]+ ),+ encoding="utf-8",+ )+ result = self._run(["--json", "-t", TEST_TRACE, "batch", "run-rsp", rsp], check=False)+ if result.returncode != 0:+ pytest.skip("response-file execution failed for supplied trace")+ data = json.loads(result.stdout)+ assert len(data["output_files"]) >= 2+ for path in data["output_files"]:+ assert os.path.isfile(path)+ assert os.path.getsize(path) > 0+++@skip_no_target+class TestCaptureE2E:+ CLI_BASE = _resolve_cli("cli-anything-unrealinsights")++ def _run(self, args, check=True, timeout=300):+ return subprocess.run(+ self.CLI_BASE + args,+ capture_output=True,+ text=True,+ check=check,+ timeout=timeout,+ env=_cli_env(),+ )++ def test_capture_run_wait(self):+ with tempfile.TemporaryDirectory() as tmpdir:+ output_trace = os.path.join(tmpdir, "capture.utrace")+ result = self._run(+ [+ "--json",+ "capture",+ "run",+ TEST_TARGET_EXE,+ "--output-trace",+ output_trace,+ "--wait",+ "--timeout",+ "180",+ ],+ check=False,+ timeout=360,+ )+ if result.returncode != 0:+ pytest.skip("capture run failed for supplied target executable")+ data = json.loads(result.stdout)+ assert data["trace_path"].lower().endswith(".utrace")+ assert data["trace_exists"] is True+ assert data["trace_size"] > 0diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/unrealinsights_cli.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/unrealinsights_cli.pynew file mode 100644index 000000000..38494e7de--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/unrealinsights_cli.py@@ -0,0 +1,582 @@+#!/usr/bin/env python3+"""+Unreal Insights CLI - trace capture and export harness.+"""++from __future__ import annotations++import os+import shlex+from pathlib import Path++import click++from cli_anything.unrealinsights import __version__+from cli_anything.unrealinsights.core.capture import (+ DEFAULT_CHANNELS,+ normalize_trace_output_path,+ resolve_capture_target,+ run_capture,+)+from cli_anything.unrealinsights.core.export import execute_export, execute_response_file+from cli_anything.unrealinsights.core.session import UnrealInsightsSession+from cli_anything.unrealinsights.utils.errors import handle_error+from cli_anything.unrealinsights.utils.output import format_size, output_json+from cli_anything.unrealinsights.utils.unrealinsights_backend import (+ ensure_engine_unrealinsights,+ resolve_trace_server_exe,+ resolve_unrealinsights_exe,+)++_repl_mode = False+++def _get_session(ctx: click.Context) -> UnrealInsightsSession:+ ctx.ensure_object(dict)+ session = ctx.obj.get("session")+ if session is None:+ session = UnrealInsightsSession()+ ctx.obj["session"] = session+ return session+++def _output(ctx: click.Context, data, human_fn=None):+ if ctx.obj.get("json_mode"):+ output_json(data)+ elif human_fn:+ human_fn(data)+ else:+ output_json(data)+++def _handle_exc(ctx: click.Context, exc: Exception):+ err = handle_error(exc, debug=ctx.obj.get("debug", False))+ if ctx.obj.get("json_mode"):+ output_json(err)+ ctx.exit(1)+ raise click.ClickException(err["error"])+++def _resolve_insights(ctx: click.Context) -> dict[str, object]:+ session = _get_session(ctx)+ info = resolve_unrealinsights_exe(session.insights_exe, required=True)+ session.set_insights_exe(info["path"])+ return info+++def _resolve_trace_server(ctx: click.Context) -> dict[str, object]:+ session = _get_session(ctx)+ info = resolve_trace_server_exe(session.trace_server_exe, required=False)+ if info["available"]:+ session.set_trace_server_exe(info["path"])+ return info+++def _require_trace(ctx: click.Context) -> str:+ session = _get_session(ctx)+ if not session.trace_path:+ raise click.ClickException("No trace selected. Use --trace <path> or `trace set <path>` first.")+ trace_path = Path(session.trace_path).expanduser().resolve()+ if not trace_path.is_file():+ raise click.ClickException(f"Trace file not found: {trace_path}")+ return str(trace_path)+++def _human_backend(data: dict[str, object]):+ insights = data["insights"]+ trace_server = data["trace_server"]+ click.echo("Resolved Backends:")+ click.echo(f" UnrealInsights.exe : {insights['path']} ({insights['source']})")+ click.echo(f" Version : {insights.get('version') or 'unknown'}")+ if trace_server["available"]:+ click.echo(f" UnrealTraceServer : {trace_server['path']} ({trace_server['source']})")+ click.echo(f" Version : {trace_server.get('version') or 'unknown'}")+ else:+ click.echo(f" UnrealTraceServer : unavailable ({trace_server.get('error', 'not found')})")+++def _human_ensure_insights(data: dict[str, object]):+ insights = data["insights"]+ click.echo(f"Engine root: {data['engine_root']}")+ click.echo(f"UnrealInsights.exe {insights['path']} ({insights['source']})")+ click.echo(f"Version: {insights.get('version') or 'unknown'}")+ trace_server = data.get("trace_server")+ if trace_server and trace_server.get("available"):+ click.echo(f"TraceServer: {trace_server['path']}")+ build = data.get("build")+ if build:+ click.echo(f"Built: {'yes' if build['succeeded'] else 'no'}")+ click.echo(f"Build log: {build['log_path']}")+++def _human_trace_info(data: dict[str, object]):+ trace_path = data.get("trace_path")+ if not trace_path:+ click.echo("No active trace selected.")+ return+ click.echo(f"Trace: {trace_path}")+ click.echo(f"Exists: {'yes' if data.get('exists') else 'no'}")+ if data.get("exists"):+ click.echo(f"Size: {format_size(data.get('file_size'))}")+++def _human_export_result(data: dict[str, object]):+ click.echo(f"Trace: {data['trace_path']}")+ click.echo(f"Command: {data['exec_command']}")+ click.echo(f"Log: {data['log_path']}")+ click.echo(f"Exit code: {data['exit_code']}")+ click.echo(f"Success: {'yes' if data['succeeded'] else 'no'}")+ if data["output_files"]:+ click.echo("Outputs:")+ for output_path in data["output_files"]:+ click.echo(f" {output_path}")+ if data["errors"]:+ click.echo("Errors:")+ for line in data["errors"]:+ click.echo(f" {line}")+++def _human_capture_result(data: dict[str, object]):+ click.echo(f"Target exe: {data['target_exe']}")+ if data.get("project_path"):+ click.echo(f"Project: {data['project_path']}")+ if data.get("engine_root"):+ click.echo(f"Engine root: {data['engine_root']}")+ click.echo(f"Trace output: {data['trace_path']}")+ click.echo(f"Channels: {data['channels']}")+ click.echo(f"Command: {' '.join(map(str, data['command']))}")+ if data["waited"]:+ click.echo(f"Exit code: {data['exit_code']}")+ click.echo(f"Trace exists: {'yes' if data['trace_exists'] else 'no'}")+ if data["trace_exists"]:+ click.echo(f"Trace size: {format_size(data['trace_size'])}")+ else:+ click.echo(f"PID: {data['pid']}")++[email protected](invoke_without_command=True)[email protected]("--json", "json_mode", is_flag=True, help="Output in JSON format.")[email protected]("--debug", is_flag=True, help="Show debug tracebacks on errors.")+ "--trace",+ "-t",+ type=click.Path(exists=False),+ envvar="UNREALINSIGHTS_TRACE",+ help="Path to the active .utrace file.",+)+ "--insights-exe",+ type=click.Path(exists=False),+ envvar="UNREALINSIGHTS_EXE",+ help="Explicit path to UnrealInsights.exe.",+)+ "--trace-server-exe",+ type=click.Path(exists=False),+ envvar="UNREAL_TRACE_SERVER_EXE",+ help="Explicit path to UnrealTraceServer.exe.",+)[email protected]_option(version=__version__)[email protected]_context+def cli(ctx, json_mode, debug, trace, insights_exe, trace_server_exe):+ """Windows-first Unreal Insights harness with REPL and exporter wrappers."""+ ctx.ensure_object(dict)+ session = _get_session(ctx)+ ctx.obj["json_mode"] = json_mode+ ctx.obj["debug"] = debug++ if trace is not None:+ session.set_trace(trace)+ if insights_exe is not None:+ session.set_insights_exe(insights_exe)+ if trace_server_exe is not None:+ session.set_trace_server_exe(trace_server_exe)++ if ctx.invoked_subcommand is None:+ ctx.invoke(repl)++[email protected]("backend")+def backend_group():+ """Backend executable discovery and inspection."""+++@backend_group.command("info")[email protected]_context+def backend_info(ctx):+ """Resolve Unreal Insights backend executables."""+ try:+ data = {+ "insights": _resolve_insights(ctx),+ "trace_server": _resolve_trace_server(ctx),+ }+ _output(ctx, data, _human_backend)+ except Exception as exc:+ _handle_exc(ctx, exc)+++@backend_group.command("ensure-insights")[email protected]("--engine-root", required=True, type=click.Path(exists=False), help="UE install root or its Engine subdir.")+ "--build-if-missing/--no-build-if-missing",+ default=True,+ show_default=True,+ help="Build UnrealInsights when it is missing under the given engine root.",+)[email protected]("--configuration", default="Development", show_default=True, help="Build configuration.")[email protected]("--timeout", type=float, default=None, help="Optional build timeout in seconds.")[email protected]_context+def backend_ensure_insights(ctx, engine_root, build_if_missing, configuration, timeout):+ """Find or build UnrealInsights.exe for a specific engine root."""+ try:+ data = ensure_engine_unrealinsights(+ engine_root,+ build_if_missing=build_if_missing,+ configuration=configuration,+ timeout=timeout,+ )+ session = _get_session(ctx)+ session.set_insights_exe(data["insights"]["path"])+ trace_server = data.get("trace_server")+ if trace_server and trace_server.get("available"):+ session.set_trace_server_exe(trace_server["path"])+ _output(ctx, data, _human_ensure_insights)+ except Exception as exc:+ _handle_exc(ctx, exc)++[email protected]("trace")+def trace_group():+ """Session trace path management."""+++@trace_group.command("set")[email protected]("trace_path", type=click.Path(exists=False))[email protected]_context+def trace_set(ctx, trace_path):+ """Set the active trace path for this session or REPL."""+ session = _get_session(ctx)+ session.set_trace(trace_path)+ _output(ctx, session.trace_info(), _human_trace_info)+++@trace_group.command("info")[email protected]_context+def trace_info(ctx):+ """Show the active trace path."""+ session = _get_session(ctx)+ _output(ctx, session.trace_info(), _human_trace_info)++[email protected]("capture")+def capture_group():+ """Trace capture orchestration."""+++@capture_group.command("run")[email protected]("target_exe", required=False, type=click.Path(exists=False))[email protected]("--project", type=click.Path(exists=False), default=None, help="Path to a .uproject file.")+ "--engine-root",+ type=click.Path(exists=False),+ default=None,+ help="UE install root such as D:\\Program Files\\Epic Games\\UE_5.5 or its Engine subdir.",+)[email protected]("--target-arg", "target_args", multiple=True, help="Argument to pass to the target executable.")[email protected]("--output-trace", type=click.Path(exists=False), default=None, help="Output .utrace path.")[email protected]("--channels", default=DEFAULT_CHANNELS, show_default=True, help="Comma-separated UE trace channels.")[email protected]("--exec-cmd", "exec_cmds", multiple=True, help="Startup UE console command for -ExecCmds.")[email protected]("--wait", is_flag=True, help="Wait for the target to exit.")[email protected]("--timeout", type=float, default=None, help="Optional timeout in seconds when waiting.")[email protected]_context+def capture_run(ctx, target_exe, project, engine_root, target_args, output_trace, channels, exec_cmds, wait, timeout):+ """Launch a target executable with UE trace flags in file mode."""+ try:+ session = _get_session(ctx)+ resolved_target_exe, resolved_target_args, launch_info = resolve_capture_target(+ target_exe,+ project=project,+ engine_root=engine_root,+ target_args=target_args,+ )+ resolved_output = normalize_trace_output_path(+ resolved_target_exe,+ output_trace=output_trace,+ current_trace=session.trace_path,+ )+ data = run_capture(+ resolved_target_exe,+ output_trace=resolved_output,+ channels=channels,+ exec_cmds=exec_cmds,+ target_args=resolved_target_args,+ wait=wait,+ timeout=timeout,+ )+ data.update(launch_info)+ session.set_trace(resolved_output)+ _output(ctx, data, _human_capture_result)+ except Exception as exc:+ _handle_exc(ctx, exc)++[email protected]("export")+def export_group():+ """Offline Unreal Insights exporters."""+++def _run_export(+ ctx: click.Context,+ exporter: str,+ output_path: str,+ *,+ columns: str | None = None,+ threads: str | None = None,+ timers: str | None = None,+ start_time: float | None = None,+ end_time: float | None = None,+ region: str | None = None,+ counter: str | None = None,+):+ trace_path = _require_trace(ctx)+ insights = _resolve_insights(ctx)+ data = execute_export(+ insights["path"],+ trace_path,+ exporter,+ output_path,+ insights_version=insights.get("version"),+ columns=columns,+ threads=threads,+ timers=timers,+ start_time=start_time,+ end_time=end_time,+ region=region,+ counter=counter,+ )+ _output(ctx, data, _human_export_result)+++@export_group.command("threads")[email protected]("output_path", type=click.Path(exists=False))[email protected]_context+def export_threads(ctx, output_path):+ """Export thread metadata."""+ try:+ _run_export(ctx, "threads", output_path)+ except Exception as exc:+ _handle_exc(ctx, exc)+++@export_group.command("timers")[email protected]("output_path", type=click.Path(exists=False))[email protected]_context+def export_timers(ctx, output_path):+ """Export timer metadata."""+ try:+ _run_export(ctx, "timers", output_path)+ except Exception as exc:+ _handle_exc(ctx, exc)+++@export_group.command("timing-events")[email protected]("output_path", type=click.Path(exists=False))[email protected]("--columns", default=None)[email protected]("--threads", default=None)[email protected]("--timers", default=None)[email protected]("--start-time", type=float, default=None)[email protected]("--end-time", type=float, default=None)[email protected]("--region", default=None)[email protected]_context+def export_timing_events(ctx, output_path, columns, threads, timers, start_time, end_time, region):+ """Export timing events."""+ try:+ _run_export(+ ctx,+ "timing-events",+ output_path,+ columns=columns,+ threads=threads,+ timers=timers,+ start_time=start_time,+ end_time=end_time,+ region=region,+ )+ except Exception as exc:+ _handle_exc(ctx, exc)+++@export_group.command("timer-stats")[email protected]("output_path", type=click.Path(exists=False))[email protected]("--columns", default=None)[email protected]("--threads", default=None)[email protected]("--timers", default=None)[email protected]("--start-time", type=float, default=None)[email protected]("--end-time", type=float, default=None)[email protected]("--region", default=None)[email protected]_context+def export_timer_stats(ctx, output_path, columns, threads, timers, start_time, end_time, region):+ """Export aggregated timer statistics."""+ try:+ _run_export(+ ctx,+ "timer-stats",+ output_path,+ columns=columns,+ threads=threads,+ timers=timers,+ start_time=start_time,+ end_time=end_time,+ region=region,+ )+ except Exception as exc:+ _handle_exc(ctx, exc)+++@export_group.command("timer-callees")[email protected]("output_path", type=click.Path(exists=False))[email protected]("--threads", default=None)[email protected]("--timers", default=None)[email protected]("--start-time", type=float, default=None)[email protected]("--end-time", type=float, default=None)[email protected]("--region", default=None)[email protected]_context+def export_timer_callees(ctx, output_path, threads, timers, start_time, end_time, region):+ """Export timer callee trees."""+ try:+ _run_export(+ ctx,+ "timer-callees",+ output_path,+ threads=threads,+ timers=timers,+ start_time=start_time,+ end_time=end_time,+ region=region,+ )+ except Exception as exc:+ _handle_exc(ctx, exc)+++@export_group.command("counters")[email protected]("output_path", type=click.Path(exists=False))[email protected]_context+def export_counters(ctx, output_path):+ """Export the counter list."""+ try:+ _run_export(ctx, "counters", output_path)+ except Exception as exc:+ _handle_exc(ctx, exc)+++@export_group.command("counter-values")[email protected]("output_path", type=click.Path(exists=False))[email protected]("--counter", default=None)[email protected]("--columns", default=None)[email protected]("--start-time", type=float, default=None)[email protected]("--end-time", type=float, default=None)[email protected]("--region", default=None)[email protected]_context+def export_counter_values(ctx, output_path, counter, columns, start_time, end_time, region):+ """Export counter values."""+ try:+ _run_export(+ ctx,+ "counter-values",+ output_path,+ counter=counter,+ columns=columns,+ start_time=start_time,+ end_time=end_time,+ region=region,+ )+ except Exception as exc:+ _handle_exc(ctx, exc)++[email protected]("batch")+def batch_group():+ """Batch export workflows."""+++@batch_group.command("run-rsp")[email protected]("rsp_path", type=click.Path(exists=False))[email protected]_context+def batch_run_rsp(ctx, rsp_path):+ """Execute a response file using UnrealInsights.exe."""+ try:+ trace_path = _require_trace(ctx)+ insights = _resolve_insights(ctx)+ data = execute_response_file(insights["path"], trace_path, rsp_path)+ _output(ctx, data, _human_export_result)+ except Exception as exc:+ _handle_exc(ctx, exc)++[email protected]_context+def repl(ctx):+ """Start the interactive REPL."""+ from cli_anything.unrealinsights.utils.repl_skin import ReplSkin++ global _repl_mode+ _repl_mode = True++ session = _get_session(ctx)+ skin = ReplSkin("unrealinsights", version=__version__)+ skin.print_banner()+ pt_session = skin.create_prompt_session()++ repl_commands = {+ "backend": "info",+ "trace": "set|info",+ "capture": "run",+ "export": "threads|timers|timing-events|timer-stats|timer-callees|counters|counter-values",+ "batch": "run-rsp",+ "help": "Show this help",+ "quit": "Exit REPL",+ }++ try:+ while True:+ try:+ trace_name = Path(session.trace_path).name if session.trace_path else ""+ line = skin.get_input(pt_session, project_name=trace_name, modified=False)+ if not line:+ continue+ if line.lower() in ("quit", "exit", "q"):+ skin.print_goodbye()+ break+ if line.lower() == "help":+ skin.help(repl_commands)+ continue++ args = shlex.split(line, posix=os.name != "nt")+ if ctx.obj.get("json_mode"):+ args = ["--json", *args]+ if ctx.obj.get("debug"):+ args = ["--debug", *args]+ try:+ cli.main(args, standalone_mode=False, obj=ctx.obj)+ except SystemExit:+ pass+ except click.exceptions.UsageError as exc:+ skin.warning(f"Usage error: {exc}")+ except Exception as exc:+ if ctx.obj.get("json_mode"):+ output_json({"error": str(exc)})+ else:+ skin.error(str(exc))+ except (EOFError, KeyboardInterrupt):+ skin.print_goodbye()+ break+ finally:+ _repl_mode = False+++def main():+ cli(obj={})+++if __name__ == "__main__":+ main()diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/__init__.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/__init__.pynew file mode 100644index 000000000..6cf718da9--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/__init__.py@@ -0,0 +1 @@+"""Utility helpers for the Unreal Insights harness."""diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/errors.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/errors.pynew file mode 100644index 000000000..25ba4a8d3--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/errors.py@@ -0,0 +1,26 @@+"""+Error handling utilities.+"""++from __future__ import annotations++import sys+import traceback+from typing import Any+++def handle_error(exc: Exception, debug: bool = False) -> dict[str, Any]:+ """Convert an exception into a structured error payload."""+ result = {+ "error": str(exc),+ "type": type(exc).__name__,+ }+ if debug:+ result["traceback"] = traceback.format_exc()+ return result+++def die(message: str, code: int = 1):+ """Print an error message and exit."""+ sys.stderr.write(f"Error: {message}\n")+ sys.exit(code)diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/output.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/output.pynew file mode 100644index 000000000..1aaaa8bc5--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/output.py@@ -0,0 +1,54 @@+"""+Output formatting helpers.+"""++from __future__ import annotations++import json+import sys+from typing import Any+++def output_json(data: Any, indent: int = 2, file=None):+ """Write JSON data to stdout or a file-like object."""+ if file is None:+ file = sys.stdout+ json.dump(data, file, indent=indent, default=str)+ file.write("\n")+++def output_table(rows: list[list[Any]], headers: list[str], file=None):+ """Print a simple ASCII table."""+ if file is None:+ file = sys.stdout++ if not rows:+ file.write("(no data)\n")+ return++ col_widths = [len(header) for header in headers]+ for row in rows:+ for idx, value in enumerate(row[: len(headers)]):+ col_widths[idx] = max(col_widths[idx], len(str(value)))++ header_line = " ".join(str(headers[idx]).ljust(col_widths[idx]) for idx in range(len(headers)))+ file.write(header_line + "\n")+ file.write(" ".join("-" * width for width in col_widths) + "\n")++ for row in rows:+ truncated = row[: len(headers)]+ line = " ".join(str(value).ljust(col_widths[idx]) for idx, value in enumerate(truncated))+ file.write(line + "\n")+++def format_size(size_bytes: int | None) -> str:+ """Format a byte count as a human-readable string."""+ if size_bytes is None:+ return "unknown"+ if size_bytes < 1024:+ return f"{size_bytes} B"+ if size_bytes < 1024 * 1024:+ return f"{size_bytes / 1024:.1f} KB"+ if size_bytes < 1024 * 1024 * 1024:+ return f"{size_bytes / (1024 * 1024):.1f} MB"+ return f"{size_bytes / (1024 * 1024 * 1024):.1f} GB"diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/repl_skin.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/repl_skin.pynew file mode 100644index 000000000..c7312348a--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/repl_skin.py@@ -0,0 +1,521 @@+"""cli-anything REPL Skin — Unified terminal interface for all CLI harnesses.++Copy this file into your CLI package at:+ cli_anything/<software>/utils/repl_skin.py++Usage:+ from cli_anything.<software>.utils.repl_skin import ReplSkin++ skin = ReplSkin("shotcut", version="1.0.0")+ skin.print_banner() # auto-detects skills/SKILL.md inside the package+ prompt_text = skin.prompt(project_name="my_video.mlt", modified=True)+ skin.success("Project saved")+ skin.error("File not found")+ skin.warning("Unsaved changes")+ skin.info("Processing 24 clips...")+ skin.status("Track 1", "3 clips, 00:02:30")+ skin.table(headers, rows)+ skin.print_goodbye()+"""++import os+import sys++# ── ANSI color codes (no external deps for core styling) ──────────────++_RESET = "\033[0m"+_BOLD = "\033[1m"+_DIM = "\033[2m"+_ITALIC = "\033[3m"+_UNDERLINE = "\033[4m"++# Brand colors+_CYAN = "\033[38;5;80m" # cli-anything brand cyan+_CYAN_BG = "\033[48;5;80m"+_WHITE = "\033[97m"+_GRAY = "\033[38;5;245m"+_DARK_GRAY = "\033[38;5;240m"+_LIGHT_GRAY = "\033[38;5;250m"++# Software accent colors — each software gets a unique accent+_ACCENT_COLORS = {+ "gimp": "\033[38;5;214m", # warm orange+ "blender": "\033[38;5;208m", # deep orange+ "inkscape": "\033[38;5;39m", # bright blue+ "audacity": "\033[38;5;33m", # navy blue+ "libreoffice": "\033[38;5;40m", # green+ "obs_studio": "\033[38;5;55m", # purple+ "kdenlive": "\033[38;5;69m", # slate blue+ "shotcut": "\033[38;5;35m", # teal green+}+_DEFAULT_ACCENT = "\033[38;5;75m" # default sky blue++# Status colors+_GREEN = "\033[38;5;78m"+_YELLOW = "\033[38;5;220m"+_RED = "\033[38;5;196m"+_BLUE = "\033[38;5;75m"+_MAGENTA = "\033[38;5;176m"++# ── Brand icon ────────────────────────────────────────────────────────++# The cli-anything icon: a small colored diamond/chevron mark+_ICON = f"{_CYAN}{_BOLD}◆{_RESET}"+_ICON_SMALL = f"{_CYAN}▸{_RESET}"++# ── Box drawing characters ────────────────────────────────────────────++_H_LINE = "─"+_V_LINE = "│"+_TL = "╭"+_TR = "╮"+_BL = "╰"+_BR = "╯"+_T_DOWN = "┬"+_T_UP = "┴"+_T_RIGHT = "├"+_T_LEFT = "┤"+_CROSS = "┼"+++def _strip_ansi(text: str) -> str:+ """Remove ANSI escape codes for length calculation."""+ import re+ return re.sub(r"\033\[[^m]*m", "", text)+++def _visible_len(text: str) -> int:+ """Get visible length of text (excluding ANSI codes)."""+ return len(_strip_ansi(text))+++class ReplSkin:+ """Unified REPL skin for cli-anything CLIs.++ Provides consistent branding, prompts, and message formatting+ across all CLI harnesses built with the cli-anything methodology.+ """++ def __init__(self, software: str, version: str = "1.0.0",+ history_file: str | None = None, skill_path: str | None = None):+ """Initialize the REPL skin.++ Args:+ software: Software name (e.g., "gimp", "shotcut", "blender").+ version: CLI version string.+ history_file: Path for persistent command history.+ Defaults to ~/.cli-anything-<software>/history+ skill_path: Path to the SKILL.md file for agent discovery.+ Auto-detected from the package's skills/ directory if not provided.+ Displayed in banner for AI agents to know where to read skill info.+ """+ self.software = software.lower().replace("-", "_")+ self.display_name = software.replace("_", " ").title()+ self.version = version++ # Auto-detect skill path from package layout:+ # cli_anything/<software>/utils/repl_skin.py (this file)+ # cli_anything/<software>/skills/SKILL.md (target)+ if skill_path is None:+ from pathlib import Path+ _auto = Path(__file__).resolve().parent.parent / "skills" / "SKILL.md"+ if _auto.is_file():+ skill_path = str(_auto)+ self.skill_path = skill_path+ self.accent = _ACCENT_COLORS.get(self.software, _DEFAULT_ACCENT)++ # History file+ if history_file is None:+ from pathlib import Path+ hist_dir = Path.home() / f".cli-anything-{self.software}"+ hist_dir.mkdir(parents=True, exist_ok=True)+ self.history_file = str(hist_dir / "history")+ else:+ self.history_file = history_file++ # Detect terminal capabilities+ self._color = self._detect_color_support()++ def _detect_color_support(self) -> bool:+ """Check if terminal supports color."""+ if os.environ.get("NO_COLOR"):+ return False+ if os.environ.get("CLI_ANYTHING_NO_COLOR"):+ return False+ if not hasattr(sys.stdout, "isatty"):+ return False+ return sys.stdout.isatty()++ def _c(self, code: str, text: str) -> str:+ """Apply color code if colors are supported."""+ if not self._color:+ return text+ return f"{code}{text}{_RESET}"++ # ── Banner ────────────────────────────────────────────────────────++ def print_banner(self):+ """Print the startup banner with branding."""+ inner = 54++ def _box_line(content: str) -> str:+ """Wrap content in box drawing, padding to inner width."""+ pad = inner - _visible_len(content)+ vl = self._c(_DARK_GRAY, _V_LINE)+ return f"{vl}{content}{' ' * max(0, pad)}{vl}"++ top = self._c(_DARK_GRAY, f"{_TL}{_H_LINE * inner}{_TR}")+ bot = self._c(_DARK_GRAY, f"{_BL}{_H_LINE * inner}{_BR}")++ # Title: ◆ cli-anything · Shotcut+ icon = self._c(_CYAN + _BOLD, "◆")+ brand = self._c(_CYAN + _BOLD, "cli-anything")+ dot = self._c(_DARK_GRAY, "·")+ name = self._c(self.accent + _BOLD, self.display_name)+ title = f" {icon} {brand} {dot} {name}"++ ver = f" {self._c(_DARK_GRAY, f' v{self.version}')}"+ tip = f" {self._c(_DARK_GRAY, ' Type help for commands, quit to exit')}"+ empty = ""++ # Skill path for agent discovery+ skill_line = None+ if self.skill_path:+ skill_icon = self._c(_MAGENTA, "◇")+ skill_label = self._c(_DARK_GRAY, " Skill:")+ skill_path_display = self._c(_LIGHT_GRAY, self.skill_path)+ skill_line = f" {skill_icon} {skill_label} {skill_path_display}"++ print(top)+ print(_box_line(title))+ print(_box_line(ver))+ if skill_line:+ print(_box_line(skill_line))+ print(_box_line(empty))+ print(_box_line(tip))+ print(bot)+ print()++ # ── Prompt ────────────────────────────────────────────────────────++ def prompt(self, project_name: str = "", modified: bool = False,+ context: str = "") -> str:+ """Build a styled prompt string for prompt_toolkit or input().++ Args:+ project_name: Current project name (empty if none open).+ modified: Whether the project has unsaved changes.+ context: Optional extra context to show in prompt.++ Returns:+ Formatted prompt string.+ """+ parts = []++ # Icon+ if self._color:+ parts.append(f"{_CYAN}◆{_RESET} ")+ else:+ parts.append("> ")++ # Software name+ parts.append(self._c(self.accent + _BOLD, self.software))++ # Project context+ if project_name or context:+ ctx = context or project_name+ mod = "*" if modified else ""+ parts.append(f" {self._c(_DARK_GRAY, '[')}")+ parts.append(self._c(_LIGHT_GRAY, f"{ctx}{mod}"))+ parts.append(self._c(_DARK_GRAY, ']'))++ parts.append(self._c(_GRAY, " ❯ "))++ return "".join(parts)++ def prompt_tokens(self, project_name: str = "", modified: bool = False,+ context: str = ""):+ """Build prompt_toolkit formatted text tokens for the prompt.++ Use with prompt_toolkit's FormattedText for proper ANSI handling.++ Returns:+ list of (style, text) tuples for prompt_toolkit.+ """+ accent_hex = _ANSI_256_TO_HEX.get(self.accent, "#5fafff")+ tokens = []++ tokens.append(("class:icon", "◆ "))+ tokens.append(("class:software", self.software))++ if project_name or context:+ ctx = context or project_name+ mod = "*" if modified else ""+ tokens.append(("class:bracket", " ["))+ tokens.append(("class:context", f"{ctx}{mod}"))+ tokens.append(("class:bracket", "]"))++ tokens.append(("class:arrow", " ❯ "))++ return tokens++ def get_prompt_style(self):+ """Get a prompt_toolkit Style object matching the skin.++ Returns:+ prompt_toolkit.styles.Style+ """+ try:+ from prompt_toolkit.styles import Style+ except ImportError:+ return None++ accent_hex = _ANSI_256_TO_HEX.get(self.accent, "#5fafff")++ return Style.from_dict({+ "icon": "#5fdfdf bold", # cyan brand color+ "software": f"{accent_hex} bold",+ "bracket": "#585858",+ "context": "#bcbcbc",+ "arrow": "#808080",+ # Completion menu+ "completion-menu.completion": "bg:#303030 #bcbcbc",+ "completion-menu.completion.current": f"bg:{accent_hex} #000000",+ "completion-menu.meta.completion": "bg:#303030 #808080",+ "completion-menu.meta.completion.current": f"bg:{accent_hex} #000000",+ # Auto-suggest+ "auto-suggest": "#585858",+ # Bottom toolbar+ "bottom-toolbar": "bg:#1c1c1c #808080",+ "bottom-toolbar.text": "#808080",+ })++ # ── Messages ──────────────────────────────────────────────────────++ def success(self, message: str):+ """Print a success message with green checkmark."""+ icon = self._c(_GREEN + _BOLD, "✓")+ print(f" {icon} {self._c(_GREEN, message)}")++ def error(self, message: str):+ """Print an error message with red cross."""+ icon = self._c(_RED + _BOLD, "✗")+ print(f" {icon} {self._c(_RED, message)}", file=sys.stderr)++ def warning(self, message: str):+ """Print a warning message with yellow triangle."""+ icon = self._c(_YELLOW + _BOLD, "⚠")+ print(f" {icon} {self._c(_YELLOW, message)}")++ def info(self, message: str):+ """Print an info message with blue dot."""+ icon = self._c(_BLUE, "●")+ print(f" {icon} {self._c(_LIGHT_GRAY, message)}")++ def hint(self, message: str):+ """Print a subtle hint message."""+ print(f" {self._c(_DARK_GRAY, message)}")++ def section(self, title: str):+ """Print a section header."""+ print()+ print(f" {self._c(self.accent + _BOLD, title)}")+ print(f" {self._c(_DARK_GRAY, _H_LINE * len(title))}")++ # ── Status display ────────────────────────────────────────────────++ def status(self, label: str, value: str):+ """Print a key-value status line."""+ lbl = self._c(_GRAY, f" {label}:")+ val = self._c(_WHITE, f" {value}")+ print(f"{lbl}{val}")++ def status_block(self, items: dict[str, str], title: str = ""):+ """Print a block of status key-value pairs.++ Args:+ items: Dict of label -> value pairs.+ title: Optional title for the block.+ """+ if title:+ self.section(title)++ max_key = max(len(k) for k in items) if items else 0+ for label, value in items.items():+ lbl = self._c(_GRAY, f" {label:<{max_key}}")+ val = self._c(_WHITE, f" {value}")+ print(f"{lbl}{val}")++ def progress(self, current: int, total: int, label: str = ""):+ """Print a simple progress indicator.++ Args:+ current: Current step number.+ total: Total number of steps.+ label: Optional label for the progress.+ """+ pct = int(current / total * 100) if total > 0 else 0+ bar_width = 20+ filled = int(bar_width * current / total) if total > 0 else 0+ bar = "█" * filled + "░" * (bar_width - filled)+ text = f" {self._c(_CYAN, bar)} {self._c(_GRAY, f'{pct:3d}%')}"+ if label:+ text += f" {self._c(_LIGHT_GRAY, label)}"+ print(text)++ # ── Table display ─────────────────────────────────────────────────++ def table(self, headers: list[str], rows: list[list[str]],+ max_col_width: int = 40):+ """Print a formatted table with box-drawing characters.++ Args:+ headers: Column header strings.+ rows: List of rows, each a list of cell strings.+ max_col_width: Maximum column width before truncation.+ """+ if not headers:+ return++ # Calculate column widths+ col_widths = [min(len(h), max_col_width) for h in headers]+ for row in rows:+ for i, cell in enumerate(row):+ if i < len(col_widths):+ col_widths[i] = min(+ max(col_widths[i], len(str(cell))), max_col_width+ )++ def pad(text: str, width: int) -> str:+ t = str(text)[:width]+ return t + " " * (width - len(t))++ # Header+ header_cells = [+ self._c(_CYAN + _BOLD, pad(h, col_widths[i]))+ for i, h in enumerate(headers)+ ]+ sep = self._c(_DARK_GRAY, f" {_V_LINE} ")+ header_line = f" {sep.join(header_cells)}"+ print(header_line)++ # Separator+ sep_parts = [self._c(_DARK_GRAY, _H_LINE * w) for w in col_widths]+ sep_line = self._c(_DARK_GRAY, f" {'───'.join([_H_LINE * w for w in col_widths])}")+ print(sep_line)++ # Rows+ for row in rows:+ cells = []+ for i, cell in enumerate(row):+ if i < len(col_widths):+ cells.append(self._c(_LIGHT_GRAY, pad(str(cell), col_widths[i])))+ row_sep = self._c(_DARK_GRAY, f" {_V_LINE} ")+ print(f" {row_sep.join(cells)}")++ # ── Help display ──────────────────────────────────────────────────++ def help(self, commands: dict[str, str]):+ """Print a formatted help listing.++ Args:+ commands: Dict of command -> description pairs.+ """+ self.section("Commands")+ max_cmd = max(len(c) for c in commands) if commands else 0+ for cmd, desc in commands.items():+ cmd_styled = self._c(self.accent, f" {cmd:<{max_cmd}}")+ desc_styled = self._c(_GRAY, f" {desc}")+ print(f"{cmd_styled}{desc_styled}")+ print()++ # ── Goodbye ───────────────────────────────────────────────────────++ def print_goodbye(self):+ """Print a styled goodbye message."""+ print(f"\n {_ICON_SMALL} {self._c(_GRAY, 'Goodbye!')}\n")++ # ── Prompt toolkit session factory ────────────────────────────────++ def create_prompt_session(self):+ """Create a prompt_toolkit PromptSession with skin styling.++ Returns:+ A configured PromptSession, or None if prompt_toolkit unavailable.+ """+ try:+ from prompt_toolkit import PromptSession+ from prompt_toolkit.history import FileHistory+ from prompt_toolkit.auto_suggest import AutoSuggestFromHistory+ from prompt_toolkit.formatted_text import FormattedText++ style = self.get_prompt_style()++ session = PromptSession(+ history=FileHistory(self.history_file),+ auto_suggest=AutoSuggestFromHistory(),+ style=style,+ enable_history_search=True,+ )+ return session+ except ImportError:+ return None++ def get_input(self, pt_session, project_name: str = "",+ modified: bool = False, context: str = "") -> str:+ """Get input from user using prompt_toolkit or fallback.++ Args:+ pt_session: A prompt_toolkit PromptSession (or None).+ project_name: Current project name.+ modified: Whether project has unsaved changes.+ context: Optional context string.++ Returns:+ User input string (stripped).+ """+ if pt_session is not None:+ from prompt_toolkit.formatted_text import FormattedText+ tokens = self.prompt_tokens(project_name, modified, context)+ return pt_session.prompt(FormattedText(tokens)).strip()+ else:+ raw_prompt = self.prompt(project_name, modified, context)+ return input(raw_prompt).strip()++ # ── Toolbar builder ───────────────────────────────────────────────++ def bottom_toolbar(self, items: dict[str, str]):+ """Create a bottom toolbar callback for prompt_toolkit.++ Args:+ items: Dict of label -> value pairs to show in toolbar.++ Returns:+ A callable that returns FormattedText for the toolbar.+ """+ def toolbar():+ from prompt_toolkit.formatted_text import FormattedText+ parts = []+ for i, (k, v) in enumerate(items.items()):+ if i > 0:+ parts.append(("class:bottom-toolbar.text", " │ "))+ parts.append(("class:bottom-toolbar.text", f" {k}: "))+ parts.append(("class:bottom-toolbar", v))+ return FormattedText(parts)+ return toolbar+++# ── ANSI 256-color to hex mapping (for prompt_toolkit styles) ─────────++_ANSI_256_TO_HEX = {+ "\033[38;5;33m": "#0087ff", # audacity navy blue+ "\033[38;5;35m": "#00af5f", # shotcut teal+ "\033[38;5;39m": "#00afff", # inkscape bright blue+ "\033[38;5;40m": "#00d700", # libreoffice green+ "\033[38;5;55m": "#5f00af", # obs purple+ "\033[38;5;69m": "#5f87ff", # kdenlive slate blue+ "\033[38;5;75m": "#5fafff", # default sky blue+ "\033[38;5;80m": "#5fd7d7", # brand cyan+ "\033[38;5;208m": "#ff8700", # blender deep orange+ "\033[38;5;214m": "#ffaf00", # gimp warm orange+}diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/unrealinsights_backend.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/unrealinsights_backend.pynew file mode 100644index 000000000..042f7b277--- /dev/null+++ b/unrealinsights/agent-harness/cli_anything/unrealinsights/utils/unrealinsights_backend.py@@ -0,0 +1,442 @@+"""+Backend helpers for resolving and invoking Unreal Insights binaries.+"""++from __future__ import annotations++import os+import re+import subprocess+from pathlib import Path+from datetime import datetime+from typing import Iterable++INSIGHTS_BINARY_NAME = "UnrealInsights.exe"+TRACE_SERVER_BINARY_NAME = "UnrealTraceServer.exe"+++def _normalize_path(path: str | Path) -> str:+ return str(Path(path).expanduser().resolve())+++def _extract_engine_version_hint(path: Path) -> str | None:+ for parent in path.parents:+ if parent.name.startswith("UE_"):+ return parent.name.removeprefix("UE_")+ return None+++def _engine_sort_key(path: Path) -> tuple[int, ...]:+ match = re.findall(r"\d+", path.name)+ if not match:+ return (0,)+ return tuple(int(part) for part in match)+++def _default_search_roots() -> list[Path]:+ roots: dict[str, Path] = {}++ for env_key in ("ProgramW6432", "ProgramFiles"):+ value = os.environ.get(env_key)+ if value:+ root = Path(value) / "Epic Games"+ roots[str(root).lower()] = root++ for drive in "CDEFGHIJKLMNOPQRSTUVWXYZ":+ root = Path(f"{drive}:/Program Files/Epic Games")+ roots[str(root).lower()] = root++ return [root for root in roots.values() if root.exists()]+++def _existing_engine_installations(search_roots: Iterable[Path] | None = None) -> list[Path]:+ installs: dict[str, Path] = {}+ roots = list(search_roots) if search_roots is not None else _default_search_roots()+ for root in roots:+ if not root.exists():+ continue+ for candidate in root.glob("UE_*"):+ if candidate.is_dir():+ installs[str(candidate.resolve()).lower()] = candidate.resolve()+ return sorted(installs.values(), key=_engine_sort_key, reverse=True)+++def _candidate_binary_paths(binary_name: str, search_roots: Iterable[Path] | None = None) -> list[Path]:+ candidates: list[Path] = []+ for install in _existing_engine_installations(search_roots):+ candidates.append(install / "Engine" / "Binaries" / "Win64" / binary_name)+ return candidates+++def _read_windows_product_version(path: Path) -> str | None:+ if os.name != "nt":+ return None++ literal = str(path).replace("'", "''")+ cmd = [+ "powershell",+ "-NoProfile",+ "-Command",+ f"(Get-Item -LiteralPath '{literal}').VersionInfo.ProductVersion",+ ]+ try:+ result = subprocess.run(+ cmd,+ capture_output=True,+ text=True,+ timeout=5,+ check=False,+ )+ except (FileNotFoundError, subprocess.TimeoutExpired):+ return None++ version = result.stdout.strip()+ return version or None+++def _build_resolution(path: Path, source: str) -> dict[str, object]:+ version = _read_windows_product_version(path)+ return {+ "available": True,+ "path": _normalize_path(path),+ "source": source,+ "version": version or _extract_engine_version_hint(path),+ "engine_version_hint": _extract_engine_version_hint(path),+ }+++def _missing_resolution(binary_name: str, reason: str) -> dict[str, object]:+ return {+ "available": False,+ "path": None,+ "source": "unresolved",+ "version": None,+ "engine_version_hint": None,+ "error": f"{binary_name} not found: {reason}",+ }+++def resolve_engine_root(engine_root: str | Path) -> Path:+ """Normalize a UE install root from either the install root or Engine subdir."""+ path = Path(engine_root).expanduser().resolve()+ root = path.parent if path.name.lower() == "engine" else path+ if not root.exists():+ raise RuntimeError(f"Engine root not found: {root}")+ if not (root / "Engine").is_dir():+ raise RuntimeError(f"Engine root must contain an Engine directory: {root}")+ return root+++def resolve_binary_from_engine_root(+ binary_name: str,+ engine_root: str | Path,+ required: bool = True,+) -> dict[str, object]:+ """Resolve a UE program binary from a specific engine root."""+ root = resolve_engine_root(engine_root)+ candidate = root / "Engine" / "Binaries" / "Win64" / binary_name+ if candidate.is_file():+ return _build_resolution(candidate, f"engine:{root.name}")+ if required:+ raise RuntimeError(f"{binary_name} not found under engine root: {root}")+ return _missing_resolution(binary_name, f"missing under engine root {root}")+++def resolve_windows_binary(+ binary_name: str,+ explicit_path: str | None = None,+ env_var_name: str | None = None,+ search_roots: Iterable[Path] | None = None,+ required: bool = True,+) -> dict[str, object]:+ """Resolve a UE program binary using explicit path, env var, then auto-discovery."""+ if explicit_path:+ explicit = Path(explicit_path).expanduser()+ if not explicit.is_file():+ raise RuntimeError(f"Explicit path does not exist: {explicit}")+ return _build_resolution(explicit.resolve(), "explicit")++ if env_var_name:+ env_value = os.environ.get(env_var_name, "").strip()+ if env_value:+ env_path = Path(env_value).expanduser()+ if not env_path.is_file():+ raise RuntimeError(f"{env_var_name} points to a missing file: {env_path}")+ return _build_resolution(env_path.resolve(), f"env:{env_var_name}")++ for candidate in _candidate_binary_paths(binary_name, search_roots):+ if candidate.is_file():+ return _build_resolution(candidate.resolve(), f"auto:{candidate.parents[3].name}")++ if required:+ raise RuntimeError(+ f"{binary_name} not found. Set an explicit path or install UE 5.5+ in an Epic Games directory."+ )+ return _missing_resolution(binary_name, "auto-discovery did not find a matching UE install")+++def resolve_unrealinsights_exe(+ explicit_path: str | None = None,+ engine_root: str | None = None,+ search_roots: Iterable[Path] | None = None,+ required: bool = True,+) -> dict[str, object]:+ if engine_root:+ return resolve_binary_from_engine_root(INSIGHTS_BINARY_NAME, engine_root, required=required)+ return resolve_windows_binary(+ INSIGHTS_BINARY_NAME,+ explicit_path=explicit_path,+ env_var_name="UNREALINSIGHTS_EXE",+ search_roots=search_roots,+ required=required,+ )+++def resolve_trace_server_exe(+ explicit_path: str | None = None,+ engine_root: str | None = None,+ search_roots: Iterable[Path] | None = None,+ required: bool = False,+) -> dict[str, object]:+ if engine_root:+ return resolve_binary_from_engine_root(TRACE_SERVER_BINARY_NAME, engine_root, required=required)+ return resolve_windows_binary(+ TRACE_SERVER_BINARY_NAME,+ explicit_path=explicit_path,+ env_var_name="UNREAL_TRACE_SERVER_EXE",+ search_roots=search_roots,+ required=required,+ )+++def ensure_parent_dir(path: str | Path):+ Path(path).expanduser().resolve().parent.mkdir(parents=True, exist_ok=True)+++def build_engine_program(+ engine_root: str | Path,+ target_name: str,+ *,+ platform: str = "Win64",+ configuration: str = "Development",+ timeout: float | None = None,+ log_path: str | None = None,+) -> dict[str, object]:+ """Build a UE program target using the engine's Build.bat."""+ root = resolve_engine_root(engine_root)+ build_bat = root / "Engine" / "Build" / "BatchFiles" / "Build.bat"+ if not build_bat.is_file():+ raise RuntimeError(f"Build.bat not found under engine root: {root}")++ if log_path is None:+ timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")+ log_path = str(root / "Engine" / "Programs" / target_name / "Saved" / "Logs" / f"build-{target_name}-{timestamp}.log")+ ensure_parent_dir(log_path)++ command = [str(build_bat), target_name, platform, configuration, "-WaitMutex"]+ try:+ result = subprocess.run(+ command,+ cwd=str(root),+ capture_output=True,+ text=True,+ timeout=timeout,+ check=False,+ )+ stdout = result.stdout+ stderr = result.stderr+ exit_code = result.returncode+ timed_out = False+ except subprocess.TimeoutExpired as exc:+ stdout = exc.stdout or ""+ stderr = exc.stderr or ""+ exit_code = None+ timed_out = True++ Path(log_path).write_text(+ "\n".join(+ [+ f"# Command: {' '.join(command)}",+ "",+ stdout or "",+ stderr or "",+ ]+ ),+ encoding="utf-8",+ errors="replace",+ )++ return {+ "command": command,+ "cwd": str(root),+ "log_path": str(Path(log_path).resolve()),+ "exit_code": exit_code,+ "timed_out": timed_out,+ "stdout": stdout,+ "stderr": stderr,+ "succeeded": (not timed_out and exit_code == 0),+ }+++def ensure_engine_unrealinsights(+ engine_root: str | Path,+ *,+ build_if_missing: bool = True,+ configuration: str = "Development",+ platform: str = "Win64",+ timeout: float | None = None,+) -> dict[str, object]:+ """Resolve UnrealInsights.exe for a given engine root, building it if requested."""+ root = resolve_engine_root(engine_root)+ trace_server = resolve_binary_from_engine_root(+ TRACE_SERVER_BINARY_NAME,+ root,+ required=False,+ )+ existing = resolve_binary_from_engine_root(+ INSIGHTS_BINARY_NAME,+ root,+ required=False,+ )+ result = {+ "engine_root": str(root),+ "trace_server": trace_server,+ "build_attempted": False,+ "build": None,+ }+ if existing["available"]:+ result["insights"] = existing+ return result++ if not build_if_missing:+ raise RuntimeError(f"{INSIGHTS_BINARY_NAME} not found under engine root: {root}")++ build = build_engine_program(+ root,+ "UnrealInsights",+ platform=platform,+ configuration=configuration,+ timeout=timeout,+ )+ result["build_attempted"] = True+ result["build"] = build+ if not build["succeeded"]:+ raise RuntimeError(f"Failed to build UnrealInsights for engine root: {root}")++ result["insights"] = resolve_binary_from_engine_root(INSIGHTS_BINARY_NAME, root, required=True)+ return result+++def build_insights_command(+ insights_exe: str,+ trace_path: str,+ exec_on_complete: str,+ log_path: str,+) -> list[str]:+ """Build the UnrealInsights.exe command line."""+ return [+ _normalize_path(insights_exe),+ f"-OpenTraceFile={_normalize_path(trace_path)}",+ f"-ABSLOG={_normalize_path(log_path)}",+ "-AutoQuit",+ "-NoUI",+ f"-ExecOnAnalysisCompleteCmd={exec_on_complete}",+ "-log",+ ]+++def _quote_cmd_value(value: str) -> str:+ escaped = value.replace('"', '\\"')+ return f'"{escaped}"'+++def build_insights_command_line(+ insights_exe: str,+ trace_path: str,+ exec_on_complete: str,+ log_path: str,+) -> str:+ """Build a raw Windows command line for UnrealInsights.exe.++ This avoids CreateProcess argv wrapping the whole -ExecOnAnalysisCompleteCmd+ argument in outer quotes, which older UnrealInsights builds fail to parse.+ """+ exe = _quote_cmd_value(_normalize_path(insights_exe))+ trace = _quote_cmd_value(_normalize_path(trace_path))+ log = _quote_cmd_value(_normalize_path(log_path))+ exec_value = _quote_cmd_value(exec_on_complete)+ return (+ f"{exe} "+ f"-OpenTraceFile={trace} "+ f"-ABSLOG={log} "+ f"-AutoQuit -NoUI "+ f"-ExecOnAnalysisCompleteCmd={exec_value} "+ f"-log"+ )+++def run_process(command: list[str] | str, timeout: float | None = None, wait: bool = True) -> dict[str, object]:+ """Run or launch a subprocess and return structured execution metadata."""+ if wait:+ try:+ result = subprocess.run(+ command,+ capture_output=True,+ text=True,+ timeout=timeout,+ check=False,+ )+ return {+ "command": command,+ "waited": True,+ "timed_out": False,+ "exit_code": result.returncode,+ "stdout": result.stdout,+ "stderr": result.stderr,+ "pid": None,+ }+ except subprocess.TimeoutExpired as exc:+ return {+ "command": command,+ "waited": True,+ "timed_out": True,+ "exit_code": None,+ "stdout": exc.stdout or "",+ "stderr": exc.stderr or "",+ "pid": None,+ }++ process = subprocess.Popen(command)+ return {+ "command": command,+ "waited": False,+ "timed_out": False,+ "exit_code": None,+ "stdout": None,+ "stderr": None,+ "pid": process.pid,+ }+++def parse_unreal_log(log_path: str | Path) -> dict[str, object]:+ """Extract warning and error lines from an Unreal log file."""+ path = Path(log_path).expanduser().resolve()+ if not path.is_file():+ return {+ "path": str(path),+ "exists": False,+ "warnings": [],+ "errors": [],+ "tail": [],+ }++ lines = path.read_text(encoding="utf-8", errors="replace").splitlines()+ warnings = [line for line in lines if "Warning:" in line]+ errors = [line for line in lines if "Error:" in line]+ return {+ "path": str(path),+ "exists": True,+ "warnings": warnings,+ "errors": errors,+ "tail": lines[-20:],+ }diff --git a/unrealinsights/agent-harness/setup.py b/unrealinsights/agent-harness/setup.pynew file mode 100644index 000000000..44e197020--- /dev/null+++ b/unrealinsights/agent-harness/setup.py@@ -0,0 +1,41 @@+"""Setup for cli-anything-unrealinsights package."""++from pathlib import Path++from setuptools import find_namespace_packages, setup++_README = Path(__file__).parent / "cli_anything" / "unrealinsights" / "README.md"+_long_desc = _README.read_text(encoding="utf-8") if _README.is_file() else ""++setup(+ name="cli-anything-unrealinsights",+ version="0.1.0",+ description="CLI harness for Unreal Insights trace capture and export workflows",+ long_description=_long_desc,+ long_description_content_type="text/markdown",+ author="cli-anything",+ packages=find_namespace_packages(include=["cli_anything.*"]),+ python_requires=">=3.10",+ install_requires=[+ "click>=8.0",+ "prompt-toolkit>=3.0",+ ],+ extras_require={+ "test": ["pytest>=7.0"],+ },+ entry_points={+ "console_scripts": [+ "cli-anything-unrealinsights=cli_anything.unrealinsights.unrealinsights_cli:main",+ ],+ },+ package_data={+ "cli_anything.unrealinsights": ["skills/*.md", "README.md"],+ },+ include_package_data=True,+ zip_safe=False,+ classifiers=[+ "Programming Language :: Python :: 3",+ "License :: OSI Approved :: MIT License",+ "Topic :: Software Development :: Debuggers",+ ],+)