colabapi 0.1.0__py3-none-any.whl

colabapi/config.py

@@ -0,0 +1,148 @@
+"""Local configuration and session state.
+
+Everything colabapi stores lives under the user's XDG config/state directories.
+The only thing ever written to disk is non-sensitive session metadata (chosen
+runtime, the `colab` session name, timestamps) plus a couple of preferences. No
+Google credentials are ever requested, transmitted, or stored. See README
+"Privacy".
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+
+def _xdg(env: str, default: Path) -> Path:
+    value = os.environ.get(env)
+    return Path(value) if value else default
+
+
+HOME = Path.home()
+CONFIG_DIR = _xdg("XDG_CONFIG_HOME", HOME / ".config") / "colabapi"
+STATE_DIR = _xdg("XDG_STATE_HOME", HOME / ".local" / "state") / "colabapi"
+DATA_DIR = _xdg("XDG_DATA_HOME", HOME / ".local" / "share") / "colabapi"
+
+CONFIG_FILE = CONFIG_DIR / "config.json"
+SESSION_FILE = STATE_DIR / "session.json"  # legacy single-session file (migrated)
+SESSIONS_FILE = STATE_DIR / "sessions.json"  # current multi-session registry
+
+
+def ensure_dirs() -> None:
+    for d in (CONFIG_DIR, STATE_DIR, DATA_DIR):
+        d.mkdir(parents=True, exist_ok=True)
+    # Keep the tree private (config may hold non-Google tokens like preferences).
+    try:
+        os.chmod(DATA_DIR, 0o700)
+        os.chmod(STATE_DIR, 0o700)
+    except OSError:
+        pass
+
+
+@dataclass
+class Config:
+    """User preferences. Never contains Google credentials."""
+
+    default_runtime: str = "cpu"
+    keepalive_interval: int = 60  # seconds between supervisory keep-alive checks
+    monitor_interval: float = 2.0  # seconds between resource refreshes
+
+    @classmethod
+    def load(cls) -> "Config":
+        if CONFIG_FILE.exists():
+            data = json.loads(CONFIG_FILE.read_text())
+            known = {k: v for k, v in data.items() if k in cls.__dataclass_fields__}
+            return cls(**known)
+        return cls()
+
+    def save(self) -> None:
+        ensure_dirs()
+        CONFIG_FILE.write_text(json.dumps(asdict(self), indent=2))
+
+
+@dataclass
+class Session:
+    """Local bookkeeping for the runtime `colab` currently has active.
+
+    The official CLI owns the real connection; colabapi only records which
+    runtime we asked for and when, so it can show uptime / estimated time left.
+    """
+
+    runtime: str = "cpu"
+    started_at: Optional[float] = None  # epoch seconds when `colab new` succeeded
+    max_lifetime_hours: float = 12.0  # absolute Colab cap (informational estimate)
+    name: Optional[str] = None  # the `colab` session name colabapi created (passed as -s)
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def load(cls) -> Optional["Session"]:
+        if not SESSION_FILE.exists():
+            return None
+        data = json.loads(SESSION_FILE.read_text())
+        known = {k: v for k, v in data.items() if k in cls.__dataclass_fields__}
+        return cls(**known)
+
+    def save(self) -> None:
+        ensure_dirs()
+        SESSION_FILE.write_text(json.dumps(asdict(self), indent=2))
+
+    @staticmethod
+    def clear() -> None:
+        SESSION_FILE.unlink(missing_ok=True)
+
+    @property
+    def is_active(self) -> bool:
+        return self.started_at is not None
+
+
+@dataclass
+class SessionStore:
+    """Registry of every named session colabapi currently manages.
+
+    colabapi can own several `colab` sessions at once (each created via
+    `colabapi run` with its own name). This is the single source of truth for the
+    session pickers used by shell / stop / monitor.
+    """
+
+    sessions: list[Session] = field(default_factory=list)
+
+    @classmethod
+    def load(cls) -> "SessionStore":
+        if SESSIONS_FILE.exists():
+            data = json.loads(SESSIONS_FILE.read_text())
+            items = []
+            for d in data.get("sessions", []):
+                known = {k: v for k, v in d.items() if k in Session.__dataclass_fields__}
+                items.append(Session(**known))
+            return cls(items)
+        # One-time migration from the legacy single-session file.
+        legacy = Session.load()
+        store = cls([legacy] if (legacy and legacy.is_active) else [])
+        if legacy:
+            store.save()
+            Session.clear()
+        return store
+
+    def save(self) -> None:
+        ensure_dirs()
+        SESSIONS_FILE.write_text(
+            json.dumps({"sessions": [asdict(s) for s in self.sessions]}, indent=2)
+        )
+
+    def add(self, session: Session) -> None:
+        self.sessions = [s for s in self.sessions if s.name != session.name]
+        self.sessions.append(session)
+        self.save()
+
+    def remove(self, name: str) -> None:
+        self.sessions = [s for s in self.sessions if s.name != name]
+        self.save()
+
+    def get(self, name: str) -> Optional[Session]:
+        return next((s for s in self.sessions if s.name == name), None)
+
+    def active(self) -> list[Session]:
+        return [s for s in self.sessions if s.is_active and s.name]

colabapi/keepalive.py

@@ -0,0 +1,64 @@
+"""Supervisory keep-alive health check.
+
+The *primary* keep-alive is Google's own: the official `colab` CLI pings Colab's
+sanctioned tunnel endpoint on an interval to hold off the idle timeout. This
+module is only a belt-and-suspenders supervisor. It runs a trivial command on
+the runtime once a minute to confirm the session is still reachable, and records
+failures so the systemd service log surfaces a silent death of Google's daemon.
+
+It addresses the IDLE timeout only; it cannot and does not try to defeat Colab's
+absolute max-lifetime cap, and it stays gentle (one tiny command per interval) so
+it looks like normal use, not abuse.
+
+Honesty note for users: aggressive keep-alive or holding a GPU runtime idle just
+to keep it can get a Google account flagged. Keep the interval reasonable.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Callable, Optional
+
+RunRemote = Callable[[str], str]
+
+# Minimal, cheap Python run on the VM (via `colab exec`) to confirm the kernel is
+# still reachable. `colab exec` executes Python, not shell, so this is Python.
+_PING = "import time; open('/tmp/.colabapi_alive','w').write(str(time.time())); print('ok')"
+
+
+class KeepAlive:
+    def __init__(self, run_remote: RunRemote, interval: int = 60,
+                 on_error: Optional[Callable[[Exception], None]] = None):
+        self.run_remote = run_remote
+        self.interval = max(interval, 30)
+        self.on_error = on_error
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self.last_ok: Optional[float] = None
+        self.failures = 0
+
+    def _loop(self) -> None:
+        while not self._stop.is_set():
+            try:
+                out = self.run_remote(_PING)
+                if "ok" in out:
+                    self.last_ok = time.time()
+                    self.failures = 0
+            except Exception as exc:  # noqa: BLE001 - reported via callback
+                self.failures += 1
+                if self.on_error:
+                    self.on_error(exc)
+            self._stop.wait(self.interval)
+
+    def start(self) -> None:
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._loop, name="colabapi-keepalive", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread:
+            self._thread.join(timeout=2)

