cfdpilot 0.1.11__tar.gz

cfdpilot-0.1.11/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.env
+*.bak

cfdpilot-0.1.11/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: cfdpilot
+Version: 0.1.11
+Summary: AI agent for OpenFOAM — diagnose, fix, and relaunch cases from your terminal
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CFDpilot
+
+**An AI agent for OpenFOAM — in your terminal.**
+
+CFDpilot reads your OpenFOAM case directly from disk, diagnoses why it diverges or
+gives wrong physics, proposes the exact fix as a colored diff, and — once you confirm —
+patches the files and reruns the solver. No ZIP upload, no browser. It runs where you
+already work: your laptop, your workstation, or an HPC node over SSH.
+
+```bash
+pip install cfdpilot
+cfdpilot login                 # authenticate once
+cd path/to/your/case && cfdpilot
+```
+
+Then just ask, in plain English:
+
+> *"Why won't my rhoSimpleFoam case converge?"*
+
+The agent maps your case, reads `fvSchemes`, `fvSolution`, your boundary conditions and
+solver log, reasons from the actual numbers (Courant number, residuals, turbulence wall
+treatment, scheme/switch consistency), and reports the bugs ranked by impact — with the
+exact fix for each. Nothing is changed without showing you a diff first, and every patch
+makes a `.bak` backup.
+
+## What it checks
+
+Boundary-condition consistency, turbulence wall treatment (low-Re vs high-Re), Courant
+number and time-step control, relaxation factors, discretisation schemes, solver-mode
+switches (e.g. `transonic`), and solver/turbulence-model compatibility — across
+incompressible, compressible, multiphase (VoF) and heat-transfer solvers.
+
+## Requirements
+
+- Python 3.10+
+- An OpenFOAM case directory (Foundation or ESI). OpenFOAM itself can run natively or in
+  Docker; the agent will use it to run the solver when you ask.
+
+## Access
+
+CFDpilot is in **free early access** for the first engineers. Run `cfdpilot login` to get
+started, or request access at [cfdpilot.com](https://cfdpilot.com).

cfdpilot-0.1.11/README.md

@@ -0,0 +1,42 @@
+# CFDpilot
+
+**An AI agent for OpenFOAM — in your terminal.**
+
+CFDpilot reads your OpenFOAM case directly from disk, diagnoses why it diverges or
+gives wrong physics, proposes the exact fix as a colored diff, and — once you confirm —
+patches the files and reruns the solver. No ZIP upload, no browser. It runs where you
+already work: your laptop, your workstation, or an HPC node over SSH.
+
+```bash
+pip install cfdpilot
+cfdpilot login                 # authenticate once
+cd path/to/your/case && cfdpilot
+```
+
+Then just ask, in plain English:
+
+> *"Why won't my rhoSimpleFoam case converge?"*
+
+The agent maps your case, reads `fvSchemes`, `fvSolution`, your boundary conditions and
+solver log, reasons from the actual numbers (Courant number, residuals, turbulence wall
+treatment, scheme/switch consistency), and reports the bugs ranked by impact — with the
+exact fix for each. Nothing is changed without showing you a diff first, and every patch
+makes a `.bak` backup.
+
+## What it checks
+
+Boundary-condition consistency, turbulence wall treatment (low-Re vs high-Re), Courant
+number and time-step control, relaxation factors, discretisation schemes, solver-mode
+switches (e.g. `transonic`), and solver/turbulence-model compatibility — across
+incompressible, compressible, multiphase (VoF) and heat-transfer solvers.
+
+## Requirements
+
+- Python 3.10+
+- An OpenFOAM case directory (Foundation or ESI). OpenFOAM itself can run natively or in
+  Docker; the agent will use it to run the solver when you ask.
+
+## Access
+
+CFDpilot is in **free early access** for the first engineers. Run `cfdpilot login` to get
+started, or request access at [cfdpilot.com](https://cfdpilot.com).

cfdpilot-0.1.11/cfdpilot/agent.py

@@ -0,0 +1,331 @@
+import json
+from cfdpilot.client import CFDPilotClient
+from cfdpilot.tools.filesystem import read_file, list_dir
+from cfdpilot.tools.log_parser import parse_log
+from cfdpilot.tools.patcher import patch_dict, generate_diff
+from cfdpilot.tools.runner import run_command, run_solver
+
+MAX_ATTEMPTS = 3
+MAX_TOOL_ROUNDS = 18  # per user request: cap agentic tool-rounds → force a final answer instead of looping forever (prevents the "fix and stabilize" runaway burn)
+
+TOOL_SCHEMAS = [
+    {
+        "name": "read_file",
+        "description": "Read a file from the OpenFOAM case directory",
+        "input_schema": {
+            "type": "object",
+            "properties": {"path": {"type": "string"}},
+            "required": ["path"]
+        }
+    },
+    {
+        "name": "list_dir",
+        "description": "List files in a directory",
+        "input_schema": {
+            "type": "object",
+            "properties": {"path": {"type": "string", "default": "."}},
+            "required": []
+        }
+    },
+    {
+        "name": "parse_log",
+        "description": "Parse an OpenFOAM log file. Returns structured JSON with residuals, Co number, divergence info.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"log_path": {"type": "string", "description": "Path to log file, or omit to auto-detect"}},
+            "required": []
+        }
+    },
+    {
+        "name": "run_command",
+        "description": "Run an OpenFOAM command (blockMesh, checkMesh, foamDictionary, etc.). NOT for the main solver.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"cmd": {"type": "string"}},
+            "required": ["cmd"]
+        }
+    },
+    {
+        "name": "run_solver",
+        "description": "Launch the OpenFOAM solver and stream residuals. Auto-stops on convergence or divergence.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "solver": {"type": "string"},
+                "max_iterations": {"type": "integer"}
+            },
+            "required": ["solver"]
+        }
+    },
+    {
+        "name": "show_diff",
+        "description": "Show a colored diff of proposed changes to a file. ALWAYS call this before patch_dict.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "file_path": {"type": "string"},
+                "proposed_content": {"type": "string"}
+            },
+            "required": ["file_path", "proposed_content"]
+        }
+    },
+    {
+        "name": "patch_dict",
+        "description": "Apply confirmed changes to an OpenFOAM dict file. Creates .bak backup automatically.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "file_path": {"type": "string"},
+                "changes": {"type": "object", "description": "key-value pairs to update"}
+            },
+            "required": ["file_path", "changes"]
+        }
+    },
+    {
+        "name": "search_knowledge",
+        "description": "Search the CFDpilot knowledge base: 1,000+ CFD-Online threads + OpenFOAM user guide. Use when you need community experience or documentation on a specific OF topic.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"query": {"type": "string", "description": "What to search for, e.g. 'GAMG divergence kOmegaSST' or 'nOuterCorrectors pimpleFoam'"}},
+            "required": ["query"]
+        }
+    },
+]
+
+
+def _dispatch_tool(name: str, inputs: dict, cwd: str, display, client=None) -> str:
+    """Execute a tool call and return result as JSON string."""
+    try:
+        if name == "read_file":
+            result = read_file(inputs["path"], cwd=cwd)
+            return json.dumps(result)
+
+        elif name == "list_dir":
+            result = list_dir(inputs.get("path", "."), cwd=cwd)
+            return json.dumps(result)
+
+        elif name == "parse_log":
+            result = parse_log(inputs.get("log_path"), cwd=cwd)
+            return json.dumps(result)
+
+        elif name == "run_command":
+            display.print_action(f"Running: {inputs['cmd']}")
+            result = run_command(inputs["cmd"], cwd=cwd)
+            return json.dumps(result)
+
+        elif name == "run_solver":
+            display.print_action(f"Launching {inputs['solver']}...")
+            result = run_solver(
+                inputs["solver"],
+                cwd=cwd,
+                max_iterations=inputs.get("max_iterations"),
+                on_line=display.print_solver_line
+            )
+            return json.dumps(result)
+
+        elif name == "show_diff":
+            diff = generate_diff(inputs["file_path"], inputs["proposed_content"])
+            display.print_diff(diff)
+            confirmed = display.confirm("Apply changes?")
+            return json.dumps({"diff": diff, "confirmed": confirmed})
+
+        elif name == "patch_dict":
+            display.print_action(f"Patching {inputs['file_path']}")
+            try:
+                result = patch_dict(inputs["file_path"], inputs["changes"])
+                display.print_action(f"Backup saved → {result['backup']}")
+                return json.dumps(result)
+            except FileNotFoundError as e:
+                return json.dumps({"success": False, "error": str(e)})
+
+        elif name == "search_knowledge":
+            query = inputs["query"]
+            display.print_action(f"Searching knowledge base: {query}")
+            results = client.search(query) if client else []
+            return json.dumps({"results": results, "count": len(results)})
+
+        return json.dumps({"error": f"Unknown tool: {name}"})
+
+    except KeyError as e:
+        return json.dumps({"error": f"Missing required input: {e}"})
+    except Exception as e:
+        return json.dumps({"error": f"Tool error: {type(e).__name__}: {e}"})
+
+
+SESSION_TOKEN_CAP = 250_000
+
+
+def _build_case_context(cwd: str, case_info: dict) -> str:
+    """Build a context block injected as the first user message."""
+    import os
+    lines = [f"Working directory: {cwd}"]
+    if case_info.get("flat_structure"):
+        files = ", ".join(case_info.get("fields", [])) or "unknown"
+        lines.append("Structure: FLAT (files dumped in one directory — no 0/constant/system hierarchy)")
+        lines.append(f"Files present: {files}")
+        lines.append("Note: read files directly by name (e.g. read_file('U'), read_file('fvSchemes'))")
+    else:
+        lines.append("Structure: standard OpenFOAM (0/ constant/ system/)")
+    if case_info.get("solver") and case_info["solver"] != "unknown":
+        lines.append(f"Solver: {case_info['solver']}")
+    if case_info.get("turbulence_model") and case_info["turbulence_model"] != "unknown":
+        lines.append(f"Turbulence: {case_info['turbulence_model']}")
+    if case_info.get("log_file"):
+        lines.append(f"Log file: {case_info['log_file']}")
+    else:
+        lines.append("Log file: none found")
+    return "\n".join(lines)
+
+
+def run_agent_loop(token: str, cwd: str, display, case_info: dict = None) -> None:
+    """Main conversation loop. Runs until user exits."""
+    client = CFDPilotClient(token)
+    messages = []
+    session_tokens = 0
+
+    # Inject case context as a silent system message (not shown to user)
+    if case_info:
+        ctx = _build_case_context(cwd, case_info)
+        messages.append({
+            "role": "user",
+            "content": f"[CASE CONTEXT — read this before answering anything]\n{ctx}"
+        })
+        messages.append({
+            "role": "assistant",
+            "content": [{"type": "text", "text": "Case context noted. Ready."}]
+        })
+
+    display.print_welcome()
+
+    while True:
+        try:
+            user_input = display.get_input()
+        except (KeyboardInterrupt, EOFError):
+            display.print_goodbye()
+            break
+
+        if user_input.lower() in ("exit", "quit", "q"):
+            display.print_goodbye()
+            break
+
+        if not user_input.strip():
+            continue
+
+        messages.append({"role": "user", "content": user_input})
+        attempt_count = 0  # Reset per user turn
+        tool_rounds = 0    # Reset per user turn — caps the agentic loop
+
+        # Agentic inner loop: keep going until no more tool calls
+        while True:
+            if session_tokens >= SESSION_TOKEN_CAP:
+                display.print_error(
+                    f"Session limit reached ({session_tokens:,} tokens). "
+                    "Start a new session: cfdpilot"
+                )
+                return
+
+            try:
+                with display.thinking():
+                    response = client.chat(messages, TOOL_SCHEMAS)
+            except RuntimeError as e:
+                display.print_error(str(e))
+                break
+
+            usage = response.get("usage", {})
+            # Count only genuinely NEW tokens. cache_read/cache_creation are the SAME
+            # context re-read across the many agentic sub-calls — counting them blew the
+            # cap after ~3 prompts ("session times out"). Cost is capped server-side anyway.
+            session_tokens += (
+                usage.get("input_tokens", 0)
+                + usage.get("output_tokens", 0)
+            )
+
+            content = response.get("content", [])
+            stop_reason = response.get("stop_reason", "end_turn")
+            credits = response.get("credits")
+
+            # Display text blocks
+            for block in content:
+                if block.get("type") == "text":
+                    display.print_text(block["text"])
+
+            # Add assistant turn to history
+            messages.append({"role": "assistant", "content": content})
+
+            # No tool calls → turn done
+            if stop_reason != "tool_use":
+                display.print_credits(credits)
+                break
+
+            # Extract and execute tool calls
+            tool_results = []
+            stuck = False
+            for block in content:
+                if block.get("type") != "tool_use":
+                    continue
+
+                tool_name = block["name"]
+                tool_inputs = block.get("input", {})
+                tool_id = block["id"]
+
+                display.print_action(f"● {tool_name}...")
+
+                # STUCK tracking
+                if tool_name == "patch_dict":
+                    attempt_count += 1
+                    if attempt_count > MAX_ATTEMPTS:
+                        display.print_stuck(attempt_count)
+                        tool_results.append({
+                            "type": "tool_result",
+                            "tool_use_id": tool_id,
+                            "content": json.dumps({"error": "MAX_ATTEMPTS_REACHED"})
+                        })
+                        stuck = True
+                        continue
+
+                result = _dispatch_tool(tool_name, tool_inputs, cwd, display, client)
+                tool_results.append({
+                    "type": "tool_result",
+                    "tool_use_id": tool_id,
+                    "content": result  # full result sent to model this turn
+                })
+
+            # Truncate tool results before storing in history to prevent context bloat.
+            # The model already processed the full content this turn.
+            MAX_TOOL_RESULT_CHARS = 1500
+            history_tool_results = []
+            for tr in tool_results:
+                content = tr["content"]
+                if len(content) > MAX_TOOL_RESULT_CHARS:
+                    content = content[:MAX_TOOL_RESULT_CHARS] + "…[truncated]"
+                history_tool_results.append({**tr, "content": content})
+            tool_rounds += 1
+            cap_hit = tool_rounds >= MAX_TOOL_ROUNDS
+            if cap_hit and history_tool_results:
+                # Inject the wrap-up instruction INTO the last tool_result (stays one user turn,
+                # satisfies the API's tool_result requirement) rather than as a 2nd user message.
+                history_tool_results[-1] = {
+                    **history_tool_results[-1],
+                    "content": history_tool_results[-1]["content"]
+                    + "\n\n[Step limit reached for this request — do NOT request more tools. "
+                      "Give your best final answer now: confirmed issues + exact fixes, and note anything still unresolved.]"
+                }
+            messages.append({"role": "user", "content": history_tool_results})
+
+            if stuck:
+                break
+
+            if cap_hit:
+                display.print_action(f"Step limit ({MAX_TOOL_ROUNDS} tool rounds) reached — wrapping up with findings so far.")
+                try:
+                    with display.thinking():
+                        final = client.chat(messages, [])  # no tools → model must answer in text
+                except RuntimeError as e:
+                    display.print_error(str(e))
+                    break
+                for fb in final.get("content", []):
+                    if fb.get("type") == "text":
+                        display.print_text(fb["text"])
+                messages.append({"role": "assistant", "content": final.get("content", [])})
+                display.print_credits(final.get("credits"))
+                break

