simulo 0.9.0__tar.gz → 0.10.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.9.0
+Version: 0.10.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.4,>=0.3
 Requires-Dist: mcap<2,>=1.3
 Provides-Extra: dev
 Requires-Dist: black>=24.0; extra == "dev"

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simulo"
-version = "0.9.0"
+version = "0.10.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.3,<0.4", "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.10.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

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

@@ -25,14 +25,14 @@ 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`` / ``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 ->
+``simulo recordings`` / ``simulo models`` / ``simulo view`` / ``simulo cancel``) 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``,
-``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 result``, ``simulo view``, and ``simulo cancel`` 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
@@ -40,6 +40,18 @@ recent job over the API (and announce what they resolved to on stderr).
 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.
+
+``simulo cancel [JOB_ID] [--yes/-y]`` requests cancellation of a queued or running job
+(``POST /v1/jobs/{id}/cancel`` — job-cancel-and-demo-apps plan). JOB_ID omitted resolves the
+most recent job ORG-WIDE, so it is confirmed before acting — a ``y``/``N`` prompt on a
+terminal, or refused (exit 2) without ``--yes`` when stdin isn't a terminal; an EXPLICIT
+JOB_ID is never prompted (naming the target is the confirmation). Past that gate: a queued
+job is cancelled immediately (prints a one-line confirmation, exits 0). A running job has
+cancellation requested and this command waits (~2s poll cadence, Ctrl-C to detach without
+un-cancelling) until the worker confirms termination, then prints the final status. A job
+already in a terminal state is refused with cancel-specific copy naming the job's actual
+status. A control plane without the cancel route (e.g. prod before this feature ships
+there) degrades gracefully, exactly like ``simulo view`` does for a missing view-session route.
 """
 
 from __future__ import annotations
@@ -58,6 +70,7 @@ 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, viewstream_requested
+from simulo._client.cancel_api import CancelApiClient, CancelApiHTTPError
 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
@@ -66,11 +79,27 @@ 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
+from simulo.interfaces.platform.runs import LOG_TAIL_MAX_BYTES, TERMINAL_JOB_STATUSES
 
 #: ``--follow`` poll cadence. Module-level so tests can shrink it.
 _FOLLOW_POLL_INTERVAL_S = 0.7
 
+#: ``simulo logs --follow`` starts from the last this-many LINES of existing
+#: output by default (``tail -f`` style) — override with ``--tail N`` /
+#: ``--from-start``. Plain ``simulo logs`` (no ``--follow``) still dumps the
+#: full log; ``simulo run``'s auto-follow starts at offset 0 (a brand-new
+#: job's history IS its live output).
+_DEFAULT_TAIL_LINES = 50
+
+#: Generous bytes-per-line heuristic for sizing the ``tail_bytes`` request
+#: window from a line count (server tail semantics are byte-based). Long
+#: training-log lines rarely exceed ~200 bytes; over-fetching just means a
+#: few extra lines are trimmed client-side.
+_TAIL_BYTES_PER_LINE = 200
+#: Floor on the requested tail window — a tiny ``--tail N`` still fetches
+#: enough bytes to survive a run of unusually long lines.
+_TAIL_MIN_BYTES = 4 * 1024
+
 #: ``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
@@ -84,9 +113,18 @@ _MINT_GAP_WINDOW_S = 90.0
 #: ``_VIEW_POLL_INTERVAL_S``) so tests can shrink the two loops independently.
 _MINT_GAP_POLL_INTERVAL_S = 1.0
 
+#: ``simulo cancel`` poll cadence while waiting for a RUNNING job's cancel to
+#: be confirmed. Module-level (like the poll constants above) so tests can
+#: shrink it. Heartbeat cadence bounds real-world cancel latency to ~15s
+#: worst case (job-cancel-and-demo-apps plan) — ~2s here is fast enough to
+#: feel responsive without hammering the server while waiting.
+_CANCEL_POLL_INTERVAL_S = 2.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)
+_RUNNING_STATUS = str(JobStatus.RUNNING)
+_CANCELLED_STATUS = str(JobStatus.CANCELLED)
 
 
 def _resolve_client_context() -> tuple[str, Optional[str]]:
@@ -384,15 +422,129 @@ def _announce_latest(record: dict[str, Any], verb: str) -> str:
     return job_id
 
 
-def _drain_logs(client: JobsApiClient, job_id: str, *, follow: bool) -> int:
-    """Print log chunks from byte offset 0; ``follow`` polls to a terminal status.
+def _tail_window_bytes(tail_lines: int) -> int:
+    """Size the ``tail_bytes`` request window for a line count (0 = end-of-log)."""
+    if tail_lines == 0:
+        return 0
+    return min(max(tail_lines * _TAIL_BYTES_PER_LINE, _TAIL_MIN_BYTES), LOG_TAIL_MAX_BYTES)
+
+
+def _split_lines_lf_only(text: str) -> list[str]:
+    """Split ``text`` into lines on ``\\n`` ONLY, each piece keeping its
+    trailing ``\\n`` (POSIX ``tail -n`` semantics — mirrors the SHAPE of
+    ``str.splitlines(keepends=True)`` but not its universal-newline scanning).
+
+    Deliberately NOT ``str.splitlines()``: that treats a bare ``\\r`` as a
+    line boundary too, so a tqdm-style progress update (``33%\\r34%\\r...\\r
+    99%\\n``) counts as ~100 "lines" instead of the one real line it is until
+    its terminating ``\\n`` — a lone mid-line ``\\r`` is a cursor move, not a
+    newline. ``\\r\\n`` (CRLF) still ends on the ``\\n`` and is still one
+    line, terminator intact (the trailing ``\\r`` rides along with its piece).
+    """
+    if not text:
+        return []
+    pieces = text.split("\n")
+    result = [piece + "\n" for piece in pieces[:-1]]
+    if pieces[-1]:  # trailing partial line with no terminator yet
+        result.append(pieces[-1])
+    return result
+
+
+def _trim_to_last_lines(text: str, lines: int, *, drop_first_partial: bool) -> str:
+    """Client-side half of tail: keep only the last ``lines`` lines of ``text``.
 
-    Shared by ``simulo logs`` and the post-``simulo run`` default follow — one
-    follow loop, one exit-code-mirrors-outcome rule.
+    ``drop_first_partial`` — the server's tail start is a BYTE position
+    (``max(0, total - tail_bytes)``) and may land mid-line (or mid-UTF-8
+    sequence, decoded as U+FFFD); when the window started mid-stream the first
+    "line" is a fragment, so it is dropped before counting.
+    """
+    if drop_first_partial:
+        cut = text.find("\n")
+        text = text[cut + 1 :] if cut >= 0 else ""
+    if lines <= 0:
+        return ""
+    return "".join(_split_lines_lf_only(text)[-lines:])
+
+
+def _start_tail(client: JobsApiClient, job_id: str, tail_lines: int) -> tuple[int, str, bool]:
+    """Open a follow at the log's tail; print it; return ``(resume_offset, status, honored)``.
+
+    Requests the tail window (one ``tail_bytes`` call, then plain offset pages
+    for a window larger than one response chunk — never the full history),
+    trims to the last ``tail_lines`` lines, prints them, and reports where
+    live paging resumes. ``honored=False`` means the server is too old to know
+    ``tail_bytes``, detected either way a legacy server can react to the
+    unknown/out-of-range param: (a) it silently IGNORES it (missing
+    ``start_offset`` on an otherwise-200 response), or (b) a strict
+    query-validation layer REJECTS it outright (422) — e.g. a server whose
+    ``le=`` bound on ``tail_bytes`` predates a since-raised
+    :data:`~simulo.interfaces.platform.runs.LOG_TAIL_MAX_BYTES` (see that
+    constant's rollout-order caveat). Either way the caller gets the SAME
+    full-history fallback: the (a) response is printed VERBATIM after a
+    one-line stderr note, or (b) triggers one bare retry without
+    ``tail_bytes`` before the same note+full-history path — the caller then
+    continues normal paging from ``resume_offset`` (never a silent hang or a
+    mis-trim).
+    """
+    window = _tail_window_bytes(tail_lines)
+    try:
+        chunk, offset, status, start_offset = client.get_log_chunk(job_id, 0, tail_bytes=window)
+    except JobsApiHTTPError as exc:
+        if exc.status != 422:
+            raise
+        # A server that rejects (rather than ignores) the unknown/out-of-
+        # range tail_bytes param — retry once, plain, then degrade exactly
+        # like the "ignored" case below.
+        chunk, offset, status, start_offset = client.get_log_chunk(job_id, 0)
+        start_offset = None
+    if start_offset is None:
+        print(
+            "note: this control plane doesn't support tail; showing the log from the start.",
+            file=sys.stderr,
+            flush=True,
+        )
+        text = chunk
+    else:
+        buffer = chunk
+        while chunk and offset < start_offset + window:
+            # The tail window exceeded one response chunk — drain the rest of
+            # the window with normal offset pages before trimming.
+            next_chunk, next_offset, status, _ = client.get_log_chunk(job_id, offset)
+            if next_offset <= offset:
+                # A misbehaving server returned a non-empty chunk without
+                # advancing the offset — stop instead of looping/growing the
+                # buffer unboundedly on a response that can never converge.
+                break
+            chunk, offset = next_chunk, next_offset
+            buffer += chunk
+        text = _trim_to_last_lines(buffer, tail_lines, drop_first_partial=start_offset > 0)
+    if text:
+        sys.stdout.write(text)
+        sys.stdout.flush()
+    return offset, status, start_offset is not None
+
+
+def _drain_logs(client: JobsApiClient, job_id: str, *, follow: bool, tail_lines: Optional[int] = None) -> int:
+    """Print log chunks; ``follow`` polls to a terminal status.
+
+    ``tail_lines=None`` prints from byte offset 0 (full history — plain
+    ``simulo logs``, ``--from-start``, and ``simulo run``'s auto-follow, where
+    offset 0 is naturally correct for a brand-new job). An int starts ``tail
+    -f`` style instead: only the last ``tail_lines`` lines of existing output,
+    then live — so re-attaching to a long-running job never re-dumps (or
+    re-downloads) its whole history. Shared by ``simulo logs`` and the
+    post-``simulo run`` default follow — one follow loop, one
+    exit-code-mirrors-outcome rule.
     """
     offset = 0
