pushmetrics-cli 0.1.0__py3-none-any.whl

pm/client/base.py

@@ -0,0 +1,229 @@
+"""Common API client primitives.
+
+`CrudClient[T]` is the generic base for resources that follow FAB's standard
+shape: list at `/<resource>/`, single at `/<resource>/<uid>`, with `POST`
+create, `PUT` update, `DELETE` remove. Subclasses set `base_path` + `model`
+and inherit list/get/create/update/delete. Resources with custom ops add
+methods on top; resources without all 5 verbs simply don't expose the
+unsupported ones at the commands layer (the methods still exist on the client
+but will get a 405 from the backend if called).
+
+`SharingMixin` provides the cross-resource `share_with_user/group/workspace`
++ `sharing_settings` pattern. Documented and stubbed here; not applied to any
+client until Phase 6.3.
+"""
+from __future__ import annotations
+
+from typing import Any, ClassVar, Dict, Generic, List, Optional, Type, TypeVar
+
+import requests
+from pydantic import BaseModel
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def api_error_prefix(method: str, path: str) -> str:
+    """``API <METHOD> <url> failed`` for an HTTP response; ``Request failed``
+    for an error the client raises itself (no request to name). Both keep
+    the ``failed: <status>`` text the agent harness scrapes."""
+    return f"API {method} {path} failed" if (method or path) else "Request failed"
+
+
+class PMApiError(RuntimeError):
+    """Raised on non-2xx API responses (other than 401, which raises NotAuthenticatedError)."""
+
+    def __init__(self, status: int, body: str, *, method: str = "", path: str = ""):
+        self.status = status
+        self.body = body
+        self.method = method
+        self.path = path
+        super().__init__(f"{api_error_prefix(method, path)}: {status} {body}")
+
+
+def raise_for_status(resp: requests.Response) -> None:
+    if resp.status_code >= 400:
+        # Redact PAT/Bearer-shaped strings from the error body before it is
+        # embedded in the exception: PMApiError messages propagate into CLI
+        # stderr and from there into agent transcripts (via the prefect
+        # cli_adapter), and a proxy/debug error page can echo the request's
+        # Authorization header.
+        from pm.auth.token import redact_secrets
+
+        raise PMApiError(
+            resp.status_code,
+            redact_secrets(resp.text or ""),
+            method=(resp.request.method or "") if resp.request else "",
+            path=resp.url,
+        )
+
+
+def _unwrap_result(body: Any, default: Any = None) -> Any:
+    """FAB endpoints typically return `{"result": ...}`; tolerate bare shapes too."""
+    if isinstance(body, dict) and "result" in body:
+        return body["result"]
+    return body if body is not None else default
+
+
+class CrudClient(Generic[T]):
+    """Generic FAB-CRUD client.
+
+    Subclasses must set `base_path` (no trailing slash; e.g. `/api/v1/folder`)
+    and `model` (a Pydantic model). They then inherit:
+
+    - `list(params=None) -> List[T]`
+    - `get(uid) -> T`
+    - `create(data) -> T`
+    - `update(uid, data) -> T`
+    - `delete(uid) -> None`
+    """
+
+    base_path: ClassVar[str] = ""
+    model: ClassVar[Type[BaseModel]]
+
+    def __init__(self, session):
+        self.session = session
+
+    def list(self, params: Optional[Dict[str, Any]] = None) -> List[T]:
+        resp = self.session.get(f"{self.base_path}/", params=params)
+        raise_for_status(resp)
+        raw = _unwrap_result(resp.json(), default=[])
+        if not isinstance(raw, list):
+            raw = [raw]
+        return [self.model.model_validate(item) for item in raw]
+
+    def list_all(self, *, page_size: int = 100, limit: Optional[int] = None) -> List[T]:
+        """Fetch EVERY row by walking FAB's pages until exhausted.
+
+        A plain ``list()`` returns only the first page — FAB caps
+        ``page_size`` at ``FAB_API_MAX_PAGE_SIZE`` (default 100) and
+        silently clamps the ``-1`` "uncap" unless the endpoint also sets
+        ``max_page_size = -1``. So a caller that wants the complete set
+        (and, critically, the true TOTAL) can't rely on one request. This
+        pages by index, using the response's top-level ``count`` to know
+        when to stop, and returns every row.
+
+        ``count`` is the PRIMARY stop condition: keep paging until we've
+        collected ``count`` rows. The short-page heuristic is only a
+        fallback for when ``count`` is absent — it must NOT stop the walk
+        while ``count`` says more rows exist, because FAB clamps an
+        over-large ``page_size`` to ``max_page_size`` and returns a page
+        SHORTER than requested on the very first request (codex/Copilot
+        review PR #5791). The page STRIDE is likewise taken from the
+        first response's actual length, not the requested ``page_size``,
+        so page indices stay aligned to what the server honored.
+
+        Used by ``pm report list`` so the agent doesn't present a single
+        capped page as "you have N reports in your workspace" (support
+        session GYmXdRekqy, 2026-07-19: 22 shown, workspace had more).
+
+        ``limit`` stops the walk once that many rows are collected, so
+        ``pm report list --limit 5`` makes one request, not one per page.
+        Without it every page is fetched, as above.
+        """
+        if limit is not None:
+            page_size = min(page_size, limit)
+        out: List[T] = []
+        page = 0
+        stride: Optional[int] = None  # server-honored page length
+        while True:
+            ps = stride or page_size
+            q = f"(page:{page},page_size:{ps})"
+            resp = self.session.get(f"{self.base_path}/", params={"q": q})
+            raise_for_status(resp)
+            body = resp.json()
+            raw = _unwrap_result(body, default=[])
+            if not isinstance(raw, list):
+                raw = [raw] if raw else []
+            out.extend(self.model.model_validate(item) for item in raw)
+            if limit is not None and len(out) >= limit:
+                return out[:limit]
+            count = body.get("count") if isinstance(body, dict) else None
+            # Empty page always terminates (nothing more to fetch).
+            if not raw:
+                break
+            # Primary: ``count`` is authoritative. Keep paging until we
+            # have every row, regardless of how short FAB made the page
+            # (an over-large page_size gets clamped, so page 0 can be
+            # shorter than requested while more rows still exist).
+            if isinstance(count, int):
+                if len(out) >= count:
+                    break
+                # Lock the stride to the server-honored first-page length
+                # so page indices align with what FAB returned.
+                if stride is None:
+                    stride = len(raw)
+                page += 1
+                continue
+            # Fallback (no ``count`` field): treat a page shorter than the
+            # stride as the end. On the FIRST page the stride is the
+            # requested ``page_size`` — a short first page then means "no
+            # more rows". On later pages it's the honored length.
+            prev_stride = stride if stride is not None else page_size
+            if len(raw) < prev_stride:
+                break
+            if stride is None:
+                stride = len(raw)
+            page += 1
+        return out
+
+    def get(self, uid: str) -> T:
+        resp = self.session.get(f"{self.base_path}/{uid}")
+        raise_for_status(resp)
+        return self.model.model_validate(_unwrap_result(resp.json()))
+
+    def create(self, data: Dict[str, Any]) -> T:
+        resp = self.session.post(f"{self.base_path}/", json=data)
+        raise_for_status(resp)
+        return self.model.model_validate(_unwrap_result(resp.json()))
+
+    def update(self, uid: str, data: Dict[str, Any]) -> T:
+        resp = self.session.put(f"{self.base_path}/{uid}", json=data)
+        raise_for_status(resp)
+        return self.model.model_validate(_unwrap_result(resp.json()))
+
+    def delete(self, uid: str) -> None:
+        resp = self.session.delete(f"{self.base_path}/{uid}")
+        raise_for_status(resp)
+
+
+class SharingMixin:
+    """Cross-resource sharing pattern (Phase 6.3 — not yet applied).
+
+    Reports, databases, agents, and integrations all expose:
+
+    - `GET  /<base>/<uid>/sharing_settings`
+    - `POST /<base>/<uid>/share_with_user`      { user_uid, permission }
+    - `POST /<base>/<uid>/share_with_group`     { group_uid, permission }
+    - `POST /<base>/<uid>/share_with_workspace` { permission }
+    """
+
+    base_path: ClassVar[str]
+
+    def sharing_settings(self, uid: str) -> Dict[str, Any]:
+        resp = self.session.get(f"{self.base_path}/{uid}/sharing_settings")
+        raise_for_status(resp)
+        return resp.json()
+
+    def share_with_user(self, uid: str, user_uid: str, permission: str) -> Dict[str, Any]:
+        resp = self.session.post(
+            f"{self.base_path}/{uid}/share_with_user",
+            json={"user_uid": user_uid, "permission": permission},
+        )
+        raise_for_status(resp)
+        return resp.json()
+
+    def share_with_group(self, uid: str, group_uid: str, permission: str) -> Dict[str, Any]:
+        resp = self.session.post(
+            f"{self.base_path}/{uid}/share_with_group",
+            json={"group_uid": group_uid, "permission": permission},
+        )
+        raise_for_status(resp)
+        return resp.json()
+
+    def share_with_workspace(self, uid: str, permission: str) -> Dict[str, Any]:
+        resp = self.session.post(
+            f"{self.base_path}/{uid}/share_with_workspace",
+            json={"permission": permission},
+        )
+        raise_for_status(resp)
+        return resp.json()

