davinci-resolve-mcp 2.203.0 → 2.205.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "2.203.0",
+  "version": "2.205.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "2.203.0"
+VERSION = "2.205.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 353-tool granular server instead
 """
 
-VERSION = "2.203.0"
+VERSION = "2.205.0"
 
 import base64
 import os
@@ -60,6 +60,12 @@ from src.utils.page_lock import (
 )
 from src.utils.proc import safe_run
 from src.utils.readback import verify_by_readback, verification_stats as _verification_stats
+from src.utils import operation_result as _operation_result
+from src.utils.operation_result import (
+    build_operation_envelope as _build_operation_envelope,
+    get_envelope_mode as _get_envelope_mode,
+    set_envelope_mode as _set_envelope_mode,
+)
 from src.utils.render_ids import (
     render_codec_id_from_codecs as _render_codec_id_from_codecs,
     render_format_id_from_formats as _render_format_id_from_formats,
@@ -1472,6 +1478,15 @@ def _guarded_action_name(args, kwargs) -> str:
     return str(args[0]) if args else "?"
 
 
+def _guarded_params(args, kwargs) -> Optional[Dict[str, Any]]:
+    """This call's `params` dict, wherever in the signature it was passed."""
+    if isinstance(kwargs.get("params"), dict):
+        return kwargs["params"]
+    if len(args) > 1 and isinstance(args[1], dict):
+        return args[1]
+    return None
+
+
 def _guard_missing_params(fn):
     """Tool decorator: report a missing parameter instead of leaking a KeyError.
 
@@ -1489,21 +1504,35 @@ def _guard_missing_params(fn):
     - **The signature is not (action, params).** `media_analysis` also takes
       `ctx: Optional[Context]`, so the wrapper forwards `*args, **kwargs` rather
       than naming parameters it does not know about.
+
+    It is also where the operation envelope is attached, for the same reason it
+    is where the missing-parameter guard lives: this is the one seam every tool
+    return passes through. In the default `dual` mode the payload is untouched
+    and the envelope rides under `_operation` — see `src/utils/operation_result`
+    for why it is namespaced rather than flattened.
     """
+    tool_name = getattr(fn, "__name__", "tool")
+
     if inspect.iscoroutinefunction(fn):
         @functools.wraps(fn)
         async def wrapper(*args, **kwargs):
+            action = _guarded_action_name(args, kwargs)
             try:
-                return await fn(*args, **kwargs)
+                result = await fn(*args, **kwargs)
             except _MissingParam as exc:
-                return _missing_param_error(exc, _guarded_action_name(args, kwargs))
+                result = _missing_param_error(exc, action)
+            return _build_operation_envelope(
+                tool_name, action, _guarded_params(args, kwargs), result)
     else:
         @functools.wraps(fn)
         def wrapper(*args, **kwargs):
+            action = _guarded_action_name(args, kwargs)
             try:
-                return fn(*args, **kwargs)
+                result = fn(*args, **kwargs)
             except _MissingParam as exc:
-                return _missing_param_error(exc, _guarded_action_name(args, kwargs))
+                result = _missing_param_error(exc, action)
+            return _build_operation_envelope(
+                tool_name, action, _guarded_params(args, kwargs), result)
 
     wrapper.__wrapped_by_missing_param_guard__ = True
     return wrapper
@@ -5238,6 +5267,15 @@ def _timeline_ripple_insert_impl(proj, tl, p: Dict[str, Any], *, resolve=None) -
         "readback": {"after_counts": after_counts, "missing": missing},
         "gap_frames_by_track": gap_by_track,
         "warnings": warnings,
+        # Semantic delta for the operation envelope. Declared rather than
+        # inferred: this action deletes and re-appends the tail to move it, so
+        # a reader counting raw API calls would see a deletion that the edit
+        # did not make.
+        "_changes": {
+            "items_added": len(built_inserts),
+            "items_moved": len(tail_rows),
+            "items_deleted": 0,
+        },
     }
     if failures:
         result["failures"] = failures
@@ -10215,6 +10253,63 @@ def _read_json_strict(path: str) -> Dict[str, Any]:
     return payload if isinstance(payload, dict) else {}
 
 