cfdpilot-0.1.11/cfdpilot/auth.py

@@ -0,0 +1,57 @@
+import json
+import time
+import httpx
+from pathlib import Path
+
+TOKEN_PATH = Path.home() / ".cfdpilot" / "config"
+API_BASE = "https://cfdpilot.com"
+POLL_INTERVAL = 2
+POLL_TIMEOUT = 600
+
+
+def save_token(token: str) -> None:
+    TOKEN_PATH.parent.mkdir(parents=True, exist_ok=True)
+    TOKEN_PATH.write_text(json.dumps({"token": token}))
+    TOKEN_PATH.chmod(0o600)
+
+
+def load_token() -> str | None:
+    if not TOKEN_PATH.exists():
+        return None
+    try:
+        return json.loads(TOKEN_PATH.read_text()).get("token")
+    except Exception:
+        return None
+
+
+def device_login() -> str:
+    """Run device flow. Blocks until authorized or timeout."""
+    try:
+        with httpx.Client(timeout=10) as client:
+            resp = client.post(f"{API_BASE}/device/code")
+            resp.raise_for_status()
+            data = resp.json()
+    except Exception as e:
+        raise ConnectionError(f"Could not reach cfdpilot.com: {e}") from e
+
+    code = data["code"]
+    url = data["url"]
+    print(f"\n  Open this URL in your browser:\n  {url}\n")
+    print("  Waiting for authentication", end="", flush=True)
+
+    deadline = time.time() + POLL_TIMEOUT
+    with httpx.Client() as client:
+        while time.time() < deadline:
+            time.sleep(POLL_INTERVAL)
+            print(".", end="", flush=True)
+            try:
+                resp = client.get(f"{API_BASE}/device/poll/{code}")
+                if resp.status_code == 200:
+                    data = resp.json()
+                    if data["status"] == "authorized":
+                        print(" ✓")
+                        return data["token"]
+            except Exception:
+                continue
+
+    raise TimeoutError("Authentication timed out. Run `cfdpilot login` again.")

