"""Execute MCP tool — a persistent IPython kernel (REPL) per session. Complements the terminal tool: ``terminal`` runs fresh bash shells, this runs Python in a persistent kernel where state (variables, imports, cwd) survives across calls. The kernel is a subprocess launched with crow-cli's own interpreter, so crow's libraries are available and code can interrogate crow.db. One kernel per ACP session, keyed by the session id riding the call's ``_meta``. """ import os import sys from logging import getLogger from pathlib import Path from fastmcp import Context from crow_cli.mcp.server.app import mcp from crow_cli.mcp_meta import meta_get, rail_unread from .kernel import CrowKernel, KernelDead logger = getLogger(__name__) # Kernels keyed by ACP session id: one persistent REPL per session. A bare # caller (no _meta) is keyed by cwd instead. _kernels: dict[str, CrowKernel] = {} def _kernel_context( ctx: Context, ) -> tuple[str, str, str | None, str | None, str | None, str | None, int]: """Return ``(key, cwd, session_id, parent_tcid, db_uri, images_dir, rlm_depth)`` from the caller-injected ``_meta``. The agent injects these (``execute_acp_execute``) so the kernel is keyed per session and starts in the session's working directory. The Context parameter is filtered out of the LLM-facing schema, so the model never sees — and cannot forge — any of it. No meta means a bare caller: key and cwd fall back to the server process's cwd. ``parent_tcid`` (the execute call's own ACP tool-call id) and ``db_uri`` feed the per-cell begin_cell prologue: they stamp subtool register entries and point the write-through sink at crow.db so the server-side drain can re-emit in-cell tool calls to the ACP client. ``images_dir`` points the kernel's image sink at the session's ImageStore directory so vision bytes land where the server's drain hydrates them. ``rlm_depth`` is how many delegations deep the calling session is, so an in-cell rlm can enforce its budget; a bare caller is depth 0. """ meta = ctx.request_context.meta if ctx.request_context else None cwd = meta_get(meta, "cwd") or os.getcwd() session_id = meta_get(meta, "session_id") parent_tcid = meta_get(meta, "tool_call_id") db_uri = meta_get(meta, "db_uri") images_dir = meta_get(meta, "images_dir") depth = meta_get(meta, "rlm_depth") if rail_unread(meta, session_id): logger.warning( "execute got a _meta it could not read (%s) — kernels fall back to " "cwd keying and the in-cell tools lose their identity", type(meta).__name__, ) return ( session_id or cwd, cwd, session_id, parent_tcid, db_uri, images_dir, depth if isinstance(depth, int) and depth > 0 else 0, ) # ~5k tokens — the same discipline as terminal's MAX_CMD_OUTPUT_SIZE. MAX_OUTPUT_CHARS = 20_000 _TAIL_CHARS = 4_000 def _cap(output: str) -> str: """Head+tail truncation so one runaway cell can't eat the context.""" if len(output) <= MAX_OUTPUT_CHARS: return output head = MAX_OUTPUT_CHARS - _TAIL_CHARS elided = len(output) - head - _TAIL_CHARS return f"{output[:head]}\n... [{elided} chars elided] ...\n{output[-_TAIL_CHARS:]}" def _prologue( session_id: str | None, parent_tcid: str | None, db_uri: str | None, images_dir: str | None, rlm_depth: int = 0, ) -> str: """Identity injection prepended to every non-empty cell: stamps the subtool register before the model's code runs. Fail-open — a broken prologue warns on stderr and the cell still runs; the tools work without identity (entries record None).""" return ( "try:\n" " from crow_cli.tools.register import begin_cell as _crow_begin\n" f" _crow_begin(session_id={session_id!r}," f" parent_tool_call_id={parent_tcid!r}, db_uri={db_uri!r}," f" images_dir={images_dir!r}, rlm_depth={rlm_depth!r})\n" "except Exception as _crow_e:\n" " import sys as _crow_sys\n" " print(f'crow prologue: {_crow_e}', file=_crow_sys.stderr)\n" ) def get_kernel( key: str, cwd: str, prelude_path: str | None = None, python_path: str | None = None, ) -> CrowKernel: """Get or lazily start the persistent kernel for a key.""" kernel = _kernels.get(key) if kernel is not None and kernel.dead: # A kernel whose channels failed is not reusable, and it is not the # caller's job to notice: replace it here so the next call just works. logger.warning(f"Replacing the dead kernel for {key}") _kernels.pop(key, None) kernel.shutdown() kernel = None if kernel is None: logger.info(f"Starting new IPython kernel for {key} in {cwd}") kernel = CrowKernel(python_path=python_path or sys.executable, cwd=cwd) _run_prelude(kernel, prelude_path) _kernels[key] = kernel return kernel def _run_prelude(kernel: CrowKernel, prelude_path: str | None = None) -> None: """Zero-day imports: every fresh kernel (start AND reset both come through get_kernel) comes up with crow_cli.tools ambient. A prelude_path replaces the built-in prelude with that file's contents. Best effort — a broken prelude logs, it never bricks the kernel.""" if prelude_path: prelude = Path(prelude_path).read_text() else: from crow_cli.tools import PRELUDE prelude = PRELUDE try: output = kernel.execute(prelude) if output.strip(): logger.warning(f"Kernel prelude produced output: {output[:200]}") except Exception: logger.warning("Kernel prelude failed", exc_info=True) def shutdown_all() -> None: """Shut down every live kernel (test cleanup / server teardown).""" for key in list(_kernels): kernel = _kernels.pop(key, None) if kernel: kernel.shutdown() @mcp.tool async def execute( ctx: Context, code: str, reset: bool = False, timeout: float | None = 30.0, prelude_path: str | None = None, python_path: str | None = None, ) -> str: """Execute one cell in this session's persistent IPython kernel. This is a Jupyter-style REPL, not a fresh Python process per call. Every non-reset call runs in the same kernel for this session, so variables, imports, function definitions, open handles, and the working directory survive from one call to the next. Write multi-step work as successive cells and reuse names already defined. Do not re-import or redefine setup merely because this is a new tool call; inspect ``dir()`` if unsure what the kernel already contains. The kernel is isolated per session id, so state does not leak between sessions. A fresh kernel starts with Crow's async helpers (``fs``, ``memory``, ``rlm``, ``vision``, ``web``, ``write``, ``edit``, and ``reload``) already available. They are async: call them with ``await``. ``reload()`` refreshes Crow's tool modules in the current kernel without clearing your variables, imports, or cwd. Use ``reset=True`` only when you intentionally want a completely new kernel; it discards all state and starts the prelude again. It runs with crow-cli's own Python interpreter, so crow's libraries are available and you can interrogate crow.db. Use it for multi-step Python work where you want to build on previous results. For bash/shell commands, use the terminal tool instead. Args: code: Python code to execute. print() is how the code talks back: the returned output is stdout + stderr, or an ANSI-stripped traceback on error. The last expression's value is NOT returned (no REPL Out[n]) — assign it, print it, or use it. reset: If True, shut down the kernel and start a fresh one, clearing all state (variables, imports). Use if the kernel is in a bad state. With empty code, just resets. Cannot clear a single variable — reset clears everything. prelude_path: Optional path to a Python file whose contents run as the prelude of the kernel the reset creates, instead of the built-in zero-day imports — how a reset says "hey, actually load this kernel". Honored only with reset=True; later plain resets fall back to the built-in prelude. python_path: Optional interpreter for the kernel the reset creates — point a reset at any env's python (a bpy-capable one, say). Honored only with reset=True; resets without it use the server's own interpreter. timeout: seconds to wait for the cell to finish (default 30). The cell is NOT killed on timeout — IPython keeps running it — so a long-running process returns a "(kernel busy: …)" notice and its output stays collectable on a later call. Pass a larger value, or None to wait indefinitely, for a cell you know runs long: a blocking rlm() delegation (slow on a local model), a build, a big query, a sleep. Returns: The program's output: stdout and stderr, or a traceback on error. When vision tools ran inside the cell, the server prepends hydrated image blocks to this text for the model — the one and only addition to execute's output. Examples: execute("x = 42") # set a variable (no output) execute("print(x * 2)") # -> "84" execute("import sqlalchemy; print(sqlalchemy.__version__)") execute("", reset=True) # fresh kernel, all state cleared execute("", reset=True, prelude_path="/env/k.py") # reset, custom prelude execute("", reset=True, python_path="/env/bin/python") # reset, other interpreter """ key = None try: key, cwd, session_id, parent_tcid, db_uri, images_dir, rlm_depth = ( _kernel_context(ctx) ) if (prelude_path or python_path) and not reset: return ( "Error: prelude_path and python_path describe the kernel a " "reset creates — pass reset=True with them." ) if reset: old = _kernels.pop(key, None) if old: old.shutdown() logger.info(f"Reset kernel for {key}") if not code.strip() and not (prelude_path or python_path): return "Kernel reset successfully. All previous state lost." kernel = get_kernel(key, cwd, prelude_path, python_path) if reset and not code.strip(): msg = "Kernel reset successfully. All previous state lost." if prelude_path: msg += f" Prelude loaded from {prelude_path}." if python_path: msg += f" Interpreter: {python_path}." return msg if code.strip(): code = _prologue(session_id, parent_tcid, db_uri, images_dir, rlm_depth) + code output = kernel.execute(code, timeout=timeout) return _cap(output) if output else "[no output]" except KernelDead as e: # The channels are gone, which is not the cell's fault and not # something a retry of THIS call can fix. Drop the kernel so the next # call builds a fresh one, and say so. logger.error(f"Kernel dead: {e}", exc_info=True) if key is not None: _kernels.pop(key, None) return ( f"Error: the kernel's channels died ({e}). It is replaced on the " "next call — call execute again." ) except Exception as e: logger.error(f"Execute error: {e}", exc_info=True) # An empty str(e) — queue.Empty from a timed-out get_shell_msg, the # bare "Error:" that read as "broken" — names its type instead, so the # failure is never invisible. detail = str(e).strip() or type(e).__name__ return f"Error: {detail}"