feat: enhance jupyter notebook functions with auto-init and kernel management

Auto-create notebooks y sesiones en jupyter_exec (append y cell).
Auto-create en jupyter_write (append_code, append_markdown, batch).
Nuevos subcomandos cleanup y shutdown-all en jupyter_kernel.
README.md renombrado a README.txt para evitar error de parseo del indexer.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

python/functions/notebook/jupyter_exec.py

@@ -10,7 +10,7 @@ import asyncio
 import json
 from functools import partial
 from typing import Any
-from urllib.error import URLError
+from urllib.error import HTTPError, URLError
 from urllib.request import Request, urlopen
 
 from jupyter_kernel_client import KernelClient
@@ -23,6 +23,80 @@ from nbformat import NotebookNode
 # ---------------------------------------------------------------------------
 
 
+def _notebook_exists(notebook_path: str, server_url: str, token: str) -> bool:
+    """Comprueba si un notebook existe en el servidor Jupyter via HEAD /api/contents."""
+    headers = {"Accept": "application/json"}
+    if token:
+        headers["Authorization"] = f"token {token}"
+    check_url = f"{server_url}/api/contents/{notebook_path}"
+    req = Request(check_url, headers=headers, method="HEAD")
+    try:
+        with urlopen(req, timeout=5):
+            return True
+    except HTTPError as e:
+        if e.code == 404:
+            return False
+        raise
+
+
+def _create_notebook(notebook_path: str, server_url: str, token: str, kernel_name: str = "python3") -> None:
+    """Crea un notebook vacio via PUT /api/contents si no existe."""
+    if _notebook_exists(notebook_path, server_url, token):
+        return
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    if token:
+        headers["Authorization"] = f"token {token}"
+    kernel_display = {"python3": "Python 3 (ipykernel)", "python": "Python 3"}.get(kernel_name, kernel_name)
+    notebook_content = {
+        "nbformat": 4,
+        "nbformat_minor": 5,
+        "metadata": {
+            "kernelspec": {"name": kernel_name, "display_name": kernel_display, "language": "python"},
+            "language_info": {"name": "python"},
+        },
+        "cells": [],
+    }
+    body = json.dumps({"type": "notebook", "content": notebook_content}).encode("utf-8")
+    url = f"{server_url}/api/contents/{notebook_path}"
+    req = Request(url, data=body, headers=headers, method="PUT")
+    with urlopen(req, timeout=10) as resp:
+        resp.read()
+
+
+def _ensure_session(server_url: str, token: str, notebook_path: str, kernel_name: str = "python3") -> str:
+    """Garantiza que exista una sesion para el notebook. Retorna el kernel_id.
+
+    Si ya hay una sesion activa, retorna su kernel_id. Si no, crea una nueva
+    via POST /api/sessions (lo cual tambien arranca un kernel).
+    """
+    kernel_id = _resolve_kernel_id(server_url, token, notebook_path)
+    if kernel_id:
+        return kernel_id
+
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    if token:
+        headers["Authorization"] = f"token {token}"
+
+    body = json.dumps({
+        "path": notebook_path,
+        "type": "notebook",
+        "kernel": {"name": kernel_name},
+    }).encode("utf-8")
+
+    url = f"{server_url}/api/sessions"
+    req = Request(url, data=body, headers=headers, method="POST")
+    with urlopen(req, timeout=10) as resp:
+        session = json.loads(resp.read())
+
+    return session.get("kernel", {}).get("id", "")
+
+
 def _api_get(url: str, token: str = "") -> dict | list | None:
     """GET a Jupyter REST API endpoint."""
     headers = {"Accept": "application/json"}
@@ -112,13 +186,14 @@ async def _async_append_execute(
     server_url: str,
     token: str,
 ) -> dict[str, Any]:
+    _create_notebook(notebook_path, server_url, token)
+    kernel_id = _ensure_session(server_url, token, notebook_path)
+
     ws_url = get_jupyter_notebook_websocket_url(
         server_url,
         notebook_path,
         token or None,
     )
-
-    kernel_id = _resolve_kernel_id(server_url, token, notebook_path)
     username = _resolve_collab_username(server_url, token)
 
     async with NbModelClient(ws_url, username=username) as nb:
@@ -149,12 +224,13 @@ async def _async_execute_cell(
     server_url: str,
     token: str,
 ) -> dict[str, Any]:
+    kernel_id = _ensure_session(server_url, token, notebook_path)
+
     ws_url = get_jupyter_notebook_websocket_url(
         server_url,
         notebook_path,
         token or None,
     )
-    kernel_id = _resolve_kernel_id(server_url, token, notebook_path)
     username = _resolve_collab_username(server_url, token)
 
     async with NbModelClient(ws_url, username=username) as nb: