nexo-brain 2.3.2 → 2.5.0

package/src/script_registry.py

@@ -0,0 +1,322 @@
+"""NEXO Script Registry — discovery, metadata, validation for personal scripts.
+
+Scripts live in NEXO_HOME/scripts/. Core scripts (from manifest) are filtered by default.
+Personal scripts use CLI as stable interface, never direct DB access.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import stat
+import subprocess
+from pathlib import Path
+
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent)))
+
+# Internal artifacts to always ignore
+_IGNORED_FILES = {
+    ".watchdog-hashes",
+    ".watchdog-fails",
+    ".watchdog-nexo-repair.lock",
+    "nexo-cron-wrapper.sh",
+}
+_IGNORED_DIRS = {"deep-sleep", "__pycache__"}
+
+# Forbidden patterns — direct DB access from personal scripts
+_FORBIDDEN_PATTERNS = [
+    re.compile(r"\bsqlite3\b"),
+    re.compile(r"\bnexo\.db\b"),
+    re.compile(r"\bcognitive\.db\b"),
+    re.compile(r"/data/nexo\.db"),
+    re.compile(r"/data/cognitive\.db"),
+    re.compile(r"\bimport\s+db\b"),
+    re.compile(r"\bfrom\s+db\s+import\b"),
+    re.compile(r"\bimport\s+cognitive\b"),
+    re.compile(r"\bfrom\s+cognitive\s+import\b"),
+]
+
+METADATA_KEYS = {"name", "description", "runtime", "timeout", "requires", "tools", "hidden"}
+
+
+def get_nexo_home() -> Path:
+    return NEXO_HOME
+
+
+def get_scripts_dir() -> Path:
+    return NEXO_HOME / "scripts"
+
+
+def load_core_script_names() -> set[str]:
+    """Load script names from crons/manifest.json (these are core, not personal)."""
+    names: set[str] = set()
+    for manifest_path in [NEXO_CODE / "crons" / "manifest.json", NEXO_HOME / "crons" / "manifest.json"]:
+        if manifest_path.exists():
+            try:
+                data = json.loads(manifest_path.read_text())
+                for cron in data.get("crons", []):
+                    script = cron.get("script", "")
+                    # script is like "scripts/nexo-immune.py" — extract filename
+                    names.add(Path(script).name)
+                break
+            except Exception:
+                continue
+    return names
+
+
+def parse_inline_metadata(path: Path) -> dict:
+    """Parse # nexo: key=value metadata from first 25 lines."""
+    meta: dict[str, str] = {}
+    try:
+        lines = path.read_text(errors="ignore").splitlines()[:25]
+    except Exception:
+        return meta
+
+    for line in lines:
+        stripped = line.strip()
+        if not stripped.startswith("# nexo:"):
+            continue
+        payload = stripped[len("# nexo:"):].strip()
+        if "=" not in payload:
+            continue
+        key, value = payload.split("=", 1)
+        k = key.strip()
+        if k in METADATA_KEYS:
+            meta[k] = value.strip()
+    return meta
+
+
+def _detect_shebang(path: Path) -> str | None:
+    """Read first line for shebang."""
+    try:
+        first = path.read_text(errors="ignore").split("\n", 1)[0]
+        if first.startswith("#!"):
+            return first
+    except Exception:
+        pass
+    return None
+
+
+def classify_runtime(path: Path, metadata: dict) -> str:
+    """Detect script runtime: python, shell, or unknown."""
+    # 1. Metadata
+    rt = metadata.get("runtime", "").lower()
+    if rt in ("python", "shell"):
+        return rt
+
+    # 2. Shebang
+    shebang = _detect_shebang(path)
+    if shebang:
+        if "python" in shebang:
+            return "python"
+        if "bash" in shebang or "/sh" in shebang:
+            return "shell"
+
+    # 3. Extension
+    ext = path.suffix.lower()
+    if ext == ".py":
+        return "python"
+    if ext == ".sh":
+        return "shell"
+
+    return "unknown"
+
+
+def _is_ignored(path: Path) -> bool:
+    """Check if file should be ignored entirely."""
+    if path.name in _IGNORED_FILES:
+        return True
+    if path.name.startswith("."):
+        return True
+    for parent in path.relative_to(get_scripts_dir()).parents:
+        if parent.name in _IGNORED_DIRS:
+            return True
+    return False
+
+
+def list_scripts(include_core: bool = False) -> list[dict]:
+    """List scripts in NEXO_HOME/scripts/.
+
+    By default only personal scripts. With include_core=True, also shows core/cron scripts.
+    """
+    scripts_dir = get_scripts_dir()
+    if not scripts_dir.is_dir():
+        return []
+
+    core_names = load_core_script_names()
+    results = []
+
+    for f in sorted(scripts_dir.iterdir()):
+        if not f.is_file():
+            continue
+        if _is_ignored(f):
+            continue
+
+        is_core = f.name in core_names
+        if is_core and not include_core:
+            continue
+
+        meta = parse_inline_metadata(f)
+        runtime = classify_runtime(f, meta)
+        name = meta.get("name", f.stem)
+        hidden = meta.get("hidden", "").lower() in ("true", "1", "yes")
+
+        if hidden and not include_core:
+            continue
+
+        results.append({
+            "name": name,
+            "runtime": runtime,
+            "description": meta.get("description", ""),
+            "path": str(f),
+            "core": is_core,
+            "metadata": meta,
+        })
+
+    return results
+
+
+def resolve_script(name: str) -> dict | None:
+    """Find a script by name (metadata name or filename stem)."""
+    scripts_dir = get_scripts_dir()
+    if not scripts_dir.is_dir():
+        return None
+
+    for f in scripts_dir.iterdir():
+        if not f.is_file() or _is_ignored(f):
+            continue
+        meta = parse_inline_metadata(f)
+        script_name = meta.get("name", f.stem)
+        if script_name == name or f.stem == name:
+            runtime = classify_runtime(f, meta)
+            return {
+                "name": script_name,
+                "runtime": runtime,
+                "description": meta.get("description", ""),
+                "path": str(f),
+                "core": f.name in load_core_script_names(),
+                "metadata": meta,
+            }
+    return None
+
+
+def resolve_script_reference(ref: str) -> dict | None:
+    """Resolve a script by name or by direct filesystem path."""
+    direct = Path(ref)
+    if direct.is_file():
+        meta = parse_inline_metadata(direct)
+        return {
+            "name": meta.get("name", direct.stem),
+            "runtime": classify_runtime(direct, meta),
+            "description": meta.get("description", ""),
+            "path": str(direct),
+            "core": direct.name in load_core_script_names(),
+            "metadata": meta,
+        }
+    return resolve_script(ref)
+
+
+def doctor_script(path_or_name: str) -> dict:
+    """Validate a single script. Returns dict with pass/warn/fail items."""
+    # Resolve
+    p = Path(path_or_name)
+    if not p.is_file():
+        info = resolve_script(path_or_name)
+        if not info:
+            return {"status": "fail", "items": [{"level": "fail", "msg": f"Script not found: {path_or_name}"}]}
+        p = Path(info["path"])
+
+    items: list[dict] = []
+    meta = parse_inline_metadata(p)
+    runtime = classify_runtime(p, meta)
+    core_names = load_core_script_names()
+    is_core = p.name in core_names
+
+    # File exists
+    if p.is_file():
+        items.append({"level": "pass", "msg": f"File exists: {p.name}"})
+    else:
+        items.append({"level": "fail", "msg": f"File missing: {p.name}"})
+        return {"status": "fail", "items": items}
+
+    # Name collision with core
+    name = meta.get("name", p.stem)
+    if not is_core:
+        for core in core_names:
+            core_stem = Path(core).stem
+            if name == core_stem:
+                items.append({"level": "fail", "msg": f"Name collision with core script: {core}"})
+
+    # Runtime recognized
+    if runtime == "unknown":
+        items.append({"level": "warn", "msg": "Runtime not recognized (no shebang, no extension match)"})
+    else:
+        items.append({"level": "pass", "msg": f"Runtime: {runtime}"})
+
+    # Shebang for shell scripts
+    if runtime == "shell":
+        shebang = _detect_shebang(p)
+        if not shebang:
+            items.append({"level": "warn", "msg": "Shell script without shebang"})
+        else:
+            items.append({"level": "pass", "msg": f"Shebang: {shebang}"})
+
+    # Executable bit for shell scripts
+    if runtime == "shell":
+        mode = p.stat().st_mode
+        if not (mode & stat.S_IXUSR):
+            items.append({"level": "warn", "msg": "Shell script missing executable bit"})
+        else:
+            items.append({"level": "pass", "msg": "Executable bit set"})
+
+    # Timeout parse
+    timeout_str = meta.get("timeout", "")
+    if timeout_str:
+        try:
+            int(timeout_str)
+            items.append({"level": "pass", "msg": f"Timeout: {timeout_str}s"})
+        except ValueError:
+            items.append({"level": "fail", "msg": f"Invalid timeout value: {timeout_str}"})
+
+    # Requires check
+    requires = meta.get("requires", "")
+    if requires:
+        for cmd in requires.split(","):
+            cmd = cmd.strip()
+            if cmd and not shutil.which(cmd):
+                items.append({"level": "fail", "msg": f"Required command not in PATH: {cmd}"})
+            elif cmd:
+                items.append({"level": "pass", "msg": f"Required command found: {cmd}"})
+
+    # Forbidden patterns (only for personal scripts)
+    if not is_core:
+        try:
+            content = p.read_text(errors="ignore")
+            for pat in _FORBIDDEN_PATTERNS:
+                match = pat.search(content)
+                if match:
+                    items.append({"level": "fail", "msg": f"Forbidden DB pattern found: {match.group()}"})
+        except Exception:
+            pass
+
+    # Determine overall status
+    levels = [i["level"] for i in items]
+    if "fail" in levels:
+        status = "fail"
+    elif "warn" in levels:
+        status = "warn"
+    else:
+        status = "pass"
+
+    return {"status": status, "items": items, "name": name, "path": str(p)}
+
+
+def doctor_all_scripts() -> list[dict]:
+    """Run doctor on all personal scripts."""
+    results = []
+    for script in list_scripts(include_core=False):
+        result = doctor_script(script["path"])
+        results.append(result)
+    return results

