ltcai 11.5.0 → 11.5.2

package/latticeai/core/http_origin.py

@@ -0,0 +1,146 @@
+"""Which host a request *really* arrived at, when something proxied it.
+
+The desktop front door is a reverse proxy: the browser talks to the gateway on
+one port and the gateway forwards to the worker on another.  ``Host`` is a
+hop-by-hop header, so it is replaced on the way out and the worker sees only its
+own internal authority — which is why every cookie-authenticated write through
+an adopted worker was rejected as ``csrf_origin_rejected``.  The gateway states
+the fact it destroyed in ``X-Forwarded-Host`` / ``X-Forwarded-Proto``; this
+module decides when to believe it.
+
+Threat model, so the rule is checkable rather than felt:
+
+* **A browser cannot set these headers.**  ``X-Forwarded-*`` are not on the
+  fetch-safelist and a page cannot add them cross-origin without a preflight
+  the CORS allowlist rejects.  So no *web page* can reach this code path.
+* **A local non-browser caller could already forge ``Origin``.**  curl on this
+  machine can send any ``Origin`` it likes, and the loopback exemption in
+  :mod:`latticeai.core.csrf` already trusts it.  Honouring a forwarded host from
+  the same caller widens nothing that was not already open.
+* **Anyone else is not trusted.**  Off-loopback the header is honoured only from
+  a peer the operator listed in ``LATTICEAI_TRUSTED_PROXIES`` — the same
+  allowlist ``latticeai.core.security.client_ip`` uses for the same reason, and
+  empty by default.
+
+The functions are pure: the caller supplies the headers and the peer address, so
+the policy is testable without an ASGI app or a socket.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from typing import Any, Optional
+
+__all__ = [
+    "FORWARDED_HOST_HEADER",
+    "FORWARDED_PROTO_HEADER",
+    "effective_host",
+    "effective_origin",
+    "peer_may_forward",
+    "request_external_origin",
+]
+
+#: The authority the client asked for, as stated by the proxy in front of us.
+FORWARDED_HOST_HEADER = "x-forwarded-host"
+#: The scheme the client used to reach that proxy.
+FORWARDED_PROTO_HEADER = "x-forwarded-proto"
+
+# Only these two are ever taken from a forwarded scheme; anything else is a
+# value we would have to reason about, and the fallback is already correct.
+_KNOWN_SCHEMES = ("https", "http")
+
+
+def peer_may_forward(peer: Optional[str]) -> bool:
+    """Whether ``X-Forwarded-*`` from this direct peer may be believed.
+
+    Loopback, or a member of the configured trusted-proxy allowlist.  An
+    unparseable or absent peer is *not* trusted: a request whose origin we
+    cannot establish is exactly the one whose claims we must not take.
+    """
+    if not peer:
+        return False
+    try:
+        address = ipaddress.ip_address(str(peer).strip())
+    except ValueError:
+        return False
+    if address.is_loopback:
+        return True
+    from latticeai.core.security import _peer_is_trusted_proxy
+
+    return _peer_is_trusted_proxy(str(peer).strip())
+
+
+def _first(value: Optional[str]) -> str:
+    """The first entry of a possibly comma-joined forwarded header."""
+    return (value or "").split(",")[0].strip()
+
+
+def effective_host(
+    *,
+    host: Optional[str],
+    forwarded_host: Optional[str] = None,
+    peer: Optional[str] = None,
+) -> Optional[str]:
+    """The authority the client aimed at: the forwarded one when believable.
+
+    Falls back to the request's own ``Host`` in every other case — no proxy, a
+    peer we do not trust, or a forwarded header that is empty.  ``None`` only
+    when there is nothing to report at all (an HTTP/1.0 request with no ``Host``
+    and no proxy), which callers already have to handle.
+    """
+    if peer_may_forward(peer):
+        claimed = _first(forwarded_host)
+        if claimed:
+            return claimed
+    own = (host or "").strip()
+    return own or None
+
+
+def effective_origin(
+    *,
+    host: Optional[str],
+    scheme: str = "http",
+    forwarded_host: Optional[str] = None,
+    forwarded_proto: Optional[str] = None,
+    peer: Optional[str] = None,
+) -> Optional[str]:
+    """``scheme://authority`` for the front door this request came through.
+
+    ``scheme`` is what *this* server is speaking; the forwarded scheme wins when
+    the peer is trusted and states one we recognise, because a TLS-terminating
+    proxy speaks plain HTTP to us while the browser is on ``https`` and a link
+    built with the wrong scheme is a broken link.
+    """
+    authority = effective_host(host=host, forwarded_host=forwarded_host, peer=peer)
+    if not authority:
+        return None
+    resolved = (scheme or "http").strip().lower() or "http"
+    if peer_may_forward(peer):
+        claimed = _first(forwarded_proto).lower()
+        if claimed in _KNOWN_SCHEMES:
+            resolved = claimed
+    return f"{resolved}://{authority}"
+
+
+def request_external_origin(request: Any, *, fallback: Optional[str] = None) -> Optional[str]:
+    """:func:`effective_origin` for a live request — the *link-building* seam.
+
+    CSRF asks "is this same-origin?"; this asks the other question: "what URL
+    should I hand a person so they can come back here?" Both must read the same
+    front door, or an invite link mails out the internal worker port that only
+    the gateway can reach.
+
+    ``fallback`` is returned when the request states no authority at all, so a
+    caller with a configured public URL keeps it.
+    """
+    headers = getattr(request, "headers", None) or {}
+    client = getattr(request, "client", None)
+    url = getattr(request, "url", None)
+    origin = effective_origin(
+        host=headers.get("host"),
+        scheme=getattr(url, "scheme", "http") or "http",
+        forwarded_host=headers.get(FORWARDED_HOST_HEADER),
+        forwarded_proto=headers.get(FORWARDED_PROTO_HEADER),
+        peer=getattr(client, "host", None) if client else None,
+    )
+    return origin or fallback

package/latticeai/core/invitations.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import hashlib
 import json
 import secrets
 from datetime import datetime, timedelta
@@ -10,6 +9,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from latticeai.core.quiet import quiet
+from latticeai.core.security import sha256_hex
 
 from .timeutil import local_now as _now
 
@@ -19,7 +19,8 @@ def _iso(dt: datetime) -> str:
 
 
 def _hash_token(token: str) -> str:
-    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+    """Strict by design: an invite code is always a string by the time it lands here."""
+    return sha256_hex(token)
 
 
 def _atomic_write(path: Path, data: Dict[str, Any]) -> None:

package/latticeai/core/io_utils.py

@@ -5,10 +5,10 @@ from __future__ import annotations
 import hashlib
 import json
 import os
-from datetime import datetime
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict
 
+from lattice_brain.utils import parse_iso as parse_iso
 from latticeai.core.quiet import quiet
 
 
@@ -27,15 +27,6 @@ def atomic_write_json(path: Path, payload: Dict[str, Any]) -> None:
         quiet()
 
 
-def parse_iso(value: Optional[str]) -> Optional[datetime]:
-    if not value:
-        return None
-    try:
-        return datetime.fromisoformat(str(value))
-    except (TypeError, ValueError):
-        return None
-
-
 def sha256_file(path: Path) -> str:
     digest = hashlib.sha256()
     with open(path, "rb") as fh:

package/latticeai/core/legacy_compatibility.py

@@ -13,7 +13,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Dict, List
 
-LEGACY_COMPATIBILITY_VERSION = "11.5.0"
+LEGACY_COMPATIBILITY_VERSION = "11.5.2"
 
 
 @dataclass(frozen=True)

package/latticeai/core/marketplace.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from copy import deepcopy
 from typing import Any, Dict, List, Optional
 
-MARKETPLACE_VERSION = "11.5.0"
+MARKETPLACE_VERSION = "11.5.2"
 TEMPLATE_KINDS = ("plugin", "workflow", "agent", "ingestion_bridge")
 
 

package/latticeai/core/messages.py

@@ -536,6 +536,41 @@ MESSAGES: Dict[str, Dict[str, str]] = {
         "ko": "한 번에 처리할 개수는 {min}에서 {max} 사이여야 합니다.",
         "en": "Ask for between {min} and {max} items in one pass.",
     },
+    # ── AI-Worker seam (the Rust loop's three calls back into Python) ────
+    "agent_seam.disabled": {
+        "ko": "워커 시임이 꺼져 있습니다. 호스트가 직접 띄운 워커에서만 열립니다.",
+        "en": "The worker seam is off. It opens only in a worker the host started itself.",
+    },
+    "agent_seam.message_required": {
+        "ko": "모델에 보낼 내용을 적어주세요.",
+        "en": "Write the message to send to the model.",
+    },
+    "agent_seam.max_tokens_out_of_range": {
+        "ko": "한 번에 만들 길이는 {min}에서 {max} 사이여야 합니다.",
+        "en": "Ask for between {min} and {max} tokens in one completion.",
+    },
+    "agent_seam.temperature_out_of_range": {
+        "ko": "온도는 {min}에서 {max} 사이여야 합니다.",
+        "en": "Temperature has to be between {min} and {max}.",
+    },
+    "agent_seam.tool_required": {
+        "ko": "실행할 도구 이름이 필요합니다.",
+        "en": "A tool name to run is required.",
+    },
+    "agent_seam.tool_blocked": {
+        "ko": "'{tool}' 도구는 어떤 모드에서도 차단됩니다 ({reason}).",
+        "en": "'{tool}' is blocked in every mode ({reason}).",
+    },
+    "agent_seam.tool_fail_closed": {
+        "ko": "'{tool}' 도구는 기존 내용을 바꾸지만 검토할 수 있는 제안으로 "
+              "만들 수 없어 차단했습니다 ({reason}).",
+        "en": "'{tool}' would change existing content but cannot be staged as a "
+              "reviewable proposal, so it is blocked ({reason}).",
+    },
+    "agent_seam.proposals_unavailable": {
+        "ko": "변경 제안 서비스가 연결되어 있지 않습니다.",
+        "en": "The change proposal service is not connected.",
+    },
     # ── MCP / setup ─────────────────────────────────────────────────────
     "mcp.connector_not_found": {
         "ko": "커넥터를 찾을 수 없습니다.",
@@ -588,6 +623,11 @@ MESSAGES: Dict[str, Dict[str, str]] = {
 }
 
 
+def bilingual(ko: str, en: str) -> Dict[str, str]:
+    """One Korean/English phrase pair, in the shape every caller renders."""
+    return {"ko": ko, "en": en}
+
+
 def resolve_language(request: Any, default: str = DEFAULT_LANGUAGE) -> str:
     """Language for this request: the product's choice, then the browser's.
 

