superkernels 0.9.0__py3-none-any.whl

superkernel/__init__.py

@@ -0,0 +1,25 @@
+"""Local Jupyter integration for Super Kernel."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("superkernels")
+except PackageNotFoundError:
+    __version__ = "0.9.0"
+
+
+def __getattr__(name: str):
+    """Load the local ipykernel only when a client explicitly requests it."""
+    if name == "SuperKernel":
+        from superkernel.kernel import SuperKernel
+
+        return SuperKernel
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "SuperKernel",
+    "__version__",
+]

superkernel/kernel.py

@@ -0,0 +1,594 @@
+"""Jupyter kernel runtime for the kernel-cloud SSE execution API."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+import threading
+import time
+import traceback
+import uuid
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any, ClassVar, Literal
+
+import requests
+from ipykernel.kernelapp import IPKernelApp
+from ipykernel.kernelbase import Kernel
+from requests import Response
+from requests.exceptions import (
+    ChunkedEncodingError,
+    HTTPError,
+    ReadTimeout,
+    RequestException,
+    Timeout,
+)
+from requests.exceptions import (
+    ConnectionError as RequestsConnectionError,
+)
+
+from superkernel import __version__
+from superkernel.logfile import DEFAULT_LOG_FILE, append_log
+from superkernel.schema import (
+    CodeExecutionRequest,
+    CodeExecutionResumeRequest,
+    ControlRequest,
+    ControlResponse,
+)
+from superkernel.state import (
+    _delete_runtime_status,
+    _normalize_gateway_url,
+    _read_auth_token,
+    _write_runtime_status,
+)
+
+
+class StaleSuperKernelError(RuntimeError):
+    """Signal that this saved local registration cannot be used anymore."""
+
+
+AdmissionState = Literal["idle", "waiting", "admitting", "admitted"]
+
+
+class SuperKernel(Kernel):
+    """Forward notebook execution to one gateway-provisioned Super Kernel."""
+
+    implementation = "superkernel"
+    implementation_version = __version__
+    language = "python"
+    language_version = f"{sys.version_info.major}.{sys.version_info.minor}"
+    language_info: ClassVar[dict[str, str]] = {
+        "name": "python",
+        "mimetype": "text/x-python",
+        "file_extension": ".py",
+    }
+    banner = "Super Kernel — local Jupyter kernel with remote execution"
+    boot: ClassVar[dict[str, Any]] = {}
+
+    @staticmethod
+    def _session_id_from_connection_file(connection_file: str) -> str:
+        """Use Jupyter's runtime connection-file ID as the notebook identity."""
+        filename = Path(connection_file).name
+        if not filename.endswith(".json"):
+            raise RuntimeError("Jupyter connection file is unavailable")
+        session_id = filename[:-5]
+        session_id = session_id.removeprefix("kernel-")
+        if not re.fullmatch(r"[A-Za-z0-9._-]{1,128}", session_id):
+            raise RuntimeError("Jupyter connection file has an invalid kernel ID")
+        return session_id
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        config = SuperKernel.boot
+        self.gateway_url = _normalize_gateway_url(str(config["gateway_url"]))
+        self.endpoint = f"{self.gateway_url}/kernel/execute"
+        self.control_endpoint = f"{self.gateway_url}/kernel/control"
+        self.remote_kernel_id = str(config["remote_kernel_id"])
+        self.auth_file = str(config["auth_file"])
+        self.timeout = float(os.getenv("SUPERKERNEL_EXECUTION_TIMEOUT", "300"))
+        connection_file = str(
+            config.get("connection_file")
+            or getattr(self.parent, "connection_file", "")
+            or getattr(IPKernelApp.instance(), "connection_file", "")
+        )
+        self.session_id = self._session_id_from_connection_file(connection_file)
+        self._execution_lock = threading.Lock()
+        self._pending_code_digest: str | None = None
+        self._pending_execution_id: str | None = None
+        self._pending_reply_id: str | None = None
+        self._pending_cursor_id: str | None = None
+        self._admission_state: AdmissionState = "idle"
+        self._output_runner_id: str | None = None
+        self._output_stream_name: str | None = None
+        self._output_ends_with_newline = True
+        self._runner_virtual_newlines: set[tuple[str, str]] = set()
+        log_file = config.get("log_file") or os.getenv("SUPERKERNEL_LOG_FILE")
+        self._log_path = Path(log_file).expanduser() if log_file else DEFAULT_LOG_FILE
+        self._runtime_status = "idle"
+        self._last_execution_at: float | None = None
+        self._runtime_status_lock = threading.Lock()
+        self._runtime_status_stop = threading.Event()
+        self._publish_runtime_status()
+        self._runtime_status_thread = threading.Thread(
+            target=self._runtime_status_heartbeat,
+            name=f"superkernel-status-{self.session_id}",
+            daemon=True,
+        )
+        self._runtime_status_thread.start()
+
+        for message_type in ("comm_open", "comm_msg", "comm_close"):
+            self.shell_handlers[message_type] = self._ignore_comm_message
+            self.control_handlers[message_type] = self._ignore_comm_message
+
+    def _ignore_comm_message(self, _stream: Any, _idents: Any, _msg: Any) -> None:
+        return None
+
+    def _write_stream(self, name: str, text: str) -> None:
+        self.send_response(self.iopub_socket, "stream", {"name": name, "text": text})
+
+    def _write_runner_stream(self, runner_id: str, name: str, text: str) -> None:
+        """Keep interleaved runner chunks readable without buffering them."""
+        if not text:
+            return
+        runner_stream = (runner_id, name)
+        if text.startswith("\n") and runner_stream in self._runner_virtual_newlines:
+            self._runner_virtual_newlines.remove(runner_stream)
+            text = text[1:]
+            if not text:
+                return
+        if (
+            self._output_runner_id is not None
+            and runner_id != self._output_runner_id
+            and not self._output_ends_with_newline
+            and not text.startswith("\n")
+        ):
+            previous_stream = self._output_stream_name or name
+            self._write_stream(previous_stream, "\n")
+            self._runner_virtual_newlines.add((self._output_runner_id, previous_stream))
+        self._write_stream(name, text)
+        self._output_runner_id = runner_id
+        self._output_stream_name = name
+        self._output_ends_with_newline = text.endswith("\n")
+
+    def _reset_runner_stream(self) -> None:
+        self._output_runner_id = None
+        self._output_stream_name = None
+        self._output_ends_with_newline = True
+        self._runner_virtual_newlines.clear()
+
+    def _send_display_data(self, data: dict[str, Any]) -> None:
+        self.send_response(
+            self.iopub_socket,
+            "display_data",
+            {"data": data, "metadata": {}},
+        )
+
+    def _log(self, message: str) -> None:
+        try:
+            append_log(message, self._log_path)
+        except Exception:  # noqa: BLE001, S110 - logging must never break execution
+            pass
+
+    def _publish_runtime_status(self) -> None:
+        try:
+            with self._runtime_status_lock:
+                status = self._runtime_status
+                last_execution_at = self._last_execution_at
+            _write_runtime_status(
+                self.gateway_url,
+                self.remote_kernel_id,
+                self.session_id,
+                status,
+                last_execution_at,
+            )
+        except Exception as exc:  # noqa: BLE001 - status must not break the kernel
+            self._log(
+                f"Local runtime status update failed: {type(exc).__name__}: {exc}"
+            )
+
+    def _set_runtime_status(self, status: str) -> None:
+        with self._runtime_status_lock:
+            self._runtime_status = status
+            if status == "busy":
+                self._last_execution_at = time.time()
+        self._publish_runtime_status()
+
+    def _runtime_status_heartbeat(self) -> None:
+        while not self._runtime_status_stop.wait(5.0):
+            self._publish_runtime_status()
+
+    def _execution_id(self, code: str) -> str:
+        digest = hashlib.sha256(code.encode("utf-8")).hexdigest()
+        if self._pending_code_digest == digest and self._pending_execution_id:
+            return self._pending_execution_id
+        self._pending_code_digest = digest
+        self._pending_execution_id = f"exec_{uuid.uuid4().hex}"
+        self._pending_reply_id = None
+        self._pending_cursor_id = None
+        return self._pending_execution_id
+
+    def _clear_pending_execution(self) -> None:
+        self._pending_code_digest = None
+        self._pending_execution_id = None
+        self._pending_reply_id = None
+        self._pending_cursor_id = None
+        self._admission_state = "idle"
+
+    @staticmethod
+    def _iter_sse(response: Response) -> Iterator[dict[str, str]]:
+        """Parse one HTTP response into SSE frames."""
+        response.encoding = "utf-8"
+        fields: dict[str, str] = {}
+        data_lines: list[str] = []
+        for line in response.iter_lines(decode_unicode=True, chunk_size=1):
+            if line == "":
+                if fields or data_lines:
+                    fields["data"] = "\n".join(data_lines)
+                    yield fields
+                fields = {}
+                data_lines = []
+                continue
+            if not line or line.startswith(":"):
+                continue
+            name, separator, value = line.partition(":")
+            if not separator:
+                value = ""
+            elif value.startswith(" "):
+                value = value[1:]
+            if name == "data":
+                data_lines.append(value)
+            else:
+                fields[name] = value
+        if fields or data_lines:
+            fields["data"] = "\n".join(data_lines)
+            yield fields
+
+    def _handle_sse_frame(self, frame: dict[str, str]) -> tuple[str | None, bool]:
+        """Render one SSE frame and return terminal status/error state."""
+        event_type = frame.get("event", "message")
+        try:
+            payload = json.loads(frame.get("data", "{}"))
+        except json.JSONDecodeError as exc:
+            raise RuntimeError(f"Gateway sent invalid SSE JSON: {exc}") from exc
+
+        if event_type in {"runner_execution_started", "runner_execution_finished"}:
+            return None, False
+
+        if event_type in {"result", "stream"}:
+            data = str(payload.get("data") or "")
+            if data:
+                stream = str(payload.get("stream") or "stdout")
+                self._write_runner_stream(
+                    str(payload.get("runner_id") or ""),
+                    "stderr" if stream == "stderr" else "stdout",
+                    data if event_type == "stream" else data.rstrip("\n") + "\n",
+                )
+            return None, str(payload.get("status") or "success") != "success"
+
+        if event_type == "execution_finished":
+            succeeded = str(payload.get("status") or "") == "success"
+            return "completed" if succeeded else "failed", not succeeded
+
+        if event_type == "error":
+            return "failed", True
+
+        raise RuntimeError(f"Gateway sent unsupported SSE event: {event_type}")
+
+    def _stream_execute(self, request: CodeExecutionRequest) -> bool:
+        """Admit locally queued code once, then resume its stable reply stream."""
+        deadline = time.monotonic() + self.timeout
+        reply_id = self._pending_reply_id
+        last_event_id = self._pending_cursor_id
+        self._admission_state = "admitted" if reply_id is not None else "waiting"
+        execution_failed = False
+
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise Timeout(
+                    "Execution did not reach a terminal status before the timeout; "
+                    "rerun the same cell to reconnect"
+                )
+            headers = {
+                "Accept": "text/event-stream",
+                "Content-Type": "application/json",
+            }
+            access_token = _read_auth_token(self.auth_file)
+            headers["Authorization"] = f"Bearer {access_token}"
+            if last_event_id is not None:
+                headers["Last-Event-ID"] = str(last_event_id)
+            body = (
+                CodeExecutionResumeRequest(
+                    kernel_id=self.remote_kernel_id,
+                    reply_id=reply_id,
+                ).model_dump(mode="json")
+                if reply_id is not None
+                else request.model_dump(mode="json")
+            )
+            self._log(
+                f"POST {self.endpoint} remote_kernel_id={self.remote_kernel_id} "
+                f"execution_id={request.execution_id} reply_id={reply_id} "
+                f"reconnect_after={last_event_id} "
+                f"code_length={len(request.code)}"
+            )
+            try:
+                if reply_id is None:
+                    # The Gateway may admit this request before its response
+                    # reaches us, so interruption is remote-best-effort while
+                    # the initial request is in flight.
+                    self._admission_state = "admitting"
+                with requests.post(
+                    self.endpoint,
+                    headers=headers,
+                    json=body,
+                    stream=True,
+                    timeout=(10.0, min(60.0, max(1.0, remaining))),
+                ) as response:
+                    if response.status_code == 409:
+                        try:
+                            detail = str(response.json().get("detail") or "")
+                        except (TypeError, ValueError):
+                            detail = ""
+                        if detail == "kernel_busy" and reply_id is None:
+                            self._admission_state = "waiting"
+                            retry_after = response.headers.get("Retry-After", "1")
+                            try:
+                                delay = min(5.0, max(0.05, float(retry_after)))
+                            except ValueError:
+                                delay = 1.0
+                            time.sleep(min(delay, max(0.01, remaining)))
+                            continue
+                    if response.status_code in {408, 425, 429, 502, 503, 504}:
+                        time.sleep(min(1.0, max(0.01, remaining)))
+                        continue
+                    response.raise_for_status()
+                    response_reply_id = response.headers.get("SuperKernel-Reply-ID")
+                    if not response_reply_id:
+                        raise RuntimeError(
+                            "Gateway omitted the execution reply identifier"
+                        )
+                    if reply_id is not None and response_reply_id != reply_id:
+                        raise RuntimeError(
+                            "Gateway changed the execution reply identifier"
+                        )
+                    reply_id = response_reply_id
+                    self._pending_reply_id = reply_id
+                    self._admission_state = "admitted"
+                    content_type = response.headers.get("content-type", "")
+                    if not content_type.lower().startswith("text/event-stream"):
+                        raise RuntimeError(
+                            f"Gateway returned {content_type or 'no content type'}; "
+                            "expected text/event-stream"
+                        )
+                    for frame in self._iter_sse(response):
+                        raw_event_id = frame.get("id")
+                        if raw_event_id is not None:
+                            if not raw_event_id.strip():
+                                raise RuntimeError(
+                                    "Gateway sent an invalid SSE event ID"
+                                )
+                            last_event_id = raw_event_id
+                            self._pending_cursor_id = last_event_id
+                        status, frame_failed = self._handle_sse_frame(frame)
+                        execution_failed = execution_failed or frame_failed
+                        if status is not None:
+                            # A terminal SSE frame is the execution boundary. Do not
+                            # wait for a reverse proxy to close its HTTP connection.
+                            return status == "completed" and not execution_failed
+            except HTTPError:
+                raise
+            except (ChunkedEncodingError, ReadTimeout, RequestsConnectionError):
+                if time.monotonic() >= deadline:
+                    raise
+                self._log(
+                    f"SSE reconnect execution_id={request.execution_id} "
+                    f"last_event_id={last_event_id}"
+                )
+                time.sleep(0.25)
+
+    def _post_control(
+        self,
+        action: str,
+        execution_id: str | None = None,
+    ) -> ControlResponse:
+        payload = ControlRequest(
+            action=action,
+            kernel_id=self.remote_kernel_id,
+            session_id=self.session_id,
+            execution_id=execution_id,
+        )
+        self._log(
+            f"POST {self.control_endpoint} remote_kernel_id={self.remote_kernel_id} "
+            f"action={action} execution_id={execution_id}"
+        )
+        headers = {"Content-Type": "application/json"}
+        access_token = _read_auth_token(self.auth_file)
+        headers["Authorization"] = f"Bearer {access_token}"
+        response = requests.post(
+            self.control_endpoint,
+            headers=headers,
+            json=payload.model_dump(mode="json"),
+            timeout=(10.0, min(30.0, self.timeout)),
+        )
+        response.raise_for_status()
+        return ControlResponse.model_validate(response.json())
+
+    def _interrupt_pending_execution(self, execution_id: str) -> None:
+        """Cancel a local wait or best-effort interrupt possible remote work."""
+        if self._admission_state == "waiting":
+            self._log(f"Local admission wait cancelled execution_id={execution_id}")
+            return
+        try:
+            self._post_control("interrupt", execution_id)
+        except Exception as exc:  # noqa: BLE001 - interruption is best effort
+            self._log(f"Super Kernel interrupt failed: {type(exc).__name__}: {exc}")
+
+    def do_execute(
+        self,
+        code: str,
+        silent: bool,
+        store_history: bool = True,
+        user_expressions: dict[str, Any] | None = None,
+        allow_stdin: bool = False,
+    ) -> dict[str, Any]:
+        # Keep the remote stream strictly aligned with Jupyter's local kernel.
+        # This also protects direct/concurrent callers outside the shell loop.
+        with self._execution_lock:
+            return self._do_execute(
+                code,
+                silent,
+                store_history,
+                user_expressions,
+                allow_stdin,
+            )
+
+    def _do_execute(
+        self,
+        code: str,
+        silent: bool,
+        store_history: bool = True,
+        user_expressions: dict[str, Any] | None = None,
+        allow_stdin: bool = False,
+    ) -> dict[str, Any]:
+        if silent or not code.strip():
+            return self._reply("ok")
+        self._set_runtime_status("busy")
+        self._reset_runner_stream()
+        execution_id = self._execution_id(code)
+        request = CodeExecutionRequest(
+            kernel_id=self.remote_kernel_id,
+            execution_id=execution_id,
+            session_id=self.session_id,
+            execution_count=self.execution_count,
+            code=code,
+        )
+        try:
+            succeeded = self._stream_execute(request)
+        except KeyboardInterrupt:
+            self._interrupt_pending_execution(execution_id)
+            self._write_stream("stderr", "[Super Kernel] Execution interrupted.\n")
+            self._clear_pending_execution()
+            self._set_runtime_status("idle")
+            return self._reply("abort")
+        except RequestException as exc:
+            self._log(f"Gateway request failed: {type(exc).__name__}: {exc}")
+            self._write_stream("stderr", "[Super Kernel] Error.\n")
+            self._set_runtime_status("error")
+            if (
+                isinstance(exc, HTTPError)
+                and exc.response is not None
+                and exc.response.status_code in {401, 404}
+            ):
+                return self._reply(
+                    "error",
+                    StaleSuperKernelError("Saved Super Kernel is unavailable"),
+                )
+            return self._reply("error", RuntimeError("Error"))
+        except Exception as exc:  # noqa: BLE001 - kernel protocol boundary
+            self._log(
+                f"Execution failed: {type(exc).__name__}: {exc}\n"
+                f"{traceback.format_exc()}"
+            )
+            self._write_stream("stderr", "[Super Kernel] Error.\n")
+            self._set_runtime_status("error")
+            return self._reply("error", RuntimeError("Error"))
+
+        self._clear_pending_execution()
+        if succeeded:
+            self._set_runtime_status("idle")
+            return self._reply("ok")
+        self._write_stream("stderr", "[Super Kernel] Error.\n")
+        self._set_runtime_status("error")
+        error = RuntimeError("Error")
+        return self._reply("error", error)
+
+    def _reply(self, status: str, error: Exception | None = None) -> dict[str, Any]:
+        reply: dict[str, Any] = {
+            "status": status,
+            "execution_count": self.execution_count,
+            "payload": [],
+            "user_expressions": {},
+        }
+        if status == "error" and error is not None:
+            reply.update(
+                {
+                    "ename": type(error).__name__,
+                    "evalue": str(error),
+                    "traceback": [],
+                }
+            )
+        return reply
+
+    def do_shutdown(self, restart: bool = False) -> dict[str, Any]:
+        """Reset remote session state for restart, then stop the local process."""
+        if restart:
+            try:
+                self._post_control("restart")
+            except Exception as exc:  # noqa: BLE001 - shutdown must complete
+                self._log(f"Super Kernel restart failed: {type(exc).__name__}: {exc}")
+            self._clear_pending_execution()
+        self._runtime_status_stop.set()
+        try:
+            _delete_runtime_status(
+                self.gateway_url,
+                self.remote_kernel_id,
+                self.session_id,
+            )
+        except Exception as exc:  # noqa: BLE001 - shutdown must complete
+            self._log(
+                f"Local runtime status cleanup failed: {type(exc).__name__}: {exc}"
+            )
+        return {"status": "ok", "restart": restart}
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m superkernel.kernel",
+        description="Launch a local Jupyter kernel bound to one Super Kernel ID.",
+    )
+    parser.add_argument("--gateway-url", required=True)
+    parser.add_argument("--remote-kernel-id", required=True)
+    parser.add_argument(
+        "--auth-file",
+        required=True,
+        help="Private UI-managed auth.json file",
+    )
+    return parser
+
+
+def _connection_file_argument(argv: list[str]) -> str:
+    """Return the runtime connection file selected by Jupyter."""
+    for index, argument in enumerate(argv):
+        if argument in {"-f", "--IPKernelApp.connection_file"}:
+            if index + 1 >= len(argv):
+                break
+            return argv[index + 1]
+        for prefix in ("--f=", "--IPKernelApp.connection_file="):
+            if argument.startswith(prefix):
+                return argument[len(prefix) :]
+    raise SystemExit("Jupyter connection file is required")
+
+
+def main(argv: list[str] | None = None) -> None:
+    args, remaining = _build_arg_parser().parse_known_args(
+        argv if argv is not None else sys.argv[1:]
+    )
+    try:
+        _read_auth_token(args.auth_file)
+    except RuntimeError as exc:
+        raise SystemExit(str(exc)) from exc
+    SuperKernel.boot = {
+        "gateway_url": args.gateway_url,
+        "remote_kernel_id": args.remote_kernel_id,
+        "auth_file": args.auth_file,
+        "connection_file": _connection_file_argument(remaining),
+    }
+    IPKernelApp.launch_instance(kernel_class=SuperKernel, argv=remaining)
+
+
+if __name__ == "__main__":
+    main()

