ltcai 11.5.2 → 11.7.0

package/latticeai/core/workspace_runs.py

@@ -1,726 +0,0 @@
-"""Agent and workflow run persistence extracted from WorkspaceOSStore."""
-from __future__ import annotations
-
-import json
-from typing import Any, Dict, List, Optional
-
-from lattice_brain.runtime.contracts import run_record_contract, workflow_run_contract
-from lattice_brain.runtime.statuses import RUN_ACTIVE_STATUSES, RUN_TERMINAL_STATUSES
-
-from .timeutil import now_iso as _now
-from .workspace_os_utils import WorkspaceStoreMixin, _json_hash, _listify
-
-
-class WorkspaceRuns(WorkspaceStoreMixin):
-    def list_agents(self, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        runs = self._scoped(_listify(state.get("agent_runs")), workspace_id)
-        return {"agents": _listify(state.get("agents")), "runs": list(reversed(runs[-100:]))}
-
-    def record_agent_run(
-        self,
-        *,
-        agent_id: str,
-        status: str,
-        input_text: str,
-        output_text: str,
-        user_email: Optional[str],
-        timeline: Optional[List[Dict[str, Any]]] = None,
-        relationships: Optional[List[str]] = None,
-        handoffs: Optional[List[Dict[str, Any]]] = None,
-        context_packets: Optional[List[Dict[str, Any]]] = None,
-        plan: Optional[List[Dict[str, Any]]] = None,
-        plan_review: Optional[Dict[str, Any]] = None,
-        review_history: Optional[List[Dict[str, Any]]] = None,
-        retry_history: Optional[List[Dict[str, Any]]] = None,
-        memory_snapshots: Optional[List[Dict[str, Any]]] = None,
-        graph: Any = None,
-        workspace_id: Optional[str] = None,
-        mode: str = "simulation",
-    ) -> Dict[str, Any]:
-        state = self.load_state()
-        resolved_workspace = self._resolve_scope(workspace_id, state)
-        run = {
-            "id": f"agent-run-{_json_hash([agent_id, input_text, output_text, _now()])[:16]}",
-            "record_schema_version": 2,
-            "agent_id": agent_id,
-            "mode": mode,
-            "status": status,
-            "input": input_text,
-            "output_preview": output_text[:1000],
-            "user_email": user_email,
-            "workspace_id": resolved_workspace,
-            "relationships": relationships or [],
-            "timeline": timeline or [],
-            "handoffs": handoffs or [],
-            "context_packets": context_packets or [],
-            "plan": plan or [],
-            "plan_review": plan_review or {},
-            "review_history": review_history or [],
-            "retry_history": retry_history or [],
-            "memory_snapshots": memory_snapshots or [],
-            "created_at": _now(),
-        }
-        if mode == "simulation":
-            # Simulated runs are replay scaffolding, not experiences — they must
-            # never enter the knowledge graph as real provenance.
-            run["graph_node_id"] = None
-            run["graph_skipped"] = "simulation runs are not recorded in the knowledge graph"
-        elif graph is not None:
-            try:
-                ingested = graph.ingest_event(
-                    "AgentRun",
-                    f"{agent_id} {status}",
-                    user_email=user_email,
-                    source="workspace_os",
-                    workspace_id=resolved_workspace,
-                    metadata={"run_id": run["id"], "agent_id": agent_id, "status": status, "mode": mode},
-                )
-                run["graph_node_id"] = ingested.get("node_id")
-            except Exception as exc:
-                run["graph_error"] = str(exc)
-        if handoffs:
-            stored_handoffs = state.setdefault("handoffs", [])
-            for handoff in handoffs:
-                stored = {
-                    **handoff,
-                    "run_id": run["id"],
-                    "workspace_id": resolved_workspace,
-                }
-                stored_handoffs.append(stored)
-            state["handoffs"] = stored_handoffs
-        state.setdefault("agent_runs", []).append(run)
-        self.save_state(state)
-        self._emit_replayable_timeline_events(area="agent", run_id=run["id"], timeline=run["timeline"], workspace_id=resolved_workspace)
-        if status == "failed":
-            self._emit_execution_event(area="agent", event_type="execution_failed", payload={"run_id": run["id"], "agent_id": agent_id, "status": status}, workspace_id=resolved_workspace)
-        self.record_timeline_event("agent", "agent_run", {"run_id": run["id"], "agent_id": agent_id, "status": status}, workspace_id=resolved_workspace)
-        run["contract"] = run_record_contract(run)
-        state = self.load_state()
-        for item in _listify(state.get("agent_runs")):
-            if item.get("id") == run["id"]:
-                item["contract"] = run["contract"]
-                break
-        self.save_state(state)
-        return run
-
-    def update_agent_run(
-        self,
-        run_id: str,
-        *,
-        workspace_id: Optional[str] = None,
-        graph: Any = None,
-        patch: Optional[Dict[str, Any]] = None,
-        **fields: Any,
-    ) -> Dict[str, Any]:
-        """Patch a persisted agent run without changing its id.
-
-        Async execution creates a durable queued/running row before work starts,
-        then updates that same row as progress, cancellation, or a terminal
-        result arrives. This keeps old run lists/read APIs compatible while
-        avoiding duplicate "placeholder + final" records.
-        """
-        updates = {**(patch or {}), **fields}
-        state = self.load_state()
-        run = next((item for item in _listify(state.get("agent_runs")) if item.get("id") == run_id), None)
-        if run is None or (workspace_id and self._record_workspace(run) != str(workspace_id)):
-            raise FileNotFoundError(run_id)
-        resolved_workspace = self._record_workspace(run)
-        old_timeline_len = len(run.get("timeline") or [])
-
-        output_text = updates.pop("output_text", None)
-        if output_text is not None:
-            run["output_preview"] = str(output_text)[:1000]
-        for key, value in updates.items():
-            run[key] = value
-        status = str(run.get("status") or "")
-        run["updated_at"] = _now()
-        if status in RUN_TERMINAL_STATUSES:
-            run.setdefault("completed_at", _now())
-
-        handoffs = updates.get("handoffs")
-        if isinstance(handoffs, list):
-            stored_handoffs = [
-                item for item in _listify(state.get("handoffs"))
-                if item.get("run_id") != run_id
-            ]
-            for handoff in handoffs:
-                if isinstance(handoff, dict):
-                    stored_handoffs.append({**handoff, "run_id": run_id, "workspace_id": resolved_workspace})
-            state["handoffs"] = stored_handoffs
-
-        if (
-            status in RUN_TERMINAL_STATUSES
-            and run.get("mode") != "simulation"
-            and graph is not None
-            and not run.get("graph_node_id")
-        ):
-            try:
-                ingested = graph.ingest_event(
-                    "AgentRun",
-                    f"{run.get('agent_id')} {status}",
-                    user_email=run.get("user_email"),
-                    source="workspace_os",
-                    workspace_id=resolved_workspace,
-                    metadata={
-                        "run_id": run_id,
-                        "agent_id": run.get("agent_id"),
-                        "status": status,
-                        "mode": run.get("mode"),
-                    },
-                )
-                run["graph_node_id"] = ingested.get("node_id")
-            except Exception as exc:
-                run["graph_error"] = str(exc)
-
-        self.save_state(state)
-        run["contract"] = run_record_contract(run)
-        state = self.load_state()
-        for item in _listify(state.get("agent_runs")):
-            if item.get("id") == run_id:
-                item["contract"] = run["contract"]
-                break
-        self.save_state(state)
-
-        timeline = run.get("timeline") or []
-        if len(timeline) > old_timeline_len:
-            self._emit_replayable_timeline_events(
-                area="agent",
-                run_id=run_id,
-                timeline=timeline[old_timeline_len:],
-                workspace_id=resolved_workspace,
-            )
-        if status == "failed":
-            self._emit_execution_event(area="agent", event_type="execution_failed", payload={"run_id": run_id, "agent_id": run.get("agent_id"), "status": status}, workspace_id=resolved_workspace)
-        elif status == "cancelled":
-            self._emit_execution_event(area="agent", event_type="execution_cancelled", payload={"run_id": run_id, "agent_id": run.get("agent_id"), "status": status}, workspace_id=resolved_workspace)
-        elif status == "interrupted":
-            self._emit_execution_event(area="agent", event_type="execution_interrupted", payload={"run_id": run_id, "agent_id": run.get("agent_id"), "status": status}, workspace_id=resolved_workspace)
-        self.record_timeline_event("agent", "agent_run_update", {"run_id": run_id, "agent_id": run.get("agent_id"), "status": status}, workspace_id=resolved_workspace)
-        return run
-
-    def get_agent_run(self, run_id: str, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        run = next((item for item in _listify(self.load_state().get("agent_runs")) if item.get("id") == run_id), None)
-        if not run or (workspace_id and self._record_workspace(run) != str(workspace_id)):
-            raise FileNotFoundError(run_id)
-        return run
-
-    def list_handoffs(self, workspace_id: Optional[str] = None, run_id: Optional[str] = None) -> Dict[str, Any]:
-        handoffs = self._scoped(_listify(self.load_state().get("handoffs")), workspace_id)
-        if run_id:
-            handoffs = [item for item in handoffs if item.get("run_id") == run_id]
-        return {"handoffs": list(reversed(handoffs[-200:]))}
-
-    def create_workflow(
-        self,
-        *,
-        name: str,
-        steps: List[Dict[str, Any]],
-        user_email: Optional[str],
-        metadata: Optional[Dict[str, Any]] = None,
-        graph: Any = None,
-        workspace_id: Optional[str] = None,
-        nodes: Optional[List[Dict[str, Any]]] = None,
-    ) -> Dict[str, Any]:
-        state = self.load_state()
-        workflow = {
-            "id": f"workflow-{_json_hash([name, steps, user_email, _now()])[:16]}",
-            "name": name or "Untitled workflow",
-            "steps": steps,
-            "user_email": user_email,
-            "workspace_id": self._resolve_scope(workspace_id, state),
-            "metadata": metadata or {},
-            "events": [{"type": "created", "timestamp": _now()}],
-            "created_at": _now(),
-            "updated_at": _now(),
-        }
-        # Workflow Designer stores a typed-node graph alongside the legacy
-        # ``steps`` list so older history keeps working and new editors get nodes.
-        if nodes is not None:
-            workflow["nodes"] = nodes
-        if graph is not None:
-            try:
-                ingested = graph.ingest_event(
-                    "Workflow",
-                    workflow["name"],
-                    user_email=user_email,
-                    source="workspace_os",
-                    workspace_id=workflow["workspace_id"],
-                    metadata={"workflow_id": workflow["id"], "steps": steps},
-                )
-                workflow["graph_node_id"] = ingested.get("node_id")
-            except Exception as exc:
-                workflow["graph_error"] = str(exc)
-        state.setdefault("workflows", []).append(workflow)
-        self.save_state(state)
-        self.record_timeline_event(
-            "workflow",
-            "workflow_created",
-            {"workflow_id": workflow["id"], "name": workflow["name"]},
-            workspace_id=workflow["workspace_id"],
-        )
-        return workflow
-
-    def record_workflow_run(
-        self,
-        *,
-        workflow_id: Optional[str],
-        name: str,
-        status: str,
-        timeline: List[Dict[str, Any]],
-        outputs: Optional[Dict[str, Any]] = None,
-        user_email: Optional[str] = None,
-        graph: Any = None,
-        workspace_id: Optional[str] = None,
-        mode: str = "simulation",
-        pause: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """Persist a Workflow Designer execution into local-first run history."""
-        state = self.load_state()
-        resolved_workspace = self._resolve_scope(workspace_id, state)
-        run = {
-            "id": f"workflow-run-{_json_hash([workflow_id, name, status, _now()])[:16]}",
-            "record_schema_version": 2,
-            "workflow_id": workflow_id,
-            "name": name or "workflow",
-            "mode": mode,
-            "status": status,
-            "timeline": timeline or [],
-            "outputs": outputs or {},
-            "user_email": user_email,
-            "workspace_id": resolved_workspace,
-            "created_at": _now(),
-        }
-        if pause:
-            run["pause"] = pause
-        if mode == "simulation":
-            # Record-only node runners do no real work; their runs must not be
-            # written into the knowledge graph as if they were real executions.
-            run["graph_node_id"] = None
-            run["graph_skipped"] = "simulation runs are not recorded in the knowledge graph"
-        elif graph is not None:
-            try:
-                ingested = graph.ingest_event(
-                    "WorkflowRun",
-                    f"{run['name']} {status}",
-                    user_email=user_email,
-                    source="workspace_os",
-                    workspace_id=resolved_workspace,
-                    metadata={"run_id": run["id"], "workflow_id": workflow_id, "status": status, "mode": mode},
-                )
-                run["graph_node_id"] = ingested.get("node_id")
-            except Exception as exc:
-                run["graph_error"] = str(exc)
-        state.setdefault("workflow_runs", []).append(run)
-        # Attach the run id to the workflow's event log for cross-linking.
-        for wf in _listify(state.get("workflows")):
-            if wf.get("id") == workflow_id:
-                wf.setdefault("events", []).append({"type": "run", "timestamp": _now(), "payload": {"run_id": run["id"], "status": status}})
-                wf["updated_at"] = _now()
-                break
-        self.save_state(state)
-        self._emit_execution_event(area="workflow", event_type="workflow_started", payload={"run_id": run["id"], "workflow_id": workflow_id, "name": name}, workspace_id=resolved_workspace)
-        self._emit_replayable_timeline_events(area="workflow", run_id=run["id"], timeline=run["timeline"], workspace_id=resolved_workspace)
-        if status == "failed":
-            self._emit_execution_event(area="workflow", event_type="execution_failed", payload={"run_id": run["id"], "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        elif status in {"ok", "partial"}:
-            self._emit_execution_event(area="workflow", event_type="workflow_completed", payload={"run_id": run["id"], "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        self.record_timeline_event("workflow", "workflow_run", {"run_id": run["id"], "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        run["contract"] = workflow_run_contract(run)
-        state = self.load_state()
-        for item in _listify(state.get("workflow_runs")):
-            if item.get("id") == run["id"]:
-                item["contract"] = run["contract"]
-                break
-        self.save_state(state)
-        return run
-
-    def update_workflow_run(
-        self,
-        run_id: str,
-        *,
-        workspace_id: Optional[str] = None,
-        graph: Any = None,
-        patch: Optional[Dict[str, Any]] = None,
-        **fields: Any,
-    ) -> Dict[str, Any]:
-        """Patch a persisted workflow run in place for async execution."""
-        updates = {**(patch or {}), **fields}
-        state = self.load_state()
-        run = next((item for item in _listify(state.get("workflow_runs")) if item.get("id") == run_id), None)
-        if run is None or (workspace_id and self._record_workspace(run) != str(workspace_id)):
-            raise FileNotFoundError(run_id)
-        resolved_workspace = self._record_workspace(run)
-        old_timeline_len = len(run.get("timeline") or [])
-
-        for key, value in updates.items():
-            if value is None and key == "pause":
-                run.pop("pause", None)
-            else:
-                run[key] = value
-        status = str(run.get("status") or "")
-        run["updated_at"] = _now()
-        if status in RUN_TERMINAL_STATUSES:
-            run.setdefault("completed_at", _now())
-
-        workflow_id = run.get("workflow_id")
-        for wf in _listify(state.get("workflows")):
-            if wf.get("id") == workflow_id:
-                wf.setdefault("events", []).append({"type": "run_update", "timestamp": _now(), "payload": {"run_id": run_id, "status": status}})
-                wf["updated_at"] = _now()
-                break
-
-        if (
-            status in RUN_TERMINAL_STATUSES
-            and run.get("mode") != "simulation"
-            and graph is not None
-            and not run.get("graph_node_id")
-        ):
-            try:
-                ingested = graph.ingest_event(
-                    "WorkflowRun",
-                    f"{run.get('name')} {status}",
-                    user_email=run.get("user_email"),
-                    source="workspace_os",
-                    workspace_id=resolved_workspace,
-                    metadata={
-                        "run_id": run_id,
-                        "workflow_id": workflow_id,
-                        "status": status,
-                        "mode": run.get("mode"),
-                    },
-                )
-                run["graph_node_id"] = ingested.get("node_id")
-            except Exception as exc:
-                run["graph_error"] = str(exc)
-
-        self.save_state(state)
-        run["contract"] = workflow_run_contract(run)
-        state = self.load_state()
-        for item in _listify(state.get("workflow_runs")):
-            if item.get("id") == run_id:
-                item["contract"] = run["contract"]
-                break
-        self.save_state(state)
-
-        timeline = run.get("timeline") or []
-        if len(timeline) > old_timeline_len:
-            self._emit_replayable_timeline_events(
-                area="workflow",
-                run_id=run_id,
-                timeline=timeline[old_timeline_len:],
-                workspace_id=resolved_workspace,
-            )
-        if status == "failed":
-            self._emit_execution_event(area="workflow", event_type="execution_failed", payload={"run_id": run_id, "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        elif status in {"ok", "partial"}:
-            self._emit_execution_event(area="workflow", event_type="workflow_completed", payload={"run_id": run_id, "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        elif status == "cancelled":
-            self._emit_execution_event(area="workflow", event_type="execution_cancelled", payload={"run_id": run_id, "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        elif status == "interrupted":
-            self._emit_execution_event(area="workflow", event_type="execution_interrupted", payload={"run_id": run_id, "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        self.record_timeline_event("workflow", "workflow_run_update", {"run_id": run_id, "workflow_id": workflow_id, "status": status}, workspace_id=resolved_workspace)
-        return run
-
-    def list_workflow_runs(self, workflow_id: Optional[str] = None, limit: int = 50, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        runs = self._scoped(_listify(self.load_state().get("workflow_runs")), workspace_id)
-        if workflow_id:
-            runs = [run for run in runs if run.get("workflow_id") == workflow_id]
-        return {"runs": list(reversed(runs[-max(1, min(limit, 300)):]))}
-
-    def list_combined_runs(
-        self,
-        *,
-        limit: int = 20,
-        workspace_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Merge agent + workflow runs into one ``started_at``-descending timeline.
-
-        Response shape is the product contract for Act screen 09 and the
-        layout-rebuild activity feed: each row carries ``source``, a human
-        ``title``, stop/resume affordances, and normalized timestamps.
-        """
-        capped = max(1, min(int(limit or 20), 100))
-        state = self.load_state()
-        agent_runs = self._scoped(_listify(state.get("agent_runs")), workspace_id)
-        workflow_runs = self._scoped(_listify(state.get("workflow_runs")), workspace_id)
-        combined: List[Dict[str, Any]] = []
-        for run in agent_runs:
-            combined.append(self.activity_run_row(run, source="agent"))
-        for run in workflow_runs:
-            combined.append(self.activity_run_row(run, source="workflow"))
-        combined.sort(key=lambda row: str(row.get("started_at") or ""), reverse=True)
-        total = len(combined)
-        return {
-            "runs": combined[:capped],
-            "total": total,
-            "truncated": total > capped,
-        }
-
-    @staticmethod
-    def _first_string(*values: Any) -> str:
-        for value in values:
-            if isinstance(value, str) and value.strip():
-                return value.strip()
-        return ""
-
-    @classmethod
-    def activity_run_title(cls, run: Dict[str, Any]) -> str:
-        """Public title resolver shared by list_combined_runs and router fallbacks."""
-        direct = cls._first_string(
-            run.get("workflow_name"),
-            run.get("name"),
-            run.get("goal"),
-            run.get("title"),
-            run.get("query"),
-        )
-        if direct:
-            return direct
-        raw_input = run.get("input")
-        if isinstance(raw_input, str) and raw_input.strip():
-            return raw_input.strip()
-        if isinstance(raw_input, dict):
-            nested = cls._first_string(
-                raw_input.get("goal"),
-                raw_input.get("name"),
-                raw_input.get("title"),
-                raw_input.get("query"),
-                raw_input.get("text"),
-                raw_input.get("prompt"),
-            )
-            if nested:
-                return nested
-        return ""
-
-    @classmethod
-    def activity_run_row(cls, run: Dict[str, Any], *, source: str) -> Dict[str, Any]:
-        """Normalize an agent or workflow run into the Act activity-feed row shape.
-
-        Public so API routers (e.g. automation_intelligence fallback) can reuse
-        the same contract without reaching for a private method.
-
-        ``source`` is the product discriminator for the 레시피/목표 badge.
-        Legacy agent runs may lack ``agent_id`` (and both ids may be None) —
-        those rows must still leave this method with ``source="agent"`` so the
-        Act feed does not collapse every goal row into a recipe badge.
-        """
-        status = str(run.get("status") or "")
-        started_at = (
-            run.get("started_at")
-            or run.get("created_at")
-            or run.get("updated_at")
-            or ""
-        )
-        finished_at = (
-            run.get("finished_at")
-            or run.get("completed_at")
-            or run.get("resolved_at")
-            or run.get("interrupted_at")
-        )
-        run_id = run.get("id") or run.get("run_id")
-        normalized_source = str(source or "").strip().lower()
-        if normalized_source not in {"agent", "workflow"}:
-            # Infer only when the caller failed to pin a valid source; prefer
-            # workflow_id when present, otherwise agent (including bare legacy).
-            if run.get("workflow_id"):
-                normalized_source = "workflow"
-            else:
-                normalized_source = "agent"
-        return {
-            "id": run_id,
-            "source": normalized_source,
-            "title": cls.activity_run_title(run),
-            "status": status,
-            "started_at": started_at,
-            "finished_at": finished_at,
-            "can_stop": status in RUN_ACTIVE_STATUSES,
-            "can_resume": status in {"awaiting_approval", "paused", "waiting_approval"},
-            "workflow_id": run.get("workflow_id"),
-            "agent_id": run.get("agent_id"),
-        }
-
-    def mark_workflow_run_resolved(
-        self, run_id: str, *, resumed_run_id: str, approved: bool,
-        workspace_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Close out a paused run after its approval decision (one decision only)."""
-        state = self.load_state()
-        run = next((item for item in _listify(state.get("workflow_runs")) if item.get("id") == run_id), None)
-        if run is None or (workspace_id and self._record_workspace(run) != str(workspace_id)):
-            raise FileNotFoundError(run_id)
-        run["status"] = "resumed" if approved else "denied"
-        run["resolved_at"] = _now()
-        run["resumed_run_id"] = resumed_run_id
-        self.save_state(state)
-        return run
-
-    def get_workflow_run(self, run_id: str, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        run = next((item for item in _listify(self.load_state().get("workflow_runs")) if item.get("id") == run_id), None)
-        if not run or (workspace_id and self._record_workspace(run) != str(workspace_id)):
-            raise FileNotFoundError(run_id)
-        return run
-
-    def reconcile_interrupted_runs(self, *, reason: str = "server_startup") -> Dict[str, Any]:
-        """Mark durable active runs as interrupted after a process restart.
-
-        Queued/running/cancelling rows cannot have an owning asyncio task after
-        startup. Paused approval runs are intentionally left untouched so their
-        durable human decision cursor remains resumable.
-        """
-        state = self.load_state()
-        interrupted: List[Dict[str, Any]] = []
-        now = _now()
-        collections = (("agent_runs", "agent"), ("workflow_runs", "workflow"))
-        for key, area in collections:
-            for run in _listify(state.get(key)):
-                status = str(run.get("status") or "")
-                if status not in RUN_ACTIVE_STATUSES:
-                    continue
-                run["status"] = "interrupted"
-                run["interrupted_at"] = now
-                run["interrupt_reason"] = reason
-                run["updated_at"] = now
-                run.setdefault("timeline", []).append({
-                    "event": "execution_interrupted",
-                    "status": "interrupted",
-                    "reason": reason,
-                    "timestamp": now,
-                })
-                interrupted.append({
-                    "kind": area,
-                    "run_id": run.get("id"),
-                    "workspace_id": self._record_workspace(run),
-                    "previous_status": status,
-                })
-        if not interrupted:
-            return {"count": 0, "interrupted": []}
-        self.save_state(state)
-        for item in interrupted:
-            area = item["kind"]
-            run_id = item["run_id"]
-            workspace = item.get("workspace_id")
-            self._emit_execution_event(
-                area=area,
-                event_type="execution_interrupted",
-                payload={"run_id": run_id, "reason": reason, "previous_status": item.get("previous_status")},
-                workspace_id=workspace,
-            )
-        self.record_timeline_event(
-            "system",
-            "startup_reconciliation",
-            {"interrupted_runs": len(interrupted), "reason": reason},
-        )
-        return {"count": len(interrupted), "interrupted": interrupted}
-
-    @staticmethod
-    def _replay_frames(run: Dict[str, Any], *, kind: str) -> List[Dict[str, Any]]:
-        frames = []
-        for index, item in enumerate(run.get("timeline") or []):
-            event = item.get("event") or item.get("event_type") or item.get("type") or "event"
-            actor = (
-                item.get("agent_id")
-                or item.get("role")
-                or item.get("source_agent")
-                or item.get("target_agent")
-                or item.get("node")
-                or kind
-            )
-            result = item.get("result") if "result" in item else item.get("output")
-            decision = item.get("outcome") or item.get("verdict") or item.get("status")
-            frames.append({
-                "index": index,
-                "event": event,
-                "actor": actor,
-                "when": item.get("timestamp") or item.get("started_at") or run.get("created_at"),
-                "why": item.get("reason") or item.get("note") or item.get("name") or "",
-                "input": item.get("context_packet") or item.get("trigger") or run.get("input"),
-                "output": result,
-                "decision": decision,
-                "raw": item,
-            })
-        return frames
-
-    def replay_agent_run(self, run_id: str, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        run = self.get_agent_run(run_id, workspace_id=workspace_id)
-        return {
-            "kind": "agent",
-            "run_id": run_id,
-            "status": run.get("status"),
-            "workspace_id": self._record_workspace(run),
-            "contract": run.get("contract") or run_record_contract(run),
-            "replayable": True,
-            "frames": self._replay_frames(run, kind="agent"),
-            "handoffs": run.get("handoffs") or [],
-            "context_packets": run.get("context_packets") or [],
-            "review_history": run.get("review_history") or [],
-            "retry_history": run.get("retry_history") or [],
-        }
-
-    def replay_workflow_run(self, run_id: str, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        run = self.get_workflow_run(run_id, workspace_id=workspace_id)
-        return {
-            "kind": "workflow",
-            "run_id": run_id,
-            "status": run.get("status"),
-            "workspace_id": self._record_workspace(run),
-            "contract": run.get("contract") or workflow_run_contract(run),
-            "replayable": True,
-            "frames": self._replay_frames(run, kind="workflow"),
-            "outputs": run.get("outputs") or {},
-        }
-
-    def get_workflow(self, workflow_id: str, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        workflow = next((wf for wf in _listify(self.load_state().get("workflows")) if wf.get("id") == workflow_id), None)
-        if not workflow or (workspace_id and self._record_workspace(workflow) != str(workspace_id)):
-            raise FileNotFoundError(workflow_id)
-        return workflow
-
-    def update_workflow_definition(
-        self,
-        workflow_id: str,
-        *,
-        name: Optional[str] = None,
-        nodes: Optional[List[Dict[str, Any]]] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-        workspace_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        """Edit a stored workflow's node graph / name without losing its history."""
-        state = self.load_state()
-        workflow = next((wf for wf in _listify(state.get("workflows")) if wf.get("id") == workflow_id), None)
-        if not workflow or (workspace_id and self._record_workspace(workflow) != str(workspace_id)):
-            raise FileNotFoundError(workflow_id)
-        if name is not None and str(name).strip():
-            workflow["name"] = str(name).strip()
-        if nodes is not None:
-            workflow["nodes"] = nodes
-        if metadata is not None:
-            workflow["metadata"] = {**(workflow.get("metadata") or {}), **metadata}
-        workflow.setdefault("events", []).append({"type": "edited", "timestamp": _now()})
-        workflow["updated_at"] = _now()
-        self.save_state(state)
-        self.record_timeline_event("workflow", "workflow_edited", {"workflow_id": workflow_id})
-        return workflow
-
-    def list_workflows(self, query: str = "", workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        workflows = list(reversed(self._scoped(_listify(self.load_state().get("workflows")), workspace_id)))
-        q = str(query or "").lower().strip()
-        if q:
-            workflows = [
-                wf for wf in workflows
-                if q in str(wf.get("name") or "").lower()
-                or q in json.dumps(wf.get("steps") or [], ensure_ascii=False).lower()
-            ]
-        return {"workflows": workflows}
-
-    def record_workflow_event(self, workflow_id: str, event_type: str, payload: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        workflows = _listify(state.get("workflows"))
-        workflow = next((item for item in workflows if item.get("id") == workflow_id), None)
-        if not workflow:
-            raise FileNotFoundError(workflow_id)
-        event = {"type": event_type, "timestamp": _now(), "payload": payload or {}}
-        workflow.setdefault("events", []).append(event)
-        workflow["updated_at"] = _now()
-        self.save_state(state)
-        self.record_timeline_event("workflow", "workflow_event", {"workflow_id": workflow_id, "event_type": event_type})
-        return workflow