geny-executor 2.48.2__tar.gz → 2.49.0__tar.gz

{geny_executor-2.48.2 → geny_executor-2.49.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: geny-executor
-Version: 2.48.2
+Version: 2.49.0
 Summary: Harness-engineered agent pipeline library with 21-stage dual-abstraction architecture, built on the Anthropic API
 Project-URL: Homepage, https://github.com/CocoRoF/geny-executor
 Project-URL: Repository, https://github.com/CocoRoF/geny-executor
@@ -40,6 +40,7 @@ Requires-Dist: websockets>=12.0
 Provides-Extra: browser
 Requires-Dist: an-web>=0.9.1; (python_version >= '3.12') and extra == 'browser'
 Provides-Extra: dev
+Requires-Dist: asyncssh>=2.14; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
@@ -49,6 +50,8 @@ Provides-Extra: docs
 Requires-Dist: edit2docs>=0.6.0; extra == 'docs'
 Provides-Extra: qdrant
 Requires-Dist: qdrant-client>=1.12.0; extra == 'qdrant'
+Provides-Extra: ssh
+Requires-Dist: asyncssh>=2.14; extra == 'ssh'
 Description-Content-Type: text/markdown
 
 # geny-executor

{geny_executor-2.48.2 → geny_executor-2.49.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "geny-executor"
-version = "2.48.2"
+version = "2.49.0"
 description = "Harness-engineered agent pipeline library with 21-stage dual-abstraction architecture, built on the Anthropic API"
 readme = "README.md"
 license = "Apache-2.0"
@@ -87,12 +87,18 @@ browser = [
 docs = [
     "edit2docs>=0.6.0",
 ]
+# Ssh* built-ins — remote command/SFTP over SSH. Pure-async (asyncssh),
+# lazy-imported so the core install stays lean.
+ssh = [
+    "asyncssh>=2.14",
+]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.24",
     "pytest-cov>=5.0",
     "ruff>=0.4.0",
     "mypy>=1.10",
+    "asyncssh>=2.14",
 ]
 
 [project.urls]

{geny_executor-2.48.2 → geny_executor-2.49.0}/src/geny_executor/memory/embedding/client.py

@@ -34,9 +34,10 @@ re-attempted the call and logged a full traceback, forever.
 
 from __future__ import annotations
 
+import asyncio
 import logging
 import os
-from typing import List, Protocol, Sequence, runtime_checkable
+from typing import List, Optional, Protocol, Sequence, runtime_checkable
 
 from geny_executor.memory.provider import CostEvent, EmbeddingDescriptor
 
@@ -148,6 +149,93 @@ def _resolve_env_api_key(provider: str, *env_vars: str) -> str:
     return ""
 
 
+class _LoopBoundClientMixin:
+    """Loop-safe caching for httpx-backed embedding SDK clients.
+
+    An httpx-based SDK client (``AsyncOpenAI``, ``genai.Client``) binds its
+    transport/connection-pool to the event loop that first drives it and
+    cannot be reused from another loop — a later call on a different loop
+    raises ``RuntimeError: Event loop is closed`` / "Future attached to a
+    different loop". Hosts that drive memory writes through a sync→async
+    bridge (Geny's ``run_coro_sync``) spin a fresh, short-lived event loop
+    **per call**, so a single cached client would (a) fail cross-loop on
+    every bridged embed and (b), never being closed, leak its socket pool
+    once per session.
+
+    Strategy:
+      * Cache ONE client on the loop that first uses it — almost always the
+        stable server loop, where the vast majority of embeds happen
+        (search, the memory stage). That loop's calls reuse it, so
+        connection pooling is preserved.
+      * If the cached client's loop is found dead, drop the reference (its
+        transport is finalized by GC) and rebind to the current loop. An
+        all-bridge caller (only ever ephemeral loops) therefore rebinds
+        each call instead of accumulating clients.
+      * Any OTHER still-live loop gets a short-lived client that the caller
+        closes within the same call (``ephemeral=True``) — never drive one
+        client's transport from two loops.
+
+    Subclasses set ``self._client`` / ``self._client_loop`` /
+    ``self._injected_client`` in ``__init__`` and implement
+    ``_build_client()``. A test-injected client (``_injected_client``) is
+    used verbatim and never rebuilt or auto-closed — the caller owns it.
+    """
+
+    _client: Optional[object] = None
+    _client_loop: Optional[asyncio.AbstractEventLoop] = None
+    _injected_client: bool = False
+
+    def _build_client(self) -> object:
+        raise NotImplementedError
+
+    def _acquire_client(self):
+        """Return ``(client, ephemeral)`` bound to the CURRENT running loop.
+
+        ``ephemeral`` clients MUST be closed by the caller (see
+        ``_aclose_client``) before the coroutine returns.
+        """
+        if self._injected_client:
+            return self._client, False
+        loop = asyncio.get_running_loop()
+        cached = self._client
+        if cached is not None:
+            if self._client_loop is loop and not loop.is_closed():
+                return cached, False  # hot path: pooled client on its loop
+            if self._client_loop is None or self._client_loop.is_closed():
+                # Cached loop is dead — drop so GC finalizes its transport,
+                # then rebind to this loop below.
+                self._client = None
+                self._client_loop = None
+                cached = None
+        if cached is None:
+            self._client = self._build_client()
+            self._client_loop = loop
+            return self._client, False
+        # Cache valid but bound to a different, still-live loop → ephemeral.
+        return self._build_client(), True
+
+    async def _aclose_client(self, client: object) -> None:
+        closer = getattr(client, "close", None)
+        if closer is None:
+            return
+        try:
+            result = closer()
+            if asyncio.iscoroutine(result):
+                await result
+        except Exception:  # noqa: BLE001 — close is best-effort
+            logger.debug("embedding client close failed", exc_info=True)
+
+    async def _close_cached_client(self) -> None:
+        """Release the cached client (``close()`` surface). No-op for an
+        injected client — its lifetime belongs to the caller."""
+        client = self._client
+        self._client = None
+        self._client_loop = None
+        if client is None or self._injected_client:
+            return
+        await self._aclose_client(client)
+
+
 __all__ = [
     "EmbeddingClient",
     "EmbeddingError",

{geny_executor-2.48.2 → geny_executor-2.49.0}/src/geny_executor/memory/embedding/google.py

@@ -15,6 +15,7 @@ from typing import Any, List, Optional, Sequence
 from geny_executor.memory.embedding.client import (
     EmbeddingClient,
     EmbeddingError,
+    _LoopBoundClientMixin,
     _resolve_env_api_key,
 )
 from geny_executor.memory.provider import EmbeddingDescriptor
@@ -27,7 +28,7 @@ _GOOGLE_DIMS = {
 }
 
 
-class GoogleEmbeddingClient(EmbeddingClient):
+class GoogleEmbeddingClient(_LoopBoundClientMixin, EmbeddingClient):
     """Google Generative AI embeddings."""
 
     def __init__(
@@ -45,7 +46,10 @@ class GoogleEmbeddingClient(EmbeddingClient):
             "google", "GOOGLE_API_KEY", "GEMINI_API_KEY"
         )
         self._dimension = dimension or _GOOGLE_DIMS.get(model, 0)
+        # Loop-safe client cache (see _LoopBoundClientMixin).
         self._client = client
+        self._client_loop = None
+        self._injected_client = client is not None
         self._descriptor = EmbeddingDescriptor(
             provider="google",
             model=model,
@@ -61,43 +65,47 @@ class GoogleEmbeddingClient(EmbeddingClient):
     async def embed(self, texts: Sequence[str]) -> List[List[float]]:
         if not texts:
             return []
-        client = self._ensure_client()
+        # Loop-safe: pooled client on the stable loop, ephemeral (closed
+        # below) on a sync-bridge loop.
+        client, ephemeral = self._acquire_client()
         try:
-            # google-genai v1: `client.aio.models.embed_content(...)`
-            resp = await client.aio.models.embed_content(
-                model=self._model,
-                contents=list(texts),
-            )
-        except Exception as exc:
-            raise EmbeddingError(f"google embed failed: {exc}") from exc
-        embeds = getattr(resp, "embeddings", None)
-        if embeds is None:
-            raise EmbeddingError(f"google embed: missing 'embeddings' in {resp!r}")
-        vectors: List[List[float]] = []
-        for item in embeds:
-            values = getattr(item, "values", None)
-            if values is None:
-                raise EmbeddingError(f"google embed: bad row: {item!r}")
-            vectors.append([float(x) for x in values])
-        if self._dimension == 0 and vectors:
-            self._dimension = len(vectors[0])
-            self._descriptor = EmbeddingDescriptor(
-                provider="google",
-                model=self._model,
-                dimension=self._dimension,
-                metric="cosine",
-                api_key_present=bool(self._api_key),
-            )
-        return vectors
+            try:
+                # google-genai v1: `client.aio.models.embed_content(...)`
+                resp = await client.aio.models.embed_content(
+                    model=self._model,
+                    contents=list(texts),
+                )
+            except Exception as exc:
+                raise EmbeddingError(f"google embed failed: {exc}") from exc
+            embeds = getattr(resp, "embeddings", None)
+            if embeds is None:
+                raise EmbeddingError(f"google embed: missing 'embeddings' in {resp!r}")
+            vectors: List[List[float]] = []
+            for item in embeds:
+                values = getattr(item, "values", None)
+                if values is None:
+                    raise EmbeddingError(f"google embed: bad row: {item!r}")
+                vectors.append([float(x) for x in values])
+            if self._dimension == 0 and vectors:
+                self._dimension = len(vectors[0])
+                self._descriptor = EmbeddingDescriptor(
+                    provider="google",
+                    model=self._model,
+                    dimension=self._dimension,
+                    metric="cosine",
+                    api_key_present=bool(self._api_key),
+                )
+            return vectors
+        finally:
+            if ephemeral:
+                await self._aclose_client(client)
 
     async def close(self) -> None:
-        return None
+        await self._close_cached_client()
 
     # ── internal ────────────────────────────────────────────────────
 
-    def _ensure_client(self):
-        if self._client is not None:
-            return self._client
+    def _build_client(self) -> object:
         try:
             from google import genai  # type: ignore
         except ImportError as exc:
@@ -105,8 +113,7 @@ class GoogleEmbeddingClient(EmbeddingClient):
                 "GoogleEmbeddingClient requires `google-genai`. "
                 "Install via `pip install geny-executor[google]`."
             ) from exc
-        self._client = genai.Client(api_key=self._api_key or None)
-        return self._client
+        return genai.Client(api_key=self._api_key or None)
 
 
 __all__ = ["GoogleEmbeddingClient"]

{geny_executor-2.48.2 → geny_executor-2.49.0}/src/geny_executor/memory/embedding/openai.py

@@ -13,13 +13,13 @@ keep request bodies reasonable and allow resume on partial failures.
 
 from __future__ import annotations
 
-import asyncio
 import logging
 from typing import List, Optional, Sequence
 
 from geny_executor.memory.embedding.client import (
     EmbeddingClient,
     EmbeddingError,
+    _LoopBoundClientMixin,
     _resolve_env_api_key,
 )
 from geny_executor.memory.provider import EmbeddingDescriptor
@@ -71,7 +71,7 @@ _OPENAI_DIMS = {
 }
 
 
-class OpenAIEmbeddingClient(EmbeddingClient):
+class OpenAIEmbeddingClient(_LoopBoundClientMixin, EmbeddingClient):
     """OpenAI embeddings via the official SDK."""
 
     def __init__(
@@ -89,7 +89,12 @@ class OpenAIEmbeddingClient(EmbeddingClient):
         # it logs a one-time migration warning (audit §2.6).
         self._api_key = api_key or _resolve_env_api_key("openai", "OPENAI_API_KEY")
         self._dimension = dimension or _OPENAI_DIMS.get(model, 0)
+        # Loop-safe client cache (see _LoopBoundClientMixin). A caller-
+        # supplied client is used verbatim (tests); otherwise lazily built
+        # per-loop by _build_client below.
         self._client = client
+        self._client_loop = None
+        self._injected_client = client is not None
         self._descriptor = EmbeddingDescriptor(
             provider="openai",
             model=model,
@@ -105,51 +110,47 @@ class OpenAIEmbeddingClient(EmbeddingClient):
     async def embed(self, texts: Sequence[str]) -> List[List[float]]:
         if not texts:
             return []
-        client = self._ensure_client()
-        out: List[List[float]] = []
-        # Bound each input to the model's token budget so one over-long
-        # text can never 400 the whole batch (crash-safety net).
-        texts = [_bound_input(t) for t in texts]
-        for i in range(0, len(texts), MAX_BATCH_SIZE):
-            batch = list(texts[i : i + MAX_BATCH_SIZE])
-            try:
-                # `openai>=1.x` exposes `await client.embeddings.create(...)`
-                resp = await client.embeddings.create(input=batch, model=self._model)
-            except Exception as exc:  # narrow is SDK-dependent
-                raise EmbeddingError(
-                    f"openai embed failed: {exc}",
-                    category=_classify_openai_error(exc),
-                ) from exc
-            # SDK response: `data: List[Embedding(embedding: List[float])]`
-            out.extend(item.embedding for item in resp.data)
-        # Update descriptor dimension if we learned it at runtime
-        if self._dimension == 0 and out:
-            self._dimension = len(out[0])
-            self._descriptor = EmbeddingDescriptor(
-                provider="openai",
-                model=self._model,
-                dimension=self._dimension,
-                metric="cosine",
-                api_key_present=bool(self._api_key),
-            )
-        return out
+        # Loop-safe: a pooled client on the stable loop, or a short-lived
+        # client on an ephemeral (sync-bridge) loop that we close below.
+        client, ephemeral = self._acquire_client()
+        try:
+            out: List[List[float]] = []
+            # Bound each input to the model's token budget so one over-long
+            # text can never 400 the whole batch (crash-safety net).
+            texts = [_bound_input(t) for t in texts]
+            for i in range(0, len(texts), MAX_BATCH_SIZE):
+                batch = list(texts[i : i + MAX_BATCH_SIZE])
+                try:
+                    # `openai>=1.x` exposes `await client.embeddings.create(...)`
+                    resp = await client.embeddings.create(input=batch, model=self._model)
+                except Exception as exc:  # narrow is SDK-dependent
+                    raise EmbeddingError(
+                        f"openai embed failed: {exc}",
+                        category=_classify_openai_error(exc),
+                    ) from exc
+                # SDK response: `data: List[Embedding(embedding: List[float])]`
+                out.extend(item.embedding for item in resp.data)
+            # Update descriptor dimension if we learned it at runtime
+            if self._dimension == 0 and out:
+                self._dimension = len(out[0])
+                self._descriptor = EmbeddingDescriptor(
+                    provider="openai",
+                    model=self._model,
+                    dimension=self._dimension,
+                    metric="cosine",
+                    api_key_present=bool(self._api_key),
+                )
+            return out
+        finally:
+            if ephemeral:
+                await self._aclose_client(client)
 
     async def close(self) -> None:
-        client = self._client
-        if client is None:
-            return
-        closer = getattr(client, "close", None)
-        if closer is None:
-            return
-        result = closer()
-        if asyncio.iscoroutine(result):
-            await result
+        await self._close_cached_client()
 
     # ── internal ────────────────────────────────────────────────────
 
-    def _ensure_client(self):
-        if self._client is not None:
-            return self._client
+    def _build_client(self) -> object:
         try:
             from openai import AsyncOpenAI  # type: ignore
         except ImportError as exc:
@@ -157,8 +158,7 @@ class OpenAIEmbeddingClient(EmbeddingClient):
                 "OpenAIEmbeddingClient requires the `openai` package. "
                 "Install via `pip install geny-executor[openai]`."
             ) from exc
-        self._client = AsyncOpenAI(api_key=self._api_key or None)
-        return self._client
+        return AsyncOpenAI(api_key=self._api_key or None)
 
 
 def _classify_openai_error(exc: Exception) -> str:

{geny_executor-2.48.2 → geny_executor-2.49.0}/src/geny_executor/memory/providers/file/provider.py

@@ -185,8 +185,21 @@ class FileMemoryProvider(MemoryProvider):
         self._initialized = True
 
     async def close(self) -> None:
-        # All writes are flushed at op time; nothing to do.
-        return None
+        # Writes are flushed at op time, so the stores need no teardown —
+        # but the embedding client owns an httpx connection pool (sockets)
+        # that must be released, or every session/restore leaks one client.
+        # The vector store shares THIS exact client instance (built with
+        # ``client=self._embedding_client``), so this is the single release
+        # point. Best-effort: a broken/cross-loop client must not turn
+        # session teardown into an error.
+        client = self._embedding_client
+        self._embedding_client = None
+        if client is None:
+            return
+        try:
+            await client.close()
+        except Exception:  # noqa: BLE001
+            logger.debug("embedding client close failed during provider close", exc_info=True)
 
     # ── layer handles ───────────────────────────────────────────────
 

geny_executor-2.49.0/src/geny_executor/tools/_ssh.py

@@ -0,0 +1,215 @@
+"""Low-level SSH primitives for the built-in SSH tools.
+
+Pure-async, built on ``asyncssh`` (native asyncio — no thread offload, so it
+drops straight into a tool's ``async def execute``). Mirrors the shape of
+``tools/_sandbox.py``: small helpers that open a connection, run a command (or
+transfer a file), and return a ``(rc, stdout, stderr)`` triple, with all output
+shaping/truncation left to the caller.
+
+``asyncssh`` is an OPTIONAL dependency (extra ``ssh``). It is imported lazily so
+the core install stays lean; callers get :class:`SSHUnavailableError` (a clean
+install hint) when it is absent, never an ``ImportError`` at import time.
+
+A "server" here is a plain dict — the credential record resolved by name from
+the per-session store (see ``tools/built_in/_ssh_store.py``):
+
+    {"name", "host", "port"?, "user", "password"?, "private_key"?,
+     "passphrase"?, "description"?, "strict_host_key"?}
+
+At least one of ``password`` / ``private_key`` must be present. The password
+never leaves this module (it is fed to the transport / to ``sudo -S`` on
+stdin), so the agent — which only ever passes a server *name* — never handles
+it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shlex
+import time
+from typing import Any, Dict, Optional, Tuple
+
+
+class SSHUnavailableError(RuntimeError):
+    """Raised when the optional ``asyncssh`` dependency is not installed."""
+
+
+class SSHConfigError(ValueError):
+    """Raised when a server record is malformed (missing host/creds, bad key)."""
+
+
+_INSTALL_HINT = (
+    "SSH tools require the `asyncssh` package. Install it via "
+    "`pip install geny-executor[ssh]`."
+)
+
+
+def _require_asyncssh():
+    try:
+        import asyncssh  # type: ignore
+    except ImportError as exc:  # pragma: no cover - env dependent
+        raise SSHUnavailableError(_INSTALL_HINT) from exc
+    return asyncssh
+
+
+def _connect_kwargs(server: Dict[str, Any], *, connect_timeout: float) -> Tuple[str, Dict[str, Any]]:
+    """Build ``(host, asyncssh.connect kwargs)`` from a server record.
+
+    Host-key verification is DISABLED by default (``known_hosts=None``) so a
+    user's own freshly-provisioned server "just works" on first contact; set
+    ``strict_host_key: true`` on the record to opt back into verification.
+    """
+    asyncssh = _require_asyncssh()
+    host = str(server.get("host") or "").strip()
+    if not host:
+        raise SSHConfigError("server record has no 'host'")
+    try:
+        port = int(server.get("port") or 22)
+    except (TypeError, ValueError):
+        raise SSHConfigError(f"invalid 'port': {server.get('port')!r}")
+    username = str(server.get("user") or server.get("username") or "").strip() or None
+
+    kwargs: Dict[str, Any] = {
+        "port": port,
+        "username": username,
+        "connect_timeout": connect_timeout,
+    }
+    # known_hosts=None disables host-key checking; opt-in strict mode uses the
+    # default system known_hosts.
+    if not server.get("strict_host_key"):
+        kwargs["known_hosts"] = None
+
+    password = server.get("password") or None
+    private_key = server.get("private_key") or None
+    if private_key:
+        passphrase = server.get("passphrase") or None
+        try:
+            key = asyncssh.import_private_key(private_key, passphrase)
+        except Exception as exc:  # noqa: BLE001 — surface a clean config error
+            raise SSHConfigError(f"invalid private_key: {exc}") from exc
+        kwargs["client_keys"] = [key]
+        if password:  # allow key + password (e.g. key + sudo password)
+            kwargs["password"] = password
+    elif password:
+        kwargs["password"] = password
+    else:
+        raise SSHConfigError("server record has neither 'password' nor 'private_key'")
+
+    return host, kwargs
+
+
+async def _open(server: Dict[str, Any], *, connect_timeout: float):
+    """Open an asyncssh connection for *server* (caller manages the context)."""
+    asyncssh = _require_asyncssh()
+    host, kwargs = _connect_kwargs(server, connect_timeout=connect_timeout)
+    return await asyncssh.connect(host, **kwargs)
+
+
+def _remote_command(command: str, *, cwd: Optional[str], sudo: bool, password: Optional[str]) -> Tuple[str, Optional[str]]:
+    """Compose the remote command string + optional stdin (sudo password)."""
+    inner = command
+    if cwd:
+        inner = f"cd {shlex.quote(cwd)} && {command}"
+    if sudo:
+        # -S reads the password from stdin; -p '' suppresses the prompt so it
+        # can't pollute stdout. Wrap in a login shell so pipes/&&/redirs work.
+        remote = f"sudo -S -p '' /bin/sh -c {shlex.quote(inner)}"
+        return remote, (password or "") + "\n"
+    return inner, None
+
+
+async def ssh_exec(
+    server: Dict[str, Any],
+    command: str,
+    *,
+    timeout: float = 60.0,
+    cwd: Optional[str] = None,
+    sudo: bool = False,
+    connect_timeout: float = 15.0,
+) -> Tuple[int, str, str]:
+    """Run *command* on *server*; return ``(exit_code, stdout, stderr)``.
+
+    ``sudo=True`` runs it under ``sudo -S`` with the server's stored password
+    fed on stdin — the agent never sees the password.
+    """
+    async with await _open(server, connect_timeout=connect_timeout) as conn:
+        remote, run_input = _remote_command(
+            command, cwd=cwd, sudo=sudo, password=server.get("password")
+        )
+        result = await asyncio.wait_for(
+            conn.run(remote, input=run_input, check=False), timeout=timeout
+        )
+        rc = result.exit_status
+        # exit_status is None on signal termination; map to 137-style non-zero.
+        if rc is None:
+            rc = 128 + int(result.exit_signal[1]) if getattr(result, "exit_signal", None) else 1
+        return int(rc), str(result.stdout or ""), str(result.stderr or "")
+
+
+async def ssh_test_connection(
+    server: Dict[str, Any], *, connect_timeout: float = 15.0
+) -> Dict[str, Any]:
+    """Open a connection and run a trivial command to verify reachability +
+    auth. Returns ``{success, latency_ms, error?}`` — never raises."""
+    start = time.monotonic()
+    try:
+        async with await _open(server, connect_timeout=connect_timeout) as conn:
+            r = await asyncio.wait_for(
+                conn.run("echo geny-ssh-ok", check=False), timeout=connect_timeout
+            )
+            latency_ms = (time.monotonic() - start) * 1000.0
+            ok = (r.exit_status == 0) and ("geny-ssh-ok" in str(r.stdout or ""))
+            out: Dict[str, Any] = {"success": bool(ok), "latency_ms": round(latency_ms, 1)}
+            if not ok:
+                out["error"] = "connected but test command failed"
+            return out
+    except SSHUnavailableError as exc:
+        return {"success": False, "error": str(exc)}
+    except SSHConfigError as exc:
+        return {"success": False, "error": f"config: {exc}"}
+    except asyncio.TimeoutError:
+        return {"success": False, "error": f"timed out after {connect_timeout:.0f}s"}
+    except Exception as exc:  # noqa: BLE001 — auth/network/etc → friendly string
+        return {"success": False, "error": _friendly_error(exc)}
+
+
+async def sftp_put(
+    server: Dict[str, Any], local_path: str, remote_path: str, *, connect_timeout: float = 15.0
+) -> None:
+    async with await _open(server, connect_timeout=connect_timeout) as conn:
+        async with conn.start_sftp_client() as sftp:
+            await sftp.put(local_path, remote_path)
+
+
+async def sftp_get(
+    server: Dict[str, Any], remote_path: str, local_path: str, *, connect_timeout: float = 15.0
+) -> None:
+    async with await _open(server, connect_timeout=connect_timeout) as conn:
+        async with conn.start_sftp_client() as sftp:
+            await sftp.get(remote_path, local_path)
+
+
+def _friendly_error(exc: Exception) -> str:
+    """Map common asyncssh/OS errors to a short, safe message (no secrets)."""
+    name = type(exc).__name__
+    msg = str(exc).strip() or name
+    lowered = msg.lower()
+    if "permission denied" in lowered or "authentication" in lowered or name == "PermissionDenied":
+        return "authentication failed (check user / password / key)"
+    if "name or service not known" in lowered or "nodename nor servname" in lowered:
+        return "host not found (check host / DNS)"
+    if "connection refused" in lowered:
+        return "connection refused (is SSH listening on that host/port?)"
+    if "timed out" in lowered or name == "TimeoutError":
+        return "connection timed out"
+    return f"{name}: {msg}"
+
+
+__all__ = [
+    "SSHUnavailableError",
+    "SSHConfigError",
+    "ssh_exec",
+    "ssh_test_connection",
+    "sftp_put",
+    "sftp_get",
+]