package/src/scripts/deep-sleep/apply_findings.py

@@ -23,6 +23,10 @@ from datetime import datetime, timedelta
 from pathlib import Path
 
 NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parents[2])))
+if str(NEXO_CODE) not in sys.path:
+    sys.path.insert(0, str(NEXO_CODE))
+
 DEEP_SLEEP_DIR = NEXO_HOME / "operations" / "deep-sleep"
 NEXO_DB = NEXO_HOME / "data" / "nexo.db"
 COGNITIVE_DB = NEXO_HOME / "data" / "cognitive.db"
@@ -236,47 +240,53 @@ def calibrate_trust_score(synthesis: dict, target_date: str) -> dict:
 
 
 def create_skill(skill_data: dict) -> dict:
-    """Create a skill in nexo.db from Deep Sleep extraction."""
-    if not NEXO_DB.exists():
-        return {"success": False, "error": "nexo.db not found"}
+    """Create a personal Skill v2 definition and sync it into SQLite."""
     try:
-        import hashlib
+        from db import materialize_personal_skill_definition
+
         skill_id = skill_data.get("id", "")
         if not skill_id:
             skill_id = "SK-DS-" + hashlib.md5(
                 skill_data.get("name", "").encode()
             ).hexdigest()[:8].upper()
 
-        name = skill_data.get("name", "")
-        description = skill_data.get("description", "")
-        tags = json.dumps(skill_data.get("tags", []))
-        trigger_patterns = json.dumps(skill_data.get("trigger_patterns", []))
-        source_sessions = json.dumps(skill_data.get("source_sessions", []))
-        steps = skill_data.get("steps", [])
-        gotchas = skill_data.get("gotchas", [])
-
-        # Build file content for the skill .md file
-        steps_md = "\n".join(f"{i+1}. {s}" for i, s in enumerate(steps))
-        gotchas_md = "\n".join(f"- {g}" for g in gotchas) if gotchas else "None"
-
-        conn = sqlite3.connect(str(NEXO_DB))
-        # Check if skill already exists
-        existing = conn.execute("SELECT id FROM skills WHERE id = ?", (skill_id,)).fetchone()
-        if existing:
-            conn.close()
-            return {"success": False, "error": f"Skill {skill_id} already exists", "id": skill_id}
-
-        now = datetime.now().isoformat(timespec='seconds')
-        conn.execute(
-            """INSERT INTO skills
-               (id, name, description, level, trust_score, tags, trigger_patterns,
-                source_sessions, linked_learnings, created_at, updated_at)
-               VALUES (?, ?, ?, 'draft', 50, ?, ?, ?, '[]', ?, ?)""",
-            (skill_id, name, description, tags, trigger_patterns, source_sessions, now, now),
+        execution_level = skill_data.get("execution_level", "")
+        scriptable = bool(skill_data.get("scriptable"))
+        mode = skill_data.get("mode", "")
+        if not mode:
+            if scriptable and execution_level == "read-only":
+                mode = "hybrid"
+            else:
+                mode = "guide"
+
+        approval_required = bool(skill_data.get("approval_required", execution_level in {"local", "remote"}))
+        script_body = str(skill_data.get("script_body", "") or "")
+        executable_entry = str(skill_data.get("executable_entry", "") or "")
+
+        result = materialize_personal_skill_definition(
+            {
+                "id": skill_id,
+                "name": skill_data.get("name", ""),
+                "description": skill_data.get("description", ""),
+                "level": skill_data.get("level", "draft"),
+                "mode": mode,
+                "execution_level": execution_level if mode != "guide" else "none",
+                "approval_required": approval_required,
+                "tags": skill_data.get("tags", []),
+                "trigger_patterns": skill_data.get("trigger_patterns", []),
+                "source_sessions": skill_data.get("source_sessions", []),
+                "steps": skill_data.get("steps", []),
+                "gotchas": skill_data.get("gotchas", []),
+                "params_schema": skill_data.get("params_schema", skill_data.get("candidate_params", {})),
+                "command_template": skill_data.get("command_template", {}),
+                "executable_entry": executable_entry,
+                "script_body": script_body,
+                "content": skill_data.get("content", ""),
+            }
         )
-        conn.commit()
-        conn.close()
-        return {"success": True, "id": skill_id, "name": name}
+        if "error" in result:
+            return {"success": False, "error": result["error"], "id": skill_id}
+        return {"success": True, "id": result["id"], "name": result.get("name", "")}
     except Exception as e:
         return {"success": False, "error": str(e)}
 
@@ -688,6 +698,26 @@ def main():
                 stats["errors"] += 1
                 print(f"  Skill error: {result.get('error', 'unknown')}", file=sys.stderr)
 
+    evolution_candidates = synthesis.get("skill_evolution_candidates", [])
+    if evolution_candidates:
+        evolution_file = DEEP_SLEEP_DIR / f"{target_date}-skill-evolution-candidates.json"
+        with open(evolution_file, "w") as f:
+            json.dump(evolution_candidates, f, indent=2, ensure_ascii=False)
+        print(f"  Skill evolution candidates: {evolution_file}")
+
+    try:
+        from skills_runtime import auto_promote_skill_evolution
+
+        promotion_result = auto_promote_skill_evolution()
+        if promotion_result.get("promoted"):
+            promotion_file = DEEP_SLEEP_DIR / f"{target_date}-skill-autopromotions.json"
+            with open(promotion_file, "w") as f:
+                json.dump(promotion_result, f, indent=2, ensure_ascii=False)
+            stats["applied"] += len(promotion_result["promoted"])
+            print(f"  Skill autopromotions: {len(promotion_result['promoted'])} → {promotion_file}")
+    except Exception as e:
+        print(f"  Skill autopromotion error: {e}", file=sys.stderr)
+
     # Create followups for abandoned projects
     abandoned_results = create_abandoned_followups(synthesis)
     for r in abandoned_results:

package/src/scripts/deep-sleep/collect.py

@@ -12,6 +12,7 @@ Environment variables:
 """
 import json
 import os
+import re
 import sqlite3
 import sys
 from datetime import datetime, timedelta
@@ -25,6 +26,32 @@ COGNITIVE_DB = NEXO_HOME / "data" / "cognitive.db"
 
 MIN_USER_MESSAGES = 3  # Skip trivial sessions
 
+# Patterns that indicate sensitive data (passwords, tokens, API keys, etc.)
+_SENSITIVE_PATTERNS = re.compile(
+    r'(?:'
+    r'sk-ant-[A-Za-z0-9_-]+'           # Anthropic API keys
+    r'|shpat_[A-Fa-f0-9]+'             # Shopify admin tokens
+    r'|shpss_[A-Fa-f0-9]+'             # Shopify shared secret
+    r'|sk-[A-Za-z0-9]{20,}'            # OpenAI-style keys
+    r'|ghp_[A-Za-z0-9]{36,}'           # GitHub PATs
+    r'|gho_[A-Za-z0-9]{36,}'           # GitHub OAuth tokens
+    r'|AIza[A-Za-z0-9_-]{35}'          # Google API keys
+    r'|ya29\.[A-Za-z0-9_-]+'           # Google OAuth tokens
+    r'|xox[bpsa]-[A-Za-z0-9-]+'        # Slack tokens
+    r'|EAAG[A-Za-z0-9]+'              # Meta/Facebook tokens
+    r'|[Pp]assword\s*[:=]\s*\S+'       # password: value or password=value
+    r'|[Ss]ecret\s*[:=]\s*\S+'         # secret: value
+    r'|[Tt]oken\s*[:=]\s*\S+'          # token: value
+    r'|[Aa]pi[_-]?[Kk]ey\s*[:=]\s*\S+'  # api_key: value
+    r')'
+)
+
+
+def _redact_sensitive(text: str) -> str:
+    """Replace sensitive patterns in text with [REDACTED]."""
+    return _SENSITIVE_PATTERNS.sub('[REDACTED]', text)
+
+
 # ── Transcript collection (kept from collect_transcripts.py) ──────────────
 
 
@@ -67,7 +94,7 @@ def extract_session(jsonl_path: Path) -> dict | None:
                         messages.append({
                             "role": "user",
                             "index": line_no,
-                            "text": content[:5000],
+                            "text": _redact_sensitive(content[:5000]),
                             "uuid": d.get("uuid", "")
                         })
                         user_msg_count += 1
@@ -83,16 +110,18 @@ def extract_session(jsonl_path: Path) -> dict | None:
                                 text_parts.append(block.get("text", ""))
                             elif block.get("type") == "tool_use":
                                 tool_input = block.get("input", {})
+                                raw_file = (
+                                    tool_input.get("file_path", "")
+                                    or str(tool_input.get("command", ""))[:100]
+                                ) if isinstance(tool_input, dict) else ""
                                 tool_uses.append({
                                     "tool": block.get("name", ""),
                                     "input_keys": list(tool_input.keys()) if isinstance(tool_input, dict) else [],
-                                    "file": (
-                                        tool_input.get("file_path", "")
-                                        or str(tool_input.get("command", ""))[:100]
-                                    ) if isinstance(tool_input, dict) else ""
+                                    "file": _redact_sensitive(raw_file)
                                 })
                     if text_parts:
                         combined = "\n".join(text_parts)[:5000]
+                        combined = _redact_sensitive(combined)
                         messages.append({
                             "role": "assistant",
                             "index": line_no,
@@ -332,12 +361,12 @@ def format_transcripts(sessions: list[dict]) -> str:
             role = "USER" if msg["role"] == "user" else "AGENT"
             idx = msg.get("index", "?")
             lines.append(f"\n[{role} @{idx}]")
-            lines.append(msg["text"])
+            lines.append(_redact_sensitive(msg["text"]))
 
         if session["tool_uses"]:
             lines.append(f"\n  -- Tool usage log --")
             for tu in session["tool_uses"]:
-                file_info = f" [{tu['file'][:80]}]" if tu.get("file") else ""
+                file_info = f" [{_redact_sensitive(tu['file'][:80])}]" if tu.get("file") else ""
                 lines.append(f"  - {tu['tool']}{file_info}")
 
     return "\n".join(lines)
@@ -447,12 +476,12 @@ def main():
             role = "USER" if msg["role"] == "user" else "AGENT"
             idx = msg.get("index", "?")
             lines.append(f"\n[{role} @{idx}]")
-            lines.append(msg["text"])
+            lines.append(_redact_sensitive(msg["text"]))
 
         if session["tool_uses"]:
             lines.append(f"\n  -- Tool usage log --")
             for tu in session["tool_uses"]:
-                file_info = f" [{tu['file'][:80]}]" if tu.get("file") else ""
+                file_info = f" [{_redact_sensitive(tu['file'][:80])}]" if tu.get("file") else ""
                 lines.append(f"  - {tu['tool']}{file_info}")
 
         session_text = "\n".join(lines)

package/src/scripts/deep-sleep/extract-prompt.md

@@ -70,6 +70,10 @@ For each candidate, extract:
 - Tags describing the domain (e.g., "shopify", "chrome", "deploy")
 - Trigger phrases that would indicate this procedure is needed (e.g., "deploy extension", "push theme")
 - Any gotchas or warnings discovered during execution
+- Whether the procedure looks scriptable (`scriptable: true|false`)
+- Automation scope: `read-only|local|remote`
+- Candidate params if the procedure clearly has repeated inputs (e.g. store, version, environment)
+- Which steps are automatable vs still manual
 
 Only flag if the procedure was SUCCESSFUL (the task was completed without major failures).
 Do NOT flag trivial tasks (single-step actions, simple file edits, quick lookups).
@@ -223,6 +227,16 @@ Return ONLY valid JSON. No markdown code fences. No explanation text before or a
       "tags": ["domain1", "domain2"],
       "trigger_phrases": ["phrase that would trigger this", "another trigger"],
       "gotchas": ["Warning or caveat discovered during execution"],
+      "scriptable": false,
+      "automation_scope": "read-only|local|remote",
+      "candidate_params": {
+        "param_name": {
+          "type": "string|integer|number|boolean",
+          "required": true
+        }
+      },
+      "automatable_steps": ["Step that could be automated"],
+      "manual_steps": ["Step that still needs human judgment"],
       "evidence": {
         "type": "transcript",
         "session_id": "filename.jsonl",

package/src/scripts/deep-sleep/synthesize-prompt.md

@@ -10,6 +10,8 @@ FIRST: Call `nexo_startup` with `task='deep-sleep synthesis'` to initialize the
 
 Read the extractions file provided below. It contains per-session findings including corrections, self-corrected errors, unformalised ideas, missed commitments, and protocol violations.
 
+Also read the runtime skill candidate file at `{{SKILL_RUNTIME_FILE}}`. It contains mature guide skills with repeated successful usage and candidates for automatic text→script evolution.
+
 Synthesize across all sessions:
 
 ### 1. Cross-Session Patterns
@@ -79,12 +81,23 @@ Consolidate `skill_candidates` from all session extractions into publishable ski
 - Generalize: replace session-specific IDs, paths, or names with placeholders or descriptions
 - Only include skills with confidence >= 0.7
 - Check if a similar skill already exists (use `nexo_skill_match` if available) — if so, note it for merging instead of creating new
+- Prefer `mode=guide` unless there is strong evidence that some steps are safely automatable
+- NEXO is now fully autonomous. Do NOT require manual approval gates in your output.
+- When `{{SKILL_RUNTIME_FILE}}` contains mature `scriptable` candidates, prefer evolving the existing skill in place:
+  - reuse the same `id`
+  - keep the guide content, steps, gotchas, and triggers
+  - emit a concrete `script_body`
+  - set `mode=hybrid` or `mode=execute`
+  - set `execution_level` to the suggested scope (`read-only`, `local`, or `remote`)
+  - set `approval_required=false`
+- If the likely scope is `local` or `remote`, you may still emit it as executable if the procedure is concrete and repeatable. If uncertain, keep it in `skill_evolution_candidates`.
 
 For each skill, generate:
 - A unique ID starting with `SK-` (e.g., `SK-DEPLOY-CHROME-EXT`)
 - Name, description, tags, trigger_patterns
 - The full step-by-step procedure as the skill content
 - Source session IDs for traceability
+- When executable: include `command_template`, `executable_entry`, and `script_body`
 
 ### 8. Consolidated Actions
 Merge and deduplicate all findings into a final action list. Each action should have:
@@ -144,12 +157,35 @@ Return ONLY valid JSON. No markdown code fences. No explanation text.
       "tags": ["tag1", "tag2"],
       "trigger_patterns": ["trigger phrase 1", "trigger phrase 2"],
       "gotchas": ["Warning or caveat"],
+      "mode": "guide|execute|hybrid",
+      "execution_level": "none|read-only|local|remote",
+      "approval_required": false,
+      "params_schema": {
+        "param_name": {"type": "string", "required": true}
+      },
+      "command_template": {
+        "argv": ["script.py", "{{param_name}}"]
+      },
+      "executable_entry": "script.py",
+      "script_body": "#!/usr/bin/env python3\n...",
       "source_sessions": ["session1.jsonl"],
       "confidence": 0.85,
       "merge_with": null
     }
   ],
 
+  "skill_evolution_candidates": [
+    {
+      "id": "SK-EXISTING-ID",
+      "reason": "Used successfully 3+ times without major corrections",
+      "suggested_mode": "hybrid",
+      "suggested_execution_level": "read-only|local|remote",
+      "approval_required": true,
+      "params_schema": {},
+      "script_brief": "What a future script should automate"
+    }
+  ],
+
   "actions": [
     {
       "action_type": "learning_add|followup_create|skill_create|morning_briefing_item",