package/latticeai/core/model_compat.py

@@ -12,7 +12,6 @@
 
 from __future__ import annotations
 
-import importlib.util
 import json
 import logging
 import re
@@ -22,6 +21,8 @@ from dataclasses import asdict, dataclass
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
+from latticeai.core.module_probe import module_available as _module_available
+
 logger = logging.getLogger(__name__)
 
 
@@ -198,13 +199,6 @@ GEMMA4_MLX_LM_MODULES = ("mlx_lm.models.gemma4", "mlx_lm.models.gemma4_text")
 GEMMA4_UNIFIED_ID_PATTERN = re.compile(r"gemma[-_/ ]?4[-_/ ]?12b", re.I)
 
 
-def _module_available(module: str) -> bool:
-    try:
-        return importlib.util.find_spec(module) is not None
-    except (ImportError, ModuleNotFoundError, AttributeError, ValueError):
-        return False
-
-
 def _is_gemma4(model_id: str) -> bool:
     raw = str(model_id or "").lower()
     return bool(re.search(r"gemma[-_/ ]?4", raw))

package/latticeai/core/module_probe.py

@@ -0,0 +1,37 @@
+"""One answer to "is this module importable?".
+
+Four modules asked it four different ways: two consulted ``find_spec``, one
+imported for real, and they disagreed about which failures mean "no" and which
+should escape. The disagreement mattered — the setup probe's copy imports for
+real *on purpose*, because a native wheel like ``mlx`` can have a perfectly
+findable spec on the wrong architecture and still raise when it loads. A copy
+that only looked for the spec would report the runtime as present and let the
+recommendation engine plan an install around a module that cannot run.
+
+So the two behaviours stay, named: ``strict=False`` asks whether Python can
+*find* the module (cheap, no side effects, no import cost); ``strict=True``
+actually imports it and answers whether it *works*.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+
+__all__ = ["module_available"]
+
+
+def module_available(name: str, *, strict: bool = False) -> bool:
+    """Report whether ``name`` can be imported, never raising.
+
+    A probe that raises is a probe that takes the caller down for asking, and
+    every caller here is deciding what to *offer* the user — "I could not tell"
+    and "it is not there" lead to the same honest answer.
+    """
+    try:
+        if strict:
+            importlib.import_module(name)
+            return True
+        return importlib.util.find_spec(name) is not None
+    except Exception:
+        return False

package/latticeai/core/run_explain.py

@@ -30,6 +30,8 @@ from __future__ import annotations
 
 from typing import Any, Dict, List, Mapping, Optional, Sequence
 
+from latticeai.core.messages import bilingual as _bilingual
+
 __all__ = ["explain_run", "STRAIN_LEVELS"]
 
 
@@ -53,8 +55,9 @@ _REPAIR_GROUPS: Dict[str, tuple] = {
 }
 
 
-def _phrase(ko: str, en: str) -> Dict[str, str]:
-    return {"ko": ko, "en": en}
+
+#: Historical module-local name for the shared phrase-pair helper.
+_phrase = _bilingual
 
 
 def _int(value: Any) -> int:

package/latticeai/core/run_store.py

@@ -21,7 +21,6 @@ Design constraints (deliberate, matching :mod:`latticeai.services.funnel_metrics
 
 from __future__ import annotations
 
-import hashlib
 import json
 import logging
 import os
@@ -34,6 +33,7 @@ from typing import Any, Dict, List, Optional
 from latticeai.core.agent import AgentRunContext, AgentState
 from latticeai.core.agent_trace import LoopTrace
 from latticeai.core.quiet import quiet
+from latticeai.core.security import sha256_hex
 
 LOGGER = logging.getLogger(__name__)
 
@@ -44,7 +44,7 @@ _RUN_ID_RE = re.compile(r"^[A-Za-z0-9_-]{8,64}$")
 
 def hash_approval_token(token: str) -> str:
     """Stable digest used both at save and at resume comparison time."""
-    return hashlib.sha256(str(token or "").encode("utf-8")).hexdigest()
+    return sha256_hex(str(token or ""))
 
 
 def serialize_run_context(ctx: AgentRunContext) -> Dict[str, Any]:

package/latticeai/core/security.py

@@ -13,6 +13,19 @@ from fastapi import HTTPException
 from latticeai.core.quiet import quiet
 
 
+def sha256_hex(text: str) -> str:
+    """The one UTF-8 SHA-256 hex digest.
+
+    Six modules each carried this three-token expression, and they did not
+    agree on what to do with ``None``: two coerced it away, one raised. The
+    helper stays **strict** on purpose — coercing here would silently give
+    every caller the digest of the empty string, which is a valid-looking
+    token hash for "no token at all". Each call site keeps the contract it
+    already had, stated in its own body where a reader can see it.
+    """
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
 def hash_password(password: str) -> str:
     salt = secrets.token_hex(16)
     key = hashlib.scrypt(password.encode(), salt=salt.encode(), n=16384, r=8, p=1)

package/latticeai/core/sessions.py

@@ -6,7 +6,6 @@ holding raw tokens are migrated transparently on load (sessions survive the
 upgrade; the raw token never touches disk again).
 """
 
