ltcai 1.6.0 → 2.0.0

package/latticeai/core/workflow_engine.py

@@ -0,0 +1,329 @@
+"""Workflow engine — typed-node workflow definitions, validation, and a
+deterministic execution interpreter with full run observability.
+
+A workflow is a small directed graph of *nodes* starting from a ``trigger``.
+Each node has a ``type`` (:data:`NODE_TYPES`), a ``config`` blob, and a ``next``
+pointer (or a list of branches for ``condition`` nodes). The engine walks the
+graph from the trigger, dispatching each node to an injected *runner* and
+recording a step-by-step timeline so a run can be inspected, replayed, and
+linked into the Workspace timeline / Knowledge Graph.
+
+The engine is pure logic with injected runners, mirroring
+:class:`latticeai.core.agent.AgentRuntime`:
+
+* production wires runners that call the real tool registry, skill registry,
+  plugin registry, and multi-agent orchestrator;
+* tests pass fakes and drive a full trigger→...→output run with no server,
+  no LLM, and no network.
+
+Backward compatibility: legacy workflows persisted as a flat ``steps`` list
+(pre-2.0) still validate and run — :func:`normalize_definition` lifts them into
+a linear node chain so existing workflow history keeps working.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Callable, Dict, List, Optional
+
+
+WORKFLOW_ENGINE_VERSION = "2.0.0"
+
+# The node vocabulary a workflow can be built from. ``trigger`` and ``output``
+# are structural; the rest dispatch to an injected runner of the same family.
+NODE_TYPES = (
+    "trigger",
+    "tool",
+    "skill",
+    "plugin",
+    "agent",
+    "condition",
+    "output",
+)
+
+# Which runner family handles each executable node type.
+_RUNNER_FOR = {
+    "tool": "tool",
+    "skill": "skill",
+    "plugin": "plugin",
+    "agent": "agent",
+}
+
+_MAX_STEPS = 100  # hard cap so a mis-wired ``next`` cycle can never hang a run.
+
+
+class WorkflowError(Exception):
+    """Raised for invalid workflow definitions."""
+
+
+def _now() -> str:
+    return datetime.now().isoformat(timespec="seconds")
+
+
+def normalize_definition(workflow: Dict[str, Any]) -> Dict[str, Any]:
+    """Return a node-based definition, lifting legacy ``steps`` lists if needed.
+
+    Never mutates the input. A legacy ``{"steps": [...]}`` workflow becomes a
+    linear ``trigger -> tool... -> output`` node chain so it validates and runs
+    under the v2.0 engine without rewriting stored history.
+    """
+    nodes = workflow.get("nodes")
+    if isinstance(nodes, list) and nodes:
+        return {
+            "id": workflow.get("id"),
+            "name": workflow.get("name") or "Untitled workflow",
+            "nodes": nodes,
+            "metadata": workflow.get("metadata") or {},
+        }
+
+    steps = workflow.get("steps") or []
+    lifted: List[Dict[str, Any]] = [{
+        "id": "trigger",
+        "type": "trigger",
+        "name": "Start",
+        "config": {"trigger": "manual"},
+        "next": "step-0" if steps else "output",
+    }]
+    for index, step in enumerate(steps):
+        action = str(step.get("action") or "tool") if isinstance(step, dict) else "tool"
+        nxt = f"step-{index + 1}" if index + 1 < len(steps) else "output"
+        lifted.append({
+            "id": f"step-{index}",
+            "type": "tool",
+            "name": action,
+            "config": {"tool": action, "args": step if isinstance(step, dict) else {"value": step}},
+            "next": nxt,
+        })
+    lifted.append({"id": "output", "type": "output", "name": "Output", "config": {}, "next": None})
+    return {
+        "id": workflow.get("id"),
+        "name": workflow.get("name") or "Untitled workflow",
+        "nodes": lifted,
+        "metadata": {**(workflow.get("metadata") or {}), "lifted_from_steps": True},
+    }
+
+
+def validate_definition(workflow: Dict[str, Any]) -> List[str]:
+    """Return a list of validation errors ([] means valid)."""
+    errors: List[str] = []
+    definition = normalize_definition(workflow)
+    nodes = definition["nodes"]
+    if not isinstance(nodes, list) or not nodes:
+        return ["workflow has no nodes"]
+
+    ids = [node.get("id") for node in nodes]
+    if len(set(ids)) != len(ids):
+        errors.append("duplicate node ids")
+    id_set = {nid for nid in ids if nid}
+
+    triggers = [node for node in nodes if node.get("type") == "trigger"]
+    if not triggers:
+        errors.append("workflow must have a trigger node")
+    elif len(triggers) > 1:
+        errors.append("workflow must have exactly one trigger node")
+
+    for node in nodes:
+        nid = node.get("id")
+        ntype = node.get("type")
+        if not nid:
+            errors.append("node missing id")
+        if ntype not in NODE_TYPES:
+            errors.append(f"node '{nid}': unknown type '{ntype}'")
+        # Validate edges point at real nodes (None terminates a branch).
+        targets: List[Any] = []
+        if ntype == "condition":
+            branches = node.get("branches") or {}
+            if not isinstance(branches, dict) or not branches:
+                errors.append(f"condition node '{nid}' must define branches (e.g. true/false)")
+            else:
+                targets.extend(branches.values())
+        else:
+            targets.append(node.get("next"))
+        for target in targets:
+            if target is not None and target not in id_set:
+                errors.append(f"node '{nid}' points at unknown node '{target}'")
+    return errors
+
+
+def _entry_node(nodes: List[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    for node in nodes:
+        if node.get("type") == "trigger":
+            return node
+    return nodes[0] if nodes else None
+
+
+def _evaluate_condition(config: Dict[str, Any], context: Dict[str, Any]) -> bool:
+    """Safe condition evaluation — NO eval. Compares a context value to a literal.
+
+    config: ``{"left": "<context key>", "op": "==|!=|>|<|>=|<=|contains|truthy",
+    "right": <literal>}``. Unknown keys / ops resolve to ``False`` so a
+    mis-configured condition fails closed onto the ``false`` branch.
+    """
+    left_key = config.get("left")
+    op = str(config.get("op") or "truthy")
+    right = config.get("right")
+    left = context.get(left_key) if left_key in context else config.get("left_value")
+    try:
+        if op == "truthy":
+            return bool(left)
+        if op == "==":
+            return left == right
+        if op == "!=":
+            return left != right
+        if op == "contains":
+            return right in left  # type: ignore[operator]
+        if op in (">", "<", ">=", "<="):
+            lf, rf = float(left), float(right)  # type: ignore[arg-type]
+            return {">": lf > rf, "<": lf < rf, ">=": lf >= rf, "<=": lf <= rf}[op]
+    except Exception:
+        return False
+    return False
+
+
+@dataclass
+class WorkflowRun:
+    workflow_id: Optional[str]
+    name: str
+    status: str = "ok"  # ok | failed | partial
+    timeline: List[Dict[str, Any]] = field(default_factory=list)
+    outputs: Dict[str, Any] = field(default_factory=dict)
+    started_at: str = field(default_factory=_now)
+    finished_at: Optional[str] = None
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "workflow_id": self.workflow_id,
+            "name": self.name,
+            "status": self.status,
+            "timeline": self.timeline,
+            "outputs": self.outputs,
+            "started_at": self.started_at,
+            "finished_at": self.finished_at,
+            "step_count": len(self.timeline),
+        }
+
+
+class WorkflowEngine:
+    """Interprets a validated workflow definition over injected runners.
+
+    ``runners`` maps a family ("tool" / "skill" / "plugin" / "agent") to a
+    callable ``runner(node, context) -> Any``. A missing runner records the
+    node as ``skipped`` with a reason rather than failing the whole run, so a
+    workflow that references a capability the host has not wired degrades
+    gracefully (and the gap is visible in the timeline).
+    """
+
+    def __init__(self, runners: Optional[Dict[str, Callable[..., Any]]] = None):
+        self.runners = runners or {}
+
+    def run(self, workflow: Dict[str, Any], *, inputs: Optional[Dict[str, Any]] = None) -> WorkflowRun:
+        definition = normalize_definition(workflow)
+        errors = validate_definition(definition)
+        run = WorkflowRun(workflow_id=definition.get("id"), name=definition.get("name") or "workflow")
+        if errors:
+            run.status = "failed"
+            run.timeline.append({"node": None, "type": "validation", "status": "failed", "errors": errors, "timestamp": _now()})
+            run.finished_at = _now()
+            return run
+
+        nodes = {node["id"]: node for node in definition["nodes"]}
+        context: Dict[str, Any] = {"inputs": inputs or {}, **(inputs or {})}
+
+        current = _entry_node(definition["nodes"])
+        steps = 0
+        had_error = False
+        had_skip = False
+        while current is not None and steps < _MAX_STEPS:
+            steps += 1
+            ntype = current.get("type")
+            nid = current.get("id")
+            entry: Dict[str, Any] = {
+                "node": nid,
+                "type": ntype,
+                "name": current.get("name") or nid,
+                "timestamp": _now(),
+            }
+
+            if ntype == "trigger":
+                entry["status"] = "ok"
+                entry["trigger"] = (current.get("config") or {}).get("trigger", "manual")
+                run.timeline.append(entry)
+                current = nodes.get(current.get("next")) if current.get("next") else None
+                continue
+
+            if ntype == "output":
+                entry["status"] = "ok"
+                payload = (current.get("config") or {}).get("value")
+                entry["output"] = payload if payload is not None else context.get("last_output")
+                run.outputs[nid] = entry["output"]
+                run.timeline.append(entry)
+                current = nodes.get(current.get("next")) if current.get("next") else None
+                continue
+
+            if ntype == "condition":
+                result = _evaluate_condition(current.get("config") or {}, context)
+                entry["status"] = "ok"
+                entry["result"] = result
+                run.timeline.append(entry)
+                branches = current.get("branches") or {}
+                target = branches.get("true" if result else "false")
+                current = nodes.get(target) if target else None
+                continue
+
+            # Executable node → dispatch to its runner family.
+            family = _RUNNER_FOR.get(ntype)
+            runner = self.runners.get(family) if family else None
+            if runner is None:
+                entry["status"] = "skipped"
+                entry["reason"] = f"no '{family}' runner configured"
+                had_skip = True
+                run.timeline.append(entry)
+                current = nodes.get(current.get("next")) if current.get("next") else None
+                continue
+            try:
+                result = runner(node=current, context=context)
+                entry["status"] = "ok"
+                entry["result"] = result
+                context["last_output"] = result
+                context[nid] = result
+            except Exception as exc:
+                entry["status"] = "error"
+                entry["reason"] = str(exc)
+                had_error = True
+            run.timeline.append(entry)
+            current = nodes.get(current.get("next")) if current.get("next") else None
+
+        if steps >= _MAX_STEPS:
+            run.timeline.append({"node": None, "type": "guard", "status": "error", "reason": f"exceeded {_MAX_STEPS} steps (cycle?)", "timestamp": _now()})
+            had_error = True
+
+        run.status = "failed" if had_error else ("partial" if had_skip else "ok")
+        run.finished_at = _now()
+        return run
+
+
+def export_workflow(workflow: Dict[str, Any]) -> Dict[str, Any]:
+    """Portable JSON representation (definition only — no run history / scope)."""
+    definition = normalize_definition(workflow)
+    return {
+        "lattice_workflow_export": WORKFLOW_ENGINE_VERSION,
+        "name": definition.get("name"),
+        "nodes": definition.get("nodes"),
+        "metadata": {k: v for k, v in (definition.get("metadata") or {}).items() if k != "lifted_from_steps"},
+    }
+
+
+def import_workflow(data: Dict[str, Any]) -> Dict[str, Any]:
+    """Validate an exported workflow and return a definition ready to persist."""
+    if not isinstance(data, dict):
+        raise WorkflowError("import payload must be a JSON object")
+    definition = {
+        "name": data.get("name") or "Imported workflow",
+        "nodes": data.get("nodes") or [],
+        "metadata": {**(data.get("metadata") or {}), "imported": True},
+    }
+    errors = validate_definition(definition)
+    if errors:
+        raise WorkflowError("; ".join(errors))
+    return definition

package/latticeai/core/workspace_os.py

@@ -18,7 +18,7 @@ from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
 
-WORKSPACE_OS_VERSION = "1.6.0"
+WORKSPACE_OS_VERSION = "2.0.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type
@@ -49,6 +49,7 @@ WORKSPACE_AREAS = [
     "memory",
     "agent",
     "workflow",
+    "plugins",
     "skills",
     "timeline",
 ]
@@ -164,7 +165,7 @@ def _parse_iso(value: Optional[str]) -> Optional[datetime]:
 class WorkspaceOSStore:
     """Local-first state store for Workspace OS APIs."""
 
-    def __init__(self, data_dir: Path | str):
+    def __init__(self, data_dir: Path | str, *, event_sink: Optional[Callable[[Dict[str, Any]], Any]] = None):
         self.data_dir = Path(data_dir).expanduser()
         self.state_path = self.data_dir / "workspace_os.json"
         self.snapshots_dir = self.data_dir / "workspace_snapshots"
@@ -172,6 +173,10 @@ class WorkspaceOSStore:
         self.data_dir.mkdir(parents=True, exist_ok=True)
         self.snapshots_dir.mkdir(parents=True, exist_ok=True)
         self.exports_dir.mkdir(parents=True, exist_ok=True)
+        # Optional realtime hook: fired on every timeline event so the Realtime
+        # bus (v2.0) receives all workspace activity without per-call wiring.
+        # Defaults to None → zero behavior change for existing callers/tests.
+        self.event_sink = event_sink
 
     @staticmethod
     def _new_workspace_record(
@@ -273,6 +278,10 @@ class WorkspaceOSStore:
                 "local_computer_memory": False,
                 "organization_workspaces": True,
                 "enterprise_seam": True,
+                "plugin_sdk": True,
+                "workflow_designer": True,
+                "multi_agent_runtime": True,
+                "realtime_collaboration": True,
             },
             "onboarding": {
                 "completed": False,
@@ -294,7 +303,9 @@ class WorkspaceOSStore:
             "agents": list(DEFAULT_AGENTS),
             "agent_runs": [],
             "workflows": [],
+            "workflow_runs": [],
             "skill_registry": {},
+            "plugin_registry": {},
             "computer_memory": {
                 "enabled": False,
                 "approved": False,
@@ -342,6 +353,12 @@ class WorkspaceOSStore:
         state.setdefault("timeline", []).append(event)
         state["timeline"] = state["timeline"][-500:]
         self.save_state(state)
+        if self.event_sink is not None:
+            try:
+                self.event_sink(event)
+            except Exception:
+                # Realtime delivery is best-effort and must never break a write.
+                pass
         return event
 
     def summary(self) -> Dict[str, Any]:
@@ -353,13 +370,16 @@ class WorkspaceOSStore:
             "workspaces": state.get("workspaces"),
             "navigation": list(WORKSPACE_AREAS),
             "feature_flags": state.get("feature_flags"),
+            "updated_at": state.get("updated_at"),
             "counts": {
                 "snapshots": len(_listify(state.get("snapshots"))),
                 "traces": len(_listify(state.get("traces"))),
                 "memories": len(_listify(state.get("memories"))),
                 "agent_runs": len(_listify(state.get("agent_runs"))),
                 "workflows": len(_listify(state.get("workflows"))),
+                "workflow_runs": len(_listify(state.get("workflow_runs"))),
                 "skills": len(state.get("skill_registry") or {}),
+                "plugins": len(state.get("plugin_registry") or {}),
                 "timeline": len(_listify(state.get("timeline"))),
             },
             "onboarding": state.get("onboarding"),
@@ -628,6 +648,7 @@ class WorkspaceOSStore:
             "memories": len(self._scoped(_listify(state.get("memories")), workspace_id)),
             "agent_runs": len(self._scoped(_listify(state.get("agent_runs")), workspace_id)),
             "workflows": len(self._scoped(_listify(state.get("workflows")), workspace_id)),
+            "workflow_runs": len(self._scoped(_listify(state.get("workflow_runs")), workspace_id)),
             "traces": len(self._scoped(_listify(state.get("traces")), workspace_id)),
             "timeline": len(self._scoped(_listify(state.get("timeline")), workspace_id)),
         }
@@ -1213,6 +1234,7 @@ class WorkspaceOSStore:
         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 = {
@@ -1226,6 +1248,10 @@ class WorkspaceOSStore:
             "created_at": _now(),
             "updated_at": _now(),
         }
+        # v2.0 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(
@@ -1244,6 +1270,93 @@ class WorkspaceOSStore:
         self.record_timeline_event("workflow", "workflow_created", {"workflow_id": workflow["id"], "name": workflow["name"]})
         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,
+    ) -> Dict[str, Any]:
+        """Persist a Workflow Designer execution into local-first run history."""
+        state = self.load_state()
+        run = {
+            "id": f"workflow-run-{_json_hash([workflow_id, name, status, _now()])[:16]}",
+            "workflow_id": workflow_id,
+            "name": name or "workflow",
+            "status": status,
+            "timeline": timeline or [],
+            "outputs": outputs or {},
+            "user_email": user_email,
+            "workspace_id": self._resolve_scope(workspace_id, state),
+            "created_at": _now(),
+        }
+        if graph is not None:
+            try:
+                ingested = graph.ingest_event(
+                    "WorkflowRun",
+                    f"{run['name']} {status}",
+                    user_email=user_email,
+                    source="workspace_os",
+                    metadata={"run_id": run["id"], "workflow_id": workflow_id, "status": status},
+                )
+                run["graph_node_id"] = ingested.get("node_id")
+            except Exception as exc:
+                run["graph_error"] = str(exc)
+        state.setdefault("workflow_runs", []).append(run)
+        state["workflow_runs"] = state["workflow_runs"][-300:]
+        # 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.record_timeline_event("workflow", "workflow_run", {"run_id": run["id"], "workflow_id": workflow_id, "status": status})
+        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 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()
@@ -1424,6 +1537,9 @@ class WorkspaceOSStore:
                     "description": desc,
                     "version": version,
                     "installed": True,
+                    "install_status": entry.get("install_status") or "ready",
+                    "validation_status": "ready" if skill_md.exists() else "missing_manifest",
+                    "source": entry.get("source") or "local",
                     "path": str(skill_dir),
                     "updated_at": entry.get("updated_at") or _now(),
                 })
@@ -1438,6 +1554,9 @@ class WorkspaceOSStore:
                 **item,
                 "enabled": bool(state_entry.get("enabled", True)),
                 "installed": bool(state_entry.get("installed")),
+                "install_status": state_entry.get("install_status") or ("ready" if state_entry.get("installed") else "available"),
+                "validation_status": state_entry.get("validation_status") or item.get("validation_status") or ("ready" if state_entry.get("installed") else "not_installed"),
+                "source": state_entry.get("source") or item.get("source") or item.get("plugin") or "marketplace",
                 "version": state_entry.get("version") or item.get("version") or "remote",
             })
         self.save_state(state)
@@ -1465,6 +1584,9 @@ class WorkspaceOSStore:
             "installed": True,
             "enabled": entry.get("enabled", True),
             "version": version,
+            "install_status": "ready",
+            "validation_status": "ready",
+            "source": (metadata or {}).get("source") or entry.get("source") or "marketplace",
             "metadata": metadata or entry.get("metadata") or {},
             "updated_at": _now(),
         })
@@ -1480,6 +1602,47 @@ class WorkspaceOSStore:
         self.record_timeline_event("skills", "skill_uninstalled", {"skill": skill})
         return entry
 
+    # ------------------------------------------------------------------
+    # Plugin SDK registry (v2.0) — mirrors the skill registry contract.
+    # ------------------------------------------------------------------
+
+    def list_plugin_registry(self) -> Dict[str, Any]:
+        return dict(self.load_state().get("plugin_registry") or {})
+
+    def set_plugin_enabled(self, plugin_id: str, enabled: bool) -> Dict[str, Any]:
+        state = self.load_state()
+        entry = state.setdefault("plugin_registry", {}).setdefault(plugin_id, {"id": plugin_id})
+        entry["enabled"] = bool(enabled)
+        entry["updated_at"] = _now()
+        self.save_state(state)
+        self.record_timeline_event("plugins", "plugin_enabled" if enabled else "plugin_disabled", {"plugin": plugin_id})
+        return entry
+
+    def mark_plugin_installed(self, plugin_id: str, *, version: str = "0.0.0", metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        state = self.load_state()
+        entry = state.setdefault("plugin_registry", {}).setdefault(plugin_id, {"id": plugin_id})
+        entry.update({
+            "id": plugin_id,
+            "installed": True,
+            "enabled": entry.get("enabled", True),
+            "version": version,
+            "install_status": "ready",
+            "validation_status": "valid",
+            "metadata": metadata or entry.get("metadata") or {},
+            "updated_at": _now(),
+        })
+        self.save_state(state)
+        self.record_timeline_event("plugins", "plugin_installed", {"plugin": plugin_id, "version": version})
+        return entry
+
+    def mark_plugin_uninstalled(self, plugin_id: str) -> Dict[str, Any]:
+        state = self.load_state()
+        entry = state.setdefault("plugin_registry", {}).setdefault(plugin_id, {"id": plugin_id})
+        entry.update({"installed": False, "enabled": False, "updated_at": _now()})
+        self.save_state(state)
+        self.record_timeline_event("plugins", "plugin_uninstalled", {"plugin": plugin_id})
+        return {"status": "ok", "plugin_id": plugin_id, "registry": entry}
+
     # ------------------------------------------------------------------
     # Audit timeline
     # ------------------------------------------------------------------