simulo 0.7.1__tar.gz → 0.9.0__tar.gz

{simulo-0.7.1/src/simulo.egg-info → simulo-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.7.1
+Version: 0.9.0
 Summary: Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause
@@ -15,7 +15,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: simulo-interfaces<0.2,>=0.1
+Requires-Dist: simulo-interfaces<0.3,>=0.2
+Requires-Dist: mcap<2,>=1.3
 Provides-Extra: dev
 Requires-Dist: black>=24.0; extra == "dev"
 Requires-Dist: isort>=5.13; extra == "dev"

{simulo-0.7.1 → simulo-0.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.7.1"
+version = "0.9.0"
 description = "Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud."
 readme = "PYPI.md"
 requires-python = ">=3.11"
@@ -20,10 +20,12 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Typing :: Typed",
 ]
-# Torch-free by construction: depends only on the contract layer. Heavy
-# imports (e.g. torch) belong inside the user's `runtime.imports()` guard,
-# resolved only at job-execution time — never in this distribution.
-dependencies = ["simulo-interfaces>=0.1,<0.2"]
+# Torch-free by construction: depends only on the contract layer and mcap.
+# Heavy imports (e.g. torch) belong inside the user's `runtime.imports()`
+# guard, resolved only at job-execution time — never in this distribution.
+# mcap: used by `simulo recordings` to read back a downloaded recording and
+# verify it (message count) — MIT-licensed, deps only lz4+zstandard.
+dependencies = ["simulo-interfaces>=0.2,<0.3", "mcap>=1.3,<2"]
 
 [project.optional-dependencies]
 dev = ["black>=24.0", "isort>=5.13", "ruff>=0.5", "mypy>=1.10", "pytest>=8.2", "build>=1.2", "twine>=5.1"]

{simulo-0.7.1 → simulo-0.9.0}/src/simulo/_client/app.py

@@ -70,6 +70,33 @@ def spawn_recorder() -> Iterator[list["JobHandle"]]:
         _SPAWN_RECORDER = previous
 
 
+# ---------------------------------------------------------------------------
+# Viewstream ambient signal — `simulo run --viewstream` scopes this for the
+# duration of one submit so a cloud `spawn()` deep inside the user's
+# @app.local_entrypoint (which `simulo run` does not call directly) can
+# attach it to the job-create call. Deliberately NOT a `spawn()`/`submit()`
+# kwarg: those kwargs feed the job's `args`, whose canonical form is the
+# `package_id` sha256 — a streaming flag must never change the package hash
+# (the live-visualization plan's wire-contract rule). Mirrors the
+# `spawn_recorder` pattern above for the same "can't thread a return value
+# through arbitrary user code" reason.
+# ---------------------------------------------------------------------------
+
+_VIEWSTREAM_REQUESTED = False
+
+
+@contextlib.contextmanager
+def viewstream_requested(enabled: bool) -> Iterator[None]:
+    """Scope ``--viewstream`` for one ``simulo run`` submit call."""
+    global _VIEWSTREAM_REQUESTED
+    previous = _VIEWSTREAM_REQUESTED
+    _VIEWSTREAM_REQUESTED = enabled
+    try:
+        yield
+    finally:
+        _VIEWSTREAM_REQUESTED = previous
+
+
 @dataclass
 class JobSpec:
     """Recorded metadata for one ``@app.job``-decorated function."""
@@ -125,8 +152,17 @@ def _spawn_local(job_name: str, package_path: Path) -> JobHandle:
     return JobHandle(job_id, package_path, job_name)
 
 
-def _spawn_cloud(job_name: str, package_path: Path, creds: Optional[dict[str, Any]]) -> JobHandle:
-    """Tar the bundle, upload it, create the job, and return a cloud JobHandle."""
+def _spawn_cloud(
+    job_name: str, package_path: Path, creds: Optional[dict[str, Any]], *, viewstream: bool = False
+) -> JobHandle:
+    """Tar the bundle, upload it, create the job, and return a cloud JobHandle.
+
+    ``viewstream`` rides ONLY the job-create call, as an optional top-level
+    body field (never inside ``args``, which feeds the ``package_id`` sha256
+    — see the live-visualization plan's wire-contract rule): a package's
+    content-addressed identity must never change based on whether this
+    particular execution asked for a live stream.
+    """
     from simulo._client.packaging import MANIFEST_FILENAME, ensure_tar
     from simulo._client.submit_api import SubmitApiClient
 
@@ -151,7 +187,7 @@ def _spawn_cloud(job_name: str, package_path: Path, creds: Optional[dict[str, An
         archive_size=len(archive_bytes),
     )
     client.upload_archive(package_id, archive_bytes)
-    record = client.create_job(package_id=package_id, job_name=job_name, args=args)
+    record = client.create_job(package_id=package_id, job_name=job_name, args=args, viewstream=viewstream)
 
     return JobHandle(JobId(str(record["job_id"])), package_path, job_name, cloud=True, base_url=base_url, token=token)
 
@@ -210,7 +246,7 @@ class JobFunction:
         else:
             creds = credentials.try_get_valid_credentials()
             if _cloud_mode_active(creds):
-                handle = _spawn_cloud(self._spec.name, package_path, creds)
+                handle = _spawn_cloud(self._spec.name, package_path, creds, viewstream=_VIEWSTREAM_REQUESTED)
             else:
                 handle = _spawn_local(self._spec.name, package_path)
         _record_spawn(handle)

{simulo-0.7.1 → simulo-0.9.0}/src/simulo/_client/cli.py

@@ -25,14 +25,21 @@ PKCE loopback flow (``.claude/skills/cli-auth/SKILL.md``) and manages
 ``~/.simulo/credentials``.
 
 **Observe commands** (``simulo jobs`` / ``simulo logs`` / ``simulo result`` /
-``simulo recordings`` / ``simulo models``) talk HTTP ONLY — the thin client never reads the
-executor's run store from disk, because submit and execute behave as if on
+``simulo recordings`` / ``simulo models`` / ``simulo view``) talk HTTP ONLY — the thin client
+never reads the executor's run store from disk, because submit and execute behave as if on
 two separate machines. They target the jobs API at the base URL resolved by
 ``config.resolve_base_url`` (env override -> ``SIMULO_ENV`` preset ->
 credentials -> the local ``simulo-backend serve`` stand-in), authenticated
-with the saved credentials' bearer token when logged in. ``simulo logs`` and
-``simulo result`` take an OPTIONAL job id: omitted, they resolve the most
+with the saved credentials' bearer token when logged in. ``simulo logs``,
+``simulo result``, and ``simulo view`` take an OPTIONAL job id: omitted, they resolve the most
 recent job over the API (and announce what they resolved to on stderr).
+
+``simulo view [JOB_ID]`` opens the default browser onto a running ``--viewstream`` job's live
+3D scene: it mints a short-lived session (``POST /v1/jobs/{id}/view-session``) and opens
+``{viewerUrl}#session={token}&gateway={gatewayUrl}&job={job_id}`` — the token rides the URL
+FRAGMENT, never the query string, so it never reaches server access logs. A queued job is
+waited on with a spinner; a finished job (completed/failed/cancelled) is refused with a clear
+message; a job not started with ``--viewstream`` surfaces the server's own error.
 """
 
 from __future__ import annotations
@@ -42,25 +49,41 @@ import json
 import os
 import sys
 import time
+import urllib.parse
+import webbrowser
 from pathlib import Path, PurePath
 from typing import Any, Callable, Optional, Sequence
 
-from simulo._client import config, credentials
+from simulo._client import config, credentials, http
 from simulo._client._entrypoint import run_entrypoint
 from simulo._client._runner import JobHandle
-from simulo._client.app import App, spawn_recorder
+from simulo._client.app import App, spawn_recorder, viewstream_requested
 from simulo._client.discovery import import_app_module
 from simulo._client.jobs_api import JobsApiClient, JobsApiError, JobsApiHTTPError, JobsApiUnavailable
 from simulo._client.login import LoginError, perform_login
 from simulo._client.mode import DISCOVERY
 from simulo._client.registry import find_app
 from simulo._client.submit_api import SubmitApiClient, SubmitApiError
+from simulo._client.view_session_api import ViewSessionApiClient, ViewSessionApiError, ViewSessionApiHTTPError
 from simulo.interfaces.platform.enums import JobStatus
 from simulo.interfaces.platform.runs import TERMINAL_JOB_STATUSES
 
 #: ``--follow`` poll cadence. Module-level so tests can shrink it.
 _FOLLOW_POLL_INTERVAL_S = 0.7
 
+#: ``simulo view`` poll cadence while a resolved job is still QUEUED.
+#: Module-level (like ``_FOLLOW_POLL_INTERVAL_S`` above) so tests can shrink it.
+_VIEW_POLL_INTERVAL_S = 0.7
+#: Bounded window (live-visualization plan, "Lifecycle edges" hardening item)
+#: tolerating the worker's claim->registration gap — the mint route can 404/409
+#: briefly after a job starts running, before the worker's claim call has
+#: reported its stream endpoint. ``simulo view`` retries the mint until this
+#: many seconds have elapsed, then gives up with a clear message.
+_MINT_GAP_WINDOW_S = 90.0
+#: Retry cadence within ``_MINT_GAP_WINDOW_S``. Separate constant (not reusing
+#: ``_VIEW_POLL_INTERVAL_S``) so tests can shrink the two loops independently.
+_MINT_GAP_POLL_INTERVAL_S = 1.0
+
 # String-typed mirrors of the contract's status sets (the API sends strings).
 _TERMINAL_STATUS_STRINGS = frozenset(str(status) for status in TERMINAL_JOB_STATUSES)
 _COMPLETED_STATUS = str(JobStatus.COMPLETED)
@@ -86,8 +109,20 @@ def _resolve_client_context() -> tuple[str, Optional[str]]:
 # ---------------------------------------------------------------------------
 
 
-def _submit_app(app_file: Path, entrypoint: Optional[str], extras: Sequence[str], *, detach: bool) -> int:
-    """Import the app in discovery mode and run its entrypoint (one submit)."""
+def _submit_app(
+    app_file: Path, entrypoint: Optional[str], extras: Sequence[str], *, detach: bool, viewstream: bool = False
+) -> int:
+    """Import the app in discovery mode and run its entrypoint (one submit).
+
+    ``viewstream`` (``simulo run --viewstream``) is scoped over the whole
+    submit via :func:`~simulo._client.app.viewstream_requested` — not passed
+    as an entrypoint kwarg — because the actual ``spawn()``/``submit()`` call
+    happens deep inside the user's ``@app.local_entrypoint`` body (or, with no
+    entrypoint, ``_submit_sole_job`` below), never at this call site directly.
+    A cloud ``spawn()`` reads the ambient flag and attaches it to the job
+    top-level (never inside ``args`` — see the live-visualization plan's
+    wire-contract rule preserving ``package_id``'s hash).
+    """
     previous_mode = os.environ.get("SIMULO_MODE")
     os.environ["SIMULO_MODE"] = DISCOVERY
     try:
@@ -97,7 +132,7 @@ def _submit_app(app_file: Path, entrypoint: Optional[str], extras: Sequence[str]
             raise TypeError(f"Discovered object is not a simulo.App: {app!r}")
 
         names = app.local_entrypoint_names
-        with spawn_recorder() as handles:
+        with spawn_recorder() as handles, viewstream_requested(viewstream):
             if names:
                 chosen = _choose_entrypoint(app_file, names, entrypoint)
                 run_entrypoint(app.resolve_local_entrypoint(chosen), extras)
@@ -201,7 +236,7 @@ def _follow_and_report(handle: JobHandle) -> int:
 def _cmd_run(args: argparse.Namespace, extras: Sequence[str]) -> int:
     assert args.app_file is not None, "_cmd_run: caller must guard against None app_file"
     app_file = Path(args.app_file).resolve()
-    return _submit_app(app_file, args.entrypoint, extras, detach=args.detach)
+    return _submit_app(app_file, args.entrypoint, extras, detach=args.detach, viewstream=args.viewstream)
 
 
 # ---------------------------------------------------------------------------
@@ -450,8 +485,36 @@ def _recording_name(record: dict[str, Any]) -> str:
     return str(name) if name else f"{record.get('recording_id', 'recording')}.mcap"
 
 
+def _verify_recording(dest: Path) -> None:
+    """Read *dest* back with the ``mcap`` reader and print a one-line summary.
+
+    This is the genuine use of the bundled ``mcap`` dependency (pyproject
+    dependencies): it replaces the manual ``python -c "from mcap.reader
+    import ..."`` check a user previously had to run by hand after `simulo
+    recordings` finished. The import is LAZY (inside this function, not at
+    module scope) so a plain `import simulo` — and every other CLI command
+    that never touches recordings — stays fast/torch-free; `mcap` is light,
+    but lazy is still the right default for a CLI-only code path.
+
+    Non-fatal by design: a corrupt or truncated download must not turn an
+    otherwise-successful fetch (the bytes are already on disk) into a crash.
+    Any failure — a genuinely corrupt file, or an mcap-library edge case —
+    prints a WARNING to stderr and returns; the file is kept and the caller's
+    exit code is unaffected.
+    """
+    try:
+        from mcap.reader import make_reader
+
+        with open(dest, "rb") as f:
+            reader = make_reader(f)
+            message_count = sum(1 for _ in reader.iter_messages())
+        print(f"verified {dest.name} — {message_count} messages", file=sys.stderr)
+    except Exception as exc:  # noqa: BLE001 — best-effort verification only; must never crash a successful download
+        print(f"WARNING: could not verify {dest.name} as a valid MCAP file: {exc}", file=sys.stderr)
+
+
 def _download_and_report(client: SubmitApiClient, job_id: str, record: dict[str, Any], dest: Path) -> bool:
-    """Download one recording to *dest*; print the Lichtblick hint on success.
+    """Download one recording to *dest*; verify + print the Lichtblick hint on success.
 
     ``dest`` must already be a caller-vetted destination — either the
     user's own ``-o PATH`` or ``out_dir / _safe_download_filename(...)``
@@ -467,12 +530,17 @@ def _download_and_report(client: SubmitApiClient, job_id: str, record: dict[str,
     — raises bare ``ValueError`` from the filesystem call, and it deserves
     the same clean one-liner (server-supplied names can no longer get here;
     ``_safe_download_filename`` rejects NULs outright).
+
+    A successful download is read back and verified (``_verify_recording``,
+    non-fatal) before the Lichtblick hint prints — a corrupt download is
+    still reported as a WARNING, never a crash.
     """
     try:
         resolved = client.download_recording(job_id, str(record["recording_id"]), dest)
     except (OSError, ValueError) as exc:
         print(f"Could not write recording to {dest}: {exc}", file=sys.stderr)
         return False
+    _verify_recording(resolved)
     print(f"Open in Lichtblick: {resolved.resolve()}")
     return True
 
@@ -868,6 +936,277 @@ def _cmd_models(args: argparse.Namespace) -> int:
     return 0 if _download_model_and_report(client, job_id, selected, dest) else 1
 
 
+#: PR3's ONE retryable mint error code — everything else (job_not_viewstream,
+#: job_not_running, job_not_found, view_sessions_disabled,
+#: rate_limit_exceeded — all pinned in view_session_api.py's module
+#: docstring) is a non-transient state that retrying can never fix.
+_STREAM_ENDPOINT_NOT_READY = "stream_endpoint_not_ready"
+#: A running job going NOT running between our own status check and the
+#: mint call — almost always because it just finished (critic MINOR).
+_JOB_NOT_RUNNING = "job_not_running"
+#: The mint route's ONLY pinned 404 code (view_session_api.py module
+#: docstring). By the time we mint, ``get_job`` has already confirmed the job
+#: exists — so a 404 with any OTHER code means the ``/view-session`` route
+#: itself isn't deployed in this environment (e.g. prod, which is
+#: staging-only for the view-session feature today), not that the job is
+#: missing. See ``_VIEW_SESSIONS_UNAVAILABLE_MESSAGE``.
+_JOB_NOT_FOUND = "job_not_found"
+#: Printed (and the command exits 1) when the mint 404s with any code other
+#: than ``job_not_found`` — i.e. the control plane doesn't have the
+#: view-session route at all, rather than not knowing this particular job.
+#: Covers BOTH shapes seen in practice: a Starlette-default 404 wrapped in the
+#: standard envelope (``code == "Not Found"``) and a non-envelope 404 from a
+#: proxy in front of the control plane (``code == "http_error"``, ``http.py``'s
+#: fallback when the body doesn't parse as the error envelope).
+_VIEW_SESSIONS_UNAVAILABLE_MESSAGE = (
+    "Live view isn't available in this environment yet (the control plane here doesn't "
+    "support view sessions). The job itself is unaffected — follow it with `simulo logs`."
+)
+#: How long a printed "waiting..." line stays valid before ``_WaitAnnouncer``
+#: re-prints it — so a multi-minute wait doesn't read as frozen on a real
+#: tty (critic MINOR; no prior periodic-reannounce precedent in this file,
+#: so this is a new, small, self-contained helper rather than a bigger
+#: refactor of the existing single-print wait loops).
+_SPINNER_REANNOUNCE_INTERVAL_S = 15.0
+
+
+def _job_ended_message(job_id: str) -> str:
+    """The one "this job is no longer running" message (NIT: hoisted — it
+    used to be duplicated verbatim in three places: the terminal-status
+    pre-check, the terminal-status re-check mid-gap-retry, and now the
+    ``job_not_running`` mint response too)."""
+    return f"Job {job_id!r} has ended — live view is only available while a job is running."
+
+
+class _WaitAnnouncer:
+    """Prints *message* immediately, then re-prints it every
+    ``_SPINNER_REANNOUNCE_INTERVAL_S`` while ``poll()`` keeps being called —
+    so a multi-minute queued-wait or gap-retry doesn't look frozen on a real
+    terminal. One small stateful helper shared by both wait loops below
+    rather than duplicating the timer bookkeeping twice.
+    """
+
+    def __init__(self, message: str) -> None:
+        self._message = message
+        self._last_announced_at: Optional[float] = None
+
+    def poll(self) -> None:
+        now = time.monotonic()
+        if self._last_announced_at is None or now - self._last_announced_at >= _SPINNER_REANNOUNCE_INTERVAL_S:
+            print(self._message, file=sys.stderr, flush=True)
+            self._last_announced_at = now
+
+
+def _wait_for_running_or_terminal(client: JobsApiClient, job_id: str, job: dict[str, Any]) -> dict[str, Any]:
+    """Poll a QUEUED job until it starts RUNNING (or goes straight to a terminal status).
+
+    The id-less-UX twin of ``simulo logs --follow``'s wait loops (see
+    ``_wait_for_job``): a spinner line prints immediately on stderr (then
+    re-prints every ``_SPINNER_REANNOUNCE_INTERVAL_S`` via ``_WaitAnnouncer``
+    — a long queue is not a frozen terminal), then the job record is
+    re-fetched at ``_VIEW_POLL_INTERVAL_S`` while its status stays
+    ``queued``. Returns as soon as the status is anything else — the caller
+    (``_cmd_view``) distinguishes ``running`` from a terminal status, which it
+    refuses with a friendly message rather than trying to mint a session.
+    """
+    announcer = _WaitAnnouncer("Waiting for the job to start streaming... (Ctrl-C to stop)")
+    while str(job.get("status")) == str(JobStatus.QUEUED):
+        announcer.poll()
+        time.sleep(_VIEW_POLL_INTERVAL_S)
+        job = client.get_job(job_id)
+    return job
+
+
+def _mint_view_session(
+    view_client: ViewSessionApiClient, jobs_client: JobsApiClient, job_id: str
+) -> tuple[Optional[dict[str, Any]], Optional[str]]:
+    """Mint a view session, tolerating the claim->registration gap (~90s bounded).
+
+    A running job's worker reports its stream endpoint in the claim request
+    body — a step that can lag briefly behind the job's status flipping to
+    ``running`` (live-visualization plan, "Lifecycle edges" hardening item).
+    The mint route responds 409 ``stream_endpoint_not_ready`` during that
+    gap; this function retries ONLY that exact error CODE (never classified
+    by HTTP status alone — PR3 also uses 409 for ``job_not_viewstream`` and
+    ``job_not_running``, which must fail fast, not spin the full window) until
+    it succeeds, the job goes terminal (re-checked on EVERY retry — a race
+    must not spin for the full window before noticing), or
+    ``_MINT_GAP_WINDOW_S`` elapses.
+
+    Returns ``(payload, None)`` on success, or ``(None, message)`` — an
+    already-friendly, ready-to-print message — when the job ended mid-wait
+    (either noticed via our own status re-check, or reported directly by the
+    server as ``job_not_running``), the mint route itself isn't deployed in
+    this environment (see below), or the gap window timed out. Any OTHER
+    error (e.g. ``job_not_viewstream`` for a job that was never started with
+    ``--viewstream``, or the pinned ``job_not_found`` 404 for a cross-org/
+    nonexistent job) is NOT retried: it propagates unchanged to the caller's
+    normal error handling (``_observe_handler``), which prints the server's
+    own message — "surface the server's error clearly" rather than the CLI
+    inventing its own text.
+
+    **Route-not-deployed graceful degradation** (live-visualization plan,
+    "graceful degradation" publish gate): production's control plane does not
+    (yet) have the ``/view-session`` route. Because ``get_job`` already
+    succeeded by the time we mint, the job is known to exist — so a 404 whose
+    code is anything OTHER than the mint route's one pinned 404 code
+    (``job_not_found``) can only mean the route itself is missing, not that
+    the job is. This is detected and turned into
+    ``_VIEW_SESSIONS_UNAVAILABLE_MESSAGE`` (never retried) rather than
+    propagating the raw ``code: message`` (e.g. the cryptic
+    ``Not Found: Not Found`` a bare Starlette 404 produces).
+    """
+    deadline = time.monotonic() + _MINT_GAP_WINDOW_S
+    announcer = _WaitAnnouncer(
+        "Waiting for the live view to become available (the worker is still registering "
+        "its stream)... (Ctrl-C to stop)"
+    )
+    while True:
+        try:
+            return view_client.create_view_session(job_id), None
+        except ViewSessionApiHTTPError as exc:
+            if exc.status == 404 and exc.code != _JOB_NOT_FOUND:
+                return None, _VIEW_SESSIONS_UNAVAILABLE_MESSAGE
+            if exc.code == _JOB_NOT_RUNNING:
+                return None, _job_ended_message(job_id)
+            if exc.code != _STREAM_ENDPOINT_NOT_READY:
+                raise
+            job = jobs_client.get_job(job_id)
+            if str(job.get("status")) in _TERMINAL_STATUS_STRINGS:
+                return None, _job_ended_message(job_id)
+            if time.monotonic() >= deadline:
+                return None, (
+                    f"Timed out waiting for job {job_id!r}'s live view to become available "
+                    "(the worker can take a few seconds to register its stream endpoint after "
+                    f"a job starts running). Try `simulo view {job_id}` again in a moment."
+                )
+            announcer.poll()
+            time.sleep(_MINT_GAP_POLL_INTERVAL_S)
+
+
+def _build_view_fragment_url(viewer_url: str, *, session_token: str, gateway_url: str, job_id: str) -> str:
+    """Build the browser URL for a minted view session.
+
+    The session token rides the URL FRAGMENT (after ``#``), never the query
+    string: fragments are never transmitted to the server or captured in
+    access logs (live-visualization plan, "Tokens out of logs" hardening
+    item), unlike a query parameter. Param names ``session``/``gateway``/
+    ``job`` are an EXACT reconciliation contract with PR5's viewer host
+    bootstrap page, which parses them via
+    ``new URLSearchParams(location.hash.slice(1))`` — do not rename them.
+    """
+    fragment = urllib.parse.urlencode({"session": session_token, "gateway": gateway_url, "job": job_id})
+    return f"{viewer_url}#{fragment}"
+
+
+def _validate_mint_response_urls(payload: dict[str, Any]) -> None:
+    """Refuse to act on a mint response whose URLs use an unsafe scheme.
+
+    SECURITY (MINOR, critic review): ``viewerUrl``/``gatewayUrl`` are
+    server-supplied strings that this command hands to ``webbrowser.open``
+    (which can dispatch to arbitrary OS protocol handlers) and embeds in a
+    printed/opened URL. A compromised or misbehaving control plane must not
+    be able to make the CLI invoke something other than a normal http(s)/
+    ws(s) endpoint. Mirrors ``http.require_https_or_loopback_for_bearer``'s
+    discipline: the secure scheme is always accepted; the plaintext sibling
+    is accepted ONLY to the local loopback (127.0.0.1/localhost/::1 — the
+    local dev viewer-web/gateway dev servers).
+    """
+    for field, secure_scheme, insecure_scheme in (
+        ("viewerUrl", "https", "http"),
+        ("gatewayUrl", "wss", "ws"),
+    ):
+        url = str(payload[field])
+        parsed = urllib.parse.urlsplit(url)
+        if parsed.scheme == secure_scheme:
+            continue
+        if parsed.scheme == insecure_scheme and http.is_loopback_host(parsed.hostname):
+            continue
+        raise ViewSessionApiError(
+            f"Refusing to use {field} {url!r} from the view-session response: expected "
+            f"{secure_scheme}:// (or {insecure_scheme}:// to the local loopback for dev)."
+        )
+
+
+def _cmd_view(args: argparse.Namespace) -> int:
+    """``simulo view [JOB_ID]`` — open the browser onto a running ``--viewstream`` job's live scene.
+
+    JOB_ID omitted: resolve the most recent job over the API and announce it
+    on stderr — the same latest-job default ``simulo logs``/``recordings``/
+    ``models`` use. A queued job is waited on (spinner) until it starts
+    running; a terminal job (completed/failed/cancelled) is refused with a
+    friendly message; a job that was never started with ``--viewstream``
+    surfaces the server's own error untouched. On success, opens the default
+    browser at the viewer URL (session token carried in the fragment, never
+    the query string) and also prints the URL for headless users to copy.
+    """
+    base_url, token = _resolve_client_context()
+    jobs_client = JobsApiClient(base_url, token=token)
+    view_client = ViewSessionApiClient(base_url, token=token)
+
+    job_id: Optional[str] = args.job_id
+    if job_id is None:
+        latest = jobs_client.get_latest_job()
+        if latest is None:
+            print(
+                "No jobs found — nothing to view. Run a job first: `simulo run app.py --viewstream`.",
+                file=sys.stderr,
+            )
+            return 1
+        job = latest
+        job_id = _announce_latest(job, "viewing")
+    else:
+        try:
+            job = jobs_client.get_job(job_id)
+        except JobsApiHTTPError as exc:
+            if exc.status == 404:
+                print(f"Job {job_id!r} not found. List runs with `simulo jobs`.", file=sys.stderr)
+                return 1
+            raise
+
+    if str(job.get("status")) == str(JobStatus.QUEUED):
+        job = _wait_for_running_or_terminal(jobs_client, job_id, job)
+        # A queue can run long enough for the access token to expire mid-wait
+        # (critic MINOR) — re-resolve (silently refreshes via the SAME shared
+        # path every other observe command uses) rather than minting with a
+        # now-stale bearer and hitting a bare 401.
+        base_url, token = _resolve_client_context()
+        jobs_client = JobsApiClient(base_url, token=token)
+        view_client = ViewSessionApiClient(base_url, token=token)
+
+    if str(job.get("status")) in _TERMINAL_STATUS_STRINGS:
+        print(_job_ended_message(job_id), file=sys.stderr)
+        return 1
+
+    payload, error = _mint_view_session(view_client, jobs_client, job_id)
+    if error is not None:
+        print(error, file=sys.stderr)
+        return 1
+    if payload is None:
+        # Invariant: _mint_view_session always returns a payload when it
+        # doesn't return an error message. A bare `assert` would be a NIT
+        # (critic) — asserts vanish under `python -O`, silently turning this
+        # into a `payload["viewerUrl"]` KeyError a few lines down instead of
+        # a clear internal-bug report.
+        raise RuntimeError("_mint_view_session returned neither a payload nor an error — this is a bug")
+
+    _validate_mint_response_urls(payload)
+    url = _build_view_fragment_url(
+        str(payload["viewerUrl"]),
+        session_token=str(payload["sessionToken"]),
+        gateway_url=str(payload["gatewayUrl"]),
+        job_id=job_id,
+    )
+    # Matches the documented narrative (context/architecture/user-journey/
+    # README.md Step 7: "Opening live view for job 8b52…9f in your
+    # browser…"), plus the bare URL on its own line so a headless user (no
+    # browser to open) can copy it directly.
+    print(f"Opening live view for job {job_id} in your browser...")
+    print(url)
+    webbrowser.open(url)
+    return 0
+
+
 def _observe_handler(
     subparser: argparse.ArgumentParser, command: Callable[[argparse.Namespace], int]
 ) -> Callable[[argparse.Namespace, Sequence[str]], int]:
@@ -913,7 +1252,7 @@ def _build_parser() -> argparse.ArgumentParser:
         prog="simulo",
         description=(
             "Simulo thin client — submit an app (local disk, or the cloud once logged in) and "
-            "observe its runs (simulo jobs / logs / result / recordings / models)."
+            "observe its runs (simulo jobs / logs / result / recordings / models / view)."
         ),
     )
     sub = parser.add_subparsers(dest="command", required=True)
@@ -938,6 +1277,16 @@ def _build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Submit a cloud job without waiting for its logs to finish (prints attach hints instead).",
     )
+    run.add_argument(
+        "--viewstream",
+        action="store_true",
+        help=(
+            "Enable the live 3D viewport stream for this cloud job (`simulo view` watches it once minted; "
+            "no effect on a local-disk submit, which never reaches a worker). Training runs noticeably "
+            "slower while streaming (roughly 4-5x, measured on a 512-environment benchmark) even with the "
+            "platform's built-in low-overhead render settings applied."
+        ),
+    )
 
     def _handle_run(args: argparse.Namespace, extras: Sequence[str]) -> int:
         """Dispatch ``simulo run``; route ``-h``/``--help`` before touching the app file.
@@ -1061,6 +1410,24 @@ def _build_parser() -> argparse.ArgumentParser:
         "-o", "--output", default=None, help="Output path (a file for one model; a directory for --all)."
     )
     models.set_defaults(func=_observe_handler(models, _cmd_models))
+
+    view = sub.add_parser(
+        "view",
+        help=(
+            "Open the browser onto a running --viewstream job's live 3D scene "
+            "(POST /v1/jobs/{id}/view-session; default: the most recent job)."
+        ),
+    )
+    view.add_argument(
+        "job_id",
+        nargs="?",
+        default=None,
+        help=(
+            "Job id to view (default: the most recent job). Only a job currently running with "
+            "--viewstream can be viewed; a queued job is waited on, a finished job is refused."
+        ),
+    )
+    view.set_defaults(func=_observe_handler(view, _cmd_view))
     return parser
 
 

{simulo-0.7.1 → simulo-0.9.0}/src/simulo/_client/http.py

@@ -60,7 +60,15 @@ class InsecureBearerError(HttpError):
     """Refused to attach a bearer token to a plain-http, non-loopback URL."""
 
 
-def _is_loopback(hostname: Optional[str]) -> bool:
+def is_loopback_host(hostname: Optional[str]) -> bool:
+    """``True`` for 127.0.0.1 / localhost / ::1 / any 127.x.x.x — the local dev loopback.
+
+    Public (not ``_``-prefixed): shared by the bearer-attachment guard below
+    AND by any caller that needs the same "is this the local dev stand-in"
+    judgment for a DIFFERENT scheme pair (e.g. ``simulo view``'s https-or-
+    loopback-http / wss-or-loopback-ws checks on a server-supplied URL before
+    handing it to ``webbrowser.open`` — see ``cli._validate_mint_urls``).
+    """
     if hostname is None:
         return False
     return hostname in _LOOPBACK_HOSTS or hostname.startswith("127.")
@@ -76,7 +84,7 @@ def require_https_or_loopback_for_bearer(url: str) -> None:
     parsed = urllib.parse.urlsplit(url)
     if parsed.scheme == "https":
         return
-    if parsed.scheme == "http" and _is_loopback(parsed.hostname):
+    if parsed.scheme == "http" and is_loopback_host(parsed.hostname):
         return
     raise InsecureBearerError(
         f"Refusing to send an Authorization bearer token to {url!r}: only https:// URLs "

{simulo-0.7.1 → simulo-0.9.0}/src/simulo/_client/submit_api.py

@@ -102,13 +102,25 @@ class SubmitApiClient:
             unavailable_hint=_UNAVAILABLE_HINT,
         )
 
-    def create_job(self, *, package_id: str, job_name: str, args: dict[str, Any]) -> dict[str, Any]:
+    def create_job(
+        self, *, package_id: str, job_name: str, args: dict[str, Any], viewstream: bool = False
+    ) -> dict[str, Any]:
         """``POST /v1/jobs`` — create the job that executes *package_id*.
 
+        ``viewstream`` is an OPTIONAL top-level body field — a sibling of
+        ``args``, never nested inside it (``args`` feeds the ``package_id``
+        sha256; a streaming flag must never change a package's content-
+        addressed identity). Sent only when ``True``: a control plane that
+        predates the live-visualization plan's ``JobSubmitRequest`` field
+        simply ignores an absent key, same as it ignores any unknown field.
+
         Returns the :class:`~simulo.interfaces.platform.runs.JobRecord` fields
         (201 on first submit; 200 on an idempotent replay of an in-flight job).
         """
-        payload = self._post_json(JOBS_ROUTE, {"package_id": package_id, "job_name": job_name, "args": args})
+        body: dict[str, Any] = {"package_id": package_id, "job_name": job_name, "args": args}
+        if viewstream:
+            body["viewstream"] = True
+        payload = self._post_json(JOBS_ROUTE, body)
         if not isinstance(payload, dict) or not payload.get("job_id"):
             raise SubmitApiError(f"Malformed create_job response: {payload!r}")
         return payload

simulo-0.9.0/src/simulo/_client/view_session_api.py

@@ -0,0 +1,122 @@
+"""HTTP client for the live-view session mint endpoint (stdlib only, torch-free).
+
+Wire contract (live-visualization plan, Wave 2 PR3 — control-plane; see
+``context/implementation-plans/live-visualization-plan.md`` and PR3's
+``simulo_control_plane.jobs.view_sessions.mint_view_session``):
+``POST /v1/jobs/{job_id}/view-session`` mints a short-lived (TTL <= 5 min)
+gateway-audience session for watching a running ``--viewstream`` job's live
+3D scene over the browser. Success (200) response body::
+
+    {"viewerUrl": "...", "gatewayUrl": "...", "sessionToken": "...", "expiresAt": "..."}
+
+Error responses use the standard ``{"error": {"code", "message", "request_id"}}``
+envelope. The PINNED codes this client's caller (``simulo._client.cli``)
+depends on by name (do not rename without updating both sides) — all raised
+as :class:`ViewSessionApiHTTPError` with ``exc.code``/``exc.status`` set from
+the body/status:
+
+* 409 ``stream_endpoint_not_ready`` — the ONLY transient/retryable one: the
+  worker claim->registration gap, or a lapsed-lease-pending-reap window.
+* 409 ``job_not_running`` — the job is no longer running (a race after the
+  caller confirmed ``running``, or a job that finished between poll and mint).
+* 409 ``job_not_viewstream`` — the job was never submitted with ``--viewstream``.
+* 404 ``job_not_found`` — unknown or cross-org job id (anti-enumeration).
+  This is the mint route's ONLY pinned 404 code. The caller
+  (``simulo._client.cli._mint_view_session``) relies on that: by the time it
+  mints, ``get_job`` has already confirmed the job exists, so it treats any
+  OTHER 404 — e.g. Starlette's default unmatched-route 404 (wrapped in the
+  standard envelope with ``code == "Not Found"`` by the control plane's
+  global ``HTTPException`` handler) or a non-envelope 404 from a proxy in
+  front of it (``code == "http_error"``, this client's fallback code when
+  the body isn't the structured envelope) — as proof the ``/view-session``
+  route itself isn't deployed in this environment (e.g. prod, which is
+  staging-only for view sessions today), and degrades gracefully instead of
+  printing the raw ``code: message``.
+* 503 ``view_sessions_disabled`` — the control plane has view sessions
+  fail-closed disabled (no JWT secret configured).
+* 429 ``rate_limit_exceeded`` — per-user mint rate limit (30/min).
+
+The route path is a LOCAL constant here rather than something imported from
+``simulo.interfaces.platform.runs`` — deliberately: PR3 owns the control
+plane's implementation (and any shared wire-contract module it lands
+alongside it), and this client codes directly against the exact path/response
+shape the plan specifies so the two PRs can land independently without a
+file-level merge conflict. Reconcile into a shared
+``simulo.interfaces.platform`` constant in a follow-up once PR3 has merged,
+if a shared module materializes.
+
+Shares request plumbing (structured-error parsing, the https-when-token
+guard, the foreign-host bearer rule) with ``jobs_api.py``/``submit_api.py``
+via ``http.py`` — one request path, not reimplemented a third time.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from simulo._client import http
+
+#: ``POST`` — mint a live-view session for a running ``--viewstream`` job.
+#: ``.format(job_id=...)``.
+VIEW_SESSION_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/view-session"
+
+_REQUEST_TIMEOUT_S = 10.0  # every outbound call has an explicit timeout (NFR)
+_UNAVAILABLE_HINT = "Check SIMULO_API_URL / SIMULO_ENV, and that you are logged in (`simulo login`)."
+
+#: Required fields of a well-formed mint response (see module docstring).
+_REQUIRED_FIELDS = ("viewerUrl", "gatewayUrl", "sessionToken", "expiresAt")
+
+# Backward-compatible-style aliases — same convention as jobs_api.py /
+# submit_api.py: these are literally ``http.HttpError``/``http.HttpHTTPError``
+# (not new subclasses), so callers that already catch ``JobsApiError`` (also
+# ``http.HttpError``) catch these too without any extra wiring.
+ViewSessionApiError = http.HttpError
+ViewSessionApiHTTPError = http.HttpHTTPError
+
+
+class ViewSessionApiClient:
+    """Client for ``POST /v1/jobs/{job_id}/view-session``."""
+
+    def __init__(self, base_url: str, *, token: Optional[str] = None) -> None:
+        if not base_url.startswith(("http://", "https://")):
+            raise ViewSessionApiError(f"API base URL must be an http(s) URL, got {base_url!r}.")
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    def create_view_session(self, job_id: str) -> dict[str, Any]:
+        """Mint a view session for *job_id*.
+
+        Raises :class:`ViewSessionApiHTTPError` on any non-2xx response — the
+        caller (``simulo._client.cli``) distinguishes the ONE retryable
+        claim->registration-gap error CODE (``stream_endpoint_not_ready``,
+        pinned with PR3) from every other code (e.g. ``job_not_viewstream``,
+        which is also a 409 — classify by ``exc.code``, never by
+        ``exc.status`` alone), letting non-retryable ones propagate unchanged
+        so the server's own error message reaches the user.
+        """
+        path = VIEW_SESSION_ROUTE_TEMPLATE.format(job_id=http.quote_path_segment(job_id))
+        payload = http.request_json(
+            "POST",
+            self._base_url + path,
+            token=self._token,
+            api_base_url=self._base_url,
+            json_body={},
+            timeout=_REQUEST_TIMEOUT_S,
+            unavailable_hint=_UNAVAILABLE_HINT,
+        )
+        if not isinstance(payload, dict):
+            raise ViewSessionApiError(f"Malformed view-session response for job {job_id!r}: expected a JSON object.")
+        # Security NIT: report only the MISSING field NAMES, never the raw
+        # payload — a malformed response could otherwise echo a partial
+        # sessionToken (or other sensitive value) into an exception message
+        # that ends up printed to the terminal or captured in a log.
+        missing = [field for field in _REQUIRED_FIELDS if field not in payload]
+        if missing:
+            raise ViewSessionApiError(
+                f"Malformed view-session response for job {job_id!r}: missing field(s) {missing}."
+            )
+        return payload

{simulo-0.7.1 → simulo-0.9.0/src/simulo.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.7.1
+Version: 0.9.0
 Summary: Simulo SDK and CLI — define robotics simulation and training apps in Python and run them on the Simulo cloud.
 Author-email: Simulo Team <team@simulo.ai>
 License: BSD-3-Clause
@@ -15,7 +15,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: simulo-interfaces<0.2,>=0.1
+Requires-Dist: simulo-interfaces<0.3,>=0.2
+Requires-Dist: mcap<2,>=1.3
 Provides-Extra: dev
 Requires-Dist: black>=24.0; extra == "dev"
 Requires-Dist: isort>=5.13; extra == "dev"

{simulo-0.7.1 → simulo-0.9.0}/src/simulo.egg-info/SOURCES.txt

@@ -32,4 +32,5 @@ src/simulo/_client/registry.py
 src/simulo/_client/runtime.py
 src/simulo/_client/stub.py
 src/simulo/_client/submit_api.py
+src/simulo/_client/view_session_api.py
 src/simulo/_client/volume.py

{simulo-0.7.1 → simulo-0.9.0}/src/simulo.egg-info/requires.txt

@@ -1,4 +1,5 @@
-simulo-interfaces<0.2,>=0.1
+simulo-interfaces<0.3,>=0.2
+mcap<2,>=1.3
 
 [dev]
 black>=24.0