mammoth-cli 2.0.84__tar.gz → 2.0.85__tar.gz

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.0.84
+Version: 2.0.85
 Summary: Command-line interface for the Mammoth Analytics platform
 Project-URL: homepage, https://mammoth.io
 Project-URL: repository, https://github.com/EdgeMetric/mammothsdk
@@ -17,7 +17,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.15,>=3.12
 Requires-Dist: jsonschema>=4.20
 Requires-Dist: keyring<26,>=25.7
-Requires-Dist: mammoth-io<0.8,>=0.7.38
+Requires-Dist: mammoth-io<0.8,>=0.7.39
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/mammoth_cli/__init__.py

@@ -6,7 +6,7 @@ not implement a second HTTP client and does not call private SDK members.
 
 from __future__ import annotations
 
-__version__ = "2.0.84"
+__version__ = "2.0.85"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/mammoth_cli/app.py

@@ -579,6 +579,24 @@ def _shared_option_params() -> list[inspect.Parameter]:
                 ),
             ],
         ),
+        opt(
+            "return_running",
+            False,
+            Annotated[
+                bool,
+                typer.Option(
+                    "--return-running",
+                    help=(
+                        "When a job or pipeline wait runs out, exit 0 with "
+                        "{status: running, job_id or dataview_id, resume} instead of a "
+                        "timeout error; resume with 'mammoth job wait JOB_ID' "
+                        "(reports success, failure or still running; waits at most "
+                        "15 minutes by default)."
+                    ),
+                    rich_help_panel="Context and timeouts",
+                ),
+            ],
+        ),
         opt(
             "pipeline_timeout",
             None,

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/mammoth_cli/bundled_skill/mammoth-cli/references/jobs-drafts.md

@@ -24,6 +24,11 @@ or wait that job — inspect it rather than submitting the original mutation.
 The `--job-timeout` /
 `--pipeline-timeout` options bound the wait.
 
+With `--return-running` a wait that runs out exits 0 with `{status: running, job_id, resume}`
+(`dataview_id` for a pipeline wait). `mammoth job wait JOB_ID` resumes: it returns
+`{status: success, job_id, result}`, a `job_failed` error with the reason, or the running handle
+again, and waits at most 15 minutes by default.
+
 A transport failure during a mutation without a confirmed job/resource handle
 is `outcome_unknown`. Re-read the exact target and scope before replaying it;
 the operation may already have committed.

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/mammoth_cli/commands/job.py

@@ -30,6 +30,7 @@ from mammoth_cli.runtime.session import open_service
 HandlerResult = tuple[Any, dict[str, Any]]
 
 _WAIT_OPTIONAL = ("timeout", "poll_interval")
+_DASHBOARD_WAIT_SYMBOL = "mammoth.api.dashboards.DashboardsAPI.wait_for_job_by_url"
 
 
 def _symbol(invocation: Invocation) -> str:
@@ -127,20 +128,48 @@ def job_get_many(invocation: Invocation) -> HandlerResult:
     return data, _meta(invocation, auth.workspace_id)
 
 
-def job_wait(invocation: Invocation) -> HandlerResult:
-    """Block until one job completes, or raise on failure/timeout.
+def _wait_call(
+    invocation: Invocation, document: dict[str, Any], kwargs: dict[str, Any]
+) -> tuple[str, dict[str, Any]]:
+    """The SDK symbol and arguments for one job wait.
+
+    A ``dashboard_url`` field switches to the URL-scoped wait: jobs dispatched
+    by published-dashboard routes are unreadable through ``GET /jobs/{id}``.
+    """
+    if "dashboard_url" not in document:
+        return _symbol(invocation), kwargs
+    return _DASHBOARD_WAIT_SYMBOL, {**kwargs, "url": document["dashboard_url"]}
+
 
-    The job id is a positional argument; optional ``timeout`` and
-    ``poll_interval`` fields are forwarded from the ``--input`` document when
-    present.
+def _wait_result(job_id: int, job: Any) -> dict[str, Any]:
+    """The ``job wait`` success payload: the job's response, plus what the job was."""
+    data: dict[str, Any] = {"status": "success", "job_id": job_id}
+    if isinstance(job, dict):
+        data.update({key: job[key] for key in ("operation", "path") if job.get(key) is not None})
+        data["result"] = job.get("response", job)
+    else:
+        data["result"] = job
+    return data
+
+
+def job_wait(invocation: Invocation) -> HandlerResult:
+    """Wait for one job and report success, failure, or still running (15 min default).
+
+    The job id is a positional argument; optional ``timeout``, ``poll_interval``
+    and ``dashboard_url`` (a published dashboard's URL slug) fields are read from
+    the ``--input`` document. Success returns ``{status, job_id, result}``; a
+    failed job is a ``job_failed`` error with its reason; a wait that runs out is
+    a ``timeout`` error, or with ``--return-running`` ``{status: running, job_id,
+    resume}``.
     """
     job_id = _require_int_positional(invocation, "job id")
     document = invocation.load_input() or {}
     kwargs: dict[str, Any] = {"job_id": job_id}
     _forward_optional(document, kwargs, _WAIT_OPTIONAL)
+    symbol, kwargs = _wait_call(invocation, document, kwargs)
     try:
         with open_service(invocation) as (service, auth):
-            data = service.call(_symbol(invocation), **kwargs)
+            data = _wait_result(job_id, service.call(symbol, **kwargs))
     except KeyboardInterrupt as exc:
         # Keep the explicit handle even when the polling implementation raises
         # a bare SIGINT.  A caller can inspect/resume it without replaying the

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/mammoth_cli/embed.py

@@ -41,6 +41,8 @@ def invoke(
     project_id: int | None = None,
     timeout: float | None = None,
     pipeline_timeout: float | None = None,
+    job_timeout: float | None = None,
+    return_running: bool = False,
 ) -> dict[str, Any]:
     """Run ``mammoth <args>`` as ``login`` and return its envelope.
 
@@ -54,12 +56,23 @@ def invoke(
             ``args`` already sets one.
         pipeline_timeout: Pipeline wait timeout in seconds, sent as
             ``--pipeline-timeout`` unless ``args`` already sets one.
+        job_timeout: Job wait timeout in seconds, sent as ``--job-timeout``
+            unless ``args`` already sets one.
+        return_running: Send ``--return-running`` so a wait that runs out
+            returns a ``status: running`` handle instead of a timeout error.
 
     Returns:
         The success envelope (``data`` + ``meta``) or the error envelope
         (``error``). A CLI error is returned, never raised.
     """
-    argv = _argv(args, project_id=project_id, timeout=timeout, pipeline_timeout=pipeline_timeout)
+    argv = _argv(
+        args,
+        project_id=project_id,
+        timeout=timeout,
+        pipeline_timeout=pipeline_timeout,
+        job_timeout=job_timeout,
+        return_running=return_running,
+    )
     call = embedded.EmbeddedCall(login=login)
     token = embedded.enter(call)
     try:
@@ -77,6 +90,8 @@ def _argv(
     project_id: int | None,
     timeout: float | None,
     pipeline_timeout: float | None,
+    job_timeout: float | None,
+    return_running: bool,
 ) -> list[str]:
     """``args`` plus the options an embedded call always runs with."""
     argv = list(args)
@@ -86,6 +101,10 @@ def _argv(
         argv += ["--timeout", str(timeout)]
     if pipeline_timeout is not None and not _has_option(argv, "--pipeline-timeout"):
         argv += ["--pipeline-timeout", str(pipeline_timeout)]
+    if job_timeout is not None and not _has_option(argv, "--job-timeout"):
+        argv += ["--job-timeout", str(job_timeout)]
+    if return_running and not _has_option(argv, "--return-running"):
+        argv.append("--return-running")
     # Last, so they win over any output or input option in ``args``.
     return [*argv, "--output", "json", "--no-input"]
 

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/mammoth_cli/runtime/executor.py

@@ -24,7 +24,7 @@ from mammoth_cli.output.render import render
 from mammoth_cli.runtime import embedded, updates
 from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.runlog import RunLog
-from mammoth_cli.services.mapping import map_sdk_exception
+from mammoth_cli.services.mapping import map_sdk_exception, running_handle
 
 Producer = Callable[[], tuple[Any, dict[str, Any]]]
 
@@ -193,8 +193,17 @@ def run(
         emit_success(command_id, data, output, update_available=update, **meta_extra)
         updates.emit_hint(update, output=output)
     except CliError as error:
-        fail(error)
-        raise typer.Exit(error.exit_status) from None
+        running = (
+            running_handle(error, command_id)
+            if invocation is not None and invocation.return_running
+            else None
+        )
+        if running is None:
+            fail(error)
+            raise typer.Exit(error.exit_status) from None
+        # --return-running: a wait that ran out is not a failure; hand back the
+        # handle to resume with.
+        emit_success(command_id, running, output, profile=profile)
     except KeyboardInterrupt as exc:
         # Polling can be interrupted after a job handle was observed.  Keep
         # that handle when an SDK exception exposes one; never turn Ctrl-C

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/mammoth_cli/runtime/invocation.py

@@ -53,6 +53,7 @@ class Invocation:
     timeout: float | None = None
     job_timeout: float | None = None
     pipeline_timeout: float | None = None
+    return_running: bool = False
     color: str = "auto"
     no_input: bool = False
     no_progress: bool = False
@@ -146,7 +147,7 @@ class Invocation:
                 continue
             try:
                 value = float(raw)
-            except (TypeError, ValueError):
+            except TypeError, ValueError:
                 continue
             if value > 0:
                 object.__setattr__(self, key, value)
@@ -228,7 +229,7 @@ class Invocation:
                     resource_dataset = int(resource_dataset)
                     if resource_dataset <= 0:
                         raise ValueError
-                except (TypeError, ValueError):
+                except TypeError, ValueError:
                     raise CliError(
                         code="invalid_resource_context",
                         message="Input field 'dataset_id' must be a positive integer.",
@@ -251,7 +252,7 @@ class Invocation:
                     expected_tasks = int(expected_tasks)
                     if expected_tasks < 0:
                         raise ValueError
-                except (TypeError, ValueError):
+                except TypeError, ValueError:
                     raise CliError(
                         code="invalid_resource_context",
                         message=f"Input field '{TASK_COUNT_FIELD}' must be a non-negative integer.",

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/mammoth_cli/runtime/session.py

@@ -32,9 +32,17 @@ from mammoth_cli.services.protocol import MammothService
 #: pass ``--timeout 300`` by hand. Reads keep the SDK default.
 DEFAULT_MUTATION_JOB_TIMEOUT = 300.0
 
+#: Wait budget for ``job wait`` / ``job wait-many`` when no timeout was given:
+#: long enough for a big transform, and never unbounded, so a resuming agent
+#: is always told the job's state (success, failure, or still running).
+DEFAULT_JOB_WAIT_TIMEOUT = 900.0
+_JOB_WAIT_COMMANDS = ("job.wait", "job.wait-many")
+
 
 def default_job_timeout(command_id: str) -> float | None:
     """The job-wait timeout for ``command_id`` when none was configured."""
+    if command_id in _JOB_WAIT_COMMANDS:
+        return DEFAULT_JOB_WAIT_TIMEOUT
     record = command_by_id(command_id) or {}
     if record.get("mutation_class", "read") in (None, "read"):
         return None

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/mammoth_cli/runtime/state.py

@@ -187,6 +187,7 @@ def _read_invocation(command_id: str, resolved_ids: dict[str, Any], base: Invoca
         timeout=base.timeout,
         job_timeout=base.job_timeout,
         pipeline_timeout=base.pipeline_timeout,
+        return_running=base.return_running,
         no_input=True,
         positionals=positionals,
         extra_args=extra_args,

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/mammoth_cli/services/command_contract.py

@@ -603,6 +603,9 @@ S7_COMMANDS = frozenset(
 # admission, and handler binding agree instead of treating every arbitrary
 # keyword as valid.
 _S7_ADDITIONAL_INPUT_FIELDS: dict[str, tuple[FieldSpec, ...]] = {
+    # Published-dashboard jobs are readable only through the URL-scoped job
+    # route; ``job wait`` polls it when the dashboard URL slug is given.
+    "job.wait": (FieldSpec("dashboard_url", required=False, annotation=str | None, default=None),),
     # The GET data route has no server-side page size; the CLI trims the row
     # list so a read-back costs a screen of tokens, not the whole view.
     "view.data.get": (

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/mammoth_cli/services/mapping.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import re
 import shlex
 from typing import Any
@@ -13,6 +14,7 @@ from mammoth.exceptions import (
     MammothError,
     MammothJobFailedError,
     MammothJobTimeoutError,
+    MammothPipelineTimeoutError,
     MammothValidationError,
     safe_response_body,
 )
@@ -107,6 +109,23 @@ def _job_recovery(job_id: object, *, profile: str | None = None) -> list[str]:
     ]
 
 
+def _pipeline_recovery(exc: MammothPipelineTimeoutError, *, profile: str | None) -> list[str]:
+    scope = f" --project {exc.project_id}" if exc.project_id is not None else ""
+    scope += f" --profile {shlex.quote(profile)}" if profile else ""
+    return [
+        f"mammoth view pipeline get {exc.dataview_id}{scope}",
+        f"mammoth view pipeline wait {exc.dataview_id}{scope}",
+    ]
+
+
+def _observed_job_fields(details: dict[str, Any]) -> dict[str, Any]:
+    """The ``operation``/``path`` of the last observed job, when the server sent them."""
+    observed = details.get("observed_job")
+    if not isinstance(observed, dict):
+        return {}
+    return {key: observed[key] for key in ("operation", "path") if observed.get(key) is not None}
+
+
 _PROJECT_DELETE = re.compile(r"/workspaces/\d+/projects/(\d+)/?$")
 _DASHBOARD_WRITE = re.compile(r"/dashboards/(\d+)(?:/|$)")
 _ENDPOINT_WORKSPACE = re.compile(r"/workspaces/(\d+)")
@@ -168,6 +187,49 @@ def _resource_recovery(
     return []
 
 
+def with_dashboard_scope(error: CliError, dashboard_url: str) -> CliError:
+    """Point a timed-out published-dashboard job's recovery at the URL-scoped route.
+
+    ``GET /jobs/{id}`` answers ``4PERM002`` for these jobs, so the generic
+    ``job get``/``job wait`` recovery would fail; ``job wait`` takes the
+    dashboard URL as an ``--input`` field and polls the URL-scoped route.
+    """
+    job_id = error.details.get("job_id")
+    if error.code != "timeout" or job_id is None:
+        return error
+    document = shlex.quote(json.dumps({"dashboard_url": dashboard_url}))
+    error.details["resume"] = f"mammoth job wait {job_id} --input {document}"
+    error.recovery_commands = [
+        f"mammoth dashboard job-by-url {shlex.quote(dashboard_url)} {job_id}",
+        error.details["resume"],
+    ]
+    return error
+
+
+def running_handle(error: CliError, command_id: str) -> dict[str, Any] | None:
+    """The ``status: running`` payload for a wait that ran out, else ``None``.
+
+    Used by ``--return-running``: a job wait or pipeline wait that timed out is
+    not a failure, so the caller gets the handle to resume with instead.
+    """
+    details = error.details
+    if error.code != "timeout" or "resume" not in details:
+        return None
+    if details.get("phase") == "pipeline" and "dataview_id" in details:
+        handle: dict[str, Any] = {"dataview_id": details["dataview_id"]}
+    elif "job_id" in details:
+        handle = {"job_id": details["job_id"], **_observed_job_fields(details)}
+    else:
+        return None
+    return {
+        "status": "running",
+        **handle,
+        "command": command_id,
+        "waited_seconds": details.get("waited_seconds"),
+        "resume": details["resume"],
+    }
+
+
 def map_sdk_exception(
     exc: BaseException,
     *,
@@ -206,6 +268,21 @@ def map_sdk_exception(
             recovery_commands=["mammoth auth login"],
         )
 
+    if isinstance(exc, MammothPipelineTimeoutError):
+        recovery = _pipeline_recovery(exc, profile=profile)
+        details = dict(exc.details)
+        details["waited_seconds"] = details.get("timeout")
+        details["resume"] = recovery[1]
+        return CliError(
+            code="timeout",
+            message="The view pipeline did not finish before the timeout.",
+            exit_status=EXIT_RETRYABLE,
+            hint="No job is involved; read the view's pipeline state and wait for it to finish.",
+            details=details,
+            retryable=True,
+            recovery_commands=recovery,
+        )
+
     if isinstance(exc, MammothJobTimeoutError):
         job_id = getattr(exc, "job_handle", None) or getattr(exc, "job_id", None)
         details = dict(getattr(exc, "details", {}) or {})
@@ -213,6 +290,10 @@ def map_sdk_exception(
             details.setdefault("job_id", job_id)
         details.setdefault("operation_state", "running")
         details.setdefault("phase", getattr(exc, "phase", None) or "polling")
+        details.update(_observed_job_fields(details))
+        details["waited_seconds"] = details.get("timeout")
+        if job_id is not None:
+            details["resume"] = _job_recovery(job_id, profile=profile)[1]
         return CliError(
             code="timeout",
             message="The operation did not finish before the timeout.",
@@ -226,13 +307,18 @@ def map_sdk_exception(
     if isinstance(exc, MammothJobFailedError):
         details = dict(getattr(exc, "details", {}) or {})
         job_id = getattr(exc, "job_handle", None) or getattr(exc, "job_id", None)
+        details["status"] = "failure"
+        details["reason"] = details.get("failure_reason") or "no reason recorded by the job"
+        details.update(_observed_job_fields(details))
         return CliError(
             code=CODE_JOB_FAILED,
-            message="The Mammoth job failed.",
+            message=f"The Mammoth job failed: {details['reason']}",
             exit_status=EXIT_API,
             hint="Inspect the job response for the failure reason.",
             details=details,
-            recovery_commands=_job_recovery(job_id, profile=profile) if job_id is not None else [],
+            recovery_commands=(
+                _job_recovery(job_id, profile=profile)[:1] if job_id is not None else []
+            ),
         )
 
     if isinstance(exc, MammothAPIError):

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/mammoth_cli/services/sdk_service.py

@@ -32,7 +32,7 @@ from mammoth_cli.runtime import parents
 from mammoth_cli.services.coerce import coerce_arguments
 from mammoth_cli.services.conditions import CONDITION_KWARG, compile_condition
 from mammoth_cli.services.dispatch import resolve_sdk_method
-from mammoth_cli.services.mapping import map_sdk_exception
+from mammoth_cli.services.mapping import map_sdk_exception, with_dashboard_scope
 
 #: Largest ``limit`` the projects route accepts (``4GENR007`` above it).
 _PROJECT_MISS = re.compile(r"^Project (ID \d+|'.*') not found\.")
@@ -284,7 +284,10 @@ class SdkMammothService:
                     fetch=lambda job_id, _remaining: dashboards.job_by_url(dashboard_url, job_id),
                 )
         except Exception as exc:
-            raise map_sdk_exception(exc) from exc
+            mapped = map_sdk_exception(exc)
+            if dashboard_url is not None:
+                mapped = with_dashboard_scope(mapped, dashboard_url)
+            raise mapped from exc
 
     def call_view(
         self,

{mammoth_cli-2.0.84 → mammoth_cli-2.0.85}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "mammoth-cli"
-version = "2.0.84"
+version = "2.0.85"
 description = "Command-line interface for the Mammoth Analytics platform"
 authors = [{name = "Mammoth Analytics", email = "support@mammoth.io"}]
 readme = "README.md"
 license = "LicenseRef-Proprietary"
 requires-python = ">=3.12,<3.15"
 dependencies = [
-    "mammoth-io (>=0.7.38,<0.8)",
+    "mammoth-io (>=0.7.39,<0.8)",
     "typer (>=0.27,<0.28)",
     "rich (>=15,<16)",
     "platformdirs (>=4.10,<5)",