cfdpilot-0.1.11/cfdpilot/case_detector.py

@@ -0,0 +1,104 @@
+import re
+from pathlib import Path
+from cfdpilot.tools.log_parser import _find_log
+
+SOLVER_PATTERN = re.compile(r"application\s+(\w+);")
+TURBULENCE_PATTERN = re.compile(r"RASModel\s+(\w+);|LESModel\s+(\w+);|model\s+(\w+);")
+DELTA_T_PATTERN = re.compile(r"deltaT\s+([\d.eE+-]+);")
+END_TIME_PATTERN = re.compile(r"endTime\s+([\d.eE+-]+);")
+
+# OF11+ uses a generic runner (`application foamRun;`) with the real physics solver
+# in the `solver` entry (e.g. `solver incompressibleVoF;`). Report both so the agent
+# knows the physics (VoF/compressible/…) AND that the launch command is still foamRun.
+SOLVER_MODULE_PATTERN = re.compile(r"^\s*solver\s+(\w+);", re.MULTILINE)
+_GENERIC_RUNNERS = {"foamRun", "foamMultiRun"}
+
+
+def _detect_solver(ctrl: str) -> str:
+    m = SOLVER_PATTERN.search(ctrl)
+    app = m.group(1) if m else None
+    if app in _GENERIC_RUNNERS:
+        sm = SOLVER_MODULE_PATTERN.search(ctrl)
+        if sm:
+            return f"{app} ({sm.group(1)})"
+    return app or "unknown"
+
+
+_OF_FLAT_MARKERS = {"controlDict", "fvSchemes", "fvSolution", "turbulenceProperties", "momentumTransport"}
+_OF_BC_FILES = {"U", "p", "T", "k", "omega", "epsilon", "nut", "alphat", "nuTilda", "p_rgh"}
+
+
+def detect_case(cwd: str) -> dict:
+    base = Path(cwd)
+    required = [base / "system" / "controlDict", base / "constant", base / "0"]
+
+    # Standard OF structure
+    if all(p.exists() for p in required):
+        pass  # proceed below
+    else:
+        # Flat structure: files dumped in one directory (forum thread, shared files)
+        flat_files = {f.name for f in base.iterdir() if f.is_file()}
+        has_markers = bool(flat_files & _OF_FLAT_MARKERS)
+        has_bc = bool(flat_files & _OF_BC_FILES)
+        if not (has_markers or has_bc):
+            return {"is_of_case": False}
+        # Flat case detected — build result directly
+        result = {"is_of_case": True, "cwd": cwd, "flat_structure": True}
+        ctrl_path = base / "controlDict"
+        if ctrl_path.exists():
+            ctrl = ctrl_path.read_text(errors="replace")
+            result["solver"] = _detect_solver(ctrl)
+            m = DELTA_T_PATTERN.search(ctrl)
+            result["deltaT"] = float(m.group(1)) if m else None
+            m = END_TIME_PATTERN.search(ctrl)
+            result["endTime"] = float(m.group(1)) if m else None
+        else:
+            result["solver"] = "unknown"
+        for turb_name in ("turbulenceProperties", "momentumTransport"):
+            turb_path = base / turb_name
+            if turb_path.exists():
+                turb = turb_path.read_text(errors="replace")
+                m = TURBULENCE_PATTERN.search(turb)
+                result["turbulence_model"] = next((g for g in m.groups() if g), "unknown") if m else "unknown"
+                result["simulation_type"] = "LES" if "LESModel" in turb else "RAS"
+                break
+        else:
+            result["turbulence_model"] = "unknown"
+        result["mesh_type"] = "unknown"
+        result["log_file"] = None
+        result["fields"] = sorted(flat_files & _OF_BC_FILES)
+        return result
+
+    result = {"is_of_case": True, "cwd": cwd}
+
+    ctrl = (base / "system" / "controlDict").read_text(errors="replace")
+    result["solver"] = _detect_solver(ctrl)
+
+    m = DELTA_T_PATTERN.search(ctrl)
+    result["deltaT"] = float(m.group(1)) if m else None
+
+    m = END_TIME_PATTERN.search(ctrl)
+    result["endTime"] = float(m.group(1)) if m else None
+
+    turb_file = base / "constant" / "turbulenceProperties"
+    if not turb_file.exists():
+        turb_file = base / "constant" / "momentumTransport"
+    result["turbulence_model"] = "unknown"
+    if turb_file.exists():
+        turb = turb_file.read_text(errors="replace")
+        m = TURBULENCE_PATTERN.search(turb)
+        if m:
+            result["turbulence_model"] = next(g for g in m.groups() if g)
+        result["simulation_type"] = "LES" if "LESModel" in turb else "RAS"
+
+    result["mesh_type"] = "blockMesh"
+    if (base / "system" / "snappyHexMeshDict").exists():
+        result["mesh_type"] = "snappyHexMesh"
+
+    log = _find_log(cwd)
+    result["log_file"] = str(log) if log else None
+
+    fields = list((base / "0").iterdir())
+    result["fields"] = [f.name for f in fields if f.is_file()]
+
+    return result