+    if tail_lines is not None:
+        offset, _status, honored = _start_tail(client, job_id, tail_lines)
+        if honored and not follow:
+            return 0  # printed the last N lines that exist — done
+        # Not honored (old server): the loop below simply continues the full
+        # history from where the server's offset-0 answer left off.
     while True:
-        chunk, offset, status = client.get_log_chunk(job_id, offset)
+        chunk, offset, status, _ = client.get_log_chunk(job_id, offset)
         if chunk:
             sys.stdout.write(chunk)
             sys.stdout.flush()
@@ -404,14 +556,32 @@ def _drain_logs(client: JobsApiClient, job_id: str, *, follow: bool) -> int:
         time.sleep(_FOLLOW_POLL_INTERVAL_S)
 
 
+def _resolve_tail_lines(args: argparse.Namespace) -> Optional[int]:
+    """Map the ``logs`` flags onto ``_drain_logs``'s ``tail_lines``.
+
+    ``--from-start`` (or plain ``simulo logs`` with no tail flag) → ``None``
+    (full history). ``--tail N`` → N, with or without ``--follow`` (``tail
+    -n`` / ``tail -nf`` parity). ``--follow`` alone → the default tail
+    (:data:`_DEFAULT_TAIL_LINES`) — following a long-running job should show
+    where it IS, not replay everything it ever printed.
+    """
+    if args.from_start:
+        return None
+    if args.tail is not None:
+        return args.tail
+    return _DEFAULT_TAIL_LINES if args.follow else None
+
+
 def _cmd_logs(args: argparse.Namespace) -> int:
