vis-agent 0.2.47.dev7678__tar.gz → 0.2.48.dev7720__tar.gz

{vis_agent-0.2.47.dev7678 → vis_agent-0.2.48.dev7720}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vis-agent
-Version: 0.2.47.dev7678
+Version: 0.2.48.dev7720
 Summary: The Vis Python SDK — author extensions and control local or remote engines.
 Project-URL: Homepage, https://vis.blockether.com
 Project-URL: Documentation, https://vis.blockether.com
@@ -28,15 +28,18 @@ Description-Content-Type: text/markdown
 
 # vis-agent
 
-Python SDK for Vis extensions and agent sessions.
+Python SDK for Vis agent sessions and extensions.
 
 ```sh
 pip install vis-agent
 ```
 
-Requires Python 3.12+. Install the Vis executable and configure a provider
-separately for local use. The execution-layer API below is unreleased: build
-the SDK and engine from the same source revision.
+You need Python 3.12+ on Linux or macOS and a configured model provider. You do not
+have to install Vis first. A local run uses the installed `vis-agent` only when it is
+the same release as the SDK. Otherwise the SDK downloads only that release's engine into
+`~/.vis/sdk` and checks it against the release checksums. Set `VIS_NO_AUTO_INSTALL=1` to
+turn this off. To download the engine ahead of time, for example in a container image, run
+`python -c "from blockether.vis.engine import install; print(install())"`.
 
 ## Run a local agent
 
