@maudecode/talaria-web 1.17.2 → 1.19.0

package/sidecar/talaria_sidecar/methods/providers.py

@@ -10,10 +10,14 @@ composes: ``hermes_cli.auth``, ``hermes_cli.models``, ``hermes_cli.runtime_provi
 from __future__ import annotations
 
 import dataclasses
+import json
 import logging
+import sqlite3
 import sys
 import threading
+from contextlib import closing
 from pathlib import Path
+from types import SimpleNamespace
 from typing import Any
 
 from ..errors import InvalidParams, RpcError
@@ -94,11 +98,57 @@ def _user_plugin_profiles() -> dict[int, tuple[Any, Path]]:
     return out
 
 
+def _hosted_plugin_profiles(roots: dict[Path, str]) -> dict[Path, list] | None:
+    """Resolve enabled directories through the Agent's host metadata and scoped provider registry."""
+    import providers
+
+    if not hasattr(providers, "_home_layer") or not callable(getattr(providers, "provider_source", None)):
+        return None
+    try:
+        from hermes_cli.plugin_isolation import ISOLATION_HOST, isolation_mode
+    except ImportError:  # per-home registries predate host isolation
+        return None
+
+    if isolation_mode() != ISOLATION_HOST:
+        return None
+    from hermes_cli.plugin_host_profiles import load_hosted_profiles
+    from hermes_constants import get_hermes_home, hermes_home_key
+
+    registered = {p.name: p for p in providers.list_providers() if providers.provider_source(p.name) == "user"}
+    home_key = hermes_home_key(get_hermes_home())
+    # Discovery also loads disabled and manifest-less category plugins. Include them when checking name collisions.
+    directories = set(roots)
+    for parent, flat in ((providers._user_plugins_dir(), False), (providers._installed_plugins_dir(), True)):
+        if parent is not None:
+            directories.update(child.resolve() for child in parent.iterdir()
+                               if child.is_dir() and not child.name.startswith(("_", "."))
+                               and (not flat or (child.name != "model-providers" and providers._declares_model_provider_kind(child))))
+    owners: dict[str, set[Path]] = {}
+    for root in directories:
+        try:
+            # Reuse the Agent's cached extraction; provider ids need not match manifest or directory names.
+            profiles = load_hosted_profiles(root, providers._user_module_name(root, home_key))
+            for profile in profiles:
+                owners.setdefault(profile.name, set()).add(root)
+        except Exception:  # noqa: BLE001 - failed extraction keeps the manifest's not_loaded row
+            log.debug("reading hosted provider plugin %s failed", root, exc_info=True)
+    found: dict[Path, list] = {root: [] for root in roots}
+    for name, profile in registered.items():
+        origins = owners.get(name, set())
+        if len(origins) == 1:
+            root = next(iter(origins))
+            if root in found:
+                found[root].append(profile)
+    return found
+
+
 def _load_plugin(root: Path) -> None:
     """Load the scoped profile's installed plugin that the process-wide discovery (run under the launch profile) skipped.
 
-    Uses the Agent's own loader, as ``hermes plugins dev`` does, once per directory. A plugin never displaces a provider
-    that is already registered, so one profile's plugin cannot change what another profile's provider id runs.
+    Uses the Agent's own loader, as ``hermes plugins dev`` does, once per directory. On an Agent with one process-wide
+    provider registry, a plugin never displaces a provider that is already registered, so one profile's plugin cannot
+    change what another profile's provider id runs. An Agent with per-home provider layers registers it in this home's
+    layer instead, so the same id is that profile's own provider.
     """
     import providers
 