-    """``simulo logs [JOB_ID] [--follow]`` — print log chunks from byte offset 0.
+    """``simulo logs [JOB_ID] [--follow] [--tail N | --from-start]`` — print log chunks.
 
     JOB_ID omitted: resolve the most recent job over the API and announce it on
     stderr — with ``--follow`` an empty store waits for the first job to appear;
     plain on an empty store is a clear error (exit 1). Plain: print what exists
-    and exit 0. ``--follow``: poll (~0.7s) while the job runs, then drain and
-    mirror the job's outcome in the exit code (0 for ``completed``, 1 otherwise).
+    and exit 0. ``--follow``: start from the last ``_DEFAULT_TAIL_LINES`` lines
+    (true-tail — never re-dumps history; ``--tail N`` / ``--from-start``
+    override), then poll (~0.7s) while the job runs, drain, and mirror the
+    job's outcome in the exit code (0 for ``completed``, 1 otherwise).
     """
     base_url, token = _resolve_client_context()
     client = JobsApiClient(base_url, token=token)
@@ -441,7 +611,7 @@ def _cmd_logs(args: argparse.Namespace) -> int:
                 return 1
             raise
 
-    return _drain_logs(client, job_id, follow=args.follow)
+    return _drain_logs(client, job_id, follow=args.follow, tail_lines=_resolve_tail_lines(args))
 
 
 def _cmd_result(args: argparse.Namespace) -> int:
@@ -1207,6 +1377,246 @@ def _cmd_view(args: argparse.Namespace) -> int:
     return 0
 
 
+# ---------------------------------------------------------------------------
+# simulo cancel
+# ---------------------------------------------------------------------------
+
+#: The cancel route's ONE pinned 404 code (cancel_api.py module docstring).
+#: Mirrors ``_JOB_NOT_FOUND`` above (view-session's identical convention): any
+#: OTHER 404 code means the ``/cancel`` route itself isn't deployed in this
+#: environment, not that this particular job is missing.
+_CANCEL_JOB_NOT_FOUND = "job_not_found"
+#: The cancel route's pinned "already terminal" code.
+_CANCEL_JOB_NOT_RUNNING = "job_not_running"
+#: Printed (and the command exits 1) when the cancel call 404s with any code
+#: other than ``job_not_found`` — i.e. this control plane doesn't have the
+#: ``/cancel`` route at all (e.g. prod before this feature ships there),
+#: rather than not knowing this particular job. Mirrors
+#: ``_VIEW_SESSIONS_UNAVAILABLE_MESSAGE``'s degrade-gracefully contract
+#: exactly, including covering both the Starlette-default-404 envelope shape
+#: (``code == "Not Found"``) and a non-envelope 404 from a proxy in front of
+#: the control plane (``code == "http_error"``, ``http.py``'s fallback).
+_CANCEL_UNAVAILABLE_MESSAGE = (
+    "Job cancel isn't available in this environment yet (the control plane here doesn't "
+    "support job cancellation). The job itself is unaffected — check its status with "
+    "`simulo jobs`."
+)
+#: Printed (exit 2) when the ID-LESS form is run non-interactively without ``--yes``.
+_CANCEL_NON_INTERACTIVE_REFUSAL = "refusing to cancel the latest job non-interactively without --yes"
+
+
+def _cancel_already_ended_message(job_id: str, server_message: str) -> str:
+    """The cancel-specific "already terminal" refusal (MAJOR fix, critic
+    review PR #345): the original implementation reused ``_job_ended_message``
+    verbatim, which is ``simulo view``'s copy ("live view is only available
+    while a job is running") — the wrong command's voice for a ``simulo
+    cancel`` caller. *server_message* is the cancel route's own 409 message,
+    which per the plan's wire contract carries the job's actual terminal
+    status (e.g. "job is 'completed', not running") — included parenthetically
+    rather than dropped, the same way ``_cmd_result`` surfaces
+    ``exc.message`` directly for its analogous "no result yet" 404.
+
+    NIT (critic review, deliberately left as-is): an already-cancelled job
+    also 409s here — script-unfriendly (a script that races a real cancel
+    against its own retry sees exit 1), but this IS the plan-pinned
+    contract, not a bug in this client.
+    """
+    return f"Job {job_id!r} has already ended — only a queued or running job can be cancelled. ({server_message})"
+
+
+def _stdin_is_tty() -> bool:
+    """``sys.stdin.isatty()`` behind a thin indirection.
+
+    Tests monkeypatch THIS function rather than swapping the real
+    interpreter-wide ``sys.stdin`` object: replacing ``sys.stdin`` itself
+    (even for one test, even restored via ``monkeypatch.setattr``) was tried
+    first and reliably hung a LATER, unrelated test file in the full suite —
+    pytest's own capture machinery holds long-lived references to the
+    original ``sys.stdin`` and gets confused by a mid-session swap. A plain
+    function monkeypatch has no such blast radius.
+    """
+    return sys.stdin.isatty()
+
+
+def _confirm_latest_job_cancel(job: dict[str, Any], *, assume_yes: bool) -> Optional[int]:
+    """Safety gate for the ID-LESS ``simulo cancel`` form ONLY (security MEDIUM,
+    PR #345 review).
+
+    The id-less form resolves the most recent job ORG-WIDE — no
+    ``created_by`` filter — so it can just as easily be a teammate's job as
+    the caller's own, and (before this gate) the resolution announce fired
+    in the same breath as the cancel POST, leaving no abort window. An
+    EXPLICIT ``JOB_ID`` is never gated here: naming the target IS the
+    confirmation, the same norm ``docker stop``/``gh run cancel`` use.
+
+    TTY: prompts ``Cancel job <id> (<name>, <status>)? [y/N] `` and proceeds
+    only on ``y``/``Y``/``yes`` (case-insensitive) — anything else (including
+    a bare Enter) aborts. Non-TTY (e.g. a script, a CI job, a pipe): refuses
+    outright unless ``--yes``/``-y`` was passed — there is no one to answer a
+    prompt, so silently proceeding would be exactly the footgun this gate
+    exists to close. ``--yes`` skips the prompt in both cases.
+
+    Returns ``None`` to proceed with the cancel (the cancel API is NOT called
+    yet at this point), or an exit code for the caller to return immediately
+    without ever calling it.
+    """
+    if assume_yes:
+        return None
+    if not _stdin_is_tty():
+        print(_CANCEL_NON_INTERACTIVE_REFUSAL, file=sys.stderr)
+        return 2
+    job_id = str(job.get("job_id"))
+    name = job.get("job_name", "-")
+    status = job.get("status", "-")
+    answer = input(f"Cancel job {job_id} ({name}, {status})? [y/N] ")
+    if answer.strip().lower() not in ("y", "yes"):
+        print("Nothing cancelled.", file=sys.stderr)
+        return 1
+    return None
+
+
+def _wait_for_cancel_confirmation(client: JobsApiClient, job_id: str, initial_status: str) -> dict[str, Any]:
+    """Poll a RUNNING job whose cancellation was just requested, until it goes terminal.
+
+    The ``simulo cancel`` twin of ``_wait_for_running_or_terminal``: prints
+    the wait message immediately via ``_WaitAnnouncer`` (then re-prints every
+    ``_SPINNER_REANNOUNCE_INTERVAL_S``, shared with the view-session waits —
+    a multi-minute cancel wait is not a frozen terminal either), while
+    actually re-fetching the job at the SEPARATE, slower
+    ``_CANCEL_POLL_INTERVAL_S`` (~2s) cadence — heartbeat-bounded cancel
+    latency (~15s worst case per the plan) does not need `simulo view`'s
+    faster queued-wait cadence. ``KeyboardInterrupt`` is NOT caught here — it
+    propagates to the caller, which prints the "cancel stays requested" note
+    and exits 130 (the server-side ``cancel_requested`` flag is untouched by
+    detaching from the wait).
+    """
+    announcer = _WaitAnnouncer(
+        "Cancel requested — waiting for the worker to stop the job... "
+        "(Ctrl-C to stop waiting; the cancel stays requested)"
+    )
+    job: dict[str, Any] = {"status": initial_status}
+    while str(job.get("status")) not in _TERMINAL_STATUS_STRINGS:
+        announcer.poll()
+        time.sleep(_CANCEL_POLL_INTERVAL_S)
+        job = client.get_job(job_id)
+    return job
+
+
+def _cmd_cancel(args: argparse.Namespace) -> int:
+    """``simulo cancel [JOB_ID] [--yes/-y]`` — request cancellation of a queued or running job.
+
+    JOB_ID omitted (the destructive-footgun case, security MEDIUM PR #345
+    review): resolve the most recent job over the API — ORG-WIDE, not just
+    the caller's own — announce it on stderr (the same latest-job default
+    the other observe commands use), then gate on confirmation
+    (``_confirm_latest_job_cancel``) BEFORE ever calling the cancel API: a
+    TTY prompts ``y``/``N``; a non-TTY (script/CI/pipe) refuses outright
+    (exit 2) unless ``--yes``/``-y`` was passed. JOB_ID given explicitly is
+    NEVER gated — naming the target is itself the confirmation (the same
+    norm ``docker stop``/``gh run cancel`` use); ``--yes`` is accepted and
+    silently ignored there, harmless for scripts that pass it unconditionally.
+
+    Past the gate, no pre-check of the job's current status (unlike
+    ``simulo view``, which needs it to decide whether to wait for a queued
+    job to start streaming): the cancel route's own response —
+    200/202/409/404 — already tells this command everything it needs.
+
+    * A QUEUED job is cancelled immediately (200): prints a one-line
+      confirmation and exits 0.
+    * A RUNNING job has cancellation requested (202, idempotent on repeat):
+      prints a wait message and polls (``_wait_for_cancel_confirmation``)
+      until the worker reports it terminal, then prints the final status —
+      exit 0 only if it reached ``cancelled`` (mirrors the follow loop's
+      "exit code mirrors outcome" rule; any other terminal status, e.g. the
+      job finished on its own in the race, is not what the user asked for).
+      Ctrl-C during the wait detaches WITHOUT un-cancelling: the server-side
+      request stays in effect, and this command exits 130 with a note to
+      check `simulo jobs`. A transient error mid-wait (e.g. a 5xx re-fetching
+      the job) gets the SAME "cancel remains requested" note, exit 1 —
+      never read as "the cancel failed".
+    * A job already in a terminal state (409 ``job_not_running``) is refused
+      with cancel-specific copy (``_cancel_already_ended_message``), exit 1
+      — including when the job is ALREADY ``cancelled`` (the plan-pinned
+      contract makes this a 409 too; script-unfriendly, but not a bug here).
+    * An unknown/cross-org job id (404 ``job_not_found``) is reported the
+      same way ``simulo logs``/``simulo view`` report one.
+    * A control plane without the cancel route at all (404 with any OTHER
+      code) degrades gracefully, mirroring ``simulo view``'s handling of a
+      missing view-session route — a clean one-liner, exit 1, no retry.
+    """
+    base_url, token = _resolve_client_context()
+    jobs_client = JobsApiClient(base_url, token=token)
+    cancel_client = CancelApiClient(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 cancel. Execute a package with "
+                "`simulo-backend run-package` to create one.",
+                file=sys.stderr,
+            )
+            return 1
+        job_id = _announce_latest(latest, "cancelling")
+        abort_code = _confirm_latest_job_cancel(latest, assume_yes=bool(args.yes))
+        if abort_code is not None:
+            return abort_code
+
+    try:
+        payload = cancel_client.cancel_job(job_id)
+    except CancelApiHTTPError as exc:
+        if exc.status == 404 and exc.code != _CANCEL_JOB_NOT_FOUND:
+            print(_CANCEL_UNAVAILABLE_MESSAGE, file=sys.stderr)
+            return 1
+        if exc.status == 404:
+            print(f"Job {job_id!r} not found. List runs with `simulo jobs`.", file=sys.stderr)
+            return 1
+        if exc.code == _CANCEL_JOB_NOT_RUNNING:
+            print(_cancel_already_ended_message(job_id, exc.message), file=sys.stderr)
+            return 1
+        raise
+
+    # Tolerant success classification (BLOCKER fix, critic review PR #345):
+    # the ONLY status that means "done, no further action" is "cancelled".
+    # ANY other successful body — the pinned "running" shape, a
+    # presentational variant like "cancelling", or anything else the server
+    # might legitimately report — means the job has not been confirmed
+    # stopped yet, so it feeds the wait loop below rather than hard-failing
+    # on an unrecognized-but-plausible in-progress status string. If the
+    # server ever reported a genuinely wrong terminal status here (e.g.
+    # "completed"), `_wait_for_cancel_confirmation` still degrades
+    # sensibly: it recognizes that status as terminal immediately (no
+    # polling) and the final report below reflects it honestly.
+    status = str(payload.get("status"))
+    if status == _CANCELLED_STATUS:
+        print(f"Job {job_id} cancelled.")
+        return 0
+
+    try:
+        job = _wait_for_cancel_confirmation(jobs_client, job_id, status)
+    except KeyboardInterrupt:
+        print(
+            f"\nStopped waiting — job {job_id}'s cancel remains requested. Check `simulo jobs` for its status.",
+            file=sys.stderr,
+        )
+        return 130
+    except JobsApiError as exc:
+        # MINOR (critic review PR #345): a transient error mid-wait (e.g. a
+        # 5xx blip re-fetching the job) must not read as "the cancel
+        # failed" — the server-side cancel_requested flag is untouched,
+        # exactly like the Ctrl-C path above, so the note matches it.
+        print(
+            f"error: {exc}\nThe cancel remains requested — check with `simulo jobs`.",
+            file=sys.stderr,
+        )
+        return 1
+
+    final_status = str(job.get("status"))
+    print(f"Job {job_id} is now {final_status}.")
+    return 0 if final_status == _CANCELLED_STATUS else 1
+
+
 def _observe_handler(
     subparser: argparse.ArgumentParser, command: Callable[[argparse.Namespace], int]
 ) -> Callable[[argparse.Namespace, Sequence[str]], int]:
@@ -1247,12 +1657,23 @@ def _observe_handler(
     return _handle
 
 
+def _nonnegative_int(value: str) -> int:
+    """argparse type for ``--tail N`` — a clear message beats ValueError's."""
+    try:
+        parsed = int(value)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"expected an integer number of lines, got {value!r}") from None
+    if parsed < 0:
+        raise argparse.ArgumentTypeError(f"expected a non-negative number of lines, got {parsed}")
+    return parsed
+
+
 def _build_parser() -> argparse.ArgumentParser:
     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 / view)."
