ltcai 9.9.2 → 9.9.4

package/latticeai/core/run_store.py

@@ -0,0 +1,243 @@
+"""Durable persistence for paused agent runs (review 2026-07-25 Wave 0.1).
+
+The ``awaiting_approval`` loop parked runs in an in-process dict, so a server
+restart between pause and resume turned every outstanding approval into a 404
+("승인하려다 사라짐"). This store writes each paused run to one JSON file under
+the data dir, so a valid, unexpired token can resume its run across restarts
+and across worker processes.
+
+Design constraints (deliberate, matching :mod:`latticeai.services.funnel_metrics`):
+
+* **One JSON file per run**, atomic replace on write — no new dependencies.
+* **Fail-open on save, fail-closed on resume.** A persistence error never
+  breaks the pause response (the in-memory path still works); a load error on
+  resume is treated as "run not found".
+* **Tokens are never stored in plaintext.** Only the SHA-256 hex digest is
+  persisted; resume hashes the presented token and compares digests.
+* **Wall-clock expiry.** The in-memory dict keeps its monotonic deadline, but
+  monotonic time does not survive a restart — the durable record carries an
+  absolute UTC epoch and files past it are swept, never resumed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import re
+import tempfile
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from latticeai.core.agent import AgentRunContext, AgentState
+from latticeai.core.agent_trace import LoopTrace
+
+LOGGER = logging.getLogger(__name__)
+
+# run_id comes from ``secrets.token_urlsafe`` — validate before any path use
+# so a crafted id can never traverse out of the store directory.
+_RUN_ID_RE = re.compile(r"^[A-Za-z0-9_-]{8,64}$")
+
+
+def hash_approval_token(token: str) -> str:
+    """Stable digest used both at save and at resume comparison time."""
+    return hashlib.sha256(str(token or "").encode("utf-8")).hexdigest()
+
+
+def serialize_run_context(ctx: AgentRunContext) -> Dict[str, Any]:
+    """Reduce an :class:`AgentRunContext` to plain JSON-safe data."""
+    return {
+        "state": ctx.state.value,
+        "plan": ctx.plan,
+        "transcript": ctx.transcript,
+        "retry_count": ctx.retry_count,
+        "state_history": ctx.state_history,
+        "corrections": ctx.corrections,
+        "final_message": ctx.final_message,
+        "rollback_log": ctx.rollback_log,
+        "executing_model": ctx.executing_model,
+        "reviewing_model": ctx.reviewing_model,
+        "approved_by_human": ctx.approved_by_human,
+        "trace": {"events": ctx.trace.events, "truncated": ctx.trace.truncated},
+    }
+
+
+def restore_run_context(payload: Dict[str, Any]) -> AgentRunContext:
+    """Rebuild an :class:`AgentRunContext` from :func:`serialize_run_context`."""
+    ctx = AgentRunContext()
+    try:
+        ctx.state = AgentState(str(payload.get("state") or AgentState.WAITING_APPROVAL.value))
+    except ValueError:
+        ctx.state = AgentState.WAITING_APPROVAL
+    ctx.plan = dict(payload.get("plan") or {})
+    ctx.transcript = list(payload.get("transcript") or [])
+    ctx.retry_count = int(payload.get("retry_count") or 0)
+    ctx.state_history = list(payload.get("state_history") or [])
+    ctx.corrections = list(payload.get("corrections") or [])
+    ctx.final_message = str(payload.get("final_message") or "")
+    ctx.rollback_log = list(payload.get("rollback_log") or [])
+    ctx.executing_model = payload.get("executing_model")
+    ctx.reviewing_model = payload.get("reviewing_model")
+    ctx.approved_by_human = bool(payload.get("approved_by_human"))
+    trace_payload = payload.get("trace") or {}
+    trace = LoopTrace()
+    trace.events = list(trace_payload.get("events") or [])
+    trace.truncated = int(trace_payload.get("truncated") or 0)
+    ctx.trace = trace
+    return ctx
+
+
+class AgentRunStore:
+    """One-JSON-file-per-run persistence for paused approval runs."""
+
+    def __init__(self, root: Path) -> None:
+        self._root = Path(root)
+
+    def _path_for(self, run_id: str) -> Optional[Path]:
+        if not _RUN_ID_RE.fullmatch(str(run_id or "")):
+            return None
+        return self._root / f"{run_id}.json"
+
+    # ── writes ───────────────────────────────────────────────────────────
+
+    def save(
+        self,
+        run_id: str,
+        *,
+        ctx: AgentRunContext,
+        req_payload: Dict[str, Any],
+        language_hint: str,
+        user: str,
+        token: str,
+        expires_epoch: float,
+        expires_at: str,
+    ) -> bool:
+        """Persist a paused run. Best-effort: returns False on any failure."""
+        path = self._path_for(run_id)
+        if path is None:
+            return False
+        record = {
+            "version": 1,
+            "run_id": run_id,
+            "user": user,
+            "language_hint": language_hint,
+            "token_hash": hash_approval_token(token),
+            "expires_epoch": float(expires_epoch),
+            "expires_at": expires_at,
+            "req": req_payload,
+            "ctx": serialize_run_context(ctx),
+        }
+        try:
+            self._root.mkdir(parents=True, exist_ok=True)
+            fd, tmp_name = tempfile.mkstemp(prefix=path.name, dir=str(self._root))
+            try:
+                with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                    json.dump(record, handle, ensure_ascii=False)
+                os.replace(tmp_name, path)
+            finally:
+                if os.path.exists(tmp_name):
+                    try:
+                        os.unlink(tmp_name)
+                    except OSError:
+                        pass
+            return True
+        except Exception as exc:  # noqa: BLE001 — pause must still answer without disk
+            LOGGER.warning("agent run store save failed for %s: %s", run_id, exc)
+            return False
+
+    def delete(self, run_id: str) -> None:
+        path = self._path_for(run_id)
+        if path is None:
+            return
+        try:
+            path.unlink(missing_ok=True)
+        except OSError as exc:
+            LOGGER.warning("agent run store delete failed for %s: %s", run_id, exc)
+
+    # ── reads ────────────────────────────────────────────────────────────
+
+    def load(self, run_id: str) -> Optional[Dict[str, Any]]:
+        """Raw persisted record, or None when missing/corrupt/invalid id."""
+        path = self._path_for(run_id)
+        if path is None:
+            return None
+        try:
+            record = json.loads(path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return None
+        except Exception as exc:  # noqa: BLE001 — corrupt record == not found
+            LOGGER.warning("agent run store load failed for %s: %s", run_id, exc)
+            return None
+        if not isinstance(record, dict) or record.get("run_id") != run_id:
+            return None
+        return record
+
+    def pending_summaries(self, user: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Unexpired pending runs (optionally per user) for surfacing in UI."""
+        summaries: List[Dict[str, Any]] = []
+        now = time.time()
+        try:
+            paths = sorted(self._root.glob("*.json"))
+        except OSError:
+            return summaries
+        for path in paths:
+            try:
+                record = json.loads(path.read_text(encoding="utf-8"))
+            except Exception:  # noqa: BLE001
+                continue
+            if not isinstance(record, dict):
+                continue
+            if float(record.get("expires_epoch") or 0) <= now:
+                continue
+            if user is not None and record.get("user") != user:
+                continue
+            plan = (record.get("ctx") or {}).get("plan") or {}
+            summaries.append({
+                "run_id": record.get("run_id"),
+                "user": record.get("user"),
+                "goal": str(plan.get("goal") or "")[:200],
+                "expires_at": record.get("expires_at"),
+            })
+        return summaries
+
+    def sweep_expired(
+        self,
+        now_epoch: Optional[float] = None,
+        *,
+        retention_seconds: float = 86400.0,
+    ) -> int:
+        """Remove long-expired run files; returns how many were removed.
+
+        Recently expired records are *kept* for ``retention_seconds`` so that
+        a resume attempt after expiry can still answer 410 with a one-click
+        replan hint (the original request message) instead of a bare 404.
+        """
+        removed = 0
+        now = time.time() if now_epoch is None else float(now_epoch)
+        try:
+            paths = list(self._root.glob("*.json"))
+        except OSError:
+            return removed
+        for path in paths:
+            try:
+                record = json.loads(path.read_text(encoding="utf-8"))
+                expires = float(record.get("expires_epoch") or 0)
+            except Exception:  # noqa: BLE001 — unreadable == expired garbage
+                expires = -float(retention_seconds)
+            if expires + float(retention_seconds) <= now:
+                try:
+                    path.unlink(missing_ok=True)
+                    removed += 1
+                except OSError:
+                    pass
+        return removed
+
+
+__all__ = [
+    "AgentRunStore",
+    "hash_approval_token",
+    "restore_run_context",
+    "serialize_run_context",
+]