colabapi/monitor.py

@@ -0,0 +1,145 @@
+"""Live CPU / RAM / GPU monitor for a connected Colab runtime.
+
+Stats are read from *inside* the runtime by executing a small Python snippet over
+the same tunnel used for the shell (via `colab exec`, which runs Python), so the
+monitor reflects the Colab VM, not your local machine. Rendering is decoupled
+from transport: pass any callable that runs Python on the runtime and returns its
+stdout.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Callable
+
+from rich.console import Group
+from rich.live import Live
+from rich.panel import Panel
+from rich.progress_bar import ProgressBar
+from rich.table import Table
+from rich.text import Text
+
+RunRemote = Callable[[str], str]
+
+# One Python program (run on the VM via `colab exec`) that emits CPU%, memory
+# (MiB), and one "GPU <csv>" line per GPU. CPU/RAM come from psutil (with a
+# /proc/meminfo fallback); GPU comes from nvidia-smi via subprocess. No GPU lines
+# simply means a CPU-only runtime.
+_STATS_SNIPPET = r'''
+import subprocess
+try:
+    import psutil
+    c = psutil.cpu_percent(interval=0.3)
+    m = psutil.virtual_memory()
+    print("CPU %.1f" % c)
+    print("MEM %d %d" % (m.used // 1048576, m.total // 1048576))
+except Exception:
+    try:
+        d = {}
+        with open("/proc/meminfo") as f:
+            for line in f:
+                p = line.split()
+                d[p[0].rstrip(":")] = int(p[1])
+        total = d["MemTotal"] // 1024
+        avail = d.get("MemAvailable", d.get("MemFree", 0)) // 1024
+        print("CPU 0.0")
+        print("MEM %d %d" % (total - avail, total))
+    except Exception:
+        print("CPU 0.0")
+        print("MEM 0 0")
+try:
+    out = subprocess.run(
+        ["nvidia-smi",
+         "--query-gpu=name,utilization.gpu,memory.used,memory.total,temperature.gpu",
+         "--format=csv,noheader,nounits"],
+        capture_output=True, text=True, timeout=5).stdout
+    for line in out.strip().splitlines():
+        if line.strip():
+            print("GPU " + line)
+except Exception:
+    pass
+'''
+
+
+def _bar(used: float, total: float, label: str, suffix: str) -> Table:
+    pct = (used / total * 100) if total else 0.0
+    grid = Table.grid(expand=True)
+    grid.add_column(width=12)
+    grid.add_column(ratio=1)
+    grid.add_column(width=22, justify="right")
+    grid.add_row(
+        Text(label, style="bold cyan"),
+        ProgressBar(total=100, completed=min(pct, 100), width=None),
+        Text(suffix, style="dim"),
+    )
+    return grid
+
+
+def _parse_cpu_mem(out: str) -> tuple[float, float, float]:
+    cpu = used = total = 0.0
+    for line in out.splitlines():
+        parts = line.split()
+        if parts and parts[0] == "CPU":
+            cpu = float(parts[1])
+        elif parts and parts[0] == "MEM":
+            used, total = float(parts[1]), float(parts[2])
+    return cpu, used, total
+
+
+def _parse_gpu(out: str) -> list[dict]:
+    gpus = []
+    for line in out.splitlines():
+        if not line.startswith("GPU "):
+            continue
+        cells = [c.strip() for c in line[4:].split(",")]
+        if len(cells) >= 5:
+            gpus.append(
+                {
+                    "name": cells[0],
+                    "util": float(cells[1] or 0),
+                    "mem_used": float(cells[2] or 0),
+                    "mem_total": float(cells[3] or 0),
+                    "temp": float(cells[4] or 0),
+                }
+            )
+    return gpus
+
+
+def build_panel(run_remote: RunRemote, session_line: str = "") -> Panel:
+    out = run_remote(_STATS_SNIPPET)
+    cpu, mem_used, mem_total = _parse_cpu_mem(out)
+    gpus = _parse_gpu(out)
+
+    rows = [
+        _bar(cpu, 100, "CPU", f"{cpu:.0f}%"),
+        _bar(mem_used, mem_total, "RAM", f"{mem_used/1024:.1f} / {mem_total/1024:.1f} GiB"),
+    ]
+    for i, g in enumerate(gpus):
+        rows.append(
+            _bar(g["util"], 100, f"GPU{i}", f"{g['util']:.0f}%  {g['temp']:.0f}°C")
+        )
+        rows.append(
+            _bar(
+                g["mem_used"],
+                g["mem_total"],
+                "  VRAM",
+                f"{g['mem_used']/1024:.1f} / {g['mem_total']/1024:.1f} GiB",
+            )
+        )
+    if not gpus:
+        rows.append(Text("  No GPU on this runtime (CPU-only).", style="dim"))
+
+    title = "colabapi runtime monitor"
+    subtitle = session_line or "Ctrl+C to exit monitor"
+    return Panel(Group(*rows), title=title, subtitle=subtitle, border_style="cyan")
+
+
+def live_monitor(run_remote: RunRemote, session_line_fn: Callable[[], str], interval: float = 2.0) -> None:
+    """Render the monitor until interrupted with Ctrl+C."""
+    with Live(refresh_per_second=4, screen=False) as live:
+        try:
+            while True:
+                live.update(build_panel(run_remote, session_line_fn()))
+                time.sleep(interval)
+        except KeyboardInterrupt:
+            pass

colabapi/runtime.py

@@ -0,0 +1,85 @@
+"""Colab runtime (accelerator) catalog + mapping to `colab new` flags.
+
+Google exposes no API that says which runtimes an account may allocate, so this
+is a static catalog of the options the official CLI accepts, annotated with the
+tier each typically requires. colabapi shows the menu and flags paid tiers; the
+browser/Google is the source of truth for what actually gets allocated (a free
+account asking for an A100 will simply be refused by Colab).
+
+`colab_flags` is the argument list handed to `colab new`, kept here so the whole
+accelerator mapping lives in one place. Validated against google-colab-cli as
+documented mid-2026 (GPUs: T4, L4, G4, H100, A100; TPUs: v5e1, v6e1).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class RuntimeType:
+    key: str
+    label: str
+    accelerator: str
+    tier: str  # "free", "pro", "pro+", "paid"
+    notes: str
+    colab_flags: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def free(self) -> bool:
+        return self.tier == "free"
+
+
+# Ordered most-accessible first.
+RUNTIMES: list[RuntimeType] = [
+    RuntimeType(
+        key="cpu", label="CPU", accelerator="None", tier="free",
+        notes="Always available. Good for lightweight demos and I/O work.",
+        colab_flags=(),
+    ),
+    RuntimeType(
+        key="t4", label="T4 GPU", accelerator="NVIDIA T4 (16 GB)", tier="free",
+        notes="Baseline free GPU. Rate-limited; availability varies.",
+        colab_flags=("--gpu", "T4"),
+    ),
+    RuntimeType(
+        key="l4", label="L4 GPU", accelerator="NVIDIA L4 (24 GB)", tier="pro",
+        notes="Usually Pro/Pay-As-You-Go; occasionally free.",
+        colab_flags=("--gpu", "L4"),
+    ),
+    RuntimeType(
+        key="g4", label="G4 GPU", accelerator="RTX PRO 6000 Blackwell (~96 GB)", tier="pro+",
+        notes="High-VRAM Blackwell option; Pro+/PAYG.",
+        colab_flags=("--gpu", "G4"),
+    ),
+    RuntimeType(
+        key="a100", label="A100 GPU", accelerator="NVIDIA A100 (40 GB)", tier="pro+",
+        notes="Pro+/PAYG; limited availability; high compute-unit burn.",
+        colab_flags=("--gpu", "A100"),
+    ),
+    RuntimeType(
+        key="h100", label="H100 GPU", accelerator="NVIDIA H100 (80 GB)", tier="pro+",
+        notes="Newest, highest compute-unit burn rate; Pro+/PAYG.",
+        colab_flags=("--gpu", "H100"),
+    ),
+    RuntimeType(
+        key="tpu-v5e", label="TPU v5e", accelerator="Cloud TPU v5e-1", tier="paid",
+        notes="Paid users; ~197 TFLOPs / 48 GB per core config.",
+        colab_flags=("--tpu", "v5e1"),
+    ),
+    RuntimeType(
+        key="tpu-v6e", label="TPU v6e", accelerator="Cloud TPU v6e-1", tier="paid",
+        notes="Newest TPU; paid users.",
+        colab_flags=("--tpu", "v6e1"),
+    ),
+]
+
+RUNTIME_BY_KEY = {r.key: r for r in RUNTIMES}
+
+
+def get(key: str) -> RuntimeType | None:
+    return RUNTIME_BY_KEY.get(key)
+
+
+def available_for_free() -> list[RuntimeType]:
+    return [r for r in RUNTIMES if r.free]

