Returns a dict so the caller can branch on exit_code and parse
    stdout without string-scraping. Every call is logged to evolution.db
    for later recall via `query_command_history`.

    Args:
        command: The shell command to execute.
        repl_id: REPL whose cwd the command runs in.
        timeout_seconds: Kill the process if it exceeds this (capped at 600).
        cwd: Override the REPL's cwd for this one call.
        use_shell: If True, pass to /bin/sh (enables pipes, redirects,
            glob expansion). Default False = tokenized exec, safer.
        env_extra: Additional env vars merged onto os.environ.
        stdin_input: Optional string piped to the command's stdin.
            Enables first-class stdin piping so CLI tools that read
            from stdin (jq, wc, grep, etc.) work without shell pipe
            syntax.  When None the child's stdin is /dev/null.
    

    Use this for watchers (watchexec, tail -f), servers, REPLs, or any
    command you want to poll output from over time. For one-shot
    commands use run_shell instead — it's simpler and auto-logs.

    Returns proc_id which is passed to tail_shell_output, send_to_shell,
    kill_shell, and wait_shell.
    

    Args:
        proc_id: From spawn_shell.
        n_lines: How many recent lines to return (capped at 500).
        stream: 'stdout', 'stderr', or 'both'.
        drain: If True, remove returned lines from the buffer so the
            next call sees only NEW output. Useful for polling loops.
    

    Args:
        signal_name: 'SIGTERM' (graceful, default), 'SIGKILL' (force),
            or 'SIGINT' (Ctrl-C equivalent).
        remove_from_registry: Drop from _PROCESSES after signalling.
    

    Args:
        pattern: SQL LIKE pattern against the command text (case-insensitive).
            Use % as wildcard, e.g. '%ripgrep%' or 'git commit%'.
        repl_id: Filter to commands run in a specific REPL.
        only_failures: Return only non-zero exit codes.
        only_timeouts: Return only commands that hit the timeout.
        since: ISO timestamp, or relative like '1h', '30m', '2d'.
        limit: Max rows to return (capped at 200).

    Returns:
        List of CommandLogEntry dicts, newest first.
    

    Args:
        since: Window to analyze (ISO or '1h'/'1d' etc). None = all time.
        top_n: How many entries to return in each top-list.
    

    Spawns a fresh subprocess running `<venv>/bin/python -c CODE`.
    No namespace carries over between calls — each invocation is a
    new interpreter. Use this when the project has dependencies that
    aren't installed in the MCP server's Python environment.

    Args:
        code: Python source to execute.
        venv_path: Path to the venv directory (e.g., "/proj/.venv")
            OR direct path to the python binary. `~` is expanded.
        repl_id: Optional REPL to inherit cwd from. Falls back to
            cwd argument, then to server's cwd.
        cwd: Explicit working directory override.
        timeout_seconds: Kill after N seconds (capped at 600).
        env_extra: Additional env vars merged onto os.environ.
            PYTHONPATH is NOT auto-set — pass it via env_extra if
            the project uses src-layout and needs it.

    Returns:
        VenvResult dict with ok/python_path/cwd/stdout/stderr/
        exit_code/duration_ms/timed_out/truncation flags/error.
    

    Checks, in order: .venv/, venv/, env/. Returns the path to the
    python binary if found, so it can be fed directly to
    run_python_in_venv.

    Args:
        repl_id: REPL whose cwd to search under.
    

Create a new Python REPL environment.

Returns:
    str: ID of the new REPL

Execute Python code in a REPL. (Create new or use an existing REPL)

Args:
    code: Python code to execute
    repl_id: ID of the REPL to use

Returns:
    str: Result of the execution including stdout, stderr, and the return value

Get information about a specific REPL instance.

Args:
    repl_id: ID of the REPL to get info for

Returns:
    str: Information about the REPL

Delete a REPL instance.

Args:
    repl_id: ID of the REPL to delete

Returns:
    str: Confirmation message

Initialize the Modular Empowerment Framework in a specific REPL.

Args:
    repl_id: ID of the REPL to initialize in

Returns:
    str: Result of the initialization