mammoth-cli 2.2.45__tar.gz → 2.2.47__tar.gz

{mammoth_cli-2.2.45 → mammoth_cli-2.2.47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mammoth-cli
-Version: 2.2.45
+Version: 2.2.47
 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.9,>=0.8.23
+Requires-Dist: mammoth-io<0.9,>=0.8.25
 Requires-Dist: platformdirs<5,>=4.10
 Requires-Dist: pydantic<3,>=2.12.5
 Requires-Dist: pyyaml<7,>=6

{mammoth_cli-2.2.45 → mammoth_cli-2.2.47}/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.2.45"
+__version__ = "2.2.47"
 
 # The versioned machine output envelope contract.
 SCHEMA_VERSION = 1

{mammoth_cli-2.2.45 → mammoth_cli-2.2.47}/mammoth_cli/app.py

@@ -46,6 +46,7 @@ from mammoth_cli.runtime import executor, validate
 from mammoth_cli.runtime.dataset_health import with_dataset_health
 from mammoth_cli.runtime.intent_only import refuse_hand_crafted_write
 from mammoth_cli.runtime.invocation import Invocation
+from mammoth_cli.runtime.locked_files import with_locked_files
 from mammoth_cli.runtime.new_data import with_new_data_path
 from mammoth_cli.runtime.state import with_state
 from mammoth_cli.runtime.strict import validate_extra_args
@@ -717,6 +718,18 @@ def _shared_option_params() -> list[inspect.Parameter]:
                 ),
             ],
         ),