colabapi/service.py

@@ -0,0 +1,73 @@
+"""systemd user-service integration.
+
+`colabapi service install` drops a user-level systemd unit that runs the
+keep-alive/tunnel daemon so the session survives after you log out of the VPS.
+User-level (systemctl --user) is preferred: it needs no root and keeps colabapi
+scoped to the invoking user. A --system flag is offered for headless servers
+where lingering user services are undesirable.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+UNIT_NAME = "colabapi.service"
+USER_UNIT_DIR = Path.home() / ".config" / "systemd" / "user"
+
+_UNIT_TEMPLATE = """\
+[Unit]
+Description=colabapi: persistent Google Colab runtime tunnel + keep-alive
+Documentation=https://github.com/lil-limbo/colabapi
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart={exec_path} daemon --foreground
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def _colabapi_path() -> str:
+    return shutil.which("colabapi") or str(Path.home() / ".local" / "bin" / "colabapi")
+
+
+def _systemctl(*args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["systemctl", "--user", *args], capture_output=True, text=True)
+
+
+def install(enable: bool = True, start: bool = False) -> str:
+    USER_UNIT_DIR.mkdir(parents=True, exist_ok=True)
+    unit_path = USER_UNIT_DIR / UNIT_NAME
+    unit_path.write_text(_UNIT_TEMPLATE.format(exec_path=_colabapi_path()))
+    _systemctl("daemon-reload")
+    if enable:
+        _systemctl("enable", UNIT_NAME)
+    if start:
+        _systemctl("start", UNIT_NAME)
+    # Enable lingering so the user service runs without an active login session.
+    subprocess.run(["loginctl", "enable-linger", os.environ.get("USER", "")],
+                   capture_output=True, text=True)
+    return str(unit_path)
+
+
+def uninstall() -> None:
+    _systemctl("disable", "--now", UNIT_NAME)
+    unit_path = USER_UNIT_DIR / UNIT_NAME
+    unit_path.unlink(missing_ok=True)
+    _systemctl("daemon-reload")
+
+
+def status() -> str:
+    return _systemctl("status", UNIT_NAME).stdout or "colabapi service not installed"
+
+
+def is_installed() -> bool:
+    return (USER_UNIT_DIR / UNIT_NAME).exists()