package/latticeai/core/workspace_os.py

@@ -49,7 +49,7 @@ __all__ = [
     "remove_skill_directory",
 ]
 
-WORKSPACE_OS_VERSION = "9.9.2"
+WORKSPACE_OS_VERSION = "9.9.4"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/latticeai/models/router.py

@@ -78,6 +78,27 @@ If context or old chat history mentions those names, treat them only as legacy a
 You are a Vision-Language Model (VLM). If an image is provided, analyze it.
 Be concise and respond in the user's language."""
 
+# Appended ONLY when retrieved context exists (review 2026-07-25 Wave 2.3):
+# grounded answers should cite their sources and admit gaps. Advisory prompt
+# guidance — grounding assessment stays annotation-only and never blocks.
+CITATION_INSTRUCTION = """The Context section above contains retrieved sources.
+Ground your claims in those sources and cite them inline as [1], [2], ... matching the order they appear in the Context.
+If the context does not cover the question, say so instead of inventing sources.
+Never cite a source that is not in the Context."""
+
+
+def _compose_system(base: str, context: str) -> str:
+    """Compose the system prompt with optional retrieved context.
+
+    Byte-compatible with the historical prompt when ``context`` is empty:
+    the return value is exactly ``base``. When context exists, the Context
+    block plus :data:`CITATION_INSTRUCTION` are appended.
+    """
+    if not context:
+        return base
+    return f"{base}\n\nContext:\n{context}\n\n{CITATION_INSTRUCTION}"
+
+
 def normalize_branding(text: Optional[str]) -> str:
     if not text:
         return ""