-import hashlib
 import json
 import logging
 import secrets
@@ -16,6 +15,7 @@ from pathlib import Path
 from typing import Dict, Optional
 
 from latticeai.core.io_utils import atomic_write_json
+from latticeai.core.security import sha256_hex
 
 SESSION_TTL = 60 * 60 * 24  # 24 hours
 SESSION_REFRESH_THRESHOLD = 60 * 15  # only persist if >15 min since last bump
@@ -25,7 +25,8 @@ _HEX64 = frozenset("0123456789abcdef")
 
 
 def _hash_token(token: str) -> str:
-    return hashlib.sha256((token or "").encode("utf-8")).hexdigest()
+    """Session keys are hashed at rest; a missing token hashes the empty string."""
+    return sha256_hex(token or "")
 
 
 def _looks_hashed(key: str) -> bool:

package/latticeai/core/sse.py

@@ -0,0 +1,25 @@
+"""The one Server-Sent Events frame builder.
+
+Five modules each formatted their own frame — three in the
+``event:``/``data:`` shape and two in the bare ``data:`` shape — with the same
+``json.dumps(..., ensure_ascii=False)`` payload. They agreed by accident, and a
+frame that disagrees by one byte is a stream the browser silently stops
+parsing, so the agreement is now structural rather than coincidental.
+
+``event=None`` produces the bare shape; a named event produces the prefixed
+one. Both are byte-identical to the copies they replaced.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+
+__all__ = ["sse_frame"]
+
+
+def sse_frame(event: Optional[str], data: Any) -> str:
+    """Render one SSE frame, terminated by the blank line that ends it."""
+    payload = json.dumps(data, ensure_ascii=False)
+    prefix = f"event: {event}\n" if event else ""
+    return f"{prefix}data: {payload}\n\n"

package/latticeai/core/users.py

@@ -100,15 +100,6 @@ def user_id_for_email(users: Dict[str, Any], email: Optional[str]) -> Optional[s
     return stable_user_id(normalized)
 
 
-def email_for_user_id(users: Dict[str, Any], user_id: Optional[str]) -> Optional[str]:
-    if not user_id:
-        return None
-    for email, user in (users or {}).items():
-        if isinstance(user, dict) and user.get("id") == user_id:
-            return email
-    return None
-
-
 def migrate_knowledge_graph_identity(db_path: Path, email_to_id: Dict[str, str]) -> int:
     """Rewrite KG owner/creator identity columns from email to stable UUIDs."""
     if not db_path.exists() or not email_to_id:

package/latticeai/core/workspace_graph_trace.py

@@ -6,16 +6,10 @@ from typing import Any, Dict, List, Optional
 from latticeai.core.quiet import quiet
 
 from .timeutil import now_iso as _now
-from .workspace_os_utils import _json_hash, _listify
+from .workspace_os_utils import WorkspaceStoreMixin, _json_hash, _listify
 
 
-class WorkspaceGraphTrace:
-    def __init__(self, store: Any):
-        self._store = store
-
-    def __getattr__(self, name: str) -> Any:
-        return getattr(self._store, name)
-
+class WorkspaceGraphTrace(WorkspaceStoreMixin):
     def build_graph_trace(
         self,
         question: str,

package/latticeai/core/workspace_os.py

@@ -53,7 +53,6 @@ from .workspace_permissions import (  # type: ignore
 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
@@ -844,15 +843,6 @@ class WorkspaceOSStore:
     # 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,

package/latticeai/core/workspace_os_constants.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 from typing import Dict
 
-WORKSPACE_OS_VERSION = "11.5.0"
+WORKSPACE_OS_VERSION = "11.5.2"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/latticeai/core/workspace_os_utils.py

@@ -17,6 +17,40 @@ from .io_utils import (
 from .io_utils import parse_iso as _parse_iso  # noqa: F401 - legacy helper re-export
 
 
+class WorkspaceStoreMixin:
+    """A collaborator that reads and writes through ``WorkspaceOSStore``.
+
+    The store was decomposed into managers that each own one branch of the state
+    document, and every one of them needs the same two things: a reference to the
+    store, and for anything it does not implement itself (``load_state``,
+    ``_scoped``, ``record_timeline_event``) to reach the store instead of raising
+    ``AttributeError``. Four managers wrote that out identically; the pair lives
+    here so a fifth cannot invent a third spelling of it.
+    """
+
+    def __init__(self, store: Any) -> None:
+        self._store = store
+
+    def __getattr__(self, name: str) -> Any:
+        # Only reached for attributes this manager does not define, so the
+        # store is the answer for every state-document operation.
+        return getattr(self._store, name)
+
+
+def graph_scope_kwargs(workspace_id: Any) -> Dict[str, Any]:
+    """The scoped-read kwargs the graph store expects (house pattern).
+
+    ``workspace_id is None`` means "unscoped caller": it reads everything it is
+    allowed to, legacy rows that predate workspaces included. A named workspace
+    reads only that workspace and never the legacy pool — which is the whole
+    isolation guarantee, so it is stated once.
+    """
+    return {
+        "allowed_workspaces": {workspace_id} if workspace_id is not None else None,
+        "include_legacy_global": workspace_id is None,
+    }
+
+
 def _safe_slug(raw: str) -> str:
     value = "".join(ch if ch.isalnum() or ch in "-_." else "-" for ch in str(raw or "").strip())
     value = "-".join(part for part in value.split("-") if part)

package/latticeai/core/workspace_review_items.py

@@ -14,16 +14,10 @@ from __future__ import annotations
 from typing import Any, Dict, List, Optional
 
 from .timeutil import now_iso as _now
-from .workspace_os_utils import _json_hash, _listify
+from .workspace_os_utils import WorkspaceStoreMixin, _json_hash, _listify
 
 
-class WorkspaceReviewItems:
-    def __init__(self, store: Any):
-        self._store = store
-
-    def __getattr__(self, name: str) -> Any:
-        return getattr(self._store, name)
-
+class WorkspaceReviewItems(WorkspaceStoreMixin):
     def create_review_item(
         self,
         *,

package/latticeai/core/workspace_runs.py

@@ -8,16 +8,10 @@ from lattice_brain.runtime.contracts import run_record_contract, workflow_run_co
 from lattice_brain.runtime.statuses import RUN_ACTIVE_STATUSES, RUN_TERMINAL_STATUSES
 
 from .timeutil import now_iso as _now
-from .workspace_os_utils import _json_hash, _listify
+from .workspace_os_utils import WorkspaceStoreMixin, _json_hash, _listify
 
 
-class WorkspaceRuns:
-    def __init__(self, store: Any):
-        self._store = store
-
-    def __getattr__(self, name: str) -> Any:
-        return getattr(self._store, name)
-
+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)

package/latticeai/core/workspace_skills.py

@@ -6,15 +6,10 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from .timeutil import now_iso as _now
+from .workspace_os_utils import WorkspaceStoreMixin
 
 
-class WorkspaceSkills:
-    def __init__(self, store: Any):
-        self._store = store
-
-    def __getattr__(self, name: str) -> Any:
-        return getattr(self._store, name)
-
+class WorkspaceSkills(WorkspaceStoreMixin):
     def list_skill_registry(self, skills_dir: Path, marketplace: Optional[List[Dict[str, Any]]] = None) -> Dict[str, Any]:
         state = self.load_state()
         registry = state.setdefault("skill_registry", {})