answer42 0.4.97__tar.gz → 0.4.99__tar.gz

{answer42-0.4.97 → answer42-0.4.99}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: answer42
-Version: 0.4.97
+Version: 0.4.99
 Summary: Answer42 — The Answer to Life, Universe, and 1C — UI Driver. MCP-powered 1C:Enterprise UI automation: click, fill, navigate, test, and introspect managed forms through the test-client API
 Author: Marvin (AI Assistant), 42Clouds, and contributors
 Author-email: "Kosolapov Stanislav (proDOOMman)" <prodoomman@gmail.com>
@@ -162,6 +162,29 @@ answer42 install-skills --dry-run --agent all
 4. зарегистрируйте MCP-сервер в агентском клиенте;
 5. проверьте установку через `credentials_check`, затем smoke-сессию `start_session` → `active_window` → `stop_session`.
 
+## Linux display prerequisite
+
+На Linux `start_session` использует живую X11-сессию, если процесс Answer42 унаследовал непустой `DISPLAY`: test manager и test client запускаются на этом дисплее, поэтому их окна и скриншоты видны на desktop.
+
+Если `DISPLAY` не задан (headless service, SSH без X11 forwarding и т. п.), Answer42 поднимает два собственных изолированных Xvfb-дисплея: один для test manager и второй для test client. В этом режиме пакет `xvfb` обязателен:
+
+```bash
+# Debian / Ubuntu
+sudo apt install xvfb
+
+# Fedora / RHEL
+sudo dnf install xorg-x11-server-Xvfb
+```
+
+Если не задан ни доступный `DISPLAY`, ни Xvfb, `start_session` завершается до создания ресурсов с понятной подсказкой по установке. Чтобы desktop-сервис видел живой X11, его launcher/service должен передать корректный `DISPLAY` и права доступа к X server (обычно через `XAUTHORITY`).
+
+## Скриншоты: stdio и StreamableHTTP
+
+`screenshot` сохраняет PNG на MCP-хосте и больше не помещает его base64-представление в результат tool-call.
+
+- В **stdio** возвращаются только `path`, размер и диагностические поля. Агентский хост при необходимости прикладывает файл по пути.
+- В **StreamableHTTP** добавляется непрозрачная одноразовая ссылка `url` на PNG. Она действует один час по умолчанию (`ONEC_MCP_SCREENSHOT_URL_TTL_SECONDS`), исчезает после первого скачивания и существует не дольше процесса сервера. Для внешнего reverse proxy укажите публичный base URL через `ONEC_MCP_SCREENSHOT_URL_BASE`.
+
 ## Транспорты: stdio и StreamableHTTP
 
 По умолчанию Answer42 использует stdio MCP transport (запускается MCP-хостом как subprocess). Для удалённого deployment доступен **StreamableHTTP** режим с MCP auth:

{answer42-0.4.97 → answer42-0.4.99}/README.md

@@ -128,6 +128,29 @@ answer42 install-skills --dry-run --agent all
 4. зарегистрируйте MCP-сервер в агентском клиенте;
 5. проверьте установку через `credentials_check`, затем smoke-сессию `start_session` → `active_window` → `stop_session`.
 
+## Linux display prerequisite
+
+На Linux `start_session` использует живую X11-сессию, если процесс Answer42 унаследовал непустой `DISPLAY`: test manager и test client запускаются на этом дисплее, поэтому их окна и скриншоты видны на desktop.
+
+Если `DISPLAY` не задан (headless service, SSH без X11 forwarding и т. п.), Answer42 поднимает два собственных изолированных Xvfb-дисплея: один для test manager и второй для test client. В этом режиме пакет `xvfb` обязателен:
+
+```bash
+# Debian / Ubuntu
+sudo apt install xvfb
+
+# Fedora / RHEL
+sudo dnf install xorg-x11-server-Xvfb
+```
+
+Если не задан ни доступный `DISPLAY`, ни Xvfb, `start_session` завершается до создания ресурсов с понятной подсказкой по установке. Чтобы desktop-сервис видел живой X11, его launcher/service должен передать корректный `DISPLAY` и права доступа к X server (обычно через `XAUTHORITY`).
+
+## Скриншоты: stdio и StreamableHTTP
+
+`screenshot` сохраняет PNG на MCP-хосте и больше не помещает его base64-представление в результат tool-call.
+
+- В **stdio** возвращаются только `path`, размер и диагностические поля. Агентский хост при необходимости прикладывает файл по пути.
+- В **StreamableHTTP** добавляется непрозрачная одноразовая ссылка `url` на PNG. Она действует один час по умолчанию (`ONEC_MCP_SCREENSHOT_URL_TTL_SECONDS`), исчезает после первого скачивания и существует не дольше процесса сервера. Для внешнего reverse proxy укажите публичный base URL через `ONEC_MCP_SCREENSHOT_URL_BASE`.
+
 ## Транспорты: stdio и StreamableHTTP
 
 По умолчанию Answer42 использует stdio MCP transport (запускается MCP-хостом как subprocess). Для удалённого deployment доступен **StreamableHTTP** режим с MCP auth:

{answer42-0.4.97 → answer42-0.4.99}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "answer42"
-version = "0.4.97"
+version = "0.4.99"
 description = "Answer42 — The Answer to Life, Universe, and 1C — UI Driver. MCP-powered 1C:Enterprise UI automation: click, fill, navigate, test, and introspect managed forms through the test-client API"
 readme = "README.md"
 requires-python = ">=3.11"

{answer42-0.4.97 → answer42-0.4.99}/src/mcp_1c/runtime.py

@@ -118,13 +118,56 @@ def find_free_port(start: int = DEFAULT_WS_PORT, end: int | None = None) -> int:
     raise RuntimeError(f"No free port found in range {start}..{end}")
 
 
-def start_xvfb(display: str, resolution: str = DEFAULT_DISPLAY_RES) -> subprocess.Popen:
-    """Start Xvfb for the given display and return the Popen handle."""
+def inherited_x11_display() -> str:
+    """Return the caller's live X11 display, if one was intentionally inherited."""
+    if os_support.IS_WINDOWS:
+        return ""
+    return os.getenv("DISPLAY", "").strip()
+
+
+def require_xvfb() -> str:
+    """Return the Xvfb executable or raise an actionable headless prerequisite error.
+
+    Xvfb is needed only when Answer42 did not inherit a live X11 ``DISPLAY``.
+    """
     if os_support.IS_WINDOWS:
         raise RuntimeError("Xvfb is not available on Windows")
     xvfb_bin = shutil.which("Xvfb") or "/usr/bin/Xvfb"