+            "observe its runs (simulo jobs / logs / result / recordings / models / view / cancel)."
         ),
     )
     sub = parser.add_subparsers(dest="command", required=True)
@@ -1346,7 +1767,29 @@ def _build_parser() -> argparse.ArgumentParser:
     logs.add_argument(
         "--follow",
         action="store_true",
-        help="Poll for new output until the job finishes; exit code mirrors job success/failure.",
+        help=(
+            "Poll for new output until the job finishes, starting from the last "
+            f"{_DEFAULT_TAIL_LINES} lines of existing output (tail -f style; use --tail N or "
+            "--from-start to change that). Exit code mirrors job success/failure."
+        ),
+    )
+    tail_group = logs.add_mutually_exclusive_group()
+    tail_group.add_argument(
+        "--tail",
+        type=_nonnegative_int,
+        metavar="N",
+        default=None,
+        help=(
+            "Show only the last N lines of existing output (0 = none — with --follow, stream "
+            f"new output only). Default with --follow: {_DEFAULT_TAIL_LINES}. The request window is "
+            "sized by an assumed ~200 bytes/line, so an unusually large N of unusually long lines may "
+            "show fewer than N lines; use --from-start if you need an exact count."
+        ),
+    )
+    tail_group.add_argument(
+        "--from-start",
+        action="store_true",
+        help="Print the full log from the beginning (with --follow: full history, then live).",
     )
     logs.set_defaults(func=_observe_handler(logs, _cmd_logs))
 