@@ -497,10 +518,8 @@ class LLMRouter:
         return raw
 
     def _build_prompt(self, message: str, context: Optional[str], tokenizer) -> str:
-        system = SYSTEM_PROMPT
         context = normalize_branding(context)
-        if context:
-            system += f"\n\nContext:\n{context}"
+        system = _compose_system(SYSTEM_PROMPT, context)
         if hasattr(tokenizer, "apply_chat_template"):
             try:
                 msgs = [{"role": "system", "content": system}, {"role": "user", "content": message}]
@@ -510,10 +529,8 @@ class LLMRouter:
         return f"<|im_start|>system\n{system}<|im_end|>\n<|im_start|>user\n{message}<|im_end|>\n<|im_start|>assistant\n"
 
     def _build_vlm_prompt(self, model, processor, message: str, context: Optional[str], num_images: int) -> str:
-        system = SYSTEM_PROMPT
         context = normalize_branding(context)
-        if context:
-            system += f"\n\nContext:\n{context}"
+        system = _compose_system(SYSTEM_PROMPT, context)
         try:
             from mlx_vlm import apply_chat_template
 
@@ -616,10 +633,8 @@ class LLMRouter:
         return normalize_branding(str(result))
 
     async def _cloud_generate(self, cloud: CloudModel, message: str, context: Optional[str], max_tokens: int, temperature: float) -> str:
-        system = SYSTEM_PROMPT
         context = normalize_branding(context)
