simulo 0.9.0__tar.gz → 0.11.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.9.0
+Version: 0.11.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,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: simulo-interfaces<0.3,>=0.2
+Requires-Dist: simulo-interfaces<0.5,>=0.4
 Requires-Dist: mcap<2,>=1.3
 Provides-Extra: dev
 Requires-Dist: black>=24.0; extra == "dev"
@@ -85,4 +85,9 @@ simulo run app.py --name robot --repeat 5
 
 Without logging in, `simulo run` packages the app locally without submitting it.
 
+Every cloud submit is fresh — running the same command twice trains twice, never a silent
+no-op. To continue training from an earlier job's checkpoint instead, pass
+`--from <job-ref>[:best|:latest]`. Job ids, and their unambiguous prefixes (`>=4` characters),
+work anywhere the CLI takes a job id.
+
 Learn more at [simulo.ai](https://simulo.ai).

{simulo-0.9.0 → simulo-0.11.0}/PYPI.md

@@ -53,4 +53,9 @@ simulo run app.py --name robot --repeat 5
 
 Without logging in, `simulo run` packages the app locally without submitting it.
 
+Every cloud submit is fresh — running the same command twice trains twice, never a silent
+no-op. To continue training from an earlier job's checkpoint instead, pass
+`--from <job-ref>[:best|:latest]`. Job ids, and their unambiguous prefixes (`>=4` characters),
+work anywhere the CLI takes a job id.
+
 Learn more at [simulo.ai](https://simulo.ai).

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.9.0"
+version = "0.11.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"
@@ -25,7 +25,7 @@ classifiers = [
 # 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"]
+dependencies = ["simulo-interfaces>=0.4,<0.5", "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.9.0 → simulo-0.11.0}/src/simulo/_client/_runner.py

@@ -92,7 +92,7 @@ class JobHandle:
 
     @property
     def package_path(self) -> Path:
-        """Directory the package was written to (``<out>/<package_id>/``)."""
+        """Directory the package was written to (``<out>/<bundle_dir_name(package_id)>/``)."""
         return self._package_path
 
     @property

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

@@ -97,6 +97,57 @@ def viewstream_requested(enabled: bool) -> Iterator[None]:
         _VIEWSTREAM_REQUESTED = previous
 
 
+# ---------------------------------------------------------------------------
+# Seed ambient signal — `simulo run --from <job-ref>[:best|:latest]` scopes the
+# seed reference for one submit (explicit-run-intent plan), exactly like the
+# viewstream signal above and for the same two reasons: the actual `spawn()`
+# happens deep inside the user's @app.local_entrypoint, and the seed is a
+# SUBMIT-time job property that must never enter `args` (whose canonical form
+# feeds the `package_id` sha256) or the package manifest. It rides the
+# `POST /v1/jobs` body as a top-level sibling of `args`, passed through
+# verbatim — the control plane resolves the ref (org-scoped, prefixes and
+# `:best`/`:latest` included) in the same request.
+# ---------------------------------------------------------------------------
+
+_SEED_FROM_REF: Optional[str] = None
+
+
+class SeedRequiresCloudError(RuntimeError):
+    """``--from`` was passed but the submit resolved to the local-disk path.
+
+    A local-disk submit only writes a package — no control plane exists to
+    resolve the seed reference or hand the checkpoint to a worker, so the
+    resulting run would silently be FRESH instead of seeded (the same
+    wrong-result hazard the loud-degradation check guards on the cloud
+    path). Refused loudly instead of ignored.
+    """
+
+
+@contextlib.contextmanager
+def seed_from_requested(seed_ref: Optional[str]) -> Iterator[None]:
+    """Scope ``--from``'s seed reference for one ``simulo run`` submit call."""
+    global _SEED_FROM_REF
+    previous = _SEED_FROM_REF
+    _SEED_FROM_REF = seed_ref
+    try:
+        yield
+    finally:
+        _SEED_FROM_REF = previous
+
+
+def _require_no_seed_for_local_submit(reason: str) -> None:
+    """Refuse a local-disk submit that carries an ambient ``--from`` seed."""
+    if _SEED_FROM_REF is None:
+        return
+    raise SeedRequiresCloudError(
+        f"--from {_SEED_FROM_REF!r} needs a cloud control plane to resolve the checkpoint, but "
+        f"{reason} — a local-disk submit only writes the package and cannot continue from another "
+        "job's checkpoint, so the run would silently start fresh instead. Log in first "
+        "(`simulo login`) or point SIMULO_API_URL/SIMULO_ENV at a control plane (and unset "
+        "SIMULO_SUBMIT=local), or drop --from for a fresh local run."
+    )
+
+
 @dataclass
 class JobSpec:
     """Recorded metadata for one ``@app.job``-decorated function."""
@@ -153,7 +204,12 @@ def _spawn_local(job_name: str, package_path: Path) -> JobHandle:
 
 
 def _spawn_cloud(
-    job_name: str, package_path: Path, creds: Optional[dict[str, Any]], *, viewstream: bool = False
+    job_name: str,
+    package_path: Path,
+    creds: Optional[dict[str, Any]],
+    *,
+    viewstream: bool = False,
+    seed_from: Optional[str] = None,
 ) -> JobHandle:
     """Tar the bundle, upload it, create the job, and return a cloud JobHandle.
 
@@ -162,12 +218,38 @@ def _spawn_cloud(
     — 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.
+
+    ``seed_from`` (``simulo run --from``, explicit-run-intent plan) follows
+    the identical rule: the seed reference is a SUBMIT-time job property,
+    never a package property — it rides the job-create call only, verbatim
+    (the control plane resolves prefixes and ``:best``/``:latest``). When the
+    server honors it, the RESOLVED provenance is announced on stderr (the
+    full source-job UUID — the confirmation that a typed prefix resolved to
+    the job the user meant); when an older server ignores it, ``create_job``
+    raises rather than let a fresh run masquerade as a seeded one.
     """
     from simulo._client.packaging import MANIFEST_FILENAME, ensure_tar
     from simulo._client.submit_api import SubmitApiClient
 
     manifest = json.loads((package_path / MANIFEST_FILENAME).read_text(encoding="utf-8"))
-    package_id = str(manifest.get("package_id") or package_path.name)
+    # The manifest's package_id is the wire identity (``sha256:<hex>``) and is
+    # the ONLY source of truth for it — every manifest ``package()`` writes
+    # carries one (see packaging.py). The local directory name is NOT a valid
+    # fallback: it is a short, non-invertible, filesystem-safe form of the id
+    # (see ``packaging.bundle_dir_name`` — truncated for Windows MAX_PATH),
+    # so guessing an id back from it would either be impossible (can't invert
+    # a truncated hash) or, worse, silently put a WRONG/incomplete id on the
+    # wire. An id-less manifest means a bundle written by a client older than
+    # this fix, or a corrupted/foreign directory — fail loudly and tell the
+    # caller how to recover, never guess.
+    package_id = manifest.get("package_id")
+    if not package_id:
+        raise RuntimeError(
+            f"Package at {package_path} has no package_id in its manifest (it predates this client "
+            "version, or its manifest is missing/corrupted). Re-run `simulo run` (or call .spawn() "
+            "again) to rebuild it before submitting to the cloud."
+        )
+    package_id = str(package_id)
     source_digest = str(manifest.get("source_digest", ""))
     args = dict(manifest.get("args") or {})
 
@@ -187,7 +269,23 @@ def _spawn_cloud(
         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, viewstream=viewstream)
+    record = client.create_job(
+        package_id=package_id,
+        job_name=job_name,
+        args=args,
+        viewstream=viewstream,
+        seed_from_job_id=seed_from,
+    )
+
+    if seed_from is not None:
+        # create_job has already guaranteed the seed dict is present (the
+        # loud-degradation guard) — this line is the human confirmation that
+        # the ref (possibly a prefix) resolved to the intended source job.
+        seed = record.get("seed") or {}
+        print(
+            f"Continuing from job {seed.get('job_id')} ({seed.get('name')}, {seed.get('kind')} checkpoint)",
+            file=sys.stderr,
+        )
 
     return JobHandle(JobId(str(record["job_id"])), package_path, job_name, cloud=True, base_url=base_url, token=token)
 
@@ -242,12 +340,20 @@ class JobFunction:
         # fail outright if the refresh token itself is no longer valid). A
         # local-disk submit must never depend on the network succeeding.
         if config.is_submit_forced_local():
+            _require_no_seed_for_local_submit("SIMULO_SUBMIT=local forces a local-disk submit")
             handle: JobHandle = _spawn_local(self._spec.name, package_path)
         else:
             creds = credentials.try_get_valid_credentials()
             if _cloud_mode_active(creds):
-                handle = _spawn_cloud(self._spec.name, package_path, creds, viewstream=_VIEWSTREAM_REQUESTED)
+                handle = _spawn_cloud(
+                    self._spec.name,
+                    package_path,
+                    creds,
+                    viewstream=_VIEWSTREAM_REQUESTED,
+                    seed_from=_SEED_FROM_REF,
+                )
             else:
+                _require_no_seed_for_local_submit("no cloud target is configured")
                 handle = _spawn_local(self._spec.name, package_path)
         _record_spawn(handle)
         return handle

{simulo-0.9.0 → simulo-0.11.0}/src/simulo/_client/bundle.py

@@ -21,7 +21,7 @@ from typing import TYPE_CHECKING, Any, Optional
 
 from simulo._client.asset import Asset
 from simulo._client.manifest import Manifest
-from simulo._client.packaging import canonical_args, package
+from simulo._client.packaging import canonical_args, package, read_bundle_package_id
 from simulo._client.volume import Volume
 
 if TYPE_CHECKING:  # typing-only; avoids any import cycle with app.py at runtime
@@ -36,7 +36,18 @@ DEFAULT_OUT_SUBPATH = (".simulo", "packages")
 # so identity reuse is not a concern, and keying on the job + args means multiple
 # spawns in one entrypoint (different job or different args) each write their own
 # package instead of the first one being reused for all.
-_BUNDLE_CACHE: dict[tuple[int, str, str], Path] = {}
+#
+# Each entry stores ``(bundle_dir, package_id)`` — the package_id the bundle
+# was written for when THIS process cached it — not just the path. The local
+# bundle directory name is a short, non-injective digest prefix (see
+# ``packaging.bundle_dir_name``), so a directory existing at the cached path is
+# NOT proof it still holds this submission's content: another submission whose
+# id happens to share the same short prefix could have called ``package()``
+# again for a DIFFERENT id and overwritten it (``package()`` unconditionally
+# rmtree+rewrites whatever it finds there). ``ensure_bundle`` re-verifies the
+# manifest on every cache hit before trusting it (see below) — turning a
+# prefix collision into a redundant rebuild, never a silently wrong package.
+_BUNDLE_CACHE: dict[tuple[int, str, str], tuple[Path, str]] = {}
 
 
 def _mount_ref(mount: object) -> dict[str, Any]:
@@ -134,21 +145,47 @@ def ensure_bundle(
 
     This is the *submit* primitive: the manifest is built from the live app object
     (no second discovery import) with the submitted job's ``args`` recorded, and
-    the source tree is written to ``<out>/<package_id>/`` — the per-submission
-    directory keyed on source + ``job_name`` + ``args``. Memoised per submission
-    (``(id(app), job_name, canonical_json(args))``) so re-submitting the same job
-    with the same args reuses the package, while a different job or different args
-    writes a distinct package rather than clobbering the first.
+    the source tree is written to ``<out>/<bundle_dir_name(package_id)>/`` — the
+    per-submission directory keyed on source + ``job_name`` + ``args`` (named by
+    the id's short, filesystem-safe form; see ``packaging.bundle_dir_name``).
+    Memoised per submission (``(id(app), job_name, canonical_json(args))``) so
+    re-submitting the same job with the same args reuses the package, while a
+    different job or different args writes a distinct package rather than
+    clobbering the first.
+
+    A cache HIT is re-verified, not trusted blindly: the short bundle directory
+    name is not injective (Windows MAX_PATH trade-off — see
+    ``packaging.bundle_dir_name``), so before returning a cached path this reads
+    the manifest actually on disk there and confirms its ``package_id`` still
+    matches what THIS cache entry was written for. A mismatch — some other
+    submission's id collided on the same short prefix and ``package()``
+    overwrote the directory — is treated as a MISS: the package is rebuilt
+    (deterministically restoring the correct content for this exact
+    submission), never served as a silently wrong package.
     """
     cache_key = (id(app), job_name, canonical_args(args))
     cached = _BUNDLE_CACHE.get(cache_key)
-    if cached is not None and cached.is_dir():
-        return cached
+    if cached is not None:
+        cached_dir, cached_package_id = cached
+        if cached_dir.is_dir() and read_bundle_package_id(cached_dir) == cached_package_id:
+            return cached_dir
     if out_dir is None:
         out_dir = project_root.joinpath(*DEFAULT_OUT_SUBPATH)
     manifest = build_manifest(app, app_file, project_root, args=args)
     bundle = package(app_file, out_dir=out_dir, project_root=project_root, manifest=manifest, job_name=job_name)
-    _BUNDLE_CACHE[cache_key] = bundle
+    bundle_package_id = read_bundle_package_id(bundle)
+    if bundle_package_id is None:
+        # Internal invariant, not a user-facing input error: package() always
+        # stamps package_id into the manifest it writes (see packaging.py). A
+        # bare `assert` here would be stripped under `python -O`, silently
+        # caching a bundle keyed on a package_id we never actually confirmed
+        # (critic finding, PR #363 round-2 re-review, 2026-07-12) — use a
+        # real, always-live exception instead.
+        raise RuntimeError(
+            f"Internal error: package() wrote a bundle at {bundle} with no package_id in its manifest. "
+            "This should never happen — please report it."
+        )
+    _BUNDLE_CACHE[cache_key] = (bundle, bundle_package_id)
     return bundle
 
 

simulo-0.11.0/src/simulo/_client/cancel_api.py

@@ -0,0 +1,105 @@
+"""HTTP client for the job cancel endpoint (stdlib only, torch-free).
+
+Wire contract (job-cancel-and-demo-apps plan — see
+``context/implementation-plans/job-cancel-and-demo-apps-plan.md``; the control
+plane's half of this route is built by a parallel PR, so this client codes
+directly against the plan's PINNED contract rather than waiting on it):
+``POST /v1/jobs/{job_id}/cancel`` (Cognito bearer, org-scoped).
+
+* 200 ``{"job_id": ..., "status": "cancelled"}`` — a QUEUED job is cancelled
+  immediately (it can never be claimed by a worker after this).
+* 202 ``{"job_id": ..., "status": "running", "cancel_requested": true}`` — a
+  RUNNING job has cancellation requested; the worker confirms termination
+  within one heartbeat interval. Idempotent — a repeat cancel of an
+  already-cancel-requested running job returns the same 202 shape again.
+* 409 ``job_not_running`` — the job is already in a terminal state
+  (completed/failed/cancelled); the response message carries the actual
+  status, but the caller (``simulo._client.cli``) does not surface it
+  verbatim — it reuses the same friendly "has ended" copy ``simulo view``
+  uses for the identical situation.
+* 404 ``job_not_found`` — unknown or cross-org job id (anti-enumeration;
+  never 403). This is the cancel route's ONLY pinned 404 code — mirrors
+  ``view_session_api.py``'s contract, and the caller relies on that the same
+  way: any OTHER 404 code means the ``/cancel`` route itself isn't deployed
+  in this environment (e.g. prod before this feature ships there), not that
+  the job is missing — see ``cli._CANCEL_UNAVAILABLE_MESSAGE``.
+
+Error responses use the standard ``{"error": {"code", "message", "request_id"}}``
+envelope, parsed by ``http.py`` exactly like every other client in this
+package.
+
+The route path is a LOCAL constant here rather than imported from
+``simulo.interfaces.platform.runs`` — deliberately, the same reconciliation
+call ``view_session_api.py`` made: the control-plane cancel route is being
+built by a parallel PR and may land independently of this one, so this client
+codes directly against the plan's pinned path/response shape rather than
+sharing a file with that PR (avoiding a merge conflict). Reconcile into a
+shared ``simulo.interfaces.platform`` constant in a follow-up once that PR has
+merged, if a shared module materializes for it.
+
+Shares request plumbing (structured-error parsing, the https-when-token
+guard, the foreign-host bearer rule) with ``jobs_api.py``/``view_session_api.py``
+via ``http.py`` — one request path, not reimplemented a fourth time.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from simulo._client import http
+
+#: ``POST`` — request cancellation of a queued or running job. ``.format(job_id=...)``.
+CANCEL_ROUTE_TEMPLATE = "/v1/jobs/{job_id}/cancel"
+
+_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 cancel response (see module docstring).
+_REQUIRED_FIELDS = ("job_id", "status")
+
+# Backward-compatible-style aliases — same convention as jobs_api.py /
+# view_session_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.
+CancelApiError = http.HttpError
+CancelApiHTTPError = http.HttpHTTPError
+
+
+class CancelApiClient:
+    """Client for ``POST /v1/jobs/{job_id}/cancel``."""
+
+    def __init__(self, base_url: str, *, token: Optional[str] = None) -> None:
+        if not base_url.startswith(("http://", "https://")):
+            raise CancelApiError(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 cancel_job(self, job_id: str) -> dict[str, Any]:
+        """Request cancellation of *job_id*; returns the parsed 200/202 body.
+
+        Raises :class:`CancelApiHTTPError` on any non-2xx response — the
+        caller (``simulo._client.cli``) classifies by ``exc.code``, never by
+        ``exc.status`` alone (both ``job_not_running`` and the route-missing
+        degradation share statuses with other codes, exactly like
+        ``ViewSessionApiClient.create_view_session``'s callers already do).
+        """
+        path = CANCEL_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 CancelApiError(f"Malformed cancel response for job {job_id!r}: expected a JSON object.")
+        missing = [field for field in _REQUIRED_FIELDS if field not in payload]
+        if missing:
+            raise CancelApiError(f"Malformed cancel response for job {job_id!r}: missing field(s) {missing}.")
+        return payload