@@ -1428,6 +1871,39 @@ def _build_parser() -> argparse.ArgumentParser:
         ),
     )
     view.set_defaults(func=_observe_handler(view, _cmd_view))
+
+    cancel = sub.add_parser(
+        "cancel",
+        help=(
+            "Request cancellation of a queued or running job "
+            "(POST /v1/jobs/{id}/cancel; default: the most recent job — confirmed before acting, "
+            "see --yes)."
+        ),
+    )
+    cancel.add_argument(
+        "job_id",
+        nargs="?",
+        default=None,
+        help=(
+            "Job id to cancel. Naming it explicitly skips confirmation (you named the target). "
+            "Omitted: cancels the most recent job ORG-WIDE — a destructive default, so it is "
+            "confirmed first: a `y`/`N` prompt on a terminal, or refused (exit 2) without --yes "
+            "when not running interactively. A queued job is cancelled immediately; a running "
+            "job has cancellation requested and this command waits for the worker to confirm it "
+            "(Ctrl-C to detach without un-cancelling)."
+        ),
+    )
+    cancel.add_argument(
+        "--yes",
+        "-y",
+        action="store_true",
+        help=(
+            "Skip the confirmation prompt for the no-JOB_ID form (required there when stdin "
+            "isn't a terminal, e.g. scripts/CI). Accepted and silently ignored when JOB_ID is "
+            "given explicitly, since that invocation is never prompted anyway."
+        ),
+    )
+    cancel.set_defaults(func=_observe_handler(cancel, _cmd_cancel))
     return parser
 
 

