feat(macos): bundle self-contained runtime (#49)

Signed-off-by: xunzhuo <xunzhuo@vllm-semantic-router.ai>

Author: Xunzhuo

Makefile

@@ -21,6 +21,9 @@ MACOS_APP_BUILD_NUMBER ?=
 MACOS_SIGNING_IDENTITY ?=
 MACOS_NOTARIZE ?=
 MACOS_ASSET_DIR ?=
+MACOS_BUNDLE_RUNTIME ?= auto
+MACOS_RUNTIME_PYTHON_VERSION ?= 3.12
+MACOS_RUNTIME_PYTHON ?=
 MACOS_RELEASE_TAG ?= latest
 MACOS_RELEASE_TITLE ?= Elephant Agent latest
 RESET_API_E2E_TARGETS = \
@@ -107,6 +110,8 @@ macos-help:
 	@echo "  make macos-build MACOS_TARGET=x86_64-apple-darwin"
 	@echo "  make macos-build-all"
 	@echo "  make macos-release-latest"
+	@echo "  MACOS_BUNDLE_RUNTIME=auto|1|0"
+	@echo "  MACOS_RUNTIME_PYTHON=/path/to/python3.12"
 	@echo ""
 	@echo "Signing/notarization variables:"
 	@echo "  MACOS_SIGNING_IDENTITY='Developer ID Application: ...'"
@@ -121,6 +126,9 @@ macos-build:
 		MACOS_SIGNING_IDENTITY="$(MACOS_SIGNING_IDENTITY)" \
 		MACOS_NOTARIZE="$(MACOS_NOTARIZE)" \
 		MACOS_ASSET_DIR="$(MACOS_ASSET_DIR)" \
+		MACOS_BUNDLE_RUNTIME="$(MACOS_BUNDLE_RUNTIME)" \
+		MACOS_RUNTIME_PYTHON_VERSION="$(MACOS_RUNTIME_PYTHON_VERSION)" \
+		MACOS_RUNTIME_PYTHON="$(MACOS_RUNTIME_PYTHON)" \
 		bash apps/macos/Scripts/build-app.sh
 
 macos-build-all:
@@ -132,7 +140,10 @@ macos-build-all:
 			MACOS_APP_BUILD_NUMBER="$(MACOS_APP_BUILD_NUMBER)" \
 			MACOS_SIGNING_IDENTITY="$(MACOS_SIGNING_IDENTITY)" \
 			MACOS_NOTARIZE="$(MACOS_NOTARIZE)" \
-			MACOS_ASSET_DIR="$(MACOS_ASSET_DIR)"; \
+			MACOS_ASSET_DIR="$(MACOS_ASSET_DIR)" \
+			MACOS_BUNDLE_RUNTIME="$(MACOS_BUNDLE_RUNTIME)" \
+			MACOS_RUNTIME_PYTHON_VERSION="$(MACOS_RUNTIME_PYTHON_VERSION)" \
+			MACOS_RUNTIME_PYTHON="$(MACOS_RUNTIME_PYTHON)"; \
 	done
 
 macos-release-latest: macos-build-all

apps/macos/Entitlements.plist

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>com.apple.security.cs.allow-jit</key>
+  <true/>
+  <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+  <true/>
+  <key>com.apple.security.cs.disable-library-validation</key>
+  <true/>
+</dict>
+</plist>

apps/macos/README.md

@@ -7,31 +7,42 @@ The mac app does not replace the Python core. It starts the existing `apps.api`
 ## Build
 
 ```bash
-swift build --package-path apps/macos
-apps/macos/Scripts/build-app.sh
-open -n "apps/macos/.build/release/Elephant Agent.app"
+make macos-build
+open -n "apps/macos/.build/release/$(uname -m | sed 's/arm64/aarch64/')-apple-darwin/Elephant Agent.app"
 ```
 
 Full Xcode is not required when the installed Command Line Tools and macOS SDK match. The packaging script creates a local `.app`, copies the site brand assets into the bundle resources, signs ad hoc by default, and emits a `.dmg`, `.app.zip`, and SHA256 files under `apps/macos/.build/artifacts/<target>/`.
 
+By default, `make macos-build` attempts to produce a self-contained app on the current Mac architecture. When `uv` is available and the requested `MACOS_TARGET` matches the host architecture, the bundle includes:
+
+- `Contents/Resources/Runtime/python`: managed CPython 3.12
+- `Contents/Resources/Runtime/site-packages`: Elephant Agent and Python dependencies
+- `Contents/Resources/Runtime/ms-playwright`: Playwright Chromium headless shell
+
+Set `MACOS_BUNDLE_RUNTIME=0` for a lightweight bootstrap build that falls back to the bundled `Install/install.sh` on machines without a developer repo. Set `MACOS_BUNDLE_RUNTIME=1` to require the embedded runtime and fail instead of falling back. Cross-architecture self-contained builds should run on a matching macOS runner or pass `MACOS_RUNTIME_PYTHON=/path/to/python3.12` for the target architecture.
+
 The repo-level Makefile wraps the release paths:
 
 ```bash
 make macos-build
 make macos-build MACOS_TARGET=aarch64-apple-darwin
 make macos-build MACOS_TARGET=x86_64-apple-darwin
 make macos-build-all
+make macos-build MACOS_BUNDLE_RUNTIME=1
 ```
 
 Developer ID distribution builds can opt into signing and notarization:
 
 ```bash
 make macos-build-all \
+  MACOS_BUNDLE_RUNTIME=1 \
   MACOS_SIGNING_IDENTITY="Developer ID Application: Example Team (TEAMID)" \
   MACOS_NOTARIZE=1 \
   APPLE_ID="apple-id@example.com" \
   APPLE_PASSWORD="app-specific-password" \
   APPLE_TEAM_ID="TEAMID"
 ```
 
+Without `MACOS_SIGNING_IDENTITY`, builds remain ad-hoc signed and notarization is skipped so local developers can still build a DMG. Ad-hoc artifacts are useful for testing but are not Gatekeeper-clean for broad distribution. Official shareable releases should use Developer ID signing and notarization.
+
 `make macos-release-latest` expects `gh` authentication and replaces the GitHub `latest` release/tag with the current local artifacts. The CI workflow `.github/workflows/macos-latest-release.yml` runs the same build on each push to `main`, uploads both macOS architecture artifacts, writes `latest.json`, and replaces the `latest` GitHub release.

apps/macos/Scripts/build-app.sh

@@ -10,6 +10,8 @@ BUNDLE_IDENTIFIER="${MACOS_BUNDLE_IDENTIFIER:-ai.agentic.elephant.mac}"
 DEPLOYMENT_TARGET="${MACOS_DEPLOYMENT_TARGET:-13.0}"
 SIGNING_IDENTITY="${MACOS_SIGNING_IDENTITY:--}"
 NOTARIZE="${MACOS_NOTARIZE:-0}"
+SIGNING_ENTITLEMENTS="${MACOS_CODESIGN_ENTITLEMENTS:-${APP_DIR}/Entitlements.plist}"
+BUNDLE_RUNTIME_REQUEST="${MACOS_BUNDLE_RUNTIME:-auto}"
 
 host_target() {
   case "$(uname -m)" in
@@ -97,6 +99,49 @@ RESOURCES="${CONTENTS}/Resources"
 ARTIFACT_PREFIX="ElephantAgent_${APP_VERSION_SAFE}_${ARTIFACT_TARGET}"
 ARTIFACT_DMG="${ARTIFACT_DIR}/${ARTIFACT_PREFIX}.dmg"
 ARTIFACT_APP_ZIP="${ARTIFACT_DIR}/${ARTIFACT_PREFIX}.app.zip"
+RUNTIME_ROOT="${RESOURCES}/Runtime"
+RUNTIME_BUILD_CACHE="${MACOS_RUNTIME_BUILD_CACHE:-${BUILD_DIR}/runtime-cache}"
+
+can_auto_bundle_runtime() {
+  if [[ -n "${MACOS_RUNTIME_PYTHON:-}" ]]; then
+    return 0
+  fi
+  if [[ "${ARTIFACT_TARGET}" != "$(host_target)" ]]; then
+    return 1
+  fi
+  command -v uv >/dev/null 2>&1
+}
+
+resolve_bundle_runtime() {
+  case "${BUNDLE_RUNTIME_REQUEST}" in
+    1|true|yes|on)
+      if [[ -z "${MACOS_RUNTIME_PYTHON:-}" && "${ARTIFACT_TARGET}" != "$(host_target)" ]]; then
+        echo "MACOS_BUNDLE_RUNTIME=1 requires a matching host target or MACOS_RUNTIME_PYTHON for ${ARTIFACT_TARGET}." >&2
+        exit 1
+      fi
+      printf '%s\n' "1"
+      ;;
+    0|false|no|off)
+      printf '%s\n' "0"
+      ;;
+    auto|"")
+      if [[ -n "${MACOS_RUNTIME_PYTHON:-}" ]]; then
+        printf '%s\n' "1"
+      elif can_auto_bundle_runtime; then
+        printf '%s\n' "1"
+      else
+        echo "Bundled runtime unavailable for ${ARTIFACT_TARGET}; falling back to installer bootstrap." >&2
+        printf '%s\n' "0"
+      fi
+      ;;
+    *)
+      echo "Unsupported MACOS_BUNDLE_RUNTIME: ${BUNDLE_RUNTIME_REQUEST}" >&2
+      exit 2
+      ;;
+  esac
+}
+
+BUNDLE_RUNTIME="$(resolve_bundle_runtime)"
 
 if [[ "${NOTARIZE}" == "auto" ]]; then
   if [[ "${SIGNING_IDENTITY}" != "-" \
@@ -138,12 +183,40 @@ sign_path() {
   local path="$1"
   require_macos_tool codesign
   if [[ "${SIGNING_IDENTITY}" == "-" ]]; then
-    codesign --force --deep --sign - "${path}" >/dev/null
+    codesign --force --sign - "${path}" >/dev/null
   else
-    codesign --force --deep --options runtime --timestamp --sign "${SIGNING_IDENTITY}" "${path}" >/dev/null
+    if [[ -f "${SIGNING_ENTITLEMENTS}" ]]; then
+      codesign --force --options runtime --timestamp --entitlements "${SIGNING_ENTITLEMENTS}" --sign "${SIGNING_IDENTITY}" "${path}" >/dev/null
+    else
+      codesign --force --options runtime --timestamp --sign "${SIGNING_IDENTITY}" "${path}" >/dev/null
+    fi
   fi
 }
 
+sign_macho_file() {
+  local path="$1"
+  require_macos_tool codesign
+  if [[ "${SIGNING_IDENTITY}" == "-" ]]; then
+    codesign --force --sign - "${path}" >/dev/null
+  else
+    if [[ -f "${SIGNING_ENTITLEMENTS}" ]]; then
+      codesign --force --options runtime --timestamp --entitlements "${SIGNING_ENTITLEMENTS}" --sign "${SIGNING_IDENTITY}" "${path}" >/dev/null
+    else
+      codesign --force --options runtime --timestamp --sign "${SIGNING_IDENTITY}" "${path}" >/dev/null
+    fi
+  fi
+}
+
+sign_nested_macho_files() {
+  local root="$1"
+  require_macos_tool file
+  while IFS= read -r -d '' path; do
+    if file "${path}" | grep -q "Mach-O"; then
+      sign_macho_file "${path}"
+    fi
+  done < <(find "${root}" -type f -print0)
+}
+
 notarize_submission() {
   local path="$1"
   local label="$2"
@@ -211,9 +284,13 @@ fi
 mkdir -p "${MACOS}" "${RESOURCES}/Brand" "${RESOURCES}/Resources" "${RESOURCES}/Install"
 install -m 755 "${BINARY}" "${MACOS}/${APP_NAME}"
 
-printf "%s\n" "${REPO_ROOT}" > "${RESOURCES}/RepoRoot.txt"
-if command -v python3 >/dev/null 2>&1; then
-  command -v python3 > "${RESOURCES}/PythonPath.txt"
+if [[ "${BUNDLE_RUNTIME}" == "1" && "${MACOS_INCLUDE_DEV_PATHS:-0}" != "1" ]]; then
+  rm -f "${RESOURCES}/RepoRoot.txt" "${RESOURCES}/PythonPath.txt"
+else
+  printf "%s\n" "${REPO_ROOT}" > "${RESOURCES}/RepoRoot.txt"
+  if command -v python3 >/dev/null 2>&1; then
+    command -v python3 > "${RESOURCES}/PythonPath.txt"
+  fi
 fi
 install -m 755 "${REPO_ROOT}/install.sh" "${RESOURCES}/Install/install.sh"
 
@@ -238,6 +315,12 @@ if [[ -d "${MACOS_RESOURCES_DIR}" ]]; then
   ditto "${MACOS_RESOURCES_DIR}" "${RESOURCES}"
 fi
 
+if [[ "${BUNDLE_RUNTIME}" == "1" ]]; then
+  bash "${SCRIPT_DIR}/package-runtime.sh" "${RUNTIME_ROOT}" "${REPO_ROOT}" "${ARTIFACT_TARGET}" "${RUNTIME_BUILD_CACHE}"
+else
+  echo "Bundled runtime: disabled. This build will use Install/install.sh bootstrap on machines without a developer repo."
+fi
+
 ICON_SOURCE="${RESOURCES}/Brand/favicon.png"
 ICONSET="${RESOURCES}/AppIcon.iconset"
 if command -v sips >/dev/null 2>&1 && command -v iconutil >/dev/null 2>&1 && [[ -f "${ICON_SOURCE}" ]]; then
@@ -300,6 +383,7 @@ cat > "${CONTENTS}/Info.plist" <<PLIST
 </plist>
 PLIST
 
+sign_nested_macho_files "${CONTENTS}"
 sign_path "${BUNDLE}"
 codesign --verify --deep --strict --verbose=2 "${BUNDLE}"
 
@@ -323,6 +407,8 @@ hdiutil create -volname "${APP_NAME}" -srcfolder "${STAGE}" -ov -format UDZO "${
 if [[ "${SIGNING_IDENTITY}" != "-" ]]; then
   codesign --force --timestamp --sign "${SIGNING_IDENTITY}" "${DMG}" >/dev/null
   notarize_path "${DMG}" "${APP_NAME}.dmg"
+else
+  echo "DMG signing/notarization skipped: MACOS_SIGNING_IDENTITY is ad-hoc."
 fi
 
 ditto -c -k --keepParent "${BUNDLE}" "${ARTIFACT_APP_ZIP}"
@@ -337,3 +423,4 @@ printf '  artifact_dmg: %s\n' "${ARTIFACT_DMG}"
 printf '  artifact_dmg_sha256: %s\n' "${ARTIFACT_DMG}.sha256"
 printf '  artifact_app_zip: %s\n' "${ARTIFACT_APP_ZIP}"
 printf '  artifact_app_zip_sha256: %s\n' "${ARTIFACT_APP_ZIP}.sha256"
+printf '  bundled_runtime: %s\n' "${BUNDLE_RUNTIME}"