clikernel 0.2.7__tar.gz → 0.2.9__tar.gz

{clikernel-0.2.7 → clikernel-0.2.9}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 <!-- do not remove -->
 
+## 0.2.9
+
+### Breaking Changes
+
+- Replace the Jupyter-protocol client with a stdio MCP router over rustygate ([#47](https://github.com/AnswerDotAI/clikernel/pull/47)), thanks to [@jph00](https://github.com/jph00)
+
+
+## 0.2.8
+
+### New Features
+
+- Stream worker iterates run() directly ([#46](https://github.com/AnswerDotAI/clikernel/pull/46)), thanks to [@jph00](https://github.com/jph00)
+
+
 ## 0.2.7
 
 ### New Features

clikernel-0.2.9/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: clikernel
+Version: 0.2.9
+Summary: Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol
+Author: clikernel contributors
+License: Apache-2.0
+Project-URL: Repository, https://github.com/AnswerDotAI/clikernel
+Project-URL: Documentation, https://AnswerDotAI.github.io/clikernel/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+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: rustygate>=0.1.7
+Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: fastship; extra == "dev"
+Dynamic: license-file
+
+# clikernel
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+`clikernel` gives an LLM agent a persistent Python workbench built from two processes. A gateway ([rustygate](https://github.com/AnswerDotAI/rustygate)) hosts real Jupyter kernels ([ipymini](https://github.com/AnswerDotAI/ipymini) by default) and serves the MCP tool surface itself; kernels live there and persist until explicitly stopped. `clikernel` starts and stops with each conversation: a router the MCP host launches, speaking stdio MCP to the model and forwarding to gateways over HTTP. It adds what a single fixed endpoint cannot: gateway naming from `gateways.toml` (a `host` argument on the kernel-selection tools reaches any machine you’ve named), delivery of your `startup.py` and `inspectors.py` into every kernel a conversation creates, and a local gateway that always exists — found running, or started as a child that lives exactly as long as the conversation.
+
+Kernel scope is the gateway’s rule, one rule everywhere: a session’s end stops the kernels it created with autoclose (the bare-`py` auto kernel, and `create`’s default) and nothing else. A kernel created with `autoclose=false` on a persistent gateway outlives the conversation, and a later conversation reattaches with `use_kernel` and finds its state intact — including the user’s live solveit kernel.
+
+## Install
+
+``` sh
+pip install clikernel
+```
+
+This brings [rustygate](https://github.com/AnswerDotAI/rustygate) and a kernel ([ipymini](https://github.com/AnswerDotAI/ipymini)) with it, and no service setup is needed: a conversation that finds no gateway starts its own. Run a resident gateway when kernels should outlive conversations (e.g. via launchd/systemd):
+
+``` sh
+rustygate --port 8787
+```
+
+## Use with an MCP host
+
+Register the stdio server with your MCP host, e.g. for Claude Code:
+
+``` sh
+claude mcp add clikernel -- clikernel-mcp
+```
+
+The tools are rustygate’s, forwarded: `py` (the normal tool — it auto-starts a kernel when none is current, and magics like a `%%bash` first line run as written), `list_kernels`, `create`, `use_kernel`, `delete_kernel`, `restart`, and `interrupt`. The router adds one thing to them: `list_kernels`, `use_kernel`, and `create` take a `host` naming a gateway from `gateways.toml`, so one MCP entry reaches every machine you’ve named. Replies carry text and image blocks exactly as the gateway rendered them.
+
+A conversation cleans up after itself: its end stops the auto kernel and every `create` it made, unless `autoclose=false` asked for a keeper. Kernels reached with `use_kernel` are never touched. `$CLIKERNEL_HOST` overrides the default gateway (`http://127.0.0.1:8787`), and when nothing answers there, the conversation runs on a private child gateway that ends with it.
+
+Pass `--quiet` (`clikernel-mcp --quiet`) for a host whose sessions should not see banner noise: startup still runs, but its output stays out of every reply.
+
+## Configuration
+
+Three optional files in `$XDG_CONFIG_HOME/clikernel/` (usually `~/.config/clikernel/`):
+
+- `startup.py` — run in every kernel clikernel creates, with `__file__` bound to its path; its output returns in the reply that announces the kernel.
+- `inspectors.py` — cell inspectors installed after startup. The file may define `inspect` and/or a list `inspectors`; each is called once per cell before it runs (1-arg: the cell’s AST; 2-arg: AST and raw source). Return a string to print a note before the cell’s output, raise `RuleBlock` (provided in the namespace) to block the cell; any other exception warns and the cell runs. See `examples/inspectors.py`.
+- `gateways.toml` — named remote gateways, so tokens never appear in tool arguments:
+
+``` toml
+[gateways.solveit]
+url = "https://solveit.example.com/gate"
+token_env = "SOLVEIT_TOKEN"
+verify = false   # optional: accept a self-signed certificate
+```
+
+## The stream protocol
+
+Run `clikernel` as a plain CLI process and the same client speaks a delimiter-framed stdin/stdout protocol for token-reading clients: no echo, a cheap `.` acknowledgement per request, responses ended by a per-process random delimiter, multiline cells framed by `--` and the delimiter. The full recipe is announced in the process’s own startup banner. Run bare it creates a kernel and stops it on exit; `--kernel <id>` attaches to an existing kernel and leaves it as found.

clikernel-0.2.9/README.md

@@ -0,0 +1,53 @@
+# clikernel
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+`clikernel` gives an LLM agent a persistent Python workbench built from two processes. A gateway ([rustygate](https://github.com/AnswerDotAI/rustygate)) hosts real Jupyter kernels ([ipymini](https://github.com/AnswerDotAI/ipymini) by default) and serves the MCP tool surface itself; kernels live there and persist until explicitly stopped. `clikernel` starts and stops with each conversation: a router the MCP host launches, speaking stdio MCP to the model and forwarding to gateways over HTTP. It adds what a single fixed endpoint cannot: gateway naming from `gateways.toml` (a `host` argument on the kernel-selection tools reaches any machine you’ve named), delivery of your `startup.py` and `inspectors.py` into every kernel a conversation creates, and a local gateway that always exists — found running, or started as a child that lives exactly as long as the conversation.
+
+Kernel scope is the gateway’s rule, one rule everywhere: a session’s end stops the kernels it created with autoclose (the bare-`py` auto kernel, and `create`’s default) and nothing else. A kernel created with `autoclose=false` on a persistent gateway outlives the conversation, and a later conversation reattaches with `use_kernel` and finds its state intact — including the user’s live solveit kernel.
+
+## Install
+
+``` sh
+pip install clikernel
+```
+
+This brings [rustygate](https://github.com/AnswerDotAI/rustygate) and a kernel ([ipymini](https://github.com/AnswerDotAI/ipymini)) with it, and no service setup is needed: a conversation that finds no gateway starts its own. Run a resident gateway when kernels should outlive conversations (e.g. via launchd/systemd):
+
+``` sh
+rustygate --port 8787
+```
+
+## Use with an MCP host
+
+Register the stdio server with your MCP host, e.g. for Claude Code:
+
+``` sh
+claude mcp add clikernel -- clikernel-mcp
+```
+
+The tools are rustygate’s, forwarded: `py` (the normal tool — it auto-starts a kernel when none is current, and magics like a `%%bash` first line run as written), `list_kernels`, `create`, `use_kernel`, `delete_kernel`, `restart`, and `interrupt`. The router adds one thing to them: `list_kernels`, `use_kernel`, and `create` take a `host` naming a gateway from `gateways.toml`, so one MCP entry reaches every machine you’ve named. Replies carry text and image blocks exactly as the gateway rendered them.
+
+A conversation cleans up after itself: its end stops the auto kernel and every `create` it made, unless `autoclose=false` asked for a keeper. Kernels reached with `use_kernel` are never touched. `$CLIKERNEL_HOST` overrides the default gateway (`http://127.0.0.1:8787`), and when nothing answers there, the conversation runs on a private child gateway that ends with it.
+
+Pass `--quiet` (`clikernel-mcp --quiet`) for a host whose sessions should not see banner noise: startup still runs, but its output stays out of every reply.
+
+## Configuration
+
+Three optional files in `$XDG_CONFIG_HOME/clikernel/` (usually `~/.config/clikernel/`):
+
+- `startup.py` — run in every kernel clikernel creates, with `__file__` bound to its path; its output returns in the reply that announces the kernel.
+- `inspectors.py` — cell inspectors installed after startup. The file may define `inspect` and/or a list `inspectors`; each is called once per cell before it runs (1-arg: the cell’s AST; 2-arg: AST and raw source). Return a string to print a note before the cell’s output, raise `RuleBlock` (provided in the namespace) to block the cell; any other exception warns and the cell runs. See `examples/inspectors.py`.
+- `gateways.toml` — named remote gateways, so tokens never appear in tool arguments:
+
+``` toml
+[gateways.solveit]
+url = "https://solveit.example.com/gate"
+token_env = "SOLVEIT_TOKEN"
+verify = false   # optional: accept a self-signed certificate
+```
+
+## The stream protocol
+
+Run `clikernel` as a plain CLI process and the same client speaks a delimiter-framed stdin/stdout protocol for token-reading clients: no echo, a cheap `.` acknowledgement per request, responses ended by a per-process random delimiter, multiline cells framed by `--` and the delimiter. The full recipe is announced in the process’s own startup banner. Run bare it creates a kernel and stops it on exit; `--kernel <id>` attaches to an existing kernel and leaves it as found.

{clikernel-0.2.7 → clikernel-0.2.9}/clikernel/__init__.py

@@ -3,9 +3,9 @@
 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.core`: Gateway naming, startup delivery, and MCP sessions on rustygate gateways
+- `clikernel.mcp`: The MCP frontend: a stdio router over 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.7"
+__version__ = "0.2.9"

clikernel-0.2.9/clikernel/_modidx.py

@@ -0,0 +1,41 @@
+# Autogenerated by nbdev
+
+d = { 'settings': { 'branch': 'main',
+                'doc_baseurl': '/clikernel',
+                'doc_host': 'https://AnswerDotAI.github.io',
+                'git_url': 'https://github.com/AnswerDotAI/clikernel',
+                'lib_path': 'clikernel'},
+  'syms': { 'clikernel.cli': { 'clikernel.cli._new_delim': ('cli.html#_new_delim', 'clikernel/cli.py'),
+                               'clikernel.cli._next_line': ('cli.html#_next_line', 'clikernel/cli.py'),
+                               'clikernel.cli._read_block': ('cli.html#_read_block', 'clikernel/cli.py'),
+                               'clikernel.cli._restore_termios': ('cli.html#_restore_termios', 'clikernel/cli.py'),
+                               'clikernel.cli._tty_clear': ('cli.html#_tty_clear', 'clikernel/cli.py'),
+                               'clikernel.cli._write_response': ('cli.html#_write_response', 'clikernel/cli.py'),
+                               'clikernel.cli.fmt_error': ('cli.html#fmt_error', 'clikernel/cli.py'),
+                               'clikernel.cli.main': ('cli.html#main', 'clikernel/cli.py'),
+                               'clikernel.cli.serve_stream': ('cli.html#serve_stream', 'clikernel/cli.py')},
+            'clikernel.core': { 'clikernel.core.Gateway': ('core.html#gateway', 'clikernel/core.py'),
+                                'clikernel.core.Gateway.__init__': ('core.html#gateway.__init__', 'clikernel/core.py'),
+                                'clikernel.core.Gateway.aclose': ('core.html#gateway.aclose', 'clikernel/core.py'),
+                                'clikernel.core.Gateway.call': ('core.html#gateway.call', 'clikernel/core.py'),
+                                'clikernel.core.Gateway.initialize': ('core.html#gateway.initialize', 'clikernel/core.py'),
+                                'clikernel.core.Gateway.rpc': ('core.html#gateway.rpc', 'clikernel/core.py'),
+                                'clikernel.core.Gateway.text': ('core.html#gateway.text', 'clikernel/core.py'),
+                                'clikernel.core.Gateway.tools': ('core.html#gateway.tools', 'clikernel/core.py'),
+                                'clikernel.core._inspector_setup': ('core.html#_inspector_setup', 'clikernel/core.py'),
+                                'clikernel.core._startup_src': ('core.html#_startup_src', 'clikernel/core.py'),
+                                'clikernel.core.cfg_dir': ('core.html#cfg_dir', 'clikernel/core.py'),
+                                'clikernel.core.default_gateway': ('core.html#default_gateway', 'clikernel/core.py'),
+                                'clikernel.core.gateways': ('core.html#gateways', 'clikernel/core.py'),
+                                'clikernel.core.resolve': ('core.html#resolve', 'clikernel/core.py'),
+                                'clikernel.core.session_defaults': ('core.html#session_defaults', 'clikernel/core.py'),
+                                'clikernel.core.startup_src': ('core.html#startup_src', 'clikernel/core.py')},
+            'clikernel.mcp': { 'clikernel.mcp.Router': ('mcp.html#router', 'clikernel/mcp.py'),
+                               'clikernel.mcp.Router.__init__': ('mcp.html#router.__init__', 'clikernel/mcp.py'),
+                               'clikernel.mcp.Router.aclose': ('mcp.html#router.aclose', 'clikernel/mcp.py'),
+                               'clikernel.mcp.Router.dispatch': ('mcp.html#router.dispatch', 'clikernel/mcp.py'),
+                               'clikernel.mcp.Router.session': ('mcp.html#router.session', 'clikernel/mcp.py'),
+                               'clikernel.mcp.Router.tools': ('mcp.html#router.tools', 'clikernel/mcp.py'),
+                               'clikernel.mcp.main': ('mcp.html#main', 'clikernel/mcp.py')},
+            'clikernel.skill': {},
+            'clikernel.stream': {}}}

{clikernel-0.2.7 → clikernel-0.2.9}/clikernel/cli.py

@@ -1,6 +1,6 @@
 """The stream-protocol frontend: the service on stdin/stdout for token-reading clients
 
-The `clikernel` command: the delimiter-framed stdin/stdout protocol v1 established (documented in the README, rationale unchanged — a client that reads stdout as tokens wants no echo, a cheap ack byte, and a per-process random delimiter to read until). The protocol machinery ports from v1 verbatim; underneath, the process is now a thin client of a gateway kernel. Run bare it creates a kernel and stops it again on exit — whoever ran the command made that decision by running it — while `--kernel` attaches to an existing kernel and leaves it exactly as found. Ctrl-C during a long cell translates into a kernel interrupt, jupyter-console style, instead of killing the process.
+The `clikernel` command: the delimiter-framed stdin/stdout protocol v1 established (documented in the README, rationale unchanged — a client that reads stdout as tokens wants no echo, a cheap ack byte, and a per-process random delimiter to read until). The protocol machinery ports from v1 verbatim; underneath, the process is now one MCP session on a gateway. Run bare it creates a kernel and stops it again on exit — whoever ran the command made that decision by running it — while `--kernel` attaches to an existing kernel and leaves it exactly as found. Ctrl-C during a long cell translates into a kernel interrupt, jupyter-console style, instead of killing the process.
 
 Docs: https://AnswerDotAI.github.io/clikernel/cli.html.md"""
 
@@ -13,7 +13,7 @@ __all__ = ['fmt_error', 'serve_stream', 'main']
 import asyncio, secrets, signal, string, sys, termios, threading, traceback, tty
 from fastcore.utils import *
 from fastcore.script import call_parse
-from .core import Client
+from .core import Gateway, default_gateway, resolve, session_defaults
 
 
 # %% ../nbs/02_cli.ipynb #d8413fff
@@ -129,21 +129,25 @@ def main(
     loop = asyncio.new_event_loop()
     threading.Thread(target=loop.run_forever, daemon=True).start()
     def run(coro): return asyncio.run_coroutine_threadsafe(coro, loop).result()
-    c = Client()
-    info = run(c.connect(host, kernel))
+    async def _open():
+        if not host: return await default_gateway()
+        url, token, verify = resolve(host)
+        return await Gateway(url, token, verify).initialize(session_defaults(local=False)), None
+    g, child = run(_open())
+    info = run(g.text('use_kernel', kernel=kernel) if kernel else g.text('py', code=''))
     stop = False
     def execute(code):
         nonlocal stop
         if code.strip() in _EXITS:
             stop = True
             return ''
-        fut = asyncio.run_coroutine_threadsafe(c.execute(code), loop)
+        fut = asyncio.run_coroutine_threadsafe(g.text('py', code=code), loop)
         while True:
             try: return fut.result()
-            except KeyboardInterrupt: asyncio.run_coroutine_threadsafe(c.interrupt(), loop)
+            except KeyboardInterrupt: asyncio.run_coroutine_threadsafe(g.call('interrupt'), loop)
     try: serve_stream(execute, info=info, should_exit=lambda: stop)
     finally:
-        if not kernel: run(c.stop())   # created for this run, cleaned up by this run
-        run(c.aclose())
+        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)
 

clikernel-0.2.9/clikernel/core.py

@@ -0,0 +1,163 @@
+"""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.
+
+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', 'cfg_dir', 'gateways', 'resolve', 'startup_src', 'session_defaults', 'Gateway', 'default_gateway']
+
+# %% ../nbs/00_core.ipynb #2b3b7f4a
+import os, tomllib, httpx
+from fastcore.utils import *
+from fastcore.xdg import xdg_config_home
+from mcpmini.core import HTTPTransport, jreq
+from rustygate.tools import start_gateway
+from . import __version__
+
+# %% ../nbs/00_core.ipynb #596419b8
+DEFAULT_URL = 'http://127.0.0.1:8787'
+
+def cfg_dir():
+    "The clikernel config directory"
+    return xdg_config_home()/'clikernel'
+
+def gateways(cfgdir=None):
+    "Named gateways from `gateways.toml`: `{name: {url, token | token_env, verify}}`"
+    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"
+    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
+    g = gateways(cfgdir).get(host)
+    if g is None: raise ValueError(f"unknown gateway {host!r}: not a URL, and not in {cfg_dir()/'gateways.toml'}")
+    return g['url'], g.get('token') or os.environ.get(g.get('token_env','')) or None, g.get('verify', True)
+
+
+# %% ../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"
+    return f'''__file__ = {str(path)!r}
+try: exec(compile({src!r}, __file__, 'exec'))
+finally: del __file__'''
+
+# %% ../nbs/00_core.ipynb #3dbf4cb6
+_INSP_RUNNER = r'''
+import inspect as _clik_inspect
+import sys as _clik_sys
+from IPython.core.error import InputRejected
+class RuleBlock(InputRejected):
+    "Raise from an inspector to deliberately block a cell; any other inspector exception is a bug, and fails open"
+
+class _ClikInspect:
+    "Calls each inspector once per cell: 1-arg get the AST, 2-arg also the raw source"
+    def __init__(self, fs): self.fs = fs
+    def visit(self, tree):
+        fr, n = _clik_sys._getframe(), 0
+        while fr:
+            n += fr.f_code.co_name == 'run_cell_async'
+            fr = fr.f_back
+        if n > 1: return tree  # nested run_cell: cell replayed by a tool (%nbrun etc.), not typed
+        for f in self.fs:
+            try:
+                note = f(tree, _clik_src) if len(_clik_inspect.signature(f).parameters) > 1 else f(tree)
+                if note: print(note, end='')
+            except InputRejected: raise
+            except Exception as e: print(f'inspector error (cell runs anyway): {e!r}')
+        return tree
+
+def _clik_stash(info):
+    global _clik_src
+    _clik_src = info.raw_cell
+
+def _clik_install(src):
+    ns = dict(RuleBlock=RuleBlock)
+    exec(compile(src, 'inspectors.py', 'exec'), ns)
+    fs = list(ns.get('inspectors') or [])
+    if callable(ns.get('inspect')): fs.append(ns['inspect'])
+    if fs:
+        ip = get_ipython()
+        ip.events.register('pre_run_cell', _clik_stash)
+        ip.ast_transformers.append(_ClikInspect(fs))
+_clik_src = ''
+'''
+
+def _inspector_setup(src):
+    "Kernel-side source installing the inspectors defined in `src`; a load failure raises, failing the create call"
+    return _INSP_RUNNER + f'\n_clik_install({src!r})'
+
+# %% ../nbs/00_core.ipynb #1362e6ce
+def startup_src(cfgdir=None):
+    "The composed startup source for one kernel: `startup.py` wrapped, then the inspector installer"
+    d = Path(cfgdir) if cfgdir else cfg_dir()
+    parts = []
+    if (p := d/'startup.py').exists(): parts.append(_startup_src(p.read_text(), p))
+    if (p := d/'inspectors.py').exists(): parts.append(_inspector_setup(p.read_text()))
+    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"
+    d = dict(startup=startup_src(cfgdir), quiet=quiet)
+    if local:
+        d['cwd'] = os.getcwd()
+        d['env'] = dict(os.environ, CLIKERNEL_QUIET='1') if quiet else dict(os.environ)
+    return d
+
+# %% ../nbs/00_core.ipynb #10ed59fc
+class Gateway:
+    "One MCP session on one rustygate: initialize with session defaults, call tools, DELETE at close"
+    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
+        verify=True,  # Verify TLS certificates?
+    ):
+        client = httpx.AsyncClient(verify=verify, timeout=httpx.Timeout(None, connect=10))
+        self.url,self._id = url,0
+        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"
+        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"
+        await self.tr.start()
+        self.info = await self.rpc('initialize', protocolVersion='2025-11-25', capabilities={},
+            clientInfo=dict(name='clikernel', version=__version__), rustygate=defaults or {})
+        await self.tr.send(jreq('notifications/initialized'))
+        return self
+
+    async def tools(self): return (await self.rpc('tools/list'))['tools']
+    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`"
+        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()
+
+# %% ../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)"
+    url, token, verify = resolve('', cfgdir)
+    d = session_defaults(cfgdir, quiet)
+    try: return await Gateway(url, token, verify).initialize(d), None
+    except httpx.ConnectError:
+        child = start_gateway()
+        return await Gateway(child.url).initialize(d), child

clikernel-0.2.9/clikernel/mcp.py

@@ -0,0 +1,92 @@
+"""The MCP frontend: a stdio router over 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.
+
+Docs: https://AnswerDotAI.github.io/clikernel/mcp.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/01_mcp.ipynb.
+
+# %% auto #0
+__all__ = ['HOST_PARAM', 'HOSTED', 'Router', 'main']
+
+# %% ../nbs/01_mcp.ipynb #28c42902
+import asyncio
+from fastcore.utils import *
+from fastcore.script import call_parse, store_true
+from mcpmini.core import serve_stdio, jresp, jerr
+from .core import Gateway, default_gateway, resolve, session_defaults
+from . import __version__
+
+
+# %% ../nbs/01_mcp.ipynb #76e2d782
+HOST_PARAM = {'type': 'string', 'description': 'Gateway to target: a gateways.toml name, or empty for the default local gateway'}
+HOSTED = ('list_kernels', 'use_kernel', 'create')
+
+class Router:
+    "Forward the harness's stdio MCP to rustygate gateways: one `Gateway` session per host, one current"
+    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?
+    ):
+        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"
+        if host not in self.sessions:
+            if host:
+                url, token, verify = resolve(host, self.cfgdir)
+                self.sessions[host] = await Gateway(url, token, verify).initialize(session_defaults(self.cfgdir, self.quiet, local=False))
+            else: self.sessions[host], self.child = await default_gateway(self.cfgdir, self.quiet)
+        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()
+
+
+# %% ../nbs/01_mcp.ipynb #79da6a3e
+@patch
+async def tools(self:Router):
+    "The local gateway's tools, with `host` added to the kernel-selection tools"
+    ts = await (await self.session()).tools()
+    for t in ts:
+        if t['name'] in HOSTED: t['inputSchema'].setdefault('properties', {})['host'] = dict(HOST_PARAM)
+    return ts
+
+@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"
+    method,id = msg.get('method'), msg.get('id')
+    try:
+        if method == 'initialize':
+            info = (await self.session()).info
+            return jresp(id, dict(protocolVersion=msg['params'].get('protocolVersion', '2025-06-18'), capabilities=dict(tools={}),
+                serverInfo=dict(name='clikernel', version=__version__), instructions=info.get('instructions')))
+        if id is None:
+            if method == 'notifications/cancelled': await (await self.session(self.cur)).tr.send(msg)
+            return None
+        if method == 'ping': return jresp(id, {})
+        if method == 'tools/list': return jresp(id, dict(tools=await self.tools()))
+        if method == 'tools/call':
+            args = msg['params'].setdefault('arguments', {})
+            has_host = 'host' in args
+            host = args.pop('host', '') or ''
+            s = await self.session(host if has_host else self.cur)
+            if has_host and msg['params']['name'] in ('use_kernel', 'create'): self.cur = host
+            return await s.tr.send(msg)
+        return jerr(id, -32601, f'method not found: {method}')
+    except Exception as e: return None if id is None else jerr(id, -32603, str(e))
+
+# %% ../nbs/01_mcp.ipynb #3b90f0e8
+@call_parse
+def main(
+    quiet:store_true=False,  # Keep startup output out of replies
+):
+    "The `clikernel-mcp` console script: the router on stdio"
+    async def _main():
+        router = Router(quiet=quiet)
+        try: await serve_stdio(router)
+        finally: await router.aclose()
+    asyncio.run(_main())
+

{clikernel-0.2.7 → clikernel-0.2.9}/clikernel/skill.py

@@ -4,17 +4,17 @@ Prefer it over one-off Python scripts (`python -c`, shell heredocs). Prefer in-k
 
 # 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.
+The first `py` creates a kernel and reports what it imported: read that banner, it says what to do next. That kernel stops when the conversation ends, as does any kernel `create` makes unless it was created with `autoclose=false`. Use `create(dlgname, autoclose=false)` when a kernel should stay running afterwards, and tell the user its id — that only helps on a gateway that itself keeps running, so mention it if the reply shows a conversation-started gateway.
 
-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.
+To continue earlier work, or to use the user's solveit kernel, `list_kernels` then `use_kernel` with the id. Attaching runs no setup and claims no ownership: the kernel's live state is the point, and it is never stopped for you.
 
-`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.
+`restart` gives a fresh interpreter under the same id; startup re-runs in kernels this conversation created, so redo everything else. `interrupt` stops a long `py` and keeps state. If a reply says the kernel is gone, the next `py` starts a fresh one.
 
-Remote gateways are the same verbs with a `host`, named in `~/.config/clikernel/gateways.toml`.
+Remote gateways are the same tools with a `host` argument on `list_kernels`, `use_kernel`, and `create`, named in `~/.config/clikernel/gateways.toml`. After selecting with a host, plain `py` runs there until the next selection.
 
 # Working in it
 
-- Magics work as written. `%cd` expands `~` and is the way to change directory: prefer it over `os.chdir`.
+- Magics work as written, including `%%bash` for shell work. `%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.

{clikernel-0.2.7 → clikernel-0.2.9}/clikernel/stream.py

@@ -22,9 +22,8 @@ def _emit(obj):
 
 async def _do_exec(kc, req):
     rid = req.get('id')
-    def _out(m):
+    async for m in kc.run(req['code']):
         if m['msg_type'] in OUTPUT_MSGS: _emit(dict(ev='out', id=rid, output=msg2out(m)))
-    await kc.run(req['code'], on_output=_out)
     _emit({'ev':'done','id':rid})
 
 async def _do_complete(kc, req):

clikernel-0.2.9/clikernel.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: clikernel
+Version: 0.2.9
+Summary: Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol
+Author: clikernel contributors
+License: Apache-2.0
+Project-URL: Repository, https://github.com/AnswerDotAI/clikernel
+Project-URL: Documentation, https://AnswerDotAI.github.io/clikernel/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+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: rustygate>=0.1.7
+Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: fastship; extra == "dev"
+Dynamic: license-file
+
+# clikernel
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+`clikernel` gives an LLM agent a persistent Python workbench built from two processes. A gateway ([rustygate](https://github.com/AnswerDotAI/rustygate)) hosts real Jupyter kernels ([ipymini](https://github.com/AnswerDotAI/ipymini) by default) and serves the MCP tool surface itself; kernels live there and persist until explicitly stopped. `clikernel` starts and stops with each conversation: a router the MCP host launches, speaking stdio MCP to the model and forwarding to gateways over HTTP. It adds what a single fixed endpoint cannot: gateway naming from `gateways.toml` (a `host` argument on the kernel-selection tools reaches any machine you’ve named), delivery of your `startup.py` and `inspectors.py` into every kernel a conversation creates, and a local gateway that always exists — found running, or started as a child that lives exactly as long as the conversation.
+
+Kernel scope is the gateway’s rule, one rule everywhere: a session’s end stops the kernels it created with autoclose (the bare-`py` auto kernel, and `create`’s default) and nothing else. A kernel created with `autoclose=false` on a persistent gateway outlives the conversation, and a later conversation reattaches with `use_kernel` and finds its state intact — including the user’s live solveit kernel.
+
+## Install
+
+``` sh
+pip install clikernel
+```
+
+This brings [rustygate](https://github.com/AnswerDotAI/rustygate) and a kernel ([ipymini](https://github.com/AnswerDotAI/ipymini)) with it, and no service setup is needed: a conversation that finds no gateway starts its own. Run a resident gateway when kernels should outlive conversations (e.g. via launchd/systemd):
+
+``` sh
+rustygate --port 8787
+```
+
+## Use with an MCP host
+
+Register the stdio server with your MCP host, e.g. for Claude Code:
+
+``` sh
+claude mcp add clikernel -- clikernel-mcp
+```
+
+The tools are rustygate’s, forwarded: `py` (the normal tool — it auto-starts a kernel when none is current, and magics like a `%%bash` first line run as written), `list_kernels`, `create`, `use_kernel`, `delete_kernel`, `restart`, and `interrupt`. The router adds one thing to them: `list_kernels`, `use_kernel`, and `create` take a `host` naming a gateway from `gateways.toml`, so one MCP entry reaches every machine you’ve named. Replies carry text and image blocks exactly as the gateway rendered them.
+
+A conversation cleans up after itself: its end stops the auto kernel and every `create` it made, unless `autoclose=false` asked for a keeper. Kernels reached with `use_kernel` are never touched. `$CLIKERNEL_HOST` overrides the default gateway (`http://127.0.0.1:8787`), and when nothing answers there, the conversation runs on a private child gateway that ends with it.
+
+Pass `--quiet` (`clikernel-mcp --quiet`) for a host whose sessions should not see banner noise: startup still runs, but its output stays out of every reply.
+
+## Configuration
+
+Three optional files in `$XDG_CONFIG_HOME/clikernel/` (usually `~/.config/clikernel/`):
+
+- `startup.py` — run in every kernel clikernel creates, with `__file__` bound to its path; its output returns in the reply that announces the kernel.
+- `inspectors.py` — cell inspectors installed after startup. The file may define `inspect` and/or a list `inspectors`; each is called once per cell before it runs (1-arg: the cell’s AST; 2-arg: AST and raw source). Return a string to print a note before the cell’s output, raise `RuleBlock` (provided in the namespace) to block the cell; any other exception warns and the cell runs. See `examples/inspectors.py`.
+- `gateways.toml` — named remote gateways, so tokens never appear in tool arguments:
+
+``` toml
+[gateways.solveit]
+url = "https://solveit.example.com/gate"
+token_env = "SOLVEIT_TOKEN"
+verify = false   # optional: accept a self-signed certificate
+```
+
+## The stream protocol
+
+Run `clikernel` as a plain CLI process and the same client speaks a delimiter-framed stdin/stdout protocol for token-reading clients: no echo, a cheap `.` acknowledgement per request, responses ended by a per-process random delimiter, multiline cells framed by `--` and the delimiter. The full recipe is announced in the process’s own startup banner. Run bare it creates a kernel and stops it on exit; `--kernel <id>` attaches to an existing kernel and leaves it as found.