+_SERVER_PREFS_ENV = "RESOLVE_MCP_SERVER_PREFS"
+
+
+def _server_preferences_path() -> str:
+    """Where server-general defaults live.
+
+    Separate from the media-analysis preferences file: these are settings about
+    how the server answers, not about how it analyses media, and mixing them
+    would make either file's name a lie.
+    """
+    override = os.environ.get(_SERVER_PREFS_ENV)
+    if override:
+        return os.path.realpath(os.path.abspath(os.path.expanduser(override)))
+    return os.path.join(project_dir, "logs", "server-preferences.json")
+
+
+def _read_server_preferences() -> Dict[str, Any]:
+    try:
+        return _read_json_strict(_server_preferences_path())
+    except ConfigParseError:
+        return {}
+
+
+def _write_server_preferences(preferences: Dict[str, Any]) -> None:
+    # Same atomic replace as the other preference stores: a crash mid-write must
+    # not truncate a file whose reader falls back to {}, since the next save
+    # would then persist that empty state over the user's settings.
+    path = _server_preferences_path()
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    tmp_path = f"{path}.tmp-{os.getpid()}-{threading.get_ident()}-{time.time_ns()}"
+    try:
+        with open(tmp_path, "w", encoding="utf-8") as handle:
+            json.dump(preferences, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+        os.replace(tmp_path, path)
+    finally:
+        try:
+            os.remove(tmp_path)
+        except OSError:
+            pass
+
+
+def _apply_persisted_envelope_mode() -> str:
+    """Restore the saved result_envelope default at startup.
+
+    An explicit RESOLVE_MCP_RESULT_ENVELOPE wins: a process-level override is a
+    deliberate act for this run, and a saved preference should not silently
+    outrank it.
+    """
+    if os.environ.get("RESOLVE_MCP_RESULT_ENVELOPE"):
+        return _get_envelope_mode()
+    saved = _read_server_preferences().get("result_envelope")
+    if isinstance(saved, str):
+        _set_envelope_mode(saved)
+    return _get_envelope_mode()
+
+
 def _read_media_analysis_preferences() -> Dict[str, Any]:
     path = _media_analysis_preferences_path()
     try:
@@ -15091,13 +15186,59 @@ def _setup_updates_defaults() -> Dict[str, Any]:
     }
 
 
+def _setup_general_defaults() -> Dict[str, Any]:
+    return {
+        "result_envelope": _get_envelope_mode(),
+        "options": {"result_envelope": list(_operation_result.MODES)},
+        "preferences_path": _server_preferences_path(),
+    }
+
+
 def _setup_defaults_snapshot() -> Dict[str, Any]:
     return {
+        "general": _setup_general_defaults(),
         "media_analysis": _setup_media_analysis_defaults(),
         "updates": _setup_updates_defaults(),
     }
 
 
+def _setup_set_general_defaults(general: Dict[str, Any], dry_run: bool) -> Dict[str, Any]:
+    """Persist server-general defaults. Currently just the result envelope."""
+    if not general:
+        return {"changed": False, "recognized": False}
+
+    mode = _first_param(
+        general, "result_envelope", "resultEnvelope", "envelope_mode", "envelopeMode",
+        default=None)
+    if mode is None:
+        return {"changed": False, "recognized": False}
+
+    cleaned = str(mode).strip().lower()
+    if cleaned not in _operation_result.MODES:
+        return _err(
+            f"result_envelope must be one of {', '.join(_operation_result.MODES)}",
+            code="INVALID_ENUM_VALUE", category="validation",
+            state={"result_envelope": mode})
+
+    if dry_run:
+        return {"changed": True, "recognized": True, "result_envelope": cleaned,
+                "current": _get_envelope_mode()}
+
+    # Persist before applying: a saved setting that does not survive a restart
+    # is a setting the caller was told they changed and did not.
+    try:
+        preferences = _read_json_strict(_server_preferences_path())
+    except ConfigParseError as exc:
+        return _err(
+            f"server preferences file is unreadable: {exc}",
+            code="CONFIG_UNREADABLE", category="state",
+            remediation=f"Repair or delete {_server_preferences_path()}, then retry.")
+    preferences["result_envelope"] = cleaned
+    _write_server_preferences(preferences)
+    _set_envelope_mode(cleaned)
+    return {"changed": True, "recognized": True, "result_envelope": _get_envelope_mode()}
+
+
 def _setup_set_media_analysis_defaults(media_defaults: Dict[str, Any], dry_run: bool) -> Dict[str, Any]:
     if not media_defaults:
         return {"changed": False, "recognized": False}