@@ -121,12 +171,13 @@ def _load_plugin(root: Path) -> None:
 def installed_plugin_profiles() -> list[tuple[str, Any]]:
     """``(manifest name, profile | None)`` for each enabled model-provider plugin installed in the scoped home.
 
-    Bundled providers are built-ins, not plugins. The Agent keeps one provider registry per process, so a profile
-    belongs to this home only when the plugin module that registered it lives in one of this home's plugin
-    directories; a plugin the launch discovery skipped is loaded here. ``None`` means the plugin could not be loaded:
-    it failed to import, its provider id is taken by another plugin, or another profile's plugin has the same directory
-    name. ponytail: ownership is read from the plugin module's globals, so a plugin that registers an unbound inline
-    profile also reads as not loaded; track registrations in the Agent if one ever does.
+    Bundled providers are built-ins, not plugins. Hosted profiles come from the Agent's scoped user registry and
+    directory metadata. In-process profiles belong to this home when their module lives in its plugin directories;
+    a plugin the launch discovery skipped is loaded here.
+    ``None`` means the plugin could not be loaded or attributed: it failed to import, its hosted provider id is
+    ambiguous, or a registration/module name collided in an older process-wide registry.
+    shortcut: in-process ownership uses module globals, so an unbound inline profile reads as not
+    loaded; use Agent registration metadata if it becomes available.
     """
     try:
         from hermes_cli.plugins_discovery import _get_disabled_plugins, _get_enabled_plugins, collect_directory_manifests, gate_manifest
@@ -141,6 +192,10 @@ def installed_plugin_profiles() -> list[tuple[str, Any]]:
     if not roots:
         return []
 
+    hosted = _hosted_plugin_profiles(roots)
+    if hosted is not None:
+        return [(name, p) for root, name in roots.items() for p in (hosted[root] or [None])]
+
     def owned() -> dict[Path, list]:
         found: dict[Path, list] = {root: [] for root in roots}
         for profile, directory in _user_plugin_profiles().values():
@@ -158,18 +213,40 @@ def installed_plugin_profiles() -> list[tuple[str, Any]]:
     return [(name, p) for root, name in roots.items() for p in (found[root] or [None])]
 
 
-def _other_profile_plugin(provider_id: str) -> bool:
-    """Whether ``provider_id`` is a plugin provider that another profile installed (the registry is process-wide)."""
-    from providers import get_provider_profile
+def _unavailable_plugin(provider_id: str) -> bool:
+    """Whether a registered plugin lacks an enabled, unambiguous owner in this home."""
+    import providers
 
-    profile = get_provider_profile(provider_id)
-    if profile is None or id(profile) not in _user_plugin_profiles():
+    profile = providers.get_provider_profile(provider_id)
+    if profile is None:
+        return False
+    if hasattr(providers, "_home_layer") and callable(getattr(providers, "provider_source", None)):
+        if providers.provider_source(profile.name) != "user":
+            return False
+    elif id(profile) not in _user_plugin_profiles():
         return False
     return not any(p is profile for _name, p in installed_plugin_profiles())
 
 
+def _agent_knows_provider(name: str) -> bool:
+    """Whether the Agent's auth layer can resolve this provider id at all.
+
+    Agent 0.21.3 resolves providers from a ``PROVIDER_REGISTRY`` snapshot of its import-time plugin discovery, so a
+    named profile's plugin loaded here on demand is unknown to it and cannot run. Registering it there would expose it
+    to every profile, so it reads as unavailable instead. Newer Agents look providers up live (``_registry_lookup``).
+    """
+    try:
+        import hermes_cli.auth as auth
+    except Exception:  # noqa: BLE001 - auth_status reports an unavailable auth layer
+        return True
+    registry = getattr(auth, "PROVIDER_REGISTRY", None)
+    return hasattr(auth, "_registry_lookup") or not isinstance(registry, dict) or name.strip().lower() in registry
+
+
 def _setup_state(profile: Any) -> str:
     """The Agent's own setup verdict for a plugin provider, without spawning its CLI or reading its credentials."""
+    if not _agent_knows_provider(str(profile.name)):
+        return "unavailable"
     try:
         status = auth_status(profile.name)
     except RpcError:
@@ -178,6 +255,9 @@ def _setup_state(profile: Any) -> str:
         return "unavailable"
     if profile.auth_type == "external_process":
         return "ready" if status.get("configured") else "missing_cli"
+    if profile.auth_type in ("oauth_external", "oauth_device_code"):
+        # The Agent's ``configured`` only means registered here; a pooled token, live or refreshable on use, means signed in.
+        return "ready" if status.get("logged_in") or status.get("needs_refresh") else "needs_setup"
     return "ready" if status.get("logged_in") or status.get("configured") else "needs_setup"
 
 