@@ -48,18 +51,16 @@ with Agent(project=".") as agent:
     print(result["status"])
 ```
 
-The SDK starts an owned `vis-agent stdio` process, sets up a temporary session
-database and cleans it up on close. This is a Python transport, not an
-interactive CLI command or an MCP server. Tasks can incur provider charges and
-access project files. For a chosen executable or multiple sessions on one
-process, use `LocalEngine`; see the [stdio guide](https://vis.blockether.com/python-sdk.html#use-stdio-from-the-python-sdk).
+The SDK starts a private Vis process with a temporary session database and removes both
+when the block ends. Tasks can incur provider charges and can change project files. To
+choose the executable or share one process between agents, use `LocalEngine`. See the
+[stdio guide](https://vis.blockether.com/python-sdk.html#use-stdio-from-the-python-sdk).
 
 - [Python SDK guide](https://vis.blockether.com/python-sdk.html) — run a local
-  agent, continue a conversation or connect to a shared gateway. `Agent` is
-  available in SDK `0.2.3` and newer.
-- [Decision models](https://vis.blockether.com/decision-models.html) — download
-  Laya or GLiNER2.5, train both heads offline, publish FP32 and select a version.
+  agent, continue a conversation or connect to a shared gateway.
 - [Python API reference](https://vis.blockether.com/python-sdk-api/) — browse
   classes, methods, signatures and types generated from the SDK source.
 - [Extension guide](https://vis.blockether.com/extending.html) — add tools to Vis.
+- [Decision models](https://vis.blockether.com/decision-models.html) — download
+  Laya or GLiNER2.5, train both heads offline, publish FP32 and select a version.
 - [Documentation](https://vis.blockether.com) — browse all guides and reference pages.

vis_agent-0.2.48.dev7720/README.md

@@ -0,0 +1,38 @@
+# vis-agent
+
+Python SDK for Vis agent sessions and extensions.
+
+```sh
+pip install vis-agent
+```
+
+You need Python 3.12+ on Linux or macOS and a configured model provider. You do not
+have to install Vis first. A local run uses the installed `vis-agent` only when it is
+the same release as the SDK. Otherwise the SDK downloads only that release's engine into
+`~/.vis/sdk` and checks it against the release checksums. Set `VIS_NO_AUTO_INSTALL=1` to
+turn this off. To download the engine ahead of time, for example in a container image, run
+`python -c "from blockether.vis.engine import install; print(install())"`.
+
+## Run a local agent
+
+```python
+from blockether.vis.engine import Agent
+
+with Agent(project=".") as agent:
+    result = agent.run("Summarize this project without changing files.")
+    print(result["status"])
+```
+
+The SDK starts a private Vis process with a temporary session database and removes both
+when the block ends. Tasks can incur provider charges and can change project files. To
+choose the executable or share one process between agents, use `LocalEngine`. See the
+[stdio guide](https://vis.blockether.com/python-sdk.html#use-stdio-from-the-python-sdk).
+
+- [Python SDK guide](https://vis.blockether.com/python-sdk.html) — run a local
+  agent, continue a conversation or connect to a shared gateway.
+- [Python API reference](https://vis.blockether.com/python-sdk-api/) — browse
+  classes, methods, signatures and types generated from the SDK source.
+- [Extension guide](https://vis.blockether.com/extending.html) — add tools to Vis.
+- [Decision models](https://vis.blockether.com/decision-models.html) — download
+  Laya or GLiNER2.5, train both heads offline, publish FP32 and select a version.
+- [Documentation](https://vis.blockether.com) — browse all guides and reference pages.

{vis_agent-0.2.47.dev7678 → vis_agent-0.2.48.dev7720}/contracts/schema/agents.json

@@ -27,7 +27,7 @@
           "type": "integer",
           "minimum": 1,
           "maximum": 600,
-          "default": 64
+          "default": 120
         },
         "allowed_models": {
           "type": "array",
@@ -80,6 +80,62 @@
       ],
       "additionalProperties": false
     },
+    "extend": {
+      "type": "object",
+      "properties": {
+        "session_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "iterations": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 600
+        }
+      },
+      "required": [
+        "session_id",
+        "iterations"
+      ],
+      "additionalProperties": false
+    },
+    "deny": {
+      "type": "object",
+      "properties": {
+        "session_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2000,
+          "pattern": "\\S"
+        }
+      },
+      "required": [
+        "session_id",
+        "reason"
+      ],
+      "additionalProperties": false
+    },
+    "resume": {
+      "type": "object",
+      "properties": {
+        "session_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "task": {
+          "$ref": "#/$defs/spawn/properties/task"
+        }
+      },
+      "required": [
+        "session_id",
+        "task"
+      ],
+      "additionalProperties": false
+    },
     "route": {
       "type": "object",
       "properties": {

{vis_agent-0.2.47.dev7678 → vis_agent-0.2.48.dev7720}/contracts/schema/gateway.json

@@ -1226,6 +1226,16 @@
       },
       "path": "/v1/sessions/:sid/workspace/root"
     },
+    {
+      "audience": "sdk",
+      "operations": {
+        "post": {
+          "request": "json",
+          "response": "json"
+        }
+      },
+      "path": "/v1/sessions/actions/archive"
+    },
     {
       "audience": "sdk",
       "operations": {
@@ -2383,6 +2393,9 @@
         {
           "const": "session.agent_name_updated"
         },
+        {
+          "const": "session.created"
+        },
         {
           "const": "session.deleted"
         },

vis_agent-0.2.48.dev7720/hatch_build.py

@@ -0,0 +1,45 @@
+"""Bundle the canonical contracts and the release tag of the matching Vis engine."""
+
+import os
+import re
+import tempfile
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+# A beta SDK (X.Y.Z.devN) cannot name its engine from its version, so CI records it.
+_TAG = re.compile(r"^(v\d+\.\d+\.\d+|beta-[0-9a-f]{40})$")
+
+
+class ContractResources(BuildHookInterface):
+    def initialize(self, version, build_data):
+        root = Path(self.root)
+        source = root / "contracts"
+        if not source.is_dir():
+            source = root.parent / "vis-contract/resources/vis-contract"
+        if not source.is_dir():
+            raise FileNotFoundError("canonical Vis contract resources are missing")
+        destination = (
+            "blockether/vis/_data" if self.target_name == "wheel" else "contracts"
+        )
+        build_data["force_include"][str(source)] = destination
+        self._release_tag(root, build_data)
+
+    def _release_tag(self, root, build_data):
+        """Record VIS_SDK_RELEASE_TAG, or the tag of the sdist this wheel comes from."""
+        tag = os.environ.get("VIS_SDK_RELEASE_TAG", "").strip()
+        recorded = root / "release-tag"
+        if not tag and recorded.is_file():
+            tag = recorded.read_text(encoding="utf-8").strip()
+        if not tag:
+            return
+        if not _TAG.match(tag):
+            raise ValueError(f"VIS_SDK_RELEASE_TAG={tag!r} is not vX.Y.Z or beta-<sha>")
+        written = Path(tempfile.mkdtemp(prefix="vis-sdk-tag-")) / "release-tag"
+        written.write_text(f"{tag}\n", encoding="utf-8")
+        destination = (
+            "blockether/vis/engine/release-tag"
+            if self.target_name == "wheel"
+            else "release-tag"
+        )
+        build_data["force_include"][str(written)] = destination

{vis_agent-0.2.47.dev7678 → vis_agent-0.2.48.dev7720}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vis-agent"
-version = "0.2.47.dev7678"
+version = "0.2.48.dev7720"
 description = "The Vis Python SDK — author extensions and control local or remote engines."
 readme = "README.md"
 requires-python = ">=3.12"

vis_agent-0.2.48.dev7720/release-tag

@@ -0,0 +1 @@
+beta-d22c87384575cfb0253119e1ad26ab78060d0305

{vis_agent-0.2.47.dev7678 → vis_agent-0.2.48.dev7720}/src/blockether/vis/engine/__init__.py

@@ -33,6 +33,7 @@ from ._council import (
     CouncilSource,
     CouncilThread,
 )
+from ._install import InstallError, ensure_installed, install
 from ._local import LocalEngine
 
 __all__ = [
@@ -51,6 +52,7 @@ __all__ = [
     "ExecutionLayer",
     "GatewayClient",
     "GatewayError",
+    "InstallError",
     "JobEvent",
     "JobEvents",
     "JSONValue",
@@ -63,4 +65,6 @@ __all__ = [
     "TransportError",
     "Turn",
     "VisTimeout",
+    "ensure_installed",
+    "install",
 ]

{vis_agent-0.2.47.dev7678 → vis_agent-0.2.48.dev7720}/src/blockether/vis/engine/_client.py

@@ -2183,6 +2183,24 @@ class ExecutionLayer(ABC):
         )
         return response.json()
 
+    def post_sessions_archive(
+        self,
+        *,
+        query: Query | None = None,
+        timeout: float | None = None,
+        body: JSONValue = None,
+    ) -> JSONValue:
+        """POST /v1/sessions/actions/archive — archive many sessions; skip working ones."""
+        response = self._request(
+            "POST",
+            "/v1/sessions/actions/archive",
+            path={},
+            query=query,
+            timeout=timeout,
+            body=body,
+        )
+        return response.json()
+
     def get_sessions_search(
         self, *, query: Query | None = None, timeout: float | None = None
     ) -> JSONValue:

vis_agent-0.2.48.dev7720/src/blockether/vis/engine/_install.py

@@ -0,0 +1,315 @@
+"""Install the Vis engine that matches this SDK.
+
+`ensure_installed()` returns the `vis-agent` command for this SDK. It uses an
+installed Vis only when that build is the same release as the SDK. Otherwise it
+downloads the release once into `$VIS_HOME/sdk/<tag>`. `install()` makes that
+download now, for example while you build a container image.
+
+The download is the engine bundle of one platform: the `vis-agent` launcher, the
+native engine and its Python runtime. It has no terminal client, web app or desktop
+app. The SDK checks the archive against the release `SHA256SUMS` and the build stamp
+against the release tag. It does not change shell profiles, the installed track or a
+running gateway. Set `VIS_NO_AUTO_INSTALL=1` to turn off the automatic download.
+"""
+
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import importlib.metadata
+import importlib.resources
+import json
+import os
+import platform
+import re
+import shutil
+import sys
+import tarfile
+import tempfile
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+_COMMAND = "vis-agent"
+_NATIVE = "vis-agent-native"
+# A launcher with this file beside it always runs the native engine beside it.
+_PINNED = "vis-agent.pinned"
+_RELEASE = re.compile(r"^\d+\.\d+\.\d+$")
+_STABLE = re.compile(r"^v\d+\.\d+\.\d+$")
+_TAG = re.compile(r"^(v\d+\.\d+\.\d+|beta-[0-9a-f]{40})$")
+_OFF = {"1", "true", "yes", "on"}
+_CHUNK = 1 << 20
+# Each network read must progress within this time; the engine bundle is large.
+_READ_TIMEOUT = 120
+
+
+class InstallError(RuntimeError):
+    """The SDK could not find or download the Vis engine."""
+
+
+def _repository() -> str:
+    return os.environ.get("VIS_REPO_SLUG") or "Blockether/vis"
+
+
+def _vis_home() -> Path:
+    return Path(os.environ.get("VIS_HOME") or Path.home() / ".vis")
+
+
+def _cache_root() -> Path:
+    return _vis_home() / "sdk"
+
+
+def _embedded_tag() -> str | None:
+    """Return the release tag that the wheel build recorded, if any."""
+    try:
+        text = (
+            importlib.resources.files("blockether.vis.engine")
+            .joinpath("release-tag")
+            .read_text(encoding="utf-8")
+        )
+    except (OSError, ModuleNotFoundError):
+        return None
+    tag = text.strip()
+    return tag if _TAG.match(tag) else None
+
+
+def _editable(distribution: importlib.metadata.Distribution) -> bool:
+    try:
+        url = json.loads(distribution.read_text("direct_url.json") or "{}")
+    except ValueError:
+        return False
+    return bool(url.get("dir_info", {}).get("editable"))
+
+
+def _sdk_tag() -> str | None:
+    """Return the release tag of this SDK, or None for a development build.
+
+    A release SDK `X.Y.Z` uses `vX.Y.Z`. A beta SDK `X.Y.Z.devN` uses the
+    `beta-<sha>` tag that its wheel build recorded. An editable checkout is a
+    development build.
+    """
+    try:
+        distribution = importlib.metadata.distribution("vis-agent")
+    except importlib.metadata.PackageNotFoundError:
+        return None
+    if _editable(distribution):
+        return None
+    version = distribution.version
+    if _RELEASE.match(version):
+        return f"v{version}"
+    return _embedded_tag()
+
+
+def _open(url: str):
+    return urllib.request.urlopen(url, timeout=_READ_TIMEOUT)
+
+
+def _fetch(url: str) -> bytes:
+    with _open(url) as response:
+        return response.read()
+
+
+def _fetch_file(url: str, target: Path) -> str:
+    """Stream `url` into `target` and return its SHA-256."""
+    digest = hashlib.sha256()
+    with _open(url) as response, open(target, "wb") as output:
+        while chunk := response.read(_CHUNK):
+            digest.update(chunk)
+            output.write(chunk)
+    return digest.hexdigest()
+
+
+def _latest_tag() -> str:
+    url = f"https://github.com/{_repository()}/releases/latest"
+    with _open(url) as response:
+        tag = response.geturl().rstrip("/").rsplit("/", 1)[-1]
+    if not _STABLE.match(tag):
+        raise InstallError(f"could not find the latest Vis release at {url}")
+    return tag
+
+
+def _expected_hash(sums: bytes, name: str) -> str:
+    for line in sums.decode("utf-8", "replace").splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[1].lstrip("*") == name:
+            return parts[0].lower()
+    raise InstallError(f"SHA256SUMS has no entry for {name}")
+
+
+def _platform_asset() -> str:
+    """Return the engine bundle name for this computer."""
+    machine = platform.machine().lower()
+    if sys.platform == "darwin" and machine == "arm64":
+        return "vis-agent-macos-arm64.tar.gz"
+    if sys.platform == "linux" and machine in ("x86_64", "amd64"):
+        return "vis-agent-linux-x64.tar.gz"
+    if sys.platform == "linux" and machine in ("aarch64", "arm64"):
+        return "vis-agent-linux-arm64.tar.gz"
+    raise InstallError(
+        f"Vis has no engine for {sys.platform} {machine}. "
+        "Use Linux (x64 or arm64) or macOS on Apple silicon."
+    )
+
+
+def _stamp_matches(stamp: Path, tag: str) -> bool:
+    """True when the build stamp `version commit track …` is the build of `tag`."""
+    try:
+        fields = stamp.read_text(encoding="utf-8").split()
+    except OSError:
+        return False
+    if len(fields) < 3:
+        return False
+    version, commit, track = fields[:3]
+    if tag.startswith("beta-"):
+        return track == "beta" and commit == tag.removeprefix("beta-")
+    return track == "release" and version == tag.removeprefix("v")
+
+
+def _executable(path: Path) -> bool:
+    return path.is_file() and os.access(path, os.X_OK)
+
+
+def _complete(directory: Path, tag: str) -> bool:
+    return (
+        _executable(directory / _COMMAND)
+        and _executable(directory / _NATIVE)
+        and (directory / _PINNED).is_file()
+        and (directory / "vis-agent-python" / "python").is_dir()
+        and _stamp_matches(directory / f"{_NATIVE}.build", tag)
+    )
+
+
+def _installed() -> str | None:
+    found = shutil.which(_COMMAND)
+    if found:
+        return found
+    candidate = Path.home() / ".local/bin" / _COMMAND
+    return str(candidate) if _executable(candidate) else None
+
+
+def _installed_matches(command: str, tag: str) -> bool:
+    """True when the launcher `command` runs the native build of `tag`.
+
+    This follows the launcher: a pinned bundle runs the engine beside it, the `dev`
+    track runs source, and otherwise the engine beside the launcher wins over the
+    one in `$VIS_HOME/install`.
+    """
+    bin_dir = Path(command).resolve().parent
+    install_dir = _vis_home() / "install"
+    bundled = bin_dir / _NATIVE
+    if not ((bin_dir / _PINNED).is_file() and _executable(bundled)):
+        try:
+            track = (install_dir / "track").read_text(encoding="utf-8").strip()
+        except OSError:
+            track = ""
+        if track == "dev":
+            return False
+    for native in (bundled, install_dir / _NATIVE):
+        if _executable(native):
+            return _stamp_matches(native.with_name(f"{_NATIVE}.build"), tag)
+    return False
+
+
+def _check_bundle(directory: Path, tag: str) -> None:
+    missing = [
+        name for name in (_COMMAND, _NATIVE) if not _executable(directory / name)
+    ]
+    python = directory / "vis-agent-python"
+    if not (python / "python").is_dir() or not list(python.glob("libvispython.*")):
+        missing.append("vis-agent-python")
+    if missing:
+        raise InstallError(f"the Vis {tag} bundle has no {', '.join(missing)}")
+    if not _stamp_matches(directory / f"{_NATIVE}.build", tag):
+        raise InstallError(
+            f"the Vis {tag} bundle has the build stamp of another release"
+        )
+
+
+def _download(tag: str, directory: Path) -> None:
+    """Download, check and unpack the engine bundle of `tag` into `directory`."""
+    asset = _platform_asset()
+    base = f"https://github.com/{_repository()}/releases/download/{tag}"
+    expected = _expected_hash(_fetch(f"{base}/SHA256SUMS"), asset)
+    with tempfile.TemporaryDirectory(dir=directory.parent, prefix=f".{tag}-") as work:
+        archive = Path(work) / asset
+        if _fetch_file(f"{base}/{asset}", archive) != expected:
+            raise InstallError(f"the {asset} of {tag} does not match SHA256SUMS")
+        bundle = Path(work) / "bundle"
+        with tarfile.open(archive) as tar:
+            tar.extractall(bundle, filter="data")
+        _check_bundle(bundle, tag)
+        (bundle / _PINNED).write_text(f"{tag}\n", encoding="utf-8")
+        if directory.exists():
+            shutil.rmtree(directory)
+        bundle.replace(directory)
+
+
+def _download_once(tag: str, *, force: bool = False) -> str:
+    root = _cache_root()
+    directory = root / tag
+    root.mkdir(parents=True, exist_ok=True)
+    with open(root / f"{tag}.lock", "w") as lock:
+        # A second process waits here and then uses the finished download.
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        if force or not _complete(directory, tag):
+            print(f"vis-agent: downloading Vis {tag} into {directory}", file=sys.stderr)
+            try:
+                _download(tag, directory)
+            except urllib.error.HTTPError as error:
+                if error.code == 404:
+                    raise InstallError(
+                        f"Vis {tag} has no engine at {error.url}. "
+                        "Install the SDK version of a published Vis release."
+                    ) from None
+                raise InstallError(f"could not download Vis {tag}: {error}") from None
+            except (OSError, tarfile.TarError) as error:
+                raise InstallError(f"could not download Vis {tag}: {error}") from None
+    return str(directory / _COMMAND)
+
+
+def install(*, force: bool = False) -> str:
+    """Download the Vis engine of this SDK now and return its `vis-agent` path.
+
+    Use it to prepare a computer or a container image before the first run. It
+    downloads into `$VIS_HOME/sdk/<tag>` even when another Vis is installed, and
+    reuses a complete download unless `force` is true. A development build of the
+    SDK installs the latest stable release. `VIS_NO_AUTO_INSTALL` does not apply.
+
+    Raises:
+        InstallError: The platform has no engine, the release has no bundle, or the
+            download fails its checks.
+    """
+    return _download_once(_sdk_tag() or _latest_tag(), force=force)
+
+
+def ensure_installed() -> str:
+    """Return the `vis-agent` command that matches this SDK, and download it when missing.
+
+    An installed `vis-agent` is used only when it runs the same release as the SDK.
+    Otherwise the SDK uses, or downloads, its own copy in `$VIS_HOME/sdk/<tag>`. A
+    development build of the SDK uses any installed command, or the latest stable
+    release.
+
+    Raises:
+        InstallError: The download is turned off with `VIS_NO_AUTO_INSTALL`, or
+            `install()` fails.
+    """
+    tag = _sdk_tag()
+    installed = _installed()
+    if tag is None and installed:
+        return installed
+    if tag is not None:
+        if installed and _installed_matches(installed, tag):
+            return installed
+        if _complete(_cache_root() / tag, tag):
+            return str(_cache_root() / tag / _COMMAND)
+    if (os.environ.get("VIS_NO_AUTO_INSTALL") or "").strip().lower() in _OFF:
+        wanted = f"Vis {tag}" if tag else f"the {_COMMAND} command"
+        raise InstallError(
+            f"{wanted} is not installed, and VIS_NO_AUTO_INSTALL turns off the "
+            "download. Install it, call install(), or pass executable=..."
+        )
+    try:
+        return install()
+    except OSError as error:
+        raise InstallError(f"could not download Vis: {error}") from None

{vis_agent-0.2.47.dev7678 → vis_agent-0.2.48.dev7720}/src/blockether/vis/engine/_local.py

@@ -1,8 +1,9 @@
 """Owned local Vis subprocess, with the same session API and no HTTP listener.
 
-You select the executable explicitly. There is no download, gateway discovery or
-user-server shutdown. Each engine gets a temporary database and stderr log, and closing
-discards them.
+Pass an executable, or keep the default `vis-agent`. The default runs the engine of
+this SDK's release (see `ensure_installed`). There is no gateway discovery or
+user-server shutdown. Each engine gets a temporary database and stderr log, and
+closing discards them.
 Supports Linux and macOS. Instances use one calling thread, like GatewayClient.
 """
 
@@ -34,6 +35,7 @@ from ._client import (
     _PollingEvents,
     _SessionPollingEvents,
 )
+from ._install import _COMMAND, InstallError, ensure_installed
 
 # Errors quote at most this much of the engine's stderr, starting at a line.
 _STDERR_TAIL = 4096
@@ -52,9 +54,12 @@ class LocalEngine(ExecutionLayer):
     """Own a private Vis process without starting an HTTP server.
 
     Use this layer when you need to choose an executable, share one local process
-    between agents, or call the session API directly. The Vis executable must be
-    installed separately. This class never downloads it or discovers a gateway.
-    Supported platforms are Linux and macOS.
+    between agents, or call the session API directly. With the default `vis-agent`,
+    `connect` uses the installed command when it runs this SDK's release. Otherwise it
+    downloads that release once into `$VIS_HOME/sdk` and checks it against the release
+    checksums.
+    Set `VIS_NO_AUTO_INSTALL=1` to turn off the download. This class never discovers
+    a gateway. Supported platforms are Linux and macOS.
 
     Args:
         executable: Executable path/name or nonempty argument sequence. The SDK
@@ -160,6 +165,12 @@ class LocalEngine(ExecutionLayer):
             raise TransportError("client is closed")
         if self._process is not None:
             return self
+        if self._command == [_COMMAND]:
+            try:
+                self._command = [ensure_installed()]
+            except InstallError as error:
+                self.close()
+                raise TransportError(f"could not start local engine: {error}") from None
         self._home = tempfile.TemporaryDirectory(prefix="vis-sdk-")
         env = {
             **os.environ,