{simulo-0.9.0 → simulo-0.10.0}/src/simulo/_client/jobs_api.py

@@ -121,20 +121,37 @@ class JobsApiClient:
             raise JobsApiError(f"Malformed job record response for {job_id!r}.")
         return payload
 
-    def get_log_chunk(self, job_id: str, offset: int) -> tuple[str, int, str]:
-        """One log chunk from ``offset``; returns ``(chunk, next_offset, status)``.
+    def get_log_chunk(
+        self, job_id: str, offset: int, *, tail_bytes: Optional[int] = None
+    ) -> tuple[str, int, str, Optional[int]]:
+        """One log chunk from ``offset``; returns ``(chunk, next_offset, status, start_offset)``.
 
         Byte-offset semantics per the contract: resume from the returned
         ``next_offset``; an empty chunk with an unchanged offset means "caught
         up" — poll again while ``status`` is non-terminal.
+
+        ``tail_bytes`` (contract tail semantics; requires ``offset == 0``) asks
+        the server to start the read that many bytes before the END of the
+        stream. ``start_offset`` in the returned tuple is the server's computed
+        start position when tail was honored, and ``None`` otherwise —
+        including when ``tail_bytes`` was requested but the server is too old
+        to know the parameter (it then answers from offset 0 exactly like a
+        plain request; callers use ``start_offset is None`` to detect that and
+        degrade to full history rather than mis-trim).
         """
-        payload = self._get(JOB_LOGS_ROUTE_TEMPLATE.format(job_id=_quote(job_id)), {"offset": str(offset)})
+        query = {"offset": str(offset)}
+        if tail_bytes is not None:
+            query["tail_bytes"] = str(tail_bytes)
+        payload = self._get(JOB_LOGS_ROUTE_TEMPLATE.format(job_id=_quote(job_id)), query)
         if not isinstance(payload, dict):
             raise JobsApiError(f"Malformed log chunk response for {job_id!r}.")
         chunk, next_offset, status = payload.get("chunk"), payload.get("next_offset"), payload.get("status")
         if not isinstance(chunk, str) or not isinstance(next_offset, int) or not isinstance(status, str):
             raise JobsApiError(f"Malformed log chunk response for {job_id!r}: {payload!r}.")
-        return chunk, next_offset, status
+        start_offset = payload.get("start_offset") if tail_bytes is not None else None
+        if start_offset is not None and not isinstance(start_offset, int):
+            raise JobsApiError(f"Malformed log chunk response for {job_id!r}: {payload!r}.")
+        return chunk, next_offset, status, start_offset
 
     def get_result(self, job_id: str) -> Any:
         """The result JSON. 404 :class:`JobsApiHTTPError` until the job succeeded."""

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simulo
-Version: 0.9.0
+Version: 0.10.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.4,>=0.3
 Requires-Dist: mcap<2,>=1.3
 Provides-Extra: dev
 Requires-Dist: black>=24.0; extra == "dev"

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

@@ -17,6 +17,7 @@ src/simulo/_client/_runner.py
 src/simulo/_client/app.py
 src/simulo/_client/asset.py
 src/simulo/_client/bundle.py
+src/simulo/_client/cancel_api.py
 src/simulo/_client/cli.py
 src/simulo/_client/config.py
 src/simulo/_client/credentials.py

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

@@ -1,4 +1,4 @@
-simulo-interfaces<0.3,>=0.2
+simulo-interfaces<0.4,>=0.3
 mcap<2,>=1.3
 
 [dev]