nexo-brain 3.2.0 → 4.0.1

package/src/system_catalog.py

@@ -3,8 +3,10 @@ from __future__ import annotations
 
 import ast
 import importlib.util
+import inspect
 import json
 import os
+import re
 import sys
 from pathlib import Path
 
@@ -28,6 +30,8 @@ SECTION_ORDER = (
     "artifacts",
 )
 
+_DOC_ARG_LINE_RE = re.compile(r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$")
+
 
 def _normalize_text(text: str | None) -> str:
     return str(text or "").strip().lower()
@@ -84,6 +88,287 @@ def _tool_category(name: str) -> str:
     return "general"
 
 
+def _annotation_text_from_ast(node: ast.AST | None) -> str:
+    if node is None:
+        return ""
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return ""
+
+
+def _literal_text(value) -> str:
+    if value is inspect._empty:
+        return ""
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if value is None:
+        return "None"
+    return repr(value)
+
+
+def _default_text_from_ast(node: ast.AST | None) -> str:
+    if node is None:
+        return ""
+    try:
+        return _literal_text(ast.literal_eval(node))
+    except Exception:
+        try:
+            return ast.unparse(node)
+        except Exception:
+            return "..."
+
+
+def _annotation_text(annotation) -> str:
+    if annotation is inspect._empty:
+        return ""
+    if isinstance(annotation, str):
+        return annotation
+    if getattr(annotation, "__module__", "") == "builtins" and hasattr(annotation, "__name__"):
+        return str(annotation.__name__)
+    text = str(annotation)
+    return text.replace("typing.", "")
+
+
+def _parse_arg_docs(doc: str) -> dict[str, str]:
+    docs: dict[str, str] = {}
+    if not doc.strip():
+        return docs
+    in_args = False
+    current_arg = ""
+    for raw_line in doc.splitlines():
+        line = raw_line.rstrip()
+        stripped = line.strip()
+        if stripped in {"Args:", "Arguments:"}:
+            in_args = True
+            current_arg = ""
+            continue
+        if not in_args:
+            continue
+        if stripped and not raw_line.startswith((" ", "\t")) and stripped.endswith(":"):
+            break
+        if not stripped:
+            current_arg = ""
+            continue
+        match = _DOC_ARG_LINE_RE.match(raw_line)
+        if match:
+            current_arg = match.group(1)
+            docs[current_arg] = match.group(2).strip()
+            continue
+        if current_arg:
+            docs[current_arg] = f"{docs[current_arg]} {stripped}".strip()
+    return docs
+
+
+def _build_signature(name: str, params: list[dict], return_annotation: str = "") -> str:
+    pieces: list[str] = []
+    for param in params:
+        part = param["name"]
+        if param.get("annotation"):
+            part += f": {param['annotation']}"
+        if not param.get("required", False):
+            part += f" = {param.get('default', '')}"
+        pieces.append(part)
+    signature = f"{name}({', '.join(pieces)})"
+    if return_annotation:
+        signature += f" -> {return_annotation}"
+    return signature
+
+
+def _example_value_for_param(param: dict) -> str:
+    name = str(param.get("name", "value"))
+    annotation = str(param.get("annotation", "")).lower()
+    if name == "id" or name.endswith("_id"):
+        return '"..."'
+    if name.endswith("_token") or name == "read_token":
+        return '"TOKEN"'
+    if "bool" in annotation:
+        return "True"
+    if "int" in annotation:
+        return "1"
+    if "float" in annotation:
+        return "1.0"
+    if "list" in annotation or name.endswith("s"):
+        return '["..."]'
+    if "dict" in annotation or "object" in annotation:
+        return '{"key": "value"}'
+    return '"..."'
+
+
+def _generic_example(name: str, params: list[dict]) -> str:
+    required = [param for param in params if param.get("required", False)]
+    if not required:
+        return f"{name}()"
+    pieces = [f"{param['name']}={_example_value_for_param(param)}" for param in required]
+    return f"{name}({', '.join(pieces)})"
+
+
+def _ast_params_for_node(node: ast.FunctionDef, arg_docs: dict[str, str]) -> list[dict]:
+    params: list[dict] = []
+    positional = list(node.args.posonlyargs) + list(node.args.args)
+    positional_defaults = [None] * (len(positional) - len(node.args.defaults)) + list(node.args.defaults)
+    for arg_node, default_node in zip(positional, positional_defaults):
+        if arg_node.arg in {"self", "cls"}:
+            continue
+        params.append(
+            {
+                "name": arg_node.arg,
+                "annotation": _annotation_text_from_ast(arg_node.annotation),
+                "required": default_node is None,
+                "default": "" if default_node is None else _default_text_from_ast(default_node),
+                "description": arg_docs.get(arg_node.arg, ""),
+            }
+        )
+    for arg_node, default_node in zip(node.args.kwonlyargs, node.args.kw_defaults):
+        if arg_node.arg in {"self", "cls"}:
+            continue
+        params.append(
+            {
+                "name": arg_node.arg,
+                "annotation": _annotation_text_from_ast(arg_node.annotation),
+                "required": default_node is None,
+                "default": "" if default_node is None else _default_text_from_ast(default_node),
+                "description": arg_docs.get(arg_node.arg, ""),
+            }
+        )
+    return params
+
+
+def _callable_params(func, arg_docs: dict[str, str]) -> list[dict]:
+    params: list[dict] = []
+    try:
+        signature = inspect.signature(func)
+    except (TypeError, ValueError):
+        return params
+    for name, param in signature.parameters.items():
+        if name in {"self", "cls"}:
+            continue
+        required = param.default is inspect._empty
+        params.append(
+            {
+                "name": name,
+                "annotation": _annotation_text(param.annotation),
+                "required": required,
+                "default": "" if required else _literal_text(param.default),
+                "description": arg_docs.get(name, ""),
+            }
+        )
+    return params
+
+
+def _guide_for_tool(name: str) -> dict[str, list]:
+    if name == "nexo_learning_add":
+        return {
+            "workflow": [
+                "Usa `applies_to` si quieres que el guard recuerde este learning antes de tocar un archivo, directorio o patrón concreto.",
+                "Usa `priority` (`critical`, `high`, `medium`, `low`) para marcar severidad operativa.",
+            ],
+            "examples": [
+                {
+                    "title": "Learning mínimo",
+                    "code": 'nexo_learning_add(category="shopify", title="Hacer pull antes de editar", content="Siempre sincronizar antes de editar el tema live.")',
+                },
+                {
+                    "title": "Learning ligado a archivo o patrón",
+                    "code": 'nexo_learning_add(category="recambios-bmw", title="Pull antes de editar theme", content="El admin puede tocar JSONs live.", applies_to="/abs/path/templates/product.json,templates/*.json,sections/*.liquid", prevention="Ejecutar `shopify theme pull` antes de editar.", priority="high")',
+                },
+            ],
+            "common_errors": [
+                "Usar `severity` en vez de `priority`.",
+                "Olvidar `title`, que es obligatorio.",
+                "No poner `applies_to` cuando quieres que el warning salte antes de tocar archivos concretos.",
+            ],
+        }
+    if name == "nexo_learning_update":
+        return {
+            "workflow": [
+                "Úsalo para completar o endurecer un learning existente cuando descubres nuevos archivos afectados, mejor `prevention` o prioridad distinta.",
+            ],
+            "examples": [
+                {
+                    "title": "Añadir alcance a un learning existente",
+                    "code": 'nexo_learning_update(id=57, applies_to="/abs/path/file.py,src/plugins/*.py", prevention="Leer schema antes del primer uso", priority="high")',
+                },
+            ],
+            "common_errors": [
+                "Intentar recrear el learning desde cero cuando basta con actualizar el existente.",
+            ],
+        }
+    if name == "nexo_reminder_get":
+        return {
+            "workflow": [
+                "Devuelve el `READ_TOKEN` necesario para `update`, `delete`, `restore` y `note` sobre ese reminder.",
+            ],
+            "examples": [
+                {
+                    "title": "Leer reminder y obtener token",
+                    "code": 'nexo_reminder_get(id="R87")',
+                },
+            ],
+            "common_errors": [
+                "Intentar editar o borrar un reminder sin llamar antes a `nexo_reminder_get`.",
+            ],
+        }
+    if name in {"nexo_reminder_update", "nexo_reminder_delete", "nexo_reminder_restore", "nexo_reminder_note"}:
+        return {
+            "workflow": [
+                "Primero llama `nexo_reminder_get(id=\"R87\")` para obtener `READ_TOKEN`.",
+                f"Luego reutiliza ese `READ_TOKEN` en `{name}(...)`.",
+            ],
+            "examples": [
+                {
+                    "title": "1. Obtener token",
+                    "code": 'nexo_reminder_get(id="R87")',
+                },
+                {
+                    "title": "2. Reutilizar READ_TOKEN",
+                    "code": f'{name}(id="R87", read_token="TOKEN")',
+                },
+            ],
+            "common_errors": [
+                "Llamar a esta tool sin `READ_TOKEN` válido.",
+                "Usar un `READ_TOKEN` de otro reminder o de una lectura antigua.",
+            ],
+        }
+    if name == "nexo_followup_get":
+        return {
+            "workflow": [
+                "Devuelve el `READ_TOKEN` necesario para `update`, `delete`, `restore` y `note` sobre ese followup.",
+            ],
+            "examples": [
+                {
+                    "title": "Leer followup y obtener token",
+                    "code": 'nexo_followup_get(id="NF45")',
+                },
+            ],
+            "common_errors": [
+                "Intentar editar o borrar un followup sin llamar antes a `nexo_followup_get`.",
+            ],
+        }
+    if name in {"nexo_followup_update", "nexo_followup_delete", "nexo_followup_restore", "nexo_followup_note"}:
+        return {
+            "workflow": [
+                "Primero llama `nexo_followup_get(id=\"NF45\")` para obtener `READ_TOKEN`.",
+                f"Luego reutiliza ese `READ_TOKEN` en `{name}(...)`.",
+            ],
+            "examples": [
+                {
+                    "title": "1. Obtener token",
+                    "code": 'nexo_followup_get(id="NF45")',
+                },
+                {
+                    "title": "2. Reutilizar READ_TOKEN",
+                    "code": f'{name}(id="NF45", read_token="TOKEN")',
+                },
+            ],
+            "common_errors": [
+                "Llamar a esta tool sin `READ_TOKEN` válido.",
+                "Usar un `READ_TOKEN` de otro followup o de una lectura antigua.",
+            ],
+        }
+    return {}
+
+
 def _parse_core_tools() -> list[dict]:
     if not SERVER_PATH.is_file():
         return []
@@ -103,44 +388,78 @@ def _parse_core_tools() -> list[dict]:
             continue
         doc = ast.get_docstring(node) or ""
         first_line = doc.strip().splitlines()[0].strip() if doc.strip() else ""
+        arg_docs = _parse_arg_docs(doc)
+        params = _ast_params_for_node(node, arg_docs)
         entries.append(
             {
                 "kind": "core_tool",
                 "name": node.name,
                 "description": first_line,
+                "doc": doc,
                 "category": _tool_category(node.name),
                 "path": str(SERVER_PATH),
                 "line": int(getattr(node, "lineno", 0) or 0),
+                "params": params,
+                "signature": _build_signature(
+                    node.name,
+                    params,
+                    _annotation_text_from_ast(node.returns),
+                ),
+                "quick_example": _generic_example(node.name, params),
                 "source": "core",
             }
         )
     return entries
 
 
-def _plugin_module_tools(filename: str, created_by: str) -> dict[str, str]:
+def _plugin_module_tools(filename: str, created_by: str) -> list[dict]:
     module_name = f"plugins.{filename[:-3]}"
     module = sys.modules.get(module_name)
     if module is None:
         plugin_dir = PLUGINS_DIR if created_by == "repo" else PERSONAL_PLUGINS_DIR
         path = Path(plugin_dir) / filename
         if not path.is_file():
-            return {}
+            return []
         try:
             spec = importlib.util.spec_from_file_location(module_name, path)
             if spec is None or spec.loader is None:
-                return {}
+                return []
             module = importlib.util.module_from_spec(spec)
             spec.loader.exec_module(module)
         except Exception:
-            return {}
+            return []
     tools = getattr(module, "TOOLS", []) or []
-    result: dict[str, str] = {}
+    result: list[dict] = []
     for item in tools:
         try:
-            _, name, description = item
+            func, name, description = item
         except Exception:
             continue
-        result[str(name)] = str(description or "")
+        doc = inspect.getdoc(func) or ""
+        arg_docs = _parse_arg_docs(doc)
+        params = _callable_params(func, arg_docs)
+        try:
+            return_annotation = _annotation_text(inspect.signature(func).return_annotation)
+        except (TypeError, ValueError):
+            return_annotation = ""
+        result.append(
+            {
+                "kind": "plugin_tool",
+                "name": str(name),
+                "description": str(description or ""),
+                "doc": doc,
+                "params": params,
+                "signature": _build_signature(
+                    str(name),
+                    params,
+                    return_annotation,
+                ),
+                "quick_example": _generic_example(str(name), params),
+                "plugin": filename,
+                "source": created_by,
+                "category": _tool_category(str(name)),
+            }
+        )
     return result
 
 
@@ -150,14 +469,17 @@ def _plugin_entries() -> list[dict]:
     for row in rows:
         filename = str(row.get("filename") or "")
         created_by = str(row.get("created_by") or row.get("source") or "repo")
-        descriptions = _plugin_module_tools(filename, created_by)
+        plugin_tools = _plugin_module_tools(filename, created_by)
+        if plugin_tools:
+            entries.extend(plugin_tools)
+            continue
         names = str(row.get("tool_names") or "").split(",")
         for name in [n.strip() for n in names if n.strip()]:
             entries.append(
                 {
                     "kind": "plugin_tool",
                     "name": name,
-                    "description": descriptions.get(name, ""),
+                    "description": "",
                     "plugin": filename,
                     "source": created_by,
                     "category": _tool_category(name),
@@ -339,13 +661,20 @@ def explain_tool(name: str) -> dict | None:
     clean = _normalize_text(name)
     if not clean:
         return None
-    exact = search_system_catalog(clean, limit=200)
-    for row in exact:
-        if _normalize_text(row.get("name")) == clean:
-            return row
-    for row in exact:
-        if clean in _normalize_text(row.get("name")):
-            return row
+    candidates = [clean]
+    if clean.startswith("mcp__nexo__"):
+        candidates.append(clean.split("mcp__nexo__", 1)[1])
+    if "__" in clean:
+        candidates.append(clean.split("__")[-1])
+    seen: set[str] = set()
+    for candidate in [item for item in candidates if item and not (item in seen or seen.add(item))]:
+        exact = search_system_catalog(candidate, limit=200)
+        for row in exact:
+            if _normalize_text(row.get("name")) == candidate:
+                return row
+        for row in exact:
+            if candidate in _normalize_text(row.get("name")):
+                return row
     return None
 
 
@@ -386,6 +715,12 @@ def format_catalog(catalog: dict, *, section: str = "", query: str = "", limit:
 def format_tool_explanation(entry: dict | None) -> str:
     if not entry:
         return "Tool/capability not found in the live system catalog."
+    params = entry.get("params") or []
+    required = [param for param in params if param.get("required")]
+    optional = [param for param in params if not param.get("required")]
+    guide = _guide_for_tool(str(entry.get("name") or ""))
+    examples = [{"title": "Quick example", "code": entry["quick_example"]}] if entry.get("quick_example") else []
+    examples.extend(guide.get("examples", []))
     lines = [
         f"CATALOG ENTRY — {entry.get('name') or entry.get('display_name')}",
         f"Section: {entry.get('_section') or entry.get('kind')}",
@@ -416,4 +751,36 @@ def format_tool_explanation(entry: dict | None) -> str:
         lines.append(f"Execution level: {entry['execution_level']}")
     if entry.get("domain"):
         lines.append(f"Domain: {entry['domain']}")
+    if entry.get("signature"):
+        lines.append(f"Signature: {entry['signature']}")
+    if required:
+        lines.append("Required args:")
+        for param in required:
+            detail = param.get("description") or "No description."
+            annotation = f" ({param['annotation']})" if param.get("annotation") else ""
+            lines.append(f"- {param['name']}{annotation}: {detail}")
+    if optional:
+        lines.append("Optional args:")
+        for param in optional:
+            detail = param.get("description") or "Optional."
+            annotation = f" ({param['annotation']})" if param.get("annotation") else ""
+            default = f" Default: {param['default']}." if param.get("default", "") != "" else ""
+            lines.append(f"- {param['name']}{annotation}: {detail}{default}")
+    if guide.get("workflow"):
+        lines.append("Workflow notes:")
+        for item in guide["workflow"]:
+            lines.append(f"- {item}")
+    if examples:
+        lines.append("Examples:")
+        for example in examples:
+            title = str(example.get("title") or "").strip()
+            code = str(example.get("code") or "").strip()
+            if title:
+                lines.append(f"- {title}")
+            if code:
+                lines.append(f"  {code}")
+    if guide.get("common_errors"):
+        lines.append("Common errors:")
+        for item in guide["common_errors"]:
+            lines.append(f"- {item}")
     return "\n".join(lines)

package/src/tools_sessions.py

@@ -542,6 +542,17 @@ def handle_heartbeat(sid: str, task: str, context_hint: str = '') -> str:
         except Exception:
             pass  # guard_log table may not exist in older installs
 
+    if context_hint and _hint_suggests_correction(context_hint):
+        try:
+            if not _recent_learning_capture_exists(conn, sid, window_seconds=300):
+                parts.append("")
+                parts.append(
+                    "⚠ LEARNING REMINDER: This looks like a user correction and no recent learning was captured. "
+                    "If it revealed a reusable pattern, write `nexo_learning_add` NOW."
+                )
+        except Exception:
+            pass  # Best-effort reminder only
+
     return "\n".join(parts)
 
 
@@ -816,6 +827,64 @@ def _hint_suggests_code_edit(hint: str) -> bool:
     return any(signal in hint_lower for signal in edit_signals)
 
 
+def _hint_suggests_correction(hint: str) -> bool:
+    """Detect explicit user correction signals in a heartbeat context hint."""
+    hint_lower = hint.lower()
+    correction_signals = [
+        "that's wrong",
+        "that is wrong",
+        "wrong approach",
+        "not like that",
+        "fix this",
+        "fix it",
+        "está mal",
+        "esta mal",
+        "mal hecho",
+        "incorrecto",
+        "te equivocas",
+        "te has equivocado",
+        "lo hiciste mal",
+        "no era eso",
+        "corrige esto",
+        "corrígelo",
+        "corrigelo",
+        "ya te dije",
+        "otra vez el mismo",
+        "de nuevo el mismo",
+        "no deberías",
+        "no deberias",
+        "shouldn't have",
+        "should not have",
+    ]
+    return any(signal in hint_lower for signal in correction_signals)
+
+
+def _recent_learning_capture_exists(conn, sid: str, window_seconds: int = 300) -> bool:
+    """Check whether a recent learning was captured manually or via protocol task close."""
+    cutoff_epoch = time.time() - window_seconds
+
+    row = conn.execute(
+        "SELECT 1 FROM learnings WHERE created_at >= ? LIMIT 1",
+        (cutoff_epoch,),
+    ).fetchone()
+    if row:
+        return True
+
+    row = conn.execute(
+        """
+        SELECT 1
+        FROM protocol_tasks
+        WHERE session_id = ?
+          AND learning_id IS NOT NULL
+          AND closed_at IS NOT NULL
+          AND CAST(strftime('%s', closed_at) AS INTEGER) >= ?
+        LIMIT 1
+        """,
+        (sid, int(cutoff_epoch)),
+    ).fetchone()
+    return bool(row)
+
+
 def _toolbox_summary(conn) -> str:
     """Quick count of available skills and behavioral learnings for startup reminder."""
     try: