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.

fix(voice): give the call every tool its rules name, under readable names (#684)

Ruben Lütkef9b52f2ac85c
diff --git a/jarvis/live/coordination.py b/jarvis/live/coordination.py
index e36c3d2da7..d3335a8bb9 100644
--- a/jarvis/live/coordination.py
+++ b/jarvis/live/coordination.py
@@ -15,15 +15,14 @@ WORK_STATUS_RULE: Final[str] = (
"done or who is waiting for them, call task_status once: it is one board of this "
"call's background tasks, every open coding agent with its workspace's git state, "
"the missions that have not ended and the agent team. For one workspace's agents "
- "or its branch alone, workspace-orchestrate status with that workspace is enough. "
+ "alone, workspace-orchestrate with action status and that workspace is enough. "
"Say the takeaway in a sentence or two and name who "
"needs the user; never read out lists, diffs or code. When the user wants to "
"hear when an agent they started themselves is done, call workspace-orchestrate "
- "watch for it; a "
- "task you sent is reported back on its own. "
- "A workspace's repository is workspace-git: its changed files, its worktrees, a new "
- "worktree when the user asks for one, putting one away or bringing it back, commit, "
- "push and pull request. "
+ "with action watch for it; a task you sent is reported back on its own. "
+ "A workspace's repository is workspace-git, with op state for its branch and "
+ "changed files: also its worktrees, a new worktree when the user asks for one, "
+ "putting one away or bringing it back, commit, push and pull request. "
)
@@ -45,6 +44,19 @@ TEAM_TALK_RULE: Final[str] = (
)
+#: Every tool the rules above call by name. A model that is told to use a tool it
+#: was not given says the tool does not exist, so these are always declared
+#: directly, also under a small model's declaration budget.
+NAMED_TOOLS: Final[tuple[str, ...]] = (
+ "task_status",
+ "workspace-orchestrate",
+ "workspace-git",
+ "show_on_screen",
+ "navigate",
+ "ask_agent",
+)
+
+
def conversation_rules(executor: str) -> str:
"""The speaking model's rules; ``executor`` is what carries out work for it."""
return (
@@ -77,4 +89,10 @@ def conversation_rules(executor: str) -> str:
)
-__all__ = ["ON_SCREEN_RULE", "TEAM_TALK_RULE", "WORK_STATUS_RULE", "conversation_rules"]
+__all__ = [
+ "NAMED_TOOLS",
+ "ON_SCREEN_RULE",
+ "TEAM_TALK_RULE",
+ "WORK_STATUS_RULE",
+ "conversation_rules",
+]
diff --git a/jarvis/live/native.py b/jarvis/live/native.py
index 7757669943..0dae7c182a 100644
--- a/jarvis/live/native.py
+++ b/jarvis/live/native.py
@@ -19,6 +19,7 @@ from jarvis.core.runtime_refs import get_supervisor_tool_gateway
from jarvis.core.tool_budget import VOICE_TOOL_BUDGET_S
from jarvis.cu.direct import COMPUTER_CONTROL_RULES
from jarvis.live.coordination import (
+ NAMED_TOOLS,
ON_SCREEN_RULE,
TEAM_TALK_RULE,
WORK_STATUS_RULE,
@@ -54,18 +55,15 @@ _SESSION_TOOLS = frozenset({
# or ``[voice].realtime_tool_declaration_budget_tokens``, the smaller wins), at
# most this many catalog tools are declared directly; every other tool stays
# reachable through discover_tools/call_tool. A small local model pays a full
-# LLM round per discovery step, so the frequent tools come first. The tools the
-# conversation rules name by name (show_on_screen, ask_agent) stay direct: a
-# small model that does not see a named tool declares it missing instead of
-# discovering it.
+# LLM round per discovery step, so the frequent tools come first. Every tool the
+# conversation rules call by name comes before them: a small model that does
+# not see a named tool declares it missing instead of discovering it.
_DIRECT_TOOL_LIMIT = 12
_DIRECT_TOOL_PREFERENCE = (
- "workspace-orchestrate",
+ *(name for name in NAMED_TOOLS if name not in _SESSION_TOOLS),
"find-app-action",
"run-app-action",
"search_web",
- "show_on_screen",
- "ask_agent",
"open_app",
"take_appshot",
"screen_snapshot",
@@ -87,12 +85,28 @@ def _declared_name(declaration: dict) -> str:
return str(declaration.get("description", "")).split(": ", 1)[0]
-def _fit_declarations(declarations: list[dict], budget_chars: int) -> tuple[dict, ...]:
- """Session built-ins plus a curated direct set that fits ``budget_chars``."""
+def _fit_declarations(
+ declarations: list[dict],
+ budget_chars: int,
+ *,
+ fillers: frozenset[str] | None = None,
+) -> tuple[dict, ...]:
+ """Session built-ins plus a curated direct set that fits ``budget_chars``.
+
+ Slots the preferred tools leave free go to other catalog tools; with
+ ``fillers`` only to those, so a tool with an effect of its own (restarting
+ the app) is never one of a small model's few direct tools by catalog order
+ alone. It stays reachable through discover_tools.
+ """
session = [d for d in declarations if d.get("name") in _SESSION_TOOLS]
rank = {name: index for index, name in enumerate(_DIRECT_TOOL_PREFERENCE)}
catalog = sorted(
- (d for d in declarations if d.get("name") not in _SESSION_TOOLS),
+ (
+ d
+ for d in declarations
+ if d.get("name") not in _SESSION_TOOLS
+ and (fillers is None or _declared_name(d) in rank or _declared_name(d) in fillers)
+ ),
key=lambda d: rank.get(_declared_name(d), len(rank)),
)
used = sum(len(json.dumps(d)) for d in session)
@@ -288,7 +302,12 @@ class NativeLiveVoiceSession(LiveVoiceSession):
budget = self._declaration_budget_tokens()
if budget <= 0:
return tuple(declarations)
- fitted = _fit_declarations(declarations, budget * 4)
+ safe = frozenset(
+ descriptor.name
+ for descriptor in self._tools.catalog()
+ if str(getattr(descriptor, "risk_tier", "")) == "safe"
+ )
+ fitted = _fit_declarations(declarations, budget * 4, fillers=safe)
# AP-30: a trimmed tool set looks exactly like a complete one.
log.info(
"Native voice declares %d of %d tools under a %d-token budget for %s; "
diff --git a/jarvis/live/tools.py b/jarvis/live/tools.py
index 1ea7a5f65b..30aee3be49 100644
--- a/jarvis/live/tools.py
+++ b/jarvis/live/tools.py
@@ -14,6 +14,7 @@ from uuid import UUID, uuid4
from jarvis.brain.cu_gate import CU_VEHICLE_TOOL_NAMES
from jarvis.control.cancel import CancelToken
from jarvis.core.protocols import SupervisorToolGateway, SupervisorToolRequest
+from jarvis.live.coordination import NAMED_TOOLS
from jarvis.live.state import LiveLedger
from jarvis.live.tasks import BackgroundTask, TaskBoard
from jarvis.safety.tool_executor import VOICE_CONFIRM_SENTINEL
@@ -56,16 +57,11 @@ _GO_AHEAD_WORDS = frozenset(
_APPROVAL_LOCALES = ("de", "en", "es", "pt")
_RECENT_SEGMENTS = 4
_REQUEST_TEXT_CHARS = 1200
-# Declared before every other tool so the size budget never drops them.
-# The conversation rules (``coordination.py``) name show_on_screen and
-# ask_agent: a model that is not given a tool it was told to use says it does
-# not exist (live 2026-10-14, a busy catalog sorted it past the budget).
-_PRIORITY_TOOLS = frozenset(
- {
- "workspace-orchestrate", "workspace-git", "find-app-action", "run-app-action",
- "show_on_screen", "ask_agent",
- }
-)
+# Declared before every other tool so the size budget never drops them: the
+# app-steering tools and every tool the conversation rules name. A model that
+# is not given a tool it was told to use says it does not exist (live
+# 2026-10-14, a busy catalog sorted show_on_screen past the budget).
+_PRIORITY_TOOLS = frozenset({"find-app-action", "run-app-action", *NAMED_TOOLS})
# Declared under its canonical name in every mode (see ``declarations``).
_DIRECT_TOOLS = frozenset({"computer", "take_appshot"})
# One screen, one mouse: these never run side by side, and a result that
@@ -127,6 +123,27 @@ def function(name: str, description: str, properties: dict, required: list[str])
}
+def _accepted_arguments(schema: Any) -> str:
+ """One sentence naming a tool's top-level arguments, for a rejected call.
+
+ The validation message alone names what was wrong, not what is right; a
+ small model then repeats the same call (live 2026-10-14: three identical
+ rejected calls in one turn).
+ """
+ properties = schema.get("properties") if isinstance(schema, dict) else None
+ if not isinstance(properties, dict) or not properties:
+ return ""
+ required = set(schema.get("required") or ())
+ parts = []
+ for name, spec in properties.items():
+ part = f"{name} (required)" if name in required else str(name)
+ values = spec.get("enum") if isinstance(spec, dict) else None
+ if isinstance(values, list) and values:
+ part += ": one of " + ", ".join(str(value) for value in values[:20])
+ parts.append(part)
+ return ("Accepted arguments: " + "; ".join(parts))[:600] + ". "
+
+
def _board_section(section: str, output: Any) -> Any:
"""One source's listing as the board shows it; None when it has another shape."""
if section == "coding_agents":
@@ -324,7 +341,7 @@ class LiveTools:
for descriptor in ordered:
if descriptor.name in _DIRECT_TOOLS:
continue
- alias = "jarvis_" + hashlib.sha256(descriptor.name.encode()).hexdigest()[:20]
+ alias = self._alias(descriptor.name)
definition = {
"type": "function",
"name": alias,
@@ -339,6 +356,21 @@ class LiveTools:
definitions.append(definition)
return definitions
+ def _alias(self, name: str) -> str:
+ """The function name a catalog tool is declared under: readable and unique.
+
+ Every provider accepts letters, digits and underscores up to 64
+ characters. The tool's own name stays legible in it: behind opaque
+ hashes a small model confused app-restart with show_on_screen (live
+ 2026-10-14). A name that would collide or not fit keeps a hash suffix.
+ """
+ readable = "jarvis_" + re.sub(r"[^A-Za-z0-9_]", "_", name)
+ owner = self._names.get(readable)
+ if len(readable) <= 64 and owner in (None, name):
+ return readable
+ digest = hashlib.sha256(name.encode()).hexdigest()[:20]
+ return readable[:43] + "_" + digest
+
async def execute(
self, call_id: str, name: str, args: dict, revision: int,
*, replay_result: dict | None = None,
@@ -805,7 +837,11 @@ class LiveTools:
"success": False,
"executed": False,
"retryable": True,
- "error": f"Invalid {field}: {exc.message[:300]}. Correct it and call again.",
+ "error": (
+ f"Invalid {field}: {exc.message[:300]}. "
+ f"{_accepted_arguments(descriptor.input_schema)}"
+ "Correct it and call again."
+ ),
}
trace = uuid4()
from jarvis.core.model_selection import ModelSelection, use_operation_model
diff --git a/tests/contract/test_gpt_live.py b/tests/contract/test_gpt_live.py
index dae8b25ccb..84540d0bcb 100644
--- a/tests/contract/test_gpt_live.py
+++ b/tests/contract/test_gpt_live.py
@@ -2,12 +2,14 @@
import asyncio
import json
+import re
from types import SimpleNamespace
import pytest
from jarvis.core.protocols import SupervisorToolDescriptor, ToolResult
from jarvis.live.config import LiveConfig
+from jarvis.live.coordination import NAMED_TOOLS
from jarvis.live.session import LiveVoiceSession
from jarvis.live.state import LiveLedger, TranscriptFragment
from jarvis.live.tools import LiveTools
@@ -333,6 +335,71 @@ async def test_a_schema_violation_tells_the_model_what_to_fix(ledger):
assert "text" in result["error"]
+async def test_a_rejected_call_names_the_arguments_the_tool_accepts(ledger):
+ # A small model sent {"status": "all"} three times in a row (live 2026-10-14).
+ class Orchestrate(Gateway):
+ def catalog(self):
+ schema = {
+ "type": "object",
+ "additionalProperties": False,
+ "properties": {
+ "action": {"type": "string", "enum": ["status", "watch"]},
+ "workspace": {"type": "string"},
+ },
+ "required": ["action"],
+ }
+ return (SupervisorToolDescriptor("workspace-orchestrate", "Panes", schema, "safe"),)
+
+ runtime = LiveTools(Orchestrate(), ledger, "s", language="en", backend_model="")
+ request = {"name": "workspace-orchestrate", "arguments_json": '{"status": "all"}'}
+ result = await runtime.execute("bad", "call_tool", request, 0)
+ assert result["executed"] is False and result["retryable"] is True
+ assert "Accepted arguments: action (required): one of status, watch; workspace." in (
+ result["error"]
+ )
+
+
+async def test_catalog_tools_are_declared_under_readable_unique_names(ledger):
+ # Behind opaque hashes a small model confused app-restart with show_on_screen.
+ long_name = "plugin." + "x" * 80
+
+ class Named(Gateway):
+ def catalog(self):
+ return tuple(
+ SupervisorToolDescriptor(name, f"Does {name}", {"type": "object"}, "safe")
+ for name in ("app-restart", "app_restart", "show_on_screen", long_name)
+ )
+
+ runtime = LiveTools(Named(), ledger, "s", language="en", backend_model="")
+ names = {
+ runtime._names[d["name"]]: d["name"]
+ for d in runtime.declarations()
+ if d["name"] in runtime._names
+ }
+ assert names["show_on_screen"] == "jarvis_show_on_screen"
+ assert names["app-restart"] == "jarvis_app_restart"
+ # The second spelling of the same readable name keeps its own alias.
+ assert names["app_restart"].startswith("jarvis_app_restart_")
+ assert len(names[long_name]) <= 64
+ assert all(re.fullmatch(r"[A-Za-z0-9_]{1,64}", alias) for alias in names.values())
+ assert len(set(names.values())) == 4
+ # The same aliases on every declaration of the session.
+ aliases = set(names.values())
+ again = {runtime._names[d["name"]] for d in runtime.declarations() if d["name"] in aliases}
+ assert again == set(names)
+
+
+def test_an_argument_hint_is_left_out_for_a_schema_without_properties():
+ from jarvis.live.tools import _accepted_arguments
+
+ assert _accepted_arguments({"type": "object"}) == ""
+ assert _accepted_arguments(None) == ""
+ long = {"properties": {f"field_{index}": {"type": "string"} for index in range(200)}}
+ assert len(_accepted_arguments(long)) <= 602
+
+
@pytest.mark.asyncio
async def test_yes_to_a_pending_approval_does_not_hang_up(ledger):
gateway = _ApprovalGateway()
@@ -1144,17 +1211,17 @@ def test_steering_tools_are_declared_before_the_size_budget_runs_out(ledger, fil
)
steering = tuple(
SupervisorToolDescriptor(name, "Steers the call", {"type": "object"}, "monitor")
- for name in (
- "workspace-orchestrate", "workspace-git", "show_on_screen", "ask_agent",
- )
+ for name in (*NAMED_TOOLS, "find-app-action", "run-app-action")
+ if name != "task_status"
)
return (*filler, *steering)
runtime = LiveTools(Crowded(), ledger, "s", language="en", backend_model="")
- declared = {runtime._names.get(d["name"]) for d in runtime.declarations()}
+ declarations = runtime.declarations()
+ declared = {runtime._names.get(d["name"], d["name"]) for d in declarations}
# The conversation rules name these tools; a model that is not given a
# named tool tells the user it does not exist.
- assert {"workspace-orchestrate", "workspace-git", "show_on_screen", "ask_agent"} <= declared
+ assert {*NAMED_TOOLS, "find-app-action", "run-app-action"} <= declared
@pytest.mark.asyncio
diff --git a/tests/unit/live/test_coordination.py b/tests/unit/live/test_coordination.py
index 47c3b810ee..2911445dea 100644
--- a/tests/unit/live/test_coordination.py
+++ b/tests/unit/live/test_coordination.py
@@ -3,11 +3,36 @@
from __future__ import annotations
import inspect
+import re
from jarvis.core.agent_brief import AGENT_BRIEF_RULE
from jarvis.live import native
from jarvis.live.config import LiveConfig
-from jarvis.live.coordination import WORK_STATUS_RULE, conversation_rules
+from jarvis.live.coordination import (
+ NAMED_TOOLS,
+ ON_SCREEN_RULE,
+ TEAM_TALK_RULE,
+ WORK_STATUS_RULE,
+ conversation_rules,
+)
+
+_RULES = WORK_STATUS_RULE + ON_SCREEN_RULE + TEAM_TALK_RULE + conversation_rules("your tools")
+# Hyphenated or underscored words in the rules that are plain English, not tools.
+_NOT_TOOLS = {"multi-step", "trade-offs"}
+
+
+def test_every_tool_the_rules_name_is_listed_and_every_listed_tool_is_named():
+ named_in_text = set(re.findall(r"\b[a-z]+(?:[-_][a-z]+)+\b", _RULES)) - _NOT_TOOLS
+ assert named_in_text <= set(NAMED_TOOLS)
+ for name in NAMED_TOOLS:
+ assert re.search(rf"\b{re.escape(name)}\b", _RULES), name
+
+
+def test_the_rules_spell_out_the_argument_a_small_model_has_to_pass():
+ # "workspace-orchestrate status" read as an argument named status (live 2026-10-14).
+ assert "workspace-orchestrate with action status" in WORK_STATUS_RULE
+ assert "workspace-orchestrate with action watch" in WORK_STATUS_RULE
+ assert "workspace-git, with op state" in WORK_STATUS_RULE
def _wire(**profile) -> dict:
diff --git a/tests/unit/live/test_native_live_fixes.py b/tests/unit/live/test_native_live_fixes.py
index 471478731f..83dcab6153 100644
--- a/tests/unit/live/test_native_live_fixes.py
+++ b/tests/unit/live/test_native_live_fixes.py
@@ -16,6 +16,7 @@ import pytest
from jarvis.core.protocols import SupervisorToolDescriptor, ToolResult
from jarvis.cu.direct import tool_schema
from jarvis.live import native, runtime
+from jarvis.live.coordination import NAMED_TOOLS
from jarvis.live.native import NativeLiveVoiceSession
from jarvis.live.state import LiveLedger
from jarvis.live.tools import LiveTools
@@ -579,6 +580,8 @@ async def test_declarations_respect_the_providers_budget(call, make_provider):
@both_providers
@pytest.mark.asyncio
async def test_tools_the_rules_name_stay_direct_under_a_budget(call, make_provider):
+ # A crowded install: every preferred tool is there, so the direct limit bites.
+ names = {*native._DIRECT_TOOL_PREFERENCE, *NAMED_TOOLS} - native._SESSION_TOOLS
named = tuple(
SupervisorToolDescriptor(
name,
@@ -586,16 +589,46 @@ async def test_tools_the_rules_name_stay_direct_under_a_budget(call, make_provid
{"type": "object", "properties": {"value": {"type": "string"}}},
"safe",
)
- for name in ("show_on_screen", "ask_agent")
+ for name in sorted(names)
)
provider = make_provider()
live = call(provider, gateway=FakeToolGateway(catalog_of(30) + named))
await live.start()
try:
- described = {
- tool["description"].split(": ", 1)[0] for tool in provider.opened_with[0].tools
- }
- assert {"show_on_screen", "ask_agent"} <= described
+ tools = provider.opened_with[0].tools
+ described = {tool["description"].split(": ", 1)[0] for tool in tools}
+ described |= {tool["name"] for tool in tools}
+ assert set(NAMED_TOOLS) <= described
+ finally:
+ await live.session.end()
+
+
+@both_providers
+async def test_free_direct_slots_go_only_to_safe_tools(call, make_provider):
+ # A sparse install left slots free, and catalog order handed one to app-restart.
+ def tool(name, risk):
+ schema = {"type": "object", "properties": {"value": {"type": "string"}}}
+ return SupervisorToolDescriptor(name, f"Does {name}.", schema, risk)
+
+ catalog = (
+ tool("app-restart", "ask"),
+ tool("a-delete-all", "monitor"),
+ tool("b-safe-lookup", "safe"),
+ tool("search_web", "safe"),
+ )
+ provider = make_provider()
+ live = call(provider, gateway=FakeToolGateway(catalog))
+ await live.start()
+ try:
+ tools = provider.opened_with[0].tools
+ described = {tool["description"].split(": ", 1)[0] for tool in tools}
+ if provider.tool_declaration_budget_tokens:
+ assert {"search_web", "b-safe-lookup"} <= described
+ assert not {"app-restart", "a-delete-all"} & described
+ else:
+ # Without a budget every tool is declared; nothing is trimmed.
+ assert {"app-restart", "a-delete-all", "b-safe-lookup"} <= described
finally:
await live.session.end()