clikernel 0.2.6__tar.gz → 0.2.7__tar.gz

{clikernel-0.2.6 → clikernel-0.2.7}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 <!-- do not remove -->
 
+## 0.2.7
+
+### New Features
+
+- Add stdin support via MCP elicitation, kernel env propagation, and Client async context manager for scoped kernel lifecycle ([#45](https://github.com/AnswerDotAI/clikernel/issues/45))
+- Simplify MCP tool docstrings by using literal docstrings with conditional suffixes for non-quiet mode instead of f-string assignment ([#44](https://github.com/AnswerDotAI/clikernel/issues/44))
+- Add --quiet option to suppress kernel startup output from connect, restart, and auto-connect execute replies ([#43](https://github.com/AnswerDotAI/clikernel/issues/43))
+
+
 ## 0.2.6
 
 ### New Features

{clikernel-0.2.6/clikernel.egg-info → clikernel-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.2.6
+Version: 0.2.7
 Summary: Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol
 Author: clikernel contributors
 License: Apache-2.0
@@ -12,9 +12,9 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastcore>=2.2.2
-Requires-Dist: jupyasyncclient>=0.2.8
+Requires-Dist: jupyasyncclient>=0.2.9
 Requires-Dist: fastspec>=0.2.2
-Requires-Dist: mcpmini>=0.0.1
+Requires-Dist: mcpmini>=0.0.3
 Requires-Dist: aidialog>=0.0.7
 Requires-Dist: pillow
 Provides-Extra: dev
@@ -51,7 +51,11 @@ Register the stdio server with your MCP host, e.g. for Claude Code:
 claude mcp add clikernel -- clikernel-mcp
 ```
 
-The tools mirror the gateway’s kernel API plus one composite: `connect` (create a fresh kernel — running `startup.py` and installing inspectors — or attach to an existing one by id), `execute` (run code, get concise text), `list_kernels`, `stop_kernel`, `restart`, and `interrupt`. An `execute` with no kernel connected auto-creates one, scoped to the conversation: it stops at conversation end, or when `connect` moves elsewhere. Kernels made or attached with an explicit `connect` are stopped only by `stop_kernel` — a later conversation reattaches by id and continues where the last one stopped. `$CLIKERNEL_HOST` overrides the default gateway (`http://127.0.0.1:8787`).
+The tools mirror the gateway’s kernel API: `connect`, `execute`, `list_kernels`, `stop_kernel`, `restart`, and `interrupt`. When executed code requests input, the MCP client shows an elicitation dialog while the same `execute` call remains active. Repeated prompts repeat that callback. Password-marked prompts are refused.
+
+An `execute` with no kernel connected auto-creates one, scoped to the conversation: it stops at conversation end, or when `connect` moves elsewhere. Kernels made or attached with an explicit `connect` are stopped only by `stop_kernel` — a later conversation reattaches by id and continues where the last one stopped. `$CLIKERNEL_HOST` overrides the default gateway (`http://127.0.0.1:8787`).
+
+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, and an auto-connecting `execute` returns just the result.
 
 ## Configuration
 

{clikernel-0.2.6 → clikernel-0.2.7}/README.md

@@ -27,7 +27,11 @@ Register the stdio server with your MCP host, e.g. for Claude Code:
 claude mcp add clikernel -- clikernel-mcp
 ```
 
-The tools mirror the gateway’s kernel API plus one composite: `connect` (create a fresh kernel — running `startup.py` and installing inspectors — or attach to an existing one by id), `execute` (run code, get concise text), `list_kernels`, `stop_kernel`, `restart`, and `interrupt`. An `execute` with no kernel connected auto-creates one, scoped to the conversation: it stops at conversation end, or when `connect` moves elsewhere. Kernels made or attached with an explicit `connect` are stopped only by `stop_kernel` — a later conversation reattaches by id and continues where the last one stopped. `$CLIKERNEL_HOST` overrides the default gateway (`http://127.0.0.1:8787`).
+The tools mirror the gateway’s kernel API: `connect`, `execute`, `list_kernels`, `stop_kernel`, `restart`, and `interrupt`. When executed code requests input, the MCP client shows an elicitation dialog while the same `execute` call remains active. Repeated prompts repeat that callback. Password-marked prompts are refused.
+
+An `execute` with no kernel connected auto-creates one, scoped to the conversation: it stops at conversation end, or when `connect` moves elsewhere. Kernels made or attached with an explicit `connect` are stopped only by `stop_kernel` — a later conversation reattaches by id and continues where the last one stopped. `$CLIKERNEL_HOST` overrides the default gateway (`http://127.0.0.1:8787`).
+
+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, and an auto-connecting `execute` returns just the result.
 
 ## Configuration
 

{clikernel-0.2.6 → clikernel-0.2.7}/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.6"
+__version__ = "0.2.7"

{clikernel-0.2.6 → clikernel-0.2.7}/clikernel/_modidx.py

@@ -15,8 +15,11 @@ d = { 'settings': { 'branch': 'main',
                                'clikernel.cli.main': ('cli.html#main', 'clikernel/cli.py'),
                                'clikernel.cli.serve_stream': ('cli.html#serve_stream', 'clikernel/cli.py')},
             'clikernel.core': { 'clikernel.core.Client': ('core.html#client', 'clikernel/core.py'),
+                                'clikernel.core.Client.__aenter__': ('core.html#client.__aenter__', 'clikernel/core.py'),
+                                'clikernel.core.Client.__aexit__': ('core.html#client.__aexit__', 'clikernel/core.py'),
                                 'clikernel.core.Client.__init__': ('core.html#client.__init__', 'clikernel/core.py'),
                                 'clikernel.core.Client._setup': ('core.html#client._setup', 'clikernel/core.py'),
+                                'clikernel.core.Client._startkw': ('core.html#client._startkw', 'clikernel/core.py'),
                                 'clikernel.core.Client._use': ('core.html#client._use', 'clikernel/core.py'),
                                 'clikernel.core.Client.aclose': ('core.html#client.aclose', 'clikernel/core.py'),
                                 'clikernel.core.Client.connect': ('core.html#client.connect', 'clikernel/core.py'),

{clikernel-0.2.6 → clikernel-0.2.7}/clikernel/core.py

@@ -97,7 +97,7 @@ STATE_LOST_SETUP = 'NOTE: the kernel restarted with a fresh interpreter: startup
 
 class Client:
     "One conversation's connection: a gateway manager, and the current kernel"
-    def __init__(self, cfgdir=None): self.cfgdir,self.mgr,self.kc,self.kid,self.auto,self.made = cfgdir,None,None,None,False,False
+    def __init__(self, cfgdir=None, quiet=False): self.cfgdir,self.quiet,self.mgr,self.kc,self.kid,self.auto,self.made = cfgdir,quiet,None,None,None,False,False
 
     async def _use(self, mgr, kid):
         "Point at `kid` on `mgr`, dropping any previous ws (never the kernel)"
@@ -106,6 +106,12 @@ class Client:
         self.kc.start_channels()
         await self.kc.wait_for_ready(timeout=30)
 
+    def _startkw(self):
+        "Creation kwargs for a local kernel: the conversation's cwd and env, with quiet advertised as CLIKERNEL_QUIET"
+        env = dict(os.environ)
+        if self.quiet: env['CLIKERNEL_QUIET'] = '1'
+        return dict(cwd=os.getcwd(), env=env)
+
 # %% ../nbs/00_core.ipynb #94497e4a
 @patch
 async def _setup(self:Client):
@@ -139,19 +145,19 @@ async def connect(self:Client, host='', kernel='', auto=False):
         await self._use(mgr, kid)
         self.made = False
         return f'connected to existing kernel {kid} on {url}' + note
-    kw = dict(cwd=os.getcwd(), env=dict(os.environ)) if not host else {}   # the default gateway is local by definition: kernels start where, and as, the conversation lives (cwd and environment - so kernel-side tools that key state to the conversation, like llmdojo's doc-state, resolve it correctly)
+    kw = self._startkw() if not host else {}   # the default gateway is local by definition: kernels start where, and as, the conversation lives (cwd and environment - so kernel-side tools that key state to the conversation, like llmdojo's doc-state, resolve it correctly)
     kid = await mgr.start_kernel(**kw)
     await self._use(mgr, kid)
     self.made = True
     out = await self._setup()
     self.auto = auto
-    return f'created kernel {kid} on {url}' + (f'\n{out}' if out.strip() else '') + note
+    return f'created kernel {kid} on {url}' + (f'\n{out}' if out.strip() and not self.quiet else '') + note
 
 @patch
-async def execute_outs(self:Client, code):
+async def execute_outs(self:Client, code, **kw):
     "Run `code` in the current kernel; nbformat-style output dicts (or a protocol note string)"
     if not self.kc: return 'no kernel: call `connect` first'
-    try: return await self.kc.run(code)
+    try: return await self.kc.exec_outs(code, **kw)
     except DeadKernelError: return 'NOTE: the kernel process died. `connect` to create or attach to another.'
 
 @patch
@@ -198,15 +204,15 @@ async def restart(self:Client):
             return f'restart failed ({e.message}); the kernel is still listed: retry, `stop` it, or `connect` for a fresh one'
         old,kw = self.kid,{}
         await self.kc.aclose()
-        if self.mgr.base_url == resolve('', self.cfgdir)[0]: kw = dict(cwd=os.getcwd(), env=dict(os.environ))
+        if self.mgr.base_url == resolve('', self.cfgdir)[0]: kw = self._startkw()
         await self._use(self.mgr, await self.mgr.start_kernel(**kw))
         self.made = True
         out = await self._setup()
-        return f'kernel {old} was gone; created fresh kernel {self.kid}.\n' + STATE_LOST_SETUP + (f'\n{out}' if out.strip() else '')
+        return f'kernel {old} was gone; created fresh kernel {self.kid}.\n' + STATE_LOST_SETUP + (f'\n{out}' if out.strip() and not self.quiet else '')
     await self.kc.wait_for_ready(timeout=30)
     if not self.made: return STATE_LOST
     out = await self._setup()
-    return STATE_LOST_SETUP + (f'\n{out}' if out.strip() else '')
+    return STATE_LOST_SETUP + (f'\n{out}' if out.strip() and not self.quiet else '')
 
 @patch
 async def interrupt(self:Client):
@@ -220,3 +226,13 @@ async def aclose(self:Client):
     "Drop connections; kernels are left exactly as they are"
     if self.kc: await self.kc.aclose()
     self.mgr,self.kc,self.kid = None,None,None
+
+# %% ../nbs/00_core.ipynb #6559aa40
+@patch
+async def __aenter__(self:Client): return self
+
+@patch
+async def __aexit__(self:Client, *exc):
+    "Stop the current kernel if this client created it (an attached kernel is left as found), then drop connections"
+    if self.made and self.kid: await self.stop()
+    await self.aclose()

{clikernel-0.2.6 → clikernel-0.2.7}/clikernel/mcp.py

@@ -1,6 +1,6 @@
 """The MCP frontend: `Client` as tools on stdio
 
-The frontend Claude Code launches per conversation: `mk_server` closes the tools over a `Client`, and `main` (the `clikernel-mcp` console script) serves it on stdio via mcpmini. There is no instructions machinery and nothing eager — usage is taught by skill text, the server answers `initialize` instantly, and nothing happens until the first tool call. An `execute` with no kernel connected auto-connects first, so `connect` is only needed to attach, to reach another gateway, or to make a kernel that outlives the conversation. Tool descriptions carry v1's hard-won wording.
+The frontend Claude Code launches per conversation. `mk_server` closes the tools over a `Client`, and `main` serves them on stdio through mcpmini. The server answers `initialize` without starting a kernel. The first `execute` auto-connects when needed. `connect` remains available for attaching, selecting another gateway, or creating a kernel that outlives the conversation. A kernel `input_request` becomes an MCP elicitation inside the same `execute` call. jupywire sends the elicitation response back to the requesting kernel.
 
 Docs: https://AnswerDotAI.github.io/clikernel/mcp.html.md"""
 
@@ -12,6 +12,7 @@ __all__ = ['part2block', 'mk_server', 'main']
 # %% ../nbs/01_mcp.ipynb #28c42902
 import asyncio
 from fastcore.utils import *
+from fastcore.script import call_parse, store_true
 from mcpmini.core import MCPServer, serve_stdio
 from aidialog.dialog import Message
 from aidialog.hist import output_parts, merge_media
@@ -32,21 +33,32 @@ def part2block(p):
 def mk_server(c:Client):
     "An `MCPServer` whose tools close over `c`: connect, execute, and the lifecycle verbs"
     alock = asyncio.Lock()
+    input_schema = dict(type='object', properties=dict(value=dict(type='string')), required=['value'])
+
+    async def _input(msg):
+        content = msg['content']
+        if content.get('password'): raise RuntimeError('password prompts are not supported through MCP')
+        r = await srv.elicit(content.get('prompt',''), input_schema)
+        if r.get('action') != 'accept': raise RuntimeError(f"input {r.get('action','cancelled')}")
+        return r['content']['value']
+
     async def connect(
         host:str='', # Gateway: empty for the local default, a `gateways.toml` name, or a URL
         kernel:str='', # Kernel id (or unique prefix) to attach to; empty creates a fresh kernel
     )->str:
-        "Connect to a kernel. With `kernel`: attach to that existing kernel exactly as it is (nothing is run) - this is how a later conversation returns to live state, and how to reach a kernel someone else created. Without: create a fresh kernel, run the user's startup.py in it, and install their inspectors; the reply includes the new kernel's id (reusable in a later `connect`) and the startup output. Kernels made or attached this way persist until explicitly stopped: disconnecting, switching, and conversation end never kill them. (Connecting also immediately stops the auto kernel, if `execute` had created one.)"
+        "Connect to a kernel. With `kernel`: attach to that existing kernel exactly as it is (nothing is run) - this is how a later conversation returns to live state, and how to reach a kernel someone else created. Without: create a fresh kernel, run the user's startup.py in it, and install their inspectors; the reply includes the new kernel's id (reusable in a later `connect`). Kernels made or attached this way persist until explicitly stopped: disconnecting, switching, and conversation end never kill them. (Connecting also immediately stops the auto kernel, if `execute` had created one.)"
         return await c.connect(host, kernel)
 
     async def execute(
         code:str, # Python/IPython code to run
     ):
-        "Run `code` in the current kernel, keeping state across calls (imports, variables, monkeypatches, cached objects). With no kernel connected, one is auto-created first (default gateway, startup.py and inspectors run), and its connect banner - kernel id and startup output - is prepended to the reply: read it. An auto-created kernel is scoped to the conversation: it stops when the conversation ends or when `connect` moves elsewhere; use `connect` for a kernel that should outlive the conversation. If the reply says the kernel died, `connect` again. Image outputs (plots etc.) come back as image blocks, resized to a token-friendly size, each preceded by its `<media id=...>` tag."
+        "Run `code` in the current kernel, keeping state across calls (imports, variables, monkeypatches, cached objects). With no kernel connected, one is auto-created first (default gateway, startup.py and inspectors run). An auto-created kernel is scoped to the conversation: it stops when the conversation ends or when `connect` moves elsewhere; use `connect` for a kernel that should outlive the conversation. Kernel input prompts use the MCP client's elicitation UI. Password prompts are refused. If the reply says the kernel died, `connect` again. Image outputs (plots etc.) come back as image blocks, resized to a token-friendly size, each preceded by its `<media id=...>` tag."
         pre = ''
-        async with alock:   # parallel first calls must not each create a kernel
-            if not c.kc: pre = await c.connect(auto=True) + '\n'
-        r = await c.execute_outs(code)
+        async with alock:
+            if not c.kc:
+                banner = await c.connect(auto=True)
+                if not c.quiet: pre = banner + '\n'
+        r = await c.execute_outs(code, on_stdin=_input)
         if isinstance(r, str): return pre + r
         res = merge_media(render_text(r, tb_maxlen=MAXLEN), output_parts(Message(msg_type='code', output=r)))
         if isinstance(res, str): return pre + res
@@ -74,14 +86,21 @@ def mk_server(c:Client):
         "Interrupt the code the current kernel is running (SIGINT, i.e. KeyboardInterrupt): the in-flight `execute` 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` is running."
         return await c.interrupt()
 
-    return MCPServer('clikernel', [connect, execute, list_kernels, stop_kernel, restart, interrupt], version=__version__)
+    if not c.quiet:
+        connect.__doc__ += " The startup output also appears in the reply."
+        execute.__doc__ += " The connect banner - kernel id and startup output - is prepended to that first reply: read it."
+    srv = MCPServer('clikernel', [connect, execute, list_kernels, stop_kernel, restart, interrupt], version=__version__)
+    return srv
 
 
 # %% ../nbs/01_mcp.ipynb #3b90f0e8
-def main():
+@call_parse
+def main(
+    quiet:store_true=False,  # Keep startup output out of replies; an auto-connecting `execute` returns just the result
+):
     "The `clikernel-mcp` console script: the tools on stdio, state is one `Client`"
     async def _main():
-        c = Client()
+        c = Client(quiet=quiet)
         try: await serve_stdio(mk_server(c))
         finally:
             if c.auto:   # an execute-made kernel is conversation-scoped; the gateway may already be gone

{clikernel-0.2.6 → clikernel-0.2.7}/clikernel/stream.py

@@ -13,6 +13,8 @@ so the compact protocol exercises the full real stack -- which is its point:
 a self-contained test client, and a reminder to keep the layers flexible.
 """
 import json,os,select,signal,subprocess,sys,time
+from fastcore.nbio import msg2out
+from jupywire.route import OUTPUT_MSGS
 
 def _emit(obj):
     sys.stdout.write(json.dumps(obj) + '\n')
@@ -20,7 +22,9 @@ def _emit(obj):
 
 async def _do_exec(kc, req):
     rid = req.get('id')
-    async for o in kc.run(req['code']): _emit(dict(ev='out', id=rid, output=o))
+    def _out(m):
+        if m['msg_type'] in OUTPUT_MSGS: _emit(dict(ev='out', id=rid, output=msg2out(m)))
+    await kc.run(req['code'], on_output=_out)
     _emit({'ev':'done','id':rid})
 
 async def _do_complete(kc, req):

{clikernel-0.2.6 → clikernel-0.2.7/clikernel.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clikernel
-Version: 0.2.6
+Version: 0.2.7
 Summary: Serve persistent Jupyter kernels to LLMs as concise text, over MCP or a plain stream protocol
 Author: clikernel contributors
 License: Apache-2.0
@@ -12,9 +12,9 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: fastcore>=2.2.2
-Requires-Dist: jupyasyncclient>=0.2.8
+Requires-Dist: jupyasyncclient>=0.2.9
 Requires-Dist: fastspec>=0.2.2
-Requires-Dist: mcpmini>=0.0.1
+Requires-Dist: mcpmini>=0.0.3
 Requires-Dist: aidialog>=0.0.7
 Requires-Dist: pillow
 Provides-Extra: dev
@@ -51,7 +51,11 @@ Register the stdio server with your MCP host, e.g. for Claude Code:
 claude mcp add clikernel -- clikernel-mcp
 ```
 
-The tools mirror the gateway’s kernel API plus one composite: `connect` (create a fresh kernel — running `startup.py` and installing inspectors — or attach to an existing one by id), `execute` (run code, get concise text), `list_kernels`, `stop_kernel`, `restart`, and `interrupt`. An `execute` with no kernel connected auto-creates one, scoped to the conversation: it stops at conversation end, or when `connect` moves elsewhere. Kernels made or attached with an explicit `connect` are stopped only by `stop_kernel` — a later conversation reattaches by id and continues where the last one stopped. `$CLIKERNEL_HOST` overrides the default gateway (`http://127.0.0.1:8787`).
+The tools mirror the gateway’s kernel API: `connect`, `execute`, `list_kernels`, `stop_kernel`, `restart`, and `interrupt`. When executed code requests input, the MCP client shows an elicitation dialog while the same `execute` call remains active. Repeated prompts repeat that callback. Password-marked prompts are refused.
+
+An `execute` with no kernel connected auto-creates one, scoped to the conversation: it stops at conversation end, or when `connect` moves elsewhere. Kernels made or attached with an explicit `connect` are stopped only by `stop_kernel` — a later conversation reattaches by id and continues where the last one stopped. `$CLIKERNEL_HOST` overrides the default gateway (`http://127.0.0.1:8787`).
+
+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, and an auto-connecting `execute` returns just the result.
 
 ## Configuration
 

{clikernel-0.2.6 → clikernel-0.2.7}/clikernel.egg-info/requires.txt

@@ -1,7 +1,7 @@
 fastcore>=2.2.2
-jupyasyncclient>=0.2.8
+jupyasyncclient>=0.2.9
 fastspec>=0.2.2
-mcpmini>=0.0.1
+mcpmini>=0.0.3
 aidialog>=0.0.7
 pillow
 

{clikernel-0.2.6 → clikernel-0.2.7}/pyproject.toml

@@ -17,9 +17,9 @@ classifiers = [
 
 dependencies = [
   "fastcore>=2.2.2",
-  "jupyasyncclient>=0.2.8",
+  "jupyasyncclient>=0.2.9",
   "fastspec>=0.2.2",
-  "mcpmini>=0.0.1",
+  "mcpmini>=0.0.3",
   "aidialog>=0.0.7",
   "pillow",
 ]