jupyter-kernel-cli 0.1.0__py3-none-any.whl

jupyter_kernel_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: jupyter-kernel-cli
+Version: 0.1.0
+Summary: Agent-friendly CLI and Python API for talking to existing Jupyter kernels.
+Home-page: https://github.com/hruskamiro/jupyter-kernel-client
+Author: Miroslav Hruska
+Author-email: hruska.miro@gmail.com
+License: MIT
+Project-URL: Homepage, https://github.com/hruskamiro/jupyter-kernel-client
+Project-URL: Repository, https://github.com/hruskamiro/jupyter-kernel-client
+Project-URL: Issues, https://github.com/hruskamiro/jupyter-kernel-client/issues
+Keywords: jupyter,kernel,cli,automation,agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jupyter-client>=7.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# jupyter-kernel-client
+
+`jk` is a small command-line tool and Python library for **executing code in an existing Jupyter kernel**.
+
+It is designed for scripts and AI agents that need a **stable, machine-readable way to inspect or modify a live Python session**.
+
+## Intended Use Case
+
+You are working in an IPython console, Spyder console, notebook kernel, or other Jupyter-backed Python session. **The session already has important state loaded:** imports, data frames, models, helper functions, configuration, intermediate results, and whatever else you have built up interactively.
+
+**Instead of asking an AI agent to recreate that state from scratch, give it access to the existing kernel.** Export or copy the kernel connection information, tell the agent to use `jk`, and let it inspect variables, run experiments, evaluate expressions, and return structured output from the same live Python process you are using.
+
+The workflow is:
+
+1. **Work normally** in an IPython, Spyder, notebook, or other Jupyter-backed console.
+2. **Load the state you care about:** data, objects, functions, imports, models, and intermediate results.
+3. **Copy the active kernel connection info**, for example with `%connect_info`.
+4. **Give that connection info to Codex or another agent.**
+5. **Tell the agent to use `jk`** to connect to that exact kernel.
+6. **Let the agent inspect and experiment** with `jk exec`, `jk eval`, `jk get`, and `jk vars`.
+
+This is useful when the hard part is **not writing code from a blank environment**, but **exploring and manipulating the state that already exists in a live session**.
+
+## Install
+
+Recommended:
+
+```bash
+pipx install jupyter-kernel-cli
+```
+
+Other install paths:
+
+```bash
+pipx install git+https://github.com/hruskamiro/jupyter-kernel-client.git
+pipx upgrade jupyter-kernel-cli
+pipx install --force .
+python -m pip install -e ".[dev]"
+```
+
+Check:
+
+```bash
+jk --help
+```
+
+## Usage
+
+Common commands:
+
+```bash
+jk kernels
+jk kernels --probe
+jk exec -f /path/to/kernel.json "x = 41"
+jk eval -f /path/to/kernel.json "x + 1"
+jk get -f /path/to/kernel.json x
+jk vars -f /path/to/kernel.json --json
+jk demo -f /path/to/kernel.json --json
+```
+
+Use **JSON for agents** and stdin for larger generated code:
+
+```bash
+cat <<'PY' | jk exec -f /path/to/kernel.json --json --stdin
+import pandas as pd
+
+summary = {
+    "variables": sorted(name for name in globals() if not name.startswith("_")),
+    "answer": 6 * 7,
+}
+summary
+PY
+```
+
+Other supported forms:
+
+```bash
+jk exec -f /path/to/kernel.json --file script.py
+jk -f /path/to/kernel.json --json eval "x + 1"
+export JK_CONNECTION_FILE=/path/to/kernel.json
+jk eval "df.shape"
+```
+
+The JSON response includes status, stdout, stderr, rich display outputs, final `text/plain` result, parsed Python literal when possible, traceback details, elapsed time, timeout state, and message id.
+
+## Using `jk` from Codex
+
+One working pattern is to start Codex with workspace sandboxing and on-request approvals:
+
+```bash
+codex -s workspace-write -a on-request
+```
+
+The exact command and permission flow may change across Codex versions, approval policies, sandbox settings, and local configuration. The important point is that Codex may need permission to run `jk` outside its command sandbox so it can open the local Jupyter kernel connection.
+
+Give Codex the **active kernel connection information**. You can copy it from
+`%connect_info`, or use
+[`spyder-copy-current`](https://github.com/hruskamiro/spyder-copy-current) and
+press `Ctrl+Alt+K` in Spyder to copy the current console's connection
+information.
+
+Ask Codex explicitly to **run `jk` outside its command sandbox**. For example:
+
+```text
+Connect to this exact Jupyter kernel using jk. Run jk with an elevated request
+and ask for reusable approval of the jk executable prefix.
+
+<paste the kernel connection information here>
+```
+
+Approve the permission request shown by Codex. If the interface offers reusable command-prefix approval, scope it to the resolved `jk` executable, which can be found with `command -v jk`.
+
+**Approving `jk` allows arbitrary code execution in the connected Jupyter
+kernel.** Treat this as execution access to that live Python session, even when
+the rest of the Codex session remains workspace-sandboxed.
+
+## JSON Contract
+
+Successful JSON responses include:
+
+```json
+{
+  "status": "ok",
+  "ok": true,
+  "execution_count": 12,
+  "stdout": "",
+  "stderr": "",
+  "outputs": [],
+  "result_text": "42",
+  "result_python": 42,
+  "ename": null,
+  "evalue": null,
+  "traceback": [],
+  "elapsed_seconds": 0.01,
+  "timed_out": false,
+  "msg_id": "..."
+}
+```
+
+Exit codes:
+
+```text
+0    kernel execution succeeded
+1    kernel execution raised an error
+2    client or argument error
+124  client timed out waiting for the kernel
+```
+
+Timeouts only stop the client wait. With only a connection file, `jk` cannot reliably kill or interrupt an arbitrary kernel process, so timed-out execution may continue in the kernel.
+
+## Python API
+
+```python
+from jupyter_kernel_client import execute, eval_expression, get_variable
+
+response = eval_expression("/path/to/kernel.json", "x + 1")
+if response.ok:
+    print(response.result_python)
+```
+
+## License
+
+MIT.

jupyter_kernel_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+jupyter_kernel_cli-0.1.0.dist-info/licenses/LICENSE,sha256=d_PcsgZbFuE93GSCHhXlJzl3kG__dhFQAUSsE0MSwnA,1072
+jupyter_kernel_client/__init__.py,sha256=WRUdSC17b9Ol_dO33yJayHcBOPvMcrvW5nzoEr8PL6E,387
+jupyter_kernel_client/cli.py,sha256=mpnS43xK7USguocwl83MFcfopPzwBJLVld4tSYkUL3w,10779
+jupyter_kernel_client/client.py,sha256=02_QMLedtbN0FPiH8Vw6jifYW--s_04HefYgGgzcOtw,7678
+jupyter_kernel_cli-0.1.0.dist-info/METADATA,sha256=pRCowl_TG21n1WW4z94ecO4lBe_ZtJyyy9gGXF78DoY,6633
+jupyter_kernel_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+jupyter_kernel_cli-0.1.0.dist-info/entry_points.txt,sha256=DfFgYmRuw95UCD8nZVMS01_2QSnNbCFZrfBAvUlIVqc,54
+jupyter_kernel_cli-0.1.0.dist-info/top_level.txt,sha256=rd_e7DJIJyUsPY3s7sVcqqmBzO3XqyA7RiUoRARzxRM,22
+jupyter_kernel_cli-0.1.0.dist-info/RECORD,,

jupyter_kernel_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

jupyter_kernel_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jk = jupyter_kernel_client.cli:main

jupyter_kernel_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miroslav Hruska
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jupyter_kernel_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+jupyter_kernel_client

jupyter_kernel_client/__init__.py

@@ -0,0 +1,21 @@
+"""Small client for executing code in an existing Jupyter kernel."""
+
+from .client import (
+    KernelClientError,
+    KernelResponse,
+    RichOutput,
+    execute,
+    eval_expression,
+    get_variable,
+    kernel_is_ready,
+)
+
+__all__ = [
+    "KernelClientError",
+    "KernelResponse",
+    "RichOutput",
+    "execute",
+    "eval_expression",
+    "get_variable",
+    "kernel_is_ready",
+]

jupyter_kernel_client/cli.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+from jupyter_core.paths import jupyter_runtime_dir
+
+from .client import KernelClientError, KernelResponse, execute, eval_expression, get_variable, kernel_is_ready
+
+
+def _default_connection_file() -> Optional[str]:
+    return os.environ.get("JK_CONNECTION_FILE") or os.environ.get("JUPYTER_CONNECTION_FILE")
+
+
+def _runtime_connection_files(limit: Optional[int] = None) -> List[Path]:
+    runtime = Path(jupyter_runtime_dir()).expanduser()
+    if not runtime.exists():
+        return []
+    files = sorted(runtime.glob("kernel-*.json"), key=lambda path: path.stat().st_mtime, reverse=True)
+    if limit is not None:
+        return files[:limit]
+    return files
+
+
+def _kernel_record(path: Path, *, probe: bool, timeout: float) -> dict:
+    record = {
+        "path": str(path),
+        "modified": path.stat().st_mtime,
+        "alive": None,
+        "error": None,
+    }
+    if not probe:
+        return record
+
+    try:
+        kernel_is_ready(str(path), timeout=timeout)
+        record["alive"] = True
+    except Exception as exc:
+        record["alive"] = False
+        record["error"] = str(exc)
+    return record
+
+
+def _read_code(args: argparse.Namespace) -> str:
+    sources = [bool(args.code), bool(args.file), bool(args.stdin)]
+    if sum(sources) != 1:
+        raise KernelClientError("Provide exactly one code source: argument, --file, or --stdin.")
+    if args.stdin:
+        return sys.stdin.read()
+    if args.file:
+        return Path(args.file).expanduser().read_text()
+    return args.code
+
+
+def _print_human(response: KernelResponse) -> int:
+    if response.stdout:
+        sys.stdout.write(response.stdout)
+    if response.stderr:
+        sys.stderr.write(response.stderr)
+
+    if response.status == "timeout":
+        sys.stderr.write(f"Timed out after {response.elapsed_seconds:.2f}s. Kernel execution may still be running.\n")
+        return 124
+
+    if response.status == "error":
+        if response.traceback:
+            sys.stderr.write("\n".join(response.traceback) + "\n")
+        elif response.ename or response.evalue:
+            sys.stderr.write(f"{response.ename}: {response.evalue}\n")
+        return 1
+
+    if response.result_text is not None:
+        sys.stdout.write(f"{response.result_text}\n")
+    return 0
+
+
+def _emit_response(response: KernelResponse, *, json_output: bool) -> int:
+    if json_output:
+        print(json.dumps(response.to_dict(), ensure_ascii=True))
+        if response.status == "timeout":
+            return 124
+        return 0 if response.ok else 1
+    return _print_human(response)
+
+
+def _resolve_connection_file(args: argparse.Namespace) -> str:
+    connection_file = args.connection_file or _default_connection_file()
+    if connection_file:
+        return str(Path(connection_file).expanduser())
+    raise KernelClientError(
+        "No connection file provided. Use --connection-file, JK_CONNECTION_FILE, "
+        "JUPYTER_CONNECTION_FILE, or run `jk kernels` to list candidates."
+    )
+
+
+def _add_common_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--connection-file",
+        "-f",
+        help="Path to a Jupyter kernel connection JSON file. Defaults to JK_CONNECTION_FILE or JUPYTER_CONNECTION_FILE.",
+    )
+    parser.add_argument("--timeout", type=float, default=30.0, help="Seconds to wait for execution completion.")
+    parser.add_argument("--json", action="store_true", help="Emit stable structured JSON output.")
+
+
+def _vars_code(*, include_private: bool, repr_length: int) -> str:
+    private_check = "True" if include_private else "not name.startswith('_')"
+    return f"""
+[
+    {{
+        "name": name,
+        "type": type(value).__module__ + "." + type(value).__qualname__,
+        "repr": repr(value)[:{repr_length}],
+    }}
+    for name, value in sorted(globals().items())
+    if {private_check}
+    and name not in {{"In", "Out", "exit", "quit", "get_ipython"}}
+]
+""".strip()
+
+
+def _run_demo(connection_file: str, *, timeout: float, json_output: bool) -> int:
+    snippets = [
+        ("stdout_and_result", "print('hello from jk')\n21 * 2"),
+        ("state_write", "jk_demo_value = {'ready': True, 'items': [1, 2, 3]}\njk_demo_value"),
+        ("state_read", "jk_demo_value"),
+        ("rich_output", "from IPython.display import display, HTML\ndisplay(HTML('<b>jk html output</b>'))\n'ok'"),
+    ]
+
+    results = []
+    exit_code = 0
+    for name, code in snippets:
+        response = execute(connection_file, code, timeout=timeout)
+        results.append({"name": name, "response": response.to_dict()})
+        if not response.ok and exit_code == 0:
+            exit_code = 124 if response.status == "timeout" else 1
+
+    if json_output:
+        print(json.dumps({"status": "ok" if exit_code == 0 else "error", "ok": exit_code == 0, "checks": results}, ensure_ascii=True))
+        return exit_code
+
+    for result in results:
+        response = result["response"]
+        status = "ok" if response["ok"] else response["status"]
+        print(f"{result['name']}: {status}")
+        if response["stdout"]:
+            print(response["stdout"], end="")
+        if response["result_text"] is not None:
+            print(response["result_text"])
+        if response["outputs"]:
+            print(f"outputs: {len(response['outputs'])}")
+    return exit_code
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="jk", description="Execute code in an existing Jupyter kernel.")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    exec_parser = subparsers.add_parser("exec", help="Execute code.")
+    _add_common_options(exec_parser)
+    exec_parser.add_argument("code", nargs="?", help="Code to execute.")
+    exec_parser.add_argument("--file", "-i", help="Read code from a file.")
+    exec_parser.add_argument("--stdin", action="store_true", help="Read code from standard input.")
+    exec_parser.add_argument("--silent", action="store_true", help="Execute silently.")
+    exec_parser.add_argument("--no-history", action="store_true", help="Do not store execution in kernel history.")
+
+    eval_parser = subparsers.add_parser("eval", help="Evaluate a Python expression.")
+    _add_common_options(eval_parser)
+    eval_parser.add_argument("expression", help="Python expression to evaluate.")
+
+    get_parser = subparsers.add_parser("get", help="Get a variable by name.")
+    _add_common_options(get_parser)
+    get_parser.add_argument("name", help="Variable name to fetch from the kernel.")
+
+    vars_parser = subparsers.add_parser("vars", help="Inspect user-visible variables in the kernel namespace.")
+    _add_common_options(vars_parser)
+    vars_parser.add_argument("--include-private", action="store_true", help="Include names beginning with underscore.")
+    vars_parser.add_argument("--repr-length", type=int, default=160, help="Maximum repr length per variable.")
+
+    demo_parser = subparsers.add_parser("demo", help="Run a short capability demo against a kernel.")
+    _add_common_options(demo_parser)
+
+    kernels_parser = subparsers.add_parser("kernels", help="List recent connection files in the Jupyter runtime directory.")
+    kernels_parser.add_argument("--json", action="store_true", help="Emit JSON.")
+    kernels_parser.add_argument("--limit", type=int, default=20, help="Maximum files to list. Use 0 for no limit.")
+    kernels_parser.add_argument("--probe", action="store_true", help="Connect to each listed file and report whether it responds.")
+    kernels_parser.add_argument("--timeout", type=float, default=1.0, help="Seconds to wait per probed kernel.")
+
+    return parser
+
+
+def _normalize_argv(argv: Optional[Iterable[str]]) -> Optional[List[str]]:
+    if argv is None:
+        values = sys.argv[1:]
+    else:
+        values = list(argv)
+
+    commands = {"exec", "eval", "get", "vars", "demo", "kernels"}
+    command_positions = [index for index, value in enumerate(values) if value in commands]
+    if not command_positions:
+        return values if argv is not None else None
+
+    command_index = command_positions[0]
+    if command_index == 0:
+        return values if argv is not None else None
+
+    normalized = [values[command_index], *values[:command_index], *values[command_index + 1 :]]
+    return normalized
+
+
+def _list_kernels(*, json_output: bool, limit: int, probe: bool, timeout: float) -> int:
+    files = _runtime_connection_files(limit=None if limit == 0 else limit)
+    records = [_kernel_record(path, probe=probe, timeout=timeout) for path in files]
+    if json_output:
+        print(json.dumps(records, ensure_ascii=True))
+        return 0
+    if not records:
+        print("No kernel connection files found.")
+        return 1
+    for record in records:
+        if probe:
+            status = "alive" if record["alive"] else "dead"
+            print(f"{status:5} {record['path']}")
+        else:
+            print(record["path"])
+    return 0
+
+
+def main(argv: Optional[Iterable[str]] = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(_normalize_argv(argv))
+
+    try:
+        if args.command == "kernels":
+            return _list_kernels(json_output=args.json, limit=args.limit, probe=args.probe, timeout=args.timeout)
+
+        connection_file = _resolve_connection_file(args)
+        if args.command == "exec":
+            code = _read_code(args)
+            response = execute(
+                connection_file,
+                code,
+                timeout=args.timeout,
+                silent=args.silent,
+                store_history=not args.no_history,
+            )
+        elif args.command == "eval":
+            response = eval_expression(connection_file, args.expression, timeout=args.timeout)
+        elif args.command == "get":
+            response = get_variable(connection_file, args.name, timeout=args.timeout)
+        elif args.command == "vars":
+            response = execute(
+                connection_file,
+                _vars_code(include_private=args.include_private, repr_length=args.repr_length),
+                timeout=args.timeout,
+            )
+        elif args.command == "demo":
+            return _run_demo(connection_file, timeout=args.timeout, json_output=args.json)
+        else:
+            parser.error(f"Unknown command: {args.command}")
+    except Exception as exc:
+        if getattr(args, "json", False):
+            print(json.dumps({"status": "client_error", "ok": False, "error": str(exc)}, ensure_ascii=True))
+        else:
+            print(f"Client error: {exc}", file=sys.stderr)
+        return 2
+
+    return _emit_response(response, json_output=args.json)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

jupyter_kernel_client/client.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import ast
+import json
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from queue import Empty
+from typing import Any, Dict, List, Optional
+
+from jupyter_client import BlockingKernelClient
+
+
+class KernelClientError(RuntimeError):
+    """Raised when the client cannot complete a request."""
+
+
+@dataclass
+class RichOutput:
+    output_type: str
+    data: Dict[str, Any] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    transient: Dict[str, Any] = field(default_factory=dict)
+    execution_count: Optional[int] = None
+    text: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "output_type": self.output_type,
+            "data": self.data,
+            "metadata": self.metadata,
+            "transient": self.transient,
+            "execution_count": self.execution_count,
+            "text": self.text,
+        }
+
+
+@dataclass
+class KernelResponse:
+    status: str
+    execution_count: Optional[int]
+    stdout: str
+    stderr: str
+    outputs: List[RichOutput]
+    result_text: Optional[str]
+    result_python: Any
+    ename: Optional[str]
+    evalue: Optional[str]
+    traceback: List[str]
+    elapsed_seconds: float
+    timed_out: bool
+    msg_id: str
+
+    @property
+    def ok(self) -> bool:
+        return self.status == "ok" and not self.timed_out
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "status": self.status,
+            "ok": self.ok,
+            "execution_count": self.execution_count,
+            "stdout": self.stdout,
+            "stderr": self.stderr,
+            "outputs": [output.to_dict() for output in self.outputs],
+            "result_text": self.result_text,
+            "result_python": self.result_python,
+            "ename": self.ename,
+            "evalue": self.evalue,
+            "traceback": self.traceback,
+            "elapsed_seconds": self.elapsed_seconds,
+            "timed_out": self.timed_out,
+            "msg_id": self.msg_id,
+        }
+
+
+def _parse_python_literal(text: Optional[str]) -> Any:
+    if text is None:
+        return None
+    try:
+        return ast.literal_eval(text)
+    except Exception:
+        return text
+
+
+def _make_client(connection_file: str, *, ready_timeout: float = 5.0) -> BlockingKernelClient:
+    path = Path(connection_file).expanduser()
+    if not path.exists():
+        raise KernelClientError(f"Connection file does not exist: {path}")
+
+    client = BlockingKernelClient(connection_file=str(path))
+    client.load_connection_file()
+    client.start_channels()
+    try:
+        client.wait_for_ready(timeout=ready_timeout)
+    except Exception as exc:
+        client.stop_channels()
+        raise KernelClientError(f"Kernel did not become ready within {ready_timeout:.1f}s: {exc}") from exc
+    return client
+
+
+def kernel_is_ready(connection_file: str, *, timeout: float = 1.0) -> None:
+    """Raise KernelClientError if the kernel connection file does not respond."""
+    client = _make_client(connection_file, ready_timeout=timeout)
+    client.stop_channels()
+
+
+def _json_safe(value: Any) -> Any:
+    try:
+        json.dumps(value)
+        return value
+    except TypeError:
+        return repr(value)
+
+
+def _message_output(msg_type: str, content: Dict[str, Any]) -> Optional[RichOutput]:
+    if msg_type not in {"execute_result", "display_data", "update_display_data"}:
+        return None
+
+    data = {key: _json_safe(value) for key, value in content.get("data", {}).items()}
+    text = data.get("text/plain")
+    return RichOutput(
+        output_type=msg_type,
+        data=data,
+        metadata=content.get("metadata", {}),
+        transient=content.get("transient", {}),
+        execution_count=content.get("execution_count"),
+        text=text if isinstance(text, str) else None,
+    )
+
+
+def execute(
+    connection_file: str,
+    code: str,
+    *,
+    timeout: float = 30.0,
+    ready_timeout: float = 5.0,
+    silent: bool = False,
+    store_history: bool = True,
+    allow_stdin: bool = False,
+) -> KernelResponse:
+    """Execute code in an existing Jupyter kernel and collect its IOPub output."""
+    if timeout <= 0:
+        raise ValueError("timeout must be greater than zero")
+
+    client = _make_client(connection_file, ready_timeout=ready_timeout)
+    stdout_chunks: List[str] = []
+    stderr_chunks: List[str] = []
+    outputs: List[RichOutput] = []
+    result_text: Optional[str] = None
+    execution_count: Optional[int] = None
+    status = "unknown"
+    ename: Optional[str] = None
+    evalue: Optional[str] = None
+    traceback: List[str] = []
+    msg_id = ""
+    started = time.monotonic()
+    timed_out = False
+
+    try:
+        msg_id = client.execute(
+            code,
+            silent=silent,
+            store_history=store_history,
+            user_expressions={},
+            allow_stdin=allow_stdin,
+            stop_on_error=True,
+        )
+        deadline = started + timeout
+
+        while time.monotonic() < deadline:
+            remaining = max(0.05, deadline - time.monotonic())
+            try:
+                msg = client.get_iopub_msg(timeout=remaining)
+            except Empty:
+                continue
+
+            if msg.get("parent_header", {}).get("msg_id") != msg_id:
+                continue
+
+            msg_type = msg.get("msg_type")
+            content = msg.get("content", {})
+
+            if msg_type == "stream":
+                if content.get("name") == "stderr":
+                    stderr_chunks.append(content.get("text", ""))
+                else:
+                    stdout_chunks.append(content.get("text", ""))
+            elif msg_type in {"execute_result", "display_data", "update_display_data"}:
+                output = _message_output(msg_type, content)
+                if output is not None:
+                    outputs.append(output)
+                    if output.text is not None:
+                        result_text = output.text
+                    execution_count = output.execution_count or execution_count
+            elif msg_type == "error":
+                status = "error"
+                ename = content.get("ename")
+                evalue = content.get("evalue")
+                traceback = content.get("traceback", [])
+            elif msg_type == "execute_input":
+                execution_count = content.get("execution_count", execution_count)
+            elif msg_type == "status" and content.get("execution_state") == "idle":
+                if status != "error":
+                    status = "ok"
+                break
+
+        timed_out = status == "unknown"
+        if timed_out:
+            status = "timeout"
+    finally:
+        client.stop_channels()
+
+    return KernelResponse(
+        status=status,
+        execution_count=execution_count,
+        stdout="".join(stdout_chunks),
+        stderr="".join(stderr_chunks),
+        outputs=outputs,
+        result_text=result_text,
+        result_python=_parse_python_literal(result_text),
+        ename=ename,
+        evalue=evalue,
+        traceback=traceback,
+        elapsed_seconds=round(time.monotonic() - started, 6),
+        timed_out=timed_out,
+        msg_id=msg_id,
+    )
+
+
+def eval_expression(connection_file: str, expression: str, *, timeout: float = 30.0) -> KernelResponse:
+    sentinel = f"__jk_value_{uuid.uuid4().hex}__"
+    code = f"globals()[{sentinel!r}] = ({expression})\nglobals().pop({sentinel!r})"
+    return execute(connection_file, code, timeout=timeout)
+
+
+def get_variable(connection_file: str, variable_name: str, *, timeout: float = 30.0) -> KernelResponse:
+    return eval_expression(connection_file, variable_name, timeout=timeout)