clikernel 0.2.10__tar.gz → 0.2.12__tar.gz

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

@@ -2,6 +2,21 @@
 
 <!-- do not remove -->
 
+## 0.2.12
+
+### New Features
+
+- Replace py/lua tools with explicit create(kernel=...) and exec(code=...); default Python `ast_node_interactivity` to all ([#51](https://github.com/AnswerDotAI/clikernel/issues/51))
+- Add --cfgdir flag to clikernel-mcp ([#50](https://github.com/AnswerDotAI/clikernel/pull/50)), thanks to [@ncoop57](https://github.com/ncoop57)
+
+
+## 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.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.2.10
+Version: 0.2.12
 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,8 +14,8 @@ 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.11
+Requires-Dist: mcpmini>=0.0.5
+Requires-Dist: rustygate>=0.1.19
 Requires-Dist: httpx
 Provides-Extra: dev
 Requires-Dist: fastship; extra == "dev"
@@ -26,16 +26,11 @@ Dynamic: license-file
 
 <!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
 
-`clikernel` gives an LLM agent a persistent Python or Luau session. Imports, variables, and results remain available between tool calls. An agent can create a kernel or attach to an existing one, including a user’s live solveit kernel, on a local or named remote gateway.
+`clikernel` gives LLM agents persistent kernel sessions over MCP or a plain stream protocol. Imports, variables, and results remain available between calls. Agents can create kernels or attach to existing ones, including a user’s live solveit kernel.
 
-[rustygate](https://github.com/AnswerDotAI/rustygate) hosts the Jupyter kernels and provides their MCP tools. `clikernel` is the conversation-side router: the MCP host launches it over stdio, and it forwards requests to gateways over HTTP. It selects gateways from `gateways.toml`, supplies `startup.py` and `inspectors.py` to Python kernels it creates, and starts a private local gateway when needed. The default kernel is [ipymini](https://github.com/AnswerDotAI/ipymini).
+[rustygate](https://github.com/AnswerDotAI/rustygate) hosts the kernels. Clikernel routes requests to local or named remote gateways and supplies startup code to Python kernels.
 
-Kernel ownership determines what happens when the conversation ends:
-
-- A session closes kernels it created with `autoclose`, including the automatic kernel used by bare `py` or `lua` and kernels created with `create`’s default settings.
-- Attaching with `use_kernel` does not make that session responsible for closing the kernel.
-- A kernel created with `autoclose=false` on a resident gateway can outlive the conversation. A later conversation can attach and continue using its state.
-- A private child gateway ends with its conversation. Use a resident gateway for kernels that need to survive across conversations.
+New kernels close with their creating conversation by default. Attaching to an existing kernel does not claim ownership. Use `autoclose=false` on a persistent gateway to keep a new kernel for later conversations. See [core](https://AnswerDotAI.github.io/clikernel/core.html) for configuration and lifecycle details.
 
 ## Install
 
@@ -57,19 +52,18 @@ Register the stdio server with your MCP host. For Claude Code:
 claude mcp add clikernel -- clikernel-mcp
 ```
 
-Use `py(code=...)` for Python/IPython or `lua(code=...)` for bundled Luau. Either starts its language’s kernel when none is current. There is one current kernel: a language mismatch errors without switching or running the code. IPython magics, including `%%bash`, are Python-only.
-
-For a named kernel, use `create(dlgname="work", language="luau")`. Omit `language` to reuse an existing binding unchanged, or default a new kernel to Python. An explicit language must match an existing binding. The other tools are `list_kernels`, `use_kernel`, `delete_kernel`, `restart`, and `interrupt`; creation, selection, and listing report the language.
+Choose a kernel, then execute code:
 
-These tools forward to rustygate. `list_kernels`, `use_kernel`, and `create` also accept a `host` naming a gateway from `gateways.toml`. One MCP registration can therefore reach multiple machines. Replies retain the gateway’s text and image blocks. Python startup and inspectors run only in Python, never Luau, including after restart.
-
-`$CLIKERNEL_HOST` overrides the default gateway URL, `http://127.0.0.1:8787`. If no gateway answers, clikernel uses a private child gateway for the conversation. The ownership rules above determine which kernels close at session end.
+``` python
+create(kernel="ipymini")
+exec(code="6*7")
+```
 
-Pass `--quiet`, as in `clikernel-mcp --quiet`, to omit startup output from replies. Python startup code still runs.
+Use `kernel="luau"` for bundled Luau, or `kernel="miniapl"` for APL when miniapl is installed on the gateway. `exec` never creates or switches kernels. See [MCP](https://AnswerDotAI.github.io/clikernel/mcp.html) for named gateways, dialog bindings, and other tools.
 
 ## Configuration
 
-Three optional files in `$XDG_CONFIG_HOME/clikernel/` configure the router, usually under `~/.config/clikernel/`:
+Three optional files in `$XDG_CONFIG_HOME/clikernel/` configure the router, usually under `~/.config/clikernel/`, or under the directory `clikernel-mcp --cfgdir` names:
 
 - `startup.py` runs in each Python kernel clikernel creates, with `__file__` set to its path. Its output appears in the reply announcing the kernel unless `--quiet` is set.
 - `inspectors.py` installs Python cell inspectors after startup. Define `inspect`, a list named `inspectors`, or both. Each inspector runs once before a cell: a one-argument inspector takes the cell’s AST, and a two-argument inspector takes the AST and raw source. Return a string to print a note before the output. Raise the provided `RuleBlock` to block execution. Other exceptions produce a warning and allow the cell to run. See [examples/inspectors.py](examples/inspectors.py).

clikernel-0.2.12/README.md

@@ -0,0 +1,65 @@
+# clikernel
+
+
+<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
+
+`clikernel` gives LLM agents persistent kernel sessions over MCP or a plain stream protocol. Imports, variables, and results remain available between calls. Agents can create kernels or attach to existing ones, including a user’s live solveit kernel.
+
+[rustygate](https://github.com/AnswerDotAI/rustygate) hosts the kernels. Clikernel routes requests to local or named remote gateways and supplies startup code to Python kernels.
+
+New kernels close with their creating conversation by default. Attaching to an existing kernel does not claim ownership. Use `autoclose=false` on a persistent gateway to keep a new kernel for later conversations. See [core](https://AnswerDotAI.github.io/clikernel/core.html) for configuration and lifecycle details.
+
+## Install
+
+``` sh
+pip install clikernel
+```
+
+This installs rustygate and ipymini. No service setup is required for a conversation-local kernel: clikernel starts a private gateway if it cannot find one. To retain kernels across conversations, run a resident gateway, for example through launchd or systemd:
+
+``` sh
+rustygate --port 8787
+```
+
+## Use with an MCP host
+
+Register the stdio server with your MCP host. For Claude Code:
+
+``` sh
+claude mcp add clikernel -- clikernel-mcp
+```
+
+Choose a kernel, then execute code:
+
+``` python
+create(kernel="ipymini")
+exec(code="6*7")
+```
+
+Use `kernel="luau"` for bundled Luau, or `kernel="miniapl"` for APL when miniapl is installed on the gateway. `exec` never creates or switches kernels. See [MCP](https://AnswerDotAI.github.io/clikernel/mcp.html) for named gateways, dialog bindings, and other tools.
+
+## Configuration
+
+Three optional files in `$XDG_CONFIG_HOME/clikernel/` configure the router, usually under `~/.config/clikernel/`, or under the directory `clikernel-mcp --cfgdir` names:
+
+- `startup.py` runs in each Python kernel clikernel creates, with `__file__` set to its path. Its output appears in the reply announcing the kernel unless `--quiet` is set.
+- `inspectors.py` installs Python cell inspectors after startup. Define `inspect`, a list named `inspectors`, or both. Each inspector runs once before a cell: a one-argument inspector takes the cell’s AST, and a two-argument inspector takes the AST and raw source. Return a string to print a note before the output. Raise the provided `RuleBlock` to block execution. Other exceptions produce a warning and allow the cell to run. See [examples/inspectors.py](examples/inspectors.py).
+- `gateways.toml` names remote gateways and configures authentication without putting tokens 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 for clients that read a text stream rather than MCP messages. It uses a delimiter-framed stdin/stdout protocol:
+
+- Input is not echoed.
+- Each request gets a `.` acknowledgement.
+- A per-process random delimiter marks the end of each response.
+- Multiline cells are framed by `--` and the delimiter.
+
+The startup banner supplies the protocol instructions and delimiter. Running `clikernel` without arguments creates a kernel and stops it on exit. `--kernel <id>` attaches to an existing kernel and leaves it running on exit.

{clikernel-0.2.10 → clikernel-0.2.12}/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.12"

{clikernel-0.2.10 → clikernel-0.2.12}/clikernel/_modidx.py

@@ -8,6 +8,7 @@ d = { 'settings': { 'branch': 'main',
   '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._response': ('cli.html#_response', '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-0.2.10 → clikernel-0.2.12}/clikernel/cli.py

@@ -1,6 +1,8 @@
 """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 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.
+The `clikernel` command connects a text-stream client to one gateway kernel. Requests and replies use a per-process delimiter. Input is not echoed. A `.` line acknowledges each accepted request before its result arrives.
+
+Running the command without arguments creates a Python kernel and stops it on exit. `--kernel` attaches to an existing kernel and leaves it running. Ctrl-C during execution interrupts the kernel without ending the CLI process.
 
 Docs: https://AnswerDotAI.github.io/clikernel/cli.html.md"""
 
@@ -38,6 +40,23 @@ def fmt_error(tag, text):
     return f"<{tag}>\n{text}{nl}</{tag}>"
 
 
+# %% ../nbs/02_cli.ipynb #5649e04a
+def _response(line, stdin, delim, execute):
+    "Return (body, accepted), acknowledging accepted requests before execution."
+    line = line.rstrip("\n")
+    if line == delim: return fmt_error("protocol-error", "no multiline request is open: start one with a bare `--` line"), False
+    if line == _MULTILINE:
+        code, err = _read_block(stdin, delim)
+        if err: return fmt_error("protocol-error", err), False
+    elif line.startswith('%%'):
+        return fmt_error("protocol-error",
+            f"a %% cell magic needs a multiline request; send it as (flush-left):\n    --\n    {line}\n    <rest of cell>\n    {delim}"), False
+    else: code = line
+    print(".", flush=True)
+    try: return execute(code), True
+    except BaseException: return fmt_error("internal-error", traceback.format_exc()), True
+
+# %% ../nbs/02_cli.ipynb #8c3decee
 def _write_response(delim, body=None):
     if body: print(body, end='' if body.endswith('\n') else '\n', flush=True)
     print(delim, flush=True)
@@ -51,6 +70,7 @@ def _next_line(stdin):
             if stdin.isatty(): raise
 
 
+# %% ../nbs/02_cli.ipynb #bd6301f5
 def _tty_clear(stream, idx, mask, cc=None):
     "Clear `mask` bits in termios field `idx` when `stream` is a TTY, with optional `cc` char overrides; returns state for `_restore_termios`"
     if not stream.isatty(): return None
@@ -69,12 +89,13 @@ def _restore_termios(state):
     if state: termios.tcsetattr(state[0], termios.TCSADRAIN, state[1])
 
 
+# %% ../nbs/02_cli.ipynb #967cb6e3
 def serve_stream(
     execute,          # Callable `code -> str`: run one request, returning the rendered response body
     info="",          # Server info announced between the loading lines (forwarded to mcp `instructions`)
     should_exit=None  # Callable checked after each request; truthy stops the worker
 ):
-    "Run the stream protocol on stdin/stdout: announce `info` and the session delimiter, then ack each request with '.', respond with `execute(code)`, and end each response with the delimiter"
+    "Serve delimiter-framed requests on stdin/stdout."
     # ONLCR off so protocol output stays bare LF; ECHO off (echoed input corrupts the protocol) and ICANON
     # off (canonical mode drops bytes past MAX_CANON with BEL spam; VMIN/VTIME make non-canonical reads
     # return per byte; ISIG stays on so ^C still interrupts)
@@ -92,25 +113,9 @@ def serve_stream(
         while True:
             line = _next_line(sys.stdin)
             if not line: break
-            line = line.rstrip("\n")
-            if line == delim:
-                _write_response(delim, fmt_error("protocol-error", "no multiline request is open: start one with a bare `--` line"))
-                continue
-            if line == _MULTILINE:
-                code, err = _read_block(sys.stdin, delim)
-                if err:
-                    _write_response(delim, fmt_error("protocol-error", err))
-                    continue
-            elif line.startswith('%%'):
-                _write_response(delim, fmt_error("protocol-error",
-                    f"a %% cell magic needs a multiline request; send it as (flush-left):\n    --\n    {line}\n    <rest of cell>\n    {delim}"))
-                continue
-            else: code = line
-            print(".", flush=True)
-            try: body = execute(code)
-            except BaseException: body = fmt_error("internal-error", traceback.format_exc())
+            body, accepted = _response(line, sys.stdin, delim, execute)
             _write_response(delim, body)
-            if should_exit and should_exit(): break
+            if accepted and should_exit and should_exit(): break
     finally:
         _restore_termios(echo_state)
         _restore_termios(output_state)
@@ -134,20 +139,22 @@ def main(
         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=''))
+    info = run(g.text('use_kernel', kernel=kernel) if kernel else g.text('create', kernel='ipymini'))
     stop = False
     def execute(code):
         nonlocal stop
         if code.strip() in _EXITS:
             stop = True
             return ''
-        fut = asyncio.run_coroutine_threadsafe(g.text('py', code=code), loop)
+        fut = asyncio.run_coroutine_threadsafe(g.text('exec', code=code), loop)
         while True:
             try: return fut.result()
             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.12}/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,15 +99,15 @@ 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"
+    "Build Python defaults, user startup, and inspector setup, in that order."
     d = Path(cfgdir) if cfgdir else cfg_dir()
-    parts = []
+    parts = ["get_ipython().ast_node_interactivity = 'all'"]
     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"
+    "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,8 +116,9 @@ 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"
-    def __init__(self,
+    "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
         verify=True,  # Verify TLS certificates?
@@ -121,41 +128,48 @@ 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
 
-    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 #2dd701f9
+@patch
+async def tools(self:Gateway): return (await self.rpc('tools/list'))['tools']
+@patch
+async def call(self:Gateway, name, **args): return await self.rpc('tools/call', name=name, arguments=args)
+
+@patch
+async def text(self:Gateway, name, **args):
+    "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
+
+# %% ../nbs/00_core.ipynb #dac7dd25
+@patch
+async def aclose(self:Gateway):
+    "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.12}/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,15 +27,16 @@ 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"
-    def __init__(self,
+    "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?
     ):
         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)
@@ -39,24 +44,19 @@ class Router:
             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"
+    "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)
     return ts
 
+# %% ../nbs/01_mcp.ipynb #e1b057dd
 @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':
@@ -78,14 +78,25 @@ async def dispatch(self:Router, msg, requester=None):
         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 #f72f6253
+@patch
+async def aclose(self:Router):
+    "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 #3b90f0e8
 @call_parse
 def main(
     quiet:store_true=False,  # Keep startup output out of replies
+    cfgdir:str=None,  # Directory holding `startup.py`, `inspectors.py`, and `gateways.toml`; `~/.config/clikernel/` if unset
 ):
-    "The `clikernel-mcp` console script: the router on stdio"
+    "Run `clikernel-mcp` as a stdio server."
     async def _main():
-        router = Router(quiet=quiet)
+        router = Router(cfgdir, quiet=quiet)
         try: await serve_stdio(router)
         finally: await router.aclose()
     asyncio.run(_main())

{clikernel-0.2.10 → clikernel-0.2.12}/clikernel/skill.py

@@ -4,24 +4,28 @@ Prefer it over one-off Python scripts (`python -c`, shell heredocs). Prefer in-k
 
 # Starting and stopping
 
-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.
+Call `create(kernel="ipymini")` before executing Python code. Creation reports what startup imported: read that banner, it says what to do next. New kernels require an explicit implementation. Add `dlgname` to bind a kernel to a dialog. Omit `kernel` only to reuse an existing binding. An explicit implementation must match that binding.
+
+A kernel this conversation creates stops when the conversation ends, unless created with `autoclose=false`. Use `create(kernel="ipymini", dlgname="work", autoclose=false)` when a kernel should stay running afterwards, and tell the user its id. This requires a gateway that keeps running. 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 `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; 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.
+`restart` gives a fresh interpreter under the same id; Python startup re-runs in Python kernels this conversation created, so redo everything else. `interrupt` stops a long `exec` and keeps state. If a reply says the kernel is gone, call `create` or `use_kernel` before executing again. Execution never creates or switches kernels.
 
-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.
+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 `exec` runs there until the next selection.
 
 # Working in it
 
-For native Luau work use `lua(code=...)`, or `create(dlgname, language="luau")` for a named kernel. The first `lua` auto-starts Luau when no kernel is selected, with the same autoclose rules as Python. There is one current kernel: `py` requires Python and `lua` requires Luau, so a mismatch errors rather than switching. Use `use_kernel` or `create` to select deliberately. Omit `language` to reuse an existing binding unchanged or default a new one to Python; an explicit language must match an existing binding. A `dlgname` execution override changes only that call. These rules also apply on named remote gateways.
+Run code with `exec(code=...)` in the selected kernel. For native Luau work, select `create(kernel="luau")` first. The same execution tool and autoclose rules apply to every implementation. A `dlgname` execution override uses an existing binding for that call without changing the current selection. These rules also apply on named remote gateways.
+
+For APL, use `create(kernel="miniapl")` then `exec(code="avg←+/÷≢ ⋄ avg 2 4 9")`. Miniapl must be installed on the gateway's PATH. Python startup and inspectors do not run in APL.
 
-Start native work with `lua(code="help()")` for the bundled guide and examples, or `lua(code='help("ex.edit_file")')` for function details.
+Start native work with `exec(code="help()")` for the bundled guide and examples, or `exec(code='help("ex.edit_file")')` for function details.
 
 Luau has persistent globals, cell-local `local` variables, and native `rg.search`, `rg.find`, `fs.read_text`, `ex.edit_text`, `ex.view_file`/`ex.edit_file`, `ex.view_cell`/`ex.edit_cell`, `os.execute`, and `io.popen` APIs. File edits use arrays of command fields (like Python exhash tuples); `{inplace=false}` previews. Shell commands use `/bin/sh -c`; pipes support read/lines/write/flush/close and persist until closed. Interrupts terminate subprocess groups and close outstanding pipes. Python startup/inspectors and IPython magics do not apply to Luau. The following guidance is for Python:
 
 - 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.
+- Python kernels created by clikernel display every expression result by default (`ast_node_interactivity='all'`); user startup can override this.
 - 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.2.10
+Version: 0.2.12
 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,8 +14,8 @@ 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.11
+Requires-Dist: mcpmini>=0.0.5
+Requires-Dist: rustygate>=0.1.19
 Requires-Dist: httpx
 Provides-Extra: dev
 Requires-Dist: fastship; extra == "dev"
@@ -26,16 +26,11 @@ Dynamic: license-file
 
 <!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
 
-`clikernel` gives an LLM agent a persistent Python or Luau session. Imports, variables, and results remain available between tool calls. An agent can create a kernel or attach to an existing one, including a user’s live solveit kernel, on a local or named remote gateway.
+`clikernel` gives LLM agents persistent kernel sessions over MCP or a plain stream protocol. Imports, variables, and results remain available between calls. Agents can create kernels or attach to existing ones, including a user’s live solveit kernel.
 
-[rustygate](https://github.com/AnswerDotAI/rustygate) hosts the Jupyter kernels and provides their MCP tools. `clikernel` is the conversation-side router: the MCP host launches it over stdio, and it forwards requests to gateways over HTTP. It selects gateways from `gateways.toml`, supplies `startup.py` and `inspectors.py` to Python kernels it creates, and starts a private local gateway when needed. The default kernel is [ipymini](https://github.com/AnswerDotAI/ipymini).
+[rustygate](https://github.com/AnswerDotAI/rustygate) hosts the kernels. Clikernel routes requests to local or named remote gateways and supplies startup code to Python kernels.
 
-Kernel ownership determines what happens when the conversation ends:
-
-- A session closes kernels it created with `autoclose`, including the automatic kernel used by bare `py` or `lua` and kernels created with `create`’s default settings.
-- Attaching with `use_kernel` does not make that session responsible for closing the kernel.
-- A kernel created with `autoclose=false` on a resident gateway can outlive the conversation. A later conversation can attach and continue using its state.
-- A private child gateway ends with its conversation. Use a resident gateway for kernels that need to survive across conversations.
+New kernels close with their creating conversation by default. Attaching to an existing kernel does not claim ownership. Use `autoclose=false` on a persistent gateway to keep a new kernel for later conversations. See [core](https://AnswerDotAI.github.io/clikernel/core.html) for configuration and lifecycle details.
 
 ## Install
 
@@ -57,19 +52,18 @@ Register the stdio server with your MCP host. For Claude Code:
 claude mcp add clikernel -- clikernel-mcp
 ```
 
-Use `py(code=...)` for Python/IPython or `lua(code=...)` for bundled Luau. Either starts its language’s kernel when none is current. There is one current kernel: a language mismatch errors without switching or running the code. IPython magics, including `%%bash`, are Python-only.
-
-For a named kernel, use `create(dlgname="work", language="luau")`. Omit `language` to reuse an existing binding unchanged, or default a new kernel to Python. An explicit language must match an existing binding. The other tools are `list_kernels`, `use_kernel`, `delete_kernel`, `restart`, and `interrupt`; creation, selection, and listing report the language.
+Choose a kernel, then execute code:
 
-These tools forward to rustygate. `list_kernels`, `use_kernel`, and `create` also accept a `host` naming a gateway from `gateways.toml`. One MCP registration can therefore reach multiple machines. Replies retain the gateway’s text and image blocks. Python startup and inspectors run only in Python, never Luau, including after restart.
-
-`$CLIKERNEL_HOST` overrides the default gateway URL, `http://127.0.0.1:8787`. If no gateway answers, clikernel uses a private child gateway for the conversation. The ownership rules above determine which kernels close at session end.
+``` python
+create(kernel="ipymini")
+exec(code="6*7")
+```
 
-Pass `--quiet`, as in `clikernel-mcp --quiet`, to omit startup output from replies. Python startup code still runs.
+Use `kernel="luau"` for bundled Luau, or `kernel="miniapl"` for APL when miniapl is installed on the gateway. `exec` never creates or switches kernels. See [MCP](https://AnswerDotAI.github.io/clikernel/mcp.html) for named gateways, dialog bindings, and other tools.
 
 ## Configuration
 
-Three optional files in `$XDG_CONFIG_HOME/clikernel/` configure the router, usually under `~/.config/clikernel/`:
+Three optional files in `$XDG_CONFIG_HOME/clikernel/` configure the router, usually under `~/.config/clikernel/`, or under the directory `clikernel-mcp --cfgdir` names:
 
 - `startup.py` runs in each Python kernel clikernel creates, with `__file__` set to its path. Its output appears in the reply announcing the kernel unless `--quiet` is set.
 - `inspectors.py` installs Python cell inspectors after startup. Define `inspect`, a list named `inspectors`, or both. Each inspector runs once before a cell: a one-argument inspector takes the cell’s AST, and a two-argument inspector takes the AST and raw source. Return a string to print a note before the output. Raise the provided `RuleBlock` to block execution. Other exceptions produce a warning and allow the cell to run. See [examples/inspectors.py](examples/inspectors.py).

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

@@ -1,8 +1,8 @@
 fastcore>=2.2.2
 jupyasyncclient>=0.2.10
 jupywire>=0.1.9
-mcpmini>=0.0.4
-rustygate>=0.1.11
+mcpmini>=0.0.5
+rustygate>=0.1.19
 httpx
 
 [dev]

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

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

clikernel-0.2.10/README.md

@@ -1,71 +0,0 @@
-# clikernel
-
-
-<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
-
-`clikernel` gives an LLM agent a persistent Python or Luau session. Imports, variables, and results remain available between tool calls. An agent can create a kernel or attach to an existing one, including a user’s live solveit kernel, on a local or named remote gateway.
-
-[rustygate](https://github.com/AnswerDotAI/rustygate) hosts the Jupyter kernels and provides their MCP tools. `clikernel` is the conversation-side router: the MCP host launches it over stdio, and it forwards requests to gateways over HTTP. It selects gateways from `gateways.toml`, supplies `startup.py` and `inspectors.py` to Python kernels it creates, and starts a private local gateway when needed. The default kernel is [ipymini](https://github.com/AnswerDotAI/ipymini).
-
-Kernel ownership determines what happens when the conversation ends:
-
-- A session closes kernels it created with `autoclose`, including the automatic kernel used by bare `py` or `lua` and kernels created with `create`’s default settings.
-- Attaching with `use_kernel` does not make that session responsible for closing the kernel.
-- A kernel created with `autoclose=false` on a resident gateway can outlive the conversation. A later conversation can attach and continue using its state.
-- A private child gateway ends with its conversation. Use a resident gateway for kernels that need to survive across conversations.
-
-## Install
-
-``` sh
-pip install clikernel
-```
-
-This installs rustygate and ipymini. No service setup is required for a conversation-local kernel: clikernel starts a private gateway if it cannot find one. To retain kernels across conversations, run a resident gateway, for example through launchd or systemd:
-
-``` sh
-rustygate --port 8787
-```
-
-## Use with an MCP host
-
-Register the stdio server with your MCP host. For Claude Code:
-
-``` sh
-claude mcp add clikernel -- clikernel-mcp
-```
-
-Use `py(code=...)` for Python/IPython or `lua(code=...)` for bundled Luau. Either starts its language’s kernel when none is current. There is one current kernel: a language mismatch errors without switching or running the code. IPython magics, including `%%bash`, are Python-only.
-
-For a named kernel, use `create(dlgname="work", language="luau")`. Omit `language` to reuse an existing binding unchanged, or default a new kernel to Python. An explicit language must match an existing binding. The other tools are `list_kernels`, `use_kernel`, `delete_kernel`, `restart`, and `interrupt`; creation, selection, and listing report the language.
-
-These tools forward to rustygate. `list_kernels`, `use_kernel`, and `create` also accept a `host` naming a gateway from `gateways.toml`. One MCP registration can therefore reach multiple machines. Replies retain the gateway’s text and image blocks. Python startup and inspectors run only in Python, never Luau, including after restart.
-
-`$CLIKERNEL_HOST` overrides the default gateway URL, `http://127.0.0.1:8787`. If no gateway answers, clikernel uses a private child gateway for the conversation. The ownership rules above determine which kernels close at session end.
-
-Pass `--quiet`, as in `clikernel-mcp --quiet`, to omit startup output from replies. Python startup code still runs.
-
-## Configuration
-
-Three optional files in `$XDG_CONFIG_HOME/clikernel/` configure the router, usually under `~/.config/clikernel/`:
-
-- `startup.py` runs in each Python kernel clikernel creates, with `__file__` set to its path. Its output appears in the reply announcing the kernel unless `--quiet` is set.
-- `inspectors.py` installs Python cell inspectors after startup. Define `inspect`, a list named `inspectors`, or both. Each inspector runs once before a cell: a one-argument inspector takes the cell’s AST, and a two-argument inspector takes the AST and raw source. Return a string to print a note before the output. Raise the provided `RuleBlock` to block execution. Other exceptions produce a warning and allow the cell to run. See [examples/inspectors.py](examples/inspectors.py).
-- `gateways.toml` names remote gateways and configures authentication without putting tokens 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 for clients that read a text stream rather than MCP messages. It uses a delimiter-framed stdin/stdout protocol:
-
-- Input is not echoed.
-- Each request gets a `.` acknowledgement.
-- A per-process random delimiter marks the end of each response.
-- Multiline cells are framed by `--` and the delimiter.
-
-The startup banner supplies the protocol instructions and delimiter. Running `clikernel` without arguments creates a kernel and stops it on exit. `--kernel <id>` attaches to an existing kernel and leaves it running on exit.