superkernel/logfile.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import datetime as dt
+import sys
+from pathlib import Path
+
+DEFAULT_LOG_FILE = Path("/var/superkernel.log")
+
+PathLike = str | Path
+
+
+def append_log(message: str, log_path: PathLike | None = DEFAULT_LOG_FILE) -> None:
+    """
+    Append a timestamped message to the log file.
+    Silently ignores filesystem errors so logging never breaks core flows.
+    """
+    if log_path is None:
+        log_path = DEFAULT_LOG_FILE
+    path = Path(log_path).expanduser()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        stamp = dt.datetime.now(dt.timezone.utc).isoformat(timespec="milliseconds")
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(f"[{stamp}] {message}\n")
+    except OSError as exc:
+        sys.stderr.write(f"[Super Kernel] Failed to write log entry: {exc}\n")

superkernel/schema.py

@@ -0,0 +1,179 @@
+"""Shared models for the Super Kernel Gateway contract."""
+
+from __future__ import annotations
+
+import datetime as dt
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+KernelType = Literal["base", "mpi", "torch"]
+
+
+class AuthRequest(BaseModel):
+    """API-key login request sent only to ``POST /auth``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    method: Literal["api_key"] = "api_key"
+
+
+class AuthResponse(BaseModel):
+    """Reusable Gateway session shared by infrastructure and kernel calls."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    access_token: str = Field(min_length=1)
+    token_type: Literal["Bearer"] = "Bearer"
+    auth_method: Literal["api_key"] = "api_key"
+    user_id: str = Field(min_length=1, max_length=320)
+    expires_at: dt.datetime
+
+
+class RuntimeDescriptor(BaseModel):
+    """One runtime image available through ``POST /infra/status``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: KernelType
+    name: str = Field(min_length=1, max_length=64)
+
+
+class ResourceAmount(BaseModel):
+    """One resource limit and its current reservation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    limit: int = Field(ge=0)
+    used: int = Field(ge=0)
+    available: int = Field(ge=0)
+    unit: Literal["count", "bytes"]
+
+
+class UserResourceResponse(BaseModel):
+    """Authenticated user's resource limits and reservations."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    vcpu: ResourceAmount
+    memory: ResourceAmount | None = None
+    gpu: ResourceAmount
+    block: ResourceAmount
+    bucket: ResourceAmount
+
+
+class InfraKernelCreateRequest(BaseModel):
+    """Idempotent kernel specification for ``POST /infra/kernel/create``."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    request_id: str = Field(min_length=1, max_length=128)
+    name: str = Field(min_length=1, max_length=128)
+    kernel_type: KernelType = Field(alias="type")
+    runtime: str = Field(min_length=1, max_length=64)
+    nodes: int = Field(default=1, ge=1, le=32)
+    vcpu_per_node: int = Field(default=1, ge=1, le=64)
+    memory_per_vcpu_gb: int = Field(default=1, ge=1, le=128)
+
+
+class InfraKernelActionRequest(BaseModel):
+    """Kernel identity for one infrastructure lifecycle mutation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kernel_id: str = Field(min_length=1, max_length=128)
+
+
+class InfraKernelResponse(BaseModel):
+    """Infrastructure create/start/stop/delete result."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kernel_id: str = Field(min_length=1)
+    status: Literal["ready", "paused", "deleted"]
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class InfraKernelStatus(BaseModel):
+    """One owned kernel returned in the infrastructure status snapshot."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kernel_id: str = Field(min_length=1)
+    request_id: str = Field(min_length=1)
+    name: str = Field(min_length=1)
+    type: KernelType
+    runtime: str = Field(min_length=1)
+    nodes: int = Field(ge=1)
+    vcpu_per_node: int = Field(ge=1)
+    memory_per_vcpu_gb: int = Field(ge=1)
+    status: Literal["idle", "busy", "degraded", "unavailable", "paused"]
+    generation: int = Field(ge=1)
+    healthy_runners: int = Field(ge=0)
+    busy_runners: int = Field(ge=0)
+    idle_runners: int = Field(ge=0)
+    expected_runners: int = Field(ge=1)
+
+
+class InfraStatusResponse(BaseModel):
+    """Complete plugin-facing Gateway snapshot."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    user_id: str = Field(min_length=1, max_length=320)
+    resources: UserResourceResponse
+    runtimes: list[RuntimeDescriptor]
+    kernels: list[InfraKernelStatus]
+    updated_at: dt.datetime
+
+
+class CodeExecutionRequest(BaseModel):
+    """Initial cell admission sent to ``POST /kernel/execute``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    mode: Literal["execute"] = "execute"
+    kernel_id: str = Field(min_length=1, max_length=128)
+    execution_id: str = Field(min_length=1, max_length=128)
+    code: str = Field(min_length=1, max_length=1_000_000)
+    execution_count: int | None = None
+    session_id: str = Field(min_length=1, max_length=128)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    def require_code(self) -> str:
+        """Return non-empty code for the execution handler."""
+        if not self.code.strip():
+            raise ValueError("code cannot be empty")
+        return self.code
+
+
+class CodeExecutionResumeRequest(BaseModel):
+    """SSE replay attachment for one already-admitted execution."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    mode: Literal["resume"] = "resume"
+    kernel_id: str = Field(min_length=1, max_length=128)
+    reply_id: str = Field(pattern=r"^skr_[A-Za-z0-9_-]{16,128}$")
+
+
+class ControlRequest(BaseModel):
+    """Body sent by ``superkernel.kernel`` to ``POST /kernel/control``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    action: Literal["interrupt", "restart"]
+    kernel_id: str = Field(min_length=1, max_length=128)
+    session_id: str | None = Field(default=None, min_length=1, max_length=128)
+    execution_id: str | None = Field(default=None, min_length=1, max_length=128)
+
+
+class ControlResponse(BaseModel):
+    """Synchronous kernel-control result."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kernel_id: str
+    action: Literal["interrupt", "restart"]
+    status: Literal["interrupted", "idle", "restarted"]
+    execution_id: str | None = None