pm/client/blocks.py

@@ -0,0 +1,461 @@
+"""Block endpoints — CRUD + execute.
+
+Used by both the generic `pm block` plumbing group and every domain group's
+factory-generated commands (`pm sql create`, `pm email send`, etc.). The
+domain groups bind `block_type` ahead of time; `pm block` accepts it per call.
+
+`execute_existing` and `execute_against_scratch` are deliberately split
+so the call site is unambiguous — no single `run()` method that switches on
+the presence of a uid argument. The scratch-reuse path mirrors the legacy
+``run_sql`` / ``send_email`` agent tools (``prefect/queryme/agent/tools/
+block_tools.py``) — no new block is persisted; an assigned scratch block
+of the requested type is reused with a transient ``content_json`` override.
+
+HTTP-only — no Superset app-context imports (codex F2 rule). This module
+runs inside the CLI process and must stay importable without the backend
+Flask app being on the path.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from pm.client.base import (
+    CrudClient,
+    _unwrap_result,
+    raise_for_status,
+)
+from pm.models.blocks import Block
+
+
+def _ensure_content_json_string(content_json: Any) -> str:
+    """Backend stores `content_json` as a string column. Accept dict-or-string
+    on the way in so callers don't have to remember to dump."""
+    if content_json is None:
+        return ""
+    if isinstance(content_json, str):
+        return content_json
+    return json.dumps(content_json)
+
+
+def _rison_type_filter(block_type: str) -> str:
+    """Build the Rison `q=` filter that FAB list endpoints expect for an
+    equality filter on `type`. Mirrors the runs client's q-encoding."""
+    return f"(filters:!((col:type,opr:eq,value:{block_type})))"
+
+
+# Per-type content_json field that selects WHICH assigned scratch block
+# to reuse for `pm <type> run/send --stdin`. Mirrors the legacy
+# `_make_db_lookup` (sql) / `_make_integration_lookup` (email/slack/...)
+# split at ``prefect/queryme/agent/tools/block_tools.py``. Types absent
+# from the map have no routing discriminator — the first assigned scratch
+# block of the type wins.
+SCRATCH_ROUTING_FIELD: Dict[str, str] = {
+    "sql": "database_id",
+    "email": "integration_id",
+    "slack": "integration_id",
+    "sftp": "integration_id",
+    "tableau": "integration_id",
+    "webhook": "integration_id",
+    "google_slides": "integration_id",
+}
+
+
+def _parse_block_content_json(value: Any) -> Dict[str, Any]:
+    """Return a parsed dict from a block's `content_json` field.
+
+    Backend stores it as a string; `Block.content_json` may be either
+    str (fresh from the API) or dict (already parsed by a caller). Empty
+    or malformed values return ``{}`` so callers never see exceptions
+    while building a lookup.
+    """
+    if value is None:
+        return {}
+    if isinstance(value, dict):
+        return value
+    if not isinstance(value, str):
+        return {}
+    try:
+        parsed = json.loads(value)
+    except (json.JSONDecodeError, ValueError):
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+class BlocksClient(CrudClient[Block]):
+    """One client for all block CRUD + execute ops.
+
+    The execute verbs (`run`, `send`) hit the same `POST /api/v1/block/<uid>/run`
+    endpoint — the `verb` argument is preserved so callers (factory-generated
+    Click commands) can attach the correct canonical_action to traces. The
+    backend doesn't differentiate; the agent telemetry does.
+    """
+
+    base_path = "/api/v1/block"
+    model = Block
+
+    # ── CRUD ───────────────────────────────────────────────────────────
+
+    def list(
+        self,
+        *,
+        type: Optional[str] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> List[Block]:
+        """List blocks, optionally filtered by type.
+
+        `type` uses FAB's Rison `q` filter so it matches the backend's
+        `search_filters = {"type": [FilterEqual], ...}` registration. Pass
+        raw `params` for ad-hoc cases (e.g. pagination); when both are
+        given, `params` wins and `type` is ignored — callers wanting both
+        should build the full Rison `q` themselves.
+        """
+        if params is None and type is not None:
+            params = {"q": _rison_type_filter(type)}
+        return super().list(params=params)
+
+    def create(
+        self,
+        *,
+        type: str,
+        name: str,
+        content_json: Any,
+        verbose_name: Optional[str] = None,
+    ) -> Block:
+        """Create a new block. Returns the persisted Block (incl. uid).
+
+        Does NOT execute. The chart (`plotly`) carve-out documented in
+        plan §3.0 — auto-render PNG on creation — lives in the executor,
+        not here; from this client's perspective every type is "create
+        only" at this verb.
+        """
+        body: Dict[str, Any] = {
+            "type": type,
+            "name": name,
+            "content_json": _ensure_content_json_string(content_json),
+        }
+        if verbose_name is not None:
+            body["verbose_name"] = verbose_name
+        return super().create(body)
+
+    def update(
+        self,
+        uid: str,
+        content_json: Any = None,
+        *,
+        name: Optional[str] = None,
+        verbose_name: Optional[str] = None,
+    ) -> Block:
+        """Update editable fields on an existing block. Only sends the
+        fields that were provided — FAB's edit_columns lets us PATCH-style
+        update without resending the rest."""
+        body: Dict[str, Any] = {}
+        if content_json is not None:
+            body["content_json"] = _ensure_content_json_string(content_json)
+        if name is not None:
+            body["name"] = name
+        if verbose_name is not None:
+            body["verbose_name"] = verbose_name
+        return super().update(uid, body)
+
+    # ── Execute (split — codex R4 #5) ──────────────────────────────────
+
+    def execute_existing(
+        self,
+        uid: str,
+        *,
+        verb: str,
+        block_properties: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Run an existing block by uid.
+
+        `verb` is `"run"` or `"send"` — preserved by the caller for
+        canonical_action telemetry but not sent to the backend (the
+        existing endpoint doesn't differentiate). `block_properties` is
+        merged into the block in-memory before execution (matches today's
+        manual-run UI behaviour). Returns `{"run_id": int, "block_uid": str,
+        "verb": str}` so trace + replay-guard keying works at the call site.
+        """
+        if verb not in ("run", "send"):
+            raise ValueError(f"execute_existing: verb must be 'run' or 'send', got {verb!r}")
+        resp = self.session.post(
+            f"{self.base_path}/{uid}/run",
+            json=block_properties or {},
+        )
+        raise_for_status(resp)
+        body = _unwrap_result(resp.json(), default={}) or {}
+        # The backend `/run` handler returns {"run_id": int}; layer the
+        # caller's context onto it so command-level telemetry doesn't
+        # have to thread these separately.
+        return {
+            "run_id": body.get("run_id"),
+            "block_uid": uid,
+            "verb": verb,
+            **{k: v for k, v in body.items() if k != "run_id"},
+        }
+
+    # ── Slides ────────────────────────────────────────────────────────
+
+    def parse_slides_template(self, uid: str) -> Dict[str, Any]:
+        """Parse a Google Slides master deck into template partials.
+
+        Hits ``POST /api/v1/block/<uid>/parse_slides_template``. The backend
+        pulls the source_file_id + integration_id off the block's
+        content_json, calls Google's Slides API, and persists the parsed
+        ``template_definition`` + a sample ``composition_json`` back onto
+        the block — then returns them in the response.
+
+        Use as the first step after creating a slides block from a master
+        deck: parse-template populates the block with the available
+        slide partials + variables; subsequent runs use the discovered
+        ``composition_json`` to render presentations.
+        """
+        resp = self.session.post(f"{self.base_path}/{uid}/parse_slides_template")
+        raise_for_status(resp)
+        body = resp.json() if resp.text else {}
+        return body if isinstance(body, dict) else {"result": body}
+
+    # ── Metrics view ──────────────────────────────────────────────────
+
+    def metrics_query(
+        self,
+        metrics_view_uid: str,
+        *,
+        measures: List[str],
+        dimensions: Optional[List[str]] = None,
+        dimension_grains: Optional[Dict[str, Any]] = None,
+        filters: Optional[List[Dict[str, Any]]] = None,
+        time_range: Optional[str] = None,
+        time_grain: Optional[str] = None,
+        order_by: Optional[List[Dict[str, Any]]] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        no_cache: bool = False,
+        parameters: Optional[Dict[str, Any]] = None,
+        extra: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Execute a semantic-layer query against a metrics view.
+
+        Hits ``POST /api/v1/block/metrics_query`` (NOTE: no uid in the URL
+        path — the metrics_view_uid lives in the body). The backend
+        compiles dialect-specific SQL via MetricsQueryEngine and runs it
+        against the underlying database; results are cached for ~5 min.
+
+        Returns the raw backend payload — ``{result?, sql, columns, data,
+        ...}``. Compilation errors come back as ``PMApiError(400)``;
+        execution errors as ``PMApiError(422)`` with the failing SQL
+        attached (the backend redacts DB URLs from the message).
+
+        ``extra`` is an escape hatch — any keys passed there are merged
+        into the request body verbatim. Used by ``pm metrics-view query
+        --stdin`` to forward fields not surfaced as kwargs (e.g. future
+        backend additions) without a client-side rev.
+        """
+        body: Dict[str, Any] = {
+            "metrics_view_uid": metrics_view_uid,
+            "measures": list(measures),
+        }
+        if dimensions:
+            body["dimensions"] = list(dimensions)
+        if dimension_grains:
+            body["dimension_grains"] = dimension_grains
+        if filters:
+            body["filters"] = list(filters)
+        if time_range:
+            body["time_range"] = time_range
+        if time_grain:
+            body["time_grain"] = time_grain
+        if order_by:
+            body["order_by"] = list(order_by)
+        if limit is not None:
+            body["limit"] = int(limit)
+        if offset is not None:
+            body["offset"] = int(offset)
+        if no_cache:
+            body["no_cache"] = True
+        if parameters:
+            body["parameters"] = parameters
+        if extra:
+            # extra wins — caller is explicitly overriding via --stdin
+            body.update(extra)
+
+        resp = self.session.post(f"{self.base_path}/metrics_query", json=body)
+        raise_for_status(resp)
+        payload = resp.json()
+        return payload if isinstance(payload, dict) else {"result": payload}
+
+    def metrics_schema(self, uid: str) -> Dict[str, Any]:
+        """Return the measures/dimensions/parameters available on a
+        metrics view. Hits ``GET /api/v1/block/<uid>/metrics_schema``.
+
+        Used as the "what can I query?" companion to ``metrics_query`` —
+        agents typically fetch the schema before constructing a query so
+        they know which measure/dimension names are valid.
+        """
+        resp = self.session.get(f"{self.base_path}/{uid}/metrics_schema")
+        raise_for_status(resp)
+        body = resp.json()
+        return _unwrap_result(body, default={}) or {}
+
+    # ── Results ────────────────────────────────────────────────────────
+
+    def results(
+        self,
+        uid: str,
+        *,
+        result_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Fetch past execution result(s) for a block.
+
+        - ``result_id=None`` → ``GET /api/v1/block/<uid>/results/`` returns
+          a list of recent results (backend caps at ~10 by default).
+        - ``result_id="last_result"`` → backend special-cases this: returns
+          ``{"result": <latest>, "last_results": [<rest>]}``.
+        - ``result_id=<specific id>`` → ``{"result": <that one>}``.
+
+        The shape varies between modes — the caller is expected to know
+        which key it asked for. Returns the raw dict from the backend.
+        """
+        path = f"{self.base_path}/{uid}/results/"
+        if result_id:
+            path = f"{self.base_path}/{uid}/results/{result_id}"
+        resp = self.session.get(path)
+        raise_for_status(resp)
+        body = resp.json()
+        # Backend's `response(200, **sanitized_results)` flattens the dict
+        # at the top level. Hand the whole thing back.
+        return body if isinstance(body, dict) else {"result": body}
+
+    def execute_against_scratch(
+        self,
+        *,
+        block_type: str,
+        content_json: Dict[str, Any],
+        verb: str,
+    ) -> Dict[str, Any]:
+        """Run `content_json` as a transient override against an existing
+        assigned scratch block of `block_type`. Mirrors the legacy
+        ``run_sql`` / ``send_email`` agent tools — no new block is
+        persisted; the scratch's stored content is merged with the body,
+        the run is executed with the merged content, and the scratch's
+        DB row is restored on the in-memory object by the backend's
+        ``/<uid>/run`` handler (see ``superset/pushmetrics/views/block/
+        api.py:1010-1027``).
+
+        Resolution:
+          - List the agent's assigned blocks of `block_type` (FAB applies
+            ``FilterAgentBlockScope`` so the list is already restricted to
+            blocks the agent owns).
+          - When the type has a routing field (``database_id`` for sql,
+            ``integration_id`` for email/slack/tableau/...) and the body
+            supplies a value for it, pick the scratch whose stored
+            content has the matching value; reject unknown values rather
+            than silently falling back (mirrors legacy ``_resolve_block``
+            in ``block_tools.py``).
+          - With no routing field or no value, use the first assigned
+            scratch block.
+
+        Safety: the scratch's routing field WINS in the merge. The body
+        can supply ``sql``/``body``/``message`` etc., but cannot escape
+        the agent's assigned database/integration by overriding
+        ``database_id`` / ``integration_id``. Same boundary the legacy
+        tool enforced.
+
+        Raises ``PMApiError`` when no assigned scratch matches.
+        """
+        # Local import — ``PMApiError`` lives in client.base and importing
+        # at module scope makes the cyclic shape harder to reason about
+        # for testing. Cheap to import per call.
+        from pm.client.base import PMApiError
+
+        body = content_json or {}
+        routing_field = SCRATCH_ROUTING_FIELD.get(block_type)
+        target_value = body.get(routing_field) if routing_field else None
+
+        assigned = self.list(type=block_type)
+        if not assigned:
+            raise PMApiError(
+                400,
+                f"No {block_type!r} blocks are assigned to this agent. "
+                f"Ask an admin to provision one to enable "
+                f"`pm {block_type} {verb} --stdin`.",
+                method="POST",
+                path=f"{self.base_path}/<scratch>/run",
+            )
+
+        # Parse every assigned block's content_json once up-front; reused
+        # for matching, error-message construction, and the final merge.
+        # Mirrors legacy ``_make_db_lookup`` / ``_make_integration_lookup``
+        # which built the lookup map in one pass.
+        parsed_assigned = [
+            (b, _parse_block_content_json(b.content_json)) for b in assigned
+        ]
+
+        scratch = None
+        scratch_stored: Dict[str, Any] = {}
+        # ``is not None`` (NOT a truthy check) so explicitly-supplied
+        # falsy routing values (``database_id: 0`` / ``""``) still trigger
+        # the routing branch — otherwise they'd silently fall back to
+        # the first scratch and the user gets the wrong database.
+        # Mirrors the comment on the available-values list below.
+        if target_value is not None:
+            for b, stored in parsed_assigned:
+                # ``stored.get(...)`` directly (no ``or ""`` shim) so
+                # stored value ``0`` can match request value ``0``.
+                stored_value = stored.get(routing_field)
+                if stored_value is not None and str(stored_value) == str(target_value):
+                    scratch = b
+                    scratch_stored = stored
+                    break
+            if scratch is None:
+                # Include falsy routing values (empty string, 0) in the
+                # available list — operators debugging a mismatch need to
+                # see what's actually configured, even if it's empty.
+                available = sorted({
+                    str(stored.get(routing_field))
+                    for _, stored in parsed_assigned
+                    if routing_field in stored
+                })
+                raise PMApiError(
+                    400,
+                    f"{routing_field}={target_value!r} is not in this "
+                    f"agent's allowed {block_type} scratch blocks. "
+                    f"Available {routing_field}: "
+                    f"{available or '(none with that field)'}.",
+                    method="POST",
+                    path=f"{self.base_path}/<scratch>/run",
+                )
+        else:
+            scratch, scratch_stored = parsed_assigned[0]
+
+        # Defensive — list() blocks always carry a uid in practice (FAB's
+        # schema makes it non-null), but ``Block.uid`` is typed
+        # ``Optional[str]`` and the contract isn't enforced client-side.
+        # Fail loudly rather than POST to /api/v1/block/None/run.
+        if not scratch.uid:
+            raise PMApiError(
+                500,
+                f"Assigned {block_type} scratch block returned without a "
+                f"uid; cannot execute.",
+                method="POST",
+                path=f"{self.base_path}/<scratch>/run",
+            )
+
+        # Build the override: scratch's stored content as the base, body
+        # overlays on top. Then pin the routing field UNCONDITIONALLY when
+        # the type has one — the scratch's value wins even if its stored
+        # content is missing the field (in which case the field is dropped
+        # from the merge so the agent cannot supply an arbitrary value).
+        # This is the boundary that prevents scope escape via the body.
+        merged: Dict[str, Any] = {**scratch_stored, **body}
+        if routing_field:
+            if routing_field in scratch_stored:
+                merged[routing_field] = scratch_stored[routing_field]
+            else:
+                merged.pop(routing_field, None)
+
+        return self.execute_existing(
+            scratch.uid,
+            verb=verb,
+            block_properties={"content_json": _ensure_content_json_string(merged)},
+        )