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.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""Router-tier society tools: ``delegate-to-agent`` and ``society-status``.
The voice front door of the agent society (MASTERPLAN §3.2, agent-definition
§4.1). Both tools answer inside the 5-second voice budget:
* ``delegate-to-agent`` appends ONE ``ASSIGN`` envelope to the society board
on behalf of Jarvis (the lead) and returns a spoken acknowledgement at
once. The scheduler — trusted Python — decides whether and how the target
starts working; the tool never spawns anything itself and never waits for
completion. Completions re-enter voice through the existing announcement
path. Risk ``monitor``: a dispatch like ``spawn-worker``, never in a worker
set (AP-5/AP-14).
* ``society-status`` reads the roster and the last events — no model call,
no spend — and answers "what is Scout doing?" (risk ``safe``).
Both reach the runtime through a lazy resolver (AD-OC1): the society is
built on first use by the server, after the brain exists.
"""
from __future__ import annotations
import asyncio
import logging
from collections.abc import Callable
from typing import Any, Final
from dodaios.core.agent_brief import AGENT_BRIEF_RULE
from dodaios.core.delegation import origin_metadata
from dodaios.core.protocols import ExecutionContext, ToolResult
from dodaios.i18n import catalog as i18n_catalog
from dodaios.society.agent_names import AgentLookup, coding_pane_hint, lookup_agent
from dodaios.society.communication import REPLY_POLICY_SCHEMA, select_reply_policy
from dodaios.society.display_name import display_name
log = logging.getLogger(__name__)
RuntimeResolver = Callable[[], Any | None]
_ACK: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.ack")
_QUIET_ACK: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.quiet_ack")
_ERROR_ACK: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.error_ack")
_QUEUED: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.queued")
_NO_AGENT: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.no_agent")
_ASK_AGENT: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.ask_agent")
_OR: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.or")
_AVAILABLE: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.available")
_NO_FIT: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.no_fit")
_REFUSED: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.refused")
_NOT_READY: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.not_ready")
_STATUS_IDLE: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.status_idle")
_STATUS_WORKING: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.status_working")
_STATUS_LAST: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.status_last")
_ROSTER: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.roster")
_EMPTY_ROSTER: Final[dict[str, str]] = i18n_catalog.table("tools.delegate.empty_roster")
def _lang(args: dict[str, Any], ctx: Any) -> str:
"""The turn's output language: ``ctx.config["output_language"]`` as the
tool-use loop stamps it (decided once per turn by ``turn_language.py``),
else a ``turn_language`` argument, else the ambient answer language. This
layer never re-derives a language from the utterance."""
config = getattr(ctx, "config", None) or {}
value = (
str(
(config.get("output_language") if isinstance(config, dict) else "")
or args.get("turn_language")
or ""
)
.strip()
.lower()
)
if not value:
try:
from dodaios.voice.action_phrases import resolve_ambient_language
value = resolve_ambient_language()
except Exception: # noqa: BLE001 — a spoken fallback beats a crash on the voice path
value = "en"
return value if value in _ACK else "en"
class DelegateToAgentTool:
"""Hand a task to a named society agent; acknowledge at once."""
name: str = "delegate_to_agent"
risk_tier: str = "monitor"
description: str = (
"Hand a task to one of the user's named agents (their agent society, listed on your "
"team card): 'let Scout research X', 'Mailbox, answer the invoice mail', 'give that "
"to the team'. Use when a background task fits the persistent team; leave `agent` "
"empty to let the lead pick the agent whose hands fit the task. The agent works in "
"the background; you acknowledge now and its result follows reply_policy. "
"Stay available for conversation while it runs; completion is delivered asynchronously. "
"Never for inventory/status questions or tasks the user wants done right here. "
"Not for coding panes in the Agentic IDE (T1, or a named Claude Code / Codex "
"session): those go through workspace-orchestrate. Pass the agent's name as heard; "
"the app matches misheard names and, when unsure, returns needs_clarification with "
"a question to ask before calling again. "
"Turn the user's intent into an actionable brief: objective, known target, relevant "
"context, scope, constraints and completion evidence. Do not merely paraphrase or "
"invent facts. Include context and completion_criteria so the agent can act independently. "
"Select reply_policy=always for requested findings, on_error for work without a "
"requested success report, none only for explicit silence. Report the acknowledgement "
"and state exactly. Keep the "
"returned assignment_id and trace_id for society_status; never speak those ids."
)
schema: dict[str, Any] = {
"type": "object",
"properties": {
"agent": {
"type": "string",
"description": (
"The agent's name as the user said it; empty when the user did not "
"name one (the best-fitting agent is picked from the task)."
),
},
"task": {
"type": "string",
"description": (
"An actionable objective and scope faithful to the user's intent, "
"not just a paraphrase. " + AGENT_BRIEF_RULE
),
},
"reply_policy": REPLY_POLICY_SCHEMA,
"context": {
"type": "string",
"description": "Relevant prior decisions, constraints and facts; omit secrets.",
},
"completion_criteria": {
"type": "string",
"description": "Required output and the evidence needed to establish completion.",
},
"refs": {
"type": "array",
"items": {"type": "string"},
"description": "Relevant file, wiki or conversation references.",
},
},
"required": ["task"],
}
is_action_tool: bool = True
def __init__(self, *, runtime_resolver: RuntimeResolver) -> None:
self._resolve = runtime_resolver
async def execute(self, args: dict[str, Any], ctx: ExecutionContext) -> ToolResult:
lang = _lang(args, ctx)
target_key = str(args.get("agent") or "").strip()
task = str(args.get("task") or "").strip()
if not task:
return ToolResult(success=False, output=_NOT_READY[lang], error="task required")
runtime = await self._runtime()
if runtime is None:
return ToolResult(success=False, output=_NOT_READY[lang], error="society unavailable")
match_info = None
if target_key:
found = await lookup_agent(runtime, target_key, context=task, surface=self.name)
if found.agent is None:
return await _unresolved(found, lang)
target, match_info = found.agent, found.match_info()
else:
target = runtime.pick_agent(task)
if target is None:
return ToolResult(success=False, output=_NO_FIT[lang], error="no_agent_fits")
from dodaios.society.events import MsgType
try:
policy = select_reply_policy(args.get("reply_policy"), MsgType.ASSIGN)
except (TypeError, ValueError) as exc: # Invalid policy returns a failed tool result.
return ToolResult(success=False, output=None, error=str(exc))
context = str(args.get("context") or "").strip()
criteria = str(args.get("completion_criteria") or "").strip()
brief = task
if context:
brief += "\n\nRelevant context:\n" + context
if criteria:
brief += "\n\nCompletion criteria:\n" + criteria
refs = args.get("refs") or []
if not isinstance(refs, list) or any(not isinstance(ref, str) for ref in refs):
return ToolResult(success=False, output=None, error="refs must be a list of strings")
if len(brief) > 20_000 or len(refs) > 20:
return ToolResult(success=False, output=None, error="assignment context exceeds limit")
env = await runtime.say(
from_agent=runtime.lead_id,
to_agent=target.agent_id,
text=brief,
trace_id=f"voice:{ctx.trace_id.hex[:12]}",
msg_type=MsgType.ASSIGN,
payload={
"text": brief, "refs": refs, "reply_policy": policy,
**origin_metadata(language=lang),
},
)
# The scheduler answered synchronously on the same trace: a CLAIM
# means the agent took it, a VETO says why not — say so, no waiting.
outcome = None
for event in await runtime.store.events_for_trace(env.trace_id):
if event.parent_event_id == env.event_id and event.msg_type in (
MsgType.CLAIM,
MsgType.VETO,
):
outcome = event
break
tracking = {
"agent_id": target.agent_id,
"agent_name": display_name(target),
"assignment_id": env.event_id,
"trace_id": env.trace_id,
"reply_policy": policy,
# Said differently than it is spelled: the reply names the agent
# that was actually reached, so the user hears who got the task.
**({"name_match": match_info} if match_info else {}),
}
if outcome is not None and outcome.msg_type is MsgType.VETO:
reason = str(outcome.payload.get("text") or outcome.payload.get("reason") or "")
return ToolResult(
success=False,
output={
**tracking,
"state": "refused",
"acknowledgement": _REFUSED[lang].format(
name=display_name(target), reason=reason
),
},
error=str(outcome.payload.get("reason") or "vetoed"),
)
ack = _ACK if policy == "always" else _ERROR_ACK if policy == "on_error" else _QUIET_ACK
return ToolResult(
success=True,
output={
**tracking,
"state": "running" if outcome is not None else "recorded",
"acknowledgement": (ack if outcome is not None else _QUEUED)[lang].format(
name=display_name(target),
),
},
artifacts=(
f"agent:{target.agent_id}",
f"assignment:{env.event_id}",
f"trace:{env.trace_id}",
),
)
async def _runtime(self) -> Any | None:
try:
runtime = self._resolve()
if runtime is not None:
prepare = getattr(runtime, "prepare_context", None)
if callable(prepare):
if not await prepare():
return None
else:
await runtime.ensure_started()
except Exception: # noqa: BLE001 — a missing society is a spoken "not ready"
log.warning("delegate_to_agent: society runtime unavailable", exc_info=True)
return None
return runtime
def _join(names: list[str], lang: str) -> str:
if len(names) <= 1:
return "".join(names)
return ", ".join(names[:-1]) + _OR[lang] + names[-1]
async def _unresolved(found: AgentLookup, lang: str) -> ToolResult:
"""The honest answer for a name no agent clearly carries: ask, or list who exists.
Never a silent "unknown": a close name becomes a question, and a name that
is no Jarvis agent but a coding pane in the Agentic IDE says so, because
the two kinds of agent are reached through different tools.
"""
if found.decision == "ask" and found.candidates:
names = [display_name(a) for a in found.candidates]
return ToolResult(
success=False,
output={
"status": "needs_clarification",
"heard": found.heard,
"candidates": names,
"question": _ASK_AGENT[lang].format(names=_join(names, lang)),
"next_step": "Ask the user this question; call again with the confirmed name.",
},
error="target_ambiguous",
)
reply = _NO_AGENT[lang].format(target=found.heard)
names = found.available_names()
roster = _AVAILABLE[lang].format(names=", ".join(names)) if names else _EMPTY_ROSTER[lang]
reply += " " + roster
hint = await asyncio.to_thread(coding_pane_hint, found.heard)
if hint:
panes = ", ".join(f"{p['agent']} ({p['workspace']})" for p in hint["panes"])
reply += (
f" Note: '{found.heard}' matches a coding pane in the Agentic IDE ({panes}), not a "
"Dodaios agent - reach it with workspace-orchestrate (resolve, then send)."
)
return ToolResult(success=False, output=reply, error="target_unknown")
async def _status_target(runtime: Any, target_key: str, lang: str) -> Any:
"""The agent a status question names, or the ``ToolResult`` that explains why not."""
found = await lookup_agent(runtime, target_key, surface="society_status")
if found.agent is not None:
return found.agent
return await _unresolved(found, lang)
# How much of an agent's newest note the team board repeats.
_BOARD_NOTE_CHARS = 200
class SocietyStatusTool:
"""What an agent (or the whole team) is doing — read-only, no model call."""
name: str = "society_status"
risk_tier: str = "safe"
description: str = (
"Answer 'what is <agent> doing?', 'is Scout done?', 'who is on the team?' from the "
"agent society's board. Read-only. Pass the agent's name, or nothing for the team. "
"Set details=true for responsibilities, capabilities, state and recorded activity/cost "
"statistics (these are observations, not quality scores). Set board=true for one "
"short row per agent: working or idle, and its newest note. Pass assignment_id "
"to inspect that exact assignment; trace_id is optional. If prior tool ids are "
"no longer in context, use agent + latest_assignment=true to retrieve the newest "
"assignment you sent that agent from the stored board, including its task and "
"result. This means newest assignment, not an arbitrary recent event. If 'that task' "
"could mean an older task or several agents, clarify the agent/task first."
)
schema: dict[str, Any] = {
"type": "object",
"properties": {
"agent": {"type": "string", "description": "An agent's name; omit for the team."},
"details": {"type": "boolean", "description": "Include actual roster and evidence."},
"board": {
"type": "boolean",
"description": "One short row per agent: working or idle, and its newest note.",
},
"assignment_id": {"type": "string", "description": "Assignment event id."},
"trace_id": {"type": "string", "description": "Optional expected assignment trace."},
"latest_assignment": {
"type": "boolean",
"description": (
"With agent: inspect the newest assignment you sent. "
"Do not combine with assignment_id."
),
},
},
}
def __init__(self, *, runtime_resolver: RuntimeResolver) -> None:
self._resolve = runtime_resolver
async def execute(self, args: dict[str, Any], ctx: ExecutionContext) -> ToolResult:
lang = _lang(args, ctx)
try:
from dodaios.society.events import MsgType
runtime = self._resolve()
if runtime is not None:
prepare = getattr(runtime, "prepare_context", None)
if callable(prepare):
if not await prepare():
runtime = None
else:
await runtime.ensure_started()
except Exception: # noqa: BLE001 — see DelegateToAgentTool._runtime
log.warning("society_status: runtime resolver failed", exc_info=True)
runtime = None
if runtime is None:
return ToolResult(success=False, output=_NOT_READY[lang], error="society unavailable")
assignment_id = str(args.get("assignment_id") or "").strip()
trace_id = str(args.get("trace_id") or "").strip()
target_key = str(args.get("agent") or "").strip()
latest_assignment = args.get("latest_assignment") is True
if assignment_id or trace_id or latest_assignment:
if latest_assignment and assignment_id:
return ToolResult(
success=False, output=None, error="choose assignment_id or latest_assignment"
)
if latest_assignment:
if not target_key:
return ToolResult(success=False, output=None, error="agent required")
target = await _status_target(runtime, target_key, lang)
if isinstance(target, ToolResult):
return target
assignment = await runtime.store.latest_assignment_for_agent(
target.agent_id,
from_agent=runtime.lead_id,
)
elif assignment_id:
assignment = await runtime.store.get_event(assignment_id)
else:
return ToolResult(success=False, output=None, error="assignment_id required")
if assignment is None or assignment.msg_type is not MsgType.ASSIGN:
return ToolResult(success=False, output=None, error="assignment_unknown")
if trace_id and trace_id != assignment.trace_id:
return ToolResult(success=False, output=None, error="assignment_trace_mismatch")
assignment_id, trace_id = assignment.event_id, assignment.trace_id
events = await runtime.store.events_for_trace(trace_id)
related = [
e
for e in events
if e.parent_event_id == assignment_id
and e.msg_type in (MsgType.CLAIM, MsgType.RESULT, MsgType.VETO)
]
# The fallback mission runner's bridge publishes its terminal result
# on mission:<run_id>, without the original assignment parent. Follow
# only the scheduler's matching claim and verify both run and owner;
# another mission or agent must never complete this assignment.
run_ids = {
str(event.payload["run_id"])
for event in related
if event.msg_type is MsgType.CLAIM
and event.from_agent == assignment.to_agent
and event.payload.get("run_id")
}
for run_id in run_ids:
if run_id.startswith("turn:"):
continue
mission_events = await runtime.store.events_for_trace(f"mission:{run_id}")
related.extend(
event
for event in mission_events
if event.msg_type is MsgType.RESULT
and event.from_agent == assignment.to_agent
and event.payload.get("run_id") == run_id
)
related.sort(key=lambda event: event.seq or 0)
last = related[-1] if related else None
state = "recorded"
if last is not None:
state = {
MsgType.CLAIM: "running",
MsgType.VETO: "refused",
MsgType.RESULT: str(last.payload.get("status") or "finished"),
}[last.msg_type]
return ToolResult(
success=True,
output={
"assignment_id": assignment_id,
"trace_id": trace_id,
"state": state,
"assignment": assignment.model_dump(mode="json"),
"events": [e.model_dump(mode="json") for e in related],
},
)
if args.get("details") is True:
targets = await runtime.roster.list()
if target_key:
target = await _status_target(runtime, target_key, lang)
if isinstance(target, ToolResult):
return target
targets = [target]
rows = []
for agent in targets:
if agent.agent_id == runtime.lead_id:
continue
recent = await runtime.store.events_for_agent(agent.agent_id, limit=10)
rows.append(
{
"agent": agent.to_dict(),
"active_runs": runtime.scheduler.active_runs(agent.agent_id),
"stats": await runtime.store.agent_stats(agent.agent_id),
"recent_events": [e.model_dump(mode="json") for e in recent],
}
)
return ToolResult(
success=True,
output={
"agents": rows,
"measurement_note": (
"Runs count recorded RESULT events and finished chat turns, once "
"each and including failures; costs are recorded costs only. No "
"independent quality rating is available."
),
},
)
if args.get("board") is True:
rows = []
for agent in await runtime.roster.list():
if agent.agent_id == runtime.lead_id:
continue
running = runtime.scheduler.active_runs(agent.agent_id)
recent = await runtime.store.events_for_agent(agent.agent_id, limit=10)
note = next((e.text for e in reversed(recent) if e.text), "")
# What it was asked to do says more than "took the task".
task = next(
(e.text for e in reversed(recent) if e.msg_type is MsgType.ASSIGN and e.text),
"",
) if running > 0 else ""
rows.append(
{
"agent": display_name(agent),
"state": "working" if running > 0 else "idle",
**({"runs": running} if running > 1 else {}),
**({"task": " ".join(task.split())[:_BOARD_NOTE_CHARS]} if task else {}),
**({"latest": " ".join(note.split())[:_BOARD_NOTE_CHARS]} if note else {}),
}
)
return ToolResult(success=True, output={"agents": rows})
if not target_key:
agents = await runtime.roster.list()
names = ", ".join(a.name for a in agents if a.agent_id != runtime.lead_id)
if not names:
return ToolResult(success=True, output=_EMPTY_ROSTER[lang])
return ToolResult(success=True, output=_ROSTER[lang].format(names=names))
target = await _status_target(runtime, target_key, lang)
if isinstance(target, ToolResult):
return target
if runtime.scheduler.active_runs(target.agent_id) > 0:
events = await runtime.store.events_for_agent(target.agent_id, limit=5)
text = next((e.text for e in reversed(events) if e.text), "")
return ToolResult(
success=True,
output=_STATUS_WORKING[lang].format(name=display_name(target), text=text),
)
events = await runtime.store.events_for_agent(target.agent_id, limit=1)
if not events:
return ToolResult(
success=True, output=_STATUS_IDLE[lang].format(name=display_name(target))
)
last = events[-1]
return ToolResult(
success=True,
output=_STATUS_LAST[lang].format(
name=display_name(target), kind=str(last.msg_type).lower(), text=last.text[:200]
),
)