hubble-cli 4.0.0__py3-none-any.whl

hubble/scanner.py

@@ -0,0 +1,134 @@
+"""Background model health scan: fetch /models, send a tiny completion to each, save working ones.
+
+Writes available_models.json in the same format as test_models.py, so both stay compatible.
+"""
+
+import json
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from hubble.models import SCAN_FILE
+from hubble.provider import normalize_base_url
+
+
+def scan_age_hours(path: Path = SCAN_FILE) -> Optional[float]:
+    try:
+        return (time.time() - path.stat().st_mtime) / 3600
+    except OSError:
+        return None
+
+
+def _probe(client: httpx.Client, base_url: str, headers: Dict[str, str], model: str, timeout: float) -> Dict[str, Any]:
+    payload = {"model": model, "messages": [{"role": "user", "content": "hi"}], "max_tokens": 10, "temperature": 0.1}
+    start = time.time()
+    result = {"model": model, "available": False, "status_code": None, "latency_ms": 0, "sample": "", "reason": ""}
+    try:
+        resp = client.post(f"{base_url}/chat/completions", headers=headers, json=payload, timeout=timeout)
+        result["latency_ms"] = round((time.time() - start) * 1000)
+        result["status_code"] = resp.status_code
+        text = resp.text
+        if resp.status_code != 200:
+            result["reason"] = f"HTTP {resp.status_code}"
+        elif "upstream returned 403" in text or '"upstream_error"' in text or "unhandled err" in text:
+            result["reason"] = "upstream error inside 200"
+        else:
+            choices = resp.json().get("choices") or []
+            content = ((choices[0].get("message") or {}).get("content") or "").strip() if choices else ""
+            if content:
+                result.update(available=True, reason="OK", sample=content.replace("\n", " ")[:60])
+            else:
+                result["reason"] = "empty content"
+    except (httpx.HTTPError, ValueError) as e:
+        result["latency_ms"] = round((time.time() - start) * 1000)
+        result["reason"] = f"{type(e).__name__}"
+    return result
+
+
+class ModelScanner:
+    """Runs one scan at a time in a daemon thread; `status` is safe to read from the UI."""
+
+    def __init__(self, base_url: str, api_key: str, concurrency: int = 12, timeout: float = 12.0,
+                 output: Path = SCAN_FILE):
+        self.base_url = normalize_base_url(base_url)
+        self.api_key = api_key
+        self.concurrency = concurrency
+        self.timeout = timeout
+        self.output = output
+        self.status = "idle"      # idle | running | done | failed
+        self.done = 0
+        self.total = 0
+        self.working = 0
+        self.error = ""
+        self._thread: Optional[threading.Thread] = None
+
+    @property
+    def running(self) -> bool:
+        return self._thread is not None and self._thread.is_alive()
+
+    def start(self) -> bool:
+        if self.running:
+            return False
+        self.status, self.done, self.total, self.working, self.error = "running", 0, 0, 0, ""
+        self._thread = threading.Thread(target=self._run, name="hubble-model-scan", daemon=True)
+        self._thread.start()
+        return True
+
+    def summary(self) -> str:
+        if self.status == "running":
+            return f"scanning models {self.done}/{self.total or '?'}"
+        if self.status == "done":
+            return f"{self.working} models available"
+        if self.status == "failed":
+            return "model scan failed"
+        return ""
+
+    def _run(self):
+        headers = {"Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json"}
+        try:
+            with httpx.Client(timeout=self.timeout + 5) as client:
+                resp = client.get(f"{self.base_url}/models", headers=headers)
+                resp.raise_for_status()
+                data = resp.json()
+                entries = data.get("data", data) if isinstance(data, dict) else data
+                owners = {m["id"]: m.get("owned_by", "") for m in entries if isinstance(m, dict) and m.get("id")}
+                self.total = len(owners)
+                results: List[Dict[str, Any]] = []
+
+                def task(name):
+                    r = _probe(client, self.base_url, headers, name, self.timeout)
+                    self.done += 1
+                    if r["available"]:
+                        self.working += 1
+                    return r
+
+                with ThreadPoolExecutor(max_workers=self.concurrency) as pool:
+                    results = list(pool.map(task, owners))
+        except (httpx.HTTPError, ValueError, KeyError, TypeError) as e:
+            self.status, self.error = "failed", f"{type(e).__name__}: {e}"[:200]
+            return
+
+        working = sorted((r for r in results if r["available"]), key=lambda r: r["latency_ms"])
+        if not working:
+            # A gateway outage or bad key would otherwise wipe the model list.
+            self.status, self.error = "failed", "no model responded; kept the previous list"
+            return
+        save = {
+            "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
+            "base_url": self.base_url,
+            "total_tested": len(results),
+            "all_ids": list(owners),
+            "working_count": len(working),
+            "working_models": [{"model": r["model"], "latency_ms": r["latency_ms"],
+                                "owner": owners.get(r["model"], ""), "sample": r["sample"]} for r in working],
+            "all_results": results,
+        }
+        self.output.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.output.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(save, indent=2, ensure_ascii=False), encoding="utf-8")
+        tmp.replace(self.output)
+        self.status = "done"

