opencommand 0.1.0__tar.gz

opencommand-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.3
+Name: opencommand
+Version: 0.1.0
+Summary: Local-first swarm agent framework: a Commander plans and dispatches a swarm of Workers that research, code, test, and interactively drive the computer to complete long-horizon codebase goals.
+Author: DSiENT
+Author-email: DSiENT <w.caskey7@gmail.com>
+Requires-Dist: asciimatics>=1.15.0
+Requires-Dist: click>=8.4.2
+Requires-Dist: playwright>=1.61.0
+Requires-Dist: pyautogui>=0.9.54
+Requires-Dist: pynput>=1.8.2
+Requires-Dist: requests>=2.34.2
+Requires-Dist: mss>=9.0.0
+Requires-Dist: pillow>=11.0.0
+Requires-Dist: llama-cpp-python>=0.3.33
+Requires-Dist: watchdog>=6.0.0
+Requires-Dist: ntfy>=2.7.1
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/D5-Interactive/OpenCommand
+Project-URL: Repository, https://github.com/D5-Interactive/OpenCommand
+Description-Content-Type: text/markdown
+
+# OpenCommand
+
+Local-first swarm agent framework. A **Commander** model plans and dispatches a
+swarm of **Workers** that research, code, test, and interactively drive the
+computer (mouse, keyboard, screen) to complete long-horizon codebase goals.
+
+Everything runs **embedded** — models are GGUF files loaded directly with
+`llama-cpp-python` (no API servers, no network at runtime). Designed for
+**Python 3.14** (free-threaded).
+
+## Install
+
+```bash
+# Run without installing (ephemeral):
+uv tool run opencommand --help
+
+# Or install globally:
+uv tool install opencommand
+playwright install   # optional, for the playwright tool
+```
+
+> **Note:** the `llama-cpp-python` prebuilt CPU wheel may crash on older CPUs
+> (illegal-instruction). If so, rebuild from source with AVX2:
+> ```bat
+> call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
+> set CMAKE_ARGS=-DGGML_AVX2=ON
+> uv pip install --no-binary llama-cpp-python --no-cache llama-cpp-python
+> ```
+
+## Usage
+
+```bash
+opencommand models list                 # list built-in embedded models
+opencommand models pull all             # download GGUF models into ./models
+opencommand run "Add unit tests for the engine module."
+opencommand run "Build a Panda3D FPS" --pipeline advanced --verify "uv run pytest -q"
+opencommand tui                         # live swarm dashboard
+opencommand cron add healthcheck "every 1h" "echo ok"
+```
+
+## Built-in models
+
+| Role          | Model                                  |
+|---------------|----------------------------------------|
+| commander     | `deepreinforce-ai/Ornith-1.0-9B-GGUF`  |
+| worker        | `unsloth/Qwen3-4B-Instruct-2507-GGUF`  |
+| vision        | `unsloth/Qwen3-VL-4B-Instruct-GGUF`    |
+| vision_small  | `openbmb/MiniCPM-V-4.6-gguf`           |
+
+## Links
+
+- `DESIGN.md` — full architecture & research notes
+- `TODO.md` — roadmap tracker
+ 

opencommand-0.1.0/README.md

@@ -0,0 +1,54 @@
+# OpenCommand
+
+Local-first swarm agent framework. A **Commander** model plans and dispatches a
+swarm of **Workers** that research, code, test, and interactively drive the
+computer (mouse, keyboard, screen) to complete long-horizon codebase goals.
+
+Everything runs **embedded** — models are GGUF files loaded directly with
+`llama-cpp-python` (no API servers, no network at runtime). Designed for
+**Python 3.14** (free-threaded).
+
+## Install
+
+```bash
+# Run without installing (ephemeral):
+uv tool run opencommand --help
+
+# Or install globally:
+uv tool install opencommand
+playwright install   # optional, for the playwright tool
+```
+
+> **Note:** the `llama-cpp-python` prebuilt CPU wheel may crash on older CPUs
+> (illegal-instruction). If so, rebuild from source with AVX2:
+> ```bat
+> call "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvars64.bat"
+> set CMAKE_ARGS=-DGGML_AVX2=ON
+> uv pip install --no-binary llama-cpp-python --no-cache llama-cpp-python
+> ```
+
+## Usage
+
+```bash
+opencommand models list                 # list built-in embedded models
+opencommand models pull all             # download GGUF models into ./models
+opencommand run "Add unit tests for the engine module."
+opencommand run "Build a Panda3D FPS" --pipeline advanced --verify "uv run pytest -q"
+opencommand tui                         # live swarm dashboard
+opencommand cron add healthcheck "every 1h" "echo ok"
+```
+
+## Built-in models
+
+| Role          | Model                                  |
+|---------------|----------------------------------------|
+| commander     | `deepreinforce-ai/Ornith-1.0-9B-GGUF`  |
+| worker        | `unsloth/Qwen3-4B-Instruct-2507-GGUF`  |
+| vision        | `unsloth/Qwen3-VL-4B-Instruct-GGUF`    |
+| vision_small  | `openbmb/MiniCPM-V-4.6-gguf`           |
+
+## Links
+
+- `DESIGN.md` — full architecture & research notes
+- `TODO.md` — roadmap tracker
+ 