colabapi/shellview.py

@@ -0,0 +1,108 @@
+"""Open an interactive Colab shell with a live resource monitor above it.
+
+When tmux is available locally we build a split window: a small top pane runs the
+colabapi monitor for the chosen session, and the bottom pane runs the real
+interactive shell (`colab console -s <name>`). The session name is shown in the
+tmux status bar. When the shell exits, the whole layout tears down.
+
+If tmux is not installed we fall back to printing a one-shot monitor snapshot,
+then handing the terminal straight to `colab console`.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+
+from rich.console import Console
+
+from .colabcli import ColabCLI
+
+console = Console()
+
+# Height (rows) of the monitor pane on top.
+_MONITOR_ROWS = 11
+
+
+def _child_env(colab: ColabCLI) -> dict:
+    return colab._child_env()
+
+
+def open_shell(colab: ColabCLI, name: str) -> int:
+    """Open the shell for session `name`, with a live monitor on top if possible."""
+    colab.session = name
+    if shutil.which("tmux"):
+        return _open_tmux(colab, name)
+    return _open_plain(colab, name)
+
+
+def _open_tmux(colab: ColabCLI, name: str) -> int:
+    exe = colab.require()
+    py = sys.executable or "python3"
+    tmux_ses = f"colabapi_{name}_{os.getpid()}"
+
+    # Env is embedded directly in each pane command, because tmux panes do not
+    # reliably inherit the environment of the client that creates the session.
+    env_prefix = (
+        f"COLABAPI_COLAB_BIN={shlex.quote(exe)} "
+        f"OAUTHLIB_RELAX_TOKEN_SCOPE=1 "
+    )
+    monitor_cmd = env_prefix + f"{shlex.quote(py)} -m colabapi.cli _panemonitor {shlex.quote(name)}"
+    # When the shell exits, kill the whole tmux session so `attach` returns and we
+    # clean up (otherwise the monitor pane would keep the session alive).
+    console_cmd = (
+        env_prefix
+        + f"{shlex.quote(exe)} console -s {shlex.quote(name)}; "
+        + f"tmux kill-session -t {shlex.quote(tmux_ses)} 2>/dev/null"
+    )
+
+    env = _child_env(colab)
+
+    def tmux(*args: str) -> subprocess.CompletedProcess:
+        return subprocess.run(["tmux", *args], env=env,
+                              stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+    # Top pane: the live monitor. Window name = session name.
+    tmux("new-session", "-d", "-s", tmux_ses, "-n", name, monitor_cmd)
+    # Bottom pane: the interactive shell.
+    tmux("split-window", "-v", "-t", tmux_ses, console_cmd)
+    # Keep the monitor pane small and focus the shell.
+    tmux("resize-pane", "-t", f"{tmux_ses}.0", "-y", str(_MONITOR_ROWS))
+    tmux("select-pane", "-t", f"{tmux_ses}.1")
+    # A distinct prefix (Ctrl-a) avoids clashing with the remote tmux's Ctrl-b.
+    tmux("set-option", "-t", tmux_ses, "prefix", "C-a")
+    tmux("set-option", "-t", tmux_ses, "status", "on")
+    tmux("set-option", "-t", tmux_ses, "status-style", "bg=colour24,fg=white")
+    tmux("set-option", "-t", tmux_ses, "status-left", f" colabapi ❯ {name} ")
+    tmux("set-option", "-t", tmux_ses, "status-left-length", "48")
+    tmux("set-option", "-t", tmux_ses, "status-right", " Ctrl-a d to detach ")
+
+    console.print(f"[green]Opening[/] [cyan]{name}[/]: monitor on top, shell below. "
+                  "[dim](tmux prefix is Ctrl-a; type 'exit' to close)[/]")
+    code = subprocess.run(["tmux", "attach-session", "-t", tmux_ses], env=env).returncode
+    tmux("kill-session", "-t", tmux_ses)  # no-op if already gone
+    console.print(f"[dim]Shell closed. Session '{name}' is still running "
+                  "(use `colabapi stop` to end it).[/]")
+    return code
+
+
+def _open_plain(colab: ColabCLI, name: str) -> int:
+    """Fallback without tmux: print a monitor snapshot, then hand over the shell."""
+    from . import monitor as monitor_mod
+
+    def run_remote(code: str) -> str:
+        res = colab.exec_code(code)
+        return res.stdout if res.stdout.strip() else res.stderr
+
+    console.print("[dim]tmux not found; showing a one-shot monitor snapshot, then the shell.[/]")
+    try:
+        console.print(monitor_mod.build_panel(run_remote, f"session {name}"))
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[dim](could not read monitor: {exc})[/]")
+    console.print(f"[green]Terminal into[/] [cyan]{name}[/]. Type 'exit' or Ctrl-D to return.\n")
+    code = colab.console()
+    console.print(f"\n[dim]Shell closed. Session '{name}' is still running.[/]")
+    return code

colabapi/timing.py

@@ -0,0 +1,53 @@
+"""Session-timing helpers.
+
+Colab enforces two independent limits:
+  * an ABSOLUTE max lifetime (roughly 12h free, longer on paid tiers) that
+    nothing can extend, and
+  * an IDLE timeout that disconnects a runtime doing nothing. This is the one
+    the keep-alive addresses.
+
+colabapi can only *estimate* the absolute end because Google does not publish an
+exact per-session deadline. The estimate is based on when the runtime came up
+plus the tier's typical cap, and is clearly labeled as an estimate.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+
+def human_duration(seconds: float) -> str:
+    seconds = int(max(seconds, 0))
+    h, rem = divmod(seconds, 3600)
+    m, s = divmod(rem, 60)
+    if h:
+        return f"{h}h {m:02d}m"
+    if m:
+        return f"{m}m {s:02d}s"
+    return f"{s}s"
+
+
+def estimated_end(started_at: Optional[float], max_lifetime_hours: float) -> Optional[float]:
+    if not started_at:
+        return None
+    return started_at + max_lifetime_hours * 3600
+
+
+def remaining(started_at: Optional[float], max_lifetime_hours: float) -> Optional[float]:
+    end = estimated_end(started_at, max_lifetime_hours)
+    if end is None:
+        return None
+    return end - time.time()
+
+
+def session_line(started_at: Optional[float], max_lifetime_hours: float) -> str:
+    if not started_at:
+        return "runtime not started"
+    up = time.time() - started_at
+    rem = remaining(started_at, max_lifetime_hours)
+    if rem is None:
+        return f"up {human_duration(up)}"
+    if rem <= 0:
+        return f"up {human_duration(up)}, past estimated limit (may disconnect any moment)"
+    return f"up {human_duration(up)} · ~{human_duration(rem)} left (est.)"