clikernel 0.2.13__tar.gz → 0.2.15__tar.gz

{clikernel-0.2.13 → clikernel-0.2.15}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 <!-- do not remove -->
 
+## 0.2.15
+
+### New Features
+
+- Replace kernel-side inspectors with built-in router cell rules checking each exec cell, adding notes or blocking subprocess and sys.path ([#54](https://github.com/AnswerDotAI/clikernel/issues/54))
+
+
+## 0.2.14
+
+### Bugs Squashed
+
+- Open a new gateway session after rustygate restarts ([#53](https://github.com/AnswerDotAI/clikernel/pull/53)), thanks to [@jph00](https://github.com/jph00)
+
+
 ## 0.2.13
 
 ### New Features

{clikernel-0.2.13 → clikernel-0.2.15}/MANIFEST.in

@@ -1,4 +1,3 @@
 include README.md
 include LICENSE
 include CHANGELOG.md
-recursive-include clikernel/dojo_data *

{clikernel-0.2.13/clikernel.egg-info → clikernel-0.2.15}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.2.13
+Version: 0.2.15
 Summary: Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol
 Author: clikernel contributors
-License: Apache-2.0
+License-Expression: Apache-2.0
 Project-URL: Repository, https://github.com/AnswerDotAI/clikernel
 Project-URL: Documentation, https://AnswerDotAI.github.io/clikernel/
 Classifier: Programming Language :: Python :: 3
@@ -18,6 +18,7 @@ Requires-Dist: mcpmini>=0.0.5
 Requires-Dist: rustygate>=0.1.22
 Requires-Dist: ipymini>=0.1.23
 Requires-Dist: httpx
+Requires-Dist: ipython
 Provides-Extra: dev
 Requires-Dist: fastship; extra == "dev"
 Dynamic: license-file
@@ -62,12 +63,13 @@ exec(code="6*7")
 
 Use `kernel="luau"` for bundled Luau, or `kernel="apl"` for APL when `basedpl` is installed in the gateway’s environment. `create` accepts any kernelspec the gateway finds. `exec` never creates or switches kernels. See [MCP](https://AnswerDotAI.github.io/clikernel/mcp.html) for named gateways, dialog bindings, and other tools.
 
+The router checks each `exec` cell against built-in rules for mistakes agents often make with this toolkit. Most rules add a note to the reply, and `--quiet` leaves the notes out. Two rules always block the cell: shell access through `subprocess`, [`os.system`](https://docs.python.org/3/library/os.html#os.system) or [`os.popen`](https://docs.python.org/3/library/os.html#os.popen), and changes to `sys.path`.
+
 ## Configuration
 
-Three optional files in `$XDG_CONFIG_HOME/clikernel/` configure the router, usually under `~/.config/clikernel/`, or under the directory `clikernel-mcp --cfgdir` names:
+Two 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

{clikernel-0.2.13 → clikernel-0.2.15}/README.md

@@ -38,12 +38,13 @@ exec(code="6*7")
 
 Use `kernel="luau"` for bundled Luau, or `kernel="apl"` for APL when `basedpl` is installed in the gateway’s environment. `create` accepts any kernelspec the gateway finds. `exec` never creates or switches kernels. See [MCP](https://AnswerDotAI.github.io/clikernel/mcp.html) for named gateways, dialog bindings, and other tools.
 
+The router checks each `exec` cell against built-in rules for mistakes agents often make with this toolkit. Most rules add a note to the reply, and `--quiet` leaves the notes out. Two rules always block the cell: shell access through `subprocess`, [`os.system`](https://docs.python.org/3/library/os.html#os.system) or [`os.popen`](https://docs.python.org/3/library/os.html#os.popen), and changes to `sys.path`.
+
 ## Configuration
 
-Three optional files in `$XDG_CONFIG_HOME/clikernel/` configure the router, usually under `~/.config/clikernel/`, or under the directory `clikernel-mcp --cfgdir` names:
+Two 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

{clikernel-0.2.13 → clikernel-0.2.15}/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.13"
+__version__ = "0.2.15"

{clikernel-0.2.13 → clikernel-0.2.15}/clikernel/_modidx.py

@@ -23,7 +23,6 @@ d = { 'settings': { 'branch': 'main',
                                 'clikernel.core.Gateway.rpc': ('core.html#gateway.rpc', 'clikernel/core.py'),
                                 'clikernel.core.Gateway.text': ('core.html#gateway.text', 'clikernel/core.py'),
                                 'clikernel.core.Gateway.tools': ('core.html#gateway.tools', 'clikernel/core.py'),
-                                'clikernel.core._inspector_setup': ('core.html#_inspector_setup', 'clikernel/core.py'),
                                 'clikernel.core._startup_src': ('core.html#_startup_src', 'clikernel/core.py'),
                                 'clikernel.core.cfg_dir': ('core.html#cfg_dir', 'clikernel/core.py'),
                                 'clikernel.core.default_gateway': ('core.html#default_gateway', 'clikernel/core.py'),
@@ -37,6 +36,4 @@ d = { 'settings': { 'branch': 'main',
                                'clikernel.mcp.Router.dispatch': ('mcp.html#router.dispatch', 'clikernel/mcp.py'),
                                'clikernel.mcp.Router.session': ('mcp.html#router.session', 'clikernel/mcp.py'),
                                'clikernel.mcp.Router.tools': ('mcp.html#router.tools', 'clikernel/mcp.py'),
-                               'clikernel.mcp.main': ('mcp.html#main', 'clikernel/mcp.py')},
-            'clikernel.skill': {},
-            'clikernel.stream': {}}}
+                               'clikernel.mcp.main': ('mcp.html#main', 'clikernel/mcp.py')}}}

{clikernel-0.2.13 → clikernel-0.2.15}/clikernel/core.py

@@ -2,7 +2,7 @@
 
 [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.
+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 sends `startup.py` as source, so it 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.
 
@@ -52,58 +52,12 @@ def _startup_src(src, path):
 try: exec(compile({src!r}, __file__, 'exec'))
 finally: del __file__'''
 
-# %% ../nbs/00_core.ipynb #3dbf4cb6
-_INSP_RUNNER = r'''
-import inspect as _clik_inspect
-import sys as _clik_sys
-from IPython.core.error import InputRejected
-class RuleBlock(InputRejected):
-    "Raise from an inspector to deliberately block a cell; any other inspector exception is a bug, and fails open"
-
-class _ClikInspect:
-    "Calls each inspector once per cell: 1-arg get the AST, 2-arg also the raw source"
-    def __init__(self, fs): self.fs = fs
-    def visit(self, tree):
-        fr, n = _clik_sys._getframe(), 0
-        while fr:
-            n += fr.f_code.co_name == 'run_cell_async'
-            fr = fr.f_back
-        if n > 1: return tree  # nested run_cell: cell replayed by a tool (%nbrun etc.), not typed
-        for f in self.fs:
-            try:
-                note = f(tree, _clik_src) if len(_clik_inspect.signature(f).parameters) > 1 else f(tree)
-                if note: print(note, end='')
-            except InputRejected: raise
-            except Exception as e: print(f'inspector error (cell runs anyway): {e!r}')
-        return tree
-
-def _clik_stash(info):
-    global _clik_src
-    _clik_src = info.raw_cell
-
-def _clik_install(src):
-    ns = dict(RuleBlock=RuleBlock)
-    exec(compile(src, 'inspectors.py', 'exec'), ns)
-    fs = list(ns.get('inspectors') or [])
-    if callable(ns.get('inspect')): fs.append(ns['inspect'])
-    if fs:
-        ip = get_ipython()
-        ip.events.register('pre_run_cell', _clik_stash)
-        ip.ast_transformers.append(_ClikInspect(fs))
-_clik_src = ''
-'''
-
-def _inspector_setup(src):
-    "Kernel-side source installing the inspectors defined in `src`; a load failure raises, failing the create call"
-    return _INSP_RUNNER + f'\n_clik_install({src!r})'
-
 # %% ../nbs/00_core.ipynb #1362e6ce
 def startup_src(cfgdir=None):
-    "Build Python defaults, user startup, and inspector setup, in that order."
+    "Build Python defaults and user startup, in that order."
     d = Path(cfgdir) if cfgdir else cfg_dir()
     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):
@@ -111,7 +65,7 @@ def session_defaults(cfgdir=None, quiet=False, local=True):
     d = dict(startup=startup_src(cfgdir), quiet=quiet)
     if local:
         d['cwd'] = os.getcwd()
-        d['env'] = dict(os.environ, CLIKERNEL_QUIET='1') if quiet else dict(os.environ)
+        d['env'] = dict(os.environ)
     return d
 
 # %% ../nbs/00_core.ipynb #10ed59fc

{clikernel-0.2.13 → clikernel-0.2.15}/clikernel/mcp.py

@@ -4,6 +4,8 @@ Claude Code starts `clikernel-mcp` for each conversation. Its `Router` accepts M
 
 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.
 
+Before forwarding `exec`, the router checks the cell against `clikernel.rules`. Most rules add a note to the reply. Two rules block the cell, which then never reaches a gateway.
+
 `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"""
@@ -14,14 +16,14 @@ Docs: https://AnswerDotAI.github.io/clikernel/mcp.html.md"""
 __all__ = ['HOST_PARAM', 'HOSTED', 'Router', 'main']
 
 # %% ../nbs/01_mcp.ipynb #28c42902
-import asyncio
+import asyncio, httpx
 from fastcore.utils import *
 from fastcore.script import call_parse, store_true
 from mcpmini.core import serve_stdio, jresp, jerr
 from .core import Gateway, default_gateway, resolve, session_defaults
+from .rules import scan
 from . import __version__
 
-
 # %% ../nbs/01_mcp.ipynb #76e2d782
 HOST_PARAM = {'type': 'string', 'description': 'Gateway to target: a gateways.toml name, or empty for the default local gateway'}
 HOSTED = ('list_kernels', 'use_kernel', 'create')
@@ -31,7 +33,7 @@ class Router:
     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?
+        quiet=False,  # Keep startup output and rule notes out of replies?
     ):
         self.cfgdir,self.quiet,self.sessions,self.cur,self.child = cfgdir,quiet,{},'',None
 
@@ -70,11 +72,22 @@ async def dispatch(self:Router, msg, requester=None):
         if method == 'tools/list': return jresp(id, dict(tools=await self.tools()))
         if method == 'tools/call':
             args = msg['params'].setdefault('arguments', {})
+            fired = scan(args.get('code', '')) if msg['params']['name'] == 'exec' else []
+            if blocks := [r.note for r in fired if r.block]:
+                return jresp(id, dict(isError=True, content=[dict(type='text', text=' '.join(blocks)+' (If the block seems wrong here, tell your user.)')]))
             has_host = 'host' in args
             host = args.pop('host', '') or ''
-            s = await self.session(host if has_host else self.cur)
+            h = host if has_host else self.cur
+            s = await self.session(h)
             if has_host and msg['params']['name'] in ('use_kernel', 'create'): self.cur = host
-            return await s.tr.send(msg)
+            try: res = await s.tr.send(msg)
+            except httpx.HTTPStatusError as e:
+                if e.response.status_code != 404: raise
+                del self.sessions[h]  # a restarted gateway answers 404 for a session id it no longer knows
+                res = await (await self.session(h)).tr.send(msg)
+            if fired and not self.quiet and 'result' in res:
+                res['result']['content'].insert(0, dict(type='text', text=''.join(f'<note>\n{r.note}\n</note>\n' for r in fired)))
+            return res
         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))
 
@@ -91,8 +104,8 @@ async def aclose(self:Router):
 # %% ../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
+    quiet:store_true=False,  # Keep startup output and rule notes out of replies
+    cfgdir:str=None,  # Directory holding `startup.py` and `gateways.toml`; `~/.config/clikernel/` if unset
 ):
     "Run `clikernel-mcp` as a stdio server."
     async def _main():

clikernel-0.2.15/clikernel/rules.py

@@ -0,0 +1,169 @@
+"""Rules that check agent-written kernel cells for common mistakes with this toolkit. The router checks each `exec` cell before forwarding it: most rules add a note to the reply, and blocking rules stop the cell. Rules see only the cell's text, not which kernel will run it, so each matches Python forms that no other kernel language produces."""
+import ast,re,tokenize
+from IPython.core.inputtransformer2 import TransformerManager
+from io import StringIO
+from fastcore.basics import store_attr
+
+
+class Rule:
+    "A named check: `fn(tree, src)` is truthy when `note` applies; `block` stops the cell, and `raw` checks the source as typed rather than as IPython transforms it"
+    def __init__(self, name, note, fn, block=False, raw=False): store_attr()
+
+_TOOLING = {'lnhashview','lnhashview_file','lnhashview_cell','lnhashview_cells','rg','nbrg','fd',
+    'find_msgs','summary_dlg','view_dlg','view_msg','view_msgs','view_file','view_cell','doc','info_md'}
+
+
+def _calls(tree):
+    for n in ast.walk(tree):
+        if isinstance(n, ast.Call): yield n
+
+
+def _callee(c): return c.func.id if isinstance(c.func, ast.Name) else None
+
+
+_DATA_EXTS = ('.json','.jsonl','.ndjson','.csv','.tsv','.log')
+
+def _textpath(node):
+    "A string constant under `node` recognisably names a non-data file: only then is a view-note earned"
+    return any(isinstance(n, ast.Constant) and isinstance(n.value, str) and '.' in n.value
+        and not n.value.lower().endswith(_DATA_EXTS) for n in ast.walk(node))
+
+
+def _is_read(c):
+    "A read_text()/open().read() call on a recognisably-named non-data file"
+    if not (isinstance(c, ast.Call) and isinstance(c.func, ast.Attribute)): return False
+    if c.func.attr == 'read_text': return _textpath(c.func.value)
+    return c.func.attr == 'read' and isinstance(c.func.value, ast.Call) and _callee(c.func.value) == 'open' and _textpath(c.func.value)
+
+
+def _read_file(tree, src):
+    "Only a displayed read (bare expression or print) earns the note: a parser-bound or assigned read never enters context"
+    for n in ast.walk(tree):
+        if isinstance(n, ast.Expr):
+            v = n.value
+            if _is_read(v): return True
+            if isinstance(v, ast.Call) and _callee(v) == 'print' and any(_is_read(a) for a in v.args): return True
+
+
+def _big_replace(tree, src):
+    for c in _calls(tree):
+        if _callee(c) in ('file_replace_lines','cell_replace_lines'):
+            for k in c.keywords:
+                if k.arg == 'new_content' and isinstance(k.value, ast.Constant) and str(k.value.value).count('\n') >= 6: return True
+
+
+def _cell_str_replace(tree, src):
+    "Only the obvious single-cell form (a literal id that isn't 'all'): batch replaces over many cells are sanctioned"
+    for c in _calls(tree):
+        if _callee(c) != 'cell_str_replace': continue
+        cid = c.args[0] if c.args else next((k.value for k in c.keywords if k.arg == 'id'), None)
+        if isinstance(cid, ast.Constant) and isinstance(cid.value, str) and cid.value != 'all': return True
+
+
+def _rawstr(tree, src):
+    try: toks = list(tokenize.generate_tokens(StringIO(src).readline))
+    except tokenize.TokenizeError: return
+    for t in toks:
+        if t.type == tokenize.STRING:
+            m = re.match(r"""([A-Za-z]*)('''|\"\"\")""", t.string)
+            if m and 'r' not in m[1].lower() and '\\' in t.string: return True
+
+
+def _hashcalc(tree, src): return any(_callee(c) in ('lnhash','line_hash') for c in _calls(tree))
+
+
+def _cmds(c):
+    "Top-level command-tuple nodes of an exhash/file_exhash/cell_exhash call"
+    if _callee(c) == 'exhash':
+        a = c.args[1] if len(c.args) > 1 else None
+        return a.elts if isinstance(a, (ast.List, ast.Tuple)) and any(isinstance(e, ast.Tuple) for e in a.elts) else []
+    return c.args[2 if _callee(c) == 'cell_exhash' else 1:]
+
+def _tuple_payload(tree, src):
+    "A lone constant a/i/c payload that is long or contains quotes/backslashes belongs in a %%exhash cell; multi-command calls are exempt, since the one-command magic can't express them atomically"
+    for c in _calls(tree):
+        if _callee(c) not in ('exhash','file_exhash','cell_exhash'): continue
+        cmds = _cmds(c)
+        if len(cmds) != 1 or not isinstance(cmds[0], ast.Tuple): continue
+        n = cmds[0]
+        if len(n.elts) < 3: continue
+        cmd,payload = n.elts[1],n.elts[2]
+        if not (isinstance(cmd, ast.Constant) and cmd.value in ('a','i','c')): continue
+        if not (isinstance(payload, ast.Constant) and isinstance(payload.value, str)): continue
+        if len(payload.value) > 20 or any(ch in payload.value for ch in '\'"\\'): return True
+
+
+def _s_repls(tree):
+    "String-constant replacement fields of s-commands in exhash calls"
+    for c in _calls(tree):
+        if _callee(c) not in ('exhash','file_exhash','cell_exhash'): continue
+        for n in ast.walk(c):
+            if not (isinstance(n, ast.Tuple) and len(n.elts) >= 4): continue
+            if not (isinstance(n.elts[1], ast.Constant) and n.elts[1].value == 's'): continue
+            if isinstance(n.elts[3], ast.Constant) and isinstance(n.elts[3].value, str): yield n.elts[3].value
+
+
+def _s_newline(tree, src): return any('\\n' in r for r in _s_repls(tree))
+
+
+def _s_long(tree, src): return any(len(r) > 120 for r in _s_repls(tree))
+
+
+
+def _postproc(tree, src):
+    for n in ast.walk(tree):
+        if isinstance(n, ast.Attribute) and isinstance(n.value, ast.Call) and _callee(n.value) in _TOOLING \
+           and n.attr in ('splitlines','split','join'): return True
+        if isinstance(n, ast.Call) and isinstance(n.func, ast.Attribute) and n.func.attr == 'join' \
+           and isinstance(n.func.value, ast.Constant) \
+           and any(_callee(c) in _TOOLING for a in n.args for c in _calls(a)): return True
+
+
+def _run_magic(tree, src):
+    # raw-source rule: in the transformed cell every magic becomes run_*_magic, so only literal raw uses count
+    return 'run_line_magic' in src or 'run_cell_magic' in src
+
+
+def _shell_escape(tree, src):
+    for n in ast.walk(tree):
+        if isinstance(n, ast.Import) and any(a.name.split('.')[0] == 'subprocess' for a in n.names): return True
+        if isinstance(n, ast.ImportFrom) and (n.module or '').split('.')[0] == 'subprocess': return True
+        if isinstance(n, ast.Call) and isinstance(n.func, ast.Attribute) and n.func.attr in ('system','popen') and isinstance(n.func.value, ast.Name) and n.func.value.id == 'os': return True
+
+
+def _sys_path(tree, src):
+    for c in _calls(tree):
+        f = c.func
+        if isinstance(f, ast.Attribute) and f.attr in ('insert','append') and isinstance(f.value, ast.Attribute) \
+           and f.value.attr == 'path' and isinstance(f.value.value, ast.Name) and f.value.value.id == 'sys': return True
+
+
+RULES = [
+    Rule('read_file', 'Read files with lnhashview_file (for editing) or view_file(nums=False).', _read_file),
+    Rule('big_replace', 'Replace a whole cell or file with %%exhash <path> [<cell_id>] % c; an inner region with a range-c address.', _big_replace),
+    Rule('cell_str_replace', 'Edit notebook cells with %%exhash <path> <cell_id>.', _cell_str_replace),
+    Rule('rawstr', 'Write non-trivial strings as r""" raw strings; %%exhash text needs no escaping at all.', _rawstr),
+    Rule('hashcalc', 'exhash addresses come only from a fresh lnhashview; never compute them.', _hashcalc),
+    Rule('tuple_payload', 'Apply a/i/c text with the %%exhash magic: it needs no quoting or escaping.', _tuple_payload),
+    Rule('s_newline', r'A 2-char \n in an s-replacement stays literal text: use a real newline in the string.', _s_newline),
+    Rule('s_long', 'Use a c command (%%exhash <addr> c) for an s-replacement over 120 chars, except when the line is much longer still.', _s_long),
+    Rule('postproc', "Show tooling results bare; narrow with the tool's own parameters.", _postproc),
+    Rule('run_magic', 'Invoke magics directly with % syntax.', _run_magic, raw=True),
+    Rule('shell_escape', 'Run shell commands with the Bash tool.', _shell_escape, block=True),
+    Rule('sys_path', 'Never modify sys.path; stop and ask the user.', _sys_path, block=True)]
+
+
+_tm = TransformerManager()
+
+def _transform(src):
+    "IPython-transform `src` so magics and `!` escapes parse; the raw text comes back if transformation fails"
+    try: return _tm.transform_cell(src)
+    except Exception: return src
+
+
+def scan(src):
+    "The rules that fire on cell `src`, parsed as IPython would parse it"
+    tsrc = _transform(src)
+    try: tree = ast.parse(tsrc)
+    except SyntaxError: return []
+    return [r for r in RULES if r.fn(tree, src if r.raw else tsrc)]

clikernel-0.2.15/clikernel/skill.py

@@ -0,0 +1,29 @@
+"""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.
+
+Prefer it to one-off scripts (`python -c`, shell heredocs), and in-kernel pyskills to shell equivalents when installed: `rgapi` (`rg()`/`fd()`/`ls()`) for search and listing, `ghapi` for GitHub and local git. Shell stays right for project tests/builds and non-Python tools.
+
+# Kernels
+
+MCP tool descriptions give each tool's parameters and rules; this covers combining them.
+
+`create(kernel="py")` first; its reply reports what startup imported and what to run next: read it before running anything. Kernels this conversation creates stop when it ends; for one that should outlive it, `create(kernel="py", dlgname="work", autoclose=false)` and tell the user its id. That needs a gateway that keeps running: say so if the reply shows a conversation-started gateway.
+
+To continue earlier work or use the user's solveit kernel: `list_kernels`, then `use_kernel` with the id. Attaching runs no setup and claims no ownership: the live state is the point, and it's never stopped for you.
+
+`restart` re-runs Python startup only in kernels this conversation created; redo everything else. `interrupt` stops a long `exec`, keeping state. If a reply says the kernel is gone, `create` or `use_kernel` before executing again.
+
+Remote gateways (named in `~/.config/clikernel/gateways.toml`): same tools, with `host=` on `list_kernels`/`use_kernel`/`create`; all other rules unchanged. After selecting with a host, plain `exec` runs there until the next selection.
+
+# Luau and APL
+
+`create(kernel="luau")`/`create(kernel="apl")`: same `exec` and autoclose rules; no Python startup or magics. Each `create` reply gives the language basics; Luau's `exec(code="help()")` is its full native API guide (`help("ex.edit_file")` for one function). APL needs `basedpl` in the gateway's environment, which provides the `apl` kernelspec.
+
+# Python
+
+- Magics work as written, incl. `%%bash`. Change directory with `%cd` (expands `~`), not `os.chdir`.
+- clikernel-created Python kernels display every expression result (`ast_node_interactivity='all'`); user startup can override.
+- All cell output lands in the conversation: `len(v)` first, then choose what to show.
+- Don't re-run imports already run. A `NameError` for a name you set up means the kernel restarted or is newly attached: redo setup.
+- After `nbdev-export` or any edit to an imported module, `importlib.reload` it and re-import held names: `from x import y` keeps the old object; a `@patch`ed method refreshes on reload (the patch writes onto the shared class). Restart only when a class you hold instances of was redefined. Check what's loaded by calling it, never with `inspect.getsource` (reads the file on disk).
+- Try the simple import or API call before changing the environment, monkeypatching, or adding setup.
+"""

{clikernel-0.2.13 → clikernel-0.2.15/clikernel.egg-info}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.2.13
+Version: 0.2.15
 Summary: Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol
 Author: clikernel contributors
-License: Apache-2.0
+License-Expression: Apache-2.0
 Project-URL: Repository, https://github.com/AnswerDotAI/clikernel
 Project-URL: Documentation, https://AnswerDotAI.github.io/clikernel/
 Classifier: Programming Language :: Python :: 3
@@ -18,6 +18,7 @@ Requires-Dist: mcpmini>=0.0.5
 Requires-Dist: rustygate>=0.1.22
 Requires-Dist: ipymini>=0.1.23
 Requires-Dist: httpx
+Requires-Dist: ipython
 Provides-Extra: dev
 Requires-Dist: fastship; extra == "dev"
 Dynamic: license-file
@@ -62,12 +63,13 @@ exec(code="6*7")
 
 Use `kernel="luau"` for bundled Luau, or `kernel="apl"` for APL when `basedpl` is installed in the gateway’s environment. `create` accepts any kernelspec the gateway finds. `exec` never creates or switches kernels. See [MCP](https://AnswerDotAI.github.io/clikernel/mcp.html) for named gateways, dialog bindings, and other tools.
 
+The router checks each `exec` cell against built-in rules for mistakes agents often make with this toolkit. Most rules add a note to the reply, and `--quiet` leaves the notes out. Two rules always block the cell: shell access through `subprocess`, [`os.system`](https://docs.python.org/3/library/os.html#os.system) or [`os.popen`](https://docs.python.org/3/library/os.html#os.popen), and changes to `sys.path`.
+
 ## Configuration
 
-Three optional files in `$XDG_CONFIG_HOME/clikernel/` configure the router, usually under `~/.config/clikernel/`, or under the directory `clikernel-mcp --cfgdir` names:
+Two 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

{clikernel-0.2.13 → clikernel-0.2.15}/clikernel.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ clikernel/_modidx.py
 clikernel/cli.py
 clikernel/core.py
 clikernel/mcp.py
+clikernel/rules.py
 clikernel/skill.py
 clikernel/stream.py
 clikernel.egg-info/PKG-INFO
@@ -16,4 +17,5 @@ clikernel.egg-info/dependency_links.txt
 clikernel.egg-info/entry_points.txt
 clikernel.egg-info/requires.txt
 clikernel.egg-info/top_level.txt
+tests/test_rules.py
 tests/test_stream.py

{clikernel-0.2.13 → clikernel-0.2.15}/clikernel.egg-info/requires.txt

@@ -5,6 +5,7 @@ mcpmini>=0.0.5
 rustygate>=0.1.22
 ipymini>=0.1.23
 httpx
+ipython
 
 [dev]
 fastship

{clikernel-0.2.13 → clikernel-0.2.15}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=68", "wheel"]
+requires = ["setuptools>=77"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -8,7 +8,7 @@ dynamic = ["version"]
 description = "Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol"
 readme = "README.md"
 requires-python = ">=3.11"
-license = { text = "Apache-2.0" }
+license = "Apache-2.0"
 authors = [{ name = "clikernel contributors" }]
 classifiers = [
   "Programming Language :: Python :: 3",
@@ -23,6 +23,7 @@ dependencies = [
   "rustygate>=0.1.22",
   "ipymini>=0.1.23",
   "httpx",
+  "ipython",
 ]
 
 [project.optional-dependencies]

clikernel-0.2.15/tests/test_rules.py

@@ -0,0 +1,80 @@
+from clikernel.rules import scan
+
+def fires(src, name): return any(r.name == name for r in scan(src))
+
+def test_rules():
+    "Each rule fires on its anti-pattern and stays quiet on the blessed route."
+    # read_text/open().read on a recognisable text file -> lnhashview
+    assert fires("Path('core.py').read_text()", "read_file")
+    assert fires("open('notes.txt').read()", "read_file")
+    assert not fires("lnhashview_file(p)", "read_file")
+    assert not fires("p.read_text()", "read_file")            # unrecognisable path: variables stay quiet
+    assert not fires("open(p).read()", "read_file")
+    assert not fires("open(p, 'r').read()", "read_file")      # a mode string is not a filename
+    assert not fires("Path('trace.jsonl').read_text()", "read_file")  # data files: a hashed line view can't help
+    assert not fires("open(d/'rows.csv').read()", "read_file")
+    assert fires("(d/'core.py').read_text()", "read_file")
+    assert fires("print(Path('a.py').read_text())", "read_file")                  # printed is displayed
+    assert not fires("yaml.safe_load(Path('wf.yaml').read_text())", "read_file")  # parser-bound: never enters context
+    assert not fires("src = Path('a.py').read_text()", "read_file")               # assigned: consumption unknown, stay quiet
+
+    # big replace_lines payload -> delete + %%exhash a
+    big = "x = 1\n" * 9
+    assert fires(f"file_replace_lines(p, new_content={big!r})", "big_replace")
+    assert fires(f"cell_replace_lines(cid, new_content={big!r})", "big_replace")
+    assert not fires("file_replace_lines(p, new_content='x = 1')", "big_replace")
+
+    # single-cell cell_str_replace -> %%exhash path cellid; batch replaces (id list / 'all') are sanctioned
+    assert fires("cell_str_replace('ab12', 'a', 'b', fname=p)", "cell_str_replace")
+    assert not fires("cell_str_replace(['ab12','cd34'], 'a', 'b')", "cell_str_replace")
+    assert not fires("cell_str_replace('all', 'a', 'b')", "cell_str_replace")
+    assert not fires("cell_str_replace(cids, 'a', 'b')", "cell_str_replace")   # variables unknowable: stay quiet
+
+    # non-raw triple-quote containing backslashes -> r-string
+    assert fires('s = """a\\nb"""', "rawstr")
+    assert not fires('s = r"""a\\nb"""', "rawstr")
+    assert not fires('s = """plain text"""', "rawstr")
+
+    # computing exhash addresses -> views only
+    assert fires("addr = lnhash(3, line)", "hashcalc")
+    assert fires("line_hash(s)", "hashcalc")
+
+    # post-processing tooling results -> bare repr / tool params
+    assert fires("'\\n'.join(lnhashview_file(p))", "postproc")
+    assert fires("rg('x', p).splitlines()[:5]", "postproc")
+    assert not fires("lnhashview_file(p)", "postproc")
+
+    # programmatic magic invocation -> % syntax
+    assert fires("get_ipython().run_line_magic('nbrun', 'abc')", "run_magic")
+    assert not fires("%nbrun abc", "run_magic")                  # a real magic is the blessed route
+
+    # tuple a/i/c payloads -> %%exhash magic (short quote-free payloads tolerated)
+    assert fires("file_exhash(p, (a, 'c', 'a longer replacement line here'))", "tuple_payload")
+    assert fires('file_exhash(p, (a, "a", "it\'s"))', "tuple_payload")             # quote in payload
+    assert fires("cell_exhash(p, cid, (a, 'i', 'x = \\\\n'))", "tuple_payload")    # backslash in payload
+    assert not fires("file_exhash(p, (a, 'c', 'metric'))", "tuple_payload")        # short one-worder: fine
+    assert not fires("file_exhash(p, (a, 's', 'longer than twenty chars ok'))", "tuple_payload")  # s is not a payload command
+    assert not fires("file_exhash(p, (a, 'c', body))", "tuple_payload")            # variables unknowable: stay quiet
+    assert not fires("file_exhash(p, (a, 'd'), (b, 'c', 'a longer replacement line here'))", "tuple_payload")  # multi-command batch: the one-command magic can't express it atomically
+    assert not fires("cell_exhash(p, cid, (a, 's', 'x', 'y'), (b, 'i', 'it\'s a long insertion here'))", "tuple_payload")
+    assert fires("cell_exhash(p, cid, (a, 'c', 'a longer replacement line here'))", "tuple_payload")  # single command: the magic is strictly better
+    assert fires("exhash(t, [(a, 'c', 'a longer replacement line here')])", "tuple_payload")           # one command in a list works the same
+
+    # literal \n in an s-replacement -> real newline; oversized s-replacement -> c command
+    assert fires(r"file_exhash(p, ('1|aa|', 's', 'x', r'a\nb'))", "s_newline")     # 2-char \n stays literal: a mistake
+    assert not fires(r"file_exhash(p, ('1|aa|', 's', 'x', 'a\nb'))", "s_newline")  # real newline: intended multiline
+    assert not fires(r"file_exhash(p, ('1|aa|', 's', r'x\n', 'y'))", "s_newline")  # pattern field: regex \n is meaningful
+    assert fires(f"file_exhash(p, ('1|aa|', 's', 'x', {'y'*121!r}))", "s_long")
+    assert not fires(f"file_exhash(p, ('1|aa|', 's', 'x', {'y'*120!r}))", "s_long")
+
+    # blockers: Python's own shell routes, but not `!` escapes, since the router can't tell Python from APL
+    assert fires("import subprocess", "shell_escape")
+    assert fires("os.system('ls')", "shell_escape")
+    assert fires("os.popen('ls')", "shell_escape")
+    assert not fires("!5", "shell_escape")                           # APL's factorial parses exactly like IPython's `!ls`
+    assert not fires("io.popen('ls')", "shell_escape")               # Luau's popen
+    assert fires("import subprocess.x", "shell_escape")          # submodule spellings
+    assert fires("from subprocess.x import y", "shell_escape")
+    assert fires("%nbrun ab12\nPath('f.py').read_text()", "read_file")  # rules still run on cells containing magics
+    assert fires("sys.path.insert(0, 'x')", "sys_path")
+    assert fires("sys.path.append('x')", "sys_path")

clikernel-0.2.13/clikernel/skill.py

@@ -1,33 +0,0 @@
-"""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.
-
-Prefer it over one-off Python scripts (`python -c`, shell heredocs). Prefer in-kernel tools over shell equivalents when they exist: file search and directory listing go through the `rgapi` pyskill (`rg()`/`fd()`/`ls()`), and GitHub and local git work through the `ghapi` pyskill, when those are installed. Shell commands remain the right tool for project test/build commands and non-Python tools.
-
-# Starting and stopping
-
-Call `create(kernel="py")` 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="py", 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; 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 `exec` runs there until the next selection.
-
-# Working in it
-
-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="apl")` then `exec(code="avg←+/÷≢ ⋄ avg 2 4 9")`. `basedpl` must be installed in the gateway's environment. It provides the `apl` kernelspec. Python startup and inspectors do not run in APL.
-
-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`.
-- 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.
-- Try the simple import or API call first, before changing the environment, monkeypatching, or adding setup.
-"""