@@ -193,47 +273,97 @@ def plugin_providers() -> list[dict]:
     return rows
 
 
-def _plugin_catalog(provider_id: str) -> list[str]:
+def _plugin_catalog(provider_id: str) -> tuple[list[str], bool]:
     """Discovery for an installed plugin the Agent's catalog has no fetcher for: the profile's own listing, then its fallback.
 
     API-key plugins already get both from ``provider_model_ids`` with their key, so only keyless auth types list here.
+    Like the Agent, the fallback list is a placeholder only when a listing was tried and declined.
     """
     for _name, profile in installed_plugin_profiles():
         if profile is None or str(profile.name).strip().lower() != provider_id.strip().lower():
             continue
+        lists = bool(profile.supports_model_listing) and profile.auth_type != "api_key"
         try:
-            live = profile.fetch_models(timeout=8.0) if profile.supports_model_listing and profile.auth_type != "api_key" else None
+            live = profile.fetch_models(timeout=8.0) if lists else None
         except Exception:  # noqa: BLE001 - a broken plugin answers with its fallback catalog
             log.debug("fetch_models(%r) failed", provider_id, exc_info=True)
             live = None
-        return [str(m) for m in (live or profile.fallback_models or ()) if m]
-    return []
+        return [str(m) for m in (live or profile.fallback_models or ()) if m], lists and not live
+    return [], False
 
 
-def model_ids(provider_id: str, *, force_refresh: bool) -> list[str]:
+def model_ids(provider_id: str, *, force_refresh: bool) -> tuple[list[str], bool]:
+    """The Agent's catalog for a provider, and whether it is the curated placeholder for an unreachable one (TAL-799)."""
     try:
-        from hermes_cli.models import provider_model_ids
+        from hermes_cli import models
     except Exception as exc:  # noqa: BLE001
         raise RpcError(f"model catalog unavailable: {exc}", condition="providers_unavailable") from exc
     try:
-        if _other_profile_plugin(provider_id):
-            return []
-    except Exception:  # noqa: BLE001 - no readable provider registry means no plugin to keep apart
+        if _unavailable_plugin(provider_id):
+            return [], False
+    except Exception:  # noqa: BLE001 - an unverified owner must not expose another plugin's models
         log.debug("plugin ownership check for %r failed", provider_id, exc_info=True)
+        return [], False
     try:
-        ids = provider_model_ids(provider_id, force_refresh=force_refresh)
+        ids = models.provider_model_ids(provider_id, force_refresh=force_refresh)
     except TypeError:
-        ids = provider_model_ids(provider_id)
+        ids = models.provider_model_ids(provider_id)
     except Exception:  # noqa: BLE001
         log.debug("provider_model_ids(%r) failed", provider_id, exc_info=True)
         ids = []
+    # Agents before the marker never flag a fallback.
+    curated = getattr(models, "CuratedFallbackModels", None)
+    fallback = isinstance(curated, type) and isinstance(ids, curated)
     ids = [str(m) for m in (ids or []) if m]
     if ids:
-        return ids
+        return ids, fallback
     try:
         return _plugin_catalog(provider_id)
     except RpcError:
