fix: harden example auto-runs against PATH and port conflicts (#2770)

Author: seratch

examples/mcp/sse_example/main.py

@@ -1,14 +1,32 @@
 import asyncio
 import os
 import shutil
+import socket
 import subprocess
 import time
-from typing import Any
+from typing import Any, cast
 
 from agents import Agent, Runner, gen_trace_id, trace
 from agents.mcp import MCPServer, MCPServerSse
 from agents.model_settings import ModelSettings
 
+SSE_HOST = os.getenv("SSE_HOST", "127.0.0.1")
+
+
+def _choose_port() -> int:
+    env_port = os.getenv("SSE_PORT")
+    if env_port:
+        return int(env_port)
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind((SSE_HOST, 0))
+        address = cast(tuple[str, int], s.getsockname())
+        return address[1]
+
+
+SSE_PORT = _choose_port()
+os.environ.setdefault("SSE_PORT", str(SSE_PORT))
+SSE_URL = f"http://{SSE_HOST}:{SSE_PORT}/sse"
+
 
 async def run(mcp_server: MCPServer):
     agent = Agent(
@@ -41,7 +59,7 @@ async def main():
     async with MCPServerSse(
         name="SSE Python Server",
         params={
-            "url": "http://localhost:8000/sse",
+            "url": SSE_URL,
         },
     ) as server:
         trace_id = gen_trace_id()
@@ -58,16 +76,19 @@ async def main():
         )
 
     # We'll run the SSE server in a subprocess. Usually this would be a remote server, but for this
-    # demo, we'll run it locally at http://localhost:8000/sse
+    # demo, we'll run it locally at SSE_URL.
     process: subprocess.Popen[Any] | None = None
     try:
         this_dir = os.path.dirname(os.path.abspath(__file__))
         server_file = os.path.join(this_dir, "server.py")
 
-        print("Starting SSE server at http://localhost:8000/sse ...")
+        print(f"Starting SSE server at {SSE_URL} ...")
 
         # Run `uv run server.py` to start the SSE server
-        process = subprocess.Popen(["uv", "run", server_file])
+        env = os.environ.copy()
+        env.setdefault("SSE_HOST", SSE_HOST)
+        env.setdefault("SSE_PORT", str(SSE_PORT))
+        process = subprocess.Popen(["uv", "run", server_file], env=env)
         # Give it 3 seconds to start
         time.sleep(3)
 

examples/mcp/sse_example/server.py

@@ -1,9 +1,13 @@
+import os
 import random
 
 from mcp.server.fastmcp import FastMCP
 
+SSE_HOST = os.getenv("SSE_HOST", "127.0.0.1")
+SSE_PORT = int(os.getenv("SSE_PORT", "8000"))
+
 # Create server
-mcp = FastMCP("Echo Server")
+mcp = FastMCP("Echo Server", host=SSE_HOST, port=SSE_PORT)
 
 
 @mcp.tool()

examples/run_examples.py

@@ -13,6 +13,7 @@
 
 import argparse
 import datetime
+import functools
 import os
 import re
 import shlex
@@ -32,13 +33,32 @@
 RERUN_FILE_DEFAULT = ROOT_DIR / ".tmp" / "examples-rerun.txt"
 DEFAULT_MAIN_LOG = LOG_DIR_DEFAULT / f"main_{datetime.datetime.now().strftime('%Y%m%d-%H%M%S')}.log"
 
+COMMON_PATH_HINTS = (
+    Path.home() / ".local" / "bin",
+    Path("/opt/homebrew/bin"),
+    Path("/opt/homebrew/sbin"),
+    Path("/usr/local/bin"),
+    Path("/usr/local/sbin"),
+)
+
+DISCOVERY_EXCLUDE = {
+    "examples/run_examples.py",
+}
+
 # Examples that are noisy, require extra credentials, or hang in auto runs.
 DEFAULT_AUTO_SKIP = {
     "examples/agent_patterns/llm_as_a_judge.py",
     "examples/agent_patterns/routing.py",
     "examples/customer_service/main.py",
     "examples/hosted_mcp/connectors.py",
     "examples/mcp/git_example/main.py",
+    # These are helper daemons or multi-process components exercised by sibling examples.
+    "examples/mcp/manager_example/app.py",
+    "examples/mcp/manager_example/mcp_server.py",
+    "examples/mcp/prompt_server/server.py",
+    "examples/mcp/sse_example/server.py",
+    "examples/mcp/streamablehttp_custom_client_example/server.py",
+    "examples/mcp/streamablehttp_example/server.py",
     "examples/model_providers/custom_example_agent.py",
     "examples/model_providers/custom_example_global.py",
     "examples/model_providers/custom_example_provider.py",
@@ -84,6 +104,63 @@ def normalize_relpath(relpath: str) -> str:
     return str(PurePosixPath(normalized))
 
 
+def split_path_entries(path_value: str) -> list[str]:
+    return [entry for entry in path_value.split(os.pathsep) if entry]
+
+
+def dedupe_existing_paths(paths: Iterable[str]) -> list[str]:
+    deduped: list[str] = []
+    seen: set[str] = set()
+    for entry in paths:
+        expanded = os.path.expanduser(entry)
+        if not expanded or expanded in seen:
+            continue
+        if not Path(expanded).exists():
+            continue
+        deduped.append(expanded)
+        seen.add(expanded)
+    return deduped
+
+
+@functools.lru_cache(maxsize=1)
+def interactive_shell_path() -> str | None:
+    shell = os.environ.get("SHELL")
+    if not shell:
+        return None
+
+    shell_name = Path(shell).name
+    if shell_name not in {"bash", "zsh"}:
+        return None
+
+    try:
+        result = subprocess.run(
+            [shell, "-lic", 'printf "%s" "$PATH"'],
+            capture_output=True,
+            check=True,
+            cwd=ROOT_DIR,
+            text=True,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+    path_value = result.stdout.strip()
+    return path_value or None
+
+
+def build_command_path(base_path: str | None = None) -> str:
+    candidates: list[str] = []
+    if base_path is None:
+        base_path = os.environ.get("PATH", "")
+    candidates.extend(split_path_entries(base_path))
+
+    shell_path = interactive_shell_path()
+    if shell_path:
+        candidates.extend(split_path_entries(shell_path))
+
+    candidates.extend(str(path) for path in COMMON_PATH_HINTS)
+    return os.pathsep.join(dedupe_existing_paths(candidates))
+
+
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description="Run example scripts sequentially.")
     parser.add_argument(
@@ -221,6 +298,10 @@ def discover_examples(filters: Iterable[str]) -> list[ExampleScript]:
         if not MAIN_PATTERN.search(source):
             continue
 
+        relpath = normalize_relpath(str(path.relative_to(ROOT_DIR)))
+        if relpath in DISCOVERY_EXCLUDE:
+            continue
+
         if filters_lower and not any(
             f in str(path.relative_to(ROOT_DIR)).lower() for f in filters_lower
         ):
@@ -351,6 +432,11 @@ def run_examples(examples: Sequence[ExampleScript], args: argparse.Namespace) ->
     buffer_output = not args.no_buffer_output and os.environ.get(
         "EXAMPLES_BUFFER_OUTPUT", "1"
     ).lower() not in {"0", "false", "no", "off"}
+    command_path = build_command_path()
+    path_augmented = command_path != os.environ.get("PATH", "")
+
+    if path_augmented:
+        print("Augmented subprocess PATH using interactive shell/common tool directories.")
 
     def safe_write_main(line: str) -> None:
         with main_log_lock:
@@ -363,6 +449,7 @@ def run_single(example: ExampleScript) -> ExampleResult:
         ensure_dirs(log_path, is_file=True)
 
         env = os.environ.copy()
+        env["PATH"] = command_path
         if auto_mode:
             env["EXAMPLES_INTERACTIVE_MODE"] = "auto"
             env["APPLY_PATCH_AUTO_APPROVE"] = "1"
@@ -441,6 +528,7 @@ def run_single(example: ExampleScript) -> ExampleResult:
         safe_write_main(f"# logs_dir: {logs_dir}")
         safe_write_main(f"# jobs: {jobs}")
         safe_write_main(f"# buffer_output: {buffer_output}")
+        safe_write_main(f"# path_augmented: {path_augmented}")
 
         run_list: list[ExampleScript] = []