extra-desktop 0.3.2__tar.gz → 0.3.4__tar.gz

{extra_desktop-0.3.2/extra_desktop.egg-info → extra_desktop-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: extra-desktop
-Version: 0.3.2
+Version: 0.3.4
 Summary: Flashless Linux, Windows & macOS Computer-Use Engine & Model Context Protocol (MCP) Server
 Author-email: AIYantra Engineering Team <engineering@yantraos.com>
 License-Expression: MIT
@@ -11,14 +11,15 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: mcp>=1.0.0
+Requires-Dist: mcp<2,>=1.0.0
+Requires-Dist: websockets>=13.0
 Requires-Dist: playwright>=1.47.0
 Requires-Dist: pillow>=10.4.0
 Requires-Dist: beautifulsoup4>=4.12.3
 Requires-Dist: imagehash>=4.3.1
 Requires-Dist: numpy>=1.26.0
 Requires-Dist: psutil>=6.0.0
-Requires-Dist: kuzu>=0.11.0
+Requires-Dist: kuzu>=0.11.0; python_version < "3.14"
 Requires-Dist: fastembed>=0.8.0
 Requires-Dist: onnxruntime>=1.19.0
 Requires-Dist: pywin32>=306; sys_platform == "win32"
@@ -32,12 +33,19 @@ Requires-Dist: pyobjc-framework-ScreenCaptureKit>=10.0; sys_platform == "darwin"
 Requires-Dist: evdev>=1.7.0; sys_platform == "linux"
 Requires-Dist: mss>=9.0.1; sys_platform == "linux"
 Requires-Dist: jeepney>=0.8.0; sys_platform == "linux"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.11.0; extra == "dev"
+Provides-Extra: benchmark
+Requires-Dist: pytest-benchmark>=4.0.0; extra == "benchmark"
 Dynamic: license-file
 
 <div align="center">
 
 <a href="https://extra.yantraos.com">
-  <img src="https://raw.githubusercontent.com/AIYantra/extra/main/assets/logo.png" alt="Extra — Get extra from your AI" width="420" />
+  <img src="assets/logo.png" alt="Extra — Get extra from your AI" width="420" />
 </a>
 
 # Extra
@@ -54,7 +62,7 @@ Dynamic: license-file
 [![Ecosystem: yantraOS](https://img.shields.io/badge/Ecosystem-yantraOS-8A2BE2.svg)](https://yantraos.com)
 [![Status: Open Source](https://img.shields.io/badge/Open%20Source-%E2%99%A5-emerald.svg)](https://github.com/AIYantra/extra)
 
-[Website](https://extra.yantraos.com) • [Quickstart](#-quickstart-1-minute) • [Linux Guide](README_LINUX.md) • [macOS Guide](README_MACOS.md) • [Architecture](ARCHITECTURE.md) • [License](LICENSE)
+[Website](https://extra.yantraos.com) • [Quickstart](#-quickstart-1-minute) • [Linux Guide](README_LINUX.md) • [macOS Guide](README_MACOS.md) • [Architecture](docs/ARCHITECTURE.md) • [License](LICENSE)
 
 <br/>
 <br/>
@@ -67,7 +75,9 @@ Dynamic: license-file
 
 ---
 
-## ✨ Why Extra?
+## What is Extra and Why Does It Exist?
+
+Extra is an open-source Computer Use protocol and Model Context Protocol (MCP) server developed by yantraOS. It bridges LLMs (including ChatGPT, Claude, Cursor, and Gemini) directly to physical desktop operating systems across Linux, macOS, and Windows. Extra replaces fragile vision-only screenshot loops with native OS accessibility trees and sub-3ms GPU frame streaming, delivering pixel-perfect clicking, instant typing, and up to 225× lower token costs.
 
 Today's AI assistants can write brilliant essays and code, but they are trapped inside a chat window. When you need them to click a button, open an app, organize your files, or input data into a spreadsheet, they can only give you text instructions.
 
@@ -81,7 +91,7 @@ It connects **Claude, Google Antigravity, Cursor, AGY**, or any autonomous agent
 
 ---
 
-## 💡 What You Can Ask Your AI To Do
+## What Can an AI Assistant Do With Extra?
 
 Once Extra is running, you can talk to your AI like a real human assistant sitting at your desk:
 
@@ -190,7 +200,9 @@ Or using native Python:
 
 ---
 
-## 🎯 How It Works Under The Hood
+## How Does Extra Work Under the Hood?
+
+Extra operates via a sovereign Dual-Plane Architecture that decouples visual perception from hardware actuation. For perception, Extra combines sub-3ms GPU frame capture (DirectX DXGI, Metal, Spectacle) with OS accessibility hierarchy inspection (COM UI Automation, AT-SPI2, Quartz). For actuation, Extra dispatches lossless kernel and Win32 hardware events with zero coordinate drift, guaranteeing deterministic control across all resolutions and display scaling factors.
 
 Extra is engineered from the ground up for speed, reliability, and token efficiency:
 
@@ -278,14 +290,14 @@ extra/
 ├── cli.py                  # CLI runner (extra doctor, test, indicators, run, inspect, snap)
 ├── install.ps1             # 1-line PowerShell installer (Windows)
 ├── install.sh              # 1-line bash installer (macOS)
-├── pyproject.toml          # PyPI package manifest (extra-desktop v0.3.1)
-├── package.json            # npm package manifest (@yantraos/extra-desktop v0.3.1)
+├── pyproject.toml          # PyPI package manifest (extra-desktop v0.3.3)
+├── package.json            # npm package manifest (@yantraos/extra-desktop v0.3.3)
 ├── server.json             # Official MCP registry manifest
 ├── glama.json              # Glama MCP ecosystem manifest
 ├── smithery.yaml           # Smithery 1-click deployment manifest
 ├── requirements.txt        # Enterprise-audited dependency manifest
 ├── STARTER_PROMPT.md       # Master AI system prompt & setup directive
-├── ARCHITECTURE.md         # Full System Architecture Specification
+├── docs/                   # Full System Architecture & Specifications
 └── RELEASE_NOTES.md        # Comprehensive version release notes
 ```
 

{extra_desktop-0.3.2 → extra_desktop-0.3.4}/README.md

@@ -1,7 +1,7 @@
 <div align="center">
 
 <a href="https://extra.yantraos.com">
-  <img src="https://raw.githubusercontent.com/AIYantra/extra/main/assets/logo.png" alt="Extra — Get extra from your AI" width="420" />
+  <img src="assets/logo.png" alt="Extra — Get extra from your AI" width="420" />
 </a>
 
 # Extra
@@ -18,7 +18,7 @@
 [![Ecosystem: yantraOS](https://img.shields.io/badge/Ecosystem-yantraOS-8A2BE2.svg)](https://yantraos.com)
 [![Status: Open Source](https://img.shields.io/badge/Open%20Source-%E2%99%A5-emerald.svg)](https://github.com/AIYantra/extra)
 
-[Website](https://extra.yantraos.com) • [Quickstart](#-quickstart-1-minute) • [Linux Guide](README_LINUX.md) • [macOS Guide](README_MACOS.md) • [Architecture](ARCHITECTURE.md) • [License](LICENSE)
+[Website](https://extra.yantraos.com) • [Quickstart](#-quickstart-1-minute) • [Linux Guide](README_LINUX.md) • [macOS Guide](README_MACOS.md) • [Architecture](docs/ARCHITECTURE.md) • [License](LICENSE)
 
 <br/>
 <br/>
@@ -31,7 +31,9 @@
 
 ---
 
-## ✨ Why Extra?
+## What is Extra and Why Does It Exist?
+
+Extra is an open-source Computer Use protocol and Model Context Protocol (MCP) server developed by yantraOS. It bridges LLMs (including ChatGPT, Claude, Cursor, and Gemini) directly to physical desktop operating systems across Linux, macOS, and Windows. Extra replaces fragile vision-only screenshot loops with native OS accessibility trees and sub-3ms GPU frame streaming, delivering pixel-perfect clicking, instant typing, and up to 225× lower token costs.
 
 Today's AI assistants can write brilliant essays and code, but they are trapped inside a chat window. When you need them to click a button, open an app, organize your files, or input data into a spreadsheet, they can only give you text instructions.
 
@@ -45,7 +47,7 @@ It connects **Claude, Google Antigravity, Cursor, AGY**, or any autonomous agent
 
 ---
 
-## 💡 What You Can Ask Your AI To Do
+## What Can an AI Assistant Do With Extra?
 
 Once Extra is running, you can talk to your AI like a real human assistant sitting at your desk:
 
@@ -154,7 +156,9 @@ Or using native Python:
 
 ---
 
-## 🎯 How It Works Under The Hood
+## How Does Extra Work Under the Hood?
+
+Extra operates via a sovereign Dual-Plane Architecture that decouples visual perception from hardware actuation. For perception, Extra combines sub-3ms GPU frame capture (DirectX DXGI, Metal, Spectacle) with OS accessibility hierarchy inspection (COM UI Automation, AT-SPI2, Quartz). For actuation, Extra dispatches lossless kernel and Win32 hardware events with zero coordinate drift, guaranteeing deterministic control across all resolutions and display scaling factors.
 
 Extra is engineered from the ground up for speed, reliability, and token efficiency:
 
@@ -242,14 +246,14 @@ extra/
 ├── cli.py                  # CLI runner (extra doctor, test, indicators, run, inspect, snap)
 ├── install.ps1             # 1-line PowerShell installer (Windows)
 ├── install.sh              # 1-line bash installer (macOS)
-├── pyproject.toml          # PyPI package manifest (extra-desktop v0.3.1)
-├── package.json            # npm package manifest (@yantraos/extra-desktop v0.3.1)
+├── pyproject.toml          # PyPI package manifest (extra-desktop v0.3.3)
+├── package.json            # npm package manifest (@yantraos/extra-desktop v0.3.3)
 ├── server.json             # Official MCP registry manifest
 ├── glama.json              # Glama MCP ecosystem manifest
 ├── smithery.yaml           # Smithery 1-click deployment manifest
 ├── requirements.txt        # Enterprise-audited dependency manifest
 ├── STARTER_PROMPT.md       # Master AI system prompt & setup directive
-├── ARCHITECTURE.md         # Full System Architecture Specification
+├── docs/                   # Full System Architecture & Specifications
 └── RELEASE_NOTES.md        # Comprehensive version release notes
 ```
 

{extra_desktop-0.3.2 → extra_desktop-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "extra-desktop"
-version = "0.3.2"
+version = "0.3.4"
 description = "Flashless Linux, Windows & macOS Computer-Use Engine & Model Context Protocol (MCP) Server"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -13,14 +13,15 @@ authors = [
     { name = "AIYantra Engineering Team", email = "engineering@yantraos.com" }
 ]
 dependencies = [
-    "mcp>=1.0.0",
+    "mcp>=1.0.0,<2",
+    "websockets>=13.0",
     "playwright>=1.47.0",
     "pillow>=10.4.0",
     "beautifulsoup4>=4.12.3",
     "imagehash>=4.3.1",
     "numpy>=1.26.0",
     "psutil>=6.0.0",
-    "kuzu>=0.11.0",
+    "kuzu>=0.11.0; python_version < '3.14'",
     "fastembed>=0.8.0",
     "onnxruntime>=1.19.0",
     "pywin32>=306; sys_platform == 'win32'",
@@ -36,6 +37,17 @@ dependencies = [
     "jeepney>=0.8.0; sys_platform == 'linux'",
 ]
 
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.6.0",
+    "mypy>=1.11.0",
+]
+benchmark = [
+    "pytest-benchmark>=4.0.0",
+]
+
 [project.scripts]
 extra = "extra.cli:main"
 extra-desktop = "extra.cli:main"
@@ -45,17 +57,20 @@ Homepage = "https://extra.yantraos.com"
 Repository = "https://github.com/AIYantra/extra"
 Documentation = "https://extra.yantraos.com/docs"
 
-[tool.setuptools.package-dir]
-"extra" = "."
-"extra.core" = "core"
-"extra.core.platform" = "core/platform"
-"extra.core.platform.windows" = "core/platform/windows"
-"extra.core.platform.macos" = "core/platform/macos"
-"extra.core.platform.linux" = "core/platform/linux"
-"extra.fastpath" = "fastpath"
-"extra.mcp" = "mcp"
+[tool.setuptools.packages.find]
+where = ["src"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["src"]
 addopts = "-p no:faulthandler"
+markers = [
+    "unit: Fast isolated unit tests with zero system dependencies",
+    "integration: Subsystem integration tests",
+    "windows: Tests requiring Windows Win32 / UIA subsystems",
+    "linux: Tests requiring Linux X11 / Wayland / AT-SPI2 subsystems",
+    "macos: Tests requiring macOS Quartz / Accessibility subsystems",
+    "benchmark: Performance profiling and stress benchmark suites",
+    "security: Security audit and vulnerability verification tests",
+]
 

{extra_desktop-0.3.2 → extra_desktop-0.3.4/src/extra}/__init__.py

@@ -2,4 +2,4 @@
 Project Extra — Flashless Linux, Windows & macOS Computer-Use Engine & MCP Server.
 """
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"

{extra_desktop-0.3.2 → extra_desktop-0.3.4/src/extra}/cli.py

@@ -22,7 +22,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 try:
     from extra import __version__
 except Exception:
-    __version__ = "0.3.1"
+    __version__ = "0.3.4"
 
 from extra.core.capture import capture_screen
 from extra.core.focus import (
@@ -359,8 +359,45 @@ def cmd_run(args: argparse.Namespace) -> int:
         os.environ["EXTRA_ISOLATED_DESKTOP"] = "1"
     if getattr(args, "pip", False):
         os.environ["EXTRA_PIP_PREVIEW"] = "1"
+
+    transport = getattr(args, "transport", "stdio")
+    host = getattr(args, "host", "127.0.0.1")
+    port = getattr(args, "port", 8000)
+    auth_token = getattr(args, "auth_token", None)
+    allowed_hosts = getattr(args, "allowed_hosts", None)
+    tunnel = getattr(args, "tunnel", False)
+    if allowed_hosts and isinstance(allowed_hosts, str):
+        allowed_hosts = [h.strip() for h in allowed_hosts.split(",") if h.strip()]
+
     from extra.mcp.server import main
-    main()
+    main(transport=transport, host=host, port=port, auth_token=auth_token, allowed_hosts=allowed_hosts, tunnel=tunnel)
+    return 0
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    """Starts the Extra MCP server over SSE HTTP transport (for ChatGPT plugins & web agents)."""
+    setattr(args, "transport", "sse")
+    return cmd_run(args)
+
+
+def cmd_connect(args: argparse.Namespace) -> int:
+    """Connects this desktop to the Extra Cloud Hub for ChatGPT automation."""
+    from extra.relay import start_relay, DEFAULT_RELAY_URL
+    hub_url = getattr(args, "hub", None) or os.environ.get("EXTRA_HUB_URL") or DEFAULT_RELAY_URL
+    token = getattr(args, "token", None)
+    if not token or token == "anonymous":
+        token = os.environ.get("EXTRA_KEY") or os.environ.get("EXTRA_RELAY_KEY")
+    if not token or token == "anonymous":
+        print("[!] Error: Workstation link key is required to connect to the Extra Cloud Hub.")
+        print("    Get your key from your dashboard at: https://extra.yantraos.com/dashboard")
+        print("    Then run:")
+        print("      extra connect --key <your_key>")
+        return 1
+    start_relay(
+        hub_url=hub_url,
+        token=token,
+        device_name=getattr(args, "name", None),
+    )
     return 0
 
 
@@ -836,7 +873,7 @@ def cmd_update(args: argparse.Namespace) -> int:
         if pyproject_file.exists():
             try:
                 subprocess.run(
-                    [sys.executable, "-m", "pip", "install", "--quiet", "-e", str(repo_dir)],
+                    [sys.executable, "-m", "pip", "install", "--quiet", "--no-deps", "-e", str(repo_dir)],
                     check=True,
                 )
                 print("  [OK] Package editable link verified.")
@@ -845,6 +882,32 @@ def cmd_update(args: argparse.Namespace) -> int:
     else:
         print("\n[Dependency Refresh] Skipped (--skip-deps specified).")
 
+    # Phase 2b: Refresh CLI executable wrappers with updated PYTHONPATH
+    try:
+        bin_dir = Path.home() / ".extra" / "bin"
+        if bin_dir.exists():
+            if platform.system() == "Windows":
+                cmd_wrapper = bin_dir / "extra.cmd"
+                cmd_content = (
+                    f"@echo off\n"
+                    f"set PYTHONPATH={repo_dir}\\src;{repo_dir};%PYTHONPATH%\n"
+                    f'"{sys.executable}" -m extra.cli %*\n'
+                )
+                cmd_wrapper.write_text(cmd_content, encoding="ascii")
+                print("  [OK] Updated Windows CLI wrapper in ~/.extra/bin/extra.cmd.")
+            else:
+                sh_wrapper = bin_dir / "extra"
+                sh_content = (
+                    f"#!/usr/bin/env bash\n"
+                    f'export PYTHONPATH="{repo_dir}/src:{repo_dir}:$PYTHONPATH"\n'
+                    f'exec "{sys.executable}" -m extra.cli "$@"\n'
+                )
+                sh_wrapper.write_text(sh_content, encoding="utf-8")
+                sh_wrapper.chmod(0o755)
+                print("  [OK] Updated Unix CLI wrapper in ~/.extra/bin/extra.")
+    except Exception as ex:
+        print(f"  [WARN] Could not refresh CLI wrapper: {ex}")
+
     # Phase 3: AI Rules & Skills Synchronization
     sync_ai_rules_and_skills(repo_dir)
 
@@ -995,6 +1058,53 @@ def cmd_audit(args) -> int:
         return 1
 
 
+def cmd_mode(args: argparse.Namespace) -> int:
+    """View or change the Extra automation execution speed mode."""
+    from extra.core.mode import (
+        ExecutionMode,
+        get_execution_mode,
+        set_execution_mode,
+        get_mode_config,
+    )
+
+    target_mode = getattr(args, "mode", None)
+    if not target_mode:
+        curr = get_execution_mode()
+        cfg = get_mode_config(curr)
+        print("\n" + "=" * 60)
+        print(f"  [Extra] EXECUTION MODE: {curr.value.upper()}")
+        print("=" * 60)
+        print(f"  * Active Profile          : {cfg.mode.value}")
+        print(f"  * Settle Delay Timeout    : {cfg.settle_timeout_sec}s")
+        print(f"  * Max Inspected Elements  : {cfg.max_inspect_elements}")
+        print(f"  * Compact UI Serialization: {cfg.compact_ui}")
+        print(f"  * Sleep Scale Factor      : {cfg.sleep_scale}x (max {cfg.max_sleep_ms}ms)")
+        print(f"  * Proactive Memory Recall : {cfg.proactive_memory_recall}")
+        print(f"  * Dual-Plane Verification : {cfg.dual_plane_verification}")
+        print("-" * 60)
+        print("  Available Modes:")
+        print("    - turbo    (low, fast)      : Sub-50ms dispatch, 0ms settle, <800B UI")
+        print("    - balanced (medium, default): ~15ms settle, balanced UI & safety gates")
+        print("    - smart    (high, verify)   : Full SOUL visual critic & memory recall")
+        print("-" * 60)
+        print("  Usage: extra mode <turbo|balanced|smart> or extra modeset <mode>\n")
+        return 0
+
+    try:
+        resolved = ExecutionMode.from_string(target_mode)
+    except Exception as e:
+        print(f"Error: Invalid mode '{target_mode}': {e}", file=sys.stderr)
+        return 1
+
+    cfg = set_execution_mode(resolved, persist=True)
+    print(f"\n[Extra] Execution mode set to: {resolved.value.upper()} (saved to ~/.extra/config.json)")
+    print(f"  * Settle Timeout   : {cfg.settle_timeout_sec}s")
+    print(f"  * Sleep Scale      : {cfg.sleep_scale}x")
+    print(f"  * Compact UI       : {cfg.compact_ui}")
+    print(f"  * Proactive Recall : {cfg.proactive_memory_recall}\n")
+    return 0
+
+
 def check_first_run_consent() -> None:
     """Checks and prompts for first-run interactive telemetry consent."""
     from extra.core.metrics.config import (
@@ -1035,7 +1145,8 @@ def check_first_run_consent() -> None:
         save_config(cfg)
 
 
-def main() -> None:
+def build_parser() -> argparse.ArgumentParser:
+    """Builds and returns the top-level ArgumentParser for Extra CLI."""
     parser = argparse.ArgumentParser(
         prog="extra",
         description="Extra — Flashless macOS, Windows & Linux Computer-Use Engine & MCP Server",
@@ -1045,6 +1156,13 @@ def main() -> None:
     )
     subparsers = parser.add_subparsers(dest="command", help="Available commands")
 
+    # mode / modeset
+    mode_parser = subparsers.add_parser("mode", help="View or set the Extra automation speed mode (turbo, balanced, smart)")
+    mode_parser.add_argument("mode", nargs="?", default=None, help="Speed mode to activate: turbo (low/fast), balanced (medium/default), smart (high/deliberate)")
+
+    modeset_parser = subparsers.add_parser("modeset", help="Set the Extra automation speed mode (alias for 'extra mode')")
+    modeset_parser.add_argument("mode", nargs="?", default=None, help="Speed mode to activate: turbo (low/fast), balanced (medium/default), smart (high/deliberate)")
+
     # doctor
     doctor_parser = subparsers.add_parser("doctor", help="Run system health and capability diagnostics")
     doctor_parser.add_argument("--open", "-o", action="store_true", help="Open System Settings privacy panes if permissions missing")
@@ -1069,11 +1187,32 @@ def main() -> None:
     update_parser.add_argument("--force", action="store_true", help="Force update and reset local changes to upstream")
 
     # run
-    run_parser = subparsers.add_parser("run", help="Start the MCP Server on stdio")
-    run_parser.add_argument("--transport", default="stdio", choices=["stdio"], help="Transport mode")
+    run_parser = subparsers.add_parser("run", help="Start the MCP Server on stdio or SSE")
+    run_parser.add_argument("--transport", default="stdio", choices=["stdio", "sse", "streamable-http"], help="Transport mode (default: stdio)")
+    run_parser.add_argument("--host", default="127.0.0.1", help="Host IP to bind to when running SSE or HTTP transport (default: 127.0.0.1)")
+    run_parser.add_argument("--port", "-p", type=int, default=8000, help="Port to bind to when running SSE or HTTP transport (default: 8000)")
+    run_parser.add_argument("--auth-token", "--auth", default=None, help="Bearer authorization token to secure SSE transport")
+    run_parser.add_argument("--allowed-hosts", default=None, help="Comma-separated allowed host header values for DNS rebinding protection")
+    run_parser.add_argument("--tunnel", "-t", action="store_true", help="Launch secure Cloudflare Quick Tunnel (public HTTPS) for pairing with ChatGPT or remote agents")
     run_parser.add_argument("--isolate", action="store_true", help="Confine automation to isolated child session / virtual desktop")
     run_parser.add_argument("--pip", action="store_true", help="Launch live Picture-in-Picture floating preview window")
 
+    # serve (ChatGPT Plugin & Remote Web Agent bridge)
+    serve_parser = subparsers.add_parser("serve", help="Start the Extra MCP Server over SSE HTTP transport (for ChatGPT plugins & web agents)")
+    serve_parser.add_argument("--host", default="127.0.0.1", help="Host IP to bind to (default: 127.0.0.1; use 0.0.0.0 for public/tunnel)")
+    serve_parser.add_argument("--port", "-p", type=int, default=8000, help="Port to bind to (default: 8000)")
+    serve_parser.add_argument("--auth-token", "--auth", default=None, help="Bearer authorization token to secure SSE transport")
+    serve_parser.add_argument("--allowed-hosts", default=None, help="Comma-separated allowed host headers (e.g. *.trycloudflare.com)")
+    serve_parser.add_argument("--tunnel", "-t", action="store_true", help="Launch secure Cloudflare Quick Tunnel (public HTTPS) for pairing with ChatGPT or remote agents")
+    serve_parser.add_argument("--isolate", action="store_true", help="Confine automation to isolated child session / virtual desktop")
+    serve_parser.add_argument("--pip", action="store_true", help="Launch live Picture-in-Picture floating preview window")
+
+    # connect (Desktop Relay Client for ChatGPT & Cloud Hub)
+    connect_parser = subparsers.add_parser("connect", help="Connect this desktop to the Extra Cloud Hub for ChatGPT automation")
+    connect_parser.add_argument("--hub", default=None, help="WebSocket Relay Hub URL (default: official extra.yantraos.com relay)")
+    connect_parser.add_argument("--key", "--token", dest="token", default="anonymous", help="Setup key or authentication token from extra.yantraos.com account")
+    connect_parser.add_argument("--name", default=None, help="Custom friendly device name for this workstation")
+
     # pip (Picture-in-Picture floating preview window)
     pip_parser = subparsers.add_parser("pip", help="Control hardware-accelerated Picture-in-Picture floating preview window")
     pip_parser.add_argument("action", nargs="?", default="demo", choices=["demo", "start", "stop"], help="Action: demo (live 3s preview), start, stop")
@@ -1154,6 +1293,11 @@ def main() -> None:
     audit_parser.add_argument("--record", "-r", action="store_true", help="Record audited mission metrics into local impact_ledger.json")
     audit_parser.add_argument("--json", action="store_true", help="Output audit results in raw JSON")
 
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
     args = parser.parse_args()
 
     if not args.command:
@@ -1171,7 +1315,9 @@ def main() -> None:
     except Exception:
         pass
 
-    if args.command == "stats":
+    if args.command in ("mode", "modeset"):
+        sys.exit(cmd_mode(args))
+    elif args.command == "stats":
         sys.exit(cmd_stats(args))
     elif args.command == "dashboard":
         sys.exit(cmd_dashboard(args))
@@ -1195,6 +1341,10 @@ def main() -> None:
         sys.exit(cmd_uninstall(args))
     elif args.command == "run":
         sys.exit(cmd_run(args))
+    elif args.command == "serve":
+        sys.exit(cmd_serve(args))
+    elif args.command == "connect":
+        sys.exit(cmd_connect(args))
     elif args.command == "pip":
         sys.exit(cmd_pip(args))
     elif args.command == "inspect":

{extra_desktop-0.3.2 → extra_desktop-0.3.4/src/extra}/core/__init__.py

@@ -74,6 +74,13 @@ from extra.core.subtask import (
     SubtaskRunner,
     run_subtask,
 )
+from extra.core.mode import (
+    ExecutionMode,
+    ModeConfig,
+    get_execution_mode,
+    set_execution_mode,
+    get_mode_config,
+)
 from extra.core.soul import (
     DecisionType,
     SoulDecision,
@@ -156,4 +163,10 @@ __all__ = [
     "SubtaskResult",
     "SubtaskRunner",
     "run_subtask",
+    # Sovereign Execution Mode Controller
+    "ExecutionMode",
+    "ModeConfig",
+    "get_execution_mode",
+    "set_execution_mode",
+    "get_mode_config",
 ]