Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

feat(local-models): assistant tools (ask-tier through ToolExecutor, no delete) and the per-turn briefing prompt

rubenluetke10-beep996f4dae810a
diff --git a/jarvis/local_models/assistant_prompt.py b/jarvis/local_models/assistant_prompt.py
new file mode 100644
index 0000000000..85d25164fe
--- /dev/null
+++ b/jarvis/local_models/assistant_prompt.py
@@ -0,0 +1,308 @@
+"""The setup assistant's briefing: a per-turn system-prompt addendum.
+
+Rendered fresh for every turn of the ``local-models`` chat surface and
+handed to the brain through ``TurnOverride.system_extra`` — the machine's
+facts, what is installed, which role runs what (and under which config
+key), the curated shortlist with fit verdicts and proven / new labels, the
+benchmark table from the cache, the hard rules, and the output contract the
+panel parses (a fenced ``jarvis-proposal`` JSON block). Budget: about 2.5k
+tokens, so lists are capped rather than complete.
+
+The three canned openers are what the panel's buttons send as the user
+turn (D6): ``SETUP_OPENER``, ``DIAGNOSE_OPENER``, ``TEST_OPENER``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import datetime as _dt
+import logging
+from typing import Any, Final
+
+log = logging.getLogger(__name__)
+
+__all__ = [
+ "DIAGNOSE_OPENER",
+ "PROPOSAL_FENCE",
+ "SETUP_OPENER",
+ "TEST_OPENER",
+ "build_system_extra",
+]
+
+PROPOSAL_FENCE: Final[str] = "jarvis-proposal"
+
+#: Rough budget guard: characters, not tokens (≈ 4 chars per token).
+_MAX_CHARS = 10_000
+_MAX_INVENTORY_ROWS = 30
+_MAX_BENCHMARK_ROWS = 40
+
+SETUP_OPENER: Final[str] = (
+ "Help me set up local models on this machine. Check the hardware and the server, then "
+ "propose ONE complete setup for the five roles (chat, voice, tools_screen, deep, "
+ "embedding) using the best proven models that fit, as a jarvis-proposal block. "
+ "Do not execute anything until I confirm."
+)
+
+DIAGNOSE_OPENER: Final[str] = (
+ "Something is not working with my local models. Find out what is broken (server, "
+ "roles, downloads, voice server), name the cause in one or two sentences, and propose "
+ "the smallest fix as a jarvis-proposal block. Do not execute anything until I confirm."
+)
+
+TEST_OPENER: Final[str] = (
+ "Run the end-to-end test of my local setup (lm_test_plan) and report the result as a "
+ "short table: one line per role with ok / error and the reason. Propose a fix as a "
+ "jarvis-proposal block only for roles that failed."
+)
+
+_RULES: Final[str] = """\
+HARD RULES
+- Never delete a model; there is no tool for it and you must not suggest one.
+- Never change the active brain provider yourself. When Ollama should answer the voice and \
+the chat, put a `brain_switch` entry in the proposal — the person clicks it.
+- Installs, downloads, role picks, option writes and voice-stack changes happen only after \
+the person confirmed the proposal; in that run, call the tools in the proposal's order.
+- Never touch BIOS, OS, driver or firewall settings; point to the OLLAMA_* guide instead.
+- Prefer models labelled `proven` whose fit is `comfortable`; a `new_little_tested` model is \
+never a default; a `stale` label means the shortlist needs a refresh — say so.
+- When a step fails, say exactly what failed (the tool's own sentence) and what to do next.
+- Answer in the person's language; keep prose short, the proposal block carries the plan.
+- Written delivery: this is a chat panel, not a voice reply — tables and lists are fine."""
+
+_CONTRACT: Final[str] = """\
+OUTPUT CONTRACT
+When you propose or revise a setup, end the message with exactly one fenced block:
+```jarvis-proposal
+{"version": 1,
+ "steps": [
+ {"id": "s1", "kind": "install_ollama", "label": "Install Ollama"},
+ {"id": "s2", "kind": "pull", "model": "qwen3.5:4b", "size_gb": 3.4, "fit": "comfortable",
+ "proven": true, "label": "Download Qwen 3.5 4B"},
+ {"id": "s3", "kind": "set_role", "role": "chat", "model": "qwen3.5:4b", "label": "..."},
+ {"id": "s4", "kind": "set_options", "model": "qwen3.5:4b", "options": {"num_ctx": 16384},
+ "label": "..."},
+ {"id": "s5", "kind": "apply_voice_stack", "model": "qwen3.5:4b", "options":
+ {"voice_model": "..."}, "label": "..."},
+ {"id": "s6", "kind": "test", "label": "Test every role"}
+ ],
+ "brain_switch": {"provider": "ollama", "why": "one sentence"},
+ "notes": ["one sentence per caveat"]}
+```
+`kind` is one of install_ollama | pull | set_role | set_options | apply_voice_stack | test. \
+`brain_switch` and `notes` are optional; `steps` may be empty when nothing needs doing."""
+
+
+# ── data gathering ────────────────────────────────────────────────────────
+
+
+def _provider(cfg: Any, name: str) -> Any:
+ providers = getattr(getattr(cfg, "brain", None), "providers", None) or {}
+ return providers.get(name) if isinstance(providers, dict) else None
+
+
+async def _machine(cfg: Any) -> dict[str, Any]:
+ import platform
+
+ from jarvis.brain.ollama_pull import accelerator_gb, total_memory_gb
+
+ (accel, source), ram = await asyncio.gather(
+ asyncio.to_thread(accelerator_gb), asyncio.to_thread(total_memory_gb)
+ )
+ brain = getattr(cfg, "brain", None)
+ worker = getattr(brain, "worker", None)
+ return {
+ "os": f"{platform.system()} {platform.release()} ({platform.machine()})",
+ "ram_gb": ram,
+ "accelerator_gb": round(accel, 1),
+ "accelerator_source": source,
+ "active_brain": str(getattr(brain, "primary", "") or ""),
+ "assistant_tier": (
+ f"{getattr(worker, 'provider', '') or ''} / {getattr(worker, 'model', '') or ''}"
+ ).strip(" /"),
+ }
+
+
+async def _inventory(root: str, transport: Any) -> tuple[list[Any], str | None]:
+ from jarvis.brain import ollama_inventory as inventory
+
+ try:
+ return await inventory.list_models(root, transport=transport), None
+ except inventory.OllamaServerError as exc:
+ return [], str(exc)
+
+
+def _roles(cfg: Any, installed_names: list[str]) -> list[dict[str, Any]]:
+ from jarvis.brain.ollama_inventory import same_model
+ from jarvis.brain.ollama_roles import ROLES, current_pick
+
+ rows: list[dict[str, Any]] = []
+ for spec in ROLES:
+ if not spec.writable:
+ continue
+ current, note = current_pick(cfg, spec.id)
+ rows.append(
+ {
+ "role": spec.id,
+ "config_key": spec.config_key,
+ "required": list(spec.required),
+ "current": current,
+ "installed": bool(current) and any(same_model(n, current) for n in installed_names),
+ "note": note,
+ }
+ )
+ return rows
+
+
+def _curated(
+ machine: dict[str, Any], installed_names: list[str], table: Any, today: _dt.date
+) -> list[dict[str, Any]]:
+ from jarvis.brain.ollama_inventory import same_model
+ from jarvis.brain.ollama_pull import RECOMMENDED_MODELS, fit_verdict
+ from jarvis.local_models.benchmarks import label_for
+
+ rows: list[dict[str, Any]] = []
+ for entry in RECOMMENDED_MODELS:
+ verdict, _note = fit_verdict(
+ entry.size_gb, machine.get("ram_gb"), float(machine.get("accelerator_gb") or 0.0)
+ )
+ rows.append(
+ {
+ "id": entry.id,
+ "role": entry.role,
+ "size_gb": entry.size_gb,
+ "tools": entry.tools,
+ "vision": entry.vision,
+ "fit": verdict,
+ "installed": any(same_model(n, entry.id) for n in installed_names),
+ "label": label_for(entry, table, today),
+ "purpose": entry.purpose,
+ }
+ )
+ return rows
+
+
+# ── rendering ─────────────────────────────────────────────────────────────
+
+
+def _yn(value: bool) -> str:
+ return "yes" if value else "no"
+
+
+def _render_machine(machine: dict[str, Any], server: dict[str, Any], root: str) -> str:
+ ram = machine.get("ram_gb")
+ lines = [
+ "MACHINE",
+ f"- OS: {machine['os']}",
+ f"- RAM: {ram:g} GB" if ram is not None else "- RAM: unknown",
+ f"- Graphics memory usable for models: {machine['accelerator_gb']:g} GB "
+ f"(source: {machine['accelerator_source']})",
+ f"- Ollama server: {root} — "
+ + (
+ f"running, version {server.get('version')}"
+ if server.get("ok")
+ else f"not answering ({server.get('detail')})"
+ ),
+ f"- Active brain provider: {machine['active_brain'] or 'unset'} "
+ "(only the person may change it)",
+ f"- You run on the Agents tier: {machine['assistant_tier'] or 'unknown'}",
+ ]
+ return "\n".join(lines)
+
+
+def _render_inventory(models: list[Any], error: str | None) -> str:
+ if error:
+ return f"INSTALLED MODELS\n- unavailable: {error}"
+ if not models:
+ return "INSTALLED MODELS\n- none"
+ lines = ["INSTALLED MODELS (name · size · capabilities · context)"]
+ for m in models[:_MAX_INVENTORY_ROWS]:
+ caps = ",".join(m.capabilities) or "unknown"
+ ctx = f"{m.context_length}" if m.context_length else "?"
+ lines.append(f"- {m.name} · {m.size_bytes / (1024**3):.1f} GB · {caps} · ctx {ctx}")
+ if len(models) > _MAX_INVENTORY_ROWS:
+ lines.append(f"- … and {len(models) - _MAX_INVENTORY_ROWS} more (lm_inventory)")
+ return "\n".join(lines)
+
+
+def _render_roles(rows: list[dict[str, Any]], voice_command: str) -> str:
+ lines = ["ROLES (role · needs · current pick · installed · config key)"]
+ for r in rows:
+ pick = r["current"] or "not set"
+ extra = f" — {r['note']}" if r["note"] else ""
+ lines.append(
+ f"- {r['role']} · {'+'.join(r['required'])} · {pick} · "
+ f"{_yn(r['installed']) if r['current'] else '-'} · {r['config_key']}{extra}"
+ )
+ managed = "--model_name" in voice_command
+ lines.append(
+ "- managed voice server: "
+ + ("installed (apply_voice_stack may change its models)" if managed else "not installed")
+ )
+ return "\n".join(lines)
+
+
+def _render_curated(rows: list[dict[str, Any]], reviewed_on: _dt.date) -> str:
+ lines = [
+ f"CURATED SHORTLIST (reviewed {reviewed_on.isoformat()}; id · role · GB · fit · "
+ "label · installed)"
+ ]
+ for r in rows:
+ caps = "tools" if r["tools"] else "-"
+ if r["vision"]:
+ caps += "+vision"
+ lines.append(
+ f"- {r['id']} · {r['role']} · {r['size_gb']:g} · {r['fit']} · {r['label']} · "
+ f"{_yn(r['installed'])} · {caps} — {r['purpose']}"
+ )
+ return "\n".join(lines)
+
+
+def _render_benchmarks(table: Any) -> str:
+ if table is None:
+ return "BENCHMARKS\n- no cached table (lm_benchmarks refresh=true inside a guided run)"
+ lines = [f"BENCHMARKS (source: {table.source}; fetched {table.fetched_at or 'n/a'})"]
+ if table.note:
+ lines.append(f"- note: {table.note}")
+ for row in table.rows[:_MAX_BENCHMARK_ROWS]:
+ lines.append(f"- {row.family} · {row.source} · {row.metric} = {row.value:g}")
+ for family, facts in list(table.library.items())[:_MAX_BENCHMARK_ROWS]:
+ upd = f"{facts.updated_days} d ago" if facts.updated_days is not None else "?"
+ lines.append(f"- {family} · library · pulls {facts.pulls:,} · updated {upd}")
+ if len(lines) == 1:
+ lines.append("- no rows")
+ return "\n".join(lines)
+
+
+async def build_system_extra(cfg: Any, *, root: str, transport: Any = None) -> str:
+ """The addendum for one turn of the local-models assistant (≈ 2.5k tokens)."""
+ from jarvis.brain.ollama_pull import CURATED_REVIEWED_ON
+ from jarvis.brain.ollama_runtime import probe_host
+ from jarvis.local_models.benchmarks import load_cached
+
+ machine, server, (models, inv_error) = await asyncio.gather(
+ _machine(cfg), probe_host(root, transport=transport), _inventory(root, transport)
+ )
+ installed_names = [m.name for m in models]
+ table = load_cached()
+ today = _dt.datetime.now(_dt.UTC).date()
+ voice_command = str(getattr(_provider(cfg, "local-realtime"), "launch_command", "") or "")
+
+ sections = [
+ "LOCAL MODELS SETUP ASSISTANT\n"
+ "You help this person set up, test and repair local models (Ollama) on THIS machine, "
+ "inside the Local models section. Read with the lm_* tools before you propose; "
+ "act only through them, and only after confirmation.",
+ _render_machine(machine, server, root),
+ _render_inventory(models, inv_error),
+ _render_roles(_roles(cfg, installed_names), voice_command),
+ _render_curated(_curated(machine, installed_names, table, today), CURATED_REVIEWED_ON),
+ _render_benchmarks(table),
+ _RULES,
+ _CONTRACT,
+ ]
+ text = "\n\n".join(sections)
+ if len(text) > _MAX_CHARS:
+ log.info("local-models prompt: %d chars, trimming the benchmark section", len(text))
+ sections[5] = "BENCHMARKS\n- table too long for the briefing; use lm_benchmarks"
+ text = "\n\n".join(sections)
+ return text
diff --git a/jarvis/local_models/assistant_tools.py b/jarvis/local_models/assistant_tools.py
new file mode 100644
index 0000000000..d8eb17b73b
--- /dev/null
+++ b/jarvis/local_models/assistant_tools.py
@@ -0,0 +1,785 @@
+"""The setup assistant's hands: Jarvis tools over the local-models functions.
+
+Every tool here wraps a function the Local models section already calls
+(``ollama_runtime``, ``ollama_inventory``, ``ollama_roles``, ``ollama_pull``,
+``ollama_library``, the managed voice server) as a
+:class:`jarvis.core.protocols.Tool`, the way :mod:`jarvis.agent_chat.folder_tools`
+wraps the chat's folder tools — so every call goes through ``ToolExecutor``
+with its risk tiers, blacklist, audit log and approval card (AP-3), on the
+``local-models`` chat surface exactly as on the voice path.
+
+Tiers: reads are ``safe``; everything that installs, starts, stops, downloads
+or writes config is ``ask`` (the panel auto-answers the cards of a confirmed
+proposal, the executor still asks); ``lm_unload`` is ``monitor``. There is
+deliberately **no delete tool** and nothing that writes ``brain.primary`` —
+the provider lock stays with the user's click.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import platform
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, Final
+
+from jarvis.core.protocols import ExecutionContext, RiskTier, Tool, ToolResult
+
+log = logging.getLogger(__name__)
+
+__all__ = [
+ "ACTION_TOOLS",
+ "ALLOWED_TIERS",
+ "LocalModelsTool",
+ "READ_TOOLS",
+ "TOOL_PREFIX",
+ "build_tools",
+ "tool_specs",
+]
+
+TOOL_PREFIX: Final[str] = "lm_"
+
+#: Every tier a local-models tool may carry. ``block`` is not on the list on
+#: purpose: a tool that must never run is a tool that must not exist here.
+ALLOWED_TIERS: Final[tuple[RiskTier, ...]] = ("safe", "monitor", "ask")
+
+Handler = Callable[[dict[str, Any], "_Env"], Awaitable[Any]]
+
+#: How long ``lm_pull`` follows a download before handing back a "still
+#: running" answer (the panel keeps polling ``lm_pull_status``).
+PULL_FOLLOW_MAX_S = 1800.0
+PULL_POLL_S = 1.0
+
+
+@dataclass(frozen=True, slots=True)
+class _Env:
+ """What every handler needs: the live config, the server root, the seams."""
+
+ cfg: Any
+ root: str
+ transport: Any = None
+ search_fn: Callable[[str], Any] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ToolSpec:
+ name: str
+ description: str
+ schema: dict[str, Any]
+ risk_tier: RiskTier
+ handler: Handler
+ summary: Callable[[dict[str, Any]], str] | None = None
+
+
+class LocalModelsTool:
+ """One spec as a Jarvis ``Tool`` bound to a config + server root."""
+
+ def __init__(self, spec: ToolSpec, env: _Env) -> None:
+ self.name: str = spec.name
+ self.description: str = spec.description
+ self.schema: dict[str, Any] = dict(spec.schema)
+ self.risk_tier: RiskTier = spec.risk_tier
+ self._spec = spec
+ self._env = env
+
+ async def execute(self, args: dict[str, Any], ctx: ExecutionContext) -> ToolResult:
+ try:
+ output = await self._spec.handler(dict(args or {}), self._env)
+ except Exception as exc: # noqa: BLE001 — the model reads the failure, the log keeps it
+ log.info("local-models tool %s failed: %s", self.name, exc, exc_info=True)
+ return ToolResult(success=False, output=str(exc), error=f"{type(exc).__name__}: {exc}")
+ return ToolResult(success=True, output=output)
+
+ def describe_args(self, args: dict[str, Any]) -> dict[str, str]:
+ """The one-line summary the approval card shows."""
+ if self._spec.summary is None:
+ return {}
+ try:
+ text = self._spec.summary(dict(args or {}))
+ except Exception: # noqa: BLE001 — a summary must never break the card
+ log.debug("local-models tool %s: summary failed", self.name, exc_info=True)
+ return {}
+ return {"summary": text} if text else {}
+
+ def __repr__(self) -> str: # pragma: no cover — debugging aid
+ return f"LocalModelsTool({self.name!r}, tier={self.risk_tier!r})"
+
+
+# ── schema helpers ────────────────────────────────────────────────────────
+
+
+def _obj(props: dict[str, Any] | None = None, required: tuple[str, ...] = ()) -> dict[str, Any]:
+ schema: dict[str, Any] = {"type": "object", "properties": dict(props or {})}
+ if required:
+ schema["required"] = list(required)
+ return schema
+
+
+_MODEL = {"type": "string", "description": "An Ollama model tag, e.g. qwen3.5:4b."}
+_ROLE = {
+ "type": "string",
+ "description": "A writable role id: chat, voice, tools_screen, deep or embedding.",
+}
+
+
+def _str(args: dict[str, Any], key: str) -> str:
+ return str(args.get(key) or "").strip()
+
+
+# ── read handlers (safe) ──────────────────────────────────────────────────
+
+
+async def _hardware(_args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ from jarvis.brain.ollama_pull import accelerator_gb, total_memory_gb
+
+ (accel, source), ram = await asyncio.gather(
+ asyncio.to_thread(accelerator_gb), asyncio.to_thread(total_memory_gb)
+ )
+ import os
+
+ return {
+ "os": platform.system(),
+ "os_version": platform.release(),
+ "machine": platform.machine(),
+ "cpu_threads": os.cpu_count() or 0,
+ "ram_gb": ram,
+ "accelerator_gb": round(accel, 1),
+ "accelerator_source": source,
+ }
+
+
+async def _server_status(_args: dict[str, Any], env: _Env) -> dict[str, Any]:
+ from jarvis.brain import ollama_runtime
+
+ status, probe = await asyncio.gather(
+ asyncio.to_thread(ollama_runtime.runtime_status),
+ ollama_runtime.probe_host(env.root, transport=env.transport),
+ )
+ out: dict[str, Any] = {
+ "runtime": status,
+ "probe": probe,
+ "install": ollama_runtime.install_snapshot(),
+ "base_url": env.root,
+ }
+ command = _voice_command(env.cfg)
+ if "--model_name" in command:
+ from jarvis.realtime.local_server import install as voice_install
+ from jarvis.realtime.local_server.preflight import report_payload, run_preflight
+
+ voice_status = await asyncio.to_thread(voice_install.server_status)
+ preflight = await asyncio.to_thread(run_preflight, voice_install.install_root())
+ out["voice"] = {
+ "launch_command": command,
+ "status": voice_status,
+ "preflight": report_payload(preflight),
+ }
+ else:
+ out["voice"] = {"launch_command": command, "status": None, "preflight": None}
+ return out
+
+
+async def _inventory(_args: dict[str, Any], env: _Env) -> dict[str, Any]:
+ from jarvis.brain import ollama_inventory as inventory
+
+ models, running = await asyncio.gather(
+ inventory.list_models(env.root, transport=env.transport),
+ inventory.running_models(env.root, transport=env.transport),
+ )
+ return {
+ "models": [
+ {
+ "name": m.name,
+ "size_gb": round(m.size_bytes / (1024**3), 2),
+ "family": m.family,
+ "parameter_size": m.parameter_size,
+ "quantization": m.quantization_level,
+ "context_length": m.context_length,
+ "capabilities": list(m.capabilities),
+ "modified_at": m.modified_at,
+ }
+ for m in models
+ ],
+ "running": [
+ {
+ "name": r.name,
+ "size_vram_gb": round(r.size_vram_bytes / (1024**3), 2),
+ "context_length": r.context_length,
+ "expires_at": r.expires_at,
+ }
+ for r in running
+ ],
+ "disk_gb": round(sum(m.size_bytes for m in models) / (1024**3), 1),
+ }
+
+
+def _role_row(state: Any) -> dict[str, Any]:
+ spec = state.spec
+ return {
+ "role": spec.id,
+ "config_key": spec.config_key,
+ "writable": spec.writable,
+ "required_capabilities": list(spec.required),
+ "current": state.current,
+ "installed": state.installed,
+ "qualifying": list(state.qualifying),
+ "recommended": state.recommended,
+ "note": state.note,
+ "context_tokens": state.context_tokens,
+ }
+
+
+async def _roles(_args: dict[str, Any], env: _Env) -> dict[str, Any]:
+ from jarvis.brain.ollama_roles import list_roles
+
+ states, error = await list_roles(env.root, env.cfg, transport=env.transport)
+ return {"roles": [_role_row(s) for s in states], "error": error}
+
+
+async def _recommendations(_args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ import datetime as _dt
+
+ from jarvis.brain.ollama_pull import recommendations
+ from jarvis.local_models import benchmarks
+
+ payload = await recommendations()
+ table = benchmarks.load_cached()
+ today = _dt.datetime.now(_dt.UTC).date()
+ for row in payload.get("models") or []:
+ row["label"] = benchmarks.label_for(str(row.get("id") or ""), table, today)
+ payload["benchmark_source"] = table.source if table is not None else "curated"
+ return payload
+
+
+async def _catalog_search(args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ from jarvis.brain.ollama_library import search_library
+
+ return await search_library(
+ _str(args, "query"),
+ sort=_str(args, "sort") or "popular",
+ capability=_str(args, "capability") or None,
+ limit=int(args.get("limit") or 20),
+ )
+
+
+async def _catalog_tags(args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ from jarvis.brain.ollama_library import library_tags
+
+ return await library_tags(_str(args, "model"))
+
+
+async def _hf_search(args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ from jarvis.brain import hf_gguf # lazy: only an install that switched HF on imports it
+
+ return await hf_gguf.search(
+ _str(args, "query"),
+ sort=_str(args, "sort") or "downloads",
+ limit=int(args.get("limit") or 20),
+ )
+
+
+async def _benchmarks(args: dict[str, Any], env: _Env) -> dict[str, Any]:
+ from jarvis.local_models import benchmarks
+
+ table: benchmarks.BenchmarkTable | None
+ if bool(args.get("refresh")) and env.search_fn is not None:
+ table = await benchmarks.refresh_benchmarks(env.search_fn)
+ else:
+ table = benchmarks.load_cached()
+ if table is None:
+ note = (
+ "No benchmark cache yet; pass refresh=true to build one."
+ if env.search_fn is not None
+ else "No benchmark cache and no web search on this surface; curated list only."
+ )
+ table = benchmarks.curated_only(note)
+ return table.to_payload()
+
+
+async def _pull_status(args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ from jarvis.brain.ollama_pull import pull_status
+
+ return await pull_status(_str(args, "model"))
+
+
+async def _server_log(args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ from jarvis.brain.ollama_runtime import tail_log
+
+ lines = max(1, min(int(args.get("lines") or 40), 200))
+ return {"lines": await asyncio.to_thread(tail_log, lines)}
+
+
+async def _env_guide(_args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ from jarvis.brain.ollama_runtime import env_guide
+
+ return {"entries": env_guide()}
+
+
+async def _suggest(model: str, env: _Env) -> tuple[dict[str, Any], list[str], dict[str, Any]]:
+ from jarvis.brain import ollama_inventory as inventory
+ from jarvis.brain import ollama_profiles
+ from jarvis.brain.ollama_pull import accelerator_gb, total_memory_gb
+
+ info = await inventory.get_model(env.root, model, transport=env.transport)
+ (accel, source), ram = await asyncio.gather(
+ asyncio.to_thread(accelerator_gb), asyncio.to_thread(total_memory_gb)
+ )
+ size_gb = round(info.size_bytes / (1024**3), 2)
+ opts, reasons = ollama_profiles.suggest_options(
+ size_gb=size_gb,
+ native_context=info.context_length,
+ accelerator_gb=accel,
+ source=source,
+ ram_gb=ram,
+ )
+ facts = {
+ "model": info.name,
+ "size_gb": size_gb,
+ "native_context": info.context_length,
+ "accelerator_gb": round(accel, 1),
+ "ram_gb": ram,
+ }
+ return opts.model_dump(exclude_none=True), reasons, facts
+
+
+async def _suggested_options(args: dict[str, Any], env: _Env) -> dict[str, Any]:
+ options, reasons, facts = await _suggest(_str(args, "model"), env)
+ return {**facts, "options": options, "reasons": reasons}
+
+
+async def _test_plan(args: dict[str, Any], env: _Env) -> dict[str, Any]:
+ from jarvis.local_models.assistant_test import run_setup_test
+
+ raw = args.get("roles")
+ roles = tuple(str(r) for r in raw) if isinstance(raw, list) and raw else None
+ report = await run_setup_test(env.cfg, roles, transport=env.transport)
+ return report.to_payload()
+
+
+# ── action handlers (ask / monitor) ───────────────────────────────────────
+
+
+async def _install_ollama(_args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ from jarvis.brain import ollama_runtime
+
+ ok, detail = await asyncio.to_thread(ollama_runtime.start_install)
+ return {"started": ok, "detail": detail, "install": ollama_runtime.install_snapshot()}
+
+
+async def _start_server(_args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ from jarvis.brain.ollama_runtime import start_server
+
+ ok, detail = await asyncio.to_thread(start_server)
+ return {"ok": ok, "detail": detail}
+
+
+async def _stop_server(_args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ from jarvis.brain.ollama_runtime import stop_server
+
+ ok, detail = await asyncio.to_thread(stop_server)
+ return {"ok": ok, "detail": detail}
+
+
+async def _pull(args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ """Start (or join) a download and follow it, reporting progress lines."""
+ from jarvis.brain.ollama_pull import pull_status, start_pull
+
+ model = _str(args, "model")
+ state = await start_pull(model)
+ lines: list[str] = [str(state.get("message") or "")]
+ if state.get("state") != "running":
+ return {**state, "progress": lines}
+ max_wait = float(args.get("max_wait_s") or PULL_FOLLOW_MAX_S)
+ started = time.monotonic()
+ last_pct = -1
+ while time.monotonic() - started < max_wait:
+ await asyncio.sleep(PULL_POLL_S)
+ state = await pull_status(model)
+ total = int(state.get("total") or 0)
+ done = int(state.get("completed") or 0)
+ pct = int(done * 100 / total) if total else -1
+ if pct >= 0 and pct // 10 > last_pct // 10:
+ last_pct = pct
+ lines.append(f"{model}: {pct}% ({done / 1e9:.1f} of {total / 1e9:.1f} GB)")
+ if state.get("state") != "running":
+ lines.append(str(state.get("message") or ""))
+ return {**state, "progress": lines}
+ lines.append(f"{model}: still downloading — check lm_pull_status for progress.")
+ return {**state, "progress": lines}
+
+
+async def _set_role(args: dict[str, Any], env: _Env) -> dict[str, Any]:
+ from jarvis.brain.ollama_roles import set_role
+
+ result = dict(set_role(_str(args, "role"), _str(args, "model"), cfg=env.cfg))
+ if result.get("drift_guarded") is False:
+ result["warning"] = (
+ "The pick was written, but the drift baseline could not be updated — "
+ "the drift guard may revert it within minutes. Check the config baseline."
+ )
+ return result
+
+
+async def _set_model_options(args: dict[str, Any], env: _Env) -> dict[str, Any]:
+ """Write ONLY keys the suggestion for this model returned — nothing else."""
+ from jarvis.core import config_writer
+
+ model = _str(args, "model")
+ wanted = args.get("options")
+ if not isinstance(wanted, dict) or not wanted:
+ raise ValueError("options must be a non-empty object.")
+ suggested, _reasons, _facts = await _suggest(model, env)
+ allowed = set(suggested)
+ rejected = sorted(k for k in wanted if k not in allowed)
+ if rejected:
+ raise ValueError(
+ f"Only the suggested keys may be set for {model} ({', '.join(sorted(allowed))}); "
+ f"refused: {', '.join(rejected)}."
+ )
+ written = await asyncio.to_thread(
+ config_writer.set_ollama_model_options, model, {k: wanted[k] for k in wanted}
+ )
+ provider = _ollama_provider(env.cfg)
+ models = getattr(provider, "models", None)
+ if isinstance(models, dict):
+ from jarvis.core.config import OllamaModelOptions
+
+ try:
+ models[model] = OllamaModelOptions.model_validate(written)
+ except (TypeError, ValueError):
+ log.info("local-models: in-memory options for %s not updated", model, exc_info=True)
+ return {"model": model, "written": written}
+
+
+async def _install_voice_server(args: dict[str, Any], _env: _Env) -> dict[str, Any]:
+ from jarvis.realtime.local_server import install as voice_install
+
+ ok, detail = await asyncio.to_thread(
+ lambda: voice_install.start_install(
+ confirmed_brain="ollama",
+ brain_model=_str(args, "brain_model"),
+ voice_model=_str(args, "voice_model"),
+ )
+ )
+ return {"started": ok, "detail": detail, "install": voice_install.snapshot()}
+
+
+async def _apply_voice_stack(args: dict[str, Any], env: _Env) -> dict[str, Any]:
+ from jarvis.realtime.local_server.configure import ManagedSetupError, apply_and_test_stack
+
+ command = _voice_command(env.cfg)
+ if "--model_name" not in command:
+ raise ValueError("Install the managed voice server first (lm_install_voice_server).")
+ try:
+ result = await apply_and_test_stack(
+ base_url=_voice_base_url(env.cfg),
+ current_command=command,
+ brain_model=_str(args, "brain_model"),
+ voice_model=_str(args, "voice_model"),
+ language=_str(args, "language") or "en",
+ )
+ except ManagedSetupError as exc:
+ # The function rolled back (or says it could not) — report, never hide.
+ return {"ok": False, "rolled_back": "restored" in str(exc), "detail": str(exc)}
+ voice = _voice_provider(env.cfg)
+ if voice is not None and result.get("launch_command"):
+ voice.launch_command = str(result["launch_command"])
+ return dict(result)
+
+
+async def _unload(args: dict[str, Any], env: _Env) -> dict[str, Any]:
+ from jarvis.brain import ollama_inventory as inventory
+
+ model = _str(args, "model")
+ await inventory.unload_model(env.root, model, transport=env.transport)
+ return {"model": model, "unloaded": True}
+
+
+# ── config readers ────────────────────────────────────────────────────────
+
+
+def _ollama_provider(cfg: Any) -> Any:
+ providers = getattr(getattr(cfg, "brain", None), "providers", None) or {}
+ return providers.get("ollama") if isinstance(providers, dict) else None
+
+
+def _voice_provider(cfg: Any) -> Any:
+ providers = getattr(getattr(cfg, "brain", None), "providers", None) or {}
+ return providers.get("local-realtime") if isinstance(providers, dict) else None
+
+
+def _voice_command(cfg: Any) -> str:
+ return str(getattr(_voice_provider(cfg), "launch_command", "") or "")
+
+
+def _voice_base_url(cfg: Any) -> str:
+ return str(getattr(_voice_provider(cfg), "base_url", "") or "") or "http://127.0.0.1:8765"
+
+
+# ── the specs ─────────────────────────────────────────────────────────────
+
+
+def _s(
+ name: str,
+ description: str,
+ schema: dict[str, Any],
+ tier: RiskTier,
+ handler: Handler,
+ summary: Callable[[dict[str, Any]], str] | None = None,
+) -> ToolSpec:
+ return ToolSpec(name, description, schema, tier, handler, summary)
+
+
+READ_TOOLS: Final[tuple[ToolSpec, ...]] = (
+ _s(
+ "lm_hardware",
+ "This machine's memory: RAM, usable graphics memory and where that figure comes from.",
+ _obj(),
+ "safe",
+ _hardware,
+ ),
+ _s(
+ "lm_server_status",
+ "Is Ollama installed and running, which version, and the state of the managed voice "
+ "server (status + preflight) when one exists.",
+ _obj(),
+ "safe",
+ _server_status,
+ ),
+ _s(
+ "lm_inventory",
+ "Every downloaded model with size, capabilities and context length, plus what is "
+ "loaded in memory right now.",
+ _obj(),
+ "safe",
+ _inventory,
+ ),
+ _s(
+ "lm_roles",
+ "The five roles (chat, voice, tools_screen, deep, embedding): current pick, its config "
+ "key, whether it is installed, which downloads qualify and the recommendation.",
+ _obj(),
+ "safe",
+ _roles,
+ ),
+ _s(
+ "lm_recommendations",
+ "The curated shortlist ranked for this machine with fit verdicts and the "
+ "proven / new_little_tested / stale label per entry.",
+ _obj(),
+ "safe",
+ _recommendations,
+ ),
+ _s(
+ "lm_catalog_search",
+ "Search the public Ollama library (ollama.com).",
+ _obj(
+ {
+ "query": {"type": "string"},
+ "sort": {"type": "string", "enum": ["popular", "newest"]},
+ "capability": {
+ "type": "string",
+ "enum": ["tools", "vision", "embedding", "thinking"],
+ },
+ "limit": {"type": "integer", "minimum": 1, "maximum": 50},
+ }
+ ),
+ "safe",
+ _catalog_search,
+ ),
+ _s(
+ "lm_catalog_tags",
+ "Every tag of one library model with its size and fit verdict for this machine.",
+ _obj({"model": _MODEL}, ("model",)),
+ "safe",
+ _catalog_tags,
+ ),
+ _s(
+ "lm_hf_search",
+ "Search GGUF repositories on Hugging Face (only when the user enabled it).",
+ _obj(
+ {
+ "query": {"type": "string"},
+ "sort": {"type": "string", "enum": ["downloads", "lastModified", "trendingScore"]},
+ "limit": {"type": "integer", "minimum": 1, "maximum": 100},
+ }
+ ),
+ "safe",
+ _hf_search,
+ ),
+ _s(
+ "lm_benchmarks",
+ "The benchmark table behind the proven / new labels (cached seven days). "
+ "refresh=true rebuilds it from the web inside a guided run.",
+ _obj({"refresh": {"type": "boolean"}}),
+ "safe",
+ _benchmarks,
+ ),
+ _s(
+ "lm_pull_status",
+ "Progress of one download.",
+ _obj({"model": _MODEL}, ("model",)),
+ "safe",
+ _pull_status,
+ ),
+ _s(
+ "lm_server_log",
+ "The last lines of the Ollama server log Jarvis writes.",
+ _obj({"lines": {"type": "integer", "minimum": 1, "maximum": 200}}),
+ "safe",
+ _server_log,
+ ),
+ _s(
+ "lm_env_guide",
+ "The OLLAMA_* environment variables that matter (models dir, host, keep-alive) and how "
+ "to set each on this OS — advice only, nothing is applied.",
+ _obj(),
+ "safe",
+ _env_guide,
+ ),
+ _s(
+ "lm_suggested_options",
+ "An advisory option profile (num_ctx, num_gpu, …) for one installed model on this "
+ "machine, with one reason per knob. Only these keys may be set with "
+ "lm_set_model_options.",
+ _obj({"model": _MODEL}, ("model",)),
+ "safe",
+ _suggested_options,
+ ),
+ _s(
+ "lm_test_plan",
+ "Run the end-to-end test: server probe, one real generation per configured role, an "
+ "embedding round trip, the voice probe when a managed voice server exists. Returns a "
+ "per-role table with ok / error statuses.",
+ _obj(
+ {
+ "roles": {
+ "type": "array",
+ "items": {"type": "string"},
+ "description": "Subset of chat, voice, tools_screen, deep, embedding.",
+ }
+ }
+ ),
+ "safe",
+ _test_plan,
+ ),
+)
+
+ACTION_TOOLS: Final[tuple[ToolSpec, ...]] = (
+ _s(
+ "lm_install_ollama",
+ "Install Ollama on this machine (winget / installer / install.sh). Starts in the "
+ "background; follow it with lm_server_status.",
+ _obj(),
+ "ask",
+ _install_ollama,
+ lambda _a: "Install Ollama",
+ ),
+ _s(
+ "lm_start_server",
+ "Start the Ollama server.",
+ _obj(),
+ "ask",
+ _start_server,
+ lambda _a: "Start the Ollama server",
+ ),
+ _s(
+ "lm_stop_server",
+ "Stop the Ollama server Jarvis started (never one started elsewhere).",
+ _obj(),
+ "ask",
+ _stop_server,
+ lambda _a: "Stop the Ollama server",
+ ),
+ _s(
+ "lm_pull",
+ "Download a model and follow the download, returning progress lines. Long downloads "
+ "hand back 'still downloading'; poll lm_pull_status then.",
+ _obj({"model": _MODEL, "max_wait_s": {"type": "number"}}, ("model",)),
+ "ask",
+ _pull,
+ lambda a: f"Download {a.get('model', '')}",
+ ),
+ _s(
+ "lm_set_role",
+ "Persist which installed model serves a role. Reports drift_guarded=false when the "
+ "config baseline could not be updated (the pick may then be reverted).",
+ _obj({"role": _ROLE, "model": _MODEL}, ("role", "model")),
+ "ask",
+ _set_role,
+ lambda a: f"Use {a.get('model', '')} for {a.get('role', '')}",
+ ),
+ _s(
+ "lm_set_model_options",
+ "Persist per-model options — only keys lm_suggested_options returned for that model.",
+ _obj(
+ {
+ "model": _MODEL,
+ "options": {"type": "object", "description": "num_ctx, num_gpu, … values."},
+ },
+ ("model", "options"),
+ ),
+ "ask",
+ _set_model_options,
+ lambda a: f"Tune {a.get('model', '')}",
+ ),
+ _s(
+ "lm_install_voice_server",
+ "Install the Jarvis-managed local voice server (background; follow with lm_server_status).",
+ _obj({"brain_model": _MODEL, "voice_model": {"type": "string"}}),
+ "ask",
+ _install_voice_server,
+ lambda _a: "Install the local voice server",
+ ),
+ _s(
+ "lm_apply_voice_stack",
+ "Switch the managed voice server to a brain + voice model pair, run the voice test and "
+ "persist only on success; reports a rollback otherwise.",
+ _obj(
+ {
+ "brain_model": _MODEL,
+ "voice_model": {"type": "string", "description": "A voice profile id."},
+ "language": {"type": "string"},
+ },
+ ("brain_model", "voice_model"),
+ ),
+ "ask",
+ _apply_voice_stack,
+ lambda a: f"Voice stack: {a.get('brain_model', '')} + {a.get('voice_model', '')}",
+ ),
+ _s(
+ "lm_unload",
+ "Free the memory a loaded model holds (it reloads on the next request).",
+ _obj({"model": _MODEL}, ("model",)),
+ "monitor",
+ _unload,
+ lambda a: f"Unload {a.get('model', '')}",
+ ),
+)
+
+
+def tool_specs(cfg: Any) -> tuple[ToolSpec, ...]:
+ """The specs offered for ``cfg`` — HF search only when the user enabled it."""
+ from jarvis.core.config import ollama_hf_enabled
+
+ hf = ollama_hf_enabled(cfg) if cfg is not None else False
+ reads = tuple(s for s in READ_TOOLS if hf or s.name != "lm_hf_search")
+ return reads + ACTION_TOOLS
+
+
+def build_tools(
+ cfg: Any,
+ *,
+ root: str,
+ transport: Any = None,
+ search_fn: Callable[[str], Any] | None = None,
+) -> dict[str, Tool]:
+ """The assistant's tools for one turn, keyed by name.
+
+ ``root`` is the Ollama server root the section talks to; ``transport``
+ the httpx test seam; ``search_fn`` (the ``search_web`` call) lets
+ ``lm_benchmarks`` refresh the table — without it the table is read-only.
+ """
+ env = _Env(cfg=cfg, root=root, transport=transport, search_fn=search_fn)
+ return {spec.name: LocalModelsTool(spec, env) for spec in tool_specs(cfg)}
diff --git a/tests/unit/local_models/test_assistant_tools.py b/tests/unit/local_models/test_assistant_tools.py
new file mode 100644
index 0000000000..4529a6197f
--- /dev/null
+++ b/tests/unit/local_models/test_assistant_tools.py
@@ -0,0 +1,284 @@
+"""The assistant's tools: allowed tiers only, no delete, ask-tier through the executor.
+
+Every action tool is exercised through a REAL ``ToolExecutor`` (bus, tier
+evaluator, approval workflow — no mocks) on the ``interactive`` surface, so
+the approval card the panel auto-answers is a genuine ticket, not a
+convention.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from pathlib import Path
+from uuid import uuid4
+
+import pytest
+
+from jarvis.core import config as cfg_mod
+from jarvis.core.bus import EventBus
+from jarvis.core.config import BrainProviderConfig, JarvisConfig, SafetyConfig
+from jarvis.core.events import ActionApprovalRequired, ActionDenied, ActionExecuted
+from jarvis.core.protocols import ExecutionContext
+from jarvis.local_models import assistant_prompt, assistant_tools
+from jarvis.local_models.assistant_tools import ALLOWED_TIERS, TOOL_PREFIX, build_tools
+from jarvis.safety.approval import ApprovalWorkflow
+from jarvis.safety.approval_surface import INTERACTIVE
+from jarvis.safety.risk_tier import RiskTierEvaluator
+from jarvis.safety.tool_executor import APPROVAL_DENIED_PREFIX, ToolExecutor
+from tests.fakes.fake_ollama_server import FakeOllamaServer
+
+ROOT = "http://fake-ollama:11434"
+
+ASK_TOOLS = {
+ "lm_install_ollama",
+ "lm_start_server",
+ "lm_stop_server",
+ "lm_pull",
+ "lm_set_role",
+ "lm_set_model_options",
+ "lm_install_voice_server",
+ "lm_apply_voice_stack",
+}
+
+
+def _cfg(*, hf: bool = False, **picks: str) -> JarvisConfig:
+ cfg = JarvisConfig()
+ cfg.brain.providers["ollama"] = BrainProviderConfig(
+ model=picks.get("chat", ""),
+ tool_model=picks.get("tools_screen", ""),
+ deep_model=picks.get("deep", ""),
+ base_url=ROOT,
+ hf_enabled=hf,
+ )
+ cfg.ultrawiki.embedding_provider = "ollama"
+ cfg.ultrawiki.embedding_model = picks.get("embedding", "")
+ return cfg
+
+
+def _server() -> FakeOllamaServer:
+ fake = FakeOllamaServer()
+ fake.add("qwen3.5:4b", size=3_400_000_000, capabilities=("completion", "tools", "vision"))
+ fake.add("embeddinggemma", size=600_000_000, capabilities=("embedding",), embed_dim=768)
+ fake.load("qwen3.5:4b")
+ return fake
+
+
+def _ctx() -> ExecutionContext:
+ return ExecutionContext(trace_id=uuid4(), user_utterance="", config={}, memory_read=None)
+
+
+def _executor(timeout_s: float = 5.0) -> tuple[ToolExecutor, EventBus]:
+ bus = EventBus()
+ executor = ToolExecutor(
+ bus,
+ RiskTierEvaluator(SafetyConfig()),
+ ApprovalWorkflow(bus, timeout_s=timeout_s),
+ default_timeout_s=timeout_s,
+ )
+ return executor, bus
+
+
[email protected](autouse=True)
+def _data_dir(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ monkeypatch.setattr(cfg_mod, "DATA_DIR", tmp_path)
+ return tmp_path
+
+
+# ------------------------------------------------------------ the tool set
+
+
+def test_every_tool_has_an_allowed_tier_and_the_prefix() -> None:
+ tools = build_tools(_cfg(hf=True), root=ROOT)
+ assert tools, "no tools built"
+ for name, tool in tools.items():
+ assert name == tool.name
+ assert name.startswith(TOOL_PREFIX), name
+ assert tool.risk_tier in ALLOWED_TIERS, (name, tool.risk_tier)
+ assert tool.schema.get("type") == "object"
+ assert tool.description
+ assert {n for n, t in tools.items() if t.risk_tier == "ask"} == ASK_TOOLS
+ assert {n for n, t in tools.items() if t.risk_tier == "monitor"} == {"lm_unload"}
+ assert "lm_test_plan" in tools and tools["lm_test_plan"].risk_tier == "safe"
+
+
+def test_no_delete_tool_and_nothing_writes_the_brain_primary() -> None:
+ tools = build_tools(_cfg(hf=True), root=ROOT)
+ for name in tools:
+ assert not any(word in name for word in ("delete", "remove", "rm_", "uninstall")), name
+ source = inspect.getsource(assistant_tools)
+ assert "set_brain_primary" not in source
+ assert "delete_model" not in source
+ assert "switch_provider" not in source
+
+
+def test_hf_search_is_offered_only_when_enabled() -> None:
+ assert "lm_hf_search" not in build_tools(_cfg(hf=False), root=ROOT)
+ assert "lm_hf_search" in build_tools(_cfg(hf=True), root=ROOT)
+
+
+def test_describe_args_is_the_card_summary() -> None:
+ tools = build_tools(_cfg(), root=ROOT)
+ assert tools["lm_pull"].describe_args({"model": "qwen3.5:4b"}) == { # type: ignore[attr-defined]
+ "summary": "Download qwen3.5:4b"
+ }
+ assert tools["lm_set_role"].describe_args({"role": "chat", "model": "x"}) == { # type: ignore[attr-defined]
+ "summary": "Use x for chat"
+ }
+ assert tools["lm_inventory"].describe_args({}) == {} # type: ignore[attr-defined]
+
+
+# ------------------------------------------------------------ reads through the executor
+
+
+async def test_safe_reads_run_through_the_executor_on_the_fake_server() -> None:
+ fake = _server()
+ tools = build_tools(_cfg(), root=ROOT, transport=fake.transport())
+ executor, _bus = _executor()
+
+ inventory = await executor.execute(
+ tools["lm_inventory"], args={}, config_snapshot={"approval_surface": INTERACTIVE}
+ )
+ assert inventory.success, inventory.error
+ names = {row["name"] for row in inventory.output["models"]}
+ assert names == {"qwen3.5:4b", "embeddinggemma"}
+ assert [r["name"] for r in inventory.output["running"]] == ["qwen3.5:4b"]
+
+ status = await executor.execute(tools["lm_server_status"], args={})
+ assert status.success, status.error
+ assert status.output["probe"]["ok"] is True
+ assert status.output["voice"]["status"] is None
+
+
+async def test_test_plan_tool_reports_per_role() -> None:
+ fake = _server()
+ tools = build_tools(_cfg(embedding="embeddinggemma"), root=ROOT, transport=fake.transport())
+ executor, _bus = _executor()
+ result = await executor.execute(tools["lm_test_plan"], args={"roles": ["embedding"]})
+ assert result.success, result.error
+ assert result.output["roles"]["embedding"]["status"] == "ok"
+ assert result.output["overall"] == "ok"
+
+
+async def test_a_failing_handler_is_an_honest_tool_error_not_an_exception() -> None:
+ fake = _server()
+ fake.offline = True
+ tools = build_tools(_cfg(), root=ROOT, transport=fake.transport())
+ result = await tools["lm_inventory"].execute({}, _ctx())
+ assert result.success is False
+ assert result.error and "OllamaServerError" in result.error
+
+
+# ------------------------------------------------------------ ask tier = a real ticket
+
+
[email protected]("name", sorted(ASK_TOOLS))
+async def test_ask_tools_raise_an_interactive_ticket_and_stop_on_denial(name: str) -> None:
+ fake = _server()
+ tools = build_tools(_cfg(), root=ROOT, transport=fake.transport())
+ executor, bus = _executor(timeout_s=5.0)
+ cards: list[ActionApprovalRequired] = []
+ executed: list[ActionExecuted] = []
+
+ async def _on_card(event: ActionApprovalRequired) -> None:
+ cards.append(event)
+ await bus.publish(ActionDenied(trace_id=event.trace_id, reason="user_vetoed"))
+
+ async def _on_executed(event: ActionExecuted) -> None:
+ executed.append(event)
+
+ bus.subscribe(ActionApprovalRequired, _on_card)
+ bus.subscribe(ActionExecuted, _on_executed)
+
+ args = {
+ "model": "qwen3.5:4b",
+ "role": "chat",
+ "options": {"num_ctx": 4096},
+ "brain_model": "qwen3.5:4b",
+ "voice_model": "kokoro",
+ }
+ result = await asyncio.wait_for(
+ executor.execute(tools[name], args=args, config_snapshot={"approval_surface": INTERACTIVE}),
+ timeout=4.0,
+ )
+
+ assert len(cards) == 1, "exactly one approval card"
+ card = cards[0]
+ assert card.tool_name == name and card.risk_tier == "ask" and card.reason == "risk_tier"
+ assert card.expires_at_ns > 0, "an interactive card has a real window"
+ assert result.success is False
+ assert result.error == f"{APPROVAL_DENIED_PREFIX} (user_vetoed)"
+ assert executed == [], "a denied action never runs"
+ # Nothing reached the server for a denied action.
+ assert not any(path in ("/api/pull", "/api/generate") for _m, path, _b in fake.calls)
+
+
+async def test_monitor_tool_runs_without_a_card() -> None:
+ fake = _server()
+ tools = build_tools(_cfg(), root=ROOT, transport=fake.transport())
+ executor, bus = _executor()
+ cards: list[ActionApprovalRequired] = []
+
+ async def _on_card(event: ActionApprovalRequired) -> None:
+ cards.append(event)
+
+ bus.subscribe(ActionApprovalRequired, _on_card)
+ result = await executor.execute(
+ tools["lm_unload"],
+ args={"model": "qwen3.5:4b"},
+ config_snapshot={"approval_surface": INTERACTIVE},
+ )
+ assert result.success, result.error
+ assert cards == []
+ assert fake.models["qwen3.5:4b"].loaded is False
+
+
+async def test_set_model_options_refuses_keys_the_suggestion_did_not_return() -> None:
+ fake = _server()
+ tools = build_tools(_cfg(), root=ROOT, transport=fake.transport())
+ suggested = await tools["lm_suggested_options"].execute({"model": "qwen3.5:4b"}, _ctx())
+ assert suggested.success, suggested.error
+ assert set(suggested.output["options"]) <= set(cfg_mod.OLLAMA_MODEL_OPTION_KEYS)
+
+ result = await tools["lm_set_model_options"].execute(
+ {"model": "qwen3.5:4b", "options": {"not_a_knob": 1}}, _ctx()
+ )
+ assert result.success is False
+ assert "refused: not_a_knob" in (result.error or "")
+
+
+# ------------------------------------------------------------ the prompt
+
+
+async def test_prompt_renders_with_the_fake_server_and_carries_the_contract() -> None:
+ fake = _server()
+ cfg = _cfg(chat="qwen3.5:4b", embedding="embeddinggemma")
+ text = await assistant_prompt.build_system_extra(cfg, root=ROOT, transport=fake.transport())
+
+ assert len(text) < 10_000, len(text)
+ assert "Ollama server: http://fake-ollama:11434 — running, version 0.32.15" in text
+ assert "- qwen3.5:4b · 3.2 GB · completion,tools,vision · ctx 262144" in text
+ assert "chat · completion · qwen3.5:4b · yes · brain.providers.ollama.model" in text
+ assert "embedding · embedding · embeddinggemma · yes · ultrawiki.embedding_model" in text
+ assert "tools_screen · tools+vision · not set" in text
+ assert "CURATED SHORTLIST (reviewed " in text
+ assert "qwen3.5:4b · chat · 3.4 · " in text and "· yes · tools+vision" in text
+ assert "new_little_tested" in text or "proven" in text
+ assert "```jarvis-proposal" in text
+ assert "Never delete a model" in text
+ assert "brain_switch" in text
+
+
+async def test_prompt_is_honest_when_the_server_is_down() -> None:
+ fake = _server()
+ fake.offline = True
+ text = await assistant_prompt.build_system_extra(_cfg(), root=ROOT, transport=fake.transport())
+ assert "not answering" in text
+ assert "INSTALLED MODELS\n- unavailable:" in text
+
+
+def test_openers_name_the_contract_and_never_execute_unasked() -> None:
+ for opener in (assistant_prompt.SETUP_OPENER, assistant_prompt.DIAGNOSE_OPENER):
+ assert "jarvis-proposal" in opener
+ assert "until I confirm" in opener
+ assert "lm_test_plan" in assistant_prompt.TEST_OPENER