clikernel 0.2.9__tar.gz → 0.2.11__tar.gz

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

@@ -2,6 +2,20 @@
 
 <!-- do not remove -->
 
+## 0.2.11
+
+### New Features
+
+- Rewrite module and API docs for clarity, harden session cleanup with try/finally and grouped errors, negotiate MCP protocol version ([#49](https://github.com/AnswerDotAI/clikernel/issues/49))
+
+
+## 0.2.10
+
+### New Features
+
+- Add Luau kernel support: lua tool and create(language=...), Python-only startup/inspectors ([#48](https://github.com/AnswerDotAI/clikernel/issues/48))
+
+
 ## 0.2.9
 
 ### Breaking Changes

clikernel-0.2.11/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: clikernel
+Version: 0.2.11
+Summary: Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol
+Author: clikernel contributors
+License: Apache-2.0
+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.5
+Requires-Dist: rustygate>=0.1.11
+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 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.

clikernel-0.2.11/README.md

@@ -0,0 +1,71 @@
+# 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.

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

@@ -4,8 +4,8 @@ Modules:
 
 - `clikernel.cli`: The stream-protocol frontend: the service on stdin/stdout for token-reading clients
 - `clikernel.core`: Gateway naming, startup delivery, and MCP sessions on rustygate gateways
-- `clikernel.mcp`: The MCP frontend: a stdio router over rustygate gateways
+- `clikernel.mcp`: Route stdio MCP requests to rustygate gateways
 - `clikernel.skill`: Use the `clikernel` MCP session as the default workspace for Python work: reading and changing files, notebook work, trying things out, checking how a library behaves, and reshaping data. One session stays open, so imports and variables carry between calls. Read this before writing, running, or debugging Python code in a session with `clikernel` connected.
 - `clikernel.stream`: Streaming JSON-lines worker protocol: nbformat-shaped output events, and a supervisor for select-based UIs."""
 
-__version__ = "0.2.9"
+__version__ = "0.2.11"

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

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

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

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

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

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

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

@@ -14,6 +14,12 @@ Remote gateways are the same tools with a `host` argument on `list_kernels`, `us
 
 # 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.
+
+Start native work with `lua(code="help()")` for the bundled guide and examples, or `lua(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.
 - Everything a cell outputs lands in the conversation. Be selective: `len(v)` first, then decide what to show.

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

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: clikernel
+Version: 0.2.11
+Summary: Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol
+Author: clikernel contributors
+License: Apache-2.0
+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.5
+Requires-Dist: rustygate>=0.1.11
+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 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.

{clikernel-0.2.9 → clikernel-0.2.11}/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.7
+mcpmini>=0.0.5
+rustygate>=0.1.11
 httpx
 
 [dev]

{clikernel-0.2.9 → clikernel-0.2.11}/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.7",
+  "mcpmini>=0.0.5",
+  "rustygate>=0.1.11",
   "httpx",
 ]
 

clikernel-0.2.9/PKG-INFO

@@ -1,76 +0,0 @@
-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

@@ -1,53 +0,0 @@
-# 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/clikernel.egg-info/PKG-INFO

@@ -1,76 +0,0 @@
-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.