opencommand-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "opencommand"
+version = "0.1.0"
+description = "Local-first swarm agent framework: a Commander plans and dispatches a swarm of Workers that research, code, test, and interactively drive the computer to complete long-horizon codebase goals."
+readme = "README.md"
+authors = [
+    { name = "DSiENT", email = "w.caskey7@gmail.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "asciimatics>=1.15.0",
+    "click>=8.4.2",
+    "playwright>=1.61.0",
+    "pyautogui>=0.9.54",
+    "pynput>=1.8.2",
+    "requests>=2.34.2",
+    "mss>=9.0.0",
+    "pillow>=11.0.0",
+    "llama-cpp-python>=0.3.33",
+    "watchdog>=6.0.0",
+    "ntfy>=2.7.1",
+]
+
+[project.scripts]
+opencommand = "opencommand:main"
+
+[project.urls]
+Homepage = "https://github.com/D5-Interactive/OpenCommand"
+Repository = "https://github.com/D5-Interactive/OpenCommand"
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12.0"]
+build-backend = "uv_build"

opencommand-0.1.0/src/opencommand/__init__.py

@@ -0,0 +1,4 @@
+def main() -> None:
+    from .cli import cli
+
+    cli()

opencommand-0.1.0/src/opencommand/cli.py

@@ -0,0 +1,375 @@
+"""click-based CLI for OpenCommand (fully embedded, no external servers).
+
+Commands:
+  opencommand workspace [path]            # show workspace + engine status
+  opencommand models pull [role]          # download built-in GGUF models
+  opencommand models list                 # list built-in model catalog
+  opencommand run "goal"                  # run the swarm autonomously
+  opencommand tui                         # live swarm dashboard
+  opencommand notify "msg"                # send a test ntfy notification
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+import click
+
+from .core.config import OpenCommandConfig
+from .core.logging import configure_logging, get_logger
+from .core.supervisor import Supervisor
+from .core.tools import ToolRegistry
+from .engine import Engine
+from .modules.system.platform import describe
+
+log = get_logger("cli")
+
+
+def _build_tools(engine: Engine, cfg: OpenCommandConfig) -> ToolRegistry:
+    from .modules.tools.desktop import DesktopTool
+    from .modules.tools.files import FilesTool
+    from .modules.tools.instructions import InstructionsTool
+    from .modules.tools.memory import MemoryTool
+    from .modules.tools.playwright import PlaywrightTool
+    from .modules.tools.research import ResearchTool
+    from .modules.tools.system import SystemTool
+    from .modules.tools.terminal import TerminalTool
+
+    reg = ToolRegistry()
+    reg.register(TerminalTool())
+    reg.register(FilesTool(cfg.workspace))
+    reg.register(MemoryTool(cfg.workspace))
+    reg.register(InstructionsTool(cfg.workspace))
+    reg.register(ResearchTool())
+    reg.register(PlaywrightTool())
+    reg.register(SystemTool())
+    vision_role = cfg.vision_model if cfg.vision else None
+    reg.register(DesktopTool(engine.runner(vision_role) if vision_role else None))
+    return reg
+
+
+def _load_cfg(path: str | None) -> OpenCommandConfig:
+    ws = Path(path).resolve() if path else Path.cwd()
+    return OpenCommandConfig.load(ws)
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+@click.option("-v", "--verbose", is_flag=True, help="Enable verbose (DEBUG) logging.")
+def cli(verbose: bool) -> None:
+    """OpenCommand  -  all-in-one local model runner & command center."""
+    configure_logging(level=logging.DEBUG if verbose else logging.INFO,
+                      workspace=_load_cfg(None).workspace, verbose=verbose)
+
+
+@cli.command()
+@click.argument("path", required=False)
+def workspace(path: str | None) -> None:
+    """Show workspace info and embedded engine status."""
+    cfg = _load_cfg(path)
+    engine = Engine(model_dir=cfg.workspace / "models")
+    click.echo(f"Workspace: {cfg.workspace}")
+    click.echo(f"Platform: {describe()}")
+    click.echo(engine.status())
+
+
+@cli.command()
+@click.argument("path", required=False)
+@click.option("--apply", is_flag=True, help="Write the recommended config to the workspace.")
+@click.option("--rebuild", is_flag=True, help="Rebuild llama-cpp-python from source with detected ISA flags.")
+def setup(path: str | None, apply: bool, rebuild: bool) -> None:
+    """Autodetect the host and show (or --apply / --rebuild) a per-host setup."""
+    from .modules.system.platform import detect, recommend_config
+
+    ws = Path(path).resolve() if path else Path.cwd()
+    d = detect()
+    rec = recommend_config(d)
+    click.echo(describe())
+    click.echo(f"Cores: {d['cores']}  RAM: {d['ram_gb']} GB  GPU: {d['gpu']['backend']}")
+    click.echo(f"ISA: {', '.join(d['isa']['extensions']) or 'base'}")
+    click.echo(f"Tools: {', '.join(k for k, v in d['tools'].items() if v) or 'none'}")
+    click.echo("\nRecommended config:")
+    click.echo(f"  max_workers={rec['config']['max_workers']}  "
+               f"pool_size={rec['engine']['pool_size']}  "
+               f"n_gpu_layers={rec['runner']['n_gpu_layers']}")
+    click.echo(f"  vision={rec['config']['vision']}")
+    if rec["build"]["cmake_args"]:
+        click.echo(f"  llama.cpp build: {rec['build']['cmake_args']}")
+    if apply:
+        cfg = OpenCommandConfig.from_host(ws)
+        cfg.save()
+        click.echo(click.style(f"\nWrote config -> {cfg._path()}", fg="green"))
+    if rebuild:
+        _rebuild_llama_cpp(rec["build"]["cmake_args"])
+
+
+def _rebuild_llama_cpp(cmake_args: str) -> None:
+    """Reinstall llama-cpp-python from source with the given CMAKE_ARGS.
+
+    Mirrors the manual x64 AVX2 build: on Windows we must compile inside the
+    MSVC x64 dev shell (vcvars64.bat), otherwise a 32-bit DLL is produced.
+    """
+    import subprocess
+
+    click.echo(click.style(f"\nRebuilding llama-cpp-python (CMAKE_ARGS={cmake_args or 'none'})...",
+                           fg="yellow"))
+    if not cmake_args:
+        click.echo("No ISA build flags detected; building with defaults.")
+    cmd, shell, env = _build_rebuild_command(cmake_args)
+    try:
+        subprocess.run(cmd, shell=shell, env=env, check=True)
+        click.echo(click.style("llama-cpp-python rebuilt.", fg="green"))
+    except subprocess.CalledProcessError as e:
+        click.echo(click.style(f"Rebuild failed (exit {e.returncode}). "
+                               "Ensure MSVC Build Tools 2022 is installed.", fg="red"))
+
+
+def _build_rebuild_command(cmake_args: str) -> tuple:
+    """Return (command, shell, env) for the llama-cpp-python source rebuild.
+
+    Windows compiles inside the MSVC x64 dev shell; POSIX sets CMAKE_ARGS in env.
+    """
+    base = ["uv", "pip", "install", "--no-binary", "llama-cpp-python",
+            "--no-cache", "llama-cpp-python"]
+    if sys.platform.startswith("win"):
+        vcvars = (r"C:\Program Files\Microsoft Visual Studio\2022\BuildTools"
+                  r"\Common7\Tools\vcvars64.bat")
+        if not Path(vcvars).exists():
+            vcvars = (r"C:\Program Files (x86)\Microsoft Visual Studio\2022"
+                      r"\BuildTools\Common7\Tools\vcvars64.bat")
+        cmd = f'call "{vcvars}" && set CMAKE_ARGS={cmake_args} && ' + " ".join(base)
+        return cmd, True, None
+    return base, False, dict(os.environ, CMAKE_ARGS=cmake_args)
+
+
+@cli.group()
+def models() -> None:
+    """Manage built-in embedded models."""
+
+
+@models.command("list")
+def models_list() -> None:
+    """List the built-in model catalog."""
+    from .engine.runner import CATALOG
+
+    for spec in CATALOG.values():
+        click.echo(f"  {spec.role:10} {spec.repo_id} [{spec.kind}] fmt={spec.chat_format}")
+
+
+@models.command("pull")
+@click.argument("role", required=False)
+@click.option("--path", default=None, help="Workspace directory.")
+def models_pull(role: str | None, path: str | None) -> None:
+    """Download built-in GGUF model(s). Role: commander|worker|vision|all."""
+    cfg = _load_cfg(path)
+    engine = Engine(model_dir=cfg.workspace / "models")
+    roles = ["commander", "worker", "vision", "vision_small"] if role in (None, "all") else [role]
+    for r in roles:
+        click.echo(f"Downloading {r}...")
+        p = engine.ensure_downloaded(r)
+        click.echo(f"  -> {p}")
+
+
+@cli.group()
+def cron() -> None:
+    """Schedule recurring tasks (e.g. 'every 1h', 'daily 09:00')."""
+
+
+@cron.command("add")
+@click.argument("name")
+@click.argument("schedule")
+@click.argument("command")
+@click.option("--path", default=None, help="Workspace directory.")
+def cron_add(name: str, schedule: str, command: str, path: str | None) -> None:
+    """Add a cron job NAME on SCHEDULE that runs COMMAND (shell)."""
+    from .modules.system.cron import CronScheduler
+
+    cfg = _load_cfg(path)
+    cron_file = cfg.workspace / ".opencommand" / "cron.json"
+    sched = CronScheduler.load(cron_file)
+    sched.schedule_command(name, schedule, command)
+    sched.save(cron_file)
+    click.echo(f"Added cron job '{name}' on '{schedule}': {command}")
+    click.echo(f"Persisted to {cron_file}")
+
+
+@cron.command("list")
+@click.option("--path", default=None, help="Workspace directory.")
+def cron_list(path: str | None) -> None:
+    """List persisted cron jobs."""
+    from .modules.system.cron import CronScheduler
+
+    cfg = _load_cfg(path)
+    cron_file = cfg.workspace / ".opencommand" / "cron.json"
+    sched = CronScheduler.load(cron_file)
+    click.echo(sched.status())
+
+
+@cron.command("remove")
+@click.argument("name")
+@click.option("--path", default=None, help="Workspace directory.")
+def cron_remove(name: str, path: str | None) -> None:
+    """Remove a persisted cron job by NAME."""
+    import json as _json
+
+    cfg = _load_cfg(path)
+    cron_file = cfg.workspace / ".opencommand" / "cron.json"
+    if not cron_file.exists():
+        click.echo("No cron jobs persisted.")
+        return
+    data = _json.loads(cron_file.read_text(encoding="utf-8"))
+    kept = [j for j in data if j["name"] != name]
+    if len(kept) == len(data):
+        click.echo(f"No job named '{name}'.")
+        return
+    cron_file.write_text(_json.dumps(kept, indent=2), encoding="utf-8")
+    click.echo(f"Removed cron job '{name}'.")
+
+
+@cron.command("status")
+@click.option("--path", default=None, help="Workspace directory.")
+def cron_status(path: str | None) -> None:
+    """Show loaded cron jobs (live in-process schedules)."""
+    from .modules.system.cron import CronScheduler
+
+    cfg = _load_cfg(path)
+    cron_file = cfg.workspace / ".opencommand" / "cron.json"
+    sched = CronScheduler.load(cron_file)
+    click.echo(sched.status())
+
+
+@cron.command("start")
+@click.option("--path", default=None, help="Workspace directory.")
+def cron_start(path: str | None) -> None:
+    """Load persisted cron jobs and run the scheduler in the foreground."""
+    import asyncio
+
+    from .modules.system.cron import CronScheduler
+
+    cfg = _load_cfg(path)
+    cron_file = cfg.workspace / ".opencommand" / "cron.json"
+    sched = CronScheduler.load(cron_file)
+    if not sched._jobs:
+        click.echo("No persisted cron jobs. Use `cron add` first.")
+        return
+    click.echo(sched.status())
+    click.echo("Running scheduler (Ctrl-C to stop)...")
+
+    async def _run() -> None:
+        sched.start()
+        try:
+            while not sched._stop.is_set():
+                await asyncio.sleep(sched._tick)
+        finally:
+            sched.stop()
+
+    try:
+        asyncio.run(_run())
+    except (KeyboardInterrupt, asyncio.CancelledError):
+        pass
+    click.echo("Scheduler stopped.")
+
+
+@cli.command()
+@click.argument("goal")
+@click.option("--path", default=None, help="Workspace directory.")
+@click.option("--max-iter", default=5, help="Automatic-mode iterations.")
+@click.option("--verify", default=None, help="Shell command to verify success (e.g. 'pytest -q').")
+@click.option("--pool", default=None, type=int, help="Worker model pool size (parallelism).")
+@click.option("--no-vision", is_flag=True, help="Disable the desktop/vision tool.")
+@click.option("--vision-model", default=None,
+              type=click.Choice(["vision", "vision_small"]),
+              help="Vision model for the desktop tool (vision=Qwen3-VL-4B, "
+                   "vision_small=MiniCPM-V-4.6 0.8B for CPU/low-RAM).")
+@click.option("--pipeline", default=None,
+              type=click.Choice(["standard", "advanced"]),
+              help="Pipeline: standard (plan->research->workers) or advanced "
+                   "(Phase 6: scaffold + research-context + commander review gate).")
+@click.option("--live-verify", is_flag=True,
+              help="After tests pass, run the desktop tool to interactively verify UI goals.")
+def run(goal: str, path: str | None, max_iter: int, verify: str | None,
+        pool: int | None, no_vision: bool, vision_model: str | None,
+        pipeline: str | None, live_verify: bool) -> None:
+    """Run a GOAL autonomously using embedded models."""
+    import asyncio
+
+    from .modules.system.automatic import run_automatic
+    from .swarm.agents.commander import Commander
+
+    cfg = _load_cfg(path)
+    if no_vision:
+        cfg.vision = None
+    if vision_model:
+        cfg.vision_model = vision_model
+    if pipeline:
+        cfg.pipeline = pipeline
+    if live_verify:
+        cfg.live_verify = True
+    engine = Engine(model_dir=cfg.workspace / "models",
+                    pool_size=pool or cfg.max_workers)
+    sup = Supervisor(max_retries=cfg.max_retries)
+    tools = _build_tools(engine, cfg)
+    commander = Commander(engine, sup, tools, cfg.workspace)
+    # Boot persisted cron jobs: they run inside the agent event loop and dispatch
+    # goals through the Commander (or run shell commands) when they fire.
+    from .modules.system.cron import CronScheduler
+    cron_file = cfg.workspace / ".opencommand" / "cron.json"
+    cron = CronScheduler.load(cron_file)
+    if cron._jobs:
+        cron.on_goal = lambda g: run_automatic(
+            commander, g, max_iterations=max_iter, verify_cmd=verify,
+            pipeline=cfg.pipeline, live_verify=cfg.live_verify)
+        click.echo(click.style(f"Loaded {len(cron._jobs)} cron job(s).", fg="green"))
+
+    async def _main() -> str:
+        if cron._jobs:
+            cron.start()
+        try:
+            return await run_automatic(
+                commander, goal, max_iterations=max_iter, verify_cmd=verify,
+                pipeline=cfg.pipeline, live_verify=cfg.live_verify)
+        finally:
+            cron.stop()
+            sup.shutdown()
+
+    click.echo(f"OpenCommand on {describe()}")
+    click.echo(click.style(f"Pipeline: {cfg.pipeline}"
+                           + (" + live-verify" if cfg.live_verify else ""), fg="cyan"))
+    click.echo(click.style("Loading embedded models...", fg="cyan"))
+    click.echo(click.style("Running automatic mode...", fg="cyan"))
+    report = asyncio.run(_main())
+    click.echo(report)
+
+
+@cli.command()
+def tui() -> None:
+    """Launch the live swarm dashboard (asciimatics)."""
+    from .tui.dashboard import run_dashboard
+
+    run_dashboard()
+
+
+@cli.command()
+@click.argument("message")
+@click.option("--title", default=None, help="Notification title.")
+@click.option("--priority", default=3, help="ntfy priority 1..5 (default 3).")
+def notify(message: str, title: str | None, priority: int) -> None:
+    """Send a test ntfy notification (needs NTFY_TOPIC env var)."""
+    from .modules.system.notify import Notifier
+
+    n = Notifier()
+    if not n.enabled:
+        click.echo(
+            "ntfy not configured. Set NTFY_TOPIC (e.g. "
+            "https://ntfy.sh/your-topic) in the environment."
+        )
+        return
+    ok = n.send(message, title=title, priority=priority)
+    click.echo("Notification sent." if ok else "Notification FAILED.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()

opencommand-0.1.0/src/opencommand/core/agent.py

@@ -0,0 +1,91 @@
+"""AgentLoop: the per-worker reasoning loop (prompt -> LLM -> tools -> observe)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..providers.provider import BaseProvider, ChatMessage
+from .errors import ContextWindowError, RetryableError
+from .tools import ToolRegistry, parse_tool_calls
+
+SYSTEM_PROMPT = (
+    "You are an OpenCommand agent operating inside a workspace on {platform}. "
+    "You complete tasks by calling tools. Think step by step, then emit tool "
+    "calls. When the task is fully done, reply with a final summary and no "
+    "tool calls. Be concise and correct; prefer running tests to claiming success."
+)
+
+
+@dataclass
+class AgentState:
+    messages: list[ChatMessage] = field(default_factory=list)
+    steps: int = 0
+    max_steps: int = 40
+
+
+class AgentLoop:
+    """Drives one worker: repeatedly calls the LLM and executes its tools."""
+
+    def __init__(
+        self,
+        provider: BaseProvider,
+        tools: ToolRegistry,
+        system: str | None = None,
+        platform: str = "this machine",
+    ) -> None:
+        self.provider = provider
+        self.tools = tools
+        self.system = system or SYSTEM_PROMPT.format(platform=platform)
+
+    async def run(self, task: str, max_steps: int = 40) -> str:
+        state = AgentState(max_steps=max_steps)
+        state.messages.append(ChatMessage(role="system", content=self.system))
+        state.messages.append(ChatMessage(role="user", content=task))
+        while state.steps < state.max_steps:
+            state.steps += 1
+            try:
+                msg = await self.provider.acomplete(state.messages, tools=self.tools.schemas())
+            except ContextWindowError:
+                # Bound history and retry instead of failing the whole run.
+                state.messages = _truncate(state.messages, keep=20)
+                state.messages.append(ChatMessage(
+                    role="system",
+                    content="Context was truncated to fit the model window. Continue."))
+                continue
+            except Exception as e:  # noqa: BLE001
+                if "context" in str(e).lower():
+                    raise ContextWindowError(str(e)) from e
+                raise RetryableError(str(e)) from e  # noqa: TRY003
+            state.messages.append(msg)
+            calls = parse_tool_calls(msg)
+            if not calls:
+                # No structured calls. If the model emitted a tool-call marker in
+                # text but parsing failed, nudge it to retry rather than stop.
+                if "<function=" in (msg.content or "") or "<tool_call" in (msg.content or ""):
+                    state.messages.append(ChatMessage(
+                        role="system",
+                        content=("Your tool call could not be parsed. Re-emit it using the "
+                                 "exact <tool_call><function=name><parameter=key>value"
+                                 "</parameter></function></tool_call> format, or reply with a "
+                                 "final summary if the task is done.")))
+                    continue
+                return msg.content or "(no output)"
+            for call in calls:
+                result = await self.tools.adispatch(call)
+                obs = result.output if result.ok else f"ERROR: {result.error}"
+                state.messages.append(
+                    ChatMessage(role="tool", content=obs, name=call.name, tool_call_id=call.id)
+                )
+            # Proactively cap history to stay within n_ctx on long tool loops.
+            if len(state.messages) > 24:
+                state.messages = _truncate(state.messages, keep=20)
+        return "(max steps reached)"
+
+
+def _truncate(messages: list[ChatMessage], keep: int = 20) -> list[ChatMessage]:
+    """Keep system + recent messages to bound context on retry."""
+    if len(messages) <= keep:
+        return messages
+    head = [m for m in messages if m.role == "system"]
+    tail = messages[-(keep - len(head)) :]
+    return head + tail