Skip to content

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

Python

Add Unreal Insights harness

aimididfef24958d00
diff --git a/.gitignore b/.gitignore
index 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.json
index 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.md
new file mode 100644
index 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 flags
diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/README.md b/unrealinsights/agent-harness/cli_anything/unrealinsights/README.md
new file mode 100644
index 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__.py
new file mode 100644
index 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__.py
new file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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 result
diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/core/export.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/core/export.py
new file mode 100644
index 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.py
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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"] > 0
diff --git a/unrealinsights/agent-harness/cli_anything/unrealinsights/unrealinsights_cli.py b/unrealinsights/agent-harness/cli_anything/unrealinsights/unrealinsights_cli.py
new file mode 100644
index 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__)
+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)
+
+
+def backend_group():
+ """Backend executable discovery and inspection."""
+
+
+@backend_group.command("info")
+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.")
+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)
+
+
+def trace_group():
+ """Session trace path management."""
+
+
+@trace_group.command("set")
[email protected]("trace_path", type=click.Path(exists=False))
+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")
+def trace_info(ctx):
+ """Show the active trace path."""
+ session = _get_session(ctx)
+ _output(ctx, session.trace_info(), _human_trace_info)
+
+
+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.")
+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)
+
+
+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))
+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))
+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)
+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)
+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)
+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))
+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)
+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)
+
+
+def batch_group():
+ """Batch export workflows."""
+
+
+@batch_group.command("run-rsp")
[email protected]("rsp_path", type=click.Path(exists=False))
+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)
+
+
+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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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",
+ ],
+)