+        opt(
+            "allow_empty",
+            False,
+            Annotated[
+                bool,
+                typer.Option(
+                    "--allow-empty",
+                    help="Add a keep filter that matches no row; without it the dry run fails.",
+                    rich_help_panel="Safety",
+                ),
+            ],
+        ),
         opt(
             "input_file",
             None,
@@ -869,7 +882,8 @@ def _execute(invocation: Invocation) -> None:
         if invocation.dry_run:
             return _dry_run(handler, invocation)
         data, meta = handler(invocation)
-        return with_new_data_path(with_dataset_health(_apply_verify(invocation, data))), meta
+        checked = with_locked_files(with_dataset_health(_apply_verify(invocation, data)))
+        return with_new_data_path(checked), meta
 
     executor.run(
         invocation.command_id,

{mammoth_cli-2.2.45 → mammoth_cli-2.2.47}/mammoth_cli/commands/schema.py

@@ -500,6 +500,10 @@ _COMMAND_DISCOVERY_PURPOSES = {
         "connect our own internal custom api build a connector for an unsupported source"
     ),
     "file.set-password": "locked password protected file pdf excel unlock",
+    "file.update": (
+        "pdf extraction method choose select pending tables only all content custom "
+        "uploaded pdf file extract_pdf_tables"
+    ),
     "project.sample-flow": "sample example demo starter data dataset try start from",
     "webhook.create": (
         "webhook http endpoint api push create data pushed in sent from another system receive "

{mammoth_cli-2.2.45 → mammoth_cli-2.2.47}/mammoth_cli/commands/view.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 import dataclasses
 import inspect
 import shlex
+import time
 from collections.abc import Callable
 from datetime import UTC, datetime
 from decimal import Decimal, InvalidOperation
@@ -4528,6 +4529,29 @@ def wait_for_view_row_count(
     return rows_after, pipeline_error
 
 
+#: Bounded wait for a submitted draft's data: its steps run after the submit returns.
+_REFRESH_ATTEMPTS = 40
+_REFRESH_RETRY_S = 0.5
+
+
+def wait_for_refreshed_view(
+    service: Any, dataset_id: int, view_id: int, project_id: int | None, stamp_before: Any
+) -> dict[str, Any] | None:
+    """The view's record once its ``data_updated_at`` has moved past ``stamp_before``.
+
+    ``None`` when it never did within the bound; the caller reports that as
+    unfinished, never as a row count it did not see refreshed.
+    """
+    for _ in range(_REFRESH_ATTEMPTS):
+        info = service.call(
+            _DATAVIEW_GET_SYMBOL, dataset_id=dataset_id, dataview_id=view_id, project_id=project_id
+        )
+        if isinstance(info, dict) and info.get("data_updated_at") != stamp_before:
+            return info
+        time.sleep(_REFRESH_RETRY_S)
+    return None
+
+
 def _row_count_now(service: Any, dataset_id: int, view_id: int, project_id: int | None) -> Any:
     """A view's row count, read directly with no settle wait.
 
@@ -4582,7 +4606,11 @@ def _settle_async_view_write(
         return data
     dataset_id = int(dataset_id)
     row_check: dict[str, Any] = dict(before or {"rows_before": None})
-    rows_after, pipeline_error = wait_for_view_row_count(service, dataset_id, view_id, project_id)
+    # The response names the follow-on job that runs the pipeline; read back
+    # before it ends and the view still shows the old row count (FB-05).
+    rows_after, pipeline_error = wait_for_view_row_count(
+        service, dataset_id, view_id, project_id, write_result=data
+    )
     row_check["rows_after"] = rows_after
     data = {**data, "row_check": row_check}
     if pipeline_error is not None:

{mammoth_cli-2.2.45 → mammoth_cli-2.2.47}/mammoth_cli/commands/view_ops.py

@@ -20,6 +20,7 @@ enum-typed fields are forwarded as the plain string given on ``--input``.
 from __future__ import annotations
 
 import json
+import re
 import shlex
 from collections.abc import Callable
 from datetime import UTC, datetime, timedelta
@@ -29,6 +30,7 @@ from mammoth_cli.commands.view import (
     _DATAVIEW_GET_SYMBOL,
     _FIND_DATASET_SYMBOL,
     BRIEF_VIEW_FIELDS,
+    UNFINISHED_STATE,
     _dataview_metadata,
     _require_discovery_allowed,
     apply_column_renames,
@@ -39,6 +41,7 @@ from mammoth_cli.commands.view import (
     reject_dataset_export_conflicts,
     wait_for_followon_job,
     wait_for_pipeline_to_settle,
+    wait_for_refreshed_view,
     wait_for_view_row_count,
     with_join_check,
 )
@@ -60,12 +63,13 @@ from mammoth_cli.runtime.dryrun import DryRunStop
 from mammoth_cli.runtime.invocation import Invocation
 from mammoth_cli.runtime.session import open_service, resolved_project
 from mammoth_cli.services.command_contract import bind_command_inputs
-from mammoth_cli.services.conditions import CONDITION_KWARG
+from mammoth_cli.services.conditions import CONDITION_KWARG, compile_condition
 from mammoth_cli.services.input_fields import TASK_COUNT_FIELD
 from mammoth_cli.services.sql_check import check_sql_binds
 from mammoth_cli.services.write_impact import (
     ImpactRead,
     Measure,
+    empties_view_error,
     measure_bulk_replace,
     measure_duplicates,
     measure_fill_missing,
@@ -438,6 +442,7 @@ def _flag_unsettled_pipeline(service: Any, dataset_id: int, view_id: int, data:
 
 
 CODE_PIPELINE_CHANGED = "pipeline_changed"
+_DRAFT_STATUS_SYMBOL = "mammoth.api.pipeline.PipelineAPI.get_draft_status"
 _TASK_LIST_SYMBOL = "mammoth.api.pipeline.PipelineAPI.list_tasks"
 
 
@@ -911,7 +916,62 @@ def view_draft_status(invocation: Invocation) -> HandlerResult:
 def view_draft_submit(invocation: Invocation) -> HandlerResult:
     """Submit a view's draft pipeline changes."""
     view_id = _view_id(invocation)
-    return _dispatch_view(invocation, view_id, "submit_draft")
+    project_id = invocation.project
+
+    def before(service: Any, dataset_id: int) -> dict[str, Any]:
+        return _draft_before_submit(service, dataset_id, view_id, project_id)
+
+    def after(service: Any, dataset_id: int, state: Any, data: Any) -> Any:
+        return _draft_submit_row_check(service, dataset_id, view_id, project_id, state, data)
+
+    return _dispatch_view(invocation, view_id, "submit_draft", before=before, after=after)
+
+
+def _draft_before_submit(
+    service: Any, dataset_id: int, view_id: int, project_id: int | None
+) -> dict[str, Any]:
+    """The view's row count and data timestamp, and whether its draft has changes to run."""
+    info = service.call(
+        _DATAVIEW_GET_SYMBOL, dataset_id=dataset_id, dataview_id=view_id, project_id=project_id
+    )
+    draft = service.call(_DRAFT_STATUS_SYMBOL, dataview_id=view_id)
+    return {
+        "row_count": info.get("row_count"),
+        "stamp": info.get("data_updated_at"),
+        "pending": bool(draft.get("has_pending_changes")),
+    }
+
+
+def _draft_submit_row_check(
+    service: Any,
+    dataset_id: int,
+    view_id: int,
+    project_id: int | None,
+    before: dict[str, Any],
+    data: Any,
+) -> Any:
+    """``data`` with the row count read once the submitted steps' data is in.
+
+    The submit returns with the pipeline ``idle`` while its steps still run, so a
+    count read at once is the old one (FB-22). A draft with nothing to run is
+    read at once; data that never refreshes is reported as unfinished.
+    """
+    if not isinstance(data, dict):
+        return data
+    if before["pending"]:
+        info = wait_for_refreshed_view(service, dataset_id, view_id, project_id, before["stamp"])
+    else:
+        info = service.call(
+            _DATAVIEW_GET_SYMBOL, dataset_id=dataset_id, dataview_id=view_id, project_id=project_id
+        )
+    rows_after = info.get("row_count") if info is not None else None
+    out = {**data, "row_check": {"rows_before": before["row_count"], "rows_after": rows_after}}
+    if info is None:
+        out["pipeline_error"] = {
+            "execution_state": UNFINISHED_STATE,
+            "wait_error": "the view's data was not refreshed after the submit; read it again",
+        }
+    return out
 
 
 def view_draft_discard(invocation: Invocation) -> HandlerResult:
@@ -1161,7 +1221,8 @@ def _impact_check(
 
     A count of zero is a no-op: ``--dry-run`` fails with ``no_op`` and a real run
     adds no task (``status: no_change``, like a same-type convert). Otherwise a
-    dry run reports the count as ``predicted_impact``. A count that cannot run
+    dry run reports the count as ``predicted_impact``. A keep filter no row matches
+    fails a dry run with ``empties_view`` unless ``--allow-empty`` is set. A count that cannot run
     is reported as unchecked in a dry run, never as zero, and never blocks a write.
     """
 
@@ -1187,6 +1248,8 @@ def _impact_check(
                     invocation, "predicted_impact", {"checked": False, "reason": exc.message}
                 )
             return None
+        if measured.empties_message and invocation.dry_run and not invocation.allow_empty:
+            raise empties_view_error(measured.empties_message, view_id=view_id)
         if measured.changes == 0:
             if invocation.dry_run:
                 raise no_op_error(measured.no_op_message, view_id=view_id)
@@ -1386,7 +1449,57 @@ def view_transform_math(invocation: Invocation) -> HandlerResult:
     assert document is not None
     _require_one_destination(document, invocation.command_id)
     kwargs = _bind_transform_inputs(invocation, document)
-    return _dispatch_view(invocation, view_id, "math", **kwargs)
+    blanks: dict[str, int] = {}
+
+    def count_blank_inputs(service: Any, dataset_id: int, _kwargs: dict[str, Any]) -> None:
+        blanks.update(
+            _blank_math_inputs(
+                service, dataset_id, view_id, resolved_project(invocation), document["expression"]
+            )
+        )
+
+    data, meta = _dispatch_view(invocation, view_id, "math", prepare=count_blank_inputs, **kwargs)
+    return _with_blank_input_note(data, blanks), meta
+
+
+def _blank_math_inputs(
+    service: Any, dataset_id: int, view_id: int, project_id: int | None, expression: Any
+) -> dict[str, int]:
+    """Blank cells of each column a math expression names, for the columns that have any.
+
+    Mammoth computes a blank input as 0, so ``qty * unit_price`` gives 0 for an
+    unpriced row and a later total counts it with no warning (FB-01).
+    """
+    info = service.call(
+        _DATAVIEW_GET_SYMBOL, dataset_id=dataset_id, dataview_id=view_id, project_id=project_id
+    )
+    read = ImpactRead(service, dataset_id, view_id, project_id, apply_column_renames(info))
+    text = str(expression)
+    named = [
+        name
+        for name in read.display_to_internal()
+        if re.search(rf"(?<![\w]){re.escape(name)}(?![\w])", text)
+    ]
+    try:
+        counts = {
+            name: read.count(compile_condition({"column": name, "operator": "IS_EMPTY"}))
+            for name in named
+        }
+    except CliError:
+        return {}  # A count that cannot run never blocks the write; it only drops the note.
+    return {name: count for name, count in counts.items() if count}
+
+
+def _with_blank_input_note(data: Any, blanks: dict[str, int]) -> Any:
+    """``data`` with a ``blank_inputs`` note when a math input column has blanks."""
+    if not blanks or not isinstance(data, dict):
+        return data
+    listed = ", ".join(f"{name} is blank in {count} row(s)" for name, count in blanks.items())
+    note = (
+        f"A blank input counts as 0 in this math step: {listed}, so the result there is "
+        "computed as if it were 0. Fill or filter those rows first if a blank must not count as 0."
+    )
+    return {**data, "blank_inputs": {"columns": blanks, "note": note}}
 
 
 def view_transform_pivot(invocation: Invocation) -> HandlerResult:

{mammoth_cli-2.2.45 → mammoth_cli-2.2.47}/mammoth_cli/errors/envelope.py

@@ -58,6 +58,7 @@ CODE_INTERRUPTED = "interrupted"
 CODE_UNSUPPORTED_CONTRACT = "unsupported_contract"
 CODE_NO_OP = "no_op"
 CODE_WOULD_FAIL = "would_fail"
+CODE_EMPTIES_VIEW = "empties_view"
 
 # User-safe, one-line summaries shown to the customer instead of the model-facing
 # ``message``/``hint``. Plain language only: no command names, ids, field names
@@ -102,6 +103,7 @@ ERROR_SUMMARIES: dict[str, str] = {
     "download_failed": "A download didn't complete.",
     "dry_run_unsupported": "That command can't be previewed, so it was not run.",
     "duplicate_input_key": _S_BAD_INPUT,
+    "empties_view": "No row matches, so this step would leave the view empty.",
     "empty_search_query": "The search was empty.",
     "export_already_exists": "An export with that name already exists.",
     "incomplete_environment_auth": _S_SIGN_IN,

{mammoth_cli-2.2.45 → mammoth_cli-2.2.47}/mammoth_cli/runtime/invocation.py

@@ -62,6 +62,7 @@ class Invocation:
     yes: bool = False
     confirm: str | None = None
     dry_run: bool = False
+    allow_empty: bool = False
     input_file: str | None = None
     input_format: str | None = None
     positionals: dict[str, Any] = field(default_factory=dict)

mammoth_cli-2.2.47/mammoth_cli/runtime/locked_files.py

@@ -0,0 +1,70 @@
+"""Password-protected files, stated wherever one appears in a result.
+
+A file record carries ``password_protected: true``, but the flag alone does not
+say what to do. :func:`with_locked_files` adds a ``locked_files`` entry per such
+file that says the file's password unlocks it and names the command that takes
+the password. It runs on every result and never makes a request.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+#: Nesting to search: a result, a listing inside it, a record in the listing.
+_MAX_DEPTH = 3
+#: Where a file record keeps the flag: a file listing, a browse search record.
+_INFO_KEYS = ("additional_info", "additional_data")
+_BROWSE_FILE_TYPE = "file_object"
+
+
+def with_locked_files(data: Any) -> Any:
+    """Return ``data`` with a ``locked_files`` list, or unchanged when no file is locked."""
+    # A file listing comes back as an SDK model; it is read as the output prints it.
+    plain = data.model_dump(mode="python") if hasattr(data, "model_dump") else data
+    if not isinstance(plain, dict):
+        return data
+    locked = [_entry(record) for record in _locked_records(plain, 0)]
+    if not locked:
+        return data
+    return {**plain, "locked_files": locked}
+
+
+def _locked_records(value: Any, depth: int) -> Iterator[dict[str, Any]]:
+    if depth > _MAX_DEPTH:
+        return
+    if isinstance(value, dict):
+        if _is_locked(value) and _file_id(value) is not None:
+            yield value
+        for child in value.values():
+            yield from _locked_records(child, depth + 1)
+    elif isinstance(value, list):
+        for child in value:
+            yield from _locked_records(child, depth + 1)
+
+
+def _is_locked(record: dict[str, Any]) -> bool:
+    return any(
+        isinstance(info := record.get(key), dict) and info.get("password_protected") is True
+        for key in _INFO_KEYS
+    )
+
+
+def _file_id(record: dict[str, Any]) -> int | None:
+    """A file record names itself ``id``; a browse record names the file ``object_id``."""
+    key = "object_id" if record.get("resource_type") == _BROWSE_FILE_TYPE else "id"
+    value = record.get(key)
+    return value if isinstance(value, int) else None
+
+
+def _entry(record: dict[str, Any]) -> dict[str, Any]:
+    file_id = _file_id(record)
+    return {
+        "file_id": file_id,
+        "name": record.get("name"),
+        "detail": "This file is password-protected; its data cannot be read until it is unlocked.",
+        "fix": (
+            "Ask the user for the file's password, not for an unlocked copy, then run "
+            f"mammoth file set-password {file_id} with the password in --input."
+        ),
+    }

{mammoth_cli-2.2.45 → mammoth_cli-2.2.47}/mammoth_cli/runtime/state.py

@@ -18,6 +18,7 @@ See ``CONTRACT-write-state.md`` (D-077) for the manifest shape this reads.
 from __future__ import annotations
 
 import json
+import time
 from typing import Any
 
 from mammoth_cli.errors.envelope import CliError
@@ -45,6 +46,19 @@ _VIEW_LIST_COMMAND = "view.list"
 #: ``verify.state`` of a write that was accepted but has not finished.
 _UNFINISHED_VERIFY_STATE = "processing"
 
+_VIEW_TASK_LIST_COMMAND = "view.task.list"
+
+#: A write answered ``status: staged`` (auto-run off) put its step in a draft.
+_STAGED_STATUS = "staged"
+_STAGED_DETAIL = (
+    "Staged in the draft, not run: the live view is unchanged until 'view draft submit'."
+)
+
+#: The backend's answer to a data read of a step that has not produced data yet.
+_STEP_NOT_RUN_YET = "no data for pipeline step"
+_DATA_READ_ATTEMPTS = 6
+_DATA_READ_RETRY_S = 2.0
+
 
 def with_state(invocation: Invocation, data: Any) -> Any:
     """Return ``data`` with a ``state`` read-back block added, per the manifest.
@@ -60,7 +74,15 @@ def with_state(invocation: Invocation, data: Any) -> Any:
     if not isinstance(readback, dict):
         return data
     unfinished = _unfinished_state(data)
-    state = unfinished or _enforce_cap(_build_state(invocation, data, readback))
+    if (
+        unfinished is None
+        and data.get("status") == _STAGED_STATUS
+        and readback.get("kind") == "data"
+    ):
+        built = _staged_state(invocation, data, readback)
+    else:
+        built = unfinished or _build_state(invocation, data, readback)
+    state = _enforce_cap(built)
     return {**_unverified_if_unreadable(data, state), "state": state}
 
 
@@ -321,7 +343,7 @@ def _data_state(resolved_ids: dict[str, Any], base: Invocation) -> dict[str, Any
     if dataset_id is not None:
         view_ids["dataset_id"] = dataset_id
     info = _call_read(_VIEW_GET_COMMAND, view_ids, base)
-    page = _call_read(_VIEW_DATA_COMMAND, view_ids, base)
+    page = _read_data_once_run(view_ids, base)
     rows = page.get("data") if isinstance(page, dict) else None
     sample = [_trim_row(row) for row in (rows or [])[:_SAMPLE_ROW_CAP]]
     state: dict[str, Any] = {
@@ -338,6 +360,64 @@ def _data_state(resolved_ids: dict[str, Any], base: Invocation) -> dict[str, Any
     return state
 
 
+def _read_data_once_run(view_ids: dict[str, Any], base: Invocation) -> Any:
+    """The view's data, waiting (bounded) for a step that has not run yet.
+
+    Read right after a write, the new step may have no data yet; the read
+    fails with "no data for pipeline step N ... yet" though the step runs a
+    moment later (FB-18, FB-22). Any other failure is raised at once.
+    """
+    for attempt in range(_DATA_READ_ATTEMPTS):
+        try:
+            return _call_read(_VIEW_DATA_COMMAND, view_ids, base)
+        except CliError as exc:
+            if _STEP_NOT_RUN_YET not in exc.message or attempt == _DATA_READ_ATTEMPTS - 1:
+                raise
+            time.sleep(_DATA_READ_RETRY_S)
+    raise AssertionError("unreachable")
+
+
+def _staged_state(
+    invocation: Invocation, data: dict[str, Any], readback: dict[str, Any]
+) -> dict[str, Any]:
+    """A draft write's read-back: the view's steps, and that the staged ones have not run.
+
+    A staged step never ran, so its data cannot be read (FB-20: the agent got
+    ``unreadable`` and polled four read commands to learn what it had staged).
+    """
+    ids_spec: dict[str, Any] = readback.get("ids") or {}
+    resolved = {name: _resolve_source(str(src), data, invocation) for name, src in ids_spec.items()}
+    view_id = _as_int(resolved.get("view_id") or resolved.get("dataview_id"))
+    read_by = f"{_VIEW_TASK_LIST_COMMAND} {view_id}"
+    try:
+        if view_id is None:
+            raise ValueError("a staged write's read-back needs the view id")
+        info = _call_read(_VIEW_GET_COMMAND, {"view_id": view_id}, invocation)
+        tasks = _call_read(_VIEW_TASK_LIST_COMMAND, {"dataview_id": view_id}, invocation)
+    except Exception as exc:  # noqa: BLE001 -- a read failure must surface, never crash the write
+        reason = exc.message if isinstance(exc, CliError) else str(exc)
+        return {"kind": "unreadable", "read_by": read_by, "reason": reason or type(exc).__name__}
+    return {
+        "kind": "staged",
+        "read_by": read_by,
+        "detail": _STAGED_DETAIL,
+        "live_row_count": info.get("row_count") if isinstance(info, dict) else None,
+        "steps": [_step_summary(task) for task in _tasks_of(tasks)],
+    }
+
+
+def _tasks_of(read_data: Any) -> list[dict[str, Any]]:
+    tasks = read_data.get("tasks") if isinstance(read_data, dict) else read_data
+    return [task for task in tasks or [] if isinstance(task, dict)]
+
+
+def _step_summary(task: dict[str, Any]) -> dict[str, Any]:
+    params = task.get("params")
+    if not isinstance(params, dict):
+        params = {}
+    return {"id": task.get("id"), "task": params.get("TASK_KEY"), "status": task.get("status")}
+
+
 def changed_columns(document: Any) -> list[str]:
     """Names of the columns a view edit's input says it wrote."""
     if not isinstance(document, dict):

{mammoth_cli-2.2.45 → mammoth_cli-2.2.47}/mammoth_cli/services/mapping.py

@@ -233,6 +233,29 @@ def running_handle(error: CliError, command_id: str) -> dict[str, Any] | None:
     }
 
 
+def _retry_hint(retry_after: str | None) -> str:
+    """How to retry a read that failed for a transient reason."""
+    if retry_after:
+        return f"Retry the read after {retry_after} s, as the server's Retry-After asks."
+    return "Retry the read once; it changed nothing. If it fails again, tell the user."
+
+
+#: A backend error ``name`` that refuses an action for lack of permission
+#: (``DASHBOARD_CREATE_NOT_ALLOWED``) arrives as a 400, not a 403.
+_NOT_ALLOWED_SUFFIX = "_NOT_ALLOWED"
+
+
+def _not_allowed_reason(body: Any, status: int | None) -> str | None:
+    """The backend's own reason when a 4xx refuses an action as not allowed."""
+    if status is None or not 400 <= status < 500 or not isinstance(body, dict):
+        return None
+    name = body.get("name")
+    message = body.get("message")
+    if not isinstance(name, str) or not name.endswith(_NOT_ALLOWED_SUFFIX):
+        return None
+    return message if isinstance(message, str) and message else name
+
+
 CODE_CLI_KEYS_NOT_ALLOWED = "cli_keys_not_allowed"
 CODE_CLI_KEYS_NEED_BROWSER_SIGN_IN = "cli_keys_need_browser_sign_in"
 _TOKEN_REFUSED_NAME = "INVALID_TOKEN_FOR_CLIENT_APPS"  # noqa: S105 - an error name
@@ -521,6 +544,20 @@ def map_sdk_exception(
                 request_id=request_id,
                 authorization_required=True,
             )
+        not_allowed = _not_allowed_reason(exc.response_body, status)
+        if not_allowed is not None:
+            return CliError(
+                code=CODE_AUTHORIZATION_REQUIRED,
+                message=not_allowed,
+                exit_status=EXIT_AUTH,
+                hint=(
+                    "This user lacks the permission for this action here. Do not retry or "
+                    "work around it: tell the user what is blocked and who can grant it."
+                ),
+                details=details,
+                request_id=request_id,
+                authorization_required=True,
+            )
         if status == 413:
             # The ingress in front of the API caps a request body (measured
             # on release 2026-09-19: a 16 MB upload passes, 60 MB does not);
@@ -553,7 +590,7 @@ def map_sdk_exception(
                 code=CODE_RETRYABLE,
                 message="Mammoth is temporarily unavailable or the request timed out.",
                 exit_status=EXIT_RETRYABLE,
-                hint="Retry after the indicated delay, honoring Retry-After when present.",
+                hint=_retry_hint(exc.retry_after),
                 details=details,
                 request_id=request_id,
                 retryable=True,

{mammoth_cli-2.2.45 → mammoth_cli-2.2.47}/mammoth_cli/services/sdk_service.py

@@ -20,6 +20,7 @@ import os
 import re
 import threading
 from collections.abc import Callable, Sequence
+from concurrent.futures import ThreadPoolExecutor
 from types import TracebackType
 from typing import Any, NoReturn
 
@@ -74,6 +75,15 @@ def _unrecognized_expression_token(message: str, expression: Any) -> str:
     return token or expression
 
 
+def _loop_running_here() -> bool:
+    """Whether the calling thread is already inside a running event loop."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return False
+    return True
+
+
 AGENT_RUN_ENV = "MAMMOTH_AGENT_RUN"
 AGENT_RUN_HEADER = "X-Mammoth-Agent-Run"
 
@@ -211,6 +221,15 @@ class SdkMammothService:
         """
         if not inspect.isawaitable(work):
             return work
+        if _loop_running_here():
+            # An async caller (the agent eval harness) already runs a loop on this
+            # thread, and a thread runs one loop at a time: run ours on a helper.
+            with ThreadPoolExecutor(max_workers=1) as helper:
+                return helper.submit(self._run_on_own_loop, work).result()
+        return self._run_on_own_loop(work)
+
+    def _run_on_own_loop(self, work: Any) -> Any:
+        """Run ``work`` on the service's loop; threads take turns."""
         with self._loop_lock:
             return self._loop.run_until_complete(work)