hubble/session.py

@@ -0,0 +1,128 @@
+"""Append-only JSONL session transcripts under ~/.hubble/projects/<project>/<id>.jsonl.
+
+Record types: meta (first line), msg (one chat message), reset (history replaced by compaction).
+"""
+
+import hashlib
+import json
+import re
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from hubble.settings import HOME_DIR
+
+
+def project_dir(root: Path) -> Path:
+    slug = re.sub(r"[^A-Za-z0-9]+", "-", root.name).strip("-")[:40] or "root"
+    digest = hashlib.sha1(str(root).lower().encode()).hexdigest()[:8]
+    return HOME_DIR / "projects" / f"{slug}-{digest}"
+
+
+class Session:
+    def __init__(self, path: Path, session_id: str):
+        self.path = path
+        self.id = session_id
+
+    def _write(self, record: Dict[str, Any]):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        record.setdefault("ts", time.time())
+        line = json.dumps(record, ensure_ascii=False) + "\n"
+        if self.path.exists() and self.path.stat().st_size:
+            with open(self.path, "rb") as f:
+                f.seek(-1, 2)
+                if f.read(1) != b"\n":
+                    line = "\n" + line  # previous write was cut off; start a fresh line
+        with open(self.path, "a", encoding="utf-8") as f:
+            f.write(line)
+
+    def append(self, message: Dict[str, Any]):
+        self._write({"type": "msg", "message": message})
+
+    def reset(self, messages: List[Dict[str, Any]]):
+        self._write({"type": "reset", "messages": messages})
+
+    def meta(self, **fields):
+        self._write({"type": "meta", **fields})
+
+
+class SessionStore:
+    def __init__(self, root: Path):
+        self.root = root
+        self.dir = project_dir(root)
+
+    def new(self, model: str) -> Session:
+        sid = time.strftime("%Y%m%d-%H%M%S") + "-" + uuid.uuid4().hex[:6]
+        session = Session(self.dir / f"{sid}.jsonl", sid)
+        session.meta(cwd=str(self.root), model=model)
+        return session
+
+    def list(self, limit: int = 20) -> List[Dict[str, Any]]:
+        if not self.dir.is_dir():
+            return []
+        files = sorted(self.dir.glob("*.jsonl"), key=lambda p: p.stat().st_mtime, reverse=True)
+        out = []
+        for p in files[:limit]:
+            messages, meta = self._replay(p)
+            first = next((m.get("content") for m in messages
+                          if m.get("role") == "user" and isinstance(m.get("content"), str)), "")
+            if not messages:
+                continue
+            out.append({"id": p.stem, "updated": p.stat().st_mtime, "model": meta.get("model"),
+                        "messages": len(messages), "title": (first or "").strip().splitlines()[0][:70] if first else ""})
+        return out
+
+    def latest(self) -> Optional[str]:
+        items = self.list(limit=1)
+        return items[0]["id"] if items else None
+
+    def load(self, session_id: str) -> Tuple[Session, List[Dict[str, Any]], Dict[str, Any]]:
+        matches = [p for p in self.dir.glob("*.jsonl") if p.stem == session_id] or \
+                  [p for p in self.dir.glob("*.jsonl") if p.stem.startswith(session_id) or session_id in p.stem]
+        if not matches:
+            raise FileNotFoundError(f"No session '{session_id}' for this project")
+        p = matches[0]
+        messages, meta = self._replay(p)
+        return Session(p, p.stem), messages, meta
+
+    @staticmethod
+    def _replay(path: Path) -> Tuple[List[Dict[str, Any]], Dict[str, Any]]:
+        messages: List[Dict[str, Any]] = []
+        meta: Dict[str, Any] = {}
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                for line in f:
+                    try:
+                        rec = json.loads(line)
+                    except ValueError:
+                        continue  # a crash can leave a partial last line
+                    kind = rec.get("type")
+                    if kind == "msg":
+                        messages.append(rec["message"])
+                    elif kind == "reset":
+                        messages = list(rec.get("messages", []))
+                    elif kind == "meta":
+                        meta.update({k: v for k, v in rec.items() if k not in ("type", "ts")})
+        except OSError:
+            pass
+        return repair_history(messages), meta
+
+
+def repair_history(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Give every assistant tool call a result, so a transcript cut mid-turn stays sendable."""
+    out: List[Dict[str, Any]] = []
+    pending: List[str] = []
+    for m in messages:
+        if pending and m.get("role") != "tool":
+            out.extend({"role": "tool", "tool_call_id": cid, "content": "Interrupted: no result recorded."}
+                       for cid in pending)
+            pending = []
+        out.append(m)
+        if m.get("role") == "assistant" and m.get("tool_calls"):
+            pending = [tc["id"] for tc in m["tool_calls"]]
+        elif m.get("role") == "tool" and m.get("tool_call_id") in pending:
+            pending.remove(m["tool_call_id"])
+    out.extend({"role": "tool", "tool_call_id": cid, "content": "Interrupted: no result recorded."}
+               for cid in pending)
+    return out

hubble/settings.py

@@ -0,0 +1,184 @@
+"""Layered settings.
+
+Precedence (later wins): built-in defaults, ~/.hubble/settings.json,
+<project>/.hubble/settings.json, <project>/.hubble/settings.local.json, CLI flags.
+Credentials come from HUBBLE_* environment variables or .env files (the older AIHUB_* names,
+from before this CLI was renamed, are still read as a fallback).
+"""
+
+import copy
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from hubble.models import DEFAULT_MODEL, PROJECT_DIR
+
+HOME_DIR = Path(os.environ.get("HUBBLE_HOME", Path.home() / ".hubble"))
+
+DEFAULTS: Dict[str, Any] = {
+    "model": DEFAULT_MODEL,
+    "base_url": "https://aihub.071129.xyz/v1",
+    "temperature": 0.3,
+    "max_tokens": 8192,
+    "context_window": 128000,
+    "auto_compact_ratio": 0.8,
+    "max_turns": 40,
+    "permission_mode": "default",
+    "persona": "code",
+    "shell": "auto",
+    "shell_timeout": 120,
+    "additional_dirs": [],
+    "shell_sandbox": "off",  # "docker" runs shell commands in an isolated, resource-capped container
+    "sandbox_image": "python:3.12-slim",
+    "sandbox_memory": "1g",
+    "sandbox_cpus": "2",
+    "sandbox_network": True,
+    "allow_secret_files": False,
+    "model_refresh_hours": 0,  # 0 = always check on startup; set hours to only recheck when stale
+    "fallback_model": "codestral-latest",
+    "show_reasoning": False,
+    "web_tools": True,
+    "web_search": {"engine": "auto"},
+    "home_animation": True,
+    "permissions": {"allow": [], "deny": []},
+}
+
+
+class ConfigError(Exception):
+    pass
+
+
+_ENV_PREFIXES = ("HUBBLE_", "AIHUB_")  # AIHUB_ is the pre-rename name, kept as a fallback
+
+
+def _read_env_file(path: Path) -> Dict[str, str]:
+    """Only HUBBLE_*/AIHUB_* keys are read, so other secrets in a .env never leak into os.environ."""
+    out: Dict[str, str] = {}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key, val = line.split("=", 1)
+                key = key.strip().removeprefix("export ").strip()
+                if key.startswith(_ENV_PREFIXES):
+                    out[key] = val.strip().strip("'\"")
+    except OSError:
+        pass
+    return out
+
+
+def _read_json(path: Path) -> Dict[str, Any]:
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError) as e:
+        raise ConfigError(f"Invalid settings file {path}: {e}")
+    if not isinstance(data, dict):
+        raise ConfigError(f"Settings file {path} must contain a JSON object")
+    return data
+
+
+def _merge(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+    for key, val in override.items():
+        if key == "permissions" and isinstance(val, dict):
+            perms = base.setdefault("permissions", {"allow": [], "deny": []})
+            for kind in ("allow", "deny"):
+                perms[kind] = list(perms.get(kind, [])) + list(val.get(kind, []))
+        elif isinstance(val, dict) and isinstance(base.get(key), dict):
+            base[key] = _merge(dict(base[key]), val)
+        else:
+            base[key] = val
+    return base
+
+
+# A cloned repository must not be able to loosen security or redirect the API key.
+NEVER_FROM_PROJECT = {"base_url", "api_key"}
+TRUSTED_ONLY = {"permission_mode", "allow_secret_files", "additional_dirs", "shell",
+                "shell_sandbox", "sandbox_network"}
+TRUST_FILE = HOME_DIR / "trusted_folders.json"
+
+
+def _trusted_folders() -> list:
+    try:
+        data = json.loads(TRUST_FILE.read_text(encoding="utf-8"))
+        return data if isinstance(data, list) else []
+    except (OSError, ValueError):
+        return []
+
+
+def is_trusted(root: Path) -> bool:
+    key = str(root.resolve()).lower()
+    return any(key == str(t).lower() or key.startswith(str(t).lower().rstrip("\\/") + os.sep)
+               for t in _trusted_folders())
+
+
+def trust_folder(root: Path):
+    folders = _trusted_folders()
+    if str(root.resolve()) not in folders:
+        folders.append(str(root.resolve()))
+    HOME_DIR.mkdir(parents=True, exist_ok=True)
+    TRUST_FILE.write_text(json.dumps(folders, indent=2), encoding="utf-8")
+
+
+def _filter_project(data: Dict[str, Any], trusted: bool, ignored: list) -> Dict[str, Any]:
+    out = {}
+    for key, val in data.items():
+        if key in NEVER_FROM_PROJECT or (key in TRUSTED_ONLY and not trusted):
+            ignored.append(key)
+            continue
+        if key == "permissions" and isinstance(val, dict) and not trusted and val.get("allow"):
+            ignored.append("permissions.allow")
+            val = {"deny": val.get("deny", [])}  # deny rules only tighten, so they always apply
+        out[key] = val
+    return out
+
+
+def load_settings(root: Path, overrides: Optional[Dict[str, Any]] = None,
+                  trusted: Optional[bool] = None) -> Dict[str, Any]:
+    if trusted is None:
+        trusted = is_trusted(root)
+    settings = copy.deepcopy(DEFAULTS)
+    settings = _merge(settings, _read_json(HOME_DIR / "settings.json"))
+    ignored: list = []
+    for path in (root / ".hubble" / "settings.json", root / ".hubble" / "settings.local.json"):
+        settings = _merge(settings, _filter_project(_read_json(path), trusted, ignored))
+    settings["_ignored_project_keys"] = sorted(set(ignored))
+    settings = _merge(settings, {k: v for k, v in (overrides or {}).items() if v is not None})
+
+    env: Dict[str, str] = {}
+    for env_file in (HOME_DIR / ".env", PROJECT_DIR / ".env"):
+        for k, v in _read_env_file(env_file).items():
+            env.setdefault(k, v)
+    env.update({k: v for k, v in os.environ.items() if k.startswith(_ENV_PREFIXES)})
+
+    if not settings.get("api_key"):
+        settings["api_key"] = env.get("HUBBLE_API_KEY") or env.get("AIHUB_API_KEY", "")
+    if overrides is None or overrides.get("base_url") is None:
+        settings["base_url"] = env.get("HUBBLE_BASE_URL") or env.get("AIHUB_BASE_URL") or settings["base_url"]
+    return settings
+
+
+def require_api_key(settings: Dict[str, Any]) -> str:
+    key = settings.get("api_key") or ""
+    if not key:
+        raise ConfigError(
+            "Missing HUBBLE_API_KEY. Set it in one of:\n"
+            f"  {PROJECT_DIR / '.env'}\n"
+            f"  {HOME_DIR / '.env'}\n"
+            "  or the environment: $env:HUBBLE_API_KEY=\"...\" (PowerShell) / export HUBBLE_API_KEY=... (bash)"
+        )
+    return key
+
+
+def save_user_setting(key: str, value: Any):
+    """Persist one value in ~/.hubble/settings.json, keeping everything else in the file."""
+    path = HOME_DIR / "settings.json"
+    data = _read_json(path)
+    data[key] = value
+    HOME_DIR.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2), encoding="utf-8")

hubble/skills.py

@@ -0,0 +1,173 @@
+"""Skills: reusable instructions the model can call itself, or the user can run with /<name>.
+
+A skill is `<name>/SKILL.md` (with resources alongside it) or a plain `<name>.md`, under
+`~/.hubble/skills/` (user, every project) or `<project>/.hubble/skills/` (project only).
+It needs `name` and `description` frontmatter; the description is what tells the model,
+and the user, when to reach for it — only the description is loaded into the system prompt,
+and the full body loads on demand, so adding skills does not bloat every request.
+"""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from hubble.settings import HOME_DIR
+from hubble.tools import Tool, ToolContext, ToolError, truncate
+
+NAME_RX = re.compile(r"^[a-z0-9][a-z0-9_-]{0,40}$")
+FRONTMATTER_RX = re.compile(r"^---\s*\n(.*?)\n---\s*\n?(.*)$", re.DOTALL)
+
+TEMPLATE = """---
+name: {name}
+description: One sentence saying what this does and, importantly, WHEN to use it (the model \
+and /help match on this). Example: "Run the project's test suite and summarize failures. Use \
+when asked to test, check or verify the code works."
+---
+
+# {title}
+
+Step-by-step instructions for the model to follow when this skill is invoked. Be concrete:
+name the exact commands, files or conventions this project uses.
+"""
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+    path: Path
+    scope: str  # "user" | "project"
+    args_hint: str = ""
+    _body: Optional[str] = field(default=None, repr=False)
+
+    def body(self) -> str:
+        if self._body is None:
+            try:
+                self._body = _parse(self.path)[1]
+            except OSError as e:
+                self._body = f"(could not read {self.path}: {e})"
+        return self._body
+
+
+def _parse(path: Path) -> tuple:
+    """Returns (frontmatter dict, body). A file with no frontmatter is treated as pure body."""
+    text = path.read_text(encoding="utf-8")
+    m = FRONTMATTER_RX.match(text)
+    if not m:
+        return {}, text
+    meta: Dict[str, str] = {}
+    for line in m.group(1).splitlines():
+        if ":" in line and not line.startswith((" ", "\t", "-")):
+            key, _, val = line.partition(":")
+            meta[key.strip().lower()] = val.strip().strip("'\"")
+    return meta, m.group(2)
+
+
+def _skill_dirs(root: Path) -> List[tuple]:
+    return [(HOME_DIR / "skills", "user"), (root / ".hubble" / "skills", "project")]
+
+
+def discover_skills(root: Path) -> List[Skill]:
+    """Project skills come after user skills and win on a name clash (more specific wins)."""
+    found: Dict[str, Skill] = {}
+    for base, scope in _skill_dirs(root):
+        if not base.is_dir():
+            continue
+        candidates = sorted(base.glob("*/SKILL.md")) + sorted(base.glob("*.md"))
+        for path in candidates:
+            name = (path.parent.name if path.name == "SKILL.md" else path.stem).lower()
+            if not NAME_RX.match(name):
+                continue
+            try:
+                meta, body = _parse(path)
+            except OSError:
+                continue
+            description = meta.get("description") or next(
+                (l.strip("# ").strip() for l in body.splitlines() if l.strip()), "") or "(no description)"
+            found[name] = Skill(name=meta.get("name", name).lower() or name, description=description,
+                                path=path, scope=scope, args_hint=meta.get("argument-hint", ""))
+    return sorted(found.values(), key=lambda s: s.name)
+
+
+def skills_prompt_block(skills: List[Skill]) -> str:
+    """Name + description only (progressive disclosure); call the skill tool for the full body."""
+    if not skills:
+        return ""
+    lines = [f'- {s.name}: {s.description}' for s in skills]
+    return ("# Skills\nReusable instructions for recurring tasks in this project. If one clearly matches "
+           "what the user asked, call the skill tool to load its full instructions before proceeding. "
+           "Do not call it speculatively; only when its description matches.\n" + "\n".join(lines))
+
+
+class SkillTool(Tool):
+    name = "skill"
+    description = ("Load the full instructions for a named skill (see the Skills section of your system "
+                   "prompt for names and descriptions). Call this before following a skill's steps.")
+    parameters = {"type": "object", "properties": {
+        "name": {"type": "string", "description": "Skill name, exactly as listed"},
+    }, "required": ["name"]}
+    kind = "read"
+
+    def __init__(self, skills: List[Skill]):
+        self.by_name = {s.name: s for s in skills}
+
+    def target(self, args):
+        return args.get("name", "")
+
+    def run(self, args, ctx):
+        skill = self.by_name.get(str(args["name"]).lower())
+        if not skill:
+            available = ", ".join(sorted(self.by_name)) or "(none)"
+            raise ToolError(f"no skill named '{args['name']}'. Available: {available}")
+        return truncate(skill.body(), 40000)
+
+
+class WriteSkillTool(Tool):
+    name = "write_skill"
+    description = ("Save a reusable skill so future sessions in this project can call it by name. Use this "
+                   "when you notice a multi-step procedure the user is likely to repeat (a release "
+                   "checklist, a debugging recipe, project-specific conventions) — not for one-off tasks. "
+                   "Ask the user before writing one unless they asked you to save it.")
+    parameters = {"type": "object", "properties": {
+        "name": {"type": "string", "description": "lowercase-with-hyphens, becomes the /name command"},
+        "description": {"type": "string",
+                        "description": "One sentence: what it does and when to use it (for matching)"},
+        "body": {"type": "string", "description": "Full instructions in Markdown"},
+        "scope": {"type": "string", "enum": ["project", "user"],
+                  "description": "project (default; this repo only) or user (every project)"},
+    }, "required": ["name", "description", "body"]}
+    kind = "edit"
+
+    def _path(self, args, ctx: ToolContext) -> Path:
+        name = str(args["name"]).lower().strip()
+        if not NAME_RX.match(name):
+            raise ToolError("name must be lowercase letters, digits, - or _ (max 41 chars)")
+        base = HOME_DIR / "skills" if args.get("scope") == "user" else ctx.root / ".hubble" / "skills"
+        return base / name / "SKILL.md"
+
+    def _content(self, args) -> str:
+        return f"---\nname: {args['name']}\ndescription: {args['description']}\n---\n\n{args['body'].strip()}\n"
+
+    def target(self, args):
+        return str(args.get("name", ""))
+
+    def preview(self, args, ctx):
+        try:
+            path = self._path(args, ctx)
+        except ToolError as e:
+            return f"(will fail: {e})"
+        old = path.read_text(encoding="utf-8") if path.is_file() else ""
+        new = self._content(args)
+        from hubble.tools import unified_diff
+        return unified_diff(old, new, str(path)) or "(no changes)"
+
+    def run(self, args, ctx: ToolContext):
+        path = self._path(args, ctx)
+        existed = path.is_file()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        ctx.snapshot(path)
+        path.write_text(self._content(args), encoding="utf-8")
+        where = "every project" if args.get("scope") == "user" else "this project"
+        return f"{'Updated' if existed else 'Saved'} skill '{args['name']}' for {where} at {path}. " \
+               f"Available immediately as /{args['name']} or the skill tool."