@@ -15691,6 +15832,17 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
                 },
                 "updates.check_interval_hours": {"values": "number >= 0.1", "storage": str(update_state_path(project_dir))},
                 "updates.snooze_hours": {"values": "number >= 0.1", "storage": str(update_state_path(project_dir))},
+                "general.result_envelope": {
+                    "description": (
+                        "Where the operation envelope goes. 'dual' (default) leaves the "
+                        "payload untouched and adds the envelope under '_operation'; "
+                        "'pure' returns only the envelope with the payload under 'result'; "
+                        "'legacy' adds nothing. Override per call with params={'envelope': ...}."
+                    ),
+                    "values": list(_operation_result.MODES),
+                    "current": _get_envelope_mode(),
+                    "storage": _server_preferences_path(),
+                },
             },
         }
 
@@ -15702,12 +15854,23 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
     if action in {"set_defaults", "set", "configure"}:
         defaults = p.get("defaults") if isinstance(p.get("defaults"), dict) else {}
         merged = {**defaults, **{k: v for k, v in p.items() if k != "defaults"}}
+        # media_analysis owns every unclaimed key, so anything another setter
+        # owns has to be named here or it lands in the wrong store.
+        _general_keys = {
+            "general", "result_envelope", "resultEnvelope",
+            "envelope_mode", "envelopeMode",
+        }
+        general_defaults = {
+            **_setup_nested(merged, "general"),
+            **{k: v for k, v in merged.items() if k in _general_keys and k != "general"},
+        }
         media_defaults = {
             **_setup_nested(merged, "media_analysis", "mediaAnalysis"),
             **{
                 key: value
                 for key, value in merged.items()
                 if key not in {"updates", "mcp_updates", "mcpUpdates", "dry_run", "dryRun"}
+                and key not in _general_keys
             },
             **({
                 "timed_markers_default": _first_param(
@@ -15758,19 +15921,25 @@ def setup(action: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any
             } if any(key in merged for key in ("snooze_hours", "snoozeHours", "update_snooze_hours", "updateSnoozeHours")) else {}),
         }
 
+        general_result = _setup_set_general_defaults(general_defaults, dry_run)
+        if general_result.get("error"):
+            return general_result
         media_result = _setup_set_media_analysis_defaults(media_defaults, dry_run)
         if media_result.get("error"):
             return media_result
         update_result = _setup_set_updates_defaults(update_defaults, dry_run)
         if update_result.get("error"):
             return update_result
-        recognized = bool(media_result.get("recognized")) or bool(update_result.get("recognized"))
+        recognized = (bool(general_result.get("recognized"))
+                      or bool(media_result.get("recognized"))
+                      or bool(update_result.get("recognized")))
         if not recognized:
             return _err("set_defaults did not receive a recognized default to set")
 
         return _ok(
             dry_run=dry_run,
             changes={
+                "general": general_result,
                 "media_analysis": media_result,
                 "updates": update_result,
             },
@@ -31310,6 +31479,9 @@ def _install_threaded_tool_dispatch(fastmcp) -> int:
 
 
 if __name__ == "__main__":
+    # Before any tool can answer: a saved result_envelope default has to be in
+    # force on the first call, not the second.
+    logger.info(f"Result envelope mode: {_apply_persisted_envelope_mode()}")
     start_background_update_check(VERSION, project_dir, logger, env=_setup_update_env())
     _install_threaded_tool_dispatch(mcp)
 

package/src/utils/operation_result.py

@@ -0,0 +1,377 @@
+"""A standard operation envelope over every compound tool's return value.
+
+Agents orchestrating multi-turn edits have to answer the same three questions
+after every call — did it actually happen, was it verified, and what changed —
+and today each tool answers them in its own vocabulary: ``readback.missing``,
+``succeeded``/``failed``, ``partial``, ``status: "confirmation_required"``.
+This module normalizes those into one shape so the answer is in the same place
+every time.
+
+Adapted from the design contributed in PR #181.
+
+**Where the envelope lives.** Its keys are namespaced under a single reserved
+key rather than merged into the top level, because half of them are already
+domain keys here and merging silently destroys them:
+
+    status       22 sites — a background job's "done", a transcription's
+                 "Transcribed", a confirm gate's "confirmation_required"
+    operation    20 sites
+    warnings     15 sites
+    result        8 sites
+    changes       2 sites
+
+Flattening the envelope over those rewrites `job_status`'s "done" to "success"
+(an agent polling a job then never sees it finish) and a confirm gate's
+"confirmation_required" to "blocked" — renaming the very signal the envelope
+exists to make unambiguous. So in the default ``dual`` mode the raw payload is
+passed through **untouched** and the envelope is added under ``_operation``,
+following the existing ``_versioning`` private-key convention. Nothing is
+shadowed, nothing is dropped, and there is still exactly one place to look.
+
+Modes:
+  ``dual``   (default) raw payload verbatim + ``_operation``.
+  ``pure``   only the envelope, domain payload nested under ``result``. Opt in
+             per call with ``params={"envelope": "pure"}``, per session with
+             ``setup(action="set_defaults", params={"result_envelope": "pure"})``,
+             or per process with ``RESOLVE_MCP_RESULT_ENVELOPE=pure``.
+  ``legacy`` no envelope at all.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import uuid
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger("resolve-mcp.operation-result")
+
+#: The reserved key the envelope hangs off in ``dual`` mode. Verified unused as
+#: a domain key across ``src/`` — ``test_envelope_key_stays_reserved`` keeps it
+#: that way, since the day a tool returns its own ``_operation`` is the day this
+#: mode starts destroying payloads the way the flat one did.
+ENVELOPE_KEY = "_operation"
+
+MODES = ("dual", "pure", "legacy")
+DEFAULT_MODE = "dual"
+
+
+def _clean_mode(mode: Any) -> Optional[str]:
+    if not isinstance(mode, str):
+        return None
+    candidate = mode.strip().lower()
+    return candidate if candidate in MODES else None
+
+
+_CURRENT_ENVELOPE_MODE = (
+    _clean_mode(os.environ.get("RESOLVE_MCP_RESULT_ENVELOPE")) or DEFAULT_MODE
+)
+
+
+def get_envelope_mode() -> str:
+    """The envelope mode applied when a call does not name one."""
+    return _CURRENT_ENVELOPE_MODE
+
+
+def set_envelope_mode(mode: str) -> str:
+    """Set the default envelope mode. Unknown values leave it unchanged."""
+    global _CURRENT_ENVELOPE_MODE
+    cleaned = _clean_mode(mode)
+    if cleaned:
+        _CURRENT_ENVELOPE_MODE = cleaned
+    return _CURRENT_ENVELOPE_MODE
+
+
+def new_execution_id() -> str:
+    """A compact id for correlating one tool call across logs and transcripts."""
+    return f"exec_{uuid.uuid4().hex[:12]}"
+
+
+# ─── Status ──────────────────────────────────────────────────────────────────
+
+def normalize_status(raw: Any) -> str:
+    """Reduce a result to 'success' | 'partial' | 'blocked' | 'failed'.
+
+    Deliberately narrow. Every rule below keys on a convention this repo
+    actually uses, checked against the call sites — a heuristic that guesses
+    from a plausible-looking key name produces exactly the confident-and-wrong
+    status the envelope is supposed to eliminate. The clearest example is
+    ``blocked``: it reads like a gate flag, but here it is a domain key holding
+    the *list of targets that could not be resolved* (`timeline` range delete,
+    `timeline_item_color.bulk_match_to_hero`), and a successful dry-run carries
+    a non-empty one. Keying on it would report a gate that never happened.
+    """
+    if not isinstance(raw, dict):
+        return "success" if bool(raw) else "failed"
+
+    # The confirm gate. `_issue_confirm_token` is the single producer of these
+    # responses and always stamps this exact status, so the check is exact
+    # rather than inferred.
+    if raw.get("status") == "confirmation_required" or raw.get("confirmation_required") is True:
+        return "blocked"
+
+    if raw.get("error"):
+        return "failed"
+    if raw.get("success") is False:
+        return "failed"
+
+    # Bulk operations set this explicitly when some units failed.
+    if raw.get("partial") is True:
+        return "partial"
+    succeeded, failed = raw.get("succeeded"), raw.get("failed")
+    if isinstance(succeeded, int) and isinstance(failed, int) and succeeded > 0 and failed > 0:
+        return "partial"
+
+    return "success"
+
+
+# ─── Warnings ────────────────────────────────────────────────────────────────
+
+def extract_warnings(raw: Any) -> List[str]:
+    """Every advisory the payload carries, as a flat list of strings."""
+    if not isinstance(raw, dict):
+        return []
+
+    out: List[str] = []
+
+    def add(value: Any) -> None:
+        if isinstance(value, str) and value.strip() and value.strip() not in out:
+            out.append(value.strip())
+
+    plural = raw.get("warnings")
+    if isinstance(plural, list):
+        for item in plural:
+            add(item if isinstance(item, str) else str(item) if item else None)
+    else:
+        add(plural)
+    add(raw.get("warning"))
+
+    ignored = raw.get("ignored_options")
+    if ignored:
+        add(f"Ignored unsupported options: {ignored}")
+
+    return out
+
+
+# ─── Verification ────────────────────────────────────────────────────────────
+
+def extract_verification(raw: Any) -> Dict[str, Any]:
+    """Normalize whatever verification evidence the payload carries.
+
+    'unverified' means *no evidence was reported*, which is not the same as
+    'checked and fine' — a caller that needs certainty should treat it as an
+    open question rather than a pass.
+    """
+    unverified = {"status": "unverified", "checks": [], "contradiction": False}
+    if not isinstance(raw, dict):
+        return unverified
+
+    # An impl that already speaks this shape wins outright.
+    existing = raw.get("verification")
+    if isinstance(existing, dict) and existing:
+        merged = dict(existing)
+        merged.setdefault(
+            "status", "passed" if existing.get("verified") else "unverified")
+        merged.setdefault("checks", [])
+        merged.setdefault("contradiction", False)
+        return merged
+
+    checks: List[Dict[str, Any]] = []
+    status = "unverified"
+    contradiction = False
+
+    readback = raw.get("readback")
+    if isinstance(readback, dict):
+        missing = readback.get("missing")
+        if isinstance(missing, list):
+            checks.append({
+                "check": "readback_verification",
+                "passed": not missing,
+                "missing_items": len(missing),
+            })
+            status = "passed" if not missing else "failed"
+
+    # verify_by_readback's own shape: a mutation that reported success while the
+    # post-state disagrees is a contradiction, this repo's single most valuable
+    # reliability signal — it must not be flattened into a plain failure.
+    if "verified" in raw:
+        verified = bool(raw["verified"])
+        contradiction = bool(raw.get("contradiction"))
+        checks.append({
+            "check": "readback_post_state",
+            "passed": verified,
+            "contradiction": contradiction,
+            "observed": raw.get("observed"),
+        })
+        status = "contradiction" if contradiction else ("passed" if verified else "failed")
+
+    if "property_restore_failures" in raw:
+        failures = _as_int(raw.get("property_restore_failures"))
+        checks.append({
+            "check": "property_restore",
+            "passed": failures == 0,
+            "restored_items": _as_int(raw.get("properties_restored_items")),
+            "failures": failures,
+        })
+        if failures and status in ("passed", "unverified"):
+            status = "partial"
+
+    succeeded, failed = raw.get("succeeded"), raw.get("failed")
+    if isinstance(succeeded, int) and isinstance(failed, int):
+        checks.append({
+            "check": "bulk_operations",
+            "passed": failed == 0,
+            "succeeded": succeeded,
+            "failed": failed,
+        })
+        if status == "unverified":
+            if failed == 0 and succeeded > 0:
+                status = "passed"
+            elif succeeded > 0:
+                status = "partial"
+            elif failed > 0:
+                status = "failed"
+
+    if not checks:
+        return unverified
+    return {"status": status, "checks": checks, "contradiction": contradiction}
+
+
+# ─── Changes ─────────────────────────────────────────────────────────────────
+
+def _as_int(value: Any) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return 0
+
+
+#: Domain key → semantic delta. Every entry is a key that exists in `src/` and
+#: means what the delta says it means; nothing is mapped on the strength of a
+#: suggestive name. `properties_restored_items`, for instance, is deliberately
+#: absent: a ripple insert restores clip properties it had to re-apply after
+#: moving items, which is bookkeeping, not an edit the user made.
+_COUNT_ALIASES = {
+    "items_added": ("inserted_clips",),
+    "items_moved": ("tail_items_shifted",),
+    "items_deleted": (),
+}
+
+
+def extract_changes(raw: Any) -> Optional[Dict[str, Any]]:
+    """The operation's semantic delta, or None when it did not report one.
+
+    None, not ``{}``. An empty dict reads as "this operation changed nothing",
+    which is a false statement about a ripple insert that simply never declared
+    its deltas — the silent-lie failure this codebase treats as a bug class. A
+    caller that needs a number and gets None knows to go and count.
+    """
+    if not isinstance(raw, dict):
+        return None
+
+    changes: Dict[str, Any] = {}
+
+    # An impl that declares its own deltas is authoritative.
+    declared = raw.get("_changes")
+    if isinstance(declared, dict):
+        changes.update(declared)
+
+    for canonical, aliases in _COUNT_ALIASES.items():
+        if canonical in raw:
+            changes[canonical] = _as_int(raw[canonical])
+            continue
+        for alias in aliases:
+            if alias in raw:
+                changes[canonical] = _as_int(raw[alias])
+                break
+
+    if "shift_frames" in raw:
+        changes["shift_frames"] = raw["shift_frames"]
+
+    versioning = raw.get("_versioning")
+    if isinstance(versioning, dict):
+        metric = versioning.get("metric")
+        before, after = versioning.get("before_value"), versioning.get("after_value")
+        if metric and before is not None and after is not None:
+            changes["metric"] = metric
+            changes["before_value"] = before
+            changes["after_value"] = after
+            try:
+                changes["delta"] = round(float(after) - float(before), 4)
+            except (TypeError, ValueError):
+                pass
+        if versioning.get("archived"):
+            changes["timeline_archived"] = True
+            if versioning.get("archived_version"):
+                changes["archived_version"] = versioning["archived_version"]
+
+    return changes or None
+
+
+# ─── Assembly ────────────────────────────────────────────────────────────────
+
+def is_passthrough(obj: Any) -> bool:
+    """MCP content objects (Image, TextContent, EmbeddedResource) go through as-is."""
+    return getattr(obj.__class__, "__name__", "") in {
+        "Image", "TextContent", "EmbeddedResource"
+    }
+
+
+def _requested_mode(params: Optional[Dict[str, Any]], fallback: Optional[str]) -> str:
+    if isinstance(params, dict):
+        for key in ("envelope", "_envelope"):
+            if key in params:
+                named = _clean_mode(params[key])
+                if named:
+                    return named
+                if isinstance(params[key], bool):
+                    return "pure" if params[key] else "legacy"
+    return _clean_mode(fallback) or get_envelope_mode()
+
+
+def build_operation_envelope(
+    tool_name: str,
+    action: str,
+    params: Optional[Dict[str, Any]],
+    raw_result: Any,
+    *,
+    execution_id: Optional[str] = None,
+    mode: Optional[str] = None,
+) -> Any:
+    """Attach the operation envelope to one action's return value."""
+    if is_passthrough(raw_result):
+        return raw_result
+
+    selected = _requested_mode(params, mode)
+    if selected == "legacy":
+        return raw_result
+
+    envelope: Dict[str, Any] = {
+        "status": normalize_status(raw_result),
+        "operation": f"{tool_name}.{action}",
+        "execution_id": execution_id or new_execution_id(),
+        "verification": extract_verification(raw_result),
+    }
+
+    changes = extract_changes(raw_result)
+    if changes is not None:
+        envelope["changes"] = changes
+
+    warnings = extract_warnings(raw_result)
+    if warnings:
+        envelope["warnings"] = warnings
+
+    versioning = raw_result.get("_versioning") if isinstance(raw_result, dict) else None
+    if isinstance(versioning, dict) and versioning.get("analysis_run_id"):
+        envelope["run_id"] = versioning["analysis_run_id"]
+
+    if selected == "pure":
+        return {**envelope, "result": raw_result}
+
+    # dual: the payload is passed through byte-for-byte and the envelope rides
+    # alongside it. A non-dict return has nowhere to carry the key, so it is
+    # handed back unchanged rather than being boxed into a shape callers of
+    # that action have never seen.
+    if not isinstance(raw_result, dict):
+        return raw_result
+    return {**raw_result, ENVELOPE_KEY: envelope}