@neoline/hostbridge 1.4.3 → 2.0.0

package/src/server_control_mcp/manager.py

@@ -1,922 +0,0 @@
-from __future__ import annotations
-
-import base64
-import hashlib
-import re
-import shlex
-import threading
-import time
-import uuid
-from collections.abc import Callable
-from contextlib import suppress
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Protocol, cast
-
-import pexpect
-
-from .hosts import HostRegistry
-from .policy import AuditSink, PolicyConfig, PolicyDecision, audit_event
-
-DEFAULT_CONNECT_TIMEOUT = 30
-DEFAULT_COMMAND_TIMEOUT = 60
-DEFAULT_REAPER_INTERVAL_SECONDS = 60
-MAX_OUTPUT_CHARS = 120_000
-REMOTE_JOB_ROOT = "$HOME/.hostbridge/jobs"
-REMOTE_SHELL = "bash"
-MAX_SHELL_TRANSFER_BYTES = 100 * 1024 * 1024
-DEFAULT_MAX_TRANSFER_BYTES = MAX_SHELL_TRANSFER_BYTES
-UPLOAD_BASE64_CHUNK_CHARS = 256 * 1024
-DOWNLOAD_CHUNK_BYTES = 5 * 1024 * 1024
-
-class PolicyDeniedError(RuntimeError):
-    """Raised when a command is blocked by the configured policy."""
-
-
-class ChildProcess(Protocol):
-    before: str
-    after: object
-
-    def sendline(self, line: str) -> None: ...
-
-    def send(self, text: str) -> None: ...
-
-    def expect(self, patterns: object, timeout: int | float = -1) -> int: ...
-
-    def isalive(self) -> bool: ...
-
-    def close(self, force: bool = False) -> None: ...
-
-    def read_nonblocking(self, size: int = 1, timeout: int | float = -1) -> str: ...
-
-
-ChildFactory = Callable[[str, list[str], int | float], ChildProcess]
-TokenFactory = Callable[[], str]
-
-
-class RemoteCommandError(RuntimeError):
-    """Raised when a remote session cannot execute a requested operation."""
-
-
-@dataclass(slots=True)
-class RemoteSession:
-    id: str
-    host_id: str
-    label: str
-    command: str
-    args: list[str]
-    child: ChildProcess
-    created_at: float = field(default_factory=time.time)
-    last_used_at: float = field(default_factory=time.time)
-    busy: bool = False
-    owner_agent_id: str | None = None
-    last_output: str = ""
-
-
-@dataclass(slots=True)
-class CommandResult:
-    session_id: str
-    host_id: str
-    command: str
-    exit_code: int | None
-    output: str
-    timed_out: bool = False
-
-
-@dataclass(slots=True)
-class RemoteTask:
-    id: str
-    session_id: str
-    host_id: str
-    command: str
-    job_dir: str
-    remote_pid: int | None
-    owner_agent_id: str | None = None
-    created_at: float = field(default_factory=time.time)
-
-
-def _new_token() -> str:
-    return uuid.uuid4().hex[:12]
-
-
-def _default_child_factory(command: str, args: list[str], timeout: int | float) -> ChildProcess:
-    return pexpect.spawn(
-        command,
-        args,
-        encoding="utf-8",
-        codec_errors="replace",
-        timeout=timeout,
-        echo=False,
-    )
-
-
-def _tail(value: str, limit: int = MAX_OUTPUT_CHARS) -> str:
-    if len(value) <= limit:
-        return value
-    return value[-limit:]
-
-
-def _extract_between_markers(raw: str, start_marker: str) -> str:
-    raw = raw.replace("\x1b[?2004h", "").replace("\x1b[?2004l", "")
-    if start_marker in raw:
-        raw = raw.split(start_marker, 1)[1]
-    lines = raw.replace("\r\n", "\n").replace("\r", "\n").split("\n")
-    cleaned = [
-        line
-        for line in lines
-        if not line.startswith("printf '") and "__SCM_START_" not in line and "__SCM_EXIT_" not in line
-    ]
-    return "\n".join(cleaned).strip("\n")
-
-
-def _parse_exit_marker(marker: object, token: str) -> int | None:
-    text = marker.group(0) if hasattr(marker, "group") else str(marker)
-    match = re.search(rf"__SCM_EXIT_{re.escape(token)}:(\d+)", text)
-    return int(match.group(1)) if match else None
-
-
-def _contains_terminal_control(text: str) -> bool:
-    return "\x1b" in text or "\x07" in text or "\\x1b" in text or "\\u001b" in text
-
-
-def _looks_shell_prompt(text: str) -> bool:
-    return re.search(r"[#$](?:\\s\*)?$", text.strip()) is not None
-
-
-def _runtime_expect_pattern(pattern: str) -> str:
-    if _contains_terminal_control(pattern) and _looks_shell_prompt(pattern):
-        return r"(?m)[^\r\n]*[#$]\s*$"
-    return pattern
-
-
-class SessionManager:
-    """Manages long-lived interactive PTYs and remote background jobs."""
-
-    def __init__(
-        self,
-        hosts: HostRegistry,
-        *,
-        child_factory: ChildFactory = _default_child_factory,
-        remote_shell: str = REMOTE_SHELL,
-        policy: PolicyConfig | None = None,
-        audit_sink: AuditSink | None = None,
-        max_sessions_per_host: int = 0,
-    ):
-        self.hosts = hosts
-        self.child_factory = child_factory
-        self.remote_shell = remote_shell
-        self._sessions: dict[str, RemoteSession] = {}
-        self._tasks: dict[str, RemoteTask] = {}
-        self._policy = policy
-        self._audit = audit_sink
-        self._max_sessions_per_host = max(0, int(max_sessions_per_host))
-        self._reaper_stop = threading.Event()
-        self._reaper_thread: threading.Thread | None = None
-
-    @property
-    def policy(self) -> PolicyConfig | None:
-        return self._policy
-
-    def start_idle_reaper(self, *, interval: int = DEFAULT_REAPER_INTERVAL_SECONDS) -> None:
-        """Spawn a background thread that closes idle sessions past policy timeout."""
-
-        if self._policy is None or not self._policy.enabled or self._policy.idle_timeout_seconds <= 0:
-            return
-        if self._reaper_thread is not None and self._reaper_thread.is_alive():
-            return
-        self._reaper_stop.clear()
-        timeout = self._policy.idle_timeout_seconds
-        thread = threading.Thread(
-            target=self._reap_loop,
-            kwargs={"interval": interval, "timeout": timeout},
-            daemon=True,
-            name="scm-idle-reaper",
-        )
-        self._reaper_thread = thread
-        thread.start()
-
-    def stop_idle_reaper(self) -> None:
-        self._reaper_stop.set()
-        thread = self._reaper_thread
-        if thread is not None and thread.is_alive():
-            thread.join(timeout=2.0)
-        self._reaper_thread = None
-
-    def _reap_loop(self, *, interval: int, timeout: int) -> None:
-        while not self._reaper_stop.wait(interval):
-            self._reap_idle(timeout)
-
-    def _reap_idle(self, timeout: int) -> int:
-        now = time.time()
-        expired = [
-            sid for sid, session in list(self._sessions.items())
-            if not session.busy and (now - session.last_used_at) > timeout
-        ]
-        for sid in expired:
-            self._safe_close(sid)
-            self._emit("session_idle_closed", session_id=sid, detail=f"idle > {timeout}s")
-        return len(expired)
-
-    def _safe_close(self, session_id: str) -> None:
-        session = self._sessions.pop(session_id, None)
-        if session is not None:
-            with suppress(Exception):
-                session.child.close(force=True)
-
-    def _emit(self, event: str, **fields: object) -> None:
-        if self._audit is None:
-            return
-        audit_event(self._audit, event=event, **{k: v for k, v in fields.items() if v is not None})  # type: ignore[arg-type]
-
-    def _check_policy(self, command: str) -> PolicyDecision | None:
-        if self._policy is None:
-            return None
-        return self._policy.evaluate(command)
-
-    def open_session(
-        self,
-        host_id: str,
-        *,
-        connect_timeout: int = DEFAULT_CONNECT_TIMEOUT,
-        token_factory: TokenFactory = _new_token,
-        owner_agent_id: str | None = None,
-    ) -> RemoteSession:
-        host = self.hosts.get(host_id)
-        self._check_host_session_limit(host.id)
-        child = self.child_factory(host.command, list(host.args), connect_timeout)
-        token = token_factory()
-        marker = f"__SCM_READY_{token}__"
-        try:
-            self._run_login_steps(child, host, connect_timeout)
-            if getattr(host, "login_steps", []):
-                self._wait_for_ready_prompt(child, host, connect_timeout)
-            child.send(f"printf '\\n{marker}\\n'\r")
-            child.expect(re.escape(marker), timeout=connect_timeout)
-        except Exception as exc:  # pexpect.TIMEOUT/EOF and fake child errors are surfaced uniformly.
-            try:
-                child.close(force=True)
-            finally:
-                raise RemoteCommandError(f"failed to establish ready shell for {host_id}: {exc}") from exc
-
-        session = RemoteSession(
-            id=uuid.uuid4().hex,
-            host_id=host.id,
-            label=host.label,
-            command=host.command,
-            args=list(host.args),
-            child=child,
-            owner_agent_id=owner_agent_id,
-            last_output=_tail(str(child.before)),
-        )
-        self._sessions[session.id] = session
-        self._emit("session_opened", session_id=session.id, host_id=host.id, outcome="ok")
-        return session
-
-    def _run_login_steps(self, child: ChildProcess, host: object, timeout: int) -> None:
-        for step in getattr(host, "login_steps", []):
-            child.expect(_runtime_expect_pattern(step.expect), timeout=timeout)
-            if step.send_secret is not None:
-                secrets = getattr(host, "secrets", {})
-                if step.send_secret not in secrets:
-                    raise RemoteCommandError(f"login step references missing secret '{step.send_secret}'")
-                self._send_login_text(child, secrets[step.send_secret])
-            else:
-                self._send_login_text(child, step.send or "")
-
-    def _send_login_text(self, child: ChildProcess, text: str) -> None:
-        # JumpServer-style menus often require carriage return rather than LF.
-        child.send(f"{text}\r")
-
-    def _wait_for_ready_prompt(self, child: ChildProcess, host: object, timeout: int) -> None:
-        ready_expect = getattr(host, "ready_expect", None)
-        pattern = ready_expect if isinstance(ready_expect, str) and ready_expect.strip() else r"(?m)[^\r\n]*[#$]\s*$"
-        child.expect(_runtime_expect_pattern(pattern), timeout=timeout)
-
-    def list_sessions(self) -> list[dict[str, object]]:
-        return [self._describe_session(session) for session in self._sessions.values()]
-
-    def close_all_sessions(self) -> dict[str, object]:
-        """Close every live session. Used for graceful shutdown."""
-
-        closed: list[str] = []
-        for session_id in list(self._sessions.keys()):
-            self._safe_close(session_id)
-            self._emit("session_closed", session_id=session_id, outcome="shutdown")
-            closed.append(session_id)
-        return {"closed": closed, "count": len(closed)}
-
-    def close_session(
-        self,
-        session_id: str,
-        *,
-        owner_agent_id: str | None = None,
-        force: bool = False,
-    ) -> dict[str, object]:
-        session = self._get_session(session_id)
-        self._check_owner(session, owner_agent_id, force=force)
-        if session.busy and not force:
-            raise RemoteCommandError(f"session {session_id} is busy; retry later or close with force")
-        session.child.close(force=True)
-        self._sessions.pop(session_id, None)
-        self._emit("session_closed", session_id=session_id, host_id=session.host_id, outcome="forced" if force else "user")
-        return {"session_id": session_id, "closed": True}
-
-    def stop_task(self, session_id: str, task_id: str, *, owner_agent_id: str | None = None, force: bool = False) -> dict[str, object]:
-        """Best-effort terminate a background task by killing its remote PID."""
-
-        task = self._tasks.get(task_id)
-        if task is None:
-            raise RemoteCommandError(f"unknown task {task_id}")
-        if task.session_id != session_id:
-            raise RemoteCommandError(f"task {task_id} does not belong to session {session_id}")
-        self._check_task_owner(task, owner_agent_id, force=force)
-        if task.remote_pid is None:
-            raise RemoteCommandError(f"task {task_id} has no recorded remote pid")
-        kill_script = f'if [ -f "{task.job_dir}/exit_code" ]; then echo already; else kill -TERM {task.remote_pid} 2>/dev/null && echo killed || echo noop; fi'
-        result = self.run_command(session_id, kill_script, timeout=10, owner_agent_id=owner_agent_id)
-        outcome = result.output.strip().splitlines()[-1] if result.output.strip() else "unknown"
-        self._emit(
-            "task_stopped",
-            session_id=session_id,
-            task_id=task_id,
-            host_id=task.host_id,
-            outcome=outcome,
-        )
-        return {"task_id": task_id, "stopped": outcome in ("killed", "already"), "outcome": outcome}
-
-    def run_command(
-        self,
-        session_id: str,
-        command: str,
-        *,
-        timeout: int = DEFAULT_COMMAND_TIMEOUT,
-        token_factory: TokenFactory = _new_token,
-        owner_agent_id: str | None = None,
-        output_limit: int = MAX_OUTPUT_CHARS,
-    ) -> CommandResult:
-        if not command.strip():
-            raise RemoteCommandError("command must not be empty")
-        decision = self._check_policy(command)
-        if decision is not None and not decision.allowed:
-            self._emit(
-                "command_denied",
-                session_id=session_id,
-                command=command,
-                outcome=decision.reason,
-                detail=decision.matched_pattern,
-            )
-            raise PolicyDeniedError(decision.reason)
-        session = self._get_session(session_id)
-        self._check_owner(session, owner_agent_id)
-        if session.busy:
-            raise RemoteCommandError(f"session {session_id} is busy")
-        if not session.child.isalive():
-            raise RemoteCommandError(f"session {session_id} is not alive")
-
-        token = token_factory()
-        start_marker = f"__SCM_START_{token}__"
-        exit_pattern = re.compile(rf"__SCM_EXIT_{re.escape(token)}:(\d+)")
-        remote_line = self._build_remote_line(command, token, start_marker)
-        session.busy = True
-        try:
-            session.child.sendline(remote_line)
-            session.child.expect(exit_pattern, timeout=timeout)
-            output = _extract_between_markers(str(session.child.before), start_marker)
-            exit_code = _parse_exit_marker(session.child.after, token)
-            result = CommandResult(session.id, session.host_id, command, exit_code, _tail(output, max(1, output_limit)))
-            self._emit(
-                "command_run",
-                session_id=session.id,
-                host_id=session.host_id,
-                command=command,
-                outcome=f"exit={exit_code}",
-            )
-        except pexpect.TIMEOUT:
-            output = _tail(str(session.child.before))
-            result = CommandResult(session.id, session.host_id, command, None, output, timed_out=True)
-            self._emit(
-                "command_run",
-                session_id=session.id,
-                host_id=session.host_id,
-                command=command,
-                outcome="timeout",
-            )
-        finally:
-            session.busy = False
-            session.last_used_at = time.time()
-            session.last_output = _tail(str(session.child.before))
-        return result
-
-    def start_task(
-        self,
-        session_id: str,
-        command: str,
-        *,
-        token_factory: TokenFactory = _new_token,
-        owner_agent_id: str | None = None,
-    ) -> RemoteTask:
-        if not command.strip():
-            raise RemoteCommandError("command must not be empty")
-        decision = self._check_policy(command)
-        if decision is not None and not decision.allowed:
-            self._emit(
-                "task_denied",
-                session_id=session_id,
-                command=command,
-                outcome=decision.reason,
-                detail=decision.matched_pattern,
-            )
-            raise PolicyDeniedError(decision.reason)
-        task_id = token_factory()
-        job_dir = f"{REMOTE_JOB_ROOT}/{task_id}"
-        quoted_command = shlex.quote(command)
-        script = (
-            f'job_dir="{job_dir}"; '
-            'mkdir -p "$job_dir"; '
-            'date -u +%Y-%m-%dT%H:%M:%SZ > "$job_dir/started_at"; '
-            f'({self.remote_shell} -lc {quoted_command} > "$job_dir/stdout.log" 2>&1; '
-            'status=$?; printf "%s\\n" "$status" > "$job_dir/exit_code"; '
-            'date -u +%Y-%m-%dT%H:%M:%SZ > "$job_dir/finished_at") & '
-            'pid=$!; printf "%s\\n" "$pid" > "$job_dir/pid"; printf "%s" "$pid"'
-        )
-        result = self.run_command(session_id, script, timeout=10, token_factory=lambda: f"task_{task_id}", owner_agent_id=owner_agent_id)
-        pid_match = re.search(r"(\d+)", result.output)
-        task = RemoteTask(
-            id=task_id,
-            session_id=session_id,
-            host_id=self._get_session(session_id).host_id,
-            command=command,
-            job_dir=job_dir,
-            remote_pid=int(pid_match.group(1)) if pid_match else None,
-            owner_agent_id=owner_agent_id,
-        )
-        self._tasks[task.id] = task
-        self._emit("task_started", session_id=session_id, task_id=task.id, host_id=task.host_id, command=command, outcome="ok")
-        return task
-
-    def task_status(
-        self,
-        session_id: str,
-        task_id: str,
-        *,
-        tail_lines: int = 80,
-        owner_agent_id: str | None = None,
-    ) -> dict[str, object]:
-        task = self._tasks.get(task_id)
-        if task is None:
-            raise RemoteCommandError(f"unknown task {task_id}")
-        if task.session_id != session_id:
-            raise RemoteCommandError(f"task {task_id} does not belong to session {session_id}")
-        self._check_task_owner(task, owner_agent_id)
-        safe_tail_lines = max(1, min(int(tail_lines), 500))
-        script = (
-            f'job_dir="{task.job_dir}"; '
-            'pid=$(cat "$job_dir/pid" 2>/dev/null || true); '
-            'if [ -f "$job_dir/exit_code" ]; then state=finished; exit_code=$(cat "$job_dir/exit_code"); '
-            'elif [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null; then state=running; exit_code=""; '
-            'else state=unknown; exit_code=""; fi; '
-            'printf "STATE=%s\\nPID=%s\\nEXIT=%s\\n---LOG---\\n" "$state" "$pid" "$exit_code"; '
-            f'tail -n {safe_tail_lines} "$job_dir/stdout.log" 2>/dev/null || true'
-        )
-        result = self.run_command(session_id, script, timeout=15, owner_agent_id=owner_agent_id)
-        metadata, _, log = result.output.partition("---LOG---\n")
-        fields: dict[str, str] = {}
-        for line in metadata.splitlines():
-            key, sep, value = line.partition("=")
-            if sep:
-                fields[key] = value
-        exit_text = fields.get("EXIT") or ""
-        return {
-            "task_id": task.id,
-            "session_id": session_id,
-            "host_id": task.host_id,
-            "command": task.command,
-            "job_dir": task.job_dir,
-            "state": fields.get("STATE", "unknown"),
-            "pid": fields.get("PID") or task.remote_pid,
-            "exit_code": int(exit_text) if exit_text.isdigit() else None,
-            "log_tail": log,
-        }
-
-
-    def file_write_text(
-        self,
-        session_id: str,
-        remote_path: str,
-        content: str,
-        *,
-        mode: str = "0644",
-        max_bytes: int = DEFAULT_MAX_TRANSFER_BYTES,
-        token_factory: TokenFactory = _new_token,
-        owner_agent_id: str | None = None,
-    ) -> dict[str, object]:
-        data = content.encode("utf-8")
-        return self._upload_bytes(
-            session_id,
-            data,
-            remote_path,
-            mode=mode,
-            max_bytes=max_bytes,
-            token_factory=token_factory,
-            owner_agent_id=owner_agent_id,
-        )
-
-    def file_read_text(
-        self,
-        session_id: str,
-        remote_path: str,
-        *,
-        max_bytes: int = DEFAULT_MAX_TRANSFER_BYTES,
-        token_factory: TokenFactory = _new_token,
-        owner_agent_id: str | None = None,
-    ) -> dict[str, object]:
-        result = self._download_bytes(
-            session_id,
-            remote_path,
-            max_bytes=max_bytes,
-            token_factory=token_factory,
-            owner_agent_id=owner_agent_id,
-        )
-        data = cast(bytes, result.pop("data_bytes"))
-        result["content"] = data.decode("utf-8")
-        return result
-
-    def file_write_bytes(
-        self,
-        session_id: str,
-        remote_path: str,
-        data: bytes,
-        *,
-        mode: str = "0644",
-        max_bytes: int = DEFAULT_MAX_TRANSFER_BYTES,
-        token_factory: TokenFactory = _new_token,
-        owner_agent_id: str | None = None,
-    ) -> dict[str, object]:
-        return self._upload_bytes(
-            session_id,
-            data,
-            remote_path,
-            mode=mode,
-            max_bytes=max_bytes,
-            token_factory=token_factory,
-            owner_agent_id=owner_agent_id,
-        )
-
-    def file_read_bytes(
-        self,
-        session_id: str,
-        remote_path: str,
-        *,
-        max_bytes: int = DEFAULT_MAX_TRANSFER_BYTES,
-        token_factory: TokenFactory = _new_token,
-        owner_agent_id: str | None = None,
-    ) -> dict[str, object]:
-        return self._download_bytes(
-            session_id,
-            remote_path,
-            max_bytes=max_bytes,
-            token_factory=token_factory,
-            owner_agent_id=owner_agent_id,
-        )
-
-    def file_upload(
-        self,
-        session_id: str,
-        local_path: Path | str,
-        remote_path: str,
-        *,
-        mode: str = "0644",
-        max_bytes: int = DEFAULT_MAX_TRANSFER_BYTES,
-        token_factory: TokenFactory = _new_token,
-        owner_agent_id: str | None = None,
-    ) -> dict[str, object]:
-        path = Path(local_path).expanduser()
-        if not path.is_absolute():
-            raise RemoteCommandError("local_path must be absolute")
-        if not path.is_file():
-            raise RemoteCommandError(f"local file not found: {path}")
-        size = path.stat().st_size
-        self._check_transfer_size(size, max_bytes)
-        return self._upload_bytes(
-            session_id,
-            path.read_bytes(),
-            remote_path,
-            mode=mode,
-            max_bytes=max_bytes,
-            token_factory=token_factory,
-            owner_agent_id=owner_agent_id,
-            local_path=str(path),
-        )
-
-    def file_download(
-        self,
-        session_id: str,
-        remote_path: str,
-        local_path: Path | str,
-        *,
-        max_bytes: int = DEFAULT_MAX_TRANSFER_BYTES,
-        token_factory: TokenFactory = _new_token,
-        owner_agent_id: str | None = None,
-    ) -> dict[str, object]:
-        path = Path(local_path).expanduser()
-        if not path.is_absolute():
-            raise RemoteCommandError("local_path must be absolute")
-        result = self._download_bytes(
-            session_id,
-            remote_path,
-            max_bytes=max_bytes,
-            token_factory=token_factory,
-            owner_agent_id=owner_agent_id,
-        )
-        data = cast(bytes, result.pop("data_bytes"))
-        path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_bytes(data)
-        result["local_path"] = str(path)
-        return result
-
-    def _upload_bytes(
-        self,
-        session_id: str,
-        data: bytes,
-        remote_path: str,
-        *,
-        mode: str,
-        max_bytes: int,
-        token_factory: TokenFactory,
-        owner_agent_id: str | None,
-        local_path: str | None = None,
-    ) -> dict[str, object]:
-        self._check_transfer_size(len(data), max_bytes)
-        self._validate_remote_path(remote_path)
-        b64 = base64.b64encode(data).decode("ascii")
-        sha256 = hashlib.sha256(data).hexdigest()
-        token = token_factory()
-        remote_q = shlex.quote(remote_path)
-        mode_q = shlex.quote(mode)
-        tmp_prefix = f"/tmp/hostbridge.upload.{token}"
-        tmp_b64 = f"{tmp_prefix}.b64"
-        tmp_out = f"{tmp_prefix}.out"
-        cleanup_script = f"rm -f {shlex.quote(tmp_b64)} {shlex.quote(tmp_out)}"
-        init_script = (
-            "set -e; "
-            f"target={remote_q}; "
-            'dir=$(dirname "$target"); mkdir -p "$dir"; '
-            f"rm -f {shlex.quote(tmp_b64)} {shlex.quote(tmp_out)}; "
-            f": > {shlex.quote(tmp_b64)}"
-        )
-        result = self.run_command(session_id, init_script, timeout=60, token_factory=lambda: token, owner_agent_id=owner_agent_id)
-        if result.exit_code != 0:
-            raise RemoteCommandError(result.output or f"failed to prepare upload for {remote_path}")
-        try:
-            self._stream_base64_to_remote_file(
-                session_id,
-                b64,
-                tmp_b64,
-                token=token,
-                owner_agent_id=owner_agent_id,
-            )
-            finalize_script = (
-                "set -e; "
-                f"target={remote_q}; mode={mode_q}; tmp_b64={shlex.quote(tmp_b64)}; tmp_out={shlex.quote(tmp_out)}; "
-                '{ base64 -d < "$tmp_b64" 2>/dev/null || base64 -D < "$tmp_b64"; } > "$tmp_out"; '
-                'chmod "$mode" "$tmp_out"; mv "$tmp_out" "$target"; rm -f "$tmp_b64"; '
-                f"printf 'BYTES=%s\\nSHA256=%s\\n' {len(data)} {shlex.quote(sha256)}"
-            )
-            result = self.run_command(
-                session_id,
-                finalize_script,
-                timeout=60,
-                token_factory=lambda: token,
-                owner_agent_id=owner_agent_id,
-            )
-            if result.exit_code != 0:
-                raise RemoteCommandError(result.output or f"failed to finalize upload for {remote_path}")
-        except Exception:
-            with suppress(Exception):
-                self.run_command(session_id, cleanup_script, timeout=10, token_factory=lambda: token, owner_agent_id=owner_agent_id)
-            raise
-        payload: dict[str, object] = {
-            "session_id": session_id,
-            "remote_path": remote_path,
-            "bytes": len(data),
-            "sha256": sha256,
-            "strategy": "shell_base64_chunked",
-        }
-        if local_path is not None:
-            payload["local_path"] = local_path
-        self._emit("file_uploaded", session_id=session_id, command=remote_path, outcome=f"bytes={len(data)}")
-        return payload
-
-    def _stream_base64_to_remote_file(
-        self,
-        session_id: str,
-        encoded: str,
-        remote_tmp_b64: str,
-        *,
-        token: str,
-        owner_agent_id: str | None,
-    ) -> None:
-        session = self._get_session(session_id)
-        self._check_owner(session, owner_agent_id)
-        if session.busy:
-            raise RemoteCommandError(f"session {session_id} is busy")
-        if not session.child.isalive():
-            raise RemoteCommandError(f"session {session_id} is not alive")
-
-        heredoc = f"__HOSTBRIDGE_UPLOAD_{token}__"
-        done_pattern = re.compile(rf"__HOSTBRIDGE_UPLOAD_DONE_{re.escape(token)}__:(\d+)")
-        chunk_size = max(4, int(UPLOAD_BASE64_CHUNK_CHARS))
-        session.busy = True
-        try:
-            session.child.send(f"cat >> {shlex.quote(remote_tmp_b64)} <<'{heredoc}'\n")
-            for offset in range(0, len(encoded), chunk_size):
-                session.child.send(encoded[offset : offset + chunk_size])
-            session.child.send(f"\n{heredoc}\nprintf '\\n__HOSTBRIDGE_UPLOAD_DONE_{token}__:%s\\n' \"$?\"\n")
-            session.child.expect(done_pattern, timeout=60)
-            marker = session.child.after
-            text = marker.group(0) if hasattr(marker, "group") else str(marker)
-            match = re.search(r":(\d+)", text)
-            if match is None or int(match.group(1)) != 0:
-                raise RemoteCommandError(f"failed to stream upload chunk for {session_id}")
-        finally:
-            session.busy = False
-            session.last_used_at = time.time()
-            session.last_output = _tail(str(session.child.before))
-
-    def _download_bytes(
-        self,
-        session_id: str,
-        remote_path: str,
-        *,
-        max_bytes: int,
-        token_factory: TokenFactory,
-        owner_agent_id: str | None,
-    ) -> dict[str, object]:
-        self._validate_remote_path(remote_path)
-        token = token_factory()
-        remote_q = shlex.quote(remote_path)
-        metadata_script = (
-            "set -e; "
-            f"target={remote_q}; "
-            'bytes=$(wc -c < "$target" | tr -d " "); '
-            f"if [ \"$bytes\" -gt {int(max_bytes)} ]; then echo 'FILE_TOO_LARGE remote pull required' >&2; exit 73; fi; "
-            "if command -v sha256sum >/dev/null 2>&1; then sha=$(sha256sum \"$target\" | awk '{print $1}'); "
-            "else sha=$(shasum -a 256 \"$target\" | awk '{print $1}'); fi; "
-            "printf 'BYTES=%s\\nSHA256=%s\\n' \"$bytes\" \"$sha\""
-        )
-        result = self.run_command(
-            session_id,
-            metadata_script,
-            timeout=60,
-            token_factory=lambda: token,
-            owner_agent_id=owner_agent_id,
-        )
-        if result.exit_code == 73:
-            self._raise_remote_pull_required(max_bytes)
-        if result.exit_code != 0:
-            raise RemoteCommandError(result.output or f"failed to download {remote_path}")
-        fields: dict[str, str] = {}
-        for line in result.output.splitlines():
-            key, _, value = line.partition("=")
-            if key:
-                fields[key] = value
-        byte_count = int(fields.get("BYTES") or 0)
-        self._check_transfer_size(byte_count, max_bytes)
-        chunks: list[bytes] = []
-        chunk_size = max(1, int(DOWNLOAD_CHUNK_BYTES))
-        for index in range((byte_count + chunk_size - 1) // chunk_size):
-            chunk_script = (
-                "set -e; "
-                f"dd if={remote_q} bs={chunk_size} skip={index} count=1 2>/dev/null | base64"
-            )
-            output_limit = max(MAX_OUTPUT_CHARS, chunk_size * 2 + 4096)
-            result = self.run_command(
-                session_id,
-                chunk_script,
-                timeout=60,
-                token_factory=lambda: token,
-                owner_agent_id=owner_agent_id,
-                output_limit=output_limit,
-            )
-            if result.exit_code != 0:
-                raise RemoteCommandError(result.output or f"failed to download chunk {index} from {remote_path}")
-            chunks.append(base64.b64decode("".join(result.output.split())))
-        data = b"".join(chunks)
-        sha256 = hashlib.sha256(data).hexdigest()
-        remote_sha = fields.get("SHA256") or sha256
-        if remote_sha != "ignored" and sha256 != remote_sha:
-            raise RemoteCommandError("download checksum mismatch")
-        self._emit("file_downloaded", session_id=session_id, command=remote_path, outcome=f"bytes={len(data)}")
-        return {
-            "session_id": session_id,
-            "remote_path": remote_path,
-            "bytes": len(data),
-            "sha256": remote_sha,
-            "strategy": "shell_base64_chunked",
-            "data_bytes": data,
-        }
-
-    def _validate_remote_path(self, remote_path: str) -> None:
-        if not remote_path or remote_path.strip() in {"", "/"}:
-            raise RemoteCommandError("remote_path must not be empty or root")
-
-    def _check_transfer_size(self, size: int, max_bytes: int) -> None:
-        if size > int(max_bytes):
-            self._raise_remote_pull_required(max_bytes)
-
-    def _raise_remote_pull_required(self, max_bytes: int) -> None:
-        raise RemoteCommandError(
-            f"file exceeds HostBridge shell transfer limit ({int(max_bytes)} bytes); use remote pull (curl/wget/modelscope/git) for large files"
-        )
-
-    def write(self, session_id: str, text: str, *, owner_agent_id: str | None = None) -> dict[str, object]:
-        return self.send(session_id, f"{text}\n", owner_agent_id=owner_agent_id)
-
-    def send(self, session_id: str, text: str, *, owner_agent_id: str | None = None) -> dict[str, object]:
-        session = self._get_session(session_id)
-        self._check_owner(session, owner_agent_id)
-        if session.busy:
-            raise RemoteCommandError(f"session {session_id} is busy")
-        if not session.child.isalive():
-            raise RemoteCommandError(f"session {session_id} is not alive")
-        session.child.send(text)
-        session.last_used_at = time.time()
-        return {"session_id": session_id, "written": True}
-
-    def read(
-        self,
-        session_id: str,
-        *,
-        timeout: float = 1.0,
-        max_chars: int = 20_000,
-        owner_agent_id: str | None = None,
-    ) -> dict[str, object]:
-        session = self._get_session(session_id)
-        self._check_owner(session, owner_agent_id)
-        chunks: list[str] = []
-        deadline = time.time() + max(0.0, timeout)
-        while len("".join(chunks)) < max_chars:
-            remaining = max(0.0, deadline - time.time())
-            if remaining <= 0 and chunks:
-                break
-            try:
-                chunk = session.child.read_nonblocking(size=4096, timeout=remaining)
-            except (pexpect.TIMEOUT, pexpect.EOF):
-                break
-            if not chunk:
-                break
-            chunks.append(str(chunk))
-        output = _tail("".join(chunks), max_chars)
-        session.last_output = output or session.last_output
-        session.last_used_at = time.time()
-        return {"session_id": session_id, "output": output, "alive": session.child.isalive()}
-
-    def _get_session(self, session_id: str) -> RemoteSession:
-        try:
-            return self._sessions[session_id]
-        except KeyError as exc:
-            raise RemoteCommandError(f"unknown session {session_id}") from exc
-
-    def _check_owner(self, session: RemoteSession, owner_agent_id: str | None, *, force: bool = False) -> None:
-        if force or owner_agent_id is None or session.owner_agent_id is None:
-            return
-        if owner_agent_id != session.owner_agent_id:
-            raise RemoteCommandError(f"session {session.id} is owned by another agent")
-
-    def _check_task_owner(self, task: RemoteTask, owner_agent_id: str | None, *, force: bool = False) -> None:
-        if force or owner_agent_id is None or task.owner_agent_id is None:
-            return
-        if owner_agent_id != task.owner_agent_id:
-            raise RemoteCommandError(f"task {task.id} is owned by another agent")
-
-    def _check_host_session_limit(self, host_id: str) -> None:
-        if self._max_sessions_per_host <= 0:
-            return
-        open_count = sum(1 for session in self._sessions.values() if session.host_id == host_id and session.child.isalive())
-        if open_count >= self._max_sessions_per_host:
-            raise RemoteCommandError(f"host {host_id} reached session limit {self._max_sessions_per_host}")
-
-    def _build_remote_line(self, command: str, token: str, start_marker: str) -> str:
-        encoded_command = base64.b64encode(command.encode("utf-8")).decode("ascii")
-        return (
-            f"__scm_cmd=$(printf %s {shlex.quote(encoded_command)} | {{ base64 --decode 2>/dev/null || base64 -D; }}); "
-            f"printf '\\n{start_marker}\\n'; "
-            f"{self.remote_shell} -lc \"$__scm_cmd\"; "
-            "__scm_status=$?; "
-            f"printf '\\n__SCM_EXIT_{token}:%s\\n' \"$__scm_status\""
-        )
-
-    @staticmethod
-    def _describe_session(session: RemoteSession) -> dict[str, object]:
-        return {
-            "session_id": session.id,
-            "host_id": session.host_id,
-            "label": session.label,
-            "command": session.command,
-            "args": session.args,
-            "alive": session.child.isalive(),
-            "busy": session.busy,
-            "owner_agent_id": session.owner_agent_id,
-            "created_at": session.created_at,
-            "last_used_at": session.last_used_at,
-        }