clikernel 0.1.2__tar.gz → 0.1.4__tar.gz

clikernel-0.1.4/CHANGELOG.md

@@ -0,0 +1,42 @@
+<!-- do not remove -->
+
+## 0.1.4
+
+### New Features
+
+- Add cell inspectors, consolidate terminal handling, and harden MCP supervisor with signal guards and error recovery ([#9](https://github.com/AnswerDotAI/clikernel/issues/9))
+- Switch MCP server from in-process shell to supervised subprocess worker, add interrupt tool and idle-SIGINT handling ([#8](https://github.com/AnswerDotAI/clikernel/issues/8))
+
+
+## 0.1.3
+
+### New Features
+
+- Add `exit` MCP tool for hard process reset, and add pyskill ([#7](https://github.com/AnswerDotAI/clikernel/issues/7))
+- Add asyncio lock and async wrappers to MCP tools to allow top-level await ([#6](https://github.com/AnswerDotAI/clikernel/issues/6))
+- Add %nbopen/%nbrun line magics for running notebook cells by id prefix ([#5](https://github.com/AnswerDotAI/clikernel/issues/5))
+- Add MCP server exposing persistent IPython session; suppress duplicate tracebacks and defer init to main() ([#3](https://github.com/AnswerDotAI/clikernel/issues/3))
+
+### Bugs Squashed
+
+- Set `structured_output`=False on MCP tool decorators ([#4](https://github.com/AnswerDotAI/clikernel/issues/4))
+
+
+## 0.1.2
+
+### New Features
+
+- Add ONLCR terminal flag control ([#2](https://github.com/AnswerDotAI/clikernel/issues/2))
+
+
+## 0.1.1
+
+### New Features
+
+- Use a fixed per-session delimiter and emit `.` ack before each response ([#1](https://github.com/AnswerDotAI/clikernel/issues/1))
+
+
+## 0.1.0
+
+- Initial release
+

{clikernel-0.1.2/clikernel.egg-info → clikernel-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.1.2
+Version: 0.1.4
 Summary: A tiny stdin/stdout IPython worker
 Author: clikernel contributors
 License: Apache-2.0
@@ -10,7 +10,9 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: execnb
+Requires-Dist: execnb>=0.2.4
+Requires-Dist: fastcore
+Requires-Dist: mcp
 Provides-Extra: dev
 Requires-Dist: fastship; extra == "dev"
 Requires-Dist: build; extra == "dev"
@@ -73,8 +75,30 @@ After execution, `clikernel` prints the acknowledgement, the rendered output, an
 
 Outputs are rendered with `fastcore.nbio.render_text`. A single non-empty output is printed directly. Multiple outputs use raw XML-ish tags, for example `<stdout>`, `<display_data mime="text/markdown">`, and `<execute_result>`.
 
+## Notebook magics
+
+`clikernel` registers two line magics wrapping `execnb`'s `nbopen`/`nbrun`, for running cells from a notebook by cell id prefix:
+
+```text
+%nbopen foo.ipynb
+%nbrun ab12
+%nbrun ab12 --above
+%nbrun --all --exported
+%nbrun ab12 --fname other.ipynb
+```
+
+`%nbopen` sets the default notebook for later `%nbrun` calls (as does passing `--fname`). `%nbrun` runs the cell whose id starts with the given prefix; `--above`/`--below` also run the cells before/after it, `--all` runs every code cell, and `--exported` filters to cells with an nbdev `#| export`/`#| exports` directive. The notebook is re-read from disk on each call, and each executed cell's rendered output is printed under a `--- {cell id} ---` header.
+
 `clikernel` sets quiet defaults for `IPYTHONDIR`, `MPLCONFIGDIR`, and `MPLBACKEND=Agg` before creating the shell. Existing `IPYTHONDIR` and `MPLCONFIGDIR` values are left alone. Loading messages and any startup warnings are printed before the first delimiter. Set `CLIKERNEL_STATE_DIR` to choose the default parent directory.
 
+## Inspectors
+
+`clikernel` can check each cell before it runs, to warn about or forbid certain code. On startup it loads inspectors from `$XDG_CONFIG_HOME/clikernel/inspectors.py` (usually `~/.config/clikernel/inspectors.py`). If that file is absent, nothing changes.
+
+Each cell is transformed first (so IPython magics and `!` shell escapes parse), and its AST is passed to every inspector before the cell executes. An inspector returns a string to prepend a note to the cell's output, raises to block the cell (it does not run, and the exception is reported), or returns None to do nothing. Define a function `inspect(tree)` and/or a list `inspectors` of such functions in the file. A broken `inspectors.py` is reported on stderr and skipped, so it cannot stop the kernel starting.
+
+See [`examples/inspectors.py`](examples/inspectors.py) for one that blocks `subprocess`, `os.system`/`os.popen`, and `!` escapes, steering the agent to the permission-checked Bash tool instead.
+
 ## Why The Protocol Is Odd
 
 `clikernel` is built for a client that reads stdout as tokens. Local echo is disabled when stdin is a TTY. The client already knows the code it sent, so echoing it back only makes the LLM read slow, expensive tokens that add no information.
@@ -105,3 +129,4 @@ ship-gh
 ship-pypi
 ship-bump  # dev release always later than prod release
 ```
+

{clikernel-0.1.2 → clikernel-0.1.4}/README.md

@@ -53,8 +53,30 @@ After execution, `clikernel` prints the acknowledgement, the rendered output, an
 
 Outputs are rendered with `fastcore.nbio.render_text`. A single non-empty output is printed directly. Multiple outputs use raw XML-ish tags, for example `<stdout>`, `<display_data mime="text/markdown">`, and `<execute_result>`.
 
+## Notebook magics
+
+`clikernel` registers two line magics wrapping `execnb`'s `nbopen`/`nbrun`, for running cells from a notebook by cell id prefix:
+
+```text
+%nbopen foo.ipynb
+%nbrun ab12
+%nbrun ab12 --above
+%nbrun --all --exported
+%nbrun ab12 --fname other.ipynb
+```
+
+`%nbopen` sets the default notebook for later `%nbrun` calls (as does passing `--fname`). `%nbrun` runs the cell whose id starts with the given prefix; `--above`/`--below` also run the cells before/after it, `--all` runs every code cell, and `--exported` filters to cells with an nbdev `#| export`/`#| exports` directive. The notebook is re-read from disk on each call, and each executed cell's rendered output is printed under a `--- {cell id} ---` header.
+
 `clikernel` sets quiet defaults for `IPYTHONDIR`, `MPLCONFIGDIR`, and `MPLBACKEND=Agg` before creating the shell. Existing `IPYTHONDIR` and `MPLCONFIGDIR` values are left alone. Loading messages and any startup warnings are printed before the first delimiter. Set `CLIKERNEL_STATE_DIR` to choose the default parent directory.
 
+## Inspectors
+
+`clikernel` can check each cell before it runs, to warn about or forbid certain code. On startup it loads inspectors from `$XDG_CONFIG_HOME/clikernel/inspectors.py` (usually `~/.config/clikernel/inspectors.py`). If that file is absent, nothing changes.
+
+Each cell is transformed first (so IPython magics and `!` shell escapes parse), and its AST is passed to every inspector before the cell executes. An inspector returns a string to prepend a note to the cell's output, raises to block the cell (it does not run, and the exception is reported), or returns None to do nothing. Define a function `inspect(tree)` and/or a list `inspectors` of such functions in the file. A broken `inspectors.py` is reported on stderr and skipped, so it cannot stop the kernel starting.
+
+See [`examples/inspectors.py`](examples/inspectors.py) for one that blocks `subprocess`, `os.system`/`os.popen`, and `!` escapes, steering the agent to the permission-checked Bash tool instead.
+
 ## Why The Protocol Is Odd
 
 `clikernel` is built for a client that reads stdout as tokens. Local echo is disabled when stdin is a TTY. The client already knows the code it sent, so echoing it back only makes the LLM read slow, expensive tokens that add no information.
@@ -85,3 +107,4 @@ ship-gh
 ship-pypi
 ship-bump  # dev release always later than prod release
 ```
+

clikernel-0.1.4/clikernel/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.4"
+
+
+
+

clikernel-0.1.4/clikernel/cli.py

@@ -0,0 +1,168 @@
+import ast,inspect,os,runpy,secrets,shlex,signal,string,sys,tempfile,termios,traceback,tty
+from pathlib import Path
+from fastcore.xdg import xdg_config_home
+
+def _state_root():
+    if d := os.environ.get("CLIKERNEL_STATE_DIR"): return Path(d).expanduser()
+    return Path(tempfile.gettempdir()) / f"clikernel-{os.getuid()}"
+
+
+def _set_default_dirs():
+    state = _state_root()
+    for env, name in (("IPYTHONDIR", "ipython"), ("MPLCONFIGDIR", "matplotlib")):
+        path = Path(os.environ.get(env, state/name)).expanduser()
+        path.mkdir(parents=True, exist_ok=True)
+        os.environ.setdefault(env, str(path))
+    os.environ.setdefault("MPLBACKEND", "Agg")
+
+
+_ALPHANUM = string.ascii_letters + string.digits
+_MULTILINE = "--"
+
+
+def _new_delim(): return "--" + ''.join(secrets.choice(_ALPHANUM) for _ in range(5))
+
+
+def _read_block(stdin, delim):
+    lines = []
+    for line in stdin:
+        if line.rstrip("\n") == delim: return "".join(lines), None
+        lines.append(line)
+    return "", f"missing block terminator: {delim}"
+
+
+def _format_error(tag, text): return f"<{tag}>\n{text}</{tag}>"
+
+
+def _write_response(delim, body=None):
+    if body: print(body, end='' if body.endswith('\n') else '\n', flush=True)
+    print(delim, flush=True)
+
+
+def _load_inspectors():
+    "Cell inspectors from `$XDG_CONFIG_HOME/clikernel/inspectors.py`: each is called with the cell AST before execution, and may return a note (prepended to the output) or raise (blocking the cell). The file may define `inspect` and/or an `inspectors` list."
+    path = xdg_config_home()/"clikernel"/"inspectors.py"
+    if not path.exists(): return []
+    try: ns = runpy.run_path(str(path))
+    except Exception:
+        print(f"clikernel: failed to load {path}:\n{traceback.format_exc()}", file=sys.stderr, flush=True)
+        return []
+    ins = list(ns.get("inspectors", []))
+    if callable(ns.get("inspect")): ins.append(ns["inspect"])
+    return ins
+
+
+def _inspect(shell, inspectors, code):
+    "Run each inspector on the cell's transformed AST; return concatenated notes. An inspector may raise to block the cell."
+    if not inspectors: return ""
+    try: tree = ast.parse(shell.transform_cell(code))
+    except SyntaxError: return ""  # let the cell's own execution report the error
+    return "".join(note for f in inspectors if (note := f(tree)))
+
+
+def _execute(shell, inspectors, code):
+    from fastcore.nbio import render_text
+    try: note = _inspect(shell, inspectors, code)
+    except Exception as e: return "blocked", _format_error("blocked", f"{type(e).__name__}: {e}")
+    outputs = shell.run(code)
+    return ("error" if shell.exc else "ok"), note + render_text(outputs)
+
+
+def _request_exit(shell): shell._clikernel_exit = True
+
+
+def _magic_wrap(fn):
+    "Make a line magic from `fn`: `--name` flags for bool params, `--name value` otherwise, else positional"
+    params = inspect.signature(fn).parameters
+    def magic(line):
+        args,kw = [],{}
+        toks = iter(shlex.split(line))
+        for t in toks:
+            if t.startswith('--'):
+                k = t[2:]
+                kw[k] = True if params[k].annotation in (bool,'bool') else next(toks)
+            else: args.append(t)
+        return fn(*args, **kw)
+    return magic
+
+
+def _make_shell():
+    from execnb.shell import CaptureShell
+    shell = CaptureShell(mpl_format=None, history=False)
+    for name in ('nbopen','nbrun'): shell.register_magic_function(_magic_wrap(getattr(shell, name)), 'line', name)
+    shell._clikernel_exit = False
+    shell.ask_exit = lambda: _request_exit(shell)
+    # execnb already captures the exception as a structured error output; suppress
+    # IPython's own traceback print so it isn't duplicated (in colour) via stdout.
+    shell.showtraceback = lambda *a, **k: None
+    shell.showsyntaxerror = lambda *a, **k: None
+    return shell
+
+
+def _should_exit(shell): return getattr(shell, "_clikernel_exit", False)
+
+
+def _next_line(stdin):
+    "Read one line; when not a TTY, SIGINT while idle means 'interrupt execution', not 'kill the worker', so ignore it"
+    while True:
+        try: return stdin.readline()
+        except KeyboardInterrupt:
+            if stdin.isatty(): raise
+
+
+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
+    fd = stream.fileno()
+    attrs = termios.tcgetattr(fd)
+    new_attrs = attrs[:]
+    new_attrs[idx] &= ~mask
+    if cc:
+        new_attrs[6] = attrs[6][:]
+        for k, v in cc.items(): new_attrs[6][k] = v
+    termios.tcsetattr(fd, termios.TCSADRAIN, new_attrs)
+    return fd, attrs
+
+
+def _restore_termios(state):
+    if state: termios.tcsetattr(state[0], termios.TCSADRAIN, state[1])
+
+
+def main():
+    # Establish our own SIGINT disposition rather than inherit the parent's: a supervisor that ignores
+    # SIGINT would otherwise pass SIG_IGN down (inherited across exec), leaving this worker uninterruptible
+    signal.signal(signal.SIGINT, signal.default_int_handler)
+    print("please wait, loading...", flush=True)
+    _set_default_dirs()
+    shell = _make_shell()
+    inspectors = _load_inspectors()
+    # 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)
+    output_state = _tty_clear(sys.__stdout__, tty.OFLAG, termios.ONLCR)
+    echo_state = _tty_clear(sys.stdin, tty.LFLAG, termios.ECHO | termios.ICANON, {termios.VMIN: 1, termios.VTIME: 0})
+    delim = _new_delim()
+    print("loading complete. first delimiter:", flush=True)
+    _write_response(delim)
+    try:
+        while True:
+            line = _next_line(sys.stdin)
+            if not line: break
+            line = line.rstrip("\n")
+            if line == _MULTILINE:
+                code, err = _read_block(sys.stdin, delim)
+                if err:
+                    _write_response(delim, _format_error("protocol-error", err))
+                    continue
+            else: code = line
+            print(".", flush=True)
+            try: _, outputs = _execute(shell, inspectors, code)
+            except BaseException: outputs = _format_error("internal-error", traceback.format_exc())
+            _write_response(delim, outputs)
+            if _should_exit(shell): break
+    finally:
+        _restore_termios(echo_state)
+        _restore_termios(output_state)
+
+
+if __name__ == "__main__": main()

clikernel-0.1.4/clikernel/mcp.py

@@ -0,0 +1,129 @@
+"MCP server supervising a persistent `clikernel` CLI worker subprocess."
+import asyncio,atexit,os,signal,sys,traceback
+
+_MARKER = "loading complete. first delimiter:"
+_DIED = "NOTE: the kernel process had died; a fresh one was started, and all previous session state (imports, variables, monkeypatches) is gone.\n"
+_MULTILINE = "--"
+
+
+class _Worker:
+    def __init__(self):
+        self.proc,self.delim,self.started,self.busy,self.desynced = None,None,False,False,False
+        self.lock = asyncio.Lock()
+
+    def alive(self): return self.proc is not None and self.proc.returncode is None
+
+    async def start(self):
+        PIPE = asyncio.subprocess.PIPE
+        self.proc = await asyncio.create_subprocess_exec(sys.executable, "-m", "clikernel.cli", limit=2**24, stdin=PIPE, stdout=PIPE)
+        while True:
+            line = (await self.proc.stdout.readline()).decode()
+            if not line: raise RuntimeError("clikernel worker failed to start")
+            if line.rstrip("\n") == _MARKER: break
+        self.delim = (await self.proc.stdout.readline()).decode().rstrip("\n")
+        self.started,self.busy,self.desynced = True,False,False
+
+    async def kill(self):
+        if self.alive():
+            self.proc.kill()
+            await self.proc.wait()
+
+    async def run(self, code):
+        "Send `code`; return `(acked, body)`. `body` None means the worker died; retry is only safe if it never acked."
+        msg = f"{_MULTILINE}\n{code}\n{self.delim}\n" if "\n" in code or code == _MULTILINE else code + "\n"
+        try:
+            self.proc.stdin.write(msg.encode())
+            await self.proc.stdin.drain()
+        except Exception: return False, None  # write failed before the worker accepted anything: safe to retry
+        self.busy = True
+        try:
+            if not (await self.proc.stdout.readline()): return False, None  # "." ack
+            lines = []
+            while True:
+                line = (await self.proc.stdout.readline()).decode()
+                if not line: return True, None
+                if line.rstrip("\n") == self.delim: return True, "".join(lines).removesuffix("\n")
+                lines.append(line)
+        except asyncio.CancelledError:
+            self.desynced = True
+            raise
+        except Exception:
+            self.desynced = True  # unexpected read failure (e.g. a line past the buffer limit): rebuild on the next call
+            return True, None
+        finally: self.busy = False
+
+
+def _errbox(): return "<internal-error>\n" + traceback.format_exc() + "</internal-error>"
+
+
+def _kill_worker(w):
+    "Reap the worker child so it can never outlive the supervisor (signal-handler safe: no await)"
+    p = w.proc
+    if p is not None and p.returncode is None:
+        try: os.kill(p.pid, signal.SIGKILL)
+        except OSError: pass
+
+
+def _install_signal_guards(w):
+    "A stray group SIGINT must not fell the supervisor; SIGTERM/SIGHUP shut down cleanly, always taking the worker with us (never orphan it)"
+    signal.signal(signal.SIGINT, signal.SIG_IGN)
+    def _shutdown(signum, frame):
+        _kill_worker(w)
+        os._exit(0)
+    for s in (signal.SIGTERM, signal.SIGHUP):
+        try: signal.signal(s, _shutdown)
+        except (ValueError, OSError): pass  # platform lacks the signal, or not on the main thread
+    atexit.register(_kill_worker, w)
+
+
+def main():
+    from mcp.server.fastmcp import FastMCP
+    mcp = FastMCP("clikernel")
+    w = _Worker()
+    _install_signal_guards(w)
+
+    @mcp.tool(structured_output=False)
+    async def execute(code:str  # IPython-compatible code to run in the persistent session
+                     )->str:   # Rendered outputs (stdout, display data, last-expression result, errors)
+        "Run `code` in the persistent IPython session, keeping state across calls (imports, variables, monkeypatches, cached objects). If the kernel process has died since the last call, a fresh one is started automatically and the response notes that session state was lost."
+        try:
+            async with w.lock:
+                note = ""
+                if w.desynced: await w.kill()
+                if not w.alive():
+                    if w.started: note = _DIED
+                    await w.start()
+                acked, body = await w.run(code)
+                if body is None and not acked:  # died before accepting the request: safe to retry on a fresh worker
+                    note = _DIED
+                    await w.start()
+                    acked, body = await w.run(code)
+                if body is None:
+                    return note + "<internal-error>\nkernel process died while executing this request; a fresh kernel will be started on the next call, with all session state lost\n</internal-error>"
+                return note + body
+        except Exception:
+            w.desynced = True
+            return _errbox()
+
+    @mcp.tool(structured_output=False)
+    async def restart()->str:
+        "Kill the kernel process and start a fresh one: new pid, `sys.modules` genuinely reset, all session state (imports, variables, monkeypatches, cached objects) discarded. Use for a clean slate, after rebuilding a native extension, or after reloading a module that other already-imported modules had patched (symptoms: a stale-class bug where `isinstance`/`is` checks mysteriously fail, or a class is missing a method you know it has). Also works when `execute` is stuck: the stuck call returns an error and the kernel comes back fresh. After restarting, redo any imports/setup the task still needs."
+        try:
+            await w.kill()
+            async with w.lock: await w.start()
+            return "restarted"
+        except Exception: return _errbox()
+
+    @mcp.tool(structured_output=False)
+    async def interrupt()->str:
+        "Interrupt the code the kernel is currently running (SIGINT, i.e. KeyboardInterrupt): the in-flight `execute` call returns with a KeyboardInterrupt traceback, and session state survives. Prefer this over `restart` when a call is merely taking too long. Only meaningful while an `execute` call is running."
+        try:
+            if not (w.alive() and w.busy): return "nothing is running"
+            w.proc.send_signal(signal.SIGINT)
+            return "interrupt sent; the running `execute` call will return with a KeyboardInterrupt"
+        except Exception: return _errbox()
+
+    mcp.run()
+
+
+if __name__ == "__main__": main()

clikernel-0.1.4/clikernel/skill.py

@@ -0,0 +1,101 @@
+"""Use the persistent `clikernel` MCP session as the default workspace for any task advanced through live Python execution -- stateful inspection, file-editing workflows, debugging, experiments, API probes, data transforms, or notebook-style work. Read this before writing, running, or debugging Python code in a session with `clikernel` connected.
+
+# Core idea
+
+`clikernel` exposes one long-lived IPython process (wrapping `execnb.shell.CaptureShell`) that runs Python/IPython code and keeps state across the whole conversation: imports, live objects, monkeypatches, cached results, API clients, small experiments. Treat it as a notebook-style workbench, not a one-shot script runner.
+
+Prefer it over one-off Python scripts (`python -c`, shell heredocs) whenever you need to inspect runtime behavior, test an idea, call a Python API, examine package state, run a live probe, or iterate on an implementation detail. Shell commands are still the right tool for file search, git, project test/build commands, and non-Python tools.
+
+There are two ways to drive it, depending on what the host supports:
+
+- **MCP server** (`clikernel-mcp`): no delimiter protocol, stdin plumbing, or readiness polling to manage -- call one tool, get back the rendered outputs.
+- **CLI** (`clikernel`): a plain stdin/stdout process using a delimiter protocol, for hosts that drive background terminal sessions instead of MCP tools.
+
+# MCP tools
+
+`execute`, `restart`, and `interrupt` are self-documenting -- read each tool's own MCP description rather than looking for docs elsewhere. `restart` gives a genuinely fresh interpreter process (new pid, `sys.modules` reset); `interrupt` stops a too-long-running `execute` while keeping session state.
+
+# CLI protocol
+
+When driven as a plain process, `clikernel` prints loading status followed by a random session delimiter -- always `--` plus 5 alphanumeric characters:
+
+    please wait, loading...
+    loading complete. first delimiter:
+    --aB3x9
+
+Any startup warnings print before the first delimiter. Treat that delimiter as the readiness signal, completion signal, and multiline terminator; it stays the same until the process exits.
+
+Send a single line to execute a single-line request. `clikernel` first prints an acknowledgement line (`.`) -- that means request *accepted*, not execution complete -- then the response body, then the session delimiter:
+
+    1+1
+    .
+    2
+    --aB3x9
+
+Use a bare `--` line to start multiline input, ending the block with the session delimiter exactly:
+
+    --
+    def f(x):
+        return x + 1
+
+    f(2)
+    --aB3x9
+
+Do not look for an IPython prompt, do not use `%cpaste`, and do not invent your own terminator. A blank line is a real (empty) request, so it makes a good idle-poll: an idle kernel answers with `.` and the delimiter; if that doesn't come back quickly, the previous request is still running or the process is wedged.
+
+Python exceptions render as normal notebook error output. Protocol/worker failures render with readable XML-ish error tags, then the session delimiter.
+
+To end the session, send `exit`. In CLI mode there is no `restart` tool -- starting a fresh process *is* the restart, and gives a genuinely fresh interpreter (the equivalent of the MCP `restart` tool).
+
+# Notebook magics
+
+Two line magics run cells from a `.ipynb` file by cell id prefix:
+
+    %nbopen foo.ipynb
+    %nbrun ab12
+    %nbrun ab12 --above
+    %nbrun --all --exported
+    %nbrun ab12 --fname other.ipynb
+
+`%nbopen` sets the default notebook for later `%nbrun` calls (passing `--fname` does too). `%nbrun` runs the cell whose id starts with the given prefix; `--above`/`--below` also run the cells before/after it, `--all` runs every code cell, and `--exported` filters to cells carrying an nbdev `#| export`/`#| exports` directive. The notebook is re-read from disk on each call, so file edits are picked up; each executed cell's output is printed under a `--- {cell id} ---` header. Cell execution shares the persistent session state, and `restart` clears the `%nbopen` default.
+
+Prefer these magics over copying cell source into `execute` by hand when working through a notebook -- e.g. after editing a cell, `%nbrun <id>` re-runs it in place, and `%nbrun <id> --above` rebuilds the state it depends on.
+
+# Output shape
+
+Outputs are rendered with `fastcore.nbio.render_text`. A single non-empty stream/display/result/error comes back as just its preferred text form, e.g. `42`. Multiple non-empty outputs use readable XML-ish tags with raw, unescaped body text, e.g.:
+
+    <stdout>
+    hello
+    </stdout>
+    <execute_result>
+    42
+    </execute_result>
+
+`display_data`/`execute_result` prefer a non-image, markdown-over-HTML representation; images are ignored. Exceptions come back as a single clean `<error>` traceback -- no color codes, not duplicated.
+
+# Interaction rules
+
+- Try the simple import or API call first, before mutating environment, monkeypatching, or adding setup. Only change session state after the ordinary path fails and the reason is understood.
+- For file-editing workflows, view the target slice first and make the smallest verified edit -- avoid whole-file rewrites when a line/range/string operation is enough.
+- Default to raw triple-quoted strings (`r'''...'''`) for generated markdown, code, regexes, commands, or other source-like text, since backslashes usually need to survive intact. Use normal triple-quoted strings only when Python's own escape processing is what you want. For risky multiline content, verify with `repr(...)` or a focused readback before writing broadly.
+- Lean on reprs: many objects returned by libraries in this ecosystem (pyskills results especially) have reprs designed for direct reading. End a cell with the bare expression instead of writing a loop to reformat fields by hand -- only drop to attribute access when the repr genuinely omits what you need.
+
+# Critical issues
+
+- Like Jupyter, only the *last* expression in a cell is printed/returned. `print(...)` any earlier value you need to see.
+- Don't re-run an `import` you've already run this session -- it's persistent, so it's already done. Use `importlib.reload` if you've changed a module and need the change picked up. If a previously-imported name raises `NameError`, the session restarted -- redo whatever imports/setup the task needs.
+- `importlib.reload`ing a module is not always enough to pick up a change: other already-imported modules that did `from x import *`, or that monkeypatched one of its classes (e.g. via fastcore's `@patch`), hold stale references that a targeted reload won't fix. If you hit a stale-class symptom (a class missing a method you know it has, `isinstance` mysteriously failing), you need a fresh interpreter process: the MCP `restart` tool, or in CLI mode, exit and start a new process.
+- Everything a cell outputs lands in the conversation and stays there. Be surgical: inspect only what's needed, and don't dump large values -- `print(len(v))` first, then decide whether to print in full or filter down.
+- The kernel is scoped to one client session and shared by any subagents within it. If the server restarts or exits, in-memory state is gone -- redo imports and setup.
+
+# Pyskills
+
+This kernel environment commonly has `pyskills` installed -- a plugin system for discovering additional Python capabilities registered by installed packages. When present, checking it is the first thing to do at the start of a session, and using a relevant pyskill is strongly preferred over ad hoc code. See `pyskills.skill`'s own docs for the full discovery/usage workflow:
+
+    from pyskills import list_pyskills, doc
+    import pyskills.skill
+    print(doc(pyskills.skill))
+"""
+
+__all__ = []

{clikernel-0.1.2 → clikernel-0.1.4/clikernel.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.1.2
+Version: 0.1.4
 Summary: A tiny stdin/stdout IPython worker
 Author: clikernel contributors
 License: Apache-2.0
@@ -10,7 +10,9 @@ Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: execnb
+Requires-Dist: execnb>=0.2.4
+Requires-Dist: fastcore
+Requires-Dist: mcp
 Provides-Extra: dev
 Requires-Dist: fastship; extra == "dev"
 Requires-Dist: build; extra == "dev"
@@ -73,8 +75,30 @@ After execution, `clikernel` prints the acknowledgement, the rendered output, an
 
 Outputs are rendered with `fastcore.nbio.render_text`. A single non-empty output is printed directly. Multiple outputs use raw XML-ish tags, for example `<stdout>`, `<display_data mime="text/markdown">`, and `<execute_result>`.
 
+## Notebook magics
+
+`clikernel` registers two line magics wrapping `execnb`'s `nbopen`/`nbrun`, for running cells from a notebook by cell id prefix:
+
+```text
+%nbopen foo.ipynb
+%nbrun ab12
+%nbrun ab12 --above
+%nbrun --all --exported
+%nbrun ab12 --fname other.ipynb
+```
+
+`%nbopen` sets the default notebook for later `%nbrun` calls (as does passing `--fname`). `%nbrun` runs the cell whose id starts with the given prefix; `--above`/`--below` also run the cells before/after it, `--all` runs every code cell, and `--exported` filters to cells with an nbdev `#| export`/`#| exports` directive. The notebook is re-read from disk on each call, and each executed cell's rendered output is printed under a `--- {cell id} ---` header.
+
 `clikernel` sets quiet defaults for `IPYTHONDIR`, `MPLCONFIGDIR`, and `MPLBACKEND=Agg` before creating the shell. Existing `IPYTHONDIR` and `MPLCONFIGDIR` values are left alone. Loading messages and any startup warnings are printed before the first delimiter. Set `CLIKERNEL_STATE_DIR` to choose the default parent directory.
 
+## Inspectors
+
+`clikernel` can check each cell before it runs, to warn about or forbid certain code. On startup it loads inspectors from `$XDG_CONFIG_HOME/clikernel/inspectors.py` (usually `~/.config/clikernel/inspectors.py`). If that file is absent, nothing changes.
+
+Each cell is transformed first (so IPython magics and `!` shell escapes parse), and its AST is passed to every inspector before the cell executes. An inspector returns a string to prepend a note to the cell's output, raises to block the cell (it does not run, and the exception is reported), or returns None to do nothing. Define a function `inspect(tree)` and/or a list `inspectors` of such functions in the file. A broken `inspectors.py` is reported on stderr and skipped, so it cannot stop the kernel starting.
+
+See [`examples/inspectors.py`](examples/inspectors.py) for one that blocks `subprocess`, `os.system`/`os.popen`, and `!` escapes, steering the agent to the permission-checked Bash tool instead.
+
 ## Why The Protocol Is Odd
 
 `clikernel` is built for a client that reads stdout as tokens. Local echo is disabled when stdin is a TTY. The client already knows the code it sent, so echoing it back only makes the LLM read slow, expensive tokens that add no information.
@@ -105,3 +129,4 @@ ship-gh
 ship-pypi
 ship-bump  # dev release always later than prod release
 ```
+

{clikernel-0.1.2 → clikernel-0.1.4}/clikernel.egg-info/SOURCES.txt

@@ -5,10 +5,13 @@ README.md
 pyproject.toml
 clikernel/__init__.py
 clikernel/cli.py
+clikernel/mcp.py
+clikernel/skill.py
 clikernel.egg-info/PKG-INFO
 clikernel.egg-info/SOURCES.txt
 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_cli.py
+tests/test_cli.py
+tests/test_mcp.py

clikernel-0.1.4/clikernel.egg-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+clikernel = clikernel.cli:main
+clikernel-mcp = clikernel.mcp:main
+
+[pyskills]
+clikernel = clikernel.skill

{clikernel-0.1.2 → clikernel-0.1.4}/clikernel.egg-info/requires.txt

@@ -1,4 +1,6 @@
-execnb
+execnb>=0.2.4
+fastcore
+mcp
 
 [dev]
 fastship

{clikernel-0.1.2 → clikernel-0.1.4}/pyproject.toml

@@ -16,7 +16,9 @@ classifiers = [
 ]
 
 dependencies = [
-  "execnb",
+  "execnb>=0.2.4",
+  "fastcore",
+  "mcp",
 ]
 
 [project.optional-dependencies]
@@ -27,11 +29,15 @@ dev = [
   "pytest",
 ]
 
+[project.entry-points.pyskills]
+clikernel = "clikernel.skill"
+
 [project.urls]
 Homepage = "https://github.com/AnswerDotAI/clikernel"
 
 [project.scripts]
 clikernel = "clikernel.cli:main"
+clikernel-mcp = "clikernel.mcp:main"
 
 [tool.setuptools.dynamic]
 version = { attr = "clikernel.__version__" }