-        if context:
-            system += f"\n\nContext:\n{context}"
+        system = _compose_system(SYSTEM_PROMPT, context)
         try:
             response = await cloud.client.chat.completions.create(
                 model=cloud.model,
@@ -703,10 +718,8 @@ class LLMRouter:
             yield chunk
 
     async def _cloud_stream_generate(self, cloud: CloudModel, message: str, context: Optional[str], max_tokens: int, temperature: float) -> AsyncIterator[str]:
-        system = SYSTEM_PROMPT
         context = normalize_branding(context)
-        if context:
-            system += f"\n\nContext:\n{context}"
+        system = _compose_system(SYSTEM_PROMPT, context)
         try:
             stream = await cloud.client.chat.completions.create(
                 model=cloud.model,

package/latticeai/runtime/persistence_runtime.py

@@ -38,6 +38,7 @@ def build_persistence_runtime(
     from latticeai.core.workspace_os import WorkspaceOSStore
     from latticeai.services.automation_intelligence import AutomationIntelligenceService
     from latticeai.services.brain_intelligence import BrainIntelligenceService
+    from latticeai.services.funnel_metrics import FunnelMetricsService
     from latticeai.services.memory_service import MemoryService
     from latticeai.services.workspace_service import WorkspaceService
 
@@ -70,11 +71,27 @@ def build_persistence_runtime(
         store=workspace_os,
         enable_graph=enable_graph,
     )
+    # UX funnel metrics (backlog #16): cheap JSON counters under the data dir.
+    # The ingestion pipeline's audit seam is wrapped so every successful
+    # ingest bumps the funnel (and starts the TTFV clock) without touching
+    # lattice_brain internals.
+    funnel_metrics = FunnelMetricsService(Path(data_dir) / "funnel_metrics.json")
+
+    def _funnel_audit(action, detail, user):
+        try:
+            if action == "kg_ingest":
+                funnel_metrics.record_ingest(
+                    duplicate=bool((detail or {}).get("duplicate"))
+                )
+        except Exception:  # noqa: BLE001 — metrics must never break ingestion
+            pass
+        audit(action, detail, user)
+
     ingestion_pipeline = IngestionPipeline(
         knowledge_graph,
         hooks=hooks_registry,
         enable_graph=enable_graph,
-        audit=audit,
+        audit=_funnel_audit,
     )
     device_identity = DeviceIdentity(data_dir)
     kg_portability = KGPortabilityService(
@@ -99,4 +116,5 @@ def build_persistence_runtime(
         "INGESTION_PIPELINE": ingestion_pipeline,
         "DEVICE_IDENTITY": device_identity,
         "KG_PORTABILITY": kg_portability,
+        "FUNNEL_METRICS": funnel_metrics,
     }

package/latticeai/runtime/router_registration.py

@@ -605,6 +605,7 @@ def register_review_and_brain_tail_routers(
     create_setup_router: Any,
     model_router: Any,
     change_proposals: Any = None,
+    knowledge_graph: Any = None,
 ) -> Any:
     """Register the final review/browser/brain tail routes in legacy order."""
 
@@ -644,6 +645,12 @@ def register_review_and_brain_tail_routers(
             require_admin=require_admin,
         ),
         create_garden_router(gardener=gardener, require_user=require_user),
-        create_setup_router(model_router=model_router, require_user=require_user),
+        create_setup_router(
+            model_router=model_router,
+            require_user=require_user,
+            ingestion_pipeline=ingestion_pipeline,
+            knowledge_graph=knowledge_graph,
+            workspace_service=workspace_service,
+        ),
     )
     return brain_network

package/latticeai/services/app_context.py

@@ -42,6 +42,9 @@ class AppContext:
     hooks: Any = None
     realtime_bus: Any = None
     capability_registry: Any = None
+    # UX funnel metrics (latticeai.services.funnel_metrics); None in tests
+    # that don't observe the funnel — every increment site is nil-safe.
+    funnel_metrics: Any = None
 
     # ── auth / session callables ──────────────────────────────────────────
     require_user: Optional[Callable[..., str]] = None

package/latticeai/services/architecture_readiness.py

@@ -17,7 +17,7 @@ from typing import Any, Dict, List
 from latticeai.core.legacy_compatibility import legacy_shim_report
 
 
-ARCHITECTURE_VERSION_TARGET = "9.9.2"
+ARCHITECTURE_VERSION_TARGET = "9.9.4"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",

package/latticeai/services/automation_execution.py

@@ -0,0 +1,266 @@
+"""Automation "run now" support: dry-run reports + execution log surfacing.
+
+Backlog #6 (review §7.2 F, Wave 2): after installing an automation the user
+should be able to run it once immediately — first as a **dry run** that
+reports exactly what WOULD happen without side effects, then for real — and
+every automation card should show its last execution result.
+
+This module owns the deterministic policy pieces:
+
+* :func:`dry_run_report` — walks the workflow's node graph (same normalizer
+  as the engine) and describes each step without invoking any runner. No
+  model call, no store write, no side effects.
+* :func:`build_last_execution` / :func:`summarize_workflow_run` — the compact
+  ``last_execution`` record persisted on the workflow's metadata and surfaced
+  by the automation overview + daily briefing.
+* :func:`last_execution_view` — read-side merge: the stamped metadata record
+  vs. the newest persisted workflow run (so trigger-driven runs surface too).
+* :func:`enqueue_failed_execution` — failed live executions become a review
+  queue item (source ``workflow_run``, kind ``automation_failure``) so
+  failures land in the same inbox as every other automation outcome.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from latticeai.core.timeutil import now_iso as _now
+
+LOGGER = logging.getLogger(__name__)
+
+AUTOMATION_CREATED_FROM = frozenset({
+    "automation_suggestion",
+    "brain_automation_recipe",
+})
+
+_TRIGGER_LABEL = {
+    "interval": "wait for the user-enabled schedule",
+    "brain_event": "wait for new Brain knowledge",
+    "manual": "start when the user asks",
+}
+
+
+def is_automation_workflow(workflow: Dict[str, Any]) -> bool:
+    metadata = (workflow or {}).get("metadata") or {}
+    return metadata.get("created_from") in AUTOMATION_CREATED_FROM
+
+
+def dry_run_report(workflow: Dict[str, Any]) -> Dict[str, Any]:
+    """Describe what a run WOULD do — deterministically, with no side effects.
+
+    Walks the normalized node chain (``trigger`` first, then ``next``
+    pointers) and emits one human-readable step per node. Nothing is
+    executed: no runner, no model, no store write.
+    """
+    from lattice_brain.workflow import normalize_definition, validate_definition
+
+    definition = normalize_definition(workflow or {})
+    errors = validate_definition(definition)
+    metadata = definition.get("metadata") or {}
+    steps: List[Dict[str, Any]] = []
+
+    nodes = {node.get("id"): node for node in definition.get("nodes") or []}
+    current = next(
+        (node for node in definition.get("nodes") or [] if node.get("type") == "trigger"),
+        None,
+    )
+    visited: set = set()
+    while current is not None and current.get("id") not in visited:
+        visited.add(current.get("id"))
+        ntype = str(current.get("type") or "")
+        config = current.get("config") or {}
+        if ntype == "trigger":
+            would = _TRIGGER_LABEL.get(
+                str(config.get("trigger") or "manual"),
+                "start when triggered",
+            )
+            would = f"skipped in a manual run ({would})"
+        elif ntype == "agent":
+            prompt = str(config.get("prompt") or config.get("goal") or "")[:160]
+            would = f"ask the local agent to draft: {prompt}" if prompt else (
+                "ask the local agent to draft a review item"
+            )
+        elif ntype == "tool":
+            would = f"run tool '{config.get('tool') or current.get('name') or 'tool'}'"
+        elif ntype == "skill":
+            would = f"run skill '{config.get('skill') or current.get('name') or 'skill'}'"
+        elif ntype == "plugin":
+            would = f"run plugin '{config.get('plugin') or current.get('name') or 'plugin'}'"
+        elif ntype == "condition":
+            would = "evaluate a branch condition"
+        elif ntype == "output":
+            would = "deliver the draft to the review inbox"
+        else:
+            would = f"run node '{current.get('id')}'"
+        steps.append({
+            "node": current.get("id"),
+            "type": ntype,
+            "name": current.get("name") or current.get("id"),
+            "would": would,
+        })
+        next_id = current.get("next")
+        current = nodes.get(next_id) if next_id else None
+
+    executable = [s for s in steps if s["type"] not in {"trigger", "output", "condition"}]
+    creates = list(metadata.get("creates") or [])
+    if errors:
+        summary = "invalid workflow: " + "; ".join(errors[:3])
+        status = "invalid"
+    else:
+        summary = (
+            f"{len(executable)} step(s) would run locally and produce a reviewable draft"
+        )
+        if creates:
+            summary += " (" + ", ".join(str(c) for c in creates[:3]) + ")"
+        summary += "; no external actions, nothing is written until you approve."
+        status = "ok"
+    return {
+        "mode": "dry_run",
+        "status": status,
+        "steps": steps,
+        "summary": summary,
+        "side_effects": False,
+        "validation_errors": errors,
+    }
+
+
+def build_last_execution(
+    *,
+    mode: str,
+    status: str,
+    summary: str,
+    run_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """The compact per-automation execution record (persisted on metadata)."""
+    return {
+        "mode": mode,                     # dry_run | live
+        "status": status,                 # ok | failed | running | partial | ...
+        "summary": str(summary or "")[:300],
+        "run_id": run_id,
+        "finished_at": _now(),
+    }
+
+
+def summarize_workflow_run(run: Dict[str, Any]) -> str:
+    """One honest line for a persisted workflow run."""
+    status = str(run.get("status") or "unknown")
+    timeline = run.get("timeline") or []
+    if status == "failed":
+        detail = ""
+        for entry in reversed(timeline):
+            if entry.get("status") in {"failed", "error"}:
+                detail = str(
+                    entry.get("reason") or entry.get("detail") or entry.get("errors") or ""
+                )[:160]
+                break
+        if not detail:
+            detail = str((run.get("outputs") or {}).get("error") or "")[:160]
+        return f"failed after {len(timeline)} step(s)" + (f": {detail}" if detail else "")
+    if status == "awaiting_approval":
+        return "paused — a step needs your approval before it can run"
+    if status in {"queued", "running", "cancelling"}:
+        return "still running"
+    return f"{status} — {len(timeline)} step(s) recorded"
+
+
+def last_execution_view(
+    workflow: Dict[str, Any],
+    *,
+    store: Any = None,
+    workspace_id: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Read-side ``last_execution``: stamped metadata vs. newest persisted run.
+
+    Run-now stamps ``metadata.last_execution`` directly; trigger/background
+    runs only leave workflow-run rows. Whichever is newer wins so the card is
+    honest about the latest execution regardless of how it was started.
+    """
+    metadata = (workflow or {}).get("metadata") or {}
+    stamped = metadata.get("last_execution")
+    stamped = dict(stamped) if isinstance(stamped, dict) else None
+
+    latest_run: Optional[Dict[str, Any]] = None
+    if store is not None and hasattr(store, "list_workflow_runs"):
+        try:
+            runs = (
+                store.list_workflow_runs(
+                    workflow_id=workflow.get("id"), limit=1, workspace_id=workspace_id
+                )
+                or {}
+            ).get("runs") or []
+            latest_run = runs[0] if runs else None
+        except Exception:  # noqa: BLE001 — surfacing must never break the overview
+            LOGGER.exception("automation last-execution run read failed")
+            latest_run = None
+
+    derived: Optional[Dict[str, Any]] = None
+    if latest_run is not None:
+        derived = {
+            "mode": "live",
+            "status": str(latest_run.get("status") or "unknown"),
+            "summary": summarize_workflow_run(latest_run),
+            "run_id": latest_run.get("id"),
+            "finished_at": str(
+                latest_run.get("completed_at")
+                or latest_run.get("updated_at")
+                or latest_run.get("created_at")
+                or ""
+            ),
+        }
+
+    if stamped is None:
+        return derived
+    if derived is None:
+        return stamped
+    return derived if str(derived.get("finished_at") or "") > str(
+        stamped.get("finished_at") or ""
+    ) else stamped
+
+
+def enqueue_failed_execution(
+    review_queue: Any,
+    *,
+    workflow: Dict[str, Any],
+    run_id: Optional[str],
+    error: str,
+    user_email: Optional[str] = None,
+    workspace_id: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Failed live execution → review queue item (never raises)."""
+    if review_queue is None:
+        return None
+    name = str(workflow.get("name") or "Automation")
+    try:
+        return review_queue.create(
+            title=f"Automation failed: {name}"[:160],
+            summary=str(error or "")[:500],
+            source="workflow_run",
+            kind="automation_failure",
+            payload={
+                "workflow_id": workflow.get("id"),
+                "run_id": run_id,
+                "error": str(error or "")[:500],
+            },
+            provenance={
+                "workflow_id": workflow.get("id"),
+                "run_id": run_id,
+                "origin": "automation_run_now",
+            },
+            user_email=user_email,
+            workspace_id=workspace_id,
+        )
+    except Exception:  # noqa: BLE001 — review enqueue is best-effort surfacing
+        LOGGER.exception("automation failure review enqueue failed")
+        return None
+
+
+__all__ = [
+    "AUTOMATION_CREATED_FROM",
+    "is_automation_workflow",
+    "dry_run_report",
+    "build_last_execution",
+    "summarize_workflow_run",
+    "last_execution_view",
+    "enqueue_failed_execution",
+]