cfdpilot-0.1.11/cfdpilot/client.py

@@ -0,0 +1,65 @@
+import json
+import uuid
+import httpx
+
+API_BASE = "https://cfdpilot.com"
+
+
+class CFDPilotClient:
+    def __init__(self, token: str):
+        self.token = token
+        self.session_id = str(uuid.uuid4())
+        self.headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        }
+
+    def search(self, query: str) -> list[dict]:
+        """GET /agent/search — query the RAG knowledge base."""
+        try:
+            with httpx.Client(timeout=30) as client:
+                response = client.get(
+                    f"{API_BASE}/agent/search",
+                    headers=self.headers,
+                    params={"query": query},
+                )
+                response.raise_for_status()
+                return response.json().get("results", [])
+        except Exception:
+            return []
+
+    def chat(self, messages: list[dict], tools: list[dict]) -> dict:
+        """POST to /agent/chat, return the response dict."""
+        try:
+            with httpx.Client(timeout=120) as client:
+                response = client.post(
+                    f"{API_BASE}/agent/chat",
+                    headers=self.headers,
+                    json={"messages": messages, "tools": tools, "session_id": self.session_id},
+                )
+                if response.status_code in (401, 402, 403, 429):
+                    try:
+                        detail = response.json().get("detail")
+                    except Exception:
+                        detail = None
+                    raise RuntimeError(detail or "No beta access yet — email rayan@cfdpilot.com")
+                response.raise_for_status()
+                return response.json()
+        except httpx.TimeoutException:
+            raise RuntimeError("Request timed out. The backend may be overloaded.")
+        except httpx.HTTPStatusError as e:
+            raise RuntimeError(f"Backend error: HTTP {e.response.status_code}")
+        except httpx.NetworkError as e:
+            raise RuntimeError(f"Network error: {e}")
+
+    def report_error(self, error: str, tb: str) -> None:
+        """Best-effort: report a CLI crash to the backend so it's logged. Never raises."""
+        try:
+            with httpx.Client(timeout=10) as client:
+                client.post(
+                    f"{API_BASE}/agent/error",
+                    headers=self.headers,
+                    json={"session_id": self.session_id, "error": error, "traceback": tb},
+                )
+        except Exception:
+            pass