monkeybot-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{monkeybot_cli-0.5.0 → monkeybot_cli-0.6.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: monkeybot-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: CLI to create, configure, validate, and chat with monkeybot agents.
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: monkeybot-browser-mcp<1,>=0.2.0
-Requires-Dist: monkeybot[cli]<4,>=3.0.0
+Requires-Dist: monkeybot-browser-mcp<1,>=0.5.0
+Requires-Dist: monkeybot[cli]<4,>=3.1.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: textual>=8.2.8

{monkeybot_cli-0.5.0 → monkeybot_cli-0.6.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "monkeybot-cli"
-version = "0.5.0"
+version = "0.6.0"
 description = "CLI to create, configure, validate, and chat with monkeybot agents."
 requires-python = ">=3.11"
 dependencies = [
     # `cli` pulls realtime + typer so `monkeybot talk` works out of the box (text mode).
     # Audio mic/PTT needs the agent (or this env) to also install monkeybot[cli-realtime].
-    "monkeybot[cli]>=3.0.0,<4",
-    "monkeybot-browser-mcp>=0.2.0,<1",
+    "monkeybot[cli]>=3.1.0,<4",
+    "monkeybot-browser-mcp>=0.5.0,<1",
     "httpx>=0.27.0",
     "pyyaml>=6.0.2",
     "python-dotenv>=1.0.0",

{monkeybot_cli-0.5.0 → monkeybot_cli-0.6.0}/skills/monkeybot/SKILL.md

@@ -56,7 +56,7 @@ npx skills add human-plus-machine/monkeybot --skill monkeybot
   - `monkeybot_config/monkeybot.yaml` — non-secret settings (model, paths, gateway, behavior).
   - `.env` — secrets and machine-local paths (API keys, GCP project, DB URL).
   - sidecars: `monkeybot_config/AGENT.md` (system prompt), `mcp.json` (MCP servers), `command_allowlist.yaml`.
-- **Precedence — important:** environment variables and `.env` win over `monkeybot.yaml`. If a user edits YAML but nothing changes, suspect a stale `.env` shadowing it (the YAML→env mapping lives in `runtime_env.py:ENV_MAP`).
+- **Precedence — important:** environment variables and `.env` win over `monkeybot.yaml` except `model.*` (provider, name, sampling, context window, summarization model, max turns, cache retention), which is YAML-only. If a user edits YAML but nothing changes, suspect a stale `.env` shadowing it (the YAML→env mapping lives in `runtime_env.py:ENV_MAP`).
 - **Defaults are fine on day one.** Most first-time users only touch `model`, `.env` credentials, and `AGENT.md`.
 
 ## Running CLI commands
@@ -111,7 +111,9 @@ uv sync
 | `vertex-claude` | `GCP_PROJECT_ID` / `GOOGLE_CLOUD_PROJECT` / `ANTHROPIC_VERTEX_PROJECT_ID` (ADC) | `monkeybot[vertex-claude]` |
 | `aws_bedrock` | `AWS_ACCESS_KEY_ID` / `AWS_PROFILE` + `AWS_REGION` | `monkeybot[bedrock]` |
 | `huggingface` | `HF_TOKEN` (or `HUGGINGFACE_API_KEY`) | `monkeybot[huggingface]` |
-| `ollama` | None required — `OLLAMA_BASE_URL` (default `http://localhost:11434`) for a non-default server | `monkeybot[ollama]` |
+| `ollama-cloud` | `OLLAMA_API_KEY` | `monkeybot[ollama]` |
+| `ollama-local` | None required — `OLLAMA_BASE_URL` (default `http://localhost:11434`). Requests send `keep_alive` 24h so prefix KV cache survives idle. | `monkeybot[ollama]` |
+| `ollama` | Legacy auto-route (key + blank URL = cloud; explicit URL wins) | `monkeybot[ollama]` |
 
 **Agent-first dependencies.** The CLI is thin — it does **not** install provider/storage extras globally. `monkeybot new` scaffolds a `pyproject.toml` with the selected provider (and any `--with` extras). Run plain `uv sync` in the agent directory. `monkeybot run` / `chat` spawn the gateway from that project's interpreter (`.venv/bin/python`, else `uv run python`), and `doctor` checks extras in that same interpreter. For a config-only tree (just `monkeybot_config/`, no `pyproject.toml`) the gateway uses the CLI's interpreter when it already has MonkeyBot 3.x (and MemPalace if memory is on). If memory is enabled and that interpreter cannot import MemPalace, `run` / `chat` provision a cached CLI-managed venv under `~/.cache/monkeybot/runtimes/` holding `monkeybot[memory]` pinned to the running core (never rewrites a `pyproject.toml`). `doctor` reuses that cache when it is already present. Otherwise extras must be installed in the CLI env (`uv tool install --with 'monkeybot[<extra>]' monkeybot-cli`).
 
@@ -158,7 +160,7 @@ Decision → config map:
 | "Run untrusted code" | `sandbox.enabled` + `SANDBOX_API_KEY` |
 | "Use specialist agents" | `subagents.personas` + `monkeybot_config/agents/*.md` |
 | "Connect external tools" | `mcp.json` (`mcpServers` object), then `validate --check-mcp` |
-| "Control cost / context size" | `model.*`, `context_curation.*` |
+| "Control cost / context size" | `model.*` |
 | "Restrict dangerous commands" | `tools.denied_patterns`, `command_allowlist.yaml` |
 | "Multiple environments" | top-level `includes:` fragments |
 

{monkeybot_cli-0.5.0 → monkeybot_cli-0.6.0}/skills/monkeybot/references/config-sections.md

@@ -2,7 +2,7 @@
 
 Deep reference for every `monkeybot.yaml` section. Load this only when a user needs to customize beyond Tier 1. The canonical, fully-commented template lives at `cli/src/monkeybot_cli/scaffold_defaults/monkeybot.example.yaml` in the monkeybot repo (copied to `monkeybot_config/monkeybot.example.yaml` when you scaffold); this file adds the **"when would I change this?"** context the comments don't.
 
-**Precedence:** env vars and `.env` win over YAML. The YAML→env mapping is `ENV_MAP` in `src/monkeybot/core/config/runtime_env.py`. If a YAML edit has no effect, check for a shadowing env var.
+**Precedence:** env vars and `.env` win over YAML for `ENV_MAP` keys. `model.*` (provider, name, temperature, max_tokens, thinking_budget, context_window, summarization_model, max_turns, cache_retention) is YAML-only — leftover `MODEL_*` env vars are ignored. The YAML→env mapping is `ENV_MAP` in `src/monkeybot/core/config/runtime_env.py`. If a YAML edit has no effect, check for a shadowing env var (except `model.*`).
 
 ---
 
@@ -34,6 +34,8 @@ Validate check ids: `paths.agent_md.exists`, `paths.skills_path.exists`, `paths.
 
 ## `model`
 
+YAML-only for provider, name, sampling, context window, summarization model, max turns, and cache retention. Leftover `MODEL_*` / `MAX_TURNS` / `CONTEXT_SUMMARIZATION_MODEL` env vars are ignored.
+
 | Field | Default | When to change |
 |---|---|---|
 | `provider` | `gemini` | Switch LLM vendor (see provider table in SKILL.md) |
@@ -41,11 +43,13 @@ Validate check ids: `paths.agent_md.exists`, `paths.skills_path.exists`, `paths.
 | `temperature` | `0.7` | Lower for deterministic output, higher for creative |
 | `max_tokens` | `60000` | Cap per-response length |
 | `thinking_budget` | `-1` | Gemini: `-1` model default, `0` off, `N` token budget. Ollama reasoning models: `-1` server default, `0` off (`reasoning_effort: none`) |
-| `context_window` | `1000000` | Summarization trigger (tokens); also drives soft-spill / `read_file` char budgets |
+| `context_window` | `1000000` | Summarization trigger (tokens); also drives soft-spill / `read_file` char budgets. **Not** Ollama `num_ctx` |
+| `keep_alive` | `24h` (ollama-local only) | How long local Ollama keeps the model (and KV prefix cache) loaded. YAML only. Set `"0"` to omit. See `docs/ollama-local.md` |
+| `num_ctx` | (unset) | Optional pinned Ollama `num_ctx`. YAML only. Omit = server default. Do not copy `context_window` |
 | `max_turns` | `1000` | Hard cap on turns per run |
-| `summarization_model` | (main model) | Cheaper model for history summarization (env `CONTEXT_SUMMARIZATION_MODEL`) |
+| `summarization_model` | (main model) | Cheaper model for history summarization (YAML-only)
 
-Validate check ids: `model.provider.supported`, `model.name.present`. Supported YAML providers: `gemini`/`vertex`, `openai`, `anthropic`, `vertex-claude`, `huggingface`, `ollama`, `aws_bedrock`, `fake`.
+Validate check ids: `model.provider.supported`, `model.name.present`. Supported YAML providers: `gemini`/`vertex`, `openai`, `anthropic`, `vertex-claude`, `huggingface`, `ollama-cloud`, `ollama-local`, `ollama`, `aws_bedrock`, `fake`.
 
 ## `gcp` / `anthropic_vertex` (non-secret identifiers)
 
@@ -71,22 +75,6 @@ Required when `memory_storage_uri` is `gcs://…` or `provider: vertex-claude` (
 | `graceful_shutdown_timeout_sec` | `5` | Allow longer drain on shutdown |
 | `cors_allow_origins` | `http://localhost:5173` | **Custom web UI** — set its origin, or `"*"` for any |
 
-## `context_curation`
-
-Trims memory injected into context. `enabled: true` by default.
-
-Recent window by default; LLM curator only when the index is token-heavy. On curator failure, falls back to the window.
-
-| Field | Default | Notes |
-|---|---|---|
-| `memory_window_lines` | `12` | Recent index lines injected; also caps curator-selected lines |
-| `memory_index_cap` | `200` | Organizer keeps this many INDEX.md entries; older rows move to `INDEX.archive.md` |
-| `memory_token_threshold` | `2000` | Call curator when estimated index tokens exceed this |
-| `curator_model` | `gemini-3-flash` | Separate small model; empty = main model |
-| `timeout_sec` | `10` | Curator call timeout |
-
-When the prompt shows fewer entries than exist, a structural confidence score triggers a `search_memory` nudge. Skill names are always shown in full in the prompt; use `list_skills` to get the skills root path.
-
 ## `memory`
 
 MemPalace capture, wake-up, and search teaching are on by default. Turn them off with `memory.enabled: false` or `MONKEYBOT_MEMORY_HOOK_ENABLED=0`. The vector stack is the optional `monkeybot[memory]` extra — omit it (and set `enabled: false`) when you do not want chromadb/onnxruntime.
@@ -176,4 +164,4 @@ Validate check: `config.includes.resolve`.
 
 ## `fake_provider`
 
-Test-only. `events_json` feeds `MODEL_PROVIDER=fake` scripted runs (env `MONKEYBOT_FAKE_PROVIDER_EVENTS`). Not for production.
+Test-only. `events_json` feeds `model.provider: fake` scripted runs (env `MONKEYBOT_FAKE_PROVIDER_EVENTS`). Not for production.

{monkeybot_cli-0.5.0 → monkeybot_cli-0.6.0}/src/monkeybot_cli/chat_local_shell.py

@@ -5,54 +5,18 @@ Output is local-only — never sent to the agent.
 
 from __future__ import annotations
 
-import os
-import signal
 import subprocess
 import sys
 import threading
 from pathlib import Path
 
-_IS_WINDOWS = sys.platform == "win32"
+from monkeybot_cli.process_tree import IS_WINDOWS, kill_process_tree, popen_kwargs_for_platform
 
 # Cap capture before TUI truncation so `!yes`-style floods cannot OOM the process.
 _MAX_CAPTURE_CHARS = 100_000
 _READ_CHUNK = 4_096
 
 
-def _popen_kwargs_for_platform() -> dict[str, object]:
-    if _IS_WINDOWS:
-        # getattr fallback: this constant only exists on Windows builds of
-        # `subprocess`, so a plain attribute access breaks importing/testing
-        # this module on POSIX even though the branch never runs there.
-        return {"creationflags": getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)}
-    return {"start_new_session": True}
-
-
-def _kill_process_tree(pid: int) -> None:
-    """Best-effort kill of the shell process group/tree.
-
-    Swallow lookup/permission races — leader exit can make killpg raise
-    ``PermissionError`` even though descendants still need a signal.
-    """
-    if _IS_WINDOWS:
-        try:
-            subprocess.run(
-                ["taskkill", "/F", "/T", "/PID", str(pid)],
-                capture_output=True,
-                check=False,
-            )
-        except OSError:
-            pass
-        return
-    try:
-        os.killpg(pid, signal.SIGKILL)
-    except (ProcessLookupError, PermissionError, OSError):
-        try:
-            os.kill(pid, signal.SIGKILL)
-        except (ProcessLookupError, PermissionError, OSError):
-            pass
-
-
 def _append_capped(chunks: list[str], total: int, data: str) -> tuple[int, bool]:
     """Append ``data`` up to the capture cap. Returns (new_total, hit_cap)."""
     remain = _MAX_CAPTURE_CHARS - total
@@ -84,7 +48,7 @@ def run_local_shell(command: str, cwd: Path, *, timeout: float = 120.0) -> tuple
         stdout=subprocess.PIPE,
         stderr=subprocess.STDOUT,
         text=True,
-        **_popen_kwargs_for_platform(),
+        **popen_kwargs_for_platform(),
     )
     assert proc.stdout is not None
 
@@ -104,7 +68,7 @@ def run_local_shell(command: str, cwd: Path, *, timeout: float = 120.0) -> tuple
                 state["total"], hit = _append_capped(chunks, state["total"], chunk)
                 if hit:
                     state["capped"] = True
-                    _kill_process_tree(proc.pid)
+                    kill_process_tree(proc.pid)
                     break
         except (ValueError, OSError):
             # stdout closed from the main thread to unblock a stuck read.
@@ -119,12 +83,12 @@ def run_local_shell(command: str, cwd: Path, *, timeout: float = 120.0) -> tuple
             proc.wait(timeout=timeout)
         except subprocess.TimeoutExpired:
             timed_out = True
-            _kill_process_tree(proc.pid)
+            kill_process_tree(proc.pid)
 
         # Shell may have exited while a descendant still holds the pipe —
         # kill the tree and close stdout so the reader cannot block forever.
         if reader.is_alive():
-            _kill_process_tree(proc.pid)
+            kill_process_tree(proc.pid)
             stop_reader.set()
             try:
                 proc.stdout.close()
@@ -139,7 +103,7 @@ def run_local_shell(command: str, cwd: Path, *, timeout: float = 120.0) -> tuple
             reader.join(timeout=0.1)
     except Exception:
         timed_out = True
-        _kill_process_tree(proc.pid)
+        kill_process_tree(proc.pid)
         stop_reader.set()
         try:
             proc.stdout.close()
@@ -149,7 +113,7 @@ def run_local_shell(command: str, cwd: Path, *, timeout: float = 120.0) -> tuple
 
     try:
         if proc.poll() is None:
-            _kill_process_tree(proc.pid)
+            kill_process_tree(proc.pid)
             try:
                 proc.wait(timeout=1)
             except Exception:

{monkeybot_cli-0.5.0 → monkeybot_cli-0.6.0}/src/monkeybot_cli/chat_session.py

@@ -229,7 +229,7 @@ class ChatSessionController:
         self.usage = UsageStore()
         self.session_id: str | None = None
         self.stream_error = False
-        self.transcript_report_dir: str | None = None
+        self.transcript_dir: str | None = None
         self._client: httpx.AsyncClient | None = None
         self._event_queue: asyncio.Queue[str | None] = asyncio.Queue()
         self._stream_task: asyncio.Task[None] | None = None
@@ -924,9 +924,9 @@ class ChatSessionController:
                 resp = await self._client.delete(f"{self.base}/sessions/{self.session_id}")
                 if resp.status_code == 200:
                     data = resp.json()
-                    report = data.get("transcript_report_dir") if isinstance(data, dict) else None
+                    report = data.get("transcript_dir") if isinstance(data, dict) else None
                     if isinstance(report, str) and report.strip():
-                        self.transcript_report_dir = report.strip()
+                        self.transcript_dir = report.strip()
             except Exception:
                 logger.warning(
                     "session DELETE on close failed session_id=%s",

{monkeybot_cli-0.5.0 → monkeybot_cli-0.6.0}/src/monkeybot_cli/chat_tui.py

@@ -1680,8 +1680,8 @@ class ChatApp(App[int]):
         src = session_dir / "transcript.ndjson"
         if not src.is_file():
             self._mount_system(
-                "No trace file found — enable transcript capture on the gateway and restart "
-                "(external gateways need MONKEYBOT_TRANSCRIPT_ENABLED=1)",
+                "No trace file found — set runtime.transcript_enabled: true in monkeybot.yaml "
+                "and restart the gateway",
                 error=True,
             )
             return
@@ -1829,10 +1829,10 @@ class ChatApp(App[int]):
     async def _close_session_and_exit(self) -> None:
         # Must not be named `_shutdown` — that shadows Textual.App._shutdown.
         await self._controller.close()
-        report_dir = getattr(self._controller, "transcript_report_dir", None)
+        report_dir = getattr(self._controller, "transcript_dir", None)
         if isinstance(report_dir, str) and report_dir:
-            self._mount_system(f"Transcript report → {report_dir}")
-            print(f"Transcript report → {report_dir}", flush=True)
+            self._mount_system(f"Transcript → {report_dir}")
+            print(f"Transcript → {report_dir}", flush=True)
         self._exit_code = 1 if self._controller.stream_error else self._exit_code
         self.exit(self._exit_code)
 

{monkeybot_cli-0.5.0 → monkeybot_cli-0.6.0}/src/monkeybot_cli/commands/chat.py

@@ -626,9 +626,9 @@ async def _plain_chat_session(
             await controller.submit(user_line)
     finally:
         await controller.close()
-        if controller.transcript_report_dir:
+        if controller.transcript_dir:
             print(
-                f"{_DIM}Transcript report → {controller.transcript_report_dir}{_RESET}",
+                f"{_DIM}Transcript → {controller.transcript_dir}{_RESET}",
                 flush=True,
             )
         await renderer.stop_io_worker()
@@ -678,7 +678,6 @@ def _spawn_gateway(config_path: Path | None, agent_root: Path, port: int) -> _Sp
         env["MONKEYBOT_CONFIG"] = str(config_path)
     env["PORT"] = str(port)
     env.setdefault("LOG_LEVEL", "error")
-    env.setdefault("MONKEYBOT_TRANSCRIPT_ENABLED", "1")
     log_file = tempfile.NamedTemporaryFile(
         mode="w+",
         prefix="monkeybot-gateway-",

{monkeybot_cli-0.5.0 → monkeybot_cli-0.6.0}/src/monkeybot_cli/commands/doctor.py

@@ -192,6 +192,146 @@ def _add_layout_checks(report: CommandReport, layout: AgentLayout) -> None:
     )
 
 
+_OLLAMA_LOCAL_DOCS = "docs/ollama-local.md"
+_OLLAMA_NUM_CTX_LARGE = 32_768
+_OLLAMA_REASONING_TAGS = ("qwen3", "gemma4", "gemma-4", "deepseek-r1", "qwq", "magistral")
+
+
+def _is_local_ollama_provider(provider: str) -> bool:
+    """True for ollama-local and legacy ``ollama`` (not ollama-cloud)."""
+    key = provider.strip().lower().replace("_", "-")
+    return key in {"ollama-local", "ollama"}
+
+
+def _looks_like_reasoning_model(model_name: str) -> bool:
+    name = model_name.lower()
+    return any(tag in name for tag in _OLLAMA_REASONING_TAGS)
+
+
+def _parse_int(raw: object) -> int | None:
+    if raw is None or raw == "":
+        return None
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return None
+
+
+def _strict_positive_int(raw: object) -> tuple[int | None, bool]:
+    """Return ``(value, invalid)``. Unset is ``(None, False)``; garbage or ``<1`` is invalid."""
+    if raw is None or raw == "":
+        return None, False
+    if isinstance(raw, bool) or not isinstance(raw, int):
+        return None, True
+    if raw < 1:
+        return None, True
+    return raw, False
+
+
+def _add_ollama_local_checks(
+    report: CommandReport,
+    *,
+    provider: str,
+    model_name: str,
+    thinking_budget: object,
+    num_ctx: object,
+) -> None:
+    """Warn on local-Ollama prefix-cache traps. Always emit the four check ids."""
+    local = _is_local_ollama_provider(provider)
+    mlx = "-mlx" in model_name.lower()
+    check(
+        report,
+        id="ollama.local.mlx_runner",
+        category="provider",
+        severity="warning",
+        passed=not mlx,
+        skip=not local,
+        message=(
+            f"model.name {model_name!r} looks like an MLX pack; prefix KV cache "
+            "often does not reuse between agent steps"
+            if mlx
+            else "model.name is not an MLX pack"
+        ),
+        field="model.name",
+        value=model_name or None,
+        remediation=(
+            f"Prefer a GGUF tag for tool-calling loops. See {_OLLAMA_LOCAL_DOCS}." if mlx else None
+        ),
+        docs=_OLLAMA_LOCAL_DOCS,
+    )
+    budget = _parse_int(thinking_budget)
+    if budget is None:
+        budget = -1
+    reasoning = _looks_like_reasoning_model(model_name)
+    thinking_on_default = budget == -1
+    check(
+        report,
+        id="ollama.local.thinking_default",
+        category="provider",
+        severity="warning",
+        passed=not thinking_on_default,
+        skip=not local or not reasoning,
+        message=(
+            "thinking_budget is -1 (server default); reasoning models generate "
+            "thinking tokens before the first visible reply"
+            if thinking_on_default
+            else f"thinking_budget is {budget}"
+        ),
+        field="model.thinking_budget",
+        value=budget,
+        remediation=(
+            f"Set thinking_budget: 0 to send reasoning_effort: none. See {_OLLAMA_LOCAL_DOCS}."
+            if thinking_on_default
+            else None
+        ),
+        docs=_OLLAMA_LOCAL_DOCS,
+    )
+    ctx, ctx_invalid = _strict_positive_int(num_ctx)
+    check(
+        report,
+        id="ollama.local.num_ctx_invalid",
+        category="provider",
+        severity="error",
+        passed=not ctx_invalid,
+        skip=not local or (ctx is None and not ctx_invalid),
+        message=(
+            f"num_ctx must be a positive integer, got {num_ctx!r}"
+            if ctx_invalid
+            else (f"num_ctx is {ctx}" if ctx is not None else "num_ctx is unset")
+        ),
+        field="model.num_ctx",
+        value=num_ctx,
+        remediation=(
+            f"Set a positive integer num_ctx (e.g. 8192), or omit it. See {_OLLAMA_LOCAL_DOCS}."
+            if ctx_invalid
+            else None
+        ),
+        docs=_OLLAMA_LOCAL_DOCS,
+    )
+    large = ctx is not None and ctx > _OLLAMA_NUM_CTX_LARGE
+    check(
+        report,
+        id="ollama.local.num_ctx_large",
+        category="provider",
+        severity="warning",
+        passed=not large,
+        skip=not local or ctx is None or ctx_invalid,
+        message=(
+            f"num_ctx {ctx} is large for a local runner; prefill will be slow"
+            if large
+            else (f"num_ctx is {ctx}" if ctx is not None else "num_ctx is unset")
+        ),
+        field="model.num_ctx",
+        value=ctx,
+        remediation=(
+            f"Pin a modest num_ctx (e.g. 8192). Do not copy context_window. See {_OLLAMA_LOCAL_DOCS}."
+            if large
+            else None
+        ),
+        docs=_OLLAMA_LOCAL_DOCS,
+    )
+
+
 def run_doctor(args: argparse.Namespace) -> int:
     cwd = Path(args.cwd).expanduser().resolve() if args.cwd else None
     config_path = resolve_config(args.config, cwd=cwd)
@@ -324,6 +464,19 @@ def run_doctor(args: argparse.Namespace) -> int:
             skip=True,
         )
 
+    thinking_raw = model.get("thinking_budget") if isinstance(model, dict) else None
+    if thinking_raw is None:
+        thinking_raw = "-1"
+    num_ctx_raw = model.get("num_ctx") if isinstance(model, dict) else None
+    model_name = str(model.get("name", "")).strip() if isinstance(model, dict) else ""
+    _add_ollama_local_checks(
+        report,
+        provider=provider,
+        model_name=model_name,
+        thinking_budget=thinking_raw,
+        num_ctx=num_ctx_raw,
+    )
+
     runtime_cfg = doc.get("runtime") if isinstance(doc.get("runtime"), dict) else {}
     port = int(runtime_cfg.get("port", 8080)) if isinstance(runtime_cfg, dict) else 8080
     free = _port_free(port)

monkeybot_cli-0.6.0/src/monkeybot_cli/commands/run_cmd.py

@@ -0,0 +1,197 @@
+"""monkeybot run — launch the SSE gateway as a subprocess."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import signal
+import subprocess
+import sys
+import time
+from collections.abc import Callable
+from pathlib import Path
+from types import FrameType
+from typing import Any
+
+from monkeybot_cli.config_resolve import (
+    load_agent_dotenv,
+    load_config_doc,
+    resolve_agent_root,
+    resolve_config,
+)
+from monkeybot_cli.opensandbox_lifecycle import (
+    ensure_opensandbox_for_agent,
+    is_sandbox_enabled,
+    server_url_from_config,
+)
+from monkeybot_cli.process_tree import IS_WINDOWS, kill_process_tree, popen_kwargs_for_platform
+from monkeybot_cli.runtime_python import gateway_argv, prepare_runtime_python
+
+_SHUTDOWN_TIMEOUT_SECS = 5.0
+_KILL_TIMEOUT_SECS = 1.0
+_Handler = Callable[[int, FrameType | None], Any] | int | None
+
+
+def _cli_exit_status(rc: int | None, received: int | None) -> int:
+    """Map a child ``wait()`` status to a CLI exit code.
+
+    ``wait()`` returns a negative signal number when the child dies from a
+    signal; ``SystemExit(-15)`` becomes shell status 241. Unix convention is
+    ``128 + signal`` (143 for SIGTERM, 130 for SIGINT).
+
+    When the shim received SIGINT, return 130 even if the child exited 0 —
+    that matches the conventional Ctrl-C exit status.
+    """
+    if received == signal.SIGINT:
+        return 130
+    if rc is None:
+        return 1
+    if rc < 0:
+        return 128 + (-rc)
+    return rc
+
+
+def _signal_process_group(proc: subprocess.Popen[bytes], signum: int) -> None:
+    if proc.poll() is not None:
+        return
+    if IS_WINDOWS:
+        try:
+            proc.send_signal(signum)
+        except OSError as exc:
+            print(f"failed to signal gateway: {exc}", file=sys.stderr)
+        return
+    try:
+        os.killpg(proc.pid, signum)
+        return
+    except ProcessLookupError:
+        return
+    except OSError as exc:
+        try:
+            proc.send_signal(signum)
+        except OSError:
+            print(f"failed to signal gateway: {exc}", file=sys.stderr)
+
+
+def run_gateway_process(
+    cmd: list[str],
+    *,
+    env: dict[str, str],
+    cwd: Path,
+    shutdown_timeout: float = _SHUTDOWN_TIMEOUT_SECS,
+    kill_timeout: float = _KILL_TIMEOUT_SECS,
+) -> int:
+    """Start the gateway and forward stop signals to its process group.
+
+    Electron sends SIGTERM only to this CLI shim. ``subprocess.run`` dies on
+    that signal and leaves uvicorn holding the port. On POSIX the child is
+    started in a new session so SIGTERM/SIGINT reach the whole tree (``uv run``
+    plus the gateway grandchild), then escalate to SIGKILL if it ignores the
+    signal for ``shutdown_timeout`` seconds.
+
+    ``start_new_session`` also detaches the gateway from the terminal's
+    foreground process group (stdin reads would raise SIGTTIN). That is fine
+    for uvicorn today and required for ``killpg``.
+
+    On Windows, ``send_signal(SIGTERM)`` only terminates the immediate child;
+    grandchildren may still be orphaned.
+
+    Interactive Ctrl-C already hits the foreground process group; forwarding
+    SIGINT matters here because the child is in a new session and would
+    otherwise keep running.
+    """
+    received: int | None = None
+    proc: subprocess.Popen[bytes] | None = None
+    signal_forwarded = False
+    deadline: float | None = None
+
+    def _forward(signum: int, _frame: object | None) -> None:
+        nonlocal received, signal_forwarded, deadline
+        if received is None:
+            received = signum
+        if proc is not None:
+            _signal_process_group(proc, signum)
+            signal_forwarded = True
+            if deadline is None:
+                deadline = time.monotonic() + shutdown_timeout
+
+    restored: dict[int, _Handler] = {}
+    forwarded = [signal.SIGINT, signal.SIGTERM]
+    if not IS_WINDOWS:
+        forwarded.append(signal.SIGHUP)
+    for sig in forwarded:
+        try:
+            restored[sig] = signal.signal(sig, _forward)
+        except (ValueError, OSError) as exc:
+            print(f"failed to install {sig.name} handler: {exc}", file=sys.stderr)
+    try:
+        proc = subprocess.Popen(
+            cmd,
+            env=env,
+            cwd=cwd,
+            **popen_kwargs_for_platform(),
+        )
+        if received is not None and not signal_forwarded:
+            _signal_process_group(proc, received)
+            if deadline is None:
+                deadline = time.monotonic() + shutdown_timeout
+        while True:
+            try:
+                rc = proc.wait(timeout=0.25)
+            except subprocess.TimeoutExpired:
+                if deadline is None or time.monotonic() < deadline:
+                    continue
+                print(
+                    "gateway did not exit after signal; killing process tree",
+                    file=sys.stderr,
+                )
+                kill_process_tree(proc.pid)
+                try:
+                    proc.wait(timeout=kill_timeout)
+                except subprocess.TimeoutExpired:
+                    print("gateway still running after kill", file=sys.stderr)
+                rc = proc.returncode
+            return _cli_exit_status(rc, received)
+    finally:
+        for sig, handler in restored.items():
+            try:
+                signal.signal(sig, handler)
+            except (ValueError, OSError) as exc:
+                print(f"failed to restore {sig.name} handler: {exc}", file=sys.stderr)
+
+
+def run_run(args: argparse.Namespace) -> int:
+    cwd = Path(args.cwd).expanduser().resolve() if args.cwd else None
+    config_path = resolve_config(args.config, cwd=cwd)
+    load_agent_dotenv(cwd=cwd, config_path=config_path)
+    env = os.environ.copy()
+    if config_path is not None:
+        env["MONKEYBOT_CONFIG"] = str(config_path)
+    if args.port:
+        env["PORT"] = str(args.port)
+    # --cwd intentionally pins the subprocess and runtime directory. Without
+    # it, an explicit config determines the agent root.
+    agent_root = resolve_agent_root(cwd=cwd, config_path=config_path)
+    if config_path is not None:
+        _, cfg_doc = load_config_doc(config_path)
+        if is_sandbox_enabled(cfg_doc):
+            if not ensure_opensandbox_for_agent(
+                agent_root,
+                server_url=server_url_from_config(cfg_doc),
+                # Fail fast: Mac app health-checks the gateway immediately.
+                docker_wait_secs=2.0,
+            ):
+                print(
+                    "Continuing without a healthy OpenSandbox — run_command may fail.",
+                    flush=True,
+                )
+    runtime = prepare_runtime_python(agent_root, config_path)
+    cmd = gateway_argv(runtime)
+    return run_gateway_process(cmd, env=env, cwd=agent_root)
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    p = subparsers.add_parser("run", help="Start the monkeybot SSE gateway")
+    p.add_argument("--config", help="Path to monkeybot.yaml (sets MONKEYBOT_CONFIG)")
+    p.add_argument("--port", type=int, help="Listen port (sets PORT)")
+    p.add_argument("--cwd", help="Working directory for the gateway process")
+    p.set_defaults(func=run_run)