-        return []
+        return [], False
+
+
+def _requests_local_runtime(requested: str | None) -> bool:
+    """Whether a resolution asks for the Agent's managed llama.cpp provider, picked the way the Agent picks it: the
+    named provider, else the profile's, else ``HERMES_INFERENCE_PROVIDER``."""
+    try:
+        from hermes_cli.providers import LLAMACPP_ALIASES
+        from hermes_cli.runtime_provider import resolve_requested_provider
+
+        return resolve_requested_provider(requested) in LLAMACPP_ALIASES
+    except Exception:  # noqa: BLE001 - an Agent without the local runtime
+        return False
+
+
+def runtime_failure(exc: Exception, requested: str | None, message: str | None = None) -> RpcError:
+    """The typed error for a runtime that did not resolve. The local llama.cpp provider has no credential to add: it
+    fails because its server is off or still starting, and the Agent's message says which (TAL-798)."""
+    condition = "local_runtime_unavailable" if _requests_local_runtime(requested) else "credential_missing"
+    return RpcError(message or str(exc), condition=condition, data={"error_type": type(exc).__name__})
+
+
+def local_models() -> dict:
+    """The Agent's managed llama.cpp runtime (TAL-798): the downloaded GGUFs, selectable before its server runs (a turn
+    on one boots it), and the endpoint the running server recorded. An Agent without the local runtime lists none."""
+    try:
+        from hermes_cli.local_runtime.bootstrap import staged_model_ids
+        from hermes_cli.providers import LLAMACPP_PROVIDER_ID
+    except Exception:  # noqa: BLE001 - predates the local runtime
+        return {"provider_id": "", "models": [], "current_endpoint": None}
+    try:
+        models = [str(m) for m in staged_model_ids() if m]
+    except Exception:  # noqa: BLE001 - an unreadable models directory lists none
+        log.debug("staged_model_ids failed", exc_info=True)
+        models = []
+    endpoint = None
+    try:
+        from hermes_cli.local_runtime.endpoint import _state_endpoint
+
+        state = _state_endpoint()
+        endpoint = str(state["base_url"]) if state else None
+    except Exception:  # noqa: BLE001 - no recorded server
+        log.debug("local runtime endpoint failed", exc_info=True)
+    return {"provider_id": str(LLAMACPP_PROVIDER_ID), "models": models, "current_endpoint": endpoint}
 
 
 def resolve_runtime(*, requested: str | None, api_key: str | None, base_url: str | None, target_model: str | None) -> dict:
@@ -248,7 +378,7 @@ def resolve_runtime(*, requested: str | None, api_key: str | None, base_url: str
             message = format_runtime_provider_error(exc)
         except Exception:  # noqa: BLE001
             message = str(exc)
-        raise RpcError(message, condition="credential_missing", data={"error_type": type(exc).__name__})
+        raise runtime_failure(exc, requested, message) from exc
     return _plain(runtime) if isinstance(runtime, dict) else {"runtime": _plain(runtime)}
 
 
@@ -346,7 +476,60 @@ def capabilities(provider: str, model: str) -> dict | None:
     return row if isinstance(row, dict) else None
 
 
+def selection_warnings(home: Path, params: dict) -> dict:
+    """Read-only guard decision using the same route resolver as a turn; never builds or evicts an Agent."""
+    from . import chat
+    try:
+        from hermes_cli.model_selection_guards import SelectionContext, selection_context_for_agent, selection_warnings as warnings
+    except ImportError as exc:
+        raise RpcError("Model selection warnings are unavailable in this Agent", condition="unsupported") from exc
+
+    model = str(params["model"])
+    runtime = chat._resolve_runtime(params.get("provider"), model)
+    provider = str(runtime.get("provider") or params.get("provider") or "")
+    base_url = str(runtime.get("base_url") or "")
+    tokens = params.get("context_tokens")
+    if not tokens:
+        with chat._AGENT_CACHE_LOCK:
+            entry = chat._AGENT_CACHE.get(params["session_id"])
+            if entry and Path(entry[2]).resolve() == home.resolve():
+                context = selection_context_for_agent(entry[0])
+                tokens = context.context_tokens if context else None
+    if not tokens and (home / "state.db").exists():
+        from agent.usage_anchor import persisted_anchor_tokens
+
+        # SessionDB opens and migrates its database. The guard needs only this read-only accessor.
+        with closing(sqlite3.connect(f"{(home / 'state.db').resolve().as_uri()}?mode=ro", uri=True)) as db:
+            row = db.execute("SELECT model_config FROM sessions WHERE id=?", (params["session_id"],)).fetchone()
+            config = json.loads(row[0] or "{}") if row else {}
+            reader = SimpleNamespace(get_session_model_config_value=lambda sid, key, default=None: config.get(key, default))
+            tokens = persisted_anchor_tokens(reader, params["session_id"], params.get("messages", []))
+    # A same-model pick on another provider still abandons the previous route's prompt cache.
+    current = params.get("current_model") if params.get("current_provider") == params.get("provider") else None
+    context = SelectionContext(context_tokens=tokens, current_model=current)
+    result = warnings(model, provider=provider, base_url=base_url, api_key=runtime.get("api_key"), selection_context=context)
+    return {"warnings": [_plain(w) for w in result], "context_tokens": tokens or None, "provider": provider, "base_url": base_url}
+
+
 def register(reg) -> None:
+    @reg.method("models.selection_warnings")
+    def selection(ctx: CallContext, params: dict) -> dict:
+        if not params.get("model") or not params.get("session_id"):
+            raise InvalidParams("model and session_id are required")
+        home = profile_home_param(params)
+        with scoped_home(home):
+            return selection_warnings(home, params)
+
+    @reg.method("models.speed_tiers")
+    def speed_tiers(ctx: CallContext, params: dict) -> dict:
+        from ..speed import supported_speed_tiers
+
+        routes = params.get("routes")
+        if not isinstance(routes, list) or any(not isinstance(route, dict) or not route.get("model") for route in routes):
+            raise InvalidParams("routes must contain model routes")
+        with scoped_home(profile_home_param(params)):
+            return {"tiers": [supported_speed_tiers(str(route["model"]), str(route.get("provider") or ""), str(route.get("base_url") or "")) for route in routes]}
+
     @reg.method("providers.registry")
     def registry_(ctx: CallContext, params: dict) -> dict:
         with scoped_home(profile_home_param(params)):
@@ -363,7 +546,13 @@ def register(reg) -> None:
         if not provider:
             raise InvalidParams("provider is required")
         with scoped_home(profile_home_param(params)):
-            return {"provider": provider, "model_ids": model_ids(provider, force_refresh=bool(params.get("force_refresh", False)))}
+            ids, fallback = model_ids(provider, force_refresh=bool(params.get("force_refresh", False)))
+            return {"provider": provider, "model_ids": ids, "fallback": fallback}
+
+    @reg.method("providers.local_models")
+    def local(ctx: CallContext, params: dict) -> dict:
+        with scoped_home(profile_home_param(params)):
+            return local_models()
 
     @reg.method("providers.resolve_runtime")
     def runtime(ctx: CallContext, params: dict) -> dict:

package/sidecar/talaria_sidecar/methods/runtime.py

@@ -2,18 +2,83 @@
 
 from __future__ import annotations
 
+import json
 import os
 import re
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
 
 from .. import SIDECAR_RPC_VERSION
 from ..errors import InvalidParams, RpcError
-from ..home import edit_launch_env
+from ..home import edit_launch_env, _frozen_launch_env
 from ..rpc import CallContext
 
 
 def register(registry) -> None:
     runtime = registry.runtime
 
+    @registry.method("runtime.agent_mutation", requires_agent=False)
+    def agent_mutation(ctx: CallContext, params: dict) -> dict:
+        from ..agent_mutation import call
+        return call(runtime, ctx, params)
+
+    @registry.method("runtime.agent_recovery", requires_agent=False)
+    def agent_recovery(ctx: CallContext, params: dict) -> dict:
+        from ..agent_mutation import recover_retained
+        return recover_retained(runtime, ctx, probe=params.get('probe') is True, complete_revision=params.get('complete_revision'))
+
+    @registry.method("runtime.sync_dependencies", requires_agent=False)
+    def sync_dependencies(ctx: CallContext, params: dict) -> dict:
+        # Source has already advanced; loading it or checking the old revision would prevent repair.
+        expected = params.get("agent_dir")
+        root = runtime.agent_dir
+        if not isinstance(expected, str) or not expected or root is None or Path(expected).resolve() != root.resolve():
+            raise InvalidParams("agent_dir must match the sidecar's configured Agent checkout")
+        if not (root / "hermes_cli" / "venv_sync.py").is_file():
+            return {"ok": True, "skipped": True, "detail": ""}
+        env = _frozen_launch_env()
+        env.update(HERMES_HOME=str(runtime.hermes_home), HERMES_DISABLE_LAZY_INSTALLS="1",
+                   PYTHONPATH=str(root) + (os.pathsep + env["PYTHONPATH"] if env.get("PYTHONPATH") else ""))
+        # The supervisor's stdin is a lifetime lease: closing it also covers a killed sidecar.
+        with tempfile.TemporaryFile() as stdout, tempfile.TemporaryFile() as stderr:
+            try:
+                proc = subprocess.Popen(
+                    [sys.executable, str(Path(__file__).parents[1] / "dependency_sync.py"), str(root)],
+                    cwd=root, env=env, stdin=subprocess.PIPE, stdout=stdout, stderr=stderr,
+                )
+            except OSError as exc:
+                return {"ok": False, "skipped": False, "detail": str(exc)}
+            deadline = time.monotonic() + 300
+            try:
+                while proc.poll() is None:
+                    ctx.check_cancelled()
+                    if time.monotonic() >= deadline:
+                        return {"ok": False, "skipped": False, "detail": "Agent dependency sync timed out."}
+                    ctx.cancel_event.wait(0.05)
+            finally:
+                proc.stdin.close()
+                proc.wait()  # The supervisor terminates and reaps its writer before releasing the lock.
+            stdout.seek(0)
+            output = stdout.read(4 * 1024 * 1024 + 1)
+            stderr.seek(0, os.SEEK_END)
+            stderr.seek(max(0, stderr.tell() - 4000))
+            diagnostic = stderr.read().decode("utf-8", errors="replace")
+            if proc.returncode != 0:
+                return {"ok": False, "skipped": False, "detail": diagnostic or output[-4000:].decode("utf-8", errors="replace") or "Agent dependency sync failed."}
+            try:
+                if len(output) > 4 * 1024 * 1024:
+                    raise ValueError("sync output exceeds limit")
+                response = json.loads(output)
+                if not isinstance(response, dict):
+                    raise ValueError("not an object")
+            except ValueError:
+                return {"ok": False, "skipped": False, "detail": "Agent dependency sync returned an invalid result."}
+            return {"ok": response.get("ok") is True, "skipped": False,
+                    "detail": str(response.get("detail") or "")[-4000:]}
+
     @registry.method("runtime.handshake", requires_agent=False)
     def handshake(ctx: CallContext, params: dict) -> dict:
         requested = params.get("rpc_version")
@@ -50,6 +115,7 @@ def register(registry) -> None:
             raise InvalidParams("set must map variable names to strings")
         if not isinstance(to_unset, list) or not all(isinstance(k, str) and names.match(k) for k in to_unset):
             raise InvalidParams("unset must list variable names")
+        to_set = {**to_set, "HERMES_DISABLE_LAZY_INSTALLS": "1"}
         for name in to_unset:
             os.environ.pop(name, None)
         for name, value in to_set.items():
@@ -67,7 +133,9 @@ def register(registry) -> None:
         if not isinstance(code, int):
             raise InvalidParams("exit_code must be an integer")
         from .chat import drain_agents
+        from ..agent_mutation import close_all
 
+        close_all()
         drain_agents()
         ctx.server.request_shutdown(exit_code=code)
         return {"ok": True}

package/sidecar/talaria_sidecar/methods/skills.py

@@ -54,6 +54,25 @@ def _category(skill_md: Path, dirs: list[Path], local: Path) -> str | None:
 
 
 def list_skills(profile_home: Path, category: str | None = None) -> dict:
+    try:
+        from agent.skill_utils import get_disabled_skill_names, is_disabled_entry
+        from tools.skills_tool import _skill_catalog, _sort_skills
+    except ImportError:
+        return _legacy_list_skills(profile_home, category)
+    disabled = get_disabled_skill_names("webui")
+    # Keep disabled rows manageable, but never advertise shadowed or unloadable copies.
+    out = [{"name": entry["load_name"], "load_name": entry["load_name"],
+            "declared_name": entry["name"], "status": entry["status"], "tier": entry["tier"],
+            "description": entry.get("description") or "", "category": entry.get("category"),
+            "disabled": is_disabled_entry(entry, disabled)}
+           for entry in _skill_catalog(skip_disabled=True) if entry["load_name"]]
+    if category:
+        out = [s for s in out if s.get("category") == category]
+    out = _sort_skills(out)
+    return {"success": True, "skills": out, "categories": sorted({s["category"] for s in out if s.get("category")}), "count": len(out)}
+
+
+def _legacy_list_skills(profile_home: Path, category: str | None = None) -> dict:
     skills_dir = profile_home / "skills"
     try:
         from agent.skill_utils import iter_skill_index_files
@@ -99,6 +118,27 @@ def list_skills(profile_home: Path, category: str | None = None) -> dict:
 
 
 def find_skill(name: str, dirs: list[Path]) -> tuple[Path | None, Path | None]:
+    try:
+        from agent.skill_utils import resolve_skill_catalog  # noqa: F401 - capability gate for the matching lookup API
+        from tools.skills_tool import _locate_skill, _skill_lookup_path_error, _skill_search_dirs
+    except ImportError:
+        return _legacy_find_skill(name, dirs)
+    if error := _skill_lookup_path_error(name):
+        raise InvalidParams(error)
+    local_name = name.replace(":", "/", 1) if ":" in name else None
+    if local_name and (error := _skill_lookup_path_error(local_name)):
+        raise InvalidParams(error)
+    roots, _ = _skill_search_dirs()
+    error, skill_dir, skill_md = _locate_skill(name, local_name, roots)
+    if error:
+        result = json.loads(error)
+        if result.get("matches"):
+            raise InvalidParams(result["error"])
+        return None, None
+    return skill_dir, skill_md
+
+
+def _legacy_find_skill(name: str, dirs: list[Path]) -> tuple[Path | None, Path | None]:
     from agent.skill_utils import iter_skill_index_files
     from tools.skills_tool import _EXCLUDED_SKILL_DIRS, _parse_frontmatter
 
@@ -208,9 +248,15 @@ def view_from_file(skill_dir: Path | None, skill_md: Path) -> dict:
 def view_skill(profile_home: Path, name: str) -> dict:
     skills_dir = profile_home / "skills"
     dirs = search_dirs(skills_dir)
-    skill_dir, skill_md = find_skill(name, dirs)
+    try:
+        skill_dir, skill_md = find_skill(name, dirs)
+    except InvalidParams as exc:
+        return {"success": False, "error": str(exc)}
     if skill_md:
-        return view_from_file(skill_dir, skill_md)
+        result = view_from_file(skill_dir, skill_md)
+        if result.get("success"):
+            result["editable"] = skill_md.name == "SKILL.md" and _within(skills_dir, skill_md)
+        return result
     if ":" in str(name or ""):
         try:
             from agent.skill_utils import is_valid_namespace, parse_qualified_name
@@ -223,7 +269,10 @@ def view_skill(profile_home: Path, name: str) -> dict:
                 pm = get_plugin_manager()
                 if pm.find_plugin_skill(name) is not None or pm.list_plugin_skills(namespace):
                     raw = skill_view(name)
-                    return json.loads(raw) if isinstance(raw, str) else raw
+                    result = json.loads(raw) if isinstance(raw, str) else raw
+                    if result.get("success"):
+                        result["editable"] = False
+                    return result
         except Exception:  # noqa: BLE001
             pass
     names = [s["name"] for s in list_skills(profile_home).get("skills", [])]
@@ -259,4 +308,18 @@ def register(registry) -> None:
             raise InvalidParams("name is required")
         with scoped_home(home):
             skill_dir, skill_md = find_skill(name, search_dirs(home / "skills"))
-        return {"found": skill_md is not None, "skill_dir": str(skill_dir) if skill_dir else None, "skill_md": str(skill_md) if skill_md else None}
+            identity = {}
+            if skill_md:
+                try:
+                    from tools.skills_tool import _skill_catalog
+                except ImportError:
+                    pass
+                else:
+                    catalog = _skill_catalog(skip_disabled=True, include_hidden=True)
+                    entry = next((e for e in catalog if e["path"] == skill_md), None)
+                    if entry is not None:
+                        if not entry["load_name"]:
+                            raise InvalidParams("Skill has no unambiguous catalog identity")
+                        identity = {"load_name": entry["load_name"], "declared_name": entry["name"],
+                                    "sibling_load_names": [e["load_name"] for e in catalog if e["name"] == entry["name"] and e["load_name"]]}
+        return {"found": skill_md is not None, "skill_dir": str(skill_dir) if skill_dir else None, "skill_md": str(skill_md) if skill_md else None, **identity}