clikernel 0.2.4__tar.gz → 0.2.6__tar.gz

{clikernel-0.2.4 → clikernel-0.2.6}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 <!-- do not remove -->
 
+## 0.2.6
+
+### New Features
+
+- Replace httpx2 exception handling with fastspec APIError in kernel restart error paths ([#42](https://github.com/AnswerDotAI/clikernel/issues/42))
+- Stop closing kernel managers on disconnect or kernel switch ([#40](https://github.com/AnswerDotAI/clikernel/issues/40))
+- Rename httpx import to httpx2 ([#39](https://github.com/AnswerDotAI/clikernel/issues/39))
+- restart now recovers when the kernel is gone by creating a fresh kernel on the same gateway, with startup files reapplied ([#38](https://github.com/AnswerDotAI/clikernel/issues/38))
+
+
+## 0.2.5
+
+### New Features
+
+- restart now re-runs startup.py and reinstalls inspectors on client-created kernels; attached kernels still restart bare ([#37](https://github.com/AnswerDotAI/clikernel/issues/37))
+
+
 ## 0.2.4
 
 ### New Features

{clikernel-0.2.4/clikernel.egg-info → clikernel-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.2.4
+Version: 0.2.6
 Summary: Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol
 Author: clikernel contributors
 License: Apache-2.0
@@ -12,7 +12,8 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastcore>=2.2.2
-Requires-Dist: jupyasyncclient>=0.2.2
+Requires-Dist: jupyasyncclient>=0.2.8
+Requires-Dist: fastspec>=0.2.2
 Requires-Dist: mcpmini>=0.0.1
 Requires-Dist: aidialog>=0.0.7
 Requires-Dist: pillow

{clikernel-0.2.4 → clikernel-0.2.6}/clikernel/__init__.py

@@ -5,7 +5,7 @@ Modules:
 - `clikernel.cli`: The stream-protocol frontend: the service on stdin/stdout for token-reading clients
 - `clikernel.core`: Connect to gateway-hosted kernels and turn execution into concise text
 - `clikernel.mcp`: The MCP frontend: `Client` as tools on stdio
-- `clikernel.skill`: Use the persistent `clikernel` MCP session as the default workspace for any task advanced through live Python execution -- stateful inspection, file-editing workflows, debugging, experiments, API probes, data transforms, or notebook-style work. Read this before writing, running, or debugging Python code in a session with `clikernel` connected.
+- `clikernel.skill`: Use the `clikernel` MCP session as the default workspace for Python work: reading and changing files, notebook work, trying things out, checking how a library behaves, and reshaping data. One session stays open, so imports and variables carry between calls. Read this before writing, running, or debugging Python code in a session with `clikernel` connected.
 - `clikernel.stream`: Streaming JSON-lines worker protocol: nbformat-shaped output events, and a supervisor for select-based UIs."""
 
-__version__ = "0.2.4"
+__version__ = "0.2.6"

{clikernel-0.2.4 → clikernel-0.2.6}/clikernel/_modidx.py

@@ -16,6 +16,7 @@ d = { 'settings': { 'branch': 'main',
                                'clikernel.cli.serve_stream': ('cli.html#serve_stream', 'clikernel/cli.py')},
             'clikernel.core': { 'clikernel.core.Client': ('core.html#client', 'clikernel/core.py'),
                                 'clikernel.core.Client.__init__': ('core.html#client.__init__', 'clikernel/core.py'),
+                                'clikernel.core.Client._setup': ('core.html#client._setup', 'clikernel/core.py'),
                                 'clikernel.core.Client._use': ('core.html#client._use', 'clikernel/core.py'),
                                 'clikernel.core.Client.aclose': ('core.html#client.aclose', 'clikernel/core.py'),
                                 'clikernel.core.Client.connect': ('core.html#client.connect', 'clikernel/core.py'),

{clikernel-0.2.4 → clikernel-0.2.6}/clikernel/core.py

@@ -7,10 +7,11 @@ Docs: https://AnswerDotAI.github.io/clikernel/core.html.md"""
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/00_core.ipynb.
 
 # %% auto #0
-__all__ = ['DEFAULT_URL', 'MAXLEN', 'STATE_LOST', 'cfg_dir', 'gateways', 'resolve', 'Client']
+__all__ = ['DEFAULT_URL', 'MAXLEN', 'STATE_LOST', 'STATE_LOST_SETUP', 'cfg_dir', 'gateways', 'resolve', 'Client']
 
 # %% ../nbs/00_core.ipynb #2b3b7f4a
 import os, tomllib
+from fastspec.errors import APIError
 from fastcore.utils import *
 from fastcore.nbio import render_text
 from fastcore.xdg import xdg_config_home
@@ -92,20 +93,34 @@ def _inspector_setup(src):
 
 # %% ../nbs/00_core.ipynb #33b7bc28
 STATE_LOST = 'NOTE: the kernel restarted with a fresh interpreter: all session state is lost (imports, variables, monkeypatches). Redo any setup the task still needs.'
+STATE_LOST_SETUP = 'NOTE: the kernel restarted with a fresh interpreter: startup.py has been re-run (its imports are back), but all other session state is lost (variables, monkeypatches, other imports). Redo what the task still needs.'
 
 class Client:
     "One conversation's connection: a gateway manager, and the current kernel"
-    def __init__(self, cfgdir=None): self.cfgdir,self.mgr,self.kc,self.kid,self.auto = cfgdir,None,None,None,False
+    def __init__(self, cfgdir=None): self.cfgdir,self.mgr,self.kc,self.kid,self.auto,self.made = cfgdir,None,None,None,False,False
 
     async def _use(self, mgr, kid):
         "Point at `kid` on `mgr`, dropping any previous ws (never the kernel)"
         if self.kc: await self.kc.aclose()
-        if self.mgr is not None and self.mgr is not mgr: await self.mgr.aclose()
         self.mgr,self.kid,self.kc = mgr,kid,mgr.client(kid)
         self.kc.start_channels()
         await self.kc.wait_for_ready(timeout=30)
 
 # %% ../nbs/00_core.ipynb #94497e4a
+@patch
+async def _setup(self:Client):
+    "Deliver `startup.py` and `inspectors.py` to the current kernel, returning startup's output"
+    out = ''
+    d = Path(self.cfgdir) if self.cfgdir else cfg_dir()
+    if (p := d/'startup.py').exists(): out = await self.execute(_startup_src(p.read_text(), p))
+    if (p := d/'inspectors.py').exists():
+        res = await self.execute(_inspector_setup(p.read_text()))
+        if res:   # a load failure is fatal: refusing to run beats running uninspected
+            await self.mgr.shutdown_kernel(self.kid)
+            self.kc,self.kid,self.auto,self.made = None,None,False,False
+            raise RuntimeError(f'inspectors.py failed to load; kernel stopped:\n{res}')
+    return out
+
 @patch
 async def connect(self:Client, host='', kernel='', auto=False):
     "Connect to a gateway (create a kernel, or attach to `kernel` by id prefix); the pointer aims at it afterwards; `auto` marks a created kernel as client-scoped"
@@ -113,7 +128,7 @@ async def connect(self:Client, host='', kernel='', auto=False):
     if self.auto:   # scoped to this client: any new connect ends it, even one already dead
         try: await self.stop()
         except Exception as e:
-            self.kc,self.kid,self.auto = None,None,False
+            self.kc,self.kid,self.auto,self.made = None,None,False,False
             note = f'\nnote: stopping the auto kernel failed ({e})'
     url,tok,ver = resolve(host, self.cfgdir)
     mgr = JupyAsyncMultiKernelManager(url, token=tok, verify=ver)
@@ -122,19 +137,13 @@ async def connect(self:Client, host='', kernel='', auto=False):
         kid = first(k['id'] for k in ks if k['id'].startswith(kernel))
         if not kid: raise ValueError(f'no kernel matching {kernel!r} on {url}: {[k["id"][:8] for k in ks]}')
         await self._use(mgr, kid)
+        self.made = False
         return f'connected to existing kernel {kid} on {url}' + note
     kw = dict(cwd=os.getcwd(), env=dict(os.environ)) if not host else {}   # the default gateway is local by definition: kernels start where, and as, the conversation lives (cwd and environment - so kernel-side tools that key state to the conversation, like llmdojo's doc-state, resolve it correctly)
     kid = await mgr.start_kernel(**kw)
     await self._use(mgr, kid)
-    out = ''
-    d = Path(self.cfgdir) if self.cfgdir else cfg_dir()
-    if (p := d/'startup.py').exists(): out = await self.execute(_startup_src(p.read_text(), p))
-    if (p := d/'inspectors.py').exists():
-        res = await self.execute(_inspector_setup(p.read_text()))
-        if res:   # a load failure is fatal: refusing to start beats running uninspected
-            await self.mgr.shutdown_kernel(kid)
-            self.kc,self.kid = None,None
-            raise RuntimeError(f'inspectors.py failed to load; kernel stopped:\n{res}')
+    self.made = True
+    out = await self._setup()
     self.auto = auto
     return f'created kernel {kid} on {url}' + (f'\n{out}' if out.strip() else '') + note
 
@@ -159,7 +168,6 @@ async def list_kernels(self:Client, host=''):
         url,tok,ver = resolve(host, self.cfgdir)
         mgr = JupyAsyncMultiKernelManager(url, token=tok, verify=ver)
         ks = await mgr.list_kernels()
-        await mgr.aclose()
     else: ks = await self.mgr.list_kernels()
     if not ks: return 'no kernels'
     def _l(k): return f"{k['id']}  {k.get('execution_state','?')}  connections={k.get('connections','?')}" + ('  <- current' if k['id']==self.kid else '')
@@ -175,16 +183,30 @@ async def stop(self:Client, kernel=''):
     await self.mgr.shutdown_kernel(kid)
     if kid == self.kid:
         await self.kc.aclose()
-        self.kc,self.kid,self.auto = None,None,False
+        self.kc,self.kid,self.auto,self.made = None,None,False,False
     return f'stopped kernel {kid}'
 
 @patch
 async def restart(self:Client):
-    "Restart the current kernel: same id, fresh interpreter"
+    "Restart the current kernel: same id, fresh interpreter; a kernel this client created gets `startup.py` and `inspectors.py` again"
     if not self.kc: return 'no kernel: call `connect` first'
-    await self.mgr.restart_kernel(self.kid)
+    try: await self.mgr.restart_kernel(self.kid)
+    except APIError as e:
+        if e.status_code is None:
+            return f'restart did not complete ({e.error_type}): retry, or `connect` for a fresh kernel; check the gateway if this persists'
+        if e.status_code != 404:
+            return f'restart failed ({e.message}); the kernel is still listed: retry, `stop` it, or `connect` for a fresh one'
+        old,kw = self.kid,{}
+        await self.kc.aclose()
+        if self.mgr.base_url == resolve('', self.cfgdir)[0]: kw = dict(cwd=os.getcwd(), env=dict(os.environ))
+        await self._use(self.mgr, await self.mgr.start_kernel(**kw))
+        self.made = True
+        out = await self._setup()
+        return f'kernel {old} was gone; created fresh kernel {self.kid}.\n' + STATE_LOST_SETUP + (f'\n{out}' if out.strip() else '')
     await self.kc.wait_for_ready(timeout=30)
-    return STATE_LOST
+    if not self.made: return STATE_LOST
+    out = await self._setup()
+    return STATE_LOST_SETUP + (f'\n{out}' if out.strip() else '')
 
 @patch
 async def interrupt(self:Client):
@@ -197,5 +219,4 @@ async def interrupt(self:Client):
 async def aclose(self:Client):
     "Drop connections; kernels are left exactly as they are"
     if self.kc: await self.kc.aclose()
-    if self.mgr: await self.mgr.aclose()
     self.mgr,self.kc,self.kid = None,None,None

{clikernel-0.2.4 → clikernel-0.2.6}/clikernel/mcp.py

@@ -67,7 +67,7 @@ def mk_server(c:Client):
         return await c.stop(kernel)
 
     async def restart()->str:
-        "Kill the current kernel's process and start a fresh one under the same id: `sys.modules` genuinely reset, all session state discarded. Use for a clean slate, after rebuilding a native extension, or after a reload left stale classes behind (symptoms: `isinstance` mysteriously failing, a class missing a method you know it has). Also works when `execute` is stuck. After restarting, redo any imports/setup the task still needs."
+        "Kill the current kernel's process and start a fresh one under the same id: `sys.modules` genuinely reset, all session state discarded. Use for a clean slate, after rebuilding a native extension, or after a reload left stale classes behind (symptoms: `isinstance` mysteriously failing, a class missing a method you know it has). Also works when `execute` is stuck. A kernel this conversation created gets startup.py re-run and inspectors reinstalled (the reply says so); an attached kernel restarts bare, as found."
         return await c.restart()
 
     async def interrupt()->str:

clikernel-0.2.6/clikernel/skill.py

@@ -0,0 +1,23 @@
+"""Use the `clikernel` MCP session as the default workspace for Python work: reading and changing files, notebook work, trying things out, checking how a library behaves, and reshaping data. One session stays open, so imports and variables carry between calls. Read this before writing, running, or debugging Python code in a session with `clikernel` connected.
+
+Prefer it over one-off Python scripts (`python -c`, shell heredocs). Prefer in-kernel tools over shell equivalents when they exist: file search and directory listing go through the `rgapi` pyskill (`rg()`/`fd()`/`ls()`), and GitHub and local git work through the `ghapi` pyskill, when those are installed. Shell commands remain the right tool for project test/build commands and non-Python tools.
+
+# Starting and stopping
+
+The first `execute` creates a kernel and reports what it imported: read that banner, it says what to do next. That kernel stops when the conversation ends. Use a bare `connect` instead when the kernel should stay running afterwards, and tell the user its id.
+
+To continue earlier work, or to use the user's solveit kernel, `list_kernels` then `connect` with the id. Attaching runs no setup: the kernel's live state is the point.
+
+`restart` gives a fresh interpreter under the same id, so redo any setup. `interrupt` stops a long `execute` and keeps state. If a reply says the kernel has stopped, `connect` again. If `connect` fails, the gateway server is not running: tell the user rather than working around it.
+
+Remote gateways are the same verbs with a `host`, named in `~/.config/clikernel/gateways.toml`.
+
+# Working in it
+
+- Magics work as written. `%cd` expands `~` and is the way to change directory: prefer it over `os.chdir`.
+- Only the last expression in a cell displays. `print(...)` any earlier value you need to see.
+- Everything a cell outputs lands in the conversation. Be selective: `len(v)` first, then decide what to show.
+- Don't re-run an `import` already run this session. If a name raises `NameError`, the kernel restarted or is newly attached: redo setup.
+- After an `nbdev-export` (or any edit to a module already imported), `importlib.reload` that module and re-import any names you hold from it: a name bound by `from x import y` keeps the old object, while a `@patch`ed method refreshes with the reload because the patch writes onto the shared class. Restart only when a class you hold instances of was itself redefined. Check what is loaded by calling it, never with `inspect.getsource`, which reads the file on disk.
+- Try the simple import or API call first, before changing the environment, monkeypatching, or adding setup.
+"""

{clikernel-0.2.4 → clikernel-0.2.6/clikernel.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.2.4
+Version: 0.2.6
 Summary: Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol
 Author: clikernel contributors
 License: Apache-2.0
@@ -12,7 +12,8 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastcore>=2.2.2
-Requires-Dist: jupyasyncclient>=0.2.2
+Requires-Dist: jupyasyncclient>=0.2.8
+Requires-Dist: fastspec>=0.2.2
 Requires-Dist: mcpmini>=0.0.1
 Requires-Dist: aidialog>=0.0.7
 Requires-Dist: pillow

{clikernel-0.2.4 → clikernel-0.2.6}/clikernel.egg-info/requires.txt

@@ -1,5 +1,6 @@
 fastcore>=2.2.2
-jupyasyncclient>=0.2.2
+jupyasyncclient>=0.2.8
+fastspec>=0.2.2
 mcpmini>=0.0.1
 aidialog>=0.0.7
 pillow

{clikernel-0.2.4 → clikernel-0.2.6}/pyproject.toml

@@ -17,7 +17,8 @@ classifiers = [
 
 dependencies = [
   "fastcore>=2.2.2",
-  "jupyasyncclient>=0.2.2",
+  "jupyasyncclient>=0.2.8",
+  "fastspec>=0.2.2",
   "mcpmini>=0.0.1",
   "aidialog>=0.0.7",
   "pillow",

clikernel-0.2.4/clikernel/skill.py

@@ -1,55 +0,0 @@
-"""Use the persistent `clikernel` MCP session as the default workspace for any task advanced through live Python execution -- stateful inspection, file-editing workflows, debugging, experiments, API probes, data transforms, or notebook-style work. Read this before writing, running, or debugging Python code in a session with `clikernel` connected.
-
-# Core idea
-
-clikernel connects this conversation to Jupyter kernels hosted by a gateway server (rustygate) that runs all the time, independently of any conversation. State lasts the whole conversation -- imports, live objects, monkeypatches, cached results -- and a kernel you `connect` explicitly persists across conversations too. Treat it as a notebook-style workbench, not a one-shot script runner.
-
-Prefer it over one-off Python scripts (`python -c`, shell heredocs) whenever you need to inspect runtime behavior, test an idea, call a Python API, examine package state, run a live probe, or iterate on an implementation detail. Prefer in-kernel tools over shell equivalents when they exist: file search and directory listing go through the `rgapi` pyskill (`rg()`/`fd()`/`ls()`), and GitHub and local git work through the `ghapi` pyskill, when those are installed. Shell commands remain the right tool for project test/build commands and non-Python tools. Run them through the harness's shell tool, never `subprocess`/`os.system` from the kernel, which would bypass the harness's permission hooks.
-
-# The lifecycle contract
-
-The lifecycle has one implicit convenience and no implicit destruction beyond it. An `execute` with no kernel connected auto-creates one (default gateway, `startup.py` and inspectors as usual), and the connect banner arrives prepended to that first reply. That auto kernel is scoped to the conversation: it stops when the conversation ends, or the moment `connect` moves anywhere else. Kernels you `connect` explicitly -- created bare or attached by id -- are never stopped except by `stop_kernel`. The tools are self-documenting -- read each tool's MCP description -- and the shape of a session is:
-
-- Start of work: just `execute` (the first call auto-connects; read the banner: it says what is imported and what to do next), or a bare `connect` when the kernel should outlive the conversation.
-- Returning to earlier work (the user asks to continue where a previous conversation left off, or to use their solveit kernel): `list_kernels` to see what's running, then `connect` with the kernel id (or unique prefix). Attach runs nothing -- the kernel's live state is the point.
-- End of work: an auto kernel stops itself with the conversation. `stop_kernel` an explicitly created kernel when it was for this task only; leave it running if the user wants to return to it, and tell the user its id so they can.
-
-`restart` gives the current kernel a genuinely fresh interpreter under the same id (redo imports after it); `interrupt` stops a too-long `execute` while keeping state. If a reply says the kernel died, `connect` again. If `connect` fails because the gateway is unreachable, the gateway server is not running -- report that to the user rather than working around it.
-
-Remote gateways (a rustygate or solveit instance elsewhere) are the same verbs with a `host`: a name from `~/.config/clikernel/gateways.toml` (`[gateways.<name>]` tables with `url`, `token` or `token_env`, and optional `verify = false` for self-signed TLS) or a URL. Tokens live in the config file, never in tool arguments.
-
-# Notebook magics
-
-`execute` runs IPython, so magics work as written. The `%nbrun` line magic (registered by aidialog, which the standard startup imports) runs cells from a `.ipynb` file by cell id prefix -- see `doc(dsk)` after startup for its options. It runs *in the kernel*, so its cells share session state and are checked by the session's inspectors.
-
-`%cd` expands `~` and is the idiomatic way to change the kernel's directory: prefer it over `os.chdir`.
-
-# Session setup
-
-`connect` (creating) first runs `~/.config/clikernel/startup.py` (with `__file__` bound, so the file can locate its neighbors), then installs inspectors from `~/.config/clikernel/inspectors.py`. Both travel as source, so remote kernels get the same setup as local ones. Inspectors see each cell before it runs (1-arg: the AST; 2-arg: AST and raw source): a returned string prints as a note ahead of the cell's output, raising `RuleBlock` (provided in the file's namespace) blocks the cell, and inspector bugs warn and fail open. Attached kernels are taken as found: no startup, no inspectors.
-
-# Output shape
-
-Outputs are rendered with `fastcore.nbio.render_text`. A single non-empty output comes back as its preferred text form, e.g. `42`; multiple outputs use readable XML-ish tags (`<stdout>`, `<execute_result>`, ...) with raw, unescaped body text. Exceptions come back as one clean traceback: ANSI-stripped, over-long lines capped at 180 characters with `File `/`Cell ` locations and the exception message always whole. `input()` fails fast in-band (`allow_stdin=False`) rather than hanging. Image outputs (plots etc.) arrive as MCP image blocks, resized to a token-friendly budget, each preceded by a `<media id=...>` text tag naming it; when the image cannot be delivered, a `<media-unavailable>` note appears in the text instead.
-
-# Interaction rules
-
-- Try the simple import or API call first, before mutating environment, monkeypatching, or adding setup.
-- Like Jupyter, only the *last* expression in a cell displays. `print(...)` any earlier value you need to see.
-- Don't re-run an `import` already run this session. If a previously-imported name raises `NameError`, the kernel restarted or is newly attached -- redo setup.
-- `importlib.reload` is not always enough: `from x import *` consumers and `@patch`-decorated classes hold stale references. On stale-class symptoms, use the `restart` tool.
-- Everything a cell outputs lands in the conversation. Be surgical: `print(len(v))` first, then decide what to show.
-- A kernel is shared by anything connected to it: subagents in this session, or the user's own client. Assume shared state is a feature, not a surprise.
-
-# Pyskills
-
-This environment commonly has `pyskills` installed. When present, check it first and prefer a relevant pyskill over ad hoc code:
-
-    from pyskills import list_pyskills, doc
-    import pyskills.skill
-    doc(pyskills.skill)
-
-# The stream protocol
-
-Driven as a plain CLI process (`clikernel [--host H] [--kernel K]`), the same client speaks a delimiter-framed stdin/stdout protocol, documented in its own startup banner and the README. Run bare it creates a kernel and stops it on exit; `--kernel` attaches and leaves it running.
-"""