superkernel/state.py

@@ -0,0 +1,150 @@
+"""Private local state access required by the SuperKernel runtime."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import stat
+import time
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+REMOTE_KERNEL_ID_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
+LOCAL_SESSION_ID_PATTERN = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+
+
+def _shared_state_dir() -> Path:
+    configured = os.getenv("SUPERKERNEL_HOME", "").strip()
+    return Path(configured).expanduser() if configured else Path.home() / ".superkernel"
+
+
+def _normalize_gateway_url(value: str) -> str:
+    parsed = urlsplit(value.strip())
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise RuntimeError("Invalid Super Kernel Gateway URL")
+    if parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise RuntimeError("Invalid Super Kernel Gateway URL")
+    path = parsed.path.rstrip("/")
+    return urlunsplit((parsed.scheme.lower(), parsed.netloc.lower(), path, "", ""))
+
+
+def _gateway_id(gateway_url: str) -> str:
+    normalized = _normalize_gateway_url(gateway_url)
+    return f"gw_{hashlib.sha256(normalized.encode()).hexdigest()[:16]}"
+
+
+def _validate_remote_kernel_id(remote_kernel_id: str) -> str:
+    if not REMOTE_KERNEL_ID_PATTERN.fullmatch(remote_kernel_id):
+        raise RuntimeError("Invalid remote Super Kernel ID")
+    return remote_kernel_id
+
+
+def _ensure_private_directory(path: Path) -> Path:
+    try:
+        details = path.lstat()
+    except FileNotFoundError:
+        path.mkdir(parents=True, exist_ok=False, mode=0o700)
+        details = path.lstat()
+    if (
+        not stat.S_ISDIR(details.st_mode)
+        or stat.S_ISLNK(details.st_mode)
+        or details.st_uid != os.geteuid()
+    ):
+        raise RuntimeError("Unsafe Super Kernel state directory")
+    path.chmod(0o700)
+    return path
+
+
+def _read_auth_token(auth_file: str) -> str:
+    """Read the current UI-provisioned Gateway session without caching it."""
+    path = Path(auth_file).expanduser()
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        descriptor = os.open(path, flags)
+    except FileNotFoundError as exc:
+        raise RuntimeError("Super Kernel authentication is unavailable") from exc
+    try:
+        details = os.fstat(descriptor)
+        if not stat.S_ISREG(details.st_mode):
+            raise RuntimeError("Invalid Super Kernel auth file")
+        if details.st_uid != os.geteuid() or stat.S_IMODE(details.st_mode) & 0o077:
+            raise RuntimeError("Unsafe Super Kernel auth file permissions")
+        with os.fdopen(descriptor, encoding="utf-8") as stream:
+            descriptor = -1
+            payload = json.load(stream)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        raise RuntimeError("Cannot read Super Kernel authentication") from exc
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+    token = payload.get("access_token") if isinstance(payload, dict) else None
+    if not isinstance(token, str) or not token:
+        raise RuntimeError("Super Kernel authentication is unavailable")
+    return token
+
+
+def _runtime_status_file(
+    gateway_url: str,
+    remote_kernel_id: str,
+    session_id: str,
+) -> Path:
+    if not LOCAL_SESSION_ID_PATTERN.fullmatch(session_id):
+        raise RuntimeError("Invalid local Super Kernel session ID")
+    return (
+        _shared_state_dir()
+        / _gateway_id(gateway_url)
+        / "runtime"
+        / _validate_remote_kernel_id(remote_kernel_id)
+        / f"{session_id}.json"
+    )
+
+
+def _write_runtime_status(
+    gateway_url: str,
+    remote_kernel_id: str,
+    session_id: str,
+    status: str,
+    last_execution_at: float | None = None,
+) -> None:
+    """Publish a non-secret runtime observation for both plugin UIs."""
+    if status not in {"idle", "busy", "error"}:
+        raise RuntimeError("Invalid local Super Kernel status")
+    root = _ensure_private_directory(_shared_state_dir())
+    gateway_dir = _ensure_private_directory(root / _gateway_id(gateway_url))
+    runtime_dir = _ensure_private_directory(gateway_dir / "runtime")
+    kernel_dir = _ensure_private_directory(
+        runtime_dir / _validate_remote_kernel_id(remote_kernel_id)
+    )
+    status_file = _runtime_status_file(gateway_url, remote_kernel_id, session_id)
+    temporary = kernel_dir / (f".{status_file.name}.{os.getpid()}.{time.time_ns()}.tmp")
+    temporary.write_text(
+        json.dumps(
+            {
+                "version": 1,
+                "gateway_url": _normalize_gateway_url(gateway_url),
+                "remote_kernel_id": remote_kernel_id,
+                "session_id": session_id,
+                "status": status,
+                "updated_at": time.time(),
+                "last_execution_at": last_execution_at,
+                "pid": os.getpid(),
+            }
+        ),
+        encoding="utf-8",
+    )
+    temporary.chmod(0o600)
+    os.replace(temporary, status_file)
+    status_file.chmod(0o600)
+
+
+def _delete_runtime_status(
+    gateway_url: str,
+    remote_kernel_id: str,
+    session_id: str,
+) -> None:
+    try:
+        _runtime_status_file(gateway_url, remote_kernel_id, session_id).unlink()
+    except FileNotFoundError:
+        pass

superkernels-0.9.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: superkernels
+Version: 0.9.0
+Summary: A local ipykernel adapter for remote Super Kernel runtimes.
+Author-email: Leo Li <leoustc@icloud.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://superkernel.leoustc.com
+Project-URL: Source, https://github.com/leoustc/collection-pip/tree/main/jupyter-superkernel/superkernel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Jupyter
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipykernel>=6.29
+Requires-Dist: pydantic>=2.7
+Requires-Dist: requests>=2.31
+Dynamic: license-file
+
+# SuperKernel
+
+SuperKernel brings remote compute into your daily notebook.
+
+It is a Jupyter-compatible Python kernel that connects a local notebook to a
+configured SuperKernel runtime. Your existing Jupyter tools continue to manage
+the notebook connection while code runs on the selected remote Python, MPI, or
+PyTorch environment.
+
+## Features
+
+- Works as a standard Jupyter kernel in JupyterLab and VS Code.
+- Streams remote output back to notebook cells as it is produced.
+- Preserves a separate Python namespace for each notebook session.
+- Executes cells sequentially and supports interrupt and restart actions.
+- Reconnects interrupted output streams without submitting the cell twice.
+- Keeps authentication tokens out of Jupyter kernelspecs and command-line
+  arguments.
+
+## Installation
+
+SuperKernel requires Python 3.10 or newer.
+
+```bash
+uv pip install superkernels
+```
+
+The JupyterLab or VS Code SuperKernel integration normally installs and
+configures the notebook kernels for you. A configured kernel can then be
+selected from the standard Jupyter kernel picker like any other kernel.
+
+This package contains the notebook runtime only. Gateway login, remote runtime
+creation, and local kernel registration are handled by a compatible
+SuperKernel client integration.
+
+The PyPI distribution is named `superkernels`. The Python import remains
+`superkernel`.
+
+## Python API
+
+The kernel class is available for integrations that need to inspect or extend
+the local runtime:
+
+```python
+from superkernel import SuperKernel
+```
+
+The supported process entry point for a configured Jupyter kernelspec is:
+
+```text
+python -m superkernel.kernel
+```
+
+Its connection and authentication arguments are generated by the client
+integration and are not intended to be entered manually.
+
+## Security
+
+SuperKernel reads authentication from a client-managed local file immediately
+before each remote request. Credentials are not embedded in the kernelspec,
+stored by this package, or passed directly on the process command line. The
+runtime fails closed when its authentication file is missing or invalid.
+
+## Project status
+
+Version 0.9.0 is the first public alpha release. The package is suitable for
+evaluation, but its integration contract may still evolve before 1.0.
+
+Learn more at [superkernel.leoustc.com](https://superkernel.leoustc.com).

superkernels-0.9.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+superkernel/__init__.py,sha256=J9gqF-jcfCsofgV1LuzrnLfJRmorzFLD3FqTS7Y_fNk,597
+superkernel/kernel.py,sha256=zHee5CmxM24NR7itbg7fAAp-vmSo7DhjzZ7wMh5yceA,24119
+superkernel/logfile.py,sha256=X5Aj9YJZ22mQefRTcn5Ytt-NRTV5scfHexxBq3_l1go,847
+superkernel/schema.py,sha256=pX3teOE6Ge43ghXjs_wA8zbOqmlXvmY-hSE8lreK1o8,5493
+superkernel/state.py,sha256=ochWHDg1CZaH5lTVRvcJYP11_25DVbE5RU22X5ZfMXs,5264
+superkernels-0.9.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+superkernels-0.9.0.dist-info/METADATA,sha256=yqk0F8PlGcLqh1_tv5nDoRIov1278JJaaDB87AfyfKo,3123
+superkernels-0.9.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+superkernels-0.9.0.dist-info/top_level.txt,sha256=HNX5XkyXWdMgpGp6Vfe7_jC1za5Hr6v6E7qmT_juWl4,12
+superkernels-0.9.0.dist-info/RECORD,,

superkernels-0.9.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

superkernels-0.9.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

superkernels-0.9.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+superkernel