ltcai 11.5.1 → 11.6.0

package/latticeai/core/workspace_os.py

@@ -1,988 +0,0 @@
-"""Workspace OS persistence and orchestration primitives.
-
-This module keeps the 1.0 Workspace OS surface intentionally local-first:
-state is stored as JSON under the configured LatticeAI data directory, graph
-operations are additive, and snapshots are immutable files that can be
-exported or compared without mutating the live knowledge graph.
-"""
-
-from __future__ import annotations
-
-import json
-import shutil
-import sqlite3
-from contextlib import contextmanager
-from pathlib import Path
-from typing import Any, Callable, Dict, Iterable, Iterator, List, Optional
-
-from latticeai.core.quiet import quiet
-
-from .timeutil import now_iso as _now
-from .workspace_computer_memory import WorkspaceComputerMemory
-from .workspace_graph_trace import WorkspaceGraphTrace
-from .workspace_indexing import WorkspaceIndexing
-from .workspace_memory import WorkspaceMemory
-from .workspace_onboarding import WorkspaceOnboarding
-from .workspace_os_constants import (
-    DEFAULT_WORKSPACE_ID,
-    EXECUTION_EVENT_TYPES,
-    MEMORY_KINDS,
-    ONBOARDING_STEPS,
-    ROLE_PERMISSIONS,
-    WORKSPACE_AREAS,
-    WORKSPACE_OS_VERSION,
-    WORKSPACE_PERMISSIONS,
-    WORKSPACE_ROLES,
-    WORKSPACE_TYPES,
-)
-from .workspace_os_state import default_state, migrate_workspaces, new_workspace_record
-
-# Extracted pure helpers (keeps this module smaller and focused on the store).
-from .workspace_os_utils import (
-    _atomic_write_json,
-    _deep_merge,
-    _json_hash,
-    _listify,
-    _safe_slug,
-    remove_skill_directory,
-)
-from .workspace_permissions import (  # type: ignore
-    WorkspacePermissionManager,
-    _member_role,
-)
-from .workspace_plugins import WorkspacePluginManager
-from .workspace_relationships import WorkspaceRelationships
-from .workspace_relationships import shortest_path as _shortest_path
-from .workspace_reorganization import plan_reorganization
-from .workspace_review_items import WorkspaceReviewItems
-from .workspace_runs import WorkspaceRuns
-from .workspace_skills import WorkspaceSkills
-from .workspace_snapshots import WorkspaceSnapshots
-from .workspace_timeline import WorkspaceTimeline
-
-__all__ = [
-    "WORKSPACE_OS_VERSION",
-    "WORKSPACE_TYPES",
-    "DEFAULT_WORKSPACE_ID",
-    "WORKSPACE_ROLES",
-    "WORKSPACE_PERMISSIONS",
-    "ROLE_PERMISSIONS",
-    "WORKSPACE_AREAS",
-    "ONBOARDING_STEPS",
-    "MEMORY_KINDS",
-    "EXECUTION_EVENT_TYPES",
-    "WorkspaceOSStore",
-    "remove_skill_directory",
-]
-
-
-
-
-
-
-
-
-
-
-
-
-
-class WorkspaceOSStore:
-    """Local-first state store for Workspace OS APIs."""
-
-    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.sqlite_path = self.data_dir / "knowledge_graph.sqlite"
-        self.snapshots_dir = self.data_dir / "workspace_snapshots"
-        self.exports_dir = self.data_dir / "workspace_exports"
-        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 receives all workspace activity without per-call wiring.
-        # Defaults to None → zero behavior change for existing callers/tests.
-        self.event_sink = event_sink
-        # Composed managers (extracted to shrink god class per architecture rules).
-        self.permissions = WorkspacePermissionManager(self)
-        self._timeline = WorkspaceTimeline(self)
-        self.plugins = WorkspacePluginManager(self)
-        self.memory = WorkspaceMemory(self)
-        self.snapshots = WorkspaceSnapshots(self)
-        self.graph_trace = WorkspaceGraphTrace(self)
-        self.runs = WorkspaceRuns(self)
-        self.review_items = WorkspaceReviewItems(self)
-        self.skills = WorkspaceSkills(self)
-        self.indexing = WorkspaceIndexing(self)
-        self.relationships = WorkspaceRelationships(self)
-        self.computer_memory = WorkspaceComputerMemory(self)
-        self.onboarding = WorkspaceOnboarding(self)
-
-    @contextmanager
-    def _connect_state_db(self) -> Iterator[sqlite3.Connection]:
-        """Transactional connection that is closed when the block exits.
-
-        ``with sqlite3.connect(...)`` commits but never closes; see
-        :meth:`lattice_brain.storage.base.StorageEngine.session`.
-        """
-        conn = sqlite3.connect(self.sqlite_path)
-        conn.execute("PRAGMA journal_mode=WAL")
-        conn.execute(
-            "CREATE TABLE IF NOT EXISTS workspace_os_state ("
-            "id TEXT PRIMARY KEY, state_json TEXT NOT NULL, updated_at TEXT NOT NULL)"
-        )
-        conn.execute(
-            "CREATE TABLE IF NOT EXISTS workspace_os_meta ("
-            "key TEXT PRIMARY KEY, value TEXT NOT NULL)"
-        )
-        try:
-            with conn:
-                yield conn
-        finally:
-            conn.close()
-
-    # ── moved to workspace_os_state.py (10.2.0) ───────────────────────────────
-    # Kept as delegators: `_default_state` and `_migrate_workspaces` are called
-    # by name in tests and by subclasses, and `_new_workspace_record` is used
-    # across the manager classes. The behaviour lives in one place now; these
-    # keep every existing call site working.
-    @staticmethod
-    def _new_workspace_record(**kwargs) -> Dict[str, Any]:
-        return new_workspace_record(**kwargs)
-
-    def _migrate_workspaces(self, state: Dict[str, Any]) -> Dict[str, Any]:
-        return migrate_workspaces(state)
-
-    def _default_state(self) -> Dict[str, Any]:
-        return default_state()
-
-    def _load_sqlite_state(self) -> Optional[Dict[str, Any]]:
-        try:
-            with self._connect_state_db() as conn:
-                row = conn.execute(
-                    "SELECT state_json FROM workspace_os_state WHERE id='current'"
-                ).fetchone()
-            if not row:
-                return None
-            data = json.loads(row[0])
-            return data if isinstance(data, dict) else None
-        except Exception:
-            return None
-
-    def _save_sqlite_state(self, state: Dict[str, Any]) -> None:
-        payload = json.dumps(state, ensure_ascii=False)
-        with self._connect_state_db() as conn:
-            conn.execute(
-                "INSERT OR REPLACE INTO workspace_os_state(id, state_json, updated_at) VALUES('current', ?, ?)",
-                (payload, state.get("updated_at") or _now()),
-            )
-
-    def _import_json_state_once(self, default: Dict[str, Any]) -> Dict[str, Any]:
-        if not self.state_path.exists():
-            return default
-        try:
-            loaded = json.loads(self.state_path.read_text(encoding="utf-8"))
-            if not isinstance(loaded, dict):
-                return default
-        except Exception:
-            return default
-        try:
-            backup = self.state_path.with_name(
-                f"{self.state_path.name}.pre-sqlite.{_now().replace(':', '-')}.json"
-            )
-            if not any(self.state_path.parent.glob(f"{self.state_path.name}.pre-sqlite.*.json")):
-                shutil.copy2(self.state_path, backup)
-        except Exception:
-            quiet()
-        return _deep_merge(default, loaded)
-
-
-
-    def migrate_workspace_identities(self, email_to_id: Dict[str, str]) -> int:
-        """Rewrite workspace membership identities from legacy emails to UUIDs.
-
-        The migration is additive and in-place: workspace records, memberships,
-        and owner fields keep their shape, only identity string values change.
-        """
-        if not email_to_id:
-            return 0
-        normalized = {str(email).strip().lower(): user_id for email, user_id in email_to_id.items() if user_id}
-        state = self.load_state()
-        changed = 0
-        for ws in (state.get("workspaces") or {}).values():
-            owner = str(ws.get("owner_user_id") or "").strip().lower()
-            if owner in normalized and ws.get("owner_user_id") != normalized[owner]:
-                ws["owner_user_id"] = normalized[owner]
-                changed += 1
-            for member in _listify(ws.get("members")):
-                member_id = str(member.get("user_id") or "").strip().lower()
-                if member_id in normalized and member.get("user_id") != normalized[member_id]:
-                    member["user_id"] = normalized[member_id]
-                    member["updated_at"] = _now()
-                    changed += 1
-            members = _listify(ws.get("members"))
-            deduped = []
-            seen_members = set()
-            for member in members:
-                member_id = member.get("user_id")
-                if member_id and member_id in seen_members:
-                    changed += 1
-                    continue
-                if member_id:
-                    seen_members.add(member_id)
-                deduped.append(member)
-            if len(deduped) != len(members):
-                ws["members"] = deduped
-        if changed:
-            state["updated_at"] = _now()
-            self.save_state(state)
-            self.record_timeline_event("workspace", "identity_uuid_migrated", {"records": changed})
-        return changed
-
-
-    def load_state(self) -> Dict[str, Any]:
-        default = self._default_state()
-        loaded = self._load_sqlite_state()
-        imported = loaded is None
-        if loaded is None:
-            loaded = self._import_json_state_once(default)
-        state = _deep_merge(default, loaded)
-        state["version"] = WORKSPACE_OS_VERSION
-        self._migrate_workspaces(state)
-        if imported:
-            self.save_state(state)
-        return state
-
-    def save_state(self, state: Dict[str, Any]) -> Dict[str, Any]:
-        state["version"] = WORKSPACE_OS_VERSION
-        state["updated_at"] = _now()
-        self._save_sqlite_state(state)
-        _atomic_write_json(self.state_path, state)
-        return state
-
-    def record_timeline_event(self, area: str, event_type: str, payload: Dict[str, Any], workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        return self._timeline.record_timeline_event(area, event_type, payload, workspace_id=workspace_id)
-
-    def _emit_execution_event(
-        self,
-        *,
-        area: str,
-        event_type: str,
-        payload: Dict[str, Any],
-        workspace_id: Optional[str],
-    ) -> None:
-        """Best-effort execution observability event for the realtime feed."""
-        if event_type not in EXECUTION_EVENT_TYPES:
-            return
-        try:
-            self.record_timeline_event(area, event_type, payload, workspace_id=workspace_id)
-        except Exception:
-            quiet()
-
-    def _emit_replayable_timeline_events(
-        self,
-        *,
-        area: str,
-        run_id: str,
-        timeline: List[Dict[str, Any]],
-        workspace_id: Optional[str],
-    ) -> None:
-        for index, item in enumerate(timeline or []):
-            event_type = item.get("event") or item.get("event_type")
-            if event_type in EXECUTION_EVENT_TYPES:
-                payload = {k: v for k, v in item.items() if k not in {"context_packet"}}
-                payload["run_id"] = run_id
-                payload["timeline_index"] = index
-                self._emit_execution_event(area=area, event_type=event_type, payload=payload, workspace_id=workspace_id)
-
-    def summary(self) -> Dict[str, Any]:
-        state = self.load_state()
-        return {
-            "version": WORKSPACE_OS_VERSION,
-            "identity": state.get("identity"),
-            "active_workspace": state.get("active_workspace"),
-            # The raw workspace registry (with member lists) must not leak to
-            # non-members; WorkspaceService.summary() adds a membership-filtered
-            # "workspace_registry" instead.
-            "workspace_count": len(state.get("workspaces") or {}),
-            "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"))),
-                "memory_snapshots": len(_listify(state.get("memory_snapshots"))),
-                "agent_runs": len(_listify(state.get("agent_runs"))),
-                "handoffs": len(_listify(state.get("handoffs"))),
-                "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 {}),
-                "templates": len(state.get("template_registry") or {}),
-                "timeline": len(_listify(state.get("timeline"))),
-            },
-            "onboarding": state.get("onboarding"),
-            "storage": {
-                "state_path": str(self.state_path),
-                "snapshots_dir": str(self.snapshots_dir),
-                "exports_dir": str(self.exports_dir),
-            },
-        }
-
-    # ------------------------------------------------------------------
-    # Organization workspaces, membership, and roles
-    # ------------------------------------------------------------------
-
-    def _active_workspace_id(self, state: Optional[Dict[str, Any]] = None) -> str:
-        state = state or self.load_state()
-        active = state.get("active_workspace") or DEFAULT_WORKSPACE_ID
-        if active not in (state.get("workspaces") or {}):
-            return DEFAULT_WORKSPACE_ID
-        return active
-
-    def _resolve_scope(self, workspace_id: Optional[str], state: Optional[Dict[str, Any]] = None) -> str:
-        """Resolve the workspace a write should be tagged with.
-
-        ``None`` falls back to the active workspace (Personal by default), so
-        legacy callers keep writing to the Personal workspace unchanged.
-        """
-        if workspace_id:
-            return str(workspace_id)
-        return self._active_workspace_id(state)
-
-    @staticmethod
-    def _record_workspace(record: Dict[str, Any]) -> str:
-        """Workspace a stored record belongs to (legacy records map to Personal)."""
-        return str(record.get("workspace_id") or DEFAULT_WORKSPACE_ID)
-
-    def _scoped(self, records: List[Dict[str, Any]], workspace_id: Optional[str]) -> List[Dict[str, Any]]:
-        if not workspace_id:
-            return records
-        target = str(workspace_id)
-        return [item for item in records if self._record_workspace(item) == target]
-
-    def list_workspaces(self, user_id: Optional[str] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        workspaces = state.get("workspaces") or {}
-        items = []
-        for ws in workspaces.values():
-            if user_id and ws.get("type") == "organization":
-                role = self._member_role(ws, user_id)
-                if role is None:
-                    continue
-            items.append(self._workspace_public(ws, user_id))
-        items.sort(key=lambda w: (w.get("type") != "personal", w.get("created_at") or ""))
-        return {
-            "active_workspace": self._active_workspace_id(state),
-            "workspaces": items,
-            "roles": list(WORKSPACE_ROLES),
-            "permissions": {role: sorted(perms) for role, perms in ROLE_PERMISSIONS.items()},
-        }
-
-    def _workspace_public(self, ws: Dict[str, Any], user_id: Optional[str] = None) -> Dict[str, Any]:
-        return {
-            "workspace_id": ws.get("workspace_id") or ws.get("id"),
-            "id": ws.get("workspace_id") or ws.get("id"),
-            "name": ws.get("name"),
-            "type": ws.get("type"),
-            "owner_user_id": ws.get("owner_user_id"),
-            "status": ws.get("status", "active"),
-            "member_count": len(_listify(ws.get("members"))),
-            "members": _listify(ws.get("members")),
-            "settings": ws.get("settings") or {},
-            "created_at": ws.get("created_at"),
-            "updated_at": ws.get("updated_at"),
-            "your_role": self._member_role(ws, user_id) if user_id else ("owner" if ws.get("type") == "personal" else None),
-        }
-
-    def get_workspace(self, workspace_id: str, user_id: Optional[str] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        ws = (state.get("workspaces") or {}).get(workspace_id)
-        if not ws:
-            raise FileNotFoundError(workspace_id)
-        return self._workspace_public(ws, user_id)
-
-    def create_organization_workspace(
-        self,
-        *,
-        name: str,
-        owner_user_id: Optional[str],
-        settings: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        if not str(name or "").strip():
-            raise ValueError("workspace name is required")
-        state = self.load_state()
-        workspaces = state.setdefault("workspaces", {})
-        base = _safe_slug(f"org-{name}")
-        workspace_id = base
-        suffix = 2
-        while workspace_id in workspaces:
-            workspace_id = f"{base}-{suffix}"
-            suffix += 1
-        record = self._new_workspace_record(
-            workspace_id=workspace_id,
-            name=name.strip(),
-            workspace_type="organization",
-            owner_user_id=owner_user_id,
-            settings=settings or {},
-        )
-        workspaces[workspace_id] = record
-        self.save_state(state)
-        self.record_timeline_event("workspace", "workspace_created", {"workspace_id": workspace_id, "type": "organization"})
-        return self._workspace_public(record, owner_user_id)
-
-    @staticmethod
-    def _member_role(ws: Dict[str, Any], user_id: Optional[str]) -> Optional[str]:
-        # Delegated to extracted module (kept for any internal direct calls).
-        return _member_role(ws, user_id)
-
-    def get_member_role(self, workspace_id: str, user_id: Optional[str]) -> Optional[str]:
-        return self.permissions.get_member_role(workspace_id, user_id)
-
-    def has_permission(self, workspace_id: str, user_id: Optional[str], permission: str) -> bool:
-        return self.permissions.has_permission(workspace_id, user_id, permission)
-
-    def _require_permission(self, ws: Dict[str, Any], actor: Optional[str], permission: str) -> None:
-        self.permissions.require_permission(ws, actor, permission)
-
-    def _load_org(self, state: Dict[str, Any], workspace_id: str) -> Dict[str, Any]:
-        ws = (state.get("workspaces") or {}).get(workspace_id)
-        if not ws:
-            raise FileNotFoundError(workspace_id)
-        if ws.get("type") != "organization":
-            raise ValueError("operation only valid for organization workspaces")
-        return ws
-
-    def update_workspace(
-        self,
-        workspace_id: str,
-        *,
-        name: Optional[str] = None,
-        settings: Optional[Dict[str, Any]] = None,
-        actor: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        state = self.load_state()
-        ws = self._load_org(state, workspace_id)
-        self._require_permission(ws, actor, "manage_workspace")
-        if name is not None and str(name).strip():
-            ws["name"] = str(name).strip()
-        if settings is not None:
-            ws["settings"] = {**(ws.get("settings") or {}), **settings}
-        ws["updated_at"] = _now()
-        self.save_state(state)
-        self.record_timeline_event("workspace", "workspace_updated", {"workspace_id": workspace_id})
-        return self._workspace_public(ws, actor)
-
-    def archive_workspace(self, workspace_id: str, *, actor: Optional[str] = None) -> Dict[str, Any]:
-        """Soft-archive an organization workspace. Data is never deleted."""
-        state = self.load_state()
-        ws = self._load_org(state, workspace_id)
-        self._require_permission(ws, actor, "manage_workspace")
-        ws["status"] = "archived"
-        ws["updated_at"] = _now()
-        if state.get("active_workspace") == workspace_id:
-            state["active_workspace"] = DEFAULT_WORKSPACE_ID
-        self.save_state(state)
-        self.record_timeline_event("workspace", "workspace_archived", {"workspace_id": workspace_id})
-        return self._workspace_public(ws, actor)
-
-    def add_member(self, workspace_id: str, *, user_id: str, role: str = "member", actor: Optional[str] = None) -> Dict[str, Any]:
-        return self.permissions.add_member(workspace_id, user_id=user_id, role=role, actor=actor)
-
-    def update_member_role(self, workspace_id: str, *, user_id: str, role: str, actor: Optional[str] = None) -> Dict[str, Any]:
-        # delegate or keep simple for now (full impl in permissions if expanded)
-        if role not in WORKSPACE_ROLES:
-            raise ValueError(f"unknown role: {role}")
-        state = self.load_state()
-        ws = self._load_org(state, workspace_id)
-        self._require_permission(ws, actor, "manage_members")
-        if user_id == ws.get("owner_user_id") and role != "owner":
-            raise ValueError("cannot demote the workspace owner")
-        member = next((m for m in _listify(ws.get("members")) if m.get("user_id") == user_id), None)
-        if not member:
-            raise FileNotFoundError(user_id)
-        member["role"] = role
-        member["updated_at"] = _now()
-        ws["updated_at"] = _now()
-        self.save_state(state)
-        self.record_timeline_event("workspace", "member_role_updated", {"workspace_id": workspace_id, "user_id": user_id, "role": role})
-        return self._workspace_public(ws, actor)
-
-    def remove_member(self, workspace_id: str, *, user_id: str, actor: Optional[str] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        ws = self._load_org(state, workspace_id)
-        self._require_permission(ws, actor, "manage_members")
-        if user_id == ws.get("owner_user_id"):
-            raise ValueError("cannot remove the workspace owner")
-        members = _listify(ws.get("members"))
-        kept = [m for m in members if m.get("user_id") != user_id]
-        if len(kept) == len(members):
-            raise FileNotFoundError(user_id)
-        ws["members"] = kept
-        ws["updated_at"] = _now()
-        self.save_state(state)
-        self.record_timeline_event("workspace", "member_removed", {"workspace_id": workspace_id, "user_id": user_id})
-        return self._workspace_public(ws, actor)
-
-    def set_active_workspace(self, workspace_id: str, user_id: Optional[str] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        ws = (state.get("workspaces") or {}).get(workspace_id)
-        if not ws:
-            raise FileNotFoundError(workspace_id)
-        if ws.get("type") == "organization" and self._member_role(ws, user_id) is None:
-            raise PermissionError(f"'{user_id or 'anonymous'}' is not a member of '{workspace_id}'")
-        state["active_workspace"] = workspace_id
-        self.save_state(state)
-        self.record_timeline_event("workspace", "workspace_activated", {"workspace_id": workspace_id})
-        return self._workspace_public(ws, user_id)
-
-    def workspace_summary(self, workspace_id: str, user_id: Optional[str] = None) -> Dict[str, Any]:
-        state = self.load_state()
-        ws = (state.get("workspaces") or {}).get(workspace_id)
-        if not ws:
-            raise FileNotFoundError(workspace_id)
-        public = self._workspace_public(ws, user_id)
-        public["counts"] = {
-            "snapshots": len(self._scoped(_listify(state.get("snapshots")), workspace_id)),
-            "memories": len(self._scoped(_listify(state.get("memories")), workspace_id)),
-            "memory_snapshots": len(self._scoped(_listify(state.get("memory_snapshots")), workspace_id)),
-            "agent_runs": len(self._scoped(_listify(state.get("agent_runs")), workspace_id)),
-            "handoffs": len(self._scoped(_listify(state.get("handoffs")), 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)),
-        }
-        return public
-
-    # ------------------------------------------------------------------
-    # Onboarding
-    # ------------------------------------------------------------------
-
-    def onboarding_status(self, users: Optional[Dict[str, Any]] = None, graph_stats: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        return self.onboarding.status(users=users, graph_stats=graph_stats)
-
-    def update_onboarding_step(
-        self,
-        step: str,
-        *,
-        status: str = "complete",
-        data: Optional[Dict[str, Any]] = None,
-        error: str = "",
-        user_email: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        return self.onboarding.update_step(
-            step, status=status, data=data, error=error, user_email=user_email
-        )
-
-    def complete_onboarding(self, data: Optional[Dict[str, Any]] = None, user_email: Optional[str] = None) -> Dict[str, Any]:
-        return self.onboarding.complete(data=data, user_email=user_email)
-
-    # ------------------------------------------------------------------
-    # Graph answer traces
-    # ------------------------------------------------------------------
-
-    def build_graph_trace(
-        self,
-        question: str,
-        graph: Any,
-        context: str = "",
-        *,
-        limit: int = 8,
-        allowed_workspaces=None,
-    ) -> Dict[str, Any]:
-        return self.graph_trace.build_graph_trace(
-            question,
-            graph,
-            context,
-            limit=limit,
-            allowed_workspaces=allowed_workspaces,
-        )
-
-    def record_trace(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.graph_trace.record_trace(*args, **kwargs)
-
-    def list_traces(self, conversation_id: Optional[str] = None, limit: int = 50, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        return self.graph_trace.list_traces(conversation_id=conversation_id, limit=limit, workspace_id=workspace_id)
-
-    # ------------------------------------------------------------------
-    # Indexing dashboard
-    # ------------------------------------------------------------------
-
-    def build_indexing_dashboard(self, graph: Any, watcher_status: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        return self.indexing.build_dashboard(graph, watcher_status)
-
-    def pause_indexing(self, graph: Any, source_id: str, watcher: Any = None) -> Dict[str, Any]:
-        return self.indexing.pause(graph, source_id, watcher)
-
-    def resume_indexing(self, graph: Any, source_id: str, watcher: Any = None) -> Dict[str, Any]:
-        return self.indexing.resume(graph, source_id, watcher)
-
-    def remove_index_source(self, graph: Any, source_id: str, watcher: Any = None) -> Dict[str, Any]:
-        return self.indexing.remove_source(graph, source_id, watcher)
-
-    # ------------------------------------------------------------------
-    # Snapshots, Time Machine, and diffs
-    # ------------------------------------------------------------------
-
-    def create_snapshot(
-        self,
-        *,
-        name: str,
-        graph: Any,
-        history: Iterable[Dict[str, Any]],
-        settings: Dict[str, Any],
-        models: Dict[str, Any],
-        workspace_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        return self.snapshots.create_snapshot(name=name, graph=graph, history=history, settings=settings, models=models, workspace_id=workspace_id)
-
-    def list_snapshots(self, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        return self.snapshots.list_snapshots(workspace_id=workspace_id)
-
-    def get_snapshot(self, snapshot_id: str) -> Dict[str, Any]:
-        return self.snapshots.get_snapshot(snapshot_id)
-
-    def snapshot_view(self, snapshot_id: str, area: str) -> Dict[str, Any]:
-        return self.snapshots.snapshot_view(snapshot_id, area)
-
-    def export_snapshot(self, snapshot_id: str) -> Dict[str, Any]:
-        return self.snapshots.export_snapshot(snapshot_id)
-
-    def restore_snapshot(
-        self,
-        snapshot_id: str,
-        *,
-        graph: Any,
-        workspace_id: Optional[str] = None,
-        user_email: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        return self.snapshots.restore_snapshot(snapshot_id, graph=graph, workspace_id=workspace_id, user_email=user_email)
-
-    def compare_snapshots(self, before_id: str, after_id: str) -> Dict[str, Any]:
-        return self.snapshots.compare_snapshots(before_id, after_id)
-
-    # ------------------------------------------------------------------
-    # Personal memory
-    # ------------------------------------------------------------------
-
-    def upsert_memory(
-        self,
-        *,
-        kind: str,
-        content: str,
-        user_email: Optional[str],
-        tags: Optional[List[str]] = None,
-        memory_id: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-        graph: Any = None,
-        workspace_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        return self.memory.upsert_memory(
-            kind=kind, content=content, user_email=user_email, tags=tags,
-            memory_id=memory_id, metadata=metadata, graph=graph, workspace_id=workspace_id
-        )
-
-    def list_memories(self, user_email: Optional[str] = None, kind: Optional[str] = None, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        return self.memory.list_memories(user_email=user_email, kind=kind, workspace_id=workspace_id)
-
-    def search_memories(self, query: str, user_email: Optional[str] = None, limit: int = 20, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        q = str(query or "").lower().strip()
-        memories = self.list_memories(user_email=user_email, workspace_id=workspace_id).get("memories", [])
-        if q:
-            memories = [
-                item for item in memories
-                if q in str(item.get("content") or "").lower()
-                or q in " ".join(item.get("tags") or []).lower()
-                or q in str(item.get("kind") or "").lower()
-            ]
-        return {"query": query, "memories": memories[: max(1, min(limit, 100))]}
-
-    def get_memory(self, memory_id: str) -> Dict[str, Any]:
-        record = next(
-            (item for item in _listify(self.load_state().get("memories")) if item.get("id") == memory_id),
-            None,
-        )
-        if record is None:
-            raise FileNotFoundError(memory_id)
-        return record
-
-    def delete_memory(self, memory_id: str) -> Dict[str, Any]:
-        state = self.load_state()
-        memories = _listify(state.get("memories"))
-        target = next((item for item in memories if item.get("id") == memory_id), None)
-        if target is None:
-            raise FileNotFoundError(memory_id)
-        state["memories"] = [item for item in memories if item.get("id") != memory_id]
-        self.save_state(state)
-        self.record_timeline_event(
-            "memory", "memory_deleted", {"memory_id": memory_id}, workspace_id=target.get("workspace_id")
-        )
-        return {"status": "ok", "memory_id": memory_id}
-
-    def create_memory_snapshot(
-        self,
-        *,
-        label: str = "memory snapshot",
-        user_email: Optional[str] = None,
-        workspace_id: Optional[str] = None,
-        memory_ids: Optional[List[str]] = None,
-        reason: str = "",
-    ) -> Dict[str, Any]:
-        """Persist a replayable point-in-time memory view without mutation."""
-        state = self.load_state()
-        scope = self._resolve_scope(workspace_id, state)
-        memories = self._scoped(_listify(state.get("memories")), scope)
-        if user_email:
-            memories = [item for item in memories if item.get("user_email") in {None, user_email}]
-        if memory_ids:
-            allowed = set(memory_ids)
-            memories = [item for item in memories if item.get("id") in allowed]
-        snapshot = {
-            "id": f"memory-snapshot-{_json_hash([label, scope, memories, _now()])[:16]}",
-            "label": label,
-            "reason": reason,
-            "workspace_id": scope,
-            "user_email": user_email,
-            "memory_count": len(memories),
-            "memories": memories,
-            "created_at": _now(),
-        }
-        state.setdefault("memory_snapshots", []).append(snapshot)
-        self.save_state(state)
-        self.record_timeline_event("memory", "memory_snapshot", {"snapshot_id": snapshot["id"], "memory_count": len(memories)}, workspace_id=scope)
-        return snapshot
-
-    def list_memory_snapshots(self, workspace_id: Optional[str] = None, limit: int = 50) -> Dict[str, Any]:
-        snapshots = self._scoped(_listify(self.load_state().get("memory_snapshots")), workspace_id)
-        return {"snapshots": list(reversed(snapshots[-max(1, min(limit, 200)):]))}
-
-    # ------------------------------------------------------------------
-    # Agent and workflow graph
-    # ------------------------------------------------------------------
-
-    def list_agents(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.list_agents(*args, **kwargs)
-
-    def record_agent_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.record_agent_run(*args, **kwargs)
-
-    def update_agent_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.update_agent_run(*args, **kwargs)
-
-    def get_agent_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.get_agent_run(*args, **kwargs)
-
-    def list_handoffs(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.list_handoffs(*args, **kwargs)
-
-    def create_workflow(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.create_workflow(*args, **kwargs)
-
-    def record_workflow_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.record_workflow_run(*args, **kwargs)
-
-    def update_workflow_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.update_workflow_run(*args, **kwargs)
-
-    def list_workflow_runs(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.list_workflow_runs(*args, **kwargs)
-
-    def list_combined_runs(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.list_combined_runs(*args, **kwargs)
-
-    def mark_workflow_run_resolved(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.mark_workflow_run_resolved(*args, **kwargs)
-
-    def get_workflow_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.get_workflow_run(*args, **kwargs)
-
-    def reconcile_interrupted_runs(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.reconcile_interrupted_runs(*args, **kwargs)
-
-    @staticmethod
-    def _replay_frames(run: Dict[str, Any], *, kind: str) -> List[Dict[str, Any]]:
-        return WorkspaceRuns._replay_frames(run, kind=kind)
-
-    def replay_agent_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.replay_agent_run(*args, **kwargs)
-
-    def replay_workflow_run(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.replay_workflow_run(*args, **kwargs)
-
-    def get_workflow(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.get_workflow(*args, **kwargs)
-
-    def update_workflow_definition(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.update_workflow_definition(*args, **kwargs)
-
-    def list_workflows(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.list_workflows(*args, **kwargs)
-
-    def record_workflow_event(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.runs.record_workflow_event(*args, **kwargs)
-
-    # ── review queue (5.6.0) ─────────────────────────────────────────────
-    # Workspace-scoped suggestion inbox. Persistence moved to
-    # ``workspace_review_items.WorkspaceReviewItems`` (v9.9.6); the transition
-    # policy still lives in ReviewQueueService (services/review_queue.py).
-
-    def create_review_item(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.review_items.create_review_item(*args, **kwargs)
-
-    def list_review_items(self, *args: Any, **kwargs: Any) -> List[Dict[str, Any]]:
-        return self.review_items.list_review_items(*args, **kwargs)
-
-    def get_review_item(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.review_items.get_review_item(*args, **kwargs)
-
-    def update_review_item(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.review_items.update_review_item(*args, **kwargs)
-
-    # ------------------------------------------------------------------
-    # Agent-native workspace: folder reorganization (v11.1.0)
-    # ------------------------------------------------------------------
-
-    def preview_reorganization(
-        self, *, root: str = "", resolve_path: Callable[[str], Any], graph: Any = None,
-        max_moves: int = 20,
-    ) -> Dict[str, Any]:
-        """What a reorganization would do — read-only, nothing is staged."""
-        return plan_reorganization(
-            root=root, resolve_path=resolve_path, graph=graph, max_moves=max_moves
-        )
-
-    def propose_reorganization(
-        self, *, root: str = "", change_proposals: Any, graph: Any = None,
-        user_email: Optional[str] = None, workspace_id: Optional[str] = None,
-        max_moves: int = 20,
-    ) -> Dict[str, Any]:
-        """Stage a folder reorganization for review and record it on the timeline.
-
-        The staging itself belongs to ``ChangeProposalService`` (one apply path
-        for every staged change); this seam exists so a long-running agent
-        session asking the Workspace OS to tidy a project leaves a trace of
-        having asked, whether or not there was anything to propose.
-        """
-        result = change_proposals.propose_reorganization(
-            root=root, graph=graph, user_email=user_email,
-            workspace_id=workspace_id, max_moves=max_moves,
-        )
-        proposed = result.get("proposed") or {}
-        self.record_timeline_event(
-            "workspace",
-            "workspace_reorg_proposed",
-            {
-                "root": root,
-                "moves": (result.get("plan") or {}).get("move_count", 0),
-                "proposal_id": proposed.get("id"),
-            },
-            workspace_id=workspace_id,
-        )
-        return result
-
-    # ------------------------------------------------------------------
-    # Relationship explorer
-    # ------------------------------------------------------------------
-
-    def relationship_explorer(self, graph: Any, node_id: str, target_id: Optional[str] = None, limit: int = 500) -> Dict[str, Any]:
-        return self.relationships.explore(graph, node_id, target_id=target_id, limit=limit)
-
-    @staticmethod
-    def _shortest_path(edges: List[Dict[str, Any]], start: str, target: Optional[str]) -> List[str]:
-        return _shortest_path(edges, start, target)
-
-    # ------------------------------------------------------------------
-    # Local Computer Memory
-    # ------------------------------------------------------------------
-
-    def configure_computer_memory(
-        self,
-        *,
-        enabled: bool,
-        approved_by: Optional[str],
-        consent: Optional[Dict[str, Any]] = None,
-        scopes: Optional[List[str]] = None,
-    ) -> Dict[str, Any]:
-        return self.computer_memory.configure(
-            enabled=enabled, approved_by=approved_by, consent=consent, scopes=scopes
-        )
-
-    def record_computer_activity(self, activity: Dict[str, Any], graph: Any = None) -> Dict[str, Any]:
-        return self.computer_memory.record_activity(activity, graph)
-
-    # ------------------------------------------------------------------
-    # Skills
-    # ------------------------------------------------------------------
-
-    def list_skill_registry(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.skills.list_skill_registry(*args, **kwargs)
-
-    def set_skill_enabled(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.skills.set_skill_enabled(*args, **kwargs)
-
-    def mark_skill_installed(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.skills.mark_skill_installed(*args, **kwargs)
-
-    def mark_skill_uninstalled(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
-        return self.skills.mark_skill_uninstalled(*args, **kwargs)
-
-    # ------------------------------------------------------------------
-    # Plugin SDK registry — mirrors the skill registry contract.
-    # ------------------------------------------------------------------
-
-    def list_plugin_registry(self) -> Dict[str, Any]:
-        return self.plugins.list_plugin_registry()
-
-    def set_plugin_enabled(self, plugin_id: str, enabled: bool) -> Dict[str, Any]:
-        return self.plugins.set_plugin_enabled(plugin_id, enabled)
-
-    def mark_plugin_installed(self, plugin_id: str, *, version: str = "0.0.0", metadata: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        return self.plugins.mark_plugin_installed(plugin_id, version=version, metadata=metadata)
-
-    def mark_plugin_uninstalled(self, plugin_id: str) -> Dict[str, Any]:
-        return self.plugins.mark_plugin_uninstalled(plugin_id)
-
-    # ------------------------------------------------------------------
-    # Marketplace template registry (v2.1 foundation)
-    # ------------------------------------------------------------------
-
-    @staticmethod
-    def _template_registry_key(kind: str, template_id: str, workspace_id: str) -> str:
-        base = f"{kind}:{template_id}"
-        return base if workspace_id == DEFAULT_WORKSPACE_ID else f"{workspace_id}:{base}"
-
-    def list_template_registry(self, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        return self.plugins.list_template_registry(workspace_id)
-
-    def mark_template_installed(
-        self,
-        *,
-        kind: str,
-        template_id: str,
-        version: str = "1.0.0",
-        metadata: Optional[Dict[str, Any]] = None,
-        workspace_id: Optional[str] = None,
-    ) -> Dict[str, Any]:
-        return self.plugins.mark_template_installed(kind=kind, template_id=template_id, version=version, metadata=metadata, workspace_id=workspace_id)
-
-    # ------------------------------------------------------------------
-    # Audit timeline
-    # ------------------------------------------------------------------
-
-    def filter_audit_timeline(
-        self,
-        audit_events: Iterable[Dict[str, Any]],
-        *,
-        user: Optional[str] = None,
-        event_type: Optional[str] = None,
-        model: Optional[str] = None,
-        since: Optional[str] = None,
-        until: Optional[str] = None,
-        limit: int = 100,
-    ) -> Dict[str, Any]:
-        return self._timeline.filter_audit_timeline(audit_events, user=user, event_type=event_type, model=model, since=since, until=until, limit=limit)
-
-    def timeline(self, audit_events: Optional[Iterable[Dict[str, Any]]] = None, limit: int = 100, workspace_id: Optional[str] = None) -> Dict[str, Any]:
-        return self._timeline.timeline(audit_events=audit_events, limit=limit, workspace_id=workspace_id)