-    if not Path(xvfb_bin).exists():
-        raise FileNotFoundError("Xvfb not found; install it to run headless sessions")
+    if not Path(xvfb_bin).is_file():
+        raise RuntimeError(
+            "Xvfb is required to start an Answer42 session on Linux when DISPLAY is not set. "
+            "Set DISPLAY to an accessible live X11 session, or install Xvfb for headless operation. "
+            "Install the 'xvfb' package (Debian/Ubuntu: sudo apt install xvfb; Fedora/RHEL: sudo dnf install xorg-x11-server-Xvfb) "
+            "and retry start_session."
+        )
+    return xvfb_bin
+
+
+def session_displays(display_offset: int) -> tuple[str, str, bool]:
+    """Choose inherited desktop display or two Answer42-owned Xvfb displays.
+
+    Returns ``(manager_display, client_display, starts_xvfb)``. A live X11
+    display is deliberately shared by manager and client: it is the caller's
+    explicit request to run visibly on that desktop. Otherwise the historical
+    isolated two-Xvfb setup is retained for headless operation.
+    """
+    desktop_display = inherited_x11_display()
+    if desktop_display:
+        return desktop_display, desktop_display, False
+    if os_support.IS_WINDOWS:
+        return "", "", False
+    require_xvfb()
+    manager_display = find_free_display(DEFAULT_DISPLAY_START + display_offset)
+    # The first X socket does not exist until start_xvfb() is called, so derive
+    # the second search position from the selected number instead of asking the
+    # same free-display scan twice.
+    client_display = find_free_display(int(manager_display.removeprefix(":")) + 1)
+    return manager_display, client_display, True
+
+
+def start_xvfb(display: str, resolution: str = DEFAULT_DISPLAY_RES) -> subprocess.Popen:
+    """Start Xvfb for the given display and return the Popen handle."""
+    xvfb_bin = require_xvfb()
     proc = subprocess.Popen(
         [xvfb_bin, display, "-screen", "0", resolution, "-ac", "+extension", "GLX", "+render", "-noreset"],
         stdout=subprocess.DEVNULL,

{answer42-0.4.97 → answer42-0.4.99}/src/mcp_1c/server.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 import argparse
 import asyncio
-import base64
 import copy
 import hashlib
 import importlib.resources
@@ -29,6 +28,7 @@ from mcp.server import MCPServer
 from mcp.server.lowlevel import NotificationOptions
 from mcp.server.mcpserver.resources import FileResource
 from mcp.server.subscriptions import ToolsListChanged
+from starlette.responses import FileResponse, PlainTextResponse
 
 from . import __version__, os_support, release_helper, runtime, skill_installer
 from . import platform as _platform
@@ -84,6 +84,11 @@ FORM_HINTS_LOCK = os_support.runtime_path("ONEC_MCP_FORM_HINTS_LOCK", "form-hint
 UI_TREE_RESOURCE_AUTO_THRESHOLD_TOKENS = int(os.getenv("ONEC_MCP_UI_TREE_RESOURCE_AUTO_THRESHOLD_TOKENS", "50000"))
 UI_TREE_RESOURCE_AUTO_THRESHOLD_BYTES = int(os.getenv("ONEC_MCP_UI_TREE_RESOURCE_AUTO_THRESHOLD_BYTES", "0"))  # deprecated fallback; 0 disables
 NOTIFY_TOOLS_CHANGED_ON_STARTUP = os.getenv("ONEC_MCP_NOTIFY_TOOLS_CHANGED_ON_STARTUP", "1").strip().lower() not in {"0", "false", "no", "off"}
+SCREENSHOT_URL_TTL_SECONDS = max(1, int(os.getenv("ONEC_MCP_SCREENSHOT_URL_TTL_SECONDS", "3600")))
+# Set only in StreamableHTTP mode.  stdio deliberately returns filesystem paths
+# and never serializes screenshot bytes into an MCP tool response.
+_SCREENSHOT_URL_BASE = ""
+_SCREENSHOT_URLS: dict[str, tuple[Path, float]] = {}
 
 
 def _float_env(names: str | tuple[str, ...], default: float) -> float:
@@ -5210,11 +5215,18 @@ async def start_session(
     if sid in _SESSIONS:
         raise ValueError(f"Session {sid!r} already exists.")
 
+    # A caller that inherited DISPLAY explicitly requests visible automation
+    # on that live X11 session. In a headless process, retain two private Xvfb
+    # displays and validate the prerequisite before allocating session state.
+    inherited_display = runtime.inherited_x11_display()
+    if not os_support.IS_WINDOWS and not inherited_display:
+        runtime.require_xvfb()
+
     data_dir = os_support.default_data_dir() / "sessions" / sid
     with _port_allocation_lock():
         port_offset = _stable_session_port_offset(sid)
         display_offset = port_offset // _PORT_BAND_SIZE
-        display = "" if os_support.IS_WINDOWS else runtime.find_free_display(runtime.DEFAULT_DISPLAY_START + display_offset)
+        display, client_display, starts_xvfb = runtime.session_displays(display_offset)
         ws_port = _find_session_port(runtime.DEFAULT_WS_PORT, port_offset, sub_offset=0)
         ibsrv_port = _find_session_port(runtime.DEFAULT_IBSRV_HTTP_PORT, port_offset, sub_offset=0)
         ibsrv_direct_regport = _find_session_port(runtime.DEFAULT_IBSRV_DIRECT_PORT, port_offset, sub_offset=0)
@@ -5244,13 +5256,10 @@ async def start_session(
             bound_snapshot = _snapshot_for_base_url(base_url)
             if bound_snapshot:
                 sess.rag_snapshot = bound_snapshot
-        if display:
+        sess.client_display = client_display
+        if starts_xvfb:
             sess.xvfb_process = runtime.start_xvfb(display)
             sess.xvfb_pid = sess.xvfb_process.pid
-        # Separate display for the test client so screenshots capture only the client window
-        client_display = "" if os_support.IS_WINDOWS else runtime.find_free_display(runtime.DEFAULT_DISPLAY_START + display_offset + 1)
-        sess.client_display = client_display
-        if client_display:
             sess.client_xvfb_process = runtime.start_xvfb(client_display)
             sess.client_xvfb_pid = sess.client_xvfb_process.pid
         await sess.bridge.start()
@@ -10972,6 +10981,42 @@ async def _dev_eval(
     return await _bridge_call_recorded(session_id, "dev_eval", {"code": code})
 
 
+def _prune_expired_screenshot_urls(now: float | None = None) -> None:
+    now = time.time() if now is None else now
+    for token, (_, expires_at) in list(_SCREENSHOT_URLS.items()):
+        if expires_at <= now:
+            _SCREENSHOT_URLS.pop(token, None)
+
+
+@mcp.custom_route("/_answer42/screenshots/{token}", methods=["GET"], include_in_schema=False)
+async def _download_screenshot(request: Any) -> Any:
+    """Serve a single-use opaque StreamableHTTP screenshot link."""
+    token = str(request.path_params.get("token") or "")
+    _prune_expired_screenshot_urls()
+    entry = _SCREENSHOT_URLS.pop(token, None)
+    if entry is None:
+        return PlainTextResponse("Screenshot link is expired or unavailable.", status_code=404)
+    image_path, expires_at = entry
+    if expires_at <= time.time() or not image_path.is_file():
+        return PlainTextResponse("Screenshot link is expired or unavailable.", status_code=404)
+    return FileResponse(image_path, media_type="image/png", filename=image_path.name)
+
+
+def _register_screenshot_url(path: Path) -> dict[str, Any] | None:
+    """Expose an opaque, time-limited screenshot URL in StreamableHTTP mode."""
+    if not _SCREENSHOT_URL_BASE:
+        return None
+    _prune_expired_screenshot_urls()
+    token = uuid.uuid4().hex + uuid.uuid4().hex
+    expires_at = time.time() + SCREENSHOT_URL_TTL_SECONDS
+    _SCREENSHOT_URLS[token] = (path.resolve(), expires_at)
+    return {
+        "url": f"{_SCREENSHOT_URL_BASE}/_answer42/screenshots/{token}",
+        "url_expires_at": datetime.fromtimestamp(expires_at, UTC).isoformat(),
+        "url_ttl_seconds": SCREENSHOT_URL_TTL_SECONDS,
+    }
+
+
 @mcp.tool()
 def screenshot(
     path: Annotated[str, "Output image path"] = "build/screenshots/screenshot.png",
@@ -10982,6 +11027,9 @@ def screenshot(
 ) -> dict[str, Any]:
     """Capture a screenshot from the MCP host. Defaults to the active visible 1C window.
 
+    The response always contains the saved path, never image base64. In
+    StreamableHTTP mode it additionally contains an opaque download URL that
+    expires after one hour by default (``ONEC_MCP_SCREENSHOT_URL_TTL_SECONDS``).
     Screenshots are for user evidence and UI diagnostics only. Do not use them
     to analyze report/table/tabular-document/list data; use structured tools
     such as tabular_document_text, tabular_documents, table_rows,
@@ -11040,7 +11088,8 @@ def screenshot(
         ) from exc
 
     data = output_path.read_bytes()
-    result = {"path": str(output_path), "bytes": len(data), "base64": base64.b64encode(data).decode("ascii")}
+    result: dict[str, Any] = {"path": str(output_path), "bytes": len(data)}
+    result.update(_register_screenshot_url(output_path) or {})
     if window:
         result["window_geometry"] = geometry
     if fallback:
@@ -11103,6 +11152,13 @@ async def _run_http(args: argparse.Namespace) -> None:
         stateless_http=args.http_stateless,
         host=args.http_host,
     )
+
+    # Image data is not placed into MCP tool results. The custom route is
+    # registered at module load because the MCP SDK builds the Starlette app
+    # from its custom-route list. The opaque token makes the URL unguessable;
+    # the short lifetime and single use bound access.
+    global _SCREENSHOT_URL_BASE
+    _SCREENSHOT_URL_BASE = (args.http_public_base_url or f"http://{args.http_host}:{args.http_port}").rstrip("/")
     config_uvicorn = uvicorn.Config(
         app,
         host=args.http_host,
@@ -11114,6 +11170,8 @@ async def _run_http(args: argparse.Namespace) -> None:
     try:
         await server.serve()
     finally:
+        _SCREENSHOT_URLS.clear()
+        _SCREENSHOT_URL_BASE = ""
         if tools_changed_task is not None:
             tools_changed_task.cancel()
             with suppress(asyncio.CancelledError):
@@ -11329,6 +11387,11 @@ def main(argv: list[str] | None = None) -> None:
         default=int(os.getenv("ONEC_MCP_HTTP_PORT", "8080")),
         help="port to bind the StreamableHTTP server to",
     )
+    parser.add_argument(
+        "--http-public-base-url",
+        default=os.getenv("ONEC_MCP_SCREENSHOT_URL_BASE", ""),
+        help="public base URL used in temporary StreamableHTTP screenshot links; useful behind a reverse proxy",
+    )
     parser.add_argument(
         "--http-token",
         default=os.getenv("ONEC_MCP_HTTP_TOKEN", ""),