clikernel 0.2.11__tar.gz → 0.2.12__tar.gz

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

@@ -2,6 +2,14 @@
 
 <!-- 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.2.11
+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
@@ -15,7 +15,7 @@ Requires-Dist: fastcore>=2.2.2
 Requires-Dist: jupyasyncclient>=0.2.10
 Requires-Dist: jupywire>=0.1.9
 Requires-Dist: mcpmini>=0.0.5
-Requires-Dist: rustygate>=0.1.11
+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.11 → clikernel-0.2.12}/clikernel/__init__.py

@@ -8,4 +8,4 @@ Modules:
 - `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.11"
+__version__ = "0.2.12"

{clikernel-0.2.11 → 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.11 → 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,14 +139,14 @@ 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)

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

@@ -99,9 +99,9 @@ def _inspector_setup(src):
 
 # %% ../nbs/00_core.ipynb #1362e6ce
 def startup_src(cfgdir=None):
-    "Combine wrapped `startup.py` source with the inspector installer, in that order."
+    "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)
@@ -117,7 +117,8 @@ def session_defaults(cfgdir=None, quiet=False, local=True):
 # %% ../nbs/00_core.ipynb #10ed59fc
 class Gateway:
     "Open an MCP session on rustygate, call its tools, and end the session with DELETE."
-    def __init__(self,
+    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?
@@ -142,20 +143,26 @@ class Gateway:
         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):
-        "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):
-        "Request session termination and close the HTTP connection."
-        try: await self.tr.delete()
-        finally: 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(

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

@@ -28,7 +28,8 @@ HOSTED = ('list_kernels', 'use_kernel', 'create')
 
 class Router:
     "Route stdio MCP to rustygate with one session per host and one current host."
-    def __init__(self,
+    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?
     ):
@@ -43,15 +44,6 @@ class Router:
             else: self.sessions[host], self.child = await default_gateway(self.cfgdir, self.quiet)
         return self.sessions[host]
 
-    async def aclose(self):
-        "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):
@@ -61,6 +53,7 @@ async def tools(self:Router):
         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):
     "Answer initialization and ping locally. Forward tool calls to gateways."
@@ -85,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
 ):
     "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.11 → 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.11 → clikernel-0.2.12/clikernel.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.2.11
+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
@@ -15,7 +15,7 @@ Requires-Dist: fastcore>=2.2.2
 Requires-Dist: jupyasyncclient>=0.2.10
 Requires-Dist: jupywire>=0.1.9
 Requires-Dist: mcpmini>=0.0.5
-Requires-Dist: rustygate>=0.1.11
+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.11 → clikernel-0.2.12}/clikernel.egg-info/requires.txt

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

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

@@ -20,7 +20,7 @@ dependencies = [
   "jupyasyncclient>=0.2.10",
   "jupywire>=0.1.9",
   "mcpmini>=0.0.5",
-  "rustygate>=0.1.11",
+  "rustygate>=0.1.19",
   "httpx",
 ]
 

clikernel-0.2.11/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.