remote-exec-grpc 0.2.1__py3-none-any.whl

remote_exec/server.py

@@ -0,0 +1,292 @@
+"""Async gRPC server: request validation, audit logging, and lifecycle.
+
+The servicer is a thin adapter between protobuf messages and
+:class:`remote_exec.executor.Executor`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import getpass
+import json
+import logging
+import math
+import os
+import re
+import socket
+import time
+import uuid
+from dataclasses import dataclass
+
+import grpc
+from google.protobuf.timestamp_pb2 import Timestamp
+
+from . import __version__
+from .config import DEFAULT_HOST, DEFAULT_PORT, format_address
+from .cmdlog import CommandLog
+from .executor import CommandSpec, Executor, Finished, Output, Started, Status, Stream
+from .policy import PolicyProvider
+from .security import TokenAuthInterceptor, peer_identity, server_credentials
+from .v1 import remote_exec_pb2 as pb
+from .v1 import remote_exec_pb2_grpc as pb_grpc
+
+log = logging.getLogger(__name__)
+audit = logging.getLogger("remote_exec.audit")
+
+MAX_COMMAND_BYTES = 256 * 1024
+MAX_ENV_ENTRIES = 1024
+MAX_ENV_VALUE_BYTES = 128 * 1024
+_ENV_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+# Keepalive: lets long silent commands survive NAT/firewall idle timeouts and
+# lets the server notice vanished clients (which cancels their commands).
+SERVER_OPTIONS = [
+    ("grpc.keepalive_time_ms", 60_000),
+    ("grpc.keepalive_timeout_ms", 20_000),
+    ("grpc.keepalive_permit_without_calls", 1),
+    ("grpc.http2.min_recv_ping_interval_without_data_ms", 10_000),
+    ("grpc.http2.max_ping_strikes", 0),
+]
+
+
+def default_shell() -> str:
+    return "/bin/bash" if os.path.exists("/bin/bash") else "/bin/sh"
+
+
+@dataclass
+class ServerSettings:
+    host: str = DEFAULT_HOST
+    port: int = DEFAULT_PORT
+    shell: str = ""
+    max_concurrent: int = 32
+    max_timeout: float | None = None
+    kill_grace: float = 5.0
+    token: str | None = None
+    tls_cert: str | None = None
+    tls_key: str | None = None
+    tls_client_ca: str | None = None
+    tools_file: str | None = None      # None: default ~/.config/remote-exec/tools.yaml if present
+    tools_required: bool = False       # error if tools_file is missing (explicit --tools)
+    command_log: str | None = None     # file recording commands and their output; None = off
+    command_log_max_mb: float = 10.0   # rotate to a new file beyond this size
+    command_log_keep: int = 0          # rotated files to keep; 0 = all
+
+    @property
+    def address(self) -> str:
+        return format_address(self.host, self.port)
+
+
+class RequestError(ValueError):
+    pass
+
+
+def validate_request(req: pb.ExecuteRequest, max_timeout: float | None) -> CommandSpec:
+    command = req.command
+    if not command.strip():
+        raise RequestError("command must not be empty")
+    if len(command.encode()) > MAX_COMMAND_BYTES:
+        raise RequestError(f"command exceeds {MAX_COMMAND_BYTES} bytes")
+    if "\x00" in command:
+        raise RequestError("command must not contain NUL bytes")
+
+    cwd = None
+    if req.working_directory:
+        if "\x00" in req.working_directory:
+            raise RequestError("working_directory must not contain NUL bytes")
+        cwd = os.path.expanduser(req.working_directory)
+        if not os.path.isabs(cwd):
+            raise RequestError(f"working_directory must be an absolute path (or start with ~): {req.working_directory!r}")
+
+    env = dict(req.environment)
+    if len(env) > MAX_ENV_ENTRIES:
+        raise RequestError(f"too many environment variables (max {MAX_ENV_ENTRIES})")
+    for key, value in env.items():
+        if not _ENV_NAME_RE.match(key):
+            raise RequestError(f"invalid environment variable name: {key!r}")
+        if "\x00" in value or len(value.encode()) > MAX_ENV_VALUE_BYTES:
+            raise RequestError(f"invalid value for environment variable {key}")
+
+    timeout = req.timeout_seconds
+    if math.isnan(timeout) or math.isinf(timeout) or timeout < 0:
+        raise RequestError("timeout_seconds must be a finite number >= 0")
+    if max_timeout and (timeout == 0 or timeout > max_timeout):
+        timeout = max_timeout
+    return CommandSpec(command=command, cwd=cwd, env=env, timeout=timeout or None)
+
+
+def _ts(dt) -> Timestamp:
+    t = Timestamp()
+    t.FromDatetime(dt)
+    return t
+
+
+_STATUS_TO_PB = {
+    Status.EXITED: pb.Finished.EXITED,
+    Status.TIMEOUT: pb.Finished.TIMEOUT,
+    Status.ERROR: pb.Finished.ERROR,
+}
+
+
+def event_to_proto(ev, hostname: str) -> pb.ExecuteEvent:
+    if isinstance(ev, Output):
+        chunk = pb.OutputChunk(data=ev.data)
+        return pb.ExecuteEvent(stdout=chunk) if ev.stream is Stream.STDOUT else pb.ExecuteEvent(stderr=chunk)
+    if isinstance(ev, Started):
+        return pb.ExecuteEvent(started=pb.Started(
+            execution_id=ev.execution_id, pid=ev.pid, start_time=_ts(ev.start_time), hostname=hostname,
+        ))
+    if isinstance(ev, Finished):
+        return pb.ExecuteEvent(finished=pb.Finished(
+            status=_STATUS_TO_PB[ev.status], exit_code=ev.exit_code, signal=ev.signal,
+            start_time=_ts(ev.start_time), end_time=_ts(ev.end_time),
+            message=ev.message, execution_id=ev.execution_id,
+        ))
+    raise TypeError(f"unknown event {ev!r}")
+
+
+def _q(value: str) -> str:
+    """Quote a value for single-line key=value audit records."""
+    return json.dumps(value, ensure_ascii=False)
+
+
+class RemoteExecutorService(pb_grpc.RemoteExecutorServicer):
+    def __init__(self, settings: ServerSettings, executor: Executor, policy: PolicyProvider,
+                 command_log: CommandLog | None = None):
+        self.settings = settings
+        self.executor = executor
+        self.policy = policy
+        self.command_log = command_log
+        self.hostname = socket.gethostname()
+        self._active = 0
+
+    async def Execute(self, request: pb.ExecuteRequest, context: grpc.aio.ServicerContext):
+        client = peer_identity(context)
+        try:
+            spec = validate_request(request, self.settings.max_timeout)
+        except RequestError as exc:
+            audit.warning("rejected client=%s reason=%s", client, _q(str(exc)))
+            if self.command_log:
+                self.command_log.rejected(client, request.command, str(exc))
+            await context.abort(grpc.StatusCode.INVALID_ARGUMENT, str(exc))
+
+        if reason := self.policy.current().check(spec.command):
+            audit.warning("rejected client=%s reason=%s command=%s", client, _q(f"tools policy: {reason}"),
+                          _q(spec.command))
+            if self.command_log:
+                self.command_log.rejected(client, spec.command, f"tools policy: {reason}")
+            await context.abort(grpc.StatusCode.PERMISSION_DENIED, f"blocked by the server's tools policy: {reason}")
+
+        if self._active >= self.settings.max_concurrent:
+            audit.warning("rejected client=%s reason=%s", client, _q("too many concurrent commands"))
+            if self.command_log:
+                self.command_log.rejected(client, spec.command, "too many concurrent commands")
+            await context.abort(
+                grpc.StatusCode.RESOURCE_EXHAUSTED,
+                f"server is already running {self._active} commands (max {self.settings.max_concurrent})",
+            )
+
+        execution_id = uuid.uuid4().hex[:12]
+        audit.info(
+            "start id=%s client=%s cwd=%s timeout=%s env_keys=%s command=%s",
+            execution_id, client, _q(spec.cwd or os.getcwd()), spec.timeout or 0,
+            _q(",".join(sorted(spec.env))), _q(spec.command),
+        )
+        if self.command_log:
+            self.command_log.start(execution_id, client, spec.cwd or os.getcwd(), spec.command,
+                                   spec.timeout or 0, spec.env)
+        started = time.monotonic()
+        outcome = "cancelled"
+        exit_code: int | str = "-"
+        self._active += 1
+        try:
+            async with contextlib.aclosing(self.executor.run(spec, execution_id)) as events:
+                async for ev in events:
+                    if isinstance(ev, Output) and self.command_log:
+                        self.command_log.output(execution_id, ev.stream.value, ev.data)
+                    elif isinstance(ev, Finished):
+                        outcome, exit_code = ev.status.value, ev.exit_code
+                        if ev.status is Status.ERROR:
+                            exit_code = "-"
+                            outcome = f"error message={_q(ev.message)}"
+                    yield event_to_proto(ev, self.hostname)
+        finally:
+            self._active -= 1
+            duration = time.monotonic() - started
+            audit.info(
+                "end id=%s client=%s status=%s exit_code=%s duration=%.3fs",
+                execution_id, client, outcome, exit_code, duration,
+            )
+            if self.command_log:
+                self.command_log.end(execution_id, outcome, exit_code, duration)
+
+    async def GetServerInfo(self, request, context):
+        policy = self.policy.current()
+        return pb.ServerInfo(
+            hostname=self.hostname, version=__version__, user=getpass.getuser(), shell=self.executor.shell,
+            allowed_tools=policy.allow, denied_tools=policy.deny,
+        )
+
+
+class RemoteExecServer:
+    """Owns the grpc.aio server and the executor."""
+
+    def __init__(self, settings: ServerSettings):
+        self.settings = settings
+        self.executor = Executor(shell=settings.shell or default_shell(), kill_grace=settings.kill_grace)
+        self.policy = PolicyProvider(settings.tools_file, required=settings.tools_required)
+        self.command_log = CommandLog(
+            settings.command_log, int(settings.command_log_max_mb * 1024 * 1024), settings.command_log_keep,
+        ) if settings.command_log else None
+        interceptors = [TokenAuthInterceptor(settings.token)] if settings.token else []
+        self._server = grpc.aio.server(interceptors=interceptors, options=SERVER_OPTIONS)
+        pb_grpc.add_RemoteExecutorServicer_to_server(
+            RemoteExecutorService(settings, self.executor, self.policy, self.command_log), self._server
+        )
+        self.bound_port: int | None = None
+
+    async def start(self) -> int:
+        s = self.settings
+        if s.tls_cert:
+            creds = server_credentials(s.tls_cert, s.tls_key, s.tls_client_ca)
+            port = self._server.add_secure_port(s.address, creds)
+        else:
+            port = self._server.add_insecure_port(s.address)
+        if not port:
+            raise OSError(f"failed to bind {s.address}")
+        await self._server.start()
+        self.bound_port = port
+        log.info(
+            "remote-exec-server %s listening on %s (tls=%s, mtls=%s, token_auth=%s, shell=%s)",
+            __version__, format_address(s.host, port), bool(s.tls_cert), bool(s.tls_client_ca),
+            bool(s.token), self.executor.shell,
+        )
+        log.info("tools policy: %s", self.policy.current().describe())
+        if self.command_log:
+            log.info("command log: %s (rotate at %g MB, keep %s)", self.command_log.path,
+                     self.settings.command_log_max_mb, self.settings.command_log_keep or "all")
+        else:
+            log.info("command log: disabled")
+        return port
+
+    async def stop(self, grace: float = 5.0) -> None:
+        """Stop accepting RPCs, cancel running ones and clean up their processes."""
+        await self._server.stop(grace)
+        await self.executor.wait_cleanups(timeout=self.settings.kill_grace + 2)
+        self.executor.kill_all()
+        if self.command_log:
+            self.command_log.close()
+
+    async def wait_for_termination(self) -> None:
+        await self._server.wait_for_termination()
+
+
+async def serve(settings: ServerSettings, stop_event: asyncio.Event | None = None) -> None:
+    server = RemoteExecServer(settings)
+    await server.start()
+    stop_event = stop_event or asyncio.Event()
+    try:
+        await stop_event.wait()
+    finally:
+        log.info("shutting down")
+        await server.stop()

remote_exec/server_cli.py

@@ -0,0 +1,219 @@
+"""``remote-exec-server`` command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import os
+import signal
+import sys
+
+from . import __version__
+from .cmdlog import DEFAULT_COMMAND_LOG, DEFAULT_MAX_MB, CommandLog
+from .config import DEFAULT_HOST, DEFAULT_PORT, ConfigError, load_server_config, split_host_port, validate_port
+from .policy import DEFAULT_TOOLS_FILE, PolicyError, PolicyProvider
+from .security import DEFAULT_TOKEN_FILE, SecurityError, generate_token_file, is_loopback_host, read_secret_file
+from .server import ServerSettings, serve
+
+log = logging.getLogger("remote_exec.server")
+
+DEFAULTS = {
+    "host": DEFAULT_HOST,
+    "port": DEFAULT_PORT,
+    "max_concurrent": 32,
+    "max_timeout": None,
+    "shell": "",
+    "kill_grace": 5.0,
+    "log_level": "INFO",
+    "log_file": None,
+    "token_file": None,
+    "tls_cert": None,
+    "tls_key": None,
+    "tls_client_ca": None,
+    "insecure_no_auth": False,
+    "allow_root": False,
+    "listen": None,
+    "tools": None,
+    "command_log": DEFAULT_COMMAND_LOG,
+    "command_log_max_mb": DEFAULT_MAX_MB,
+    "command_log_keep": 0,
+    "no_command_log": False,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="remote-exec-server",
+        description="Run the remote-exec gRPC server. Executes commands requested by "
+        "remote-exec-client as the current (non-root) user.",
+        epilog="Listening on a non-loopback address requires authentication "
+        "(--token-file and/or --tls-client-ca) unless --insecure-no-auth is given.",
+    )
+    addr = p.add_argument_group("listen address")
+    addr.add_argument("--host", help=f"address to bind (default: {DEFAULT_HOST}; use 0.0.0.0 for all interfaces)")
+    addr.add_argument("--port", type=int, help=f"TCP port (default: {DEFAULT_PORT})")
+    addr.add_argument("--listen", metavar="HOST:PORT", help="shorthand for --host and --port, e.g. 0.0.0.0:50051")
+    p.add_argument("--config", metavar="FILE", help="YAML file with server settings (CLI options override it)")
+
+    sec = p.add_argument_group("security")
+    sec.add_argument("--token-file", metavar="FILE", help="file containing the shared bearer token clients must send")
+    sec.add_argument("--tls-cert", metavar="FILE", help="server TLS certificate (PEM)")
+    sec.add_argument("--tls-key", metavar="FILE", help="server TLS private key (PEM)")
+    sec.add_argument("--tls-client-ca", metavar="FILE", help="CA for client certificates; enables mTLS")
+    sec.add_argument("--insecure-no-auth", action="store_true", default=None,
+                     help="allow listening on a non-loopback address without any authentication (NOT recommended)")
+    sec.add_argument("--allow-root", action="store_true", default=None,
+                     help="allow running as root (NOT recommended)")
+    sec.add_argument("--generate-token", nargs="?", const=str(DEFAULT_TOKEN_FILE), metavar="FILE",
+                     help=f"create a new random token file (mode 600) and exit; default FILE: {DEFAULT_TOKEN_FILE}")
+    sec.add_argument("--force", action="store_true", default=None,
+                     help="with --generate-token: replace an existing token file")
+
+    ex = p.add_argument_group("execution")
+    ex.add_argument("--tools", metavar="FILE",
+                    help=f"tools.yaml with allowed/denied programs (default: {DEFAULT_TOOLS_FILE} if it exists, "
+                    "else allow everything except ssh); reloaded automatically when changed")
+    ex.add_argument("--shell", help="shell used as '<shell> -c <command>' (default: /bin/bash, else /bin/sh)")
+    ex.add_argument("--max-concurrent", type=int, help="max concurrently running commands (default: 32)")
+    ex.add_argument("--max-timeout", type=float, metavar="SECONDS",
+                    help="upper bound for command timeouts; also applied to commands without a timeout")
+    ex.add_argument("--kill-grace", type=float, metavar="SECONDS",
+                    help="seconds between SIGTERM and SIGKILL when stopping a command (default: 5)")
+
+    lg = p.add_argument_group("logging")
+    lg.add_argument("--log-level", help="DEBUG, INFO, WARNING, ERROR (default: INFO)")
+    lg.add_argument("--log-file", metavar="FILE", help="also append logs to FILE (default: stderr only)")
+    lg.add_argument("--command-log", metavar="FILE",
+                    help=f"file recording every command and its output (default: ./{DEFAULT_COMMAND_LOG} "
+                    "in the directory the server is started from)")
+    lg.add_argument("--command-log-max-mb", type=float, metavar="MB",
+                    help=f"start a new command log file when it would exceed MB (default: {DEFAULT_MAX_MB:g})")
+    lg.add_argument("--command-log-keep", type=int, metavar="N",
+                    help="keep only the N most recent rotated command logs (default: 0 = keep all)")
+    lg.add_argument("--no-command-log", action="store_true", default=None, help="do not write a command log")
+    p.add_argument("-v", "--version", action="version", version=f"%(prog)s {__version__}")
+    return p
+
+
+def resolve_settings(args: argparse.Namespace) -> tuple[ServerSettings, dict]:
+    if args.listen and (args.host is not None or args.port is not None):
+        raise ConfigError("--listen cannot be combined with --host/--port")
+    # Precedence: defaults < config file < command line; "listen" expands to host+port.
+    opts = dict(DEFAULTS)
+    for layer in (load_server_config(args.config) if args.config else {}, vars(args)):
+        layer = {k: v for k, v in layer.items() if v is not None and k != "config"}
+        if layer.get("listen"):
+            layer["host"], layer["port"] = split_host_port(str(layer.pop("listen")), DEFAULT_PORT)
+        opts.update(layer)
+    opts["port"] = validate_port(opts["port"])
+    if opts["max_concurrent"] < 1:
+        raise ConfigError("max_concurrent must be >= 1")
+    if opts["max_timeout"] is not None and opts["max_timeout"] <= 0:
+        raise ConfigError("max_timeout must be > 0")
+    if bool(opts["tls_cert"]) != bool(opts["tls_key"]):
+        raise ConfigError("--tls-cert and --tls-key must be given together")
+    if opts["tls_client_ca"] and not opts["tls_cert"]:
+        raise ConfigError("--tls-client-ca (mTLS) requires --tls-cert/--tls-key")
+    if float(opts["command_log_max_mb"]) < 0.001:
+        raise ConfigError("command_log_max_mb must be at least 0.001 (1 KiB)")
+    if int(opts["command_log_keep"]) < 0:
+        raise ConfigError("command_log_keep must be >= 0")
+    command_log = None
+    if not opts["no_command_log"] and opts["command_log"] not in (None, False, ""):
+        # Relative paths are relative to the directory the server is started from.
+        command_log = os.path.abspath(os.path.expanduser(str(opts["command_log"])))
+
+    token = read_secret_file(opts["token_file"]) if opts["token_file"] else None
+    settings = ServerSettings(
+        host=str(opts["host"]), port=opts["port"], shell=opts["shell"] or "",
+        max_concurrent=int(opts["max_concurrent"]), max_timeout=opts["max_timeout"],
+        kill_grace=float(opts["kill_grace"]), token=token,
+        tls_cert=opts["tls_cert"], tls_key=opts["tls_key"], tls_client_ca=opts["tls_client_ca"],
+        tools_file=opts["tools"], tools_required=bool(opts["tools"]),
+        command_log=command_log, command_log_max_mb=float(opts["command_log_max_mb"]),
+        command_log_keep=int(opts["command_log_keep"]),
+    )
+    return settings, opts
+
+
+def check_safety(settings: ServerSettings, opts: dict) -> None:
+    if hasattr(os, "geteuid") and os.geteuid() == 0 and not opts["allow_root"]:
+        raise SecurityError(
+            "refusing to run as root: commands would execute with full privileges. "
+            "Run as an unprivileged user (or pass --allow-root if you really mean it)."
+        )
+    authenticated = bool(settings.token or settings.tls_client_ca)
+    if not is_loopback_host(settings.host):
+        if not authenticated and not opts["insecure_no_auth"]:
+            raise SecurityError(
+                f"refusing to listen on non-loopback address {settings.host!r} without authentication. "
+                "Configure --token-file and/or mTLS (--tls-cert/--tls-key/--tls-client-ca), "
+                "or pass --insecure-no-auth on a fully trusted network."
+            )
+        if not authenticated:
+            log.warning("listening on %s WITHOUT authentication: anyone who can reach this port can run commands", settings.host)
+        if not settings.tls_cert:
+            log.warning("TLS is disabled: traffic (including the token) is unencrypted; use only over a trusted/encrypted network such as WireGuard/Tailscale")
+
+
+def setup_logging(level: str, log_file: str | None) -> None:
+    handlers: list[logging.Handler] = [logging.StreamHandler(sys.stderr)]
+    if log_file:
+        handlers.append(logging.FileHandler(os.path.expanduser(log_file)))
+    logging.basicConfig(
+        level=getattr(logging, str(level).upper(), logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        handlers=handlers,
+        force=True,
+    )
+
+
+async def _run(settings: ServerSettings) -> None:
+    stop = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, stop.set)
+    await serve(settings, stop)
+
+
+def do_generate_token(path: str, force: bool) -> int:
+    try:
+        target = generate_token_file(path, force=force)
+    except SecurityError as exc:
+        print(f"remote-exec-server: error: {exc}", file=sys.stderr)
+        return 1
+    print(f"token written to {target} (mode 600)")
+    print("next steps:")
+    print(f"  server: remote-exec-server --host 0.0.0.0 --token-file {target}")
+    print("  client: copy this file to the client machine (e.g. ~/.config/remote-exec/token, chmod 600)")
+    print("          and set 'token_file:' in the client config")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.generate_token:
+        return do_generate_token(args.generate_token, bool(args.force))
+    try:
+        # Logging first so config warnings (e.g. token file permissions) are shown.
+        setup_logging(args.log_level or "INFO", args.log_file)
+        settings, opts = resolve_settings(args)
+        setup_logging(opts["log_level"], opts["log_file"])
+        check_safety(settings, opts)
+        PolicyProvider(settings.tools_file, required=settings.tools_required)  # validate tools.yaml early
+        if settings.command_log:  # fail now, not on the first command, if the log is not writable
+            CommandLog(settings.command_log, int(settings.command_log_max_mb * 1024 * 1024)).close()
+    except (ConfigError, SecurityError, PolicyError, OSError) as exc:
+        print(f"remote-exec-server: error: {exc}", file=sys.stderr)
+        return 2
+    try:
+        asyncio.run(_run(settings))
+    except OSError as exc:
+        print(f"remote-exec-server: error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

remote_exec/skill.py

@@ -0,0 +1,39 @@
+"""Install the Claude Code skill (custom slash command) for remote-exec-client."""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+SKILL_NAME = "remote-exec"
+DEFAULT_SKILL_DIR = Path("~/.claude/commands")
+
+
+class SkillExistsError(Exception):
+    pass
+
+
+def skill_text() -> str:
+    return resources.files("remote_exec").joinpath("claude_skill.md").read_text(encoding="utf-8")
+
+
+def install_skill(directory: str | Path | None = None, force: bool = False) -> tuple[Path, str]:
+    """Write ``<directory>/remote-exec.md``.
+
+    Returns the path and one of ``"installed"``, ``"updated"``, ``"unchanged"``.
+    An existing file with different content (e.g. edited by the user) is only
+    replaced when ``force`` is true.
+    """
+    target = Path(directory or DEFAULT_SKILL_DIR).expanduser() / f"{SKILL_NAME}.md"
+    text = skill_text()
+    if target.exists():
+        if target.read_text(encoding="utf-8") == text:
+            return target, "unchanged"
+        if not force:
+            raise SkillExistsError(f"{target} already exists with different content; use --force to overwrite it")
+        status = "updated"
+    else:
+        status = "installed"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(text, encoding="utf-8")
+    return target, status

remote_exec/v1/__init__.py

@@ -0,0 +1 @@
+"""Generated protobuf / gRPC code for API version v1 (see proto/)."""

remote_exec/v1/remote_exec_pb2.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: remote_exec/v1/remote_exec.proto
+# Protobuf Python Version: 7.35.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    7,
+    35,
+    1,
+    '',
+    'remote_exec/v1/remote_exec.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n remote_exec/v1/remote_exec.proto\x12\x0eremote_exec.v1\x1a\x1fgoogle/protobuf/timestamp.proto\"\xcf\x01\n\x0e\x45xecuteRequest\x12\x0f\n\x07\x63ommand\x18\x01 \x01(\t\x12\x19\n\x11working_directory\x18\x02 \x01(\t\x12\x44\n\x0b\x65nvironment\x18\x03 \x03(\x0b\x32/.remote_exec.v1.ExecuteRequest.EnvironmentEntry\x12\x17\n\x0ftimeout_seconds\x18\x04 \x01(\x01\x1a\x32\n\x10\x45nvironmentEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"\xcf\x01\n\x0c\x45xecuteEvent\x12*\n\x07started\x18\x01 \x01(\x0b\x32\x17.remote_exec.v1.StartedH\x00\x12-\n\x06stdout\x18\x02 \x01(\x0b\x32\x1b.remote_exec.v1.OutputChunkH\x00\x12-\n\x06stderr\x18\x03 \x01(\x0b\x32\x1b.remote_exec.v1.OutputChunkH\x00\x12,\n\x08\x66inished\x18\x04 \x01(\x0b\x32\x18.remote_exec.v1.FinishedH\x00\x42\x07\n\x05\x65vent\"n\n\x07Started\x12\x14\n\x0c\x65xecution_id\x18\x01 \x01(\t\x12\x0b\n\x03pid\x18\x02 \x01(\x05\x12.\n\nstart_time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x10\n\x08hostname\x18\x04 \x01(\t\"\x1b\n\x0bOutputChunk\x12\x0c\n\x04\x64\x61ta\x18\x01 \x01(\x0c\"\xa9\x02\n\x08\x46inished\x12/\n\x06status\x18\x01 \x01(\x0e\x32\x1f.remote_exec.v1.Finished.Status\x12\x11\n\texit_code\x18\x02 \x01(\x05\x12\x0e\n\x06signal\x18\x03 \x01(\x05\x12.\n\nstart_time\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12,\n\x08\x65nd_time\x18\x05 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x0f\n\x07message\x18\x06 \x01(\t\x12\x14\n\x0c\x65xecution_id\x18\x07 \x01(\t\"D\n\x06Status\x12\x16\n\x12STATUS_UNSPECIFIED\x10\x00\x12\n\n\x06\x45XITED\x10\x01\x12\x0b\n\x07TIMEOUT\x10\x02\x12\t\n\x05\x45RROR\x10\x03\"\x16\n\x14GetServerInfoRequest\"y\n\nServerInfo\x12\x10\n\x08hostname\x18\x01 \x01(\t\x12\x0f\n\x07version\x18\x02 \x01(\t\x12\x0c\n\x04user\x18\x03 \x01(\t\x12\r\n\x05shell\x18\x04 \x01(\t\x12\x15\n\rallowed_tools\x18\x05 \x03(\t\x12\x14\n\x0c\x64\x65nied_tools\x18\x06 \x03(\t2\xae\x01\n\x0eRemoteExecutor\x12I\n\x07\x45xecute\x12\x1e.remote_exec.v1.ExecuteRequest\x1a\x1c.remote_exec.v1.ExecuteEvent0\x01\x12Q\n\rGetServerInfo\x12$.remote_exec.v1.GetServerInfoRequest\x1a\x1a.remote_exec.v1.ServerInfob\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'remote_exec.v1.remote_exec_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_EXECUTEREQUEST_ENVIRONMENTENTRY']._loaded_options = None
+  _globals['_EXECUTEREQUEST_ENVIRONMENTENTRY']._serialized_options = b'8\001'
+  _globals['_EXECUTEREQUEST']._serialized_start=86
+  _globals['_EXECUTEREQUEST']._serialized_end=293
+  _globals['_EXECUTEREQUEST_ENVIRONMENTENTRY']._serialized_start=243
+  _globals['_EXECUTEREQUEST_ENVIRONMENTENTRY']._serialized_end=293
+  _globals['_EXECUTEEVENT']._serialized_start=296
+  _globals['_EXECUTEEVENT']._serialized_end=503
+  _globals['_STARTED']._serialized_start=505
+  _globals['_STARTED']._serialized_end=615
+  _globals['_OUTPUTCHUNK']._serialized_start=617
+  _globals['_OUTPUTCHUNK']._serialized_end=644
+  _globals['_FINISHED']._serialized_start=647
+  _globals['_FINISHED']._serialized_end=944
+  _globals['_FINISHED_STATUS']._serialized_start=876
+  _globals['_FINISHED_STATUS']._serialized_end=944
+  _globals['_GETSERVERINFOREQUEST']._serialized_start=946
+  _globals['_GETSERVERINFOREQUEST']._serialized_end=968
+  _globals['_SERVERINFO']._serialized_start=970
+  _globals['_SERVERINFO']._serialized_end=1091
+  _globals['_REMOTEEXECUTOR']._serialized_start=1094
+  _globals['_REMOTEEXECUTOR']._serialized_end=1268
+# @@protoc_insertion_point(module_scope)