clikernel 0.2.10__tar.gz → 0.2.11__tar.gz

{clikernel-0.2.10 → clikernel-0.2.11}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 <!-- do not remove -->
 
+## 0.2.11
+
+### New Features
+
+- Rewrite module and API docs for clarity, harden session cleanup with try/finally and grouped errors, negotiate MCP protocol version ([#49](https://github.com/AnswerDotAI/clikernel/issues/49))
+
+
 ## 0.2.10
 
 ### New Features

{clikernel-0.2.10/clikernel.egg-info → clikernel-0.2.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.2.10
+Version: 0.2.11
 Summary: Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol
 Author: clikernel contributors
 License: Apache-2.0
@@ -14,7 +14,7 @@ License-File: LICENSE
 Requires-Dist: fastcore>=2.2.2
 Requires-Dist: jupyasyncclient>=0.2.10
 Requires-Dist: jupywire>=0.1.9
-Requires-Dist: mcpmini>=0.0.4
+Requires-Dist: mcpmini>=0.0.5
 Requires-Dist: rustygate>=0.1.11
 Requires-Dist: httpx
 Provides-Extra: dev

{clikernel-0.2.10 → clikernel-0.2.11}/clikernel/__init__.py

@@ -4,8 +4,8 @@ Modules:
 
 - `clikernel.cli`: The stream-protocol frontend: the service on stdin/stdout for token-reading clients
 - `clikernel.core`: Gateway naming, startup delivery, and MCP sessions on rustygate gateways
-- `clikernel.mcp`: The MCP frontend: a stdio router over rustygate gateways
+- `clikernel.mcp`: Route stdio MCP requests to rustygate gateways
 - `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.10"
+__version__ = "0.2.11"

{clikernel-0.2.10 → clikernel-0.2.11}/clikernel/cli.py

@@ -147,7 +147,9 @@ def main(
             except KeyboardInterrupt: asyncio.run_coroutine_threadsafe(g.call('interrupt'), loop)
     try: serve_stream(execute, info=info, should_exit=lambda: stop)
     finally:
-        run(g.aclose())   # ends the session: the kernel this run created dies with it, an attached one survives
-        if child: child.stop()
-        loop.call_soon_threadsafe(loop.stop)
+        try: run(g.aclose())
+        finally:
+            try:
+                if child: child.stop()
+            finally: loop.call_soon_threadsafe(loop.stop)
 

{clikernel-0.2.10 → clikernel-0.2.11}/clikernel/core.py

@@ -1,6 +1,12 @@
 """Gateway naming, startup delivery, and MCP sessions on rustygate gateways
 
-clikernel is the LLM side of a two-process design: a gateway ([rustygate](https://github.com/AnswerDotAI/rustygate)) hosts the kernels and serves MCP itself at `POST /mcp`; clikernel starts and stops with each conversation and routes the harness's stdio MCP to gateways. This module is the client layer: gateway naming from `gateways.toml`, the per-session kernel-creation defaults (the conversation's cwd and environment, with `startup.py` and `inspectors.py` composed into one startup source), `Gateway` — one MCP session on one gateway — and `default_gateway`, which finds the local gateway or starts an owned child that lives exactly as long as the conversation. Kernel lifecycle policy lives gateway-side: ending a session stops the kernels it created with autoclose and nothing else.
+[Rustygate](https://github.com/AnswerDotAI/rustygate) hosts kernels and serves MCP requests at `POST /mcp`. Clikernel runs alongside it for the duration of a conversation. It routes the LLM client's stdio MCP requests to gateways.
+
+This module connects to those gateways. `gateways.toml` gives them names. `session_defaults` supplies kernel startup code and, for a local gateway, the conversation's working directory and environment. It combines `startup.py` and `inspectors.py` into source that can run on another machine.
+
+`Gateway` represents one MCP session on one gateway. `default_gateway` connects to the local gateway or starts a child process if it cannot connect. The caller must stop any returned child. The MCP router does this when the conversation ends.
+
+Rustygate tracks the session's current kernel and which kernels it created. Ending a session stops its autoclose kernels. It leaves other kernels running. Stopping an owned gateway process stops all kernels in that process.
 
 Docs: https://AnswerDotAI.github.io/clikernel/core.html.md"""
 
@@ -21,16 +27,16 @@ from . import __version__
 DEFAULT_URL = 'http://127.0.0.1:8787'
 
 def cfg_dir():
-    "The clikernel config directory"
+    "Return the clikernel configuration directory."
     return xdg_config_home()/'clikernel'
 
 def gateways(cfgdir=None):
-    "Named gateways from `gateways.toml`: `{name: {url, token | token_env, verify}}`"
+    "Read named gateways as `{name: {url, token | token_env, verify}}` from `gateways.toml`."
     p = (Path(cfgdir) if cfgdir else cfg_dir())/'gateways.toml'
     return tomllib.loads(p.read_text()).get('gateways', {}) if p.exists() else {}
 
 def resolve(host='', cfgdir=None):
-    "`(url, token, verify)` for `host`: empty = the default local gateway, a URL = itself, else a `gateways.toml` name"
+    "Resolve an empty host, URL, or configured gateway name to `(url, token, verify)`."
     if not host: return os.environ.get('CLIKERNEL_HOST', DEFAULT_URL), os.environ.get('CLIKERNEL_TOKEN'), True
     if '://' in host: return host, os.environ.get('CLIKERNEL_TOKEN'), True
     cfgdir = Path(cfgdir) if cfgdir else cfg_dir()
@@ -41,7 +47,7 @@ def resolve(host='', cfgdir=None):
 
 # %% ../nbs/00_core.ipynb #0d846754
 def _startup_src(src, path):
-    "The startup file's source wrapped so `__file__` is bound to its path during the run, and absent after"
+    "Wrap startup source with `__file__` set to its path during execution and deleted afterwards."
     return f'''__file__ = {str(path)!r}
 try: exec(compile({src!r}, __file__, 'exec'))
 finally: del __file__'''
@@ -93,7 +99,7 @@ def _inspector_setup(src):
 
 # %% ../nbs/00_core.ipynb #1362e6ce
 def startup_src(cfgdir=None):
-    "The composed startup source for one kernel: `startup.py` wrapped, then the inspector installer"
+    "Combine wrapped `startup.py` source with the inspector installer, in that order."
     d = Path(cfgdir) if cfgdir else cfg_dir()
     parts = []
     if (p := d/'startup.py').exists(): parts.append(_startup_src(p.read_text(), p))
@@ -101,7 +107,7 @@ def startup_src(cfgdir=None):
     return '\n'.join(parts)
 
 def session_defaults(cfgdir=None, quiet=False, local=True):
-    "The `rustygate` initialize extension: startup source and quiet, plus cwd and env for a local gateway"
+    "Return startup and quiet settings for rustygate initialization. Local sessions also include cwd and env."
     d = dict(startup=startup_src(cfgdir), quiet=quiet)
     if local:
         d['cwd'] = os.getcwd()
@@ -110,7 +116,7 @@ def session_defaults(cfgdir=None, quiet=False, local=True):
 
 # %% ../nbs/00_core.ipynb #10ed59fc
 class Gateway:
-    "One MCP session on one rustygate: initialize with session defaults, call tools, DELETE at close"
+    "Open an MCP session on rustygate, call its tools, and end the session with DELETE."
     def __init__(self,
         url,          # The gateway base URL, e.g. 'http://127.0.0.1:8787'
         token=None,   # Gateway auth token, sent as a bearer token
@@ -121,17 +127,18 @@ class Gateway:
         self.tr = HTTPTransport(f"{url.rstrip('/')}/mcp", token=token, http_client=client)
 
     async def rpc(self, method, **params):
-        "One JSON-RPC request, returning its result and raising on a protocol-level error"
+        "Send a JSON-RPC request and return its result. Raise `RuntimeError` for protocol errors."
         self._id += 1
         r = await self.tr.send(jreq(method, self._id, **params))
         if 'error' in r: raise RuntimeError(f"{r['error']['code']}: {r['error']['message']}")
         return r['result']
 
     async def initialize(self, defaults=None):
-        "Open the MCP session, sending `defaults` as the `rustygate` extension; returns self"
+        "Open the MCP session with `defaults` in the `rustygate` extension. Return self."
         await self.tr.start()
         self.info = await self.rpc('initialize', protocolVersion='2025-11-25', capabilities={},
             clientInfo=dict(name='clikernel', version=__version__), rustygate=defaults or {})
+        self.tr.proto = self.info['protocolVersion']
         await self.tr.send(jreq('notifications/initialized'))
         return self
 
@@ -139,23 +146,23 @@ class Gateway:
     async def call(self, name, **args): return await self.rpc('tools/call', name=name, arguments=args)
 
     async def text(self, name, **args):
-        "A tool call's text blocks joined; raises on `isError`"
+        "Join a tool reply's text blocks. Raise `RuntimeError` for `isError` replies."
         r = await self.call(name, **args)
         t = ''.join(c.get('text','') for c in r['content'] if c['type'] == 'text')
         if r.get('isError'): raise RuntimeError(t)
         return t
 
     async def aclose(self):
-        "End the MCP session — the gateway stops the kernels this session created with autoclose — and drop the connection"
-        await self.tr.delete()
-        await self.tr.aclose()
+        "Request session termination and close the HTTP connection."
+        try: await self.tr.delete()
+        finally: await self.tr.aclose()
 
 # %% ../nbs/00_core.ipynb #0d054375
 async def default_gateway(
     cfgdir=None,  # Config dir for `session_defaults` (the standard one if None)
     quiet=False,  # Keep startup output out of replies?
 ):
-    "An initialized `Gateway` on the default local gateway, plus the owned child rustygate when none was running (else None)"
+    "Return an initialized `Gateway` and its new child process, or None if it reused a gateway. The caller must stop any child."
     url, token, verify = resolve('', cfgdir)
     d = session_defaults(cfgdir, quiet)
     try: return await Gateway(url, token, verify).initialize(d), None

{clikernel-0.2.10 → clikernel-0.2.11}/clikernel/mcp.py

@@ -1,6 +1,10 @@
-"""The MCP frontend: a stdio router over rustygate gateways
+"""Route stdio MCP requests to rustygate gateways
 
-The frontend Claude Code launches per conversation. `Router` speaks stdio MCP to the harness and forwards to gateways: rustygate serves the tool surface itself, so the router defines no tools — it fetches the local gateway's `tools/list`, adds a `host` parameter to the kernel-selection tools, and forwards `tools/call` verbatim to the right gateway, ids intact so cancellation maps through. `main` serves a `Router` on stdio and ends every gateway session on the way out — the DELETE that stops each session's autoclose kernels, and the owned child gateway with them.
+Claude Code starts `clikernel-mcp` for each conversation. Its `Router` accepts MCP messages over stdio and sends tool calls to rustygate gateways. Rustygate implements the tools. The router gets their schemas from the local gateway and adds `host` to `list_kernels`, `use_kernel`, and `create`.
+
+Each host has a separate gateway session. The router remembers one current host for calls without an explicit `host`. It removes `host` before forwarding a call but preserves the JSON-RPC request id. Cancellation notifications also retain their original ids.
+
+`main` runs the router and closes its gateway sessions on exit. Closing a session sends an HTTP DELETE. The gateway then stops the kernels that session created with autoclose. If the router started a child gateway, it stops that process too.
 
 Docs: https://AnswerDotAI.github.io/clikernel/mcp.html.md"""
 
@@ -23,7 +27,7 @@ HOST_PARAM = {'type': 'string', 'description': 'Gateway to target: a gateways.to
 HOSTED = ('list_kernels', 'use_kernel', 'create')
 
 class Router:
-    "Forward the harness's stdio MCP to rustygate gateways: one `Gateway` session per host, one current"
+    "Route stdio MCP to rustygate with one session per host and one current host."
     def __init__(self,
         cfgdir=None,  # Config dir for `session_defaults` and `gateways.toml` (the standard one if None)
         quiet=False,  # Keep startup output out of replies?
@@ -31,7 +35,7 @@ class Router:
         self.cfgdir,self.quiet,self.sessions,self.cur,self.child = cfgdir,quiet,{},'',None
 
     async def session(self, host=''):
-        "The initialized `Gateway` for `host`, made on first use; empty means the default local gateway"
+        "Return the session for `host`, initializing it on first use. Empty `host` selects the default local gateway."
         if host not in self.sessions:
             if host:
                 url, token, verify = resolve(host, self.cfgdir)
@@ -40,15 +44,18 @@ class Router:
         return self.sessions[host]
 
     async def aclose(self):
-        "End every gateway session — stopping each one's autoclose kernels — then the owned child gateway"
-        for s in self.sessions.values(): await s.aclose()
-        if self.child: self.child.stop()
+        "Close all sessions and their autoclose kernels, then stop any owned gateway."
+        try: results = await asyncio.gather(*(s.aclose() for s in self.sessions.values()), return_exceptions=True)
+        finally:
+            if self.child: self.child.stop()
+        errors = [r for r in results if isinstance(r, BaseException)]
+        if errors: raise BaseExceptionGroup('MCP session cleanup failed', errors)
 
 
 # %% ../nbs/01_mcp.ipynb #79da6a3e
 @patch
 async def tools(self:Router):
-    "The local gateway's tools, with `host` added to the kernel-selection tools"
+    "Return the local gateway's tools with `host` added to `list_kernels`, `use_kernel`, and `create`."
     ts = await (await self.session()).tools()
     for t in ts:
         if t['name'] in HOSTED: t['inputSchema'].setdefault('properties', {})['host'] = dict(HOST_PARAM)
@@ -56,7 +63,7 @@ async def tools(self:Router):
 
 @patch
 async def dispatch(self:Router, msg, requester=None):
-    "One JSON-RPC message from the harness: initialize and ping answered here, the tool surface forwarded"
+    "Answer initialization and ping locally. Forward tool calls to gateways."
     method,id = msg.get('method'), msg.get('id')
     try:
         if method == 'initialize':
@@ -83,7 +90,7 @@ async def dispatch(self:Router, msg, requester=None):
 def main(
     quiet:store_true=False,  # Keep startup output out of replies
 ):
-    "The `clikernel-mcp` console script: the router on stdio"
+    "Run `clikernel-mcp` as a stdio server."
     async def _main():
         router = Router(quiet=quiet)
         try: await serve_stdio(router)

{clikernel-0.2.10 → clikernel-0.2.11/clikernel.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.2.10
+Version: 0.2.11
 Summary: Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol
 Author: clikernel contributors
 License: Apache-2.0
@@ -14,7 +14,7 @@ License-File: LICENSE
 Requires-Dist: fastcore>=2.2.2
 Requires-Dist: jupyasyncclient>=0.2.10
 Requires-Dist: jupywire>=0.1.9
-Requires-Dist: mcpmini>=0.0.4
+Requires-Dist: mcpmini>=0.0.5
 Requires-Dist: rustygate>=0.1.11
 Requires-Dist: httpx
 Provides-Extra: dev

{clikernel-0.2.10 → clikernel-0.2.11}/clikernel.egg-info/requires.txt

@@ -1,7 +1,7 @@
 fastcore>=2.2.2
 jupyasyncclient>=0.2.10
 jupywire>=0.1.9
-mcpmini>=0.0.4
+mcpmini>=0.0.5
 rustygate>=0.1.11
 httpx
 

{clikernel-0.2.10 → clikernel-0.2.11}/pyproject.toml

@@ -19,7 +19,7 @@ dependencies = [
   "fastcore>=2.2.2",
   "jupyasyncclient>=0.2.10",
   "jupywire>=0.1.9",
-  "mcpmini>=0.0.4",
+  "mcpmini>=0.0.5",
   "rustygate>=0.1.11",
   "httpx",
 ]