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
"""BrainManager: Intent-Router + Smart-Fallback + Pipeline-Adapter.
Architecture:
1. **Router** (`dodaios/brain/router.py`) classifies user intent:
- `fast` → fast model (Haiku) for tool actions, smalltalk
- `deep` → reasoning model (Opus) for analysis, planning, explanation
- `code` → Jarvis-Agent-backed heavy worker
2. **Model-Cache**: `(provider_name, model) → Brain-Instance` — multiple
models of the same family coexist without re-instantiation.
3. **Fallback-Chain**: On error (429, 500, auth, …) the manager tries in order:
- same provider, deep_model (if fast is rate-limited, try deeper)
- `claude-api` (OAuth Max plan)
- `claude-api` (separate quota)
- `gemini`, `openrouter`, `openai` (when keys are present)
- Ollama was completely removed from the project on 2026-04-21.
4. **Pipeline-Adapter**: `__call__(text) -> str` for `speech/pipeline.py`.
5. **Voice-Commands**: "wechsel auf gemini", "denk gründlich", "denk schnell".
"""
from __future__ import annotations
import ast
import asyncio
import base64
import json
import logging
import re
import time
from collections.abc import (
AsyncIterator,
Awaitable,
Callable,
Iterable,
Mapping,
Sequence,
)
from contextvars import ContextVar
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, Literal, cast
from uuid import UUID, uuid4
# Real turn outcomes feed the passive health record behind the status dots.
from dodaios.brain import provider_health_ledger as _health_ledger
from dodaios.brain.local_context import LOCAL_CONTEXT_MARKER
# ONE canonical billing/budget/quota marker list, shared with the test-badge
# classifier (provider_test.classify_provider_error) so the live fallback chain and
# the API-Keys badge can never disagree on "out of credits / over budget" (AP-22).
from dodaios.brain.provider_test import BILLING_LIMIT_MARKERS
from dodaios.brain.spawn_gate import effort_warrants_delegation
from dodaios.brain.tool_shortlist import (
FIND_TOOLS_NAME,
ROLE_BASE,
FindToolsTool,
plan_surface,
tool_tokens,
)
from dodaios.brain.turn_override import TurnOverride
from dodaios.core.bus import EventBus
from dodaios.core.config import (
FORCE_SPAWN_MODE_BALANCED,
FORCE_SPAWN_MODE_PERMISSIVE,
BrainTierConfig,
JarvisConfig,
normalize_force_spawn_mode,
)
from dodaios.core.events import (
ActionExecuted,
AnnouncementRequested,
BrainProviderSwitched,
BrainTurnCompleted,
BrainTurnStarted,
ResponseGenerated,
VisionInjected,
)
from dodaios.core.protocols import (
Brain,
BrainMessage,
BrainRequest,
CostRecord,
ImageBlock,
ReasoningEffort,
Tool,
)
from dodaios.core.redact import safe_preview
from dodaios.core.response_style import CONVERSATIONAL_RESPONSE_STYLE
from dodaios.core.turn_language import (
DEFAULT_LOCALE,
TURN_LANGUAGE,
conversation_language_from_history,
detect_text_language,
resolve_conversation_language,
resolve_output_language,
)
from dodaios.i18n import catalog as i18n_catalog
from dodaios.i18n.locales import (
SUPPORTED_LANGUAGE_NAMES,
SUPPORTED_LOCALES,
is_known_language,
language_name,
phrase_locale,
)
from dodaios.memory import CoreMemory, PersonStore, RecallStore, Soul, UserProfile
from dodaios.memory.curator import Curator
from dodaios.safety.tool_executor import ToolExecutor
from dodaios.voice.action_phrases import (
CU_CANCEL_EXIT_CODE,
CU_TOOL_OUTCOME_LAYER,
OUTPUT_LANGUAGE_ENV_KEY,
action_phrase,
cu_failure_readback,
cu_success_readback,
extract_speakable_reason,
localize_failure_reason,
)
from dodaios.voice.contextual_readback import render_readback
from . import proactivity as _proactivity
from .action_honesty import has_unbacked_action_claim, replace_unbacked_action_claim
from .assistant_name import resolve_assistant_name
from .dispatcher import BrainDispatcher
from .evidence_gate import live_surface_covers
from .identity import identity_block
from .intent_router import RoutingDecision, classify
from .local_action_gate import (
HARNESS_NAME,
LocalActionMode,
LocalToolCall,
_looks_like_desktop_control,
external_integration_terms,
is_open_app_intent,
match_local_action,
requires_external_integration,
)
from .local_action_gate import _normalize as _gate_normalize
from .mission_command_gate import match_mission_command
from .persona_loader import load_effective_persona_prompt
from .provider_registry import BrainProviderRegistry
from .rate_limit_tracker import RateLimitTracker
from .streaming import aggregate
from .tool_call_recovery import extract_leaked_tool_calls
from .tool_surface import stamp_tool_surface
from .turn_planner import is_contextual_follow_up, plan_turn
from .voice_command_gate import match_voice_command
if TYPE_CHECKING:
from dodaios.brain.evidence_gate import EvidenceVerdict
from dodaios.brain.wiki_context import WikiContextInjector
from dodaios.control.cost import CostMeter as CostMeterLike
from dodaios.voice.contextual_readback import ReadbackComposer
log = logging.getLogger(__name__)
_PUBLISH_RESPONSE_EVENT: ContextVar[bool] = ContextVar(
"dodaios.brain.manager.publish_response_event",
default=True,
)
_TURN_HISTORY_OVERRIDE: ContextVar[tuple[BrainMessage, ...] | None] = ContextVar(
"dodaios.brain.manager.turn_history_override",
default=None,
)
#: The typed chat's per-turn pick (dodaios/brain/turn_override.py): read where
#: the chain, the tool surface and the dispatcher are built; never persisted on
#: the manager, so a concurrent voice turn keeps its own brain.
_TURN_OVERRIDE: ContextVar[TurnOverride | None] = ContextVar(
"dodaios.brain.manager.turn_override",
default=None,
)
class _SkillTurnState:
"""Task-local mutable state for one manager skill-routing turn."""
__slots__ = ("content", "injected_inline", "match", "owner", "source")
def __init__(self, owner: Any) -> None:
self.owner = owner
self.match: Any | None = None
self.content = ""
self.source = "match"
self.injected_inline = False
_SKILL_TURN_STATE: ContextVar[_SkillTurnState | None] = ContextVar(
"dodaios.brain.manager.skill_turn_state",
default=None,
)
#: Bounds for the conversation-context block appended to a Computer-Use goal.
#: The deterministic gate ships the RAW current utterance as the mission goal;
#: a correction / follow-up turn ("that is the wrong server", "do it with
#: Computer-Use") carries no task of its own, so the goal must inherit the
#: recent turns that defined it. Kept small: the CU step prompt repeats the
#: goal on every screenshot cycle.
_CU_CONTEXT_MAX_MESSAGES = 40
_CU_CONTEXT_MAX_MESSAGE_CHARS = 2_000
# Plugin-paired skill capture (2026-08-18): whether a catalog plugin holds a
# usable credential is a keyring read, remembered per plugin for this long so
# the turn path pays for it once per window, not once per matched turn.
_PAIRED_CONNECTION_TTL_S = 15.0
_PAIRED_CONNECTION_CACHE: dict[str, tuple[float, bool]] = {}
#: Hard bound on the per-turn vision capture (Wave-3 latency fix). ``vision.
#: current()`` can stall (mss BitBlt hang, paused-state miss, slow disk); without
#: a cap it blocks the whole brain turn on the hot path. On timeout the turn
#: proceeds text-only.
_VISION_COLLECT_TIMEOUT_S: float = 2.5
def _estimate_usd_from_usage(
meter: Any,
model: str,
usage: dict[str, int],
) -> float:
"""Maps `agg.usage` to the CostMeter price table.
Returns 0.0 when the model is not in the price table — tracking still
occurs but the budget gate does not trigger. This is intentional:
prefer no gate over a wrong gate (see BudgetConfig.estimate_usd).
"""
config = getattr(meter, "_config", None)
if config is None:
return 0.0
prices = getattr(config, "prices", None) or {}
from dodaios.control.cost import BudgetConfig as _BC
return _BC.estimate_usd(
prices, model,
tokens_in=int(usage.get("input_tokens", 0)),
tokens_out=int(usage.get("output_tokens", 0)),
tokens_cache_hit=int(usage.get("cache_hit_tokens", 0)),
)
PROVIDER_ALIASES = {
"claude": "claude-api",
"anthropic": "claude-api",
"opus": "claude-api",
"haiku": "claude-api",
"sonnet": "claude-api",
"gpt": "openai",
"chatgpt": "openai",
"openai": "openai",
"gemini": "gemini",
"flash": "gemini",
"pro": "gemini",
"openrouter": "openrouter",
"grok": "grok",
"nvidia": "nvidia",
"nim": "nvidia",
"nemotron": "nvidia",
}
SUBAGENT_ONLY_BRAIN_PROVIDERS: frozenset[str] = frozenset(
{"antigravity", "codex", "openai-codex", "grok-build", "grok-cli", "grokbuild"}
)
_MAIN_BRAIN_FALLBACK_PROVIDER_ORDER: tuple[str, ...] = (
"gemini",
"claude-api",
"openai",
"openrouter",
"grok",
"nvidia",
)
# Human-readable display names for each brain provider id. Used to tell the
# answering LLM which provider/model it is embodying this turn (the system
# prompt never carried this before, so a "which model are you?" question got a
# guessed answer that defaulted to "Gemini" — forensic 2026-06-20, voice session
# 15:15: Grok was live and answering, yet Jarvis claimed to be Gemini). Kept
# self-contained in the brain layer (no UI-catalog import — that would invert the
# layer dependency) and defensive: an unmapped id degrades to a readable label.
_PROVIDER_DISPLAY_NAMES: dict[str, str] = {
"claude-api": "Anthropic Claude",
"openai": "OpenAI GPT",
# Both the CLI brain id ("codex") and the sub-agent value ("openai-codex")
# map to the same readable label, so whichever surfaces as a turn prov_name
# is named correctly (the user explicitly wants "Codex / GPT-5.5" recognised).
"codex": "OpenAI Codex (GPT-5.5)",
"openai-codex": "OpenAI Codex (GPT-5.5)",
"openrouter": "OpenRouter",
"grok": "xAI Grok",
"nvidia": "NVIDIA NIM",
"gemini": "Google Gemini",
"antigravity": "Google Antigravity (Gemini)",
"grok-build": "Grok Build (xAI subscription)",
}
def _provider_display_name(provider: str) -> str:
"""A readable label for a brain provider id (never crashes on unknown ids)."""
pid = (provider or "").strip()
mapped = _PROVIDER_DISPLAY_NAMES.get(pid)
if mapped:
return mapped
# Unknown id → readable fallback: "some-new_provider" → "Some New Provider".
return pid.replace("-", " ").replace("_", " ").title() or "the configured provider"
def _provider_identity_directive(provider: str, model: str | None, name: str) -> str:
"""Authoritative, anti-guessing self-identity line for the system prompt.
Names the *actual* provider/model answering this turn (set per fallback-chain
attempt in ``generate()``). ``name`` is kept for callers; the assistant's name
is already stated by the identity block.
"""
label = _provider_display_name(provider)
model_str = (model or "").strip() or "the provider's default"
return (
f"Runtime fact: this turn you are running on the brain provider {label} "
f"(model: {model_str}). If asked which model or provider powers you, say exactly "
"this; never guess."
)
# Mapping of Credential-Manager slot -> Brain provider ID. Brain slots only;
# TTS/STT providers have their own lifecycles outside BrainManager.
# Used by the SecretConfigured subscriber to remove the corresponding provider
# from _dead_providers after the user sets a key, so it is retried on the next
# turn without requiring an app restart.
_SECRET_KEY_TO_BRAIN: dict[str, str] = {
"gemini_api_key": "gemini",
"google_aistudio_api_key": "gemini",
"google_api_key": "gemini",
"anthropic_api_key": "claude-api",
"openai_api_key": "openai",
"openrouter_api_key": "openrouter",
"grok_api_key": "grok",
"xai_api_key": "grok",
"nvidia_api_key": "nvidia",
}
# ──────────────────────────────────────────────────────────────────
# Tier defaults per provider (source of truth for fast/frontier mapping)
# ──────────────────────────────────────────────────────────────────
#
# As of 2026-04. Update when providers release new models or deprecate old
# ones. Structure: tier → provider → model-id.
#
# "router" = fast tier (<1s first token, tool use, cheap).
# "deep" = frontier tier (reasoning, long context, more expensive).
#
# Wave-4 migration: the second key was previously named ``"sub_jarvis"``
# because the frontier model drove the Sub-Jarvis tier. The Sub-Jarvis tier
# was removed with the Jarvis-Agent-Bridge migration, but the frontier mapping
# itself is retained as the deep-brain source — hence simply ``"deep"``.
#
# Aliases like "haiku"/"opus" are NOT mapped here — PROVIDER_ALIASES
# resolves them to the canonical provider name first, then
# _resolve_tier_model() looks up here.
# Tool names whose successful execution means a real on-screen DESKTOP ACTION
# happened (open an app, click, type, scroll, …). When the router brain runs
# one of these and then produces NO narration text — a known Gemini behaviour
# after a function call — the turn is NOT empty/confused: a confirmation must be
# spoken, never a clarifying question (live bug 2026-06-09, AP-19-adjacent: a
# successful computer_use run that opened Chrome was answered with "Wie meinst
# du das genau?"). ``computer_use`` + ``open_app`` are the router-reachable
# desktop tools; the rest are the in-loop GUI primitives, listed for robustness
# so a future router-exposed action stays covered.
_DESKTOP_ACTION_TOOL_NAMES: frozenset[str] = frozenset({
"computer_use",
"open_app",
"click",
"click_element",
"type_text",
"hotkey",
"scroll",
"move_mouse",
"switch_window",
})
TIER_DEFAULTS_BY_PROVIDER: dict[str, dict[str, str]] = {
"router": {
# Frontier 2026-Q2 — main Jarvis tier (latency-first, pure dispatcher).
# 2026-04-29: gemini-3-flash is only available as -preview (Google API
# returns 404 NOT_FOUND without -preview).
"claude-api": "claude-haiku-4-5-20251001",
"gemini": "gemini-3-flash-preview",
"openai": "gpt-5.5",
"deepseek": "deepseek-chat",
# Gateway: a model-less OpenRouter user must NEVER default to a paid
# Anthropic id (that billed Opus/Haiku on a free key — §3/AP-22). A free
# general-purpose model degrades with a clean 404 if ever retired, instead
# of silently billing the most expensive model in the catalog.
"openrouter": "nvidia/nemotron-3-ultra-550b-a55b:free",
# Grok 4.3 is available across regions and supports local tool use.
"grok": "grok-4.3",
# NVIDIA NIM router pick: a widely-hosted, tool-capable, low-latency model
# (the reasoning Nemotron flagships are the deep tier). The user's own pick
# from the live catalog wins over this. 2026-08-09: moved off Meta's
# Llama 3.3 70B (dense, late 2024) to NVIDIA's own current sparse
# generation — 12B of 120B activate per token, so it answers faster than
# the dense model it replaces. Verified against integrate.api.nvidia.com.
"nvidia": "nvidia/nemotron-3-super-120b-a12b",
"mistral": "mistral-small-3.1",
# Local providers: no server-side catalog is knowable ahead of time —
# empty means "the plugin discovers the first installed model".
"ollama": "",
"local-openai": "",
},
"deep": {
# Frontier 2026-Q2 — deep brain (user mandate 2026-04-29:
# frontier everywhere). 2026-06-14: switched from claude-fable-5 to
# claude-opus-4-8 — fable-5 is approved-access-only and the Claude Max
# subscription cannot reach it ("Claude Fable 5 is currently
# unavailable"); this deep tier calls the Brain API directly and has no
# model-unavailable retry, so the pinned model must be one we can reach.
"claude-api": "claude-opus-4-8",
"gemini": "gemini-3.1-pro-preview",
"openai": "gpt-5.5-pro",
"deepseek": "deepseek-reasoner",
# Gateway: never a paid Anthropic default for a model-less OpenRouter
# user (§3/AP-22) — see the router-tier note above.
"openrouter": "nvidia/nemotron-3-ultra-550b-a55b:free",
"grok": "grok-4.3",
# NVIDIA NIM deep pick: NVIDIA's own reasoning flagship. 2026-08-09:
# the Llama-3.1-based Nemotron Ultra gives way to the current
# Nemotron 3 Ultra (verified against integrate.api.nvidia.com), which
# the OpenRouter tiers above already name.
"nvidia": "nvidia/nemotron-3-ultra-550b-a55b",
"mistral": "mistral-large-3",
# Local providers: empty = plugin-side discovery (see router tier).
"ollama": "",
"local-openai": "",
},
}
def _mirror_tier_defaults(source: str, target: str) -> None:
"""Give ``target`` the same per-tier default models as ``source``.
For provider families that are the same catalogue on a different endpoint.
Re-typing the ids instead would create a second literal list that drifts on
the next model rotation — the BUG-008 shape — and it would drift on exactly
the tier a production project cares about most.
"""
for tier in TIER_DEFAULTS_BY_PROVIDER.values():
if source in tier:
tier[target] = tier[source]
# Vertex AI serves the SAME Gemini model ids as AI Studio; the endpoint and the
# billing account differ, the catalogue does not.
_mirror_tier_defaults("gemini", "vertex")
# Hard loop bounds for DELEGATED realtime voice turns (prefer_tool_model).
# Classic chat turns keep the dispatcher defaults (15 rounds, no deadline).
#
# These are CEILINGS for a runaway turn, not a target for a working one. The
# 2026-07-14 incident (an unbounded delegate at 14 rounds / 66 s) was answered
# with 6 rounds / 20 s, and that cut the churn — but it also guillotined every
# honest multi-step task at about five steps, which the user then heard as
# "so far I got to …" (GT-11). Round count and wall clock are not the same
# risk: a round only ever happens because the model asked for another tool, so
# 12 rounds cost nothing on a turn that finishes in three. The wall clock is
# the real latency, and 45 s is what a genuinely progressing ~8-round turn
# needs at Flash speed with reasoning off (≈2 s model + ≈3 s tool per round).
#
# Both paths still end the turn gracefully rather than hard-breaking:
# ToolUseLoop forces ONE final tool-less synthesis round over the evidence
# already gathered (_BUDGET_FINAL_DIRECTIVE / _DEADLINE_FINAL_DIRECTIVE).
#
# KNOWN COST of the flat 45 s, and the follow-up it asks for: a turn that is
# CHURNING (re-issuing near-identical lookups) now burns 45 s before it is cut
# off, where it used to burn 20. The correct shape is a deadline that starts
# short and is EXTENDED by each successful tool call — progress buys time,
# churn does not — but ``deadline_s`` is a single float fixed at ToolUseLoop
# construction, so that fix lives in dodaios/brain/tool_use_loop.py (+ the
# dispatcher pass-through), not here.
_DELEGATE_MAX_TURNS: int = 12
_DELEGATE_DEADLINE_S: float = 45.0
# Delegated rounds ask the provider to skip internal "thinking" entirely.
# Live 2026-07-17 (FlightRecorder p50 15-18 s, worst 33 s): the hoisted Tool
# Model (Gemini Flash) ran every one of its 3-6 sequential rounds with the
# SDK-default dynamic thinking over a ~53k-token context, so plain questions
# ran the 20 s deadline out. The router-tier factory caps thinking only on
# the tier's OWN provider entry — a live provider switch (e.g. router →
# openrouter) parks that cap on the wrong entry and the hoisted Tool Model
# escapes it. Passing the per-request hint here covers the delegated turn
# deterministically, independent of which provider entry carries the cap.
# Same doctrine as the router thinking cap (BUG-LATENCY 2026-05-24) and the
# Computer-Use calls (dodaios/cu/brain_call.py); providers without a
# reasoning knob ignore the hint (AP-21: capability hint, no provider pin).
_DELEGATE_REASONING_EFFORT: Literal["none"] = "none"
# Appended to the system prompt of DELEGATED voice turns only. Live 2026-07-17
# (turn af736681): the tool loop spent 5 sequential rounds on one question —
# three near-identical wiki-recall calls, then wiki-list, then wiki-page-read —
# and ran the 20 s deadline out. Every round is a full provider round-trip, so
# round count IS the latency. Static text (byte-stable across turns) so the
# delegated prefix keeps its own provider prompt-cache entry.
_DELEGATE_VOICE_DIRECTIVE = (
"DELEGATED VOICE TURN: the user is waiting on a live call and every model round costs "
"seconds. Batch independent lookups into one round (search_web takes several "
"`queries`), never repeat a call whose result you have, and answer as soon as the "
"evidence suffices."
)
def _resolve_tier_model(
tier: str,
provider: str,
explicit_model: str | None,
) -> str:
"""Returns the model for (tier, provider).
1. If `explicit_model` is set (from [brain.router] in jarvis.toml),
that value is used — user override takes precedence.
2. Otherwise look up in TIER_DEFAULTS_BY_PROVIDER.
3. Otherwise return an empty string (the Brain constructor then uses its
hardcoded DEFAULT_MODEL as a fallback).
Unknown providers do NOT raise — every brain plugin has its own
DEFAULT_MODEL as an emergency anchor.
"""
if explicit_model:
return explicit_model
return TIER_DEFAULTS_BY_PROVIDER.get(tier, {}).get(provider, "")
def get_tier_default_model(tier: str, provider: str) -> str | None:
"""Public API for the setup wizard / UI / voice_command_gate.
Returns the default model for (tier, provider) or None if no default
exists. The caller can use this to decide whether the provider is
supported at all.
"""
return TIER_DEFAULTS_BY_PROVIDER.get(tier, {}).get(provider)
def _coerce_main_brain_provider(provider: str | None, *fallbacks: str | None) -> str:
"""Return a main-brain-capable provider.
Some provider integrations exist only for the heavy subagent worker. They
must remain present in the codebase for that path, but an old persisted
``brain.primary`` must not make the main router run through them.
"""
candidate = (provider or "").strip()
if candidate and candidate not in SUBAGENT_ONLY_BRAIN_PROVIDERS:
return candidate
for fallback in (*fallbacks, *_MAIN_BRAIN_FALLBACK_PROVIDER_ORDER):
value = (fallback or "").strip()
if value and value not in SUBAGENT_ONLY_BRAIN_PROVIDERS:
return value
return _MAIN_BRAIN_FALLBACK_PROVIDER_ORDER[0]
# ──────────────────────────────────────────────────────────────────
# Force-spawn pattern builder (persona mandate phase 3)
# ──────────────────────────────────────────────────────────────────
#
# The three lists in ``BrainRoutingConfig`` are compiled into three regex
# patterns here. ``BrainManager._should_force_spawn`` evaluates them in
# order: smalltalk allowlist wins (no spawn), otherwise verb match → spawn,
# otherwise marker match → spawn.
#
# Pattern matches ``\bnichts\b`` as a "negative-lookahead-no-match" sentinel
# for empty lists — prevents an empty verb list from degenerating into a
# greedy match-everything regex.
_NEVER_MATCH_RE: re.Pattern[str] = re.compile(r"(?!.*)", re.IGNORECASE)
# ``MessageSent.source_layer`` values for CONVERSATIONAL turns that must NEVER
# force-spawn a mission, whatever their text contains. A drag-dropped mission
# recap (``ui.web.ws.mission_inject``) embeds the dropped card's OWN text
# verbatim, so a title carrying a spawn trigger ("sub-agent") or an action verb
# ("Write …") would otherwise leak that trigger into the directive and spawn a
# NEW mission whose only deliverable is a conversational recap (no file) ->
# empty diff -> critic_loop_exhausted. The doom-loop fixed 2026-06-16: every
# failed mission the user dragged in to discuss spawned another failed mission.
# Keep in sync with ``dodaios.ui.web.mission_inject.MISSION_INJECT_SOURCE_LAYER``
# and ``dodaios.brain.drop_context.DROP_SOURCE_LAYER`` (parity tests in
# tests/unit/brain/test_routing.py). ``ui.drop`` = a dragged-and-dropped file /
# image / text: reacted to inline, never auto-dispatched as a worker.
_NON_SPAWN_SOURCE_LAYERS: frozenset[str] = frozenset(
{"ui.web.ws.mission_inject", "ui.drop"}
)
# Two-turn voice/chat confirmation for a consequential ``ask``-tier tool. Turn N
# defers the action (the executor returns ``VOICE_CONFIRM_SENTINEL``) and speaks a
# question; this holds what turn N+1 needs to resolve the user's "ja"/"nein".
# Bounded re-asks avoid a soft-lock on a persistently ambiguous answer.
_MAX_CONFIRM_REASKS = 2
_SCREEN_CONFIRM_TTL_S = 20.0
class _PendingVoiceConfirm:
"""A deferred consequential action awaiting the user's next yes/no."""
__slots__ = ("trace_id", "lang", "tool_name", "reasks")
def __init__(self, trace_id: UUID, lang: str, tool_name: str, reasks: int = 0) -> None:
self.trace_id = trace_id
self.lang = lang
self.tool_name = tool_name
self.reasks = reasks
class _PendingScreenConfirm:
"""A short-lived, conversation-scoped proposal to inspect the screen."""
__slots__ = ("expires_at", "lang")
def __init__(self, lang: str, expires_at: float) -> None:
self.lang = lang
self.expires_at = expires_at
# Option A (2026-06-15): a heavy-research request whose deliverable is an ANSWER
# (comparison / overview / recommendation / summary) is answered INLINE via the
# router's search_web tool; only research that BUILDS a verifiable ARTIFACT (a
# file / report / document) offloads to a sub-agent mission, because the
# Worker->Critic pipeline grades artifacts via git diff and is hostile to an
# answer-only research turn (empty-diff veto -> critic_loop_exhausted, live
# mission 019ecb56, 2026-06-15). These three regexes decide "wants an artifact".
#
# A build/produce VERB (write/create/build/generate/export/save + DE forms).
# Deliberately disjoint from the research/analysis verbs in
# ``heavy_research_verbs`` (recherchier/analysier/compar/...) so a pure research
# answer never matches.
_BUILD_VERB_RE: re.Pattern[str] = re.compile(
r"\b(writ|wrote|creat|build|buil|generat|produc|draft|compil|render|"
r"export|saved?|"
r"schreib|geschrieben|erstell|baue|bau|generier|verfass|speicher|exportier)"
r"\w*",
re.IGNORECASE,
)
# A document / artefact NOUN — the thing being built is a file-shaped deliverable.
_DOC_NOUN_RE: re.Pattern[str] = re.compile(
r"\b(report|document|deck|slides?|spreadsheet|presentation|"
# build-a-deliverable nouns (a file-shaped result the Worker->Critic
# pipeline can verify via git diff): web/app/doc artefacts, DE + EN. A
# build VERB is still required by _research_wants_artifact, so a bare
# question ("what is an html file") never matches. "summary" is
# deliberately EXCLUDED — it is an ANSWER, not a file (discriminator test).
r"website|web ?page|webseite|html|app|application|anwendung|"
r"dashboard|landing ?page|visuali\w+|script|skript|"
r"bericht|dokument|tabelle|praesentation|präsentation)\b", # i18n-allow: DE artefact nouns
re.IGNORECASE,
)
# A named file / real extension, or an explicit "into a file" instruction — an
# artefact deliverable on its own, no build verb required ("... into ai_news.md").
_NAMED_FILE_RE: re.Pattern[str] = re.compile(
r"\.(md|txt|html?|json|csv|pdf|docx?|xlsx?|pptx?|ya?ml|toml)\b"
r"|\bfile\s+named\b|\bnamed\s+\S+\.\w+"
r"|\bdatei\s+namens\b|\bin\s+eine\s+datei\b|\bin\s+die\s+datei\b" # i18n-allow: DE file phrasing
r"|\binto\s+a\s+file\b",
re.IGNORECASE,
)
# BUG-LIVE-04 (Recon-Agent 3, 2026-05-16): Whisper transcribes silence,
# background TV, music, jingles into a small set of well-known sentinel
# strings. Empirical sample from data/jarvis_desktop.log (~75% mission
# fail rate on 2026-05-16 — half driven by these phrases).
#
# 2026-05-17 (H2 from audit-team 10): the original single-set + startswith
# match was too greedy for short Single-Token seeds. "you" filtered every
# English utterance starting with "You" (e.g. "You there?"), "musik"
# filtered "Musik lauter machen", "applaus" filtered "Applaus für die
# Band". Real user voice queries were silently dropped from the
# force-spawn path. The fix splits the seeds into two buckets:
#
# _WHISPER_FP_EXACT_ONLY -- short tokens that also appear in
# legitimate speech; only the *whole*
# utterance must equal the seed (after
# punctuation strip).
# _WHISPER_FP_PREFIX_OK -- multi-word phrases distinctive enough
# that any utterance starting with them
# is almost certainly a Whisper artefact;
# startswith match still allowed.
#
# An entry must appear in exactly ONE bucket. The combined frozenset
# WHISPER_FALSE_POSITIVE_SEEDS below is kept as a backwards-compatible
# alias for any external caller (tests, telemetry) that wants the
# complete catalogue.
_WHISPER_FP_EXACT_ONLY: frozenset[str] = frozenset({
# Short tokens / single words that legit user speech also starts with.
"you",
"musik",
"[musik]",
"applaus",
"[applaus]",
"subscribe",
"tschüss",
"untertitel",
"untertitelung",
"thank you",
"thank you.",
})
_WHISPER_FP_PREFIX_OK: frozenset[str] = frozenset({
# Multi-word phrases distinctive enough that startswith is safe.
"untertitelung des zdf für funk, 2017",
"untertitelung des zdf für funk",
"vielen dank",
"vielen dank fürs zuschauen",
"vielen dank für ihre aufmerksamkeit",
"bis zum nächsten mal",
"bis zum nächsten mal!",
"thanks for watching",
"thank you for watching",
"see you next time",
"ich verstehe es nicht",
})
# Backwards-compatible alias — equals the union of both buckets so any
# external introspection (telemetry, eval harness) still sees the full
# catalogue. Disjoint by construction; assertion at import time catches
# accidental duplication when the lists are edited.
_WHISPER_FALSE_POSITIVE_SEEDS: frozenset[str] = (
_WHISPER_FP_EXACT_ONLY | _WHISPER_FP_PREFIX_OK
)
assert not (_WHISPER_FP_EXACT_ONLY & _WHISPER_FP_PREFIX_OK), (
"Whisper FP seed lists must be disjoint"
)
_PC_CONTROL_RE: re.Pattern[str] = re.compile(
r"\b("
r"klick|click|tippe|tipp|type|schreib|schreibe|reinschreib|prompt|prompten|"
r"absenden|sende|send|drueck|druecke|drück|drücke|press|taste|hotkey|"
r"browser|fenster|feld|eingabefeld|chatgpt|tab|button|pc|desktop|"
# The live SURFACE the user names to act ON — screen / Bildschirm. A request
# that points at the screen is computer-use (a worker has no desktop), so
# naming it must register here: it keeps the turn OFF the sub-agent path and
# marks it an action turn so a tool-incapable talker delegates it to a
# tool-capable provider that picks computer_use (user pain 2026-06-21:
# "mach es am Bildschirm" / "do it on screen" was not recognized at all).
r"bildschirm|screen|"
r"maus|mouse|cursor"
r")\w*\b",
re.IGNORECASE,
)
_INSTRUCTIONAL_QUESTION_RE: re.Pattern[str] = re.compile(
r"^\s*(?:"
# "wie <verb> ich/man …" — a HOW-TO question, never a build request. The
# build/create verbs are listed too so "wie erstelle/baue/schreibe ich eine
# HTML-Datei" stays an inline answer and is not mistaken for "build me a file"
# (live bug 2026-06-21). The English how-to is already caught by "how do/can …".
r"wie\s+(?:kann|koennte|könnte|muss|soll|mach|mache|macht|geht|funktioniert"
r"|erstell|erstelle|erstellt|baue|bau|baut|schreib|schreibe|schreibt"
r"|programmier|programmiere|generier|generiere|implementier|implementiere)\s+"
r"|was\s+(?:ist|bedeutet|heisst|heißt)\s+"
r"|woran\s+erkenne\s+"
r"|warum\s+"
r"|how\s+(?:do|can|could|should|would)\s+"
r"|what\s+(?:is|does|are)\s+"
r"|why\s+"
r")",
re.IGNORECASE,
)
def _build_verb_pattern(terms: list[str]) -> re.Pattern[str]:
"""``\\b<term>\\w*\\b`` regex for action verbs including conjugated forms."""
if not terms:
return _NEVER_MATCH_RE
parts = [re.escape(t) + r"\w*" for t in terms]
return re.compile(r"\b(?:" + "|".join(parts) + r")\b", re.IGNORECASE)
def _build_marker_pattern(markers: list[str]) -> re.Pattern[str]:
"""``\\b<marker>\\b`` regex for external-system markers (PR/Repo/...)."""
if not markers:
return _NEVER_MATCH_RE
parts = [re.escape(m) for m in markers]
return re.compile(r"\b(?:" + "|".join(parts) + r")\b", re.IGNORECASE)
def _build_smalltalk_pattern(allowlist: list[str]) -> re.Pattern[str]:
"""Smalltalk allowlist as a case-insensitive substring match."""
if not allowlist:
return _NEVER_MATCH_RE
parts = [re.escape(p) for p in allowlist]
return re.compile(r"(?:^|\b)(?:" + "|".join(parts) + r")(?:\b|$)", re.IGNORECASE)
# Leading greeting / wake-word / politeness run, stripped before the smalltalk
# re-check in ``BrainManager._is_smalltalk``. Anchored at ^, repeats so several
# leading tokens collapse ("Hey Jarvis, hallo, öffne ..."), and swallows the i18n-allow
# trailing separators (comma / period / …). Longer tokens ("hey jarvis") precede
# their prefix ("hey") so the longest run is consumed. Live bug 2026-06-07
# (data/jarvis_desktop.log 18:19:07): "Hallo, öffne ihn für mich" was silenced i18n-allow
# as smalltalk because the allowlist substring-matched the leading "Hallo".
_GREETING_PREFIX_RE = re.compile(
r"^(?:\s*(?:"
r"hey\s+jarvis|hi\s+jarvis|hallo\s+jarvis|ok(?:ay)?\s+jarvis|jarvis|"
r"guten\s+morgen|guten\s+abend|guten\s+tag|good\s+morning|good\s+evening|"
r"hey|hi|hallo|hello|moin|servus|"
r"ok|okay|bitte|danke|thanks|thank\s+you"
r")\b[\s,.!?:;-]*)+",
re.IGNORECASE,
)
# A clear ACTION / request signal inside an utterance that ALSO matched the
# smalltalk allowlist. A continuation-recombine (or a polite preamble) can glue
# an answered chit-chat turn onto a real command (a smalltalk greeting followed
# by "open the oldest Bill-Gates post for me") or trail one ("open Chrome,
# thanks"). The smalltalk allowlist then matches the conversational part and
# (without this signal) the WHOLE turn is demoted to a tool-less smalltalk turn,
# hiding computer_use / spawn_worker (live bug 2026-06-19 11:43, the Bill-Gates
# turn: the deep brain answered a no-op "saved your note" reply and never opened
# the browser). When this signal is present the turn is a COMMAND, not
# chit-chat, so ``_is_smalltalk`` keeps the action tools visible. Pure regex, no
# LLM (AP-11). Intentionally NARROW (high-signal tokens + explicit request
# framing only) so a long but signal-less friendly remark carries no match and
# stays smalltalk, preserving the anti-fake-spawn tool-hiding.
_ACTION_REQUEST_RE = re.compile(
r"(?:"
# open / launch an app, file, page, browser
r"\b(?:oeffn\w*|öffn\w*|aufmach\w*|aufzumach\w*|start\w*|open\w*|launch\w*)\b|" # i18n-allow
# research / analysis / search
r"\b(?:recherchier\w*|research\w*|analys\w*|analyz\w*|untersuch\w*|" # i18n-allow
r"vergleich\w*|such\w*|search\w*|google\w*)\b|" # i18n-allow
# explicit action verbs
r"\b(?:zeig\w*|lies|lese|liest|schreib\w*|install\w*|deinstallier\w*|" # i18n-allow
r"deploy\w*|spawn\w*|delegier\w*)\b|"
# request framing (DE)
r"\bich\s+(?:möchte|will|brauche|hätte\s+gern)\b|" # i18n-allow
r"\b(?:kannst|könntest|würdest)\s+du\b|" # i18n-allow
r"\b(?:mach|zeig|gib|hol|such|lies|öffne|bau)\s+(?:mir|mal|uns)\b|" # i18n-allow
# request framing (EN)
r"\b(?:can|could|would)\s+you\b|\bi\s+(?:want|need)\b|\bi'?d\s+like\b|"
r"\b(?:show|give|help)\s+me\b"
r")",
re.IGNORECASE,
)
def _looks_like_pc_control(user_text: str) -> bool:
"""Detects local screen/PC control requests intended for the computer-use harness."""
return bool(_PC_CONTROL_RE.search(user_text or ""))
# Subset of ``force_spawn_phrases`` that NAMES the execution vehicle (a worker),
# as opposed to merely describing how THOROUGH the work should be. This is a
# PARTITION of the existing trigger phrases, not a new detection list: it only
# decides which matched trigger keeps absolute priority over the computer-use
# stand-down. Naming the vehicle ("subagent" / "spawn" / "openclaw" / "delegate")
# is an UNAMBIGUOUS spawn request (mandate 2026-06-15) and wins over everything.
# A DEPTH marker ("deep dive" / "gründlich" / "umfassend" / …) is ambiguous — it
# overlaps with computer-use requests ("Mach einen Deep Dive mit Computer Use in
# meinem Chrome Browser …") — so it must NOT override an explicit on-screen
# request; that computer-use-vs-spawn call is the LLM router's. Matched as a
# substring of the trigger the regex returned, so conjugations are covered
# ("spawne"/"gespawnt" -> "spawn", "delegiert" -> "delegier"). No depth phrase
# contains any of these stems, so the partition is clean.
_VEHICLE_NAME_TRIGGER_STEMS: frozenset[str] = frozenset({
"openclaw", "open claw", "open-claw",
"subagent", "sub-agent", "sub agent",
"spawn", "delegier", "delegate",
})
def _trigger_names_vehicle(matched_trigger: str) -> bool:
"""True iff the matched force-spawn trigger NAMES a worker vehicle (vs. a
thoroughness/depth descriptor). Only a vehicle name keeps absolute priority
over the computer-use stand-down — a depth marker yields to it."""
m = (matched_trigger or "").strip().lower()
return any(stem in m for stem in _VEHICLE_NAME_TRIGGER_STEMS)
def _is_instructional_question(user_text: str) -> bool:
"""True for how-to / explanatory questions that should be answered directly.
A question opener does NOT make the whole turn a question. "Warum ist
Spotify nicht offen, mach es auf" asks and then commands, and reading it as
instructional suppresses the command — the same blind spot the tool loop's
copy of this rule carried until commit 163b2808. That copy owns the
imperative test; this one calls it rather than growing a second version
that can drift.
"""
text = user_text or ""
if not _INSTRUCTIONAL_QUESTION_RE.search(text):
return False
from dodaios.brain.tool_use_loop import ( # noqa: PLC0415 — cycle-safe here
_has_trailing_imperative,
)
return not _has_trailing_imperative(text)
# Spawn-tool names hidden from a plain knowledge question's tool surface — the
# vehicles that delegate to a background worker. A read/search/desktop tool is
# NEVER in here (the question must stay answerable inline).
_SPAWN_TOOL_NAMES: frozenset[str] = frozenset({"spawn_worker", "multi_spawn"})
# Agentic-IDE pane tools that only make sense RELATIVE TO AN OPEN WORKSPACE.
# With none open, every one of them can only fail — while their schemas cost
# ~10 KB of input on every tool-loop iteration (2026-07-28 cost audit).
# Deliberately NOT listed: ``agentic-ide-status`` (answers "nothing is open"
# honestly) and ``agentic-ide-resume`` (the command that OPENS a workspace
# by voice — hiding it would strand the feature).
# The on-demand artifact tool. Offered ONLY on a turn that explicitly asks for
# a page/picture (see _hide_artifact_tool_without_request): the maintainer's
# rule is that an artifact is something the user asks for, never something the
# assistant decides an answer deserves.
_ARTIFACT_TOOL_NAME: str = "create_artifact"
# Agentic-IDE pane tools that only make sense RELATIVE TO AN OPEN WORKSPACE.
_AGENTIC_IDE_WORKSPACE_TOOL_NAMES: frozenset[str] = frozenset({
"agentic-ide-terminal-report",
"agentic-ide-prompt",
"agentic-ide-fanout",
"agentic-ide-spawn-terminals",
"agentic-ide-move-terminal",
"agentic-ide-close-agent-terminals",
"agentic-ide-focus",
})
# Consequential action tools a signalless turn must never INHERIT from the
# conversation context. Forensic 2026-06-27: the German smalltalk "Was geht ab?"
# was mis-transcribed as "Lask it up!" [en] conf 0.509, missed every smalltalk /
# whisper-junk list, and the router-LLM (reading a 30k-token context full of the
# prior "open Discord, bridge-mine channel" command) re-ran that exact CU plan on
# a turn that asked for nothing. ``computer_use`` + the spawn vehicles are the
# heavy, irreversible-looking actions hidden here. Deliberately NOT hidden: the
# read-only ``screenshot`` tool (so "Was siehst du auf dem Bildschirm?" still
# works) and ``open_app`` (lighter; naming an app already reads as action-intent).
# INHERITANCE NEEDS SOMETHING TO INHERIT (2026-08-17): the hide applies only
# while a desktop episode is live or just ended — see
# ``_hide_action_tools_on_signalless_turn``. Outside one there is no prior plan
# in the context, and hiding the vehicle then only costs the turn its ability
# to act.
_INHERITABLE_ACTION_TOOL_NAMES: frozenset[str] = _SPAWN_TOOL_NAMES | {"computer_use"}
# The only tools a SMALLTALK turn may not see. The 2026-05-01 incident was ONE
# tool class, not the whole surface: the LLM hallucinated a ``spawn_worker`` on
# chit-chat and then reported test work it had never started. Nothing else in the
# surface caused that. The historical full-hide additionally removed every action
# vehicle from a turn the substring allowlist merely READ as chit-chat, which is
# its own bug — the model then has nothing to act with, whatever the user asked
# for. See ``_smalltalk_tool_override``.
_SMALLTALK_HIDDEN_TOOL_NAMES: frozenset[str] = _SPAWN_TOOL_NAMES
# Deterministic write/record tools that create user-visible state (a contact, a
# profile field, a wiki note, a calendar event, a phone call). On a turn with NO
# action signal of its own these must NOT sit in the LLM surface, or the model
# can pick one on a plain conversational question (deep-dive 2026-06-30: a
# "does my budget fit?" turn had google_calendar/contact-upsert/wiki-ingest/
# update-profile ungated). Hidden by the signalless guard, with a hard exemption
# for any tool the deterministic layer ALREADY mandated this turn (a real "merk
# dir, dass…" keeps wiki-ingest via resolve_save_mandate; a calendar READ keeps
# google_calendar via the evidence gate) so the say-do write feature and calendar
# reads never regress. The background wiki (VoiceFactBridge) is untouched — it is
# not a model-callable tool (AP-9).
_DETERMINISTIC_WRITE_TOOL_NAMES: frozenset[str] = frozenset({
# Keys are the tools' .name attributes (what the turn dict is keyed by) —
# NOT the hyphenated entry-point names. "update-profile" (the ep name)
# sat here since introduction, so the signalless gate never actually
# stripped update_profile (found in the 2026-07-06 pipeline audit).
"contact-upsert", "update_profile", "wiki-ingest", "google_calendar",
"call-contact",
})
# Tools withheld on a turn that carries a CAPTURED SCREEN image. Screen pixels
# and UI text are untrusted evidence (docs/screen-context.md §4.2), so injected
# on-screen text must not be able to start something expensive and unattended:
# a background worker, or a silent record write (a contact, a calendar entry, a
# wiki note, an outbound call). Everything else stays — including
# ``computer_use``, whose "looking is not operating" boundary (maintainer mandate
# 2026-08-02) is enforced per call by ``cu_gate.llm_computer_use_allowed`` in
# ``tool_use_loop``/``realtime.tools``. That gate reads the USER's utterance, so
# a look request is refused there even inside a live desktop episode, and text
# rendered on screen can never unlock it. See ``_image_turn_tool_override``.
_SCREEN_TURN_HIDDEN_TOOL_NAMES: frozenset[str] = (
_SPAWN_TOOL_NAMES | _DETERMINISTIC_WRITE_TOOL_NAMES
)
# The user literally names a skill ("nutz den Skill cloud-debug", "run the
# skill …"). An explicit skill request is its own vehicle and always keeps
# ``run-skill`` visible — the pc-control run-skill hide below must never veto
# it. Same word in DE/EN; matched with word boundaries so unrelated words
# ("skillful") don't trip it.
_EXPLICIT_SKILL_REQUEST_RE = re.compile(r"\bskills?\b", re.IGNORECASE)
# Interrogative opener (DE / EN / ES) — the leading question word of a plain
# "what/which/who/how/…"-style factual question. Anchored at the start after an
# optional wake/greeting/politeness run so "Jarvis, welche Firmen …" still
# matches. A trailing "?" is accepted as an independent signal (STT often drops
# the question word's leading capital but keeps the rising-intonation "?"), but
# the real anchor is the opener — STT frequently strips terminal punctuation.
_QUESTION_OPENER_RE: re.Pattern[str] = re.compile(
r"^\s*(?:(?:hey|hallo|hi|hello|ok(?:ay)?|bitte|please|jarvis)[\s,]+){0,3}"
r"(?:"
# DE interrogatives
r"was|welche[rsnm]?|wer|wen|wem|wessen|wie ?viele?|wie|wieso|warum|weshalb|"
r"wann|woher|wohin|wo|wof[üu]r|womit|wodurch|"
# EN interrogatives
r"what|which|who|whom|whose|how|when|where|why|"
# ES interrogatives
r"qu[ée]|cu[áa]les?|qui[ée]nes?|c[óo]mo|cu[áa]ndo|d[óo]nde|cu[áa]nt[oa]s?"
r")\b",
re.IGNORECASE,
)
def _is_plain_knowledge_question(user_text: str) -> bool:
"""True iff the utterance is shaped like a plain factual/knowledge question.
Pure form check (interrogative opener OR a trailing "?") — it does NOT judge
action intent or artifact-build; the caller combines this with the existing
deterministic detectors. Pure regex (AP-11 safe), DE/EN/ES.
"""
t = (user_text or "").strip()
if not t:
return False
return bool(_QUESTION_OPENER_RE.search(t) or t.endswith("?"))
# Definitional "what IS X" guard for the deterministic skill match. A plugin
# skill's voice trigger is an un-anchored bare-name pattern (e.g. ``(github|…)``)
# that fires on ANY mention — including when the app is merely the SUBJECT of a
# knowledge question ("was ist GitHub?", "what is Stripe?"). Such a turn must be
# ANSWERED, not captured by the skill (live skill-routing eval 2026-06-24: both
# negative controls over-fired here). Precision over recall: suppress ONLY when
# the matched trigger token is the predicate of a copula in a definitional
# opener — so a real data request that merely starts with "was ist" ("was ist
# in meinem Posteingang?", token "posteingang") is NOT suppressed, because there
# the token does not sit directly after the copula (the "in"/"mein" data context
# breaks the predicate run).
_DEFINITIONAL_OPENER_RE = re.compile(
r"^\s*(?:was\s+(?:ist|sind|bedeutet|war|waren)"
r"|wof[üu]r\s+(?:ist|steht|braucht|nutzt|benutzt|verwendet)"
r"|erkl[äa]r(?:e|st|en)?\b"
r"|what(?:'s|\s+is|\s+are|\s+does)\b"
r"|tell\s+me\s+(?:about|what)\b"
r")",
re.IGNORECASE,
)
# Copula → (optional adverb, but NOT a data-context word) → optional article →
# the matched token. ``%s`` is filled with the re.escape'd trigger token.
_DEFINITIONAL_PREDICATE_TMPL = (
r"\b(?:ist|sind|war|waren|is|are|was|were|bedeutet|means)\s+"
r"(?:(?!\b(?:in|auf|an|aus|von|mein|meine|meinem|meinen|my|on|from|of)\b)"
r"\w+\s+){0,2}"
r"(?:ein(?:e|er|en)?\s+|a\s+|an\s+|the\s+)?%s\b"
)
def _is_definitional_question_about(user_text: str, token: str) -> bool:
"""True when ``user_text`` is a definitional question whose subject IS the
matched trigger ``token`` — so firing that skill would be wrong."""
if not user_text or not token:
return False
if not _DEFINITIONAL_OPENER_RE.match(user_text):
return False
pat = re.compile(_DEFINITIONAL_PREDICATE_TMPL % re.escape(token), re.IGNORECASE)
return bool(pat.search(user_text))
# Opinion / advice / recommendation / decision questions, and casual
# question-openers ("ich hab da mal eine Frage"). These are CONVERSATION, not
# work: the brain answers them inline — they must NEVER force-spawn a worker,
# even when they contain an everyday word that collides with an action verb in
# the universal catalogue ("Frage" -> "frag"/"frage", the filler particle
# "halt" -> "halt"). A live relocation-comparison turn once force-spawned:
# "ich hab ne Frage ... was würdest du mir empfehlen?"
# force-spawned because has_action_intent matched "Frage"/"halt", so
# _is_generic_subagent_work classified a pure chat turn as generic sub-agent
# work; the answer then returned out-of-band via the MissionAnnouncer and never
# reached the session transcript. Precision over recall: matched only by clear
# opinion/advice/decision phrasings, not by every question. DE/EN/ES, with
# umlaut + ASCII variants (STT emits either). Pure regex (AP-11 safe).
_OPINION_ADVICE_QUESTION_RE = re.compile(
r"(?:"
# advice / recommendation (DE)
r"was\s+(?:w[üu]rdest|wuerdest|w[üu]rde|wuerde)\s+du\b"
r"|was\s+(?:empfiehlst|r[äa]tst|raetst|schl[äa]gst|schlaegst)\s+du\b"
r"|(?:hast|h[äa]ttest|haettest)\s+du\s+(?:einen?\s+)?(?:tipp|rat|empfehlung|vorschlag)"
# opinion (DE)
r"|was\s+(?:h[äa]ltst|haeltst|meinst|denkst|sagst)\s+du\b"
r"|wie\s+(?:siehst|findest|beurteilst)\s+du\b"
r"|(?:deiner|aus\s+deiner)\s+(?:meinung|sicht)\b"
r"|was\s+ist\s+deine\s+(?:meinung|empfehlung|einsch[äa]tzung|einschaetzung)"
# decision help (DE)
r"|soll(?:te)?\s+ich\b[^?]*\boder\b"
r"|was\s+(?:ist|w[äa]re|waere)\s+(?:besser|kl[üu]ger|klueger|sinnvoller)\b"
# conversational question opener (DE). Adjectives/intensifiers between the
# article and "Frage" must not blind the guard: "ich hab mal eine GANZ
# GENERELLE Frage, wie viel Geld hat Elon Musk?" slipped past the rigid
# "eine frage" form and force-spawned a worker for a one-search knowledge
# question (live bug 2026-07-16, voice session 11:49).
r"|ich\s+(?:hab|habe|h[äa]tte|haette)\s+(?:da\s+)?(?:mal\s+)?(?:noch\s+)?(?:'?ne|eine)\s+(?:[\w-]+\s+){0,3}?frage"
r"|kann\s+ich\s+dich\s+(?:mal\s+)?(?:was|etwas)\s+fragen"
# advice / opinion (EN)
r"|what\s+(?:would|do)\s+you\s+(?:recommend|suggest|advise|think)\b"
r"|what\s+should\s+i\b"
r"|should\s+i\b[^?]*\bor\b"
r"|(?:what(?:'s|\s+is)\s+)?your\s+(?:opinion|advice|take|recommendation)\b"
r"|do\s+you\s+think\b"
r"|i\s+(?:have|'ve\s+got|got)\s+a\s+(?:[\w-]+\s+){0,3}?question\b"
r"|can\s+i\s+ask\s+you\b"
# advice / opinion (ES)
r"|qu[ée]\s+(?:me\s+)?(?:recomiendas|aconsejas|sugieres)\b"
r"|qu[ée]\s+(?:opinas|piensas|crees)\b"
r"|tengo\s+una\s+(?:[\w-]+\s+){0,3}?pregunta\b"
r"|deber[íi]a\s+"
r")",
re.IGNORECASE,
)
def _is_opinion_advice_question(user_text: str) -> bool:
"""True for opinion / advice / recommendation / decision questions (and
casual question-openers) that must be answered inline, never force-spawned.
See ``_OPINION_ADVICE_QUESTION_RE`` for the full rationale (live bug
2026-06-19): a conversational turn must not be dispatched to a worker just
because an everyday word collides with an action verb.
"""
return bool(_OPINION_ADVICE_QUESTION_RE.search(user_text or ""))
def _conversational_turn_suppresses_read_mandate(user_text: str) -> bool:
"""True when an opinion/advice/conversational turn must stand the READ
evidence gate down instead of forcing a tool.
Live 2026-06-30 (Bora-Bora voice session): the user asked a plain travel
question — "...bin jetzt bei meinem Budget bei so 25.000 Euro ... passt es?".
The word "budget" matched the cloud-billing domain, the gate FORCED
``cli_gcloud``, the model answered the travel question without that
(irrelevant) tool, and the honesty backstop then VOIDED the good answer
(``executed=[]``). The very same classifier that already inlines such a turn
(force-spawn skip, log "opinion/advice/conversational question — inline")
suppresses the read mandate here, so a chat/advice turn is never dead-ended
by an irrelevant tool it never needed. The tool stays in the surface, so the
model keeps discretion to call it — it is just never *forced*, and the answer
is never voided.
Narrow on purpose (no confab regression): fires ONLY on an actual
opinion/advice/conversational opener. A bare data lookup ("Was sind meine
Abrechnungen?", live 2026-06-17) matches no opener and stays gated. Pure
regex (AP-11). WRITE mandates (``resolve_save_mandate``) are intentional and
handled separately — only the READ gate stands down here.
"""
return _is_opinion_advice_question(user_text)
# A spawn / sub-agent / worker token in DE/EN/ES (declined forms included). Used
# by both the decline guard below and nowhere else — kept local on purpose.
_SPAWN_TOKEN = (
r"(?:sub-?agent\w*|subagent\w*|subagente\w*|worker\w*|trabajador\w*|"
r"spawn\w*|delegier\w*|delegate\w*|delega\w*)"
)
# Explicit spawn DECLINE: the user literally says "don't spawn a subagent" /
# "no sub-agent" / "talk to me directly". The explicit heavy-work trigger hoist
# in ``_should_force_spawn`` is NEGATION-BLIND — it substring-matches the
# trigger word ("Subagent"/"spawn") and force-spawns, doing the exact OPPOSITE
# of what the user asked. A decline must therefore HARD-stand-down BEFORE that
# hoist. Live bug 2026-06-19 (voice session 18:41, Turn 2): "Nee, ich möchte,
# dass du keinen Subagent dafür spawnst. Ich möchte, dass du direkt mit mir
# sprichst." force-spawned (trigger match='Subagent'). Recall over precision: a
# missed decline re-spawns against an explicit "no" (the user-hostile bug);
# a rare over-match only hands the choice back to the brain, which still sees
# spawn_worker and can spawn if it judges so. Pure regex (AP-11), DE/EN/ES,
# umlaut + ASCII variants. Char-window (not word-count) so commas between the
# negation and the token ("nicht, dass du das spawnst") still match.
_SPAWN_DECLINE_RE = re.compile(
r"(?:"
# negated spawn / subagent / worker (DE): kein* / nicht / ohne / niemals
r"\bkein(?:e|en|er|es|s)?\b[^.?!]{0,20}" + _SPAWN_TOKEN
+ r"|\b(?:nicht|ohne|niemals)\b[^.?!]{0,20}" + _SPAWN_TOKEN
# talk-to-me-directly (DE)
+ r"|\bdirekt\s+mit\s+mir\b"
+ r"|\b(?:sprich|red|rede|antwort|antworte|sag)\w*\b[^.?!]{0,15}\bdirekt\b"
# negated spawn / subagent / worker (EN)
+ r"|\b(?:no|without|don'?t|do\s+not|dont|never|not)\b[^.?!]{0,22}" + _SPAWN_TOKEN
# talk-to-me-directly (EN). NB: a bare "just talk/tell me" arm was
# deliberately removed (review MAJOR-1) — without a directness/spawn token
# it false-matched a compound command ("Just tell me, spawn a subagent to
# analyse the logs"), swallowing a genuine spawn request. The directness
# intent is already carried by the \bdirectly\b / \bdirekt mit mir\b arms.
+ r"|\b(?:talk|answer|respond|speak)\b[^.?!]{0,12}\bdirectly\b"
# negated spawn / subagent + talk-directly (ES)
+ r"|\bno\b[^.?!]{0,22}" + _SPAWN_TOKEN
+ r"|\bh[áa]bla(?:me)?\b[^.?!]{0,15}\bdirectamente\b"
+ r")",
re.IGNORECASE,
)
# A leading "No," answers the ASSISTANT'S last proposal; it does not negate the
# vehicle named after it. English collapses two German words into one — "kein"
# (negates the noun) and "nein" (contradicts the previous statement) are both
# "no" — and ``_SPAWN_DECLINE_RE``'s char-window arm reads either as the first.
# Live bug 2026-08-24 (voice session 10:24, Turn 4): Jarvis offered to do the
# job inline, the user corrected him with "No, no, a worker should do it." and
# the gate scored that explicit delegation ORDER as a decline — the exact
# opposite — so the third spawn request in a row was refused. The German arms
# were never affected because they key on "kein/nicht/ohne/niemals", never on
# "nein". Stripped only when the particle is punctuated off ("No, …"), which is
# what makes it a reply rather than a determiner: "No subagent please" has no
# comma, keeps its window, and still declines. Any real negation that follows
# ("No, do not spawn …", "No, no subagent!") matches on its own merits after
# the strip. Pure regex (AP-11).
_CONTRADICTION_LEAD_RE = re.compile(
r"^(?:\s*(?:no|nope|nah|nein|nee|noe)\s*[,;:]+)+\s*", # i18n-allow: spoken input
re.IGNORECASE,
)
def _is_spawn_decline(user_text: str) -> bool:
"""True when the user explicitly declines a worker spawn — "don't spawn a
subagent", "no sub-agent", "talk to me directly". Must override the
negation-blind explicit-trigger hoist in ``_should_force_spawn``.
See ``_SPAWN_DECLINE_RE`` for the full rationale (live bug 2026-06-19,
Turn 2): an explicit decline that NAMES the vehicle ("Subagent"/"spawn")
must never be read as a spawn request. A leading contradiction particle is
dropped first — see ``_CONTRADICTION_LEAD_RE`` (live bug 2026-08-24).
"""
return bool(
_SPAWN_DECLINE_RE.search(_CONTRADICTION_LEAD_RE.sub("", user_text or ""))
)
# The user NAMING the auto-spawn *feature* — talking about it, complaining about
# it, asking to fix it — as opposed to COMMANDING a spawn. "Auto-Spawn" /
# "automatic spawn(ing)" is a feature NAME, never a vehicle imperative: nobody
# dispatches a worker by saying "auto-spawn". The negation-blind vehicle hoist in
# ``_should_force_spawn`` would otherwise substring-match the "spawn" inside
# "auto-spawn" (the hyphen is a \b word boundary) and force-spawn the very thing
# the user is complaining about. Anchored on the "auto"/"automatic" qualifier so
# a bare imperative ("Spawne einen Subagenten …") is untouched — the 2026-06-15
# mandate ("when I say subagent it MUST spawn") stays intact.
_SPAWN_FEATURE_RE = re.compile(
r"\bauto[-\s]?spawn\w*" # auto-spawn / autospawn / auto spawn(ing)
r"|\bautomatic(?:ally)?[\s-]+spawn\w*" # automatic spawn / automatically spawning
r"|\bautomatisch\w*[\s-]+spawn\w*", # automatisches spawnen
re.IGNORECASE,
)
def _is_spawn_feature_reference(user_text: str) -> bool:
"""True when the user names the auto-spawn *feature* (talks about / complains
about / asks to fix it) instead of commanding a worker spawn.
Must override the negation-blind explicit-trigger hoist in
``_should_force_spawn`` — mirroring ``_is_spawn_decline`` — because that hoist
substring-matches the "spawn" inside "Auto-Spawn" and would force-spawn the
very feature the user is complaining about. Live bug 2026-07-01 (voice session
21:26:44): "Auto-Spawn, das müssen wir erstmal fixen" spawned a full Opus
mission whose "still on it" heartbeats then spoke out of nowhere for minutes.
Anchored on "auto"/"automatic" so a bare imperative that NAMES the vehicle
("Spawne einen Subagenten …") is not matched and still force-spawns.
"""
return bool(_SPAWN_FEATURE_RE.search(user_text or ""))
def _prompt_sent_line(terminal: str, files: list[str], lang: str) -> str:
"""Spoken confirmation that an Agentic-IDE terminal received the prompt.
Deliberately short and pane-named: in a four-pane workspace the only thing
the user needs to hear is WHICH agent got it. Naming the attached file when
there is exactly one is worth the extra second — it is also the fastest way
for the user to catch a wrong file before the agent acts on it.
"""
from dodaios.voice.action_phrases import action_phrase
if len(files) == 1:
return action_phrase(
"ide_prompt_sent_one_file", lang, terminal=terminal, file=files[0]
)
if files:
return action_phrase(
"ide_prompt_sent_files", lang, terminal=terminal, count=len(files)
)
return action_phrase("ide_prompt_sent", lang, terminal=terminal)
def _terminal_not_running_line(terminal: str, status: str, lang: str) -> str:
"""Honest readback when the addressed pane is not accepting input."""
from dodaios.voice.action_phrases import action_phrase
return action_phrase(
"ide_terminal_not_running", lang, terminal=terminal, status=status
)
def _join_names(names: Sequence[str], lang: str) -> str:
"""Call-signs as a speakable list ("Iris und Bruno", "Iris, Bruno and Casey")."""
from dodaios.voice.action_phrases import action_phrase
items = [n for n in names if n]
if not items:
return ""
if len(items) == 1:
return items[0]
return action_phrase(
"ide_names_pair", lang, head=", ".join(items[:-1]), last=items[-1]
)
def _fanout_reply_line(result: Any, lang: str) -> str:
"""Spoken readback for a fan-out, naming who got it and who did not.
The live 2026-07-26 lie came from a readback that could only describe
success: one pane was briefed, the sentence named one pane, and the realtime
provider filled the gap from the user's own question ("Iris and Bruno").
Every branch here therefore names the panes it is talking about, and the
partial case is its own sentence rather than an optional clause — an
optional clause is what gets dropped when a model paraphrases.
A single addressee keeps the exact wording the one-pane path always had:
that is the common case, and it should not start sounding like a fleet
operation because the plumbing underneath grew one.
"""
from dodaios.voice.action_phrases import action_phrase
deliveries = result.deliveries
ok = [d.terminal for d in result.delivered]
bad = [d.terminal for d in result.undelivered]
if len(deliveries) == 1:
only = deliveries[0]
if only.delivered:
line = _prompt_sent_line(only.terminal, list(only.files), lang)
elif only.reason_code == "not_running":
line = _terminal_not_running_line(only.terminal, only.status, lang)
else:
line = action_phrase(
"ide_prompt_sent_nobody", lang, failed=only.terminal
)
elif not ok:
line = action_phrase(
"ide_prompt_sent_nobody", lang, failed=_join_names(bad, lang)
)
elif bad:
line = action_phrase(
"ide_prompt_sent_partial",
lang,
names=_join_names(ok, lang),
failed=_join_names(bad, lang),
)
else:
line = action_phrase(
"ide_prompt_sent_many", lang, names=_join_names(ok, lang)
)
stuck = [d.terminal for d in result.typed_but_not_started]
if stuck:
line = f"{line} " + action_phrase(
"ide_prompt_typed_not_started", lang, names=_join_names(stuck, lang)
)
return line
def _recent_agent(recent: Any) -> str:
"""The coding agent a remembered workspace mostly ran, defaulting to Claude.
Reopening a project the user last worked in with Codex should not silently
switch them to a different agent. ``agents`` is a name -> pane-count map, so
the majority answer is the one that matches what they saw last time.
"""
counts = getattr(recent, "agents", None) or {}
if not counts:
return "claude"
return max(counts.items(), key=lambda kv: kv[1])[0]
@dataclass(slots=True)
class _PendingCliChoice:
"""A "did you mean Claude Code or Codex?" waiting for its answer.
Kept on the manager rather than inside the detector for the same reason the
pane-name question is: the detector answers "is this clear?", and only the
turn loop knows what to do about it and when the answer arrives.
The whole fleet is held, not just the unclear part. "Two Klaudi terminals
and one Codex" is ONE request, and opening the Codex pane while asking about
the other two would leave the user answering a question about a workspace
that had already changed under them.
"""
groups: tuple[Any, ...]
"""The parsed fleet. Every group with no CLI takes the answered one."""
utterance: str
candidates: tuple[str, ...]
"""CLI display names offered, best first. The answer names one of these."""
asked_at: float
"""``time.monotonic()`` — the window is short on purpose (see TTL)."""
#: How long the CLI question stays answerable.
#:
#: Two minutes, the same bound as the pane-name question and the delegation
#: offer: long enough for "uh… Codex", short enough that a forgotten question
#: cannot open panes in the middle of an unrelated turn later on.
_CLI_QUESTION_TTL_S = 120.0
#: A short reply is an ANSWER; a sentence is the user moving on.
_CLI_ANSWER_MAX_WORDS = 6
def _available_terminal_kinds() -> str:
"""The coding CLIs this workspace can open, as a spoken list.
Read from the registry rather than written out here: a list kept in a
sentence drifts from the one the workspace actually has, and the whole
reason this sentence exists is to tell the user something true when they
named a CLI that is not on it.
"""
try:
from dodaios.workspace import agents as workspace_agents
names = [agent.display_name for agent in workspace_agents.coding_agents()]
except Exception: # noqa: BLE001 - a phrase must never break a turn
return ""
return ", ".join(names)
def _terminals_spawned_line(
names: list[str], *, requested: int, folder: str | None, lang: str
) -> str:
"""Spoken confirmation for "open N more terminals".
Always names the new panes: they are how the user addresses them in the very
next sentence ("Zara, mach mal ..."), and hearing three names after asking
for five is the fastest possible way to notice the workspace was full.
The names are joined with commas rather than a localized "and" — a list
separator needs no translation, and a per-language conjunction would be one
more thing to get wrong in a fourth locale.
"""
from dodaios.voice.action_phrases import action_phrase
listed = ", ".join(names)
if folder is not None:
# A workspace had to be opened first; naming the folder is what makes the
# assumption auditable.
return action_phrase(
"ide_terminals_opened_workspace", lang, folder=folder, names=listed
)
if len(names) < requested:
return action_phrase(
"ide_terminals_spawned_capped", lang, count=len(names), names=listed
)
if len(names) == 1:
return action_phrase("ide_terminals_spawned_one", lang, names=listed)
return action_phrase(
"ide_terminals_spawned", lang, count=len(names), names=listed
)
# Conversational coaching: "help me [get better at a soft / cognitive /
# conversational skill]" — asking, thinking, phrasing, deciding, understanding,
# expressing, communicating. This is CONVERSATION (Jarvis answers inline and
# asks the user smart questions), never a heavy-worker spawn. It trips the
# action-verb catalogue when the coaching OBJECT is itself a verb ("intelligent
# zu fragen" -> "frag"/"frage"). Live bug 2026-06-19 (voice session 18:41,
# Turn 1): "Hilf mir aber dabei, intelligent zu fragen. Für mich ist Fragen
# einer der Schlüssel für Erfolg, verstehst du?" -> matched action verbs
# ['frag','frage'] -> has_action_intent -> _is_generic_subagent_work ->
# force-spawn. High precision: a help/teach framing AND a cognitive/
# conversational object verb must BOTH be present, so "Hilf mir, eine E-Mail zu
# schreiben und zu senden" (concrete artifact) does NOT match and stays
# spawnable. Pure regex (AP-11), DE/EN/ES, umlaut + ASCII variants (the runtime
# output-language doctrine mandates all three locales; the sibling guards cover
# es too).
_CONVERSATIONAL_COACHING_RE = re.compile(
r"(?:"
# DE: help / teach / show-me-how framing ...
r"\b(?:hilf|hilfst|helfen|helf|bring\s+mir\s+bei|beibring\w*|lehr\w*|"
r"zeig\s+mir,?\s+wie)\b"
r"[^.?!]{0,50}"
# ... + a cognitive / conversational skill object
r"\b(?:frag\w*|denk\w*|nachdenk\w*|formulier\w*|verstehen|verstehe|"
r"entscheid\w*|reflektier\w*|aus(?:zu)?dr[üu]ck\w*|kommunizier\w*|"
r"argumentier\w*|[üu]berleg\w*|zuh[öo]r\w*|reden|sprechen)\b"
# EN: help / teach / show me ... + a cognitive skill object
r"|\b(?:help|teach|show)\s+me\b[^.?!]{0,50}"
r"\b(?:ask|think|phrase|formulate|understand|decide|reflect|communicate|"
r"express|reason|articulate|listen|converse)\b"
# ES: ayúdame / enséñame / muéstrame cómo ... + a cognitive skill object
r"|\b(?:ay[úu]dame|ens[eé][ñn]ame|mu[ée]strame\s+c[óo]mo)\b[^.?!]{0,50}"
r"\b(?:pregunt\w*|pensar|formular|decidir|comunicar|reflexionar|"
r"expresar|razonar|escuchar|hablar|conversar)\b"
r")",
re.IGNORECASE,
)
def _is_conversational_coaching(user_text: str) -> bool:
"""True when the user asks for help getting better at a soft / cognitive /
conversational skill (asking, thinking, phrasing, deciding, understanding).
Answered inline, never force-spawned.
See ``_CONVERSATIONAL_COACHING_RE`` for the full rationale (live bug
2026-06-19, Turn 1): a coaching request must not be dispatched to a worker
just because its skill object collides with an action verb ("fragen").
"""
return bool(_CONVERSATIONAL_COACHING_RE.search(user_text or ""))
def _extract_leaked_spawn_call(text: str) -> dict[str, Any] | None:
"""Return the ``input`` dict of a leaked ``spawn_worker`` tool_use, else None.
Some providers (notably Gemini) intermittently emit a ``tool_use`` block as
the response *text* instead of invoking the tool — the brain reply becomes
raw ``[{"type":"tool_use","name":"spawn_worker","input":{...}}]`` JSON,
which would otherwise be spoken (scrubbed to "Es trat ein Fehler auf") and
the delegated Jarvis-Agent would never run. This accepts only a whole JSON
response (bare or strictly fenced); JSON quoted inside prose is never an
executable instruction.
"""
for call in extract_leaked_tool_calls(text):
if call.get("name") == "spawn_worker":
return dict(call.get("input") or {})
return None
def _may_be_tool_use_leak(text: str) -> bool:
"""Cheap shape test: could ``text`` still turn out to be a leaked tool_use?
Structured JSON at the very start (optionally inside a ```json fence) is the
only cue available while a stream is still growing. It is a SUSPICION, never
a verdict — a perfectly good answer may open with a markdown link
(``[Doku](…)``) or a JSON example. Use it only to WITHHOLD a chunk until the
buffer is complete; :func:`_looks_like_tool_use_leak` then decides for real.
"""
if not text:
return False
s = text.lstrip()
if s.startswith("```"):
s = s.lstrip("`")
if s[:4].lower() == "json":
s = s[4:]
s = s.lstrip()
return s.startswith("[") or s.startswith("{")
def _is_whole_structured_document(text: str) -> bool:
"""True when ``text`` is ONE structured document and nothing else.
``[Doku](https://…) beschreibt das genau.`` opens with ``[`` but carries
prose after the bracket — that is speech. ``{"exit_code": 0, …}`` and its
Python-repr twin ``{'exit_code': 0, …}`` are blobs with no prose at all and
must never reach TTS. Parsing decides; the first character does not.
"""
s = text.strip()
if s.startswith("```") and s.endswith("```") and len(s) > 6:
s = s[3:-3].strip()
if s[:4].lower() == "json":
s = s[4:].strip()
if not (s.startswith("[") or s.startswith("{")):
return False
try:
json.loads(s)
return True
except (json.JSONDecodeError, ValueError):
pass # not JSON — the Python-repr shape is tried next
# A Python repr is not JSON but is just as unspeakable. Literals only —
# ``literal_eval`` never executes anything. Bounded so a long prose answer
# that merely opens with a bracket cannot cost real parse time.
if len(s) > 20_000:
return False
try:
ast.literal_eval(s)
except (ValueError, SyntaxError, MemoryError, RecursionError):
return False # not a Python literal either — this is prose, not a blob
return True
def _looks_like_tool_use_leak(text: str) -> bool:
"""True if ``text`` IS a provider's tool_use block emitted as TEXT.
The authoritative verdict, for a COMPLETE buffer. The old test — "the text
starts with ``[`` or ``{``" — was a suspicion promoted to a verdict: an
answer opening with a markdown link or a JSON example was classed as a leak
and, on the streaming path, silently dropped in full. So the shape test only
gates the real check now: either the strict recovery parser finds an actual
tool call, or the whole text is a structured document with no prose in it.
"""
if not _may_be_tool_use_leak(text):
return False
if extract_leaked_tool_calls(text):
return True
return _is_whole_structured_document(text)
_CLI_TOOL_PREFIX = "cli_"
# Lines a CLI prints when it wants interactive confirmation — never spoken.
_CLI_PROMPT_NOISE_RE = re.compile(
r"\(y/n\)|\[y/n\]|would you like to|do you want to continue|press any key",
re.IGNORECASE,
)
def _extract_cli_error_line(stderr: str) -> str:
"""Pick the most informative, speakable line out of a CLI's stderr.
Prefers an ``ERROR:``-prefixed line (the actionable cause), strips the
``ERROR: (gcloud.x.y)`` command-path prefix, and skips interactive-prompt
noise such as ``Would you like to enable and retry (y/N)?``. Returns ``""``
when nothing speakable remains. Pure string work — no LLM (AP-11).
"""
lines = [ln.strip() for ln in (stderr or "").splitlines() if ln.strip()]
speakable = [ln for ln in lines if not _CLI_PROMPT_NOISE_RE.search(ln)]
error_lines = [ln for ln in speakable if ln.upper().startswith("ERROR")]
chosen = (error_lines or speakable or [""])[0]
# Drop a leading "ERROR: (gcloud.billing.budgets.list) " command-path prefix.
chosen = re.sub(r"^ERROR:\s*(\([^)]*\)\s*)?", "", chosen, flags=re.IGNORECASE)
return chosen.strip()[:200]
# Spoken CLI-failure readbacks; placeholders {cause} / {code}.
_CLI_FAILURE_PHRASES: dict[str, dict[str, str]] = i18n_catalog.locale_maps("brain.cli_failure")
# Spoken reply when a recovered tool ran but produced nothing speakable.
_NOTHING_FOUND_PHRASE: dict[str, str] = i18n_catalog.table("brain.nothing_found")
# Navigation fast-path acknowledgement; placeholder {label}.
_NAVIGATION_ACK: dict[str, str] = i18n_catalog.table("brain.navigation_ack")
def _cli_failure_reason(output: Any, error: str | None, *, language: str) -> str:
"""Honest spoken readback for a FAILED ``cli_<name>`` call.
The user must never hear a bare ``exit 1`` (the CLI tool's ``error`` field)
nor "Dazu habe ich nichts gefunden". Surface the stderr cause if present,
else name the exit code. Static, no LLM (AP-11); mirrors
:func:`dodaios.voice.action_phrases.cu_failure_readback` (live repro
2026-06-17, ``gcloud billing budgets list`` → exit 1 narrated as "nothing
found").
"""
stderr = ""
exit_code: int | None = None
if isinstance(output, dict):
stderr = str(output.get("stderr") or "")
ec = output.get("exit_code")
if isinstance(ec, int):
exit_code = ec
phrases = _CLI_FAILURE_PHRASES.get(language, _CLI_FAILURE_PHRASES["en"])
cause = _extract_cli_error_line(stderr)
if cause:
return phrases["cause"].format(cause=cause)
if exit_code is None and error:
m = re.search(r"exit\s+(-?\d+)", error)
if m:
exit_code = int(m.group(1))
if exit_code is not None:
return phrases["code"].format(code=exit_code)
return phrases["bare"]
def _evidence_answer_is_unverified(
required_tool: str, executed: set[str], response_text: str, *, suppressed: bool
) -> bool:
"""True when a mandated-tool turn produced an answer WITHOUT calling the tool.
The evidence gate's ``require_tool`` directive tells the model to answer ONLY
from the tool's result. If the model returns a non-empty answer but the
mandated tool never ran (``executed_tool_names``), that answer is necessarily
unverified — at worst a confabulation (live repro 2026-06-17, session
296abc82: the model invented "the gcloud tool blocked execution because it
classified the request as an explanatory question"). Empty answers and
fire-and-forget ``suppress_response`` turns are handled elsewhere, so they
are excluded here.
"""
if not required_tool or suppressed:
return False
if required_tool in (executed or set()):
return False
return bool((response_text or "").strip())
# A concrete particular — something the answer could only have if it had the
# data in front of it: a clock time, a calendar date, any figure, a named
# weekday or month, an address or link, a list of items, or a bare statement
# that there are none. Explanations and general knowledge carry none of these.
# Deliberately broad on the "specific" side: over-detecting costs one honest
# fallback, under-detecting speaks a confabulation.
_CONCRETE_DATUM_RE = re.compile(
r"\d" # any figure at all
r"|\bhttps?://|\bwww\.|@[\w.-]+\.\w{2,}" # a link or an address
r"|^\s*[-*•]\s+.+$" # a bullet item
r"|\b(?:"
# Named days and months. DE / EN / ES — the answer surface is localized.
r"montag|dienstag|mittwoch|donnerstag|freitag|samstag|sonnabend|" # i18n-allow
r"sonntag|" # i18n-allow
r"januar|februar|m[äa]rz|dezember|oktober|" # i18n-allow: DE months that differ from EN
r"monday|tuesday|wednesday|thursday|friday|saturday|sunday|"
r"january|february|march|april|may|june|july|august|september|october|"
r"november|december|"
r"lunes|martes|mi[ée]rcoles|jueves|viernes|s[áa]bado|domingo|"
r"enero|febrero|marzo|abril|mayo|junio|julio|agosto|septiembre|"
r"octubre|noviembre|diciembre"
r")\b"
# "you have none" is as much a claim about the data as naming an item. The
# subject is required — a bare "kein"/"no" belongs to ordinary prose
# ("not by a spark plug") and must not count.
r"|\b(?:du\s+hast|es\s+(?:gibt|sind|ist))(?:\s+\w+){0,3}\s+" # i18n-allow: DE existence claim
r"(?:keine?|nichts)\b" # i18n-allow: DE existence claim
r"|\b(?:you\s+have|there\s+(?:is|are))(?:\s+\w+){0,3}\s+"
r"(?:no|none|nothing)\b"
r"|\b(?:tienes|hay)(?:\s+\w+){0,3}\s+(?:ning[úu]n\w*|nada)\b",
re.IGNORECASE | re.MULTILINE,
)
# The answer attributes the fact to what was already said in this conversation.
# Repeating something the user themselves stated is not a fabrication, and no
# tool could have grounded it — the honest fallback would be the wrong answer.
_CONVERSATION_ATTRIBUTION_RE = re.compile(
r"\b(?:"
r"du\s+hattest\s+\w*\s?gesagt|du\s+sagtest|hattest\s+du\s+gesagt|" # i18n-allow
r"wie\s+(?:du\s+)?(?:gesagt|erw[äa]hnt|besprochen)|" # i18n-allow: DE history reference
r"vorhin\s+(?:gesagt|erw[äa]hnt)|laut\s+deiner\s+angabe|" # i18n-allow: DE history reference
r"you\s+(?:said|told\s+me|mentioned)|as\s+you\s+(?:said|mentioned)|"
r"earlier\s+you\s+(?:said|mentioned)|from\s+what\s+you\s+told\s+me|"
r"(?:me\s+)?dijiste|seg[úu]n\s+me\s+dijiste|como\s+mencionaste"
r")\b",
re.IGNORECASE,
)
# A claim about the mandated tool ITSELF — that it ran, refused, failed, or
# returned something. The 2026-06-17 confabulation was exactly this shape ("the
# gcloud tool blocked execution because it classified the request as an
# explanatory question"): no figure, no date, and entirely invented. Nothing the
# user said can excuse it, so it is never exempted by attribution.
_TOOL_NOUN_RE = re.compile(
r"\b(?:tool|werkzeug|befehl|kommando|cli|api|abfrage|query|command|" # i18n-allow: DE tool noun
r"skript|script|herramienta|comando|consulta)\w*",
re.IGNORECASE,
)
_EXECUTION_VERB_RE = re.compile(
r"\b(?:blockier\w*|verweiger\w*|abgelehnt|fehlgeschlagen|" # i18n-allow: DE execution verb
r"zur[üu]ckgegeben|ausgef[üu]hrt|gelaufen|geliefert|aufgerufen|" # i18n-allow
r"gestartet|" # i18n-allow
r"block\w*|refus\w*|denied|deny|return\w*|fail\w*|ran|run|executed|"
r"invoked|called|"
r"bloque\w*|rechaz\w*|devolv\w*|fall\w*|ejecut\w*|llam\w*)\b",
re.IGNORECASE,
)
def _answer_claims_tool_behaviour(response_text: str) -> bool:
"""True when the answer says what the mandated tool did — it did nothing."""
text = response_text or ""
return bool(_TOOL_NOUN_RE.search(text) and _EXECUTION_VERB_RE.search(text))
def _answer_claims_unverified_data(response_text: str) -> bool:
"""True when the answer reports a PARTICULAR the mandated tool never supplied.
The evidence backstop used to replace *every* answer of a turn whose
mandated tool did not run. That deleted correct answers: the model explains
how something works, or repeats what the user said two turns ago, and the
user hears "Ich konnte das gerade nicht abrufen" instead — the guard
fabricating a failure to prevent a fabrication.
So the backstop now needs an actual claim, of one of two kinds: a statement
about what the mandated tool did (:func:`_answer_claims_tool_behaviour`), or
a concrete particular (:data:`_CONCRETE_DATUM_RE`) that is not attributed to
the conversation itself. An answer made of explanation alone claims nothing
and stays.
Pure regex, no LLM (AP-11). This judges DATA claims only — a false *action*
claim ("I checked your calendar") carries no particular and is caught by
:func:`replace_unbacked_action_claim` right after this guard.
"""
text = (response_text or "").strip()
if not text:
return False
if _answer_claims_tool_behaviour(text):
return True
if not _CONCRETE_DATUM_RE.search(text):
return False
return not _CONVERSATION_ATTRIBUTION_RE.search(text)
_EVIDENCE_UNFULFILLED_PHRASES: dict[str, str] = i18n_catalog.table("brain.evidence_unfulfilled")
# Spoken domain labels for the honest "couldn't reach X" fallback. Mirrors the
# capability vocabulary already used by evidence_gate's refusal tables, so a
# mandated-but-unrun READ names the real domain ("…deine Cloud-Abrechnung…")
# instead of the generic "the tool" — which also seeds the conversation history
# so a follow-up "welches Werkzeug?" is answerable. Localized for every
# supported language; an unknown domain falls back to the generic phrase.
_EVIDENCE_DOMAIN_LABELS: dict[str, dict[str, str]] = i18n_catalog.locale_maps(
"brain.evidence_domain_labels"
)
# Domain-aware variant of the unfulfilled phrase — same honesty contract (never
# claims a "block"/invents a reason), just names the capability via {label}.
_EVIDENCE_UNFULFILLED_DOMAIN_PHRASES: dict[str, str] = i18n_catalog.table(
"brain.evidence_unfulfilled_domain"
)
def _evidence_unfulfilled_answer(*, lang: str, domain: str = "") -> str:
"""Honest spoken fallback for a mandated-tool turn whose tool never ran.
Static, no LLM (AP-11). Never claims the tool "blocked" or invents a reason.
When ``domain`` is a known external-data domain the phrase NAMES the
capability ("…deine Cloud-Abrechnung…"); otherwise it degrades to the generic
wording. Localized for every supported language (de/en/es/pt); an unrecognised
code degrades to the default locale so the spoken turn never crashes (Runtime
Output Language doctrine).
"""
if lang not in _EVIDENCE_UNFULFILLED_PHRASES:
lang = DEFAULT_LOCALE
label = _EVIDENCE_DOMAIN_LABELS.get(lang, {}).get(domain, "")
if label:
return _EVIDENCE_UNFULFILLED_DOMAIN_PHRASES[lang].format(label=label)
return _EVIDENCE_UNFULFILLED_PHRASES[lang]
# Honest spoken fallback for a mandated WRITE (e.g. contact-upsert) that never
# ran — the say-do gap (live voice session 2026-06-30: "Okay, sehr gut" spoken
# while no contact was saved). Distinct from the READ fallback above: it speaks
# to a write ("not saved yet"), not a failed lookup. Static, no LLM (AP-11);
# localized for every supported language, unknown code → default locale.
_ACTION_UNFULFILLED_PHRASES: dict[str, dict[str, str]] = i18n_catalog.nested_table(
"brain.action_unfulfilled"
)
# A write tool with no bespoke table reuses the contact wording's shape.
_ACTION_UNFULFILLED_DEFAULT = _ACTION_UNFULFILLED_PHRASES["contact-upsert"]
def _action_unfulfilled_answer(required_tool: str, *, lang: str) -> str:
"""Honest spoken fallback for a mandated WRITE tool that never ran.
Mirrors :func:`_evidence_unfulfilled_answer` but for a write/create action:
it must never claim the save happened. Unknown tool or language degrades to
the contact wording / default locale so the spoken turn never crashes.
"""
table = _ACTION_UNFULFILLED_PHRASES.get(required_tool, _ACTION_UNFULFILLED_DEFAULT)
return i18n_catalog.pick(table, lang)
def _unfulfilled_replacement(
*,
required_tool: str,
executed: set[str],
response_text: str,
suppressed: bool,
is_write: bool,
lang: str,
domain: str = "",
) -> str | None:
"""Decide whether a mandated-tool turn's answer must be replaced for honesty.
Returns the honest replacement text, or ``None`` to keep the answer as-is.
Shared by the read evidence gate and the write (contact) say-do guard.
A WRITE mandate additionally LEAVES A CLARIFYING QUESTION intact: asking the
user to repeat a missing/broken field (e.g. the '@'-less email) is the
desired behavior, not a fake claim — only a flat confirmation with no
question is corrected.
A READ mandate leaves an answer that CLAIMS NOTHING intact: an explanation,
or a fact the user themselves supplied earlier, is not a confabulation and
must not be traded for "I couldn't retrieve that" (see
:func:`_answer_claims_unverified_data`).
"""
if not _evidence_answer_is_unverified(
required_tool, executed, response_text, suppressed=suppressed
):
return None
if is_write:
if "?" in (response_text or ""):
return None # honest clarifying question — keep it
return _action_unfulfilled_answer(required_tool, lang=lang)
if not _answer_claims_unverified_data(response_text):
return None # nothing was claimed — nothing to correct
return _evidence_unfulfilled_answer(lang=lang, domain=domain)
def _safe_recovered_text(value: Any) -> str:
"""Redact, cap, and reject tool-envelope text before it reaches speech."""
text = safe_preview(value, max_chars=600)[:600].strip()
return "" if _looks_like_tool_use_leak(text) else text
def _render_recovered_tool_output(output: Any) -> str:
"""Speakable plain-text rendering of a recovered tool's output.
Why this exists (live repro 2026-06-14, voice "Was hältst du von exp.com?"):
a *read* tool such as ``search_web`` returns STRUCTURED data
(``{"query": …, "results": [{"title", "snippet", …}]}``), not a spoken
sentence. A properly-invoked tool call re-injects that data for a follow-up
brain turn that phrases it; the leaked-recovery shortcut
(:meth:`BrainManager._recover_leaked_tool`) has no such turn, so it used to
return ``str(result.output)`` — a ``{``-prefixed Python repr. The streaming
guard :func:`_looks_like_tool_use_leak` then mistook that ANSWER for ANOTHER
leaked tool_use block, dropped it, and the user heard the canned
"Ich habe die Aktion erkannt, konnte sie aber nicht ausführen." even though
the search had succeeded.
This renders structured output to readable text that never begins with
``{``/``[``. An empty return means "nothing speakable" — the caller then
supplies a localized 'nothing found' fallback (never a repr, never the
failure phrase).
"""
if output is None:
return ""
if isinstance(output, str):
return _safe_recovered_text(output)
if isinstance(output, dict):
results = output.get("results")
if isinstance(results, list):
parts: list[str] = []
for item in results:
if not isinstance(item, dict):
continue
title = _safe_recovered_text(item.get("title") or "")
snippet = _safe_recovered_text(item.get("snippet") or "")
if snippet and title and title.lower() not in snippet.lower():
parts.append(f"{title}: {snippet}")
else:
parts.append(snippet or title)
joined = " ".join(p for p in parts if p).strip()
return _safe_recovered_text(joined)
# CLI tools (cli_<name>) return {exit_code, stdout, stderr, duration_ms}.
# This renderer is reached only after the caller verified success, so a
# non-empty stdout IS the answer — surface it instead of dead-ending in
# "" (which made the caller speak "Dazu habe ich nichts gefunden" even
# though gcloud returned real project data; live repro 2026-06-17).
if "exit_code" in output and ("stdout" in output or "stderr" in output):
return _safe_recovered_text(output.get("stdout") or "")
# Connected tools use many result schemas. Preserve a bounded set of
# human-facing scalar fields while omitting technical identifiers,
# raw bodies, URLs, tokens, and headers. The normal ToolUseLoop gives
# structured results back to the model for synthesis; this branch is a
# defense-in-depth fallback when a provider leaked the call as text.
parts: list[str] = []
for key in (
"sender", "from", "subject", "title", "date", "time", "status",
"summary", "description",
):
val = output.get(key)
if isinstance(val, str) and val.strip():
rendered = _safe_recovered_text(val)
if rendered:
parts.append(rendered)
elif isinstance(val, (list, tuple)):
rendered = _render_recovered_tool_output(val)
if rendered:
parts.append(rendered)
if parts:
return _safe_recovered_text(" — ".join(parts))
normalized_keys = {
re.sub(r"[^a-z0-9]", "", str(key).lower()) for key in output
}
has_private_or_technical_key = any(
key.endswith(("id", "token"))
or any(
marker in key
for marker in (
"body", "secret", "authorization", "header", "raw",
"html", "attachment", "payload", "apikey",
)
)
for key in normalized_keys
)
if not has_private_or_technical_key:
# Preserve the established fallback contract for compact explicit
# answer/status mappings. ``content`` remains excluded because
# connector schemas routinely use it for full private bodies.
for key in ("text", "answer", "message", "result"):
val = output.get(key)
if isinstance(val, str) and val.strip():
return _safe_recovered_text(val)
# Fail closed for unknown mappings. Connector schemas commonly store
# full private bodies under content/message/result and use camelCase
# identifiers/tokens, so a generic scalar fallback can disclose data.
return ""
if isinstance(output, (list, tuple)):
rendered_items = (
_render_recovered_tool_output(item).strip() for item in output
)
joined = " ".join(item for item in rendered_items if item).strip()
return _safe_recovered_text(joined)
return _safe_recovered_text(output)
def _extract_leaked_tool_call(text: str) -> tuple[str, dict[str, Any]] | None:
"""Return ``(tool_name, input_dict)`` of ANY leaked tool_use block, else None.
Generalises :func:`_extract_leaked_spawn_call` (spawn-only) to EVERY router
tool — ``cli_*``, ``open_app``, ``dispatch_to_harness``, ``screenshot`` …
Gemini intermittently emits the ``tool_use`` block as response *text*
instead of invoking it; in the streaming voice path that JSON would be
spoken (scrubbed to silence) and the action would never run. This recovers
the call so it can be executed deterministically (see
:meth:`BrainManager._recover_leaked_tool`).
"""
calls = extract_leaked_tool_calls(text)
if calls:
call = calls[0]
return str(call["name"]), dict(call.get("input") or {})
return None
# Single source of truth for the reply-language vocabulary (Python ↔ REST ↔ TS).
# "auto" = mirror the user's input language; the rest hard-pin that language.
SUPPORTED_REPLY_LANGUAGES: tuple[str, ...] = ("auto", *SUPPORTED_LOCALES)
# French speech can be pinned in configuration without adding a translated UI.
_REPLY_LANGS: frozenset[str] = frozenset((*SUPPORTED_REPLY_LANGUAGES, "fr"))
_REPLY_LANG_NAMES: dict[str, str] = {**SUPPORTED_LANGUAGE_NAMES, "fr": "French"}
# Spoken confirmation for a deterministic reply-language switch (the
# voice_command_gate "language_switch" path). Keyed by target code and phrased
# IN that language so — because set_reply_language() runs first — the TTS voice
# resolves to the new language and the switch is audible. "auto" has no single
# language, so it confirms in the conversation's phrase language
# (``brain.lang_switch_confirm_auto``; English for an unsupported one).
_LANG_SWITCH_CONFIRM: dict[str, str] = i18n_catalog.table("brain.lang_switch_confirm")
# Spoken when the live reply-language switch applied but PERSIST failed (read-only
# / locked jarvis.toml). Honest: scoped to this session, not "from now on", because
# it reverts on restart (audit 2026-06-27). de/en/es/pt.
_LANG_SWITCH_CONFIRM_SESSION: dict[str, str] = i18n_catalog.table(
"brain.lang_switch_confirm_session"
)
# Sub-agent (Heavy-Task worker) provider switch — the voice_command_gate
# "subagent_switch" path. The gate returns the spoken provider word; this maps
# it to a CANONICAL [brain.sub_jarvis].provider slug (the values are the only
# accepted ones — this map IS the validation). Persisted via the 3-layer
# config_writer.set_sub_jarvis_provider so the drift-guard cannot revert it; the
# running worker re-resolves it per mission (_live_subagent_provider), so the
# switch applies to the NEXT mission without a restart.
_SUBAGENT_VOICE_TO_CANONICAL: dict[str, str] = {
"openai": "openai", "gpt": "openai",
"codex": "openai-codex", "chatgpt": "openai-codex", "openai-codex": "openai-codex",
"claude": "claude-api", "anthropic": "claude-api",
"gemini": "gemini",
"openrouter": "openrouter",
"grok": "grok",
"nvidia": "nvidia", "nim": "nvidia", "nemotron": "nvidia",
"antigravity": "antigravity",
"grok-build": "grok-build",
"grok build": "grok-build",
"grokbuild": "grok-build",
"grok-cli": "grok-build",
}
_SUBAGENT_DISPLAY: dict[str, str] = {
"openai": "OpenAI", "openai-codex": "Codex", "claude-api": "Claude",
"gemini": "Gemini", "openrouter": "OpenRouter", "grok": "xAI Grok",
"nvidia": "NVIDIA NIM",
"antigravity": "Antigravity",
"grok-build": "Grok Build",
}
_SUBAGENT_SWITCH_CONFIRM: dict[str, str] = i18n_catalog.table("brain.subagent_switch_confirm")
# Honest spoken failure phrases for a deterministic subagent switch that the
# validated apply_provider_switch refused (missing credential / unknown). Never
# a false "done"; always names what failed. de/en/es/pt (Runtime Output Language).
_SUBAGENT_SWITCH_FAIL: dict[str, dict[str, str]] = i18n_catalog.nested_table(
"brain.subagent_switch_fail"
)
def _subagent_switch_failure_phrase(result: dict, display: str, lang: str) -> str:
kind = str(result.get("error_kind") or "other")
table = _SUBAGENT_SWITCH_FAIL.get(kind, _SUBAGENT_SWITCH_FAIL["other"])
return i18n_catalog.pick(table, lang).format(p=display)
# Main-brain provider switch — the voice_command_gate "provider_switch" path.
# Mirrors the subagent tables: routed through the validated apply_provider_switch
# so the spoken readback is HONEST (audit 2026-06-27: the old path returned ""
# silently, even when the switch was refused). de/en/es/pt (Runtime Output Language).
_PROVIDER_SWITCH_CONFIRM: dict[str, str] = i18n_catalog.table("brain.provider_switch_confirm")
_PROVIDER_SWITCH_FAIL: dict[str, dict[str, str]] = i18n_catalog.nested_table(
"brain.provider_switch_fail"
)
def _provider_switch_failure_phrase(result: dict, display: str, lang: str) -> str:
kind = str(result.get("error_kind") or "other")
table = _PROVIDER_SWITCH_FAIL.get(kind, _PROVIDER_SWITCH_FAIL["other"])
return i18n_catalog.pick(table, lang).format(p=display)
# Background-task cancel — the voice_command_gate "cancel" path. Honest readback:
# names the count when something was stopped, says so plainly when nothing ran
# (audit 2026-06-27: the old path was silent either way). de/en/es/pt.
_CANCEL_CONFIRM: dict[str, str] = i18n_catalog.table("brain.cancel_confirm")
_CANCEL_NONE: dict[str, str] = i18n_catalog.table("brain.cancel_none")
# Thinking-depth override — the voice_command_gate "depth_deep"/"depth_fast"
# path. Confirms the new depth instead of staying silent (audit 2026-06-27).
_DEPTH_CONFIRM: dict[str, dict[str, str]] = i18n_catalog.nested_table("brain.depth_confirm")
# The one standing contract every substantive prompt carries: the honesty rule
# (said once in the whole prompt; the unbacked-claim backstop enforces it), the
# research-versus-action routing difference, and the self-control facts the
# model cannot know. Every attached tool already reaches the model as a full
# function definition, so the prompt carries no tool-name list. Static, so the
# cached system prefix stays byte-stable.
_CORE_CONTRACT = (
"Never claim an action or result unless a tool call in this turn returned it; "
"otherwise say it has not happened. A denied or failed call returned nothing: "
"never supply its answer yourself; say what was blocked and why.\n"
"Research and fresh facts (news, prices, weather): search_web, never cli_*; cli_* "
"and plugin tools act on the user's own accounts; evergreen knowledge needs no tool. "
"Work for one of your agents: delegate_to_agent; spawn_worker only for heavy "
"background work the user asked for.\n"
"Dodaios's own settings (wake phrase, voice, providers, language, restart) are yours "
"to change: its command tools such as `brain-switch` or `wake-word-set`, "
"`set_config_value` for a plain key, `cli_jarvisctl` as the fallback."
)
# Conversational style for typed (written) turns: the shared system prompt
# carries the voice persona's spoken-output rules, which must not govern an
# answer that is read on screen.
_WRITTEN_CHAT_STYLE = (
"WRITTEN CHAT STYLE: this turn is typed and read on screen, so the SPOKEN OUTPUT "
"rules do not apply; Markdown and digits are fine where they help. No emojis."
)
# The written-only rules, for a prompt that already carries the shared policy
# (a society agent's briefing has it under "How to reply to the person").
_WRITTEN_CHAT_RULES = _WRITTEN_CHAT_STYLE
# Keep the API chat and the main brain's written delivery equally conversational.
_WRITTEN_CHAT_STYLE += "\n" + CONVERSATIONAL_RESPONSE_STYLE
#: Upper bound for the legacy core-memory block in the system prompt.
_CORE_MEMORY_MAX_CHARS = 20_000
def _is_written_turn() -> bool:
"""True when the current turn is a typed (written) turn, not voice.
Reads the per-turn override's tool context (``{"delivery": "written"}``,
set by the agent-chat brain runner for every typed chat turn). Defensive:
any missing piece means a voice-style turn, so the spoken-output rules
keep applying.
"""
try:
override = _TURN_OVERRIDE.get()
except Exception: # noqa: BLE001 — no override context: voice-style turn
return False
if override is None:
return False
context = getattr(override, "tool_context", None)
if not isinstance(context, dict):
try:
context = dict(context or {})
except Exception: # noqa: BLE001 — unexpected mapping shape
return False
return context.get("delivery") == "written"
def normalize_reply_language(value: object) -> str:
"""Coerce a raw reply-language value to a known code, else ``"auto"``.
Accepts case-insensitive, whitespace-padded input. Unknown / empty / None
fall back to ``"auto"`` (mirror the user's input language) so a typo in
jarvis.toml never silently breaks the voice/chat path.
"""
if not isinstance(value, str):
return "auto"
code = value.strip().lower()
return code if code in _REPLY_LANGS else "auto"
# Spoken fallback when the ENTIRE provider chain fails (no key, depleted
# credits, all rate-limited). The detailed provider/billing diagnostic
# (``_format_provider_chain_error``) is developer-facing and must NEVER reach
# the voice path — a concierge does not read "Account-Problem bei grok …
# console.x.ai/team/billing" aloud (live complaint 2026-06-01). Instead we
# speak a short, provider-agnostic apology in the user's SELECTED reply
# language (de/en/es/pt; "auto" → German, the default locale). Three variants
# per language so repeated failures in one session don't sound robotic
# (mirrors the ACK-variant approach). The full diagnostic stays in the logs.
_PROVIDER_DOWN_PHRASES: dict[str, tuple[str, ...]] = i18n_catalog.variant_table(
"brain.provider_down"
)
# Cause-aware variants of the total-failure apology (maintainer directive
# 2026-07-21: "when such an error happens, SAY what it was about"). One
# spoken sentence per root-cause CATEGORY — still voice-safe (no provider
# names, no URLs, no billing pages; ADR-0010) but honest about WHY, with the
# in-app recovery step. Keys mirror the ``kind`` values classified by the
# provider chain (``_format_provider_chain_error``); an unknown/unlisted kind
# falls back to the generic rotation above.
_PROVIDER_DOWN_CAUSE_PHRASES: dict[str, dict[str, str]] = i18n_catalog.nested_table(
"brain.provider_down_cause"
)
# Priority when several providers failed for different reasons — the FIRST
# matching kind names the spoken cause. Mirrors the root-cause ordering of
# ``_format_provider_chain_error`` (missing key beats rate limit, etc.);
# ``skipped_cooldown`` collapses onto rate_limit and network/other onto
# ``unreachable``.
_PROVIDER_DOWN_CAUSE_PRIORITY: tuple[str, ...] = (
"missing_key",
"bad_key",
"account_blocked",
"vision_unsupported",
"invalid_model",
"local_context",
"context_overflow",
"rate_limit",
"unreachable",
)
def _primary_provider_down_cause(
errors: list[tuple[str, str, str, str]] | None,
) -> str | None:
"""Map a provider-error list onto the single spoken cause category."""
if not errors:
return None
kinds = {kind for _prov, _model, kind, _detail in errors}
if "skipped_cooldown" in kinds:
kinds.add("rate_limit")
if kinds - {
"missing_key",
"bad_key",
"account_blocked",
"vision_unsupported",
"invalid_model",
"local_context",
"context_overflow",
"rate_limit",
"skipped_cooldown",
"empty_response",
}:
# Any unclassified failure (network, timeout, 5xx) reads as
# unreachable — the honest generic cause.
kinds.add("unreachable")
for cause in _PROVIDER_DOWN_CAUSE_PRIORITY:
if cause in kinds:
return cause
return None
def _provider_down_phrase(lang: str, idx: int, cause: str | None = None) -> str:
"""Localized apology for a total brain-chain failure, cause-aware.
``lang`` is a reply-language code (de/en/es/pt); anything else — notably
"auto" or a language without translations — falls back to English
(``DEFAULT_LOCALE``). When ``cause`` names
a known failure category, the phrase states WHY and the in-app recovery
step (maintainer directive 2026-07-21) — still without provider names,
URLs, or jargon (ADR-0010). Otherwise ``idx`` rotates deterministically
through the generic variants so repeated failures in one session don't
repeat the identical sentence.
"""
lang_key = (lang or "").strip().lower()
if cause:
cause_table = _PROVIDER_DOWN_CAUSE_PHRASES.get(cause)
if cause_table:
return i18n_catalog.pick(cause_table, lang_key)
variants = i18n_catalog.pick(_PROVIDER_DOWN_PHRASES, lang_key)
return variants[idx % len(variants)]
# AD-OE6: a model round that dies AFTER tools already ran must end in an honest
# spoken notice, never silence. Forensic 2026-07-05 (session 3e27dd8e): the
# provider sent finish_reason="error" on a ~224k-token round following 10+
# executed tools; the empty-response guard is (correctly) skipped when tool
# calls exist, so the turn counted as success with empty text — the user heard
# NOTHING. Voice-safe: no provider names, no jargon (ADR-0010).
_MID_ANSWER_ERROR_PHRASES: dict[str, str] = i18n_catalog.table("brain.mid_answer_error")
#: Source layers that run without a person waiting on the reply. An appshot
#: parked for "the next message" belongs to the user's next message, never to
#: a scheduled task or a background worker that happens to run first.
_AUTOMATED_LAYER_PREFIXES = (
"tasks",
"workflows",
"skills",
"missions",
"society",
"supervisor",
"tool.",
)
def _takes_pending_appshot(source_layer: str | None) -> bool:
layer = (source_layer or "").strip().lower()
return not layer.startswith(_AUTOMATED_LAYER_PREFIXES)
def _current_turn_language(owner: object) -> str:
"""This turn's language: the context's own, else the last one set."""
return TURN_LANGUAGE.get() or getattr(owner, "_turn_detected_lang", "")
def _turn_phrase_language(owner: object, user_text: str) -> str:
"""The de/en/es/pt language of a system phrase for *user_text*.
One resolver for every canned phrase: the pin, else the language
``generate()`` resolved for this turn (which already applied stickiness,
the chat's own history and ``language_text`` — so an internal English
"continue" prompt does not make the error phrases English), else the text
within the running conversation, else English. ``generate()`` only
receives text (the pipeline resolves the STT tag separately), hence
``"unknown"`` as the tag. Reads the manager's fields with ``getattr`` so
lightweight stand-ins work too.
"""
pin = getattr(owner, "_reply_language", "")
if pin in _REPLY_LANG_NAMES:
return pin
turn = TURN_LANGUAGE.get()
if turn:
return phrase_locale(turn) if is_known_language(turn) else DEFAULT_LOCALE
return resolve_output_language(
pin,
"unknown",
user_text,
conversation_language=getattr(owner, "_conversation_language", ""),
)
def _is_local_provider(provider: str | None) -> bool:
"""True for an on-device provider (no key, no price list)."""
try:
from dodaios.brain.app_control import LOCAL_PROVIDERS
except Exception: # noqa: BLE001 — pricing must never break a turn
return False
return bool(provider) and provider in LOCAL_PROVIDERS
async def _turn_cost_usd(
provider: str | None,
model: str | None,
tokens_in: int,
tokens_out: int,
tokens_cached: int,
) -> float:
"""USD cost of one completed brain turn; never raises."""
# On-device models are free and absent from every price list; pricing
# them warned on every turn and refreshed a remote catalogue for nothing.
if _is_local_provider(provider):
return 0.0
try:
from dodaios.brain import cost
# A model the static table has never heard of is priced
# from the provider feed — ONE refresh per model per
# process (capped at 3 s), so a new generation stops
# shipping as "$0.00" until someone edits the table.
if tokens_in > 0 or tokens_out > 0 or tokens_cached > 0:
await cost.ensure_pricing_for(model)
usd = cost.calculate_cost_usd(model, tokens_in, tokens_out, tokens_cached)
if usd == 0.0 and tokens_in > 0:
# An unknown model prices as $0.00 and every surface
# then renders the turn as free — that silence is how
# 1.87M deepseek tokens went unbilled for a month
# (2026-07-28 cost audit). Say it once per turn.
log.warning(
"No pricing for model %r (static table and "
"provider feed) — %d in / %d out tokens recorded "
"as $0.00; add it to dodaios/brain/cost.py "
"PRICING_USD_PER_MTOK",
model, tokens_in, tokens_out,
)
return usd
except Exception: # noqa: BLE001
log.warning(
"Cost calculation failed for model %r — recording $0.00",
model, exc_info=True,
)
return 0.0
class BrainManager:
"""Top-level orchestrator with intent router and smart fallback."""
def __init__(
self,
config: JarvisConfig,
bus: EventBus,
*,
core_memory: CoreMemory | None = None,
recall: RecallStore | None = None,
tools: dict[str, Tool] | None = None,
local_action_tools: dict[str, Tool] | None = None,
tool_executor: ToolExecutor | None = None,
system_prompt_extra: str = "",
user_profile: UserProfile | None = None,
soul: Soul | None = None,
people: PersonStore | None = None,
curator: Curator | None = None,
cost_meter: "CostMeterLike | None" = None, # noqa: UP037
wiki_injector: "WikiContextInjector | None" = None, # noqa: UP037
contacts: Any = None,
readback_composer: "ReadbackComposer | None" = None, # noqa: UP037
) -> None:
self._config = config
self._bus = bus
# User-facing reply-language pin. "auto" mirrors the user's input
# language (DE/EN/ES); a pinned code forces that language for every
# reply (desktop "Languages" view). Consumed by
# _reply_language_directive(); mutated live via set_reply_language().
self._reply_language: str = normalize_reply_language(
getattr(getattr(config, "brain", None), "reply_language", None)
)
self._core_memory = core_memory
self._recall = recall
# The message recorder the factory attached to the bus for this brain,
# detached again by aclose() (see own_message_recorder).
self._message_recorder: tuple[Any, Any] | None = None
self._tools = tools or {}
self._local_action_tools = dict(local_action_tools or {})
self._tool_executor = tool_executor
# Two-turn voice/chat confirmation (forensic 2026-06-18): an ask-tier tool
# on a conversational turn is deferred + spoken-confirmed instead of
# blocking on a UI approval no voice user can give. Enabled by config,
# opted into per-turn only by conversational callers (``allow_voice_confirm``).
self._voice_confirm_enabled: bool = bool(
getattr(getattr(config, "brain", None), "voice_confirm", True)
)
self._pending_voice_confirm: _PendingVoiceConfirm | None = None
# Ambiguous visual requests use a separate, read-only yes/no proposal.
# Keying by source keeps a web-chat answer from authorizing a voice
# capture (and vice versa); entries expire quickly and never persist.
self._pending_screen_confirms: dict[
tuple[str, str], _PendingScreenConfirm
] = {}
self._system_prompt_extra = system_prompt_extra
self._user_profile = user_profile
self._soul = soul
self._people = people
# Chunk B (contacts): optional ContactStore (Contract 1, owned by Chunk
# A). When set, _build_system_prompt() appends its compact name-index
# (names + relationship only; details on demand via contact-lookup).
# None until Chunk A is merged — the block is simply omitted (graceful).
self._contacts = contacts
# Context-aware spoken readbacks (maintainer mandate: no fixed stock
# phrases). When wired (router tier, via factory.build_readback_composer)
# the deterministic action-path readbacks — CU outcome/dispatch, budget,
# tool-failed — are phrased fresh for the situation by a bounded flash
# call, with the EXISTING canned line as the instant fallback. None on the
# bare/CLI managers and in tests => unchanged canned behavior (risk-free).
self._readback_composer = readback_composer
# Phase 5 / ADR-0006: optional budget hook. Fed with aggregated usage
# post-call; pre-call blocks when in cooldown or when the task/daily
# budget is exceeded. When None, the feature is completely inactive —
# no effect on the dispatch path.
self._cost_meter = cost_meter
self._curator = curator
self._vision_provider = None
# Drag-drop: ad-hoc images attached to ONE upcoming turn, keyed by that
# turn's trace_id (see dodaios/brain/drop_context.py). Popped + cleared in
# _collect_vision_images, bypassing the screen-vision gate so a dropped
# picture reaches the multimodal brain even with screen-vision off.
self._pending_turn_images: dict[UUID, tuple[ImageBlock, ...]] = {}
# Drag-drop SILENT context: pictures dropped onto the bar/mascot, parked
# for the NEXT real turn (a drop never triggers a turn). See
# add_dropped_context / generate. Dropped TEXT goes into _history.
self._pending_drop_images: tuple[ImageBlock, ...] = ()
# B5 Agent C: wiki context injector. None = no-op (Agent B not merged
# yet, or [wiki_context].enabled = false). Set by factory.py for the
# router tier only; sub-tiers never get wiki injection.
self._wiki_injector: WikiContextInjector | None = wiki_injector
# Per-turn wiki context suffix; set in generate() and consumed by
# _build_system_prompt(). Reset to "" after each turn.
self._wiki_context_suffix: str = ""
# Per-turn detected language (de/en/es/pt or "" when ambiguous/pinned),
# set at the top of generate(); consumed by _reply_language_directive()
# in auto mode to hard-pin the turn's language so a tool-synthesis turn
# cannot drift back to German (live bug 2026-06-14).
self._turn_detected_lang: str = ""
# Sticky conversation language (de/en/es/pt, "" until established). Updated
# only on a SUBSTANTIVE turn so a thin interjection ("Now", "Stop") never
# flips an established conversation; consumed by _update_turn_language and
# exposed to the speech pipeline / deterministic tool readbacks so the
# whole turn stays in one language (natural-flow forensic 2026-06-18).
self._conversation_language: str = ""
# AD-OE6 zero-silent-drop signal. True for exactly one turn after the
# whole provider fallback chain failed (no key / depleted credits /
# rate-limited everywhere). The voice pipeline reads this to decide
# whether to speak a spoken "all providers are down" fallback instead
# of returning silently to LISTENING. A legitimate empty turn
# (suppress_response fire-and-forget) leaves this False.
self._last_turn_all_failed: bool = False
# AD-OE6 companion signal. True for exactly one turn when the winning
# provider finished with ``suppress_response`` (a fire-and-forget
# ``spawn_worker`` background mission that reports back over the bus).
# The voice pipeline reads this to tell a LEGIT silent turn (spawn —
# stay silent) from a turn that produced no speech for any other reason
# (function_call/CU without speech, empty content). The latter must NOT
# drop the user into silence — it gets a spoken clarifying question
# (live "Jarvis antwortet nie" cause 2026-06-08: conversational turns
# returned a function_call and the turn ended mute).
self._last_turn_suppressed: bool = False
# AD-OE6 companion signal #2. True for exactly one turn when the winning
# provider executed a DESKTOP-ACTION tool (computer_use / open_app /
# click / type / …) but produced no narration text. A wordless desktop
# action is a SUCCESS the user must hear confirmed — NOT a clarifying
# question. Live bug 2026-06-09 (data/jarvis_desktop.log 16:27): the
# router brain called computer_use, the CU loop opened Chrome ([cu] step
# 1.1 open_app → step 2 done), Gemini emitted no text, and the pipeline
# spoke "Wie meinst du das genau?" — so a successful action looked like
# incomprehension. The pipeline reads this to speak a confirmation
# instead. Reset to False each turn; only the winning provider sets it.
self._last_turn_executed_action_tool: bool = False
# Rotation cursor for the localized "brain unreachable" spoken fallback
# (_provider_down_phrase). Advances once per total-failure turn so the
# phrase varies instead of repeating verbatim.
self._provider_down_idx: int = 0
self._registry = BrainProviderRegistry()
raw_primary = getattr(config.brain, "primary", None)
router_cfg = getattr(config.brain, "router", None)
coerced_primary = _coerce_main_brain_provider(
raw_primary,
getattr(router_cfg, "provider", None),
getattr(config.brain, "deep_brain", None),
)
if coerced_primary != (raw_primary or "").strip():
log.warning(
"Brain provider %r is subagent-only; using %r as main brain.",
raw_primary,
coerced_primary,
)
config.brain.primary = coerced_primary
self._active_name: str = coerced_primary
# The (provider, model) actually answering the CURRENT turn. Set per
# fallback-chain attempt in generate() right before the dispatcher is
# built, consumed by _build_system_prompt to inject the authoritative
# self-identity line (forensic 2026-06-20: the answering LLM never knew
# which provider it was, so a provider question got a guessed "Gemini").
# None outside a turn → no identity block on helper prompt builds.
self._active_turn_identity: tuple[str, str | None] | None = None
# Last persist-to-disk outcome of ``switch(..., persist=True)``.
# ``None`` = no persisting switch attempted yet. The provider route
# reads this to report the ACTUAL disk result instead of echoing the
# request flag (anti-silent-drop, AD-OE6).
self.last_persist_ok: bool | None = None
# Cache: (provider-name, model-name-or-None) → Brain-Instance
self._brain_cache: dict[tuple[str, str | None], Brain] = {}
# Latency sprint 2: provider caching is communicated to the brain plugins
# via environment variables (they are stateless API adapters, not DI).
# Always set rather than only-when-true so that a subsequent
# reconfiguration via hot-reload works in both directions (true→false
# disables it).
import os as _os
perf = getattr(config, "performance", None)
if perf is not None:
_os.environ["JARVIS_ANTHROPIC_PROMPT_CACHE"] = (
"1" if getattr(perf, "anthropic_prompt_cache", False) else "0"
)
_os.environ["JARVIS_GEMINI_CONTEXT_CACHE"] = (
"1" if getattr(perf, "gemini_context_cache", False) else "0"
)
self._history: list[BrainMessage] = []
self._lock = asyncio.Lock()
# Sticky override: "denk gründlich" sets _force_level="deep"
# until the user says "denk schnell".
self._force_level: str | None = None
# Circuit breaker for 429-limited providers (skip for 30s)
self._rate_tracker = RateLimitTracker(cooldown_s=30.0)
# Session dead-list: providers that definitely have no key/auth in
# THIS session. Filtered from the chain until session end or until the
# next provider switch (user sets a key in the UI → switch triggers
# reset). Prevents each voice turn from running through 8 sequential
# "no API key" failures.
self._dead_providers: set[str] = set()
# The provider a person switched to at runtime ("switch to openai").
# A deliberate pick keeps answering even on the realtime voice key.
self._switched_to: str | None = None
# Model-scoped twin of `_dead_providers`: a billing-style rejection
# (account_blocked, e.g. HTTP 402) on ONE model must not dead-list a
# provider that has other, untried models still in this turn's chain
# (e.g. a paid model capped out while a free model on the same
# provider is still funded). Populated/consulted only for
# account_blocked; missing_key/bad_key stay provider-wide since a
# dead credential blocks every model on that provider.
self._dead_provider_models: set[tuple[str, str | None]] = set()
# Populated by from_tier_config(). Tier fallbacks are runtime
# priorities, not just healthcheck metadata.
self._configured_fallbacks: list[tuple[str, str | None]] = []
# Persona mandate phase 3: deterministic force-spawn heuristic.
# Lazily compiled from self._config.brain.routing.
self._routing_patterns: tuple[
re.Pattern[str], re.Pattern[str], re.Pattern[str]
] | None = None
# Heavy-research force-spawn patterns (verb + heaviness-marker), lazily
# compiled from brain.routing.heavy_research_*. Live bug 2026-06-14.
self._heavy_research_patterns: tuple[
re.Pattern[str], re.Pattern[str]
] | None = None
# User-Mandate 2026-05-14: strict-mode trigger-phrase regex
# (compiled from `brain.routing.force_spawn_phrases`). Cached so
# the hot path stays cheap.
self._force_spawn_pattern: re.Pattern[str] | None = None
# AD-12 / AP-OC5 (wave-4 router): optional handlers for Jarvis-Agent
# mission status/cancel. Injected via ``set_mission_command_handlers``
# after bootstrap so the BrainManager constructor has no hard
# dependency on MissionManager.
self._jarvis_agent_status_fn: (
Callable[[str | None], Awaitable[str]] | None
) = None
self._jarvis_agent_cancel_fn: (
Callable[[str | None], Awaitable[str]] | None
) = None
# ------------------------------------------------------------------
# Tiered-Routing-Factory (Phase 5)
# ------------------------------------------------------------------
@classmethod
def from_tier_config(
cls,
tier: Literal["router"],
config: JarvisConfig,
bus: EventBus,
*,
provider_override: str | None = None,
tools: dict[str, Tool] | None = None,
local_action_tools: dict[str, Tool] | None = None,
tool_executor: ToolExecutor | None = None,
core_memory: CoreMemory | None = None,
recall: RecallStore | None = None,
user_profile: UserProfile | None = None,
soul: Soul | None = None,
people: PersonStore | None = None,
contacts: Any = None,
) -> BrainManager:
"""Builds a BrainManager from the tier-specific config.
Wave-4 migration: previously there were two tiers, ``router`` and
``sub_jarvis``. The Sub-Jarvis tier was replaced by the Jarvis-Agent
bridge (see docs/jarvis-agents-bridge.md §11); only ``router`` remains.
Reads `config.brain.router` and writes into a deep copy of JarvisConfig:
- `brain.primary = tier_cfg.provider` (or `provider_override`)
- `brain.deep_brain = tier_cfg.fallback_provider`, UNLESS a
`provider_override` collapses a non-split tier (fallback in
{None, provider}) — then deep_brain follows the override so a
user-chosen frontier provider leads deep/code too (see below).
The global `config` instance is left unchanged.
Args:
provider_override: When set, `tier_cfg.provider` is ignored and
the override is used. This is the hook for the live provider
switch: when the user says "wechsel auf gemini" via voice.
The associated `tier_cfg.model` is then NOT used (it was
intended for the original provider) — instead the default
from TIER_DEFAULTS_BY_PROVIDER applies for the new provider.
"""
tier_cfg = getattr(config.brain, tier, None)
if tier_cfg is None:
# A fresh install ships NO [brain.router] block: dodaios.toml.example
# has a [brain] table but no [brain.router] sub-table, and neither
# the wizard, the installer, nor onboarding ever writes one. Raising
# here left ``app.state.brain = None``, which bricked BOTH the
# voice/chat brain AND the provider-switch route — the latter then
# surfaced the misleading "headless mode" 503 on every "Set active"
# click. This only ever hit downloaders: the maintainer's own
# jarvis.toml HAS the block (textbook AP-23 "works on my machine").
# Instead of failing, synthesize the tier from the user's REAL
# selection. BrainTierConfig only requires ``provider``; the model is
# filled per-provider by ``_resolve_tier_model``. Provider-agnostic —
# it honours whatever main provider the fresh user configured, and an
# explicit [brain.router] block still overrides this untouched.
default_provider = (
(config.brain.primary or "").strip()
or (config.brain.routing_provider or "").strip()
or "claude-api"
)
log.info(
"No [brain.%s] block in config — synthesizing a default tier from "
"brain.primary=%r so a fresh install boots a working brain.",
tier,
default_provider,
)
tier_cfg = BrainTierConfig(provider=default_provider)
local_config = config.model_copy(deep=True)
requested_provider = provider_override or tier_cfg.provider
effective_provider = _coerce_main_brain_provider(
requested_provider,
tier_cfg.provider,
tier_cfg.fallback_provider,
getattr(config.brain, "deep_brain", None),
)
if effective_provider != (requested_provider or "").strip():
log.warning(
"Brain provider %r is subagent-only; using %r as router brain.",
requested_provider,
effective_provider,
)
local_config.brain.primary = effective_provider
# deep_brain normally mirrors the tier's fallback provider. But when an
# explicit override redirected the active provider away from the tier
# default AND there is no deliberate cross-provider deep split
# (fallback_provider == provider), the deep brain must FOLLOW the override
# — otherwise a user-chosen frontier provider (grok/codex) still delegates
# every deep/code turn to the orphaned tier default. Forensic 2026-06-20:
# primary=grok left deep_brain=gemini, so reasoning turns ran on Gemini
# despite the user picking Grok ("Grok for everything" mandate). An
# explicit split (fallback_provider != provider) is preserved.
deep_provider = tier_cfg.fallback_provider
if (
provider_override
and effective_provider != tier_cfg.provider
and (
# No fallback configured at all (None/"") is even less of a
# deliberate split than a symmetric one — follow the override
# rather than strand deep_brain at None for the whole session.
not tier_cfg.fallback_provider
or tier_cfg.fallback_provider == tier_cfg.provider
)
):
deep_provider = effective_provider
local_config.brain.deep_brain = deep_provider
# Tier model resolver:
# - If a live override is active: ignore tier_cfg.model (it belonged to
# the ORIGINAL tier provider, e.g. [brain.router].model="gemini-3.5-flash").
# BUT the override provider's OWN picked model
# ([brain.providers.<override>].model) IS the user's selection and MUST
# win over the hardcoded TIER default. Without this, an OpenRouter user
# who picked a free model silently ran — and was billed for — the
# hardcoded paid anthropic/claude default (router=haiku-4.5, deep=opus-4.8)
# on EVERY boot, because this very assignment clobbered the picked model
# in the in-memory config before _fast_model/_deep_model could read it
# (live forensic 2026-06-29: ~5€ OpenRouter key drained on Opus + Haiku).
# AP-21/AP-22, open-source single-key §3.
# - If no override: respect tier_cfg.model, then the provider pick, then
# fall back to the default. Fresh installs have no [brain.router]
# block, so ignoring providers.<name>.model here would overwrite the
# model selected in the UI on every boot.
if provider_override:
override_pc = (local_config.brain.providers or {}).get(effective_provider)
explicit_model = getattr(override_pc, "model", None) or None
else:
provider_pc = (local_config.brain.providers or {}).get(effective_provider)
explicit_model = (
tier_cfg.model
or getattr(provider_pc, "model", None)
or None
)
resolved_model = _resolve_tier_model(tier, effective_provider, explicit_model)
if resolved_model and effective_provider in (local_config.brain.providers or {}):
local_config.brain.providers[effective_provider].model = resolved_model
# BUG-LATENCY (2026-05-24): the router is a pure dispatcher — it must not
# burn seconds on "extended thinking". Cap the thinking budget on the
# router provider config. ``local_config`` is a deep copy, so this affects
# ONLY the router brain — workers/critic (separate config load) keep full
# frontier reasoning (user mandate). Gemini honours thinking_budget=0 as
# "no thinking"; providers without the field ignore it harmlessly.
router_prov_cfg = local_config.brain.providers.get(effective_provider)
if router_prov_cfg is not None:
try:
router_prov_cfg.thinking_budget = 0
except (AttributeError, TypeError):
pass
configured_fallbacks: list[tuple[str, str | None]] = []
if tier_cfg.fallback_provider:
resolved_fallback = _resolve_tier_model(
tier, tier_cfg.fallback_provider, tier_cfg.fallback_model
)
configured_fallbacks.append((tier_cfg.fallback_provider, resolved_fallback))
# BUG-LATENCY (2026-05-24): only mutate the fallback provider's `model`
# when it is a DIFFERENT provider than the primary. When primary ==
# fallback (e.g. [brain.router] provider="gemini" + fallback_provider=
# "gemini"), both share the same providers["gemini"] entry, so this
# write used to clobber the primary's fast model (flash) with the deep
# fallback model (pro) — the router then ran every turn on the slow
# reasoning model (~9 s thinking). The same-provider fallback model is
# still carried in `configured_fallbacks` for the chain below.
if (
tier_cfg.fallback_provider
and tier_cfg.fallback_provider != effective_provider
and tier_cfg.fallback_provider in (local_config.brain.providers or {})
):
resolved_fallback = _resolve_tier_model(
tier, tier_cfg.fallback_provider, tier_cfg.fallback_model
)
if resolved_fallback:
local_config.brain.providers[tier_cfg.fallback_provider].model = resolved_fallback
if tier_cfg.fallback_provider_2:
resolved_fallback_2 = _resolve_tier_model(
tier, tier_cfg.fallback_provider_2, tier_cfg.fallback_model_2
)
configured_fallbacks.append((tier_cfg.fallback_provider_2, resolved_fallback_2))
if (
resolved_fallback_2
and tier_cfg.fallback_provider_2 != effective_provider
and tier_cfg.fallback_provider_2 in (local_config.brain.providers or {})
):
local_config.brain.providers[tier_cfg.fallback_provider_2].model = (
resolved_fallback_2
)
manager = cls(
config=local_config,
bus=bus,
core_memory=core_memory,
recall=recall,
tools=tools,
local_action_tools=local_action_tools,
tool_executor=tool_executor,
user_profile=user_profile,
soul=soul,
people=people,
contacts=contacts,
)
manager._configured_fallbacks = configured_fallbacks
# Bug E fix (2026-04-29) — pre-boot key check.
# Push providers without an API key directly into _dead_providers,
# otherwise they produce BrainTurnStarted hallucination tags in the DB
# before _ensure_client() crashes. Example: user only has Anthropic +
# Gemini + xAI keys → openai/openrouter are not tried at all.
from dodaios.core import config as _cfg_mod
from dodaios.core.config import PROVIDER_SECRET_CANDIDATES
provider_to_slots: dict[str, list[str]] = {}
for secret_key, provider_name in _SECRET_KEY_TO_BRAIN.items():
provider_to_slots.setdefault(provider_name, []).append(secret_key)
for provider_name, secret_specs in PROVIDER_SECRET_CANDIDATES.items():
try:
key_value = _cfg_mod.get_secret_any(secret_specs)
except Exception: # noqa: BLE001
key_value = None
if not key_value:
# A keyless-but-credentialed provider — an OAuth login on disk
# (codex via ChatGPT) or a Google Cloud project signing with
# Application Default Credentials (vertex) — is NOT dead-listed
# (open-source AP-22).
if _keyless_provider_is_rescued_by_oauth(provider_name):
log.info(
"Pre-boot key check: '%s' has no API key but a login / "
"Cloud project credential -> kept active.",
provider_name,
)
continue
manager._dead_providers.add(provider_name)
log.info(
"Pre-boot key check: no key in %s -> provider '%s' disabled.",
provider_to_slots.get(provider_name, [provider_name]),
provider_name,
)
return manager
# ------------------------------------------------------------------
# Provider instance cache
# ------------------------------------------------------------------
def available_providers(self) -> list[str]:
return self._registry.available()
def failed_providers(self) -> dict[str, str]:
return self._registry.failed()
def _provider_cfg(self, name: str):
return self._config.brain.providers.get(name)
def _fast_model(self, name: str) -> str | None:
cfg = self._provider_cfg(name)
if cfg is None:
return get_tier_default_model("router", name)
return cfg.model or get_tier_default_model("router", name)
def _deep_model(self, name: str) -> str | None:
cfg = self._provider_cfg(name)
if cfg is None:
return get_tier_default_model("deep", name)
# Precedence: explicit deep_model → the user's CHOSEN model → hardcoded
# tier default. The chosen model MUST outrank the hardcoded default:
# otherwise a provider with a `model` set but no `deep_model` (e.g.
# openrouter = "nvidia/nemotron-...:free") silently runs the deep slot on
# a foreign-family default (anthropic/claude-opus-4.8). Live forensic
# 2026-06-29: that default is a PAID model 403-blocked by the user's
# OpenRouter key spend-limit, while the chosen FREE model answered fine —
# so the turn bricked despite a healthy, user-selected brain. Respect the
# selected model; never hijack a turn onto the most expensive Anthropic
# model the user never picked (AP-21/AP-22, open-source single-key §3).
return (
getattr(cfg, "deep_model", None)
or getattr(cfg, "model", None)
or get_tier_default_model("deep", name)
)
def _cu_model(self, name: str) -> str | None:
"""Resolve the Tool Model for ``name``, including the legacy CU key."""
return self._tool_model_model(name)
def _tool_model_model(
self, name: str, fallback: str | None = None
) -> str | None:
"""Resolve an explicit Tool Model pin before a caller's model choice."""
from dodaios.core.model_selection import operation_model, worker_selection
selection = operation_model.get() or worker_selection(self._config)
if selection is not None and selection.provider == name:
return selection.model or fallback or get_tier_default_model("worker", name)
cfg = self._provider_cfg(name)
if cfg is None:
return fallback or get_tier_default_model("router", name)
return (
getattr(cfg, "tool_model", None)
or getattr(cfg, "cu_model", None)
or fallback
or getattr(cfg, "model", None)
or get_tier_default_model("router", name)
)
def _tool_model_provider(self) -> str:
"""Return the canonical Tool Model provider or its legacy fallback."""
from dodaios.core.model_selection import operation_model, worker_selection
selection = operation_model.get() or worker_selection(self._config)
if selection is not None:
return selection.provider
try:
brain_cfg = self._config.brain
canonical = getattr(brain_cfg, "tool_model", None)
provider = (getattr(canonical, "provider", None) or "").strip()
if provider:
return provider
legacy = getattr(brain_cfg, "computer_use", None)
return (getattr(legacy, "provider", None) or "").strip()
except Exception: # noqa: BLE001 -- config failure must not block dispatch
return ""
def _tool_model_source(self) -> str:
"""Identify whether the selection came from canonical or legacy config."""
try:
fields_set = getattr(self._config.brain, "model_fields_set", set())
if "tool_model" in fields_set:
return "tool_model"
if "computer_use" in fields_set:
return "computer_use"
except Exception: # noqa: BLE001, S110 -- status must never raise
pass
return "auto" if self._tool_model_provider() in ("", "auto") else "tool_model"
@staticmethod
def _tool_model_family(provider: str) -> str:
"""Credential/quota family used to avoid same-family fallback bricks."""
return {
"codex": "openai",
"openai-api": "openai",
"antigravity": "gemini",
}.get(provider, provider)
def _tool_model_credential_ready(self, provider: str) -> bool:
"""Whether ``provider`` has a portable usable credential."""
try:
from dodaios.brain.app_control import get_spec, is_credential_present
spec = get_spec(provider)
if spec is not None:
return bool(is_credential_present(spec))
from dodaios.core import config as cfg_mod
return bool(cfg_mod.get_provider_secret(provider))
except Exception: # noqa: BLE001 -- a failed probe is not readiness
return False
def tool_model_candidate_status(
self, provider: str, model: str | None = None
) -> dict[str, Any]:
"""Return a secret-free runtime capability verdict for one candidate."""
provider = (provider or "").strip()
model = model or self._cu_model(provider)
result: dict[str, Any] = {
"provider": provider,
"model": model,
"ready": False,
"reason": "unknown",
"tools": None,
"vision": None,
}
if not provider or provider == "auto":
result["reason"] = "automatic_selection"
return result
if provider not in set(self._registry.available()):
result["reason"] = "provider_unavailable"
return result
if provider in self._dead_providers:
result["reason"] = "provider_dead"
return result
if (provider, model) in self._dead_provider_models:
result["reason"] = "model_dead"
return result
if not self._rate_tracker.is_available(provider, model):
result["reason"] = "rate_limited"
return result
if not self._tool_model_credential_ready(provider):
result["reason"] = "missing_credential"
return result
try:
brain = self._get_brain(provider, model)
except Exception: # noqa: BLE001 -- status must remain secret-free
result["reason"] = "provider_initialization_failed"
return result
result["vision"] = getattr(brain, "supports_vision", None)
try:
can_call = getattr(brain, "can_call_tools", None)
tools = (
bool(can_call())
if callable(can_call)
else bool(getattr(brain, "supports_tools", True))
)
except Exception: # noqa: BLE001 -- fail closed for action routing
result["reason"] = "capability_probe_failed"
return result
result["tools"] = tools
if not tools:
result["reason"] = "tools_unsupported"
return result
result["ready"] = True
result["reason"] = "ready"
return result
def _tool_model_base_chain(self) -> list[tuple[str, str | None]]:
"""Build the stable cross-provider chain used by automatic selection."""
brain_cfg = self._config.brain
names = [
getattr(brain_cfg, "primary", None),
getattr(brain_cfg, "deep_brain", None),
getattr(getattr(brain_cfg, "router", None), "provider", None),
"gemini",
"claude-api",
"openai",
"openrouter",
"grok",
"nvidia",
*self._registry.available(),
]
seen: set[str] = set()
chain: list[tuple[str, str | None]] = []
for name in names:
if not name or name in seen:
continue
seen.add(name)
chain.append((name, self._cu_model(name)))
return chain
def resolve_tool_model(
self, chain: list[tuple[str, str | None]] | None = None
) -> dict[str, Any]:
"""Resolve a key-ready, tool-capable provider across quota families."""
configured = self._tool_model_provider()
configured_model = (
self._cu_model(configured)
if configured and configured != "auto"
else None
)
candidates = list(chain) if chain is not None else self._tool_model_base_chain()
if configured and configured != "auto":
candidates.insert(0, (configured, configured_model))
seen_families: set[str] = set()
first_failure = "no_tool_capable_provider"
configured_failure: str | None = None
for index, (provider, model) in enumerate(candidates):
family = self._tool_model_family(provider)
if family in seen_families:
continue
seen_families.add(family)
verdict = self.tool_model_candidate_status(
provider, self._tool_model_model(provider, model)
)
if verdict["ready"]:
selected_configured = (
configured not in ("", "auto") and provider == configured
)
return {
"configured_provider": configured or "auto",
"configured_model": configured_model,
"effective_provider": provider,
"effective_model": verdict["model"],
"state": (
"ready"
if selected_configured or configured in ("", "auto")
else "fallback"
),
"reason": (
"configured_selection"
if selected_configured
else (
f"configured_{configured_failure}"
if configured_failure is not None
else "automatic_selection"
)
),
"source": self._tool_model_source(),
"tools": verdict["tools"],
"vision": verdict["vision"],
}
if index == 0:
first_failure = str(verdict["reason"])
if configured not in ("", "auto") and provider == configured:
configured_failure = str(verdict["reason"])
return {
"configured_provider": configured or "auto",
"configured_model": configured_model,
"effective_provider": None,
"effective_model": None,
"state": "blocked",
"reason": first_failure,
"source": self._tool_model_source(),
"tools": False,
"vision": None,
}
def _cu_provider(self) -> str:
"""Compatibility accessor for the canonical global Tool Model provider."""
provider = self._tool_model_provider()
return "" if provider == "auto" else provider
def _hoist_tool_model(
self, chain: list[tuple[str, str | None]]
) -> list[tuple[str, str | None]]:
"""Filter a delegated turn to tool-capable cross-family candidates."""
from dodaios.core.model_selection import operation_model, worker_selection
selection = operation_model.get() or worker_selection(self._config)
if selection is not None:
# A selected subscription must not silently turn into metered API usage.
return [(selection.provider, selection.model)]
configured = self._tool_model_provider()
candidates = list(chain)
if configured and configured != "auto":
candidates.insert(0, (configured, self._cu_model(configured)))
ready: list[tuple[str, str | None]] = []
seen_families: set[str] = set()
for provider, model in candidates:
family = self._tool_model_family(provider)
if family in seen_families:
continue
seen_families.add(family)
verdict = self.tool_model_candidate_status(
provider, self._tool_model_model(provider, model)
)
if verdict["ready"]:
ready.append((provider, verdict["model"]))
if not ready:
log.warning("No credential-ready, tool-capable Tool Model is available.")
return ready
def _lead_vision_chain(
self, chain: list[tuple[str, str | None]]
) -> list[tuple[str, str | None]]:
"""On an image turn, put the router vision FAST model first.
Live 2026-08-31 17:06: a realtime screenshot delegated through
``prefer_tool_model`` led with Vertex ``gemini-3.7-flash`` (the Tool
Model). Five providers then failed and grok-4.6 answered after 20 s.
Live 2026-08-31 19:38: the first cut ranked by ``_active_name``
(chat primary ``openrouter``). OpenRouter 402'd in 0.3 s, then
Vertex ``gemini-3-flash-preview`` sat 20.5 s. Grok never ran. The
router already names the look model (``[brain.router]``). Rank by
that config, not the chat primary — AP-21: never hardcode a
provider name, never treat a broke primary as a vision ranking
signal.
"""
if not chain:
return chain
router = getattr(getattr(self._config, "brain", None), "router", None)
router_provider = (
getattr(router, "provider", None) if router is not None else None
)
vision: list[tuple[str, str | None]] = []
rest: list[tuple[str, str | None]] = []
seen: set[str] = set()
def _consider(provider: str, model: str | None) -> None:
if provider in seen or provider in self._dead_providers:
return
seen.add(provider)
pick_model = self._vision_look_model(provider) or model
if self._provider_advertises_vision(provider, pick_model):
vision.append((provider, pick_model))
else:
rest.append((provider, model))
# Router first (from config), then the rest of the chain. The chat
# primary is not a ranking signal — it may be a billed-out slot.
if isinstance(router_provider, str) and router_provider:
_consider(router_provider, None)
for provider, model in chain:
_consider(provider, model)
if not vision:
return chain
led = vision + rest
log.info(
"screen-turn vision lead: %s(%s) — %d vision-capable, %d others",
led[0][0],
led[0][1],
len(vision),
len(rest),
)
return led
def _vision_look_model(self, provider: str) -> str | None:
"""The fast look-at-screen model for ``provider``, never the CU/tool slot.
Computer-Use and the Tool Model pick heavy siblings (grok-4.6). A
screenshot narration wants the router-tier fast id when this is the
routing provider.
"""
router = getattr(getattr(self._config, "brain", None), "router", None)
if (
router is not None
and getattr(router, "provider", None) == provider
and getattr(router, "model", None)
):
return str(router.model)
return self._fast_model(provider)
def _provider_advertises_vision(
self, provider: str, model: str | None
) -> bool:
try:
brain = self._get_brain(provider, model)
except Exception: # noqa: BLE001 — unready provider stays in the tail
return False
return getattr(brain, "supports_vision", False) is True
def _get_brain(
self, name: str, model: str | None = None, *, scope: str | None = None
) -> Brain:
"""Retrieves a Brain instance from the cache, or builds a new one.
``scope`` namespaces the cache entry (``"<name>@<scope>"``): a turn
under a ``TurnOverride`` gets its own instance, so its client — and
the credential that client resolved — is never the voice brain's.
"""
from dodaios.core.model_selection import operation_model
selected = operation_model.get()
if selected is not None and selected.brain_override is not None:
if name != selected.provider or (model and model != selected.model):
raise RuntimeError(
"This operation cannot switch its selected model or billing account."
)
return selected.brain_override
key = (name if scope is None else f"{name}@{scope}", model)
if key in self._brain_cache:
return self._brain_cache[key]
kwargs: dict[str, Any] = {}
if model:
kwargs["model"] = model
cfg = self._provider_cfg(name)
if cfg is not None and cfg.base_url:
kwargs["base_url"] = cfg.base_url
# Latency sprint 1: pass through thinking budget — currently only Gemini
# accepts this parameter. Other providers raise TypeError, then the
# second attempt below retries without kwargs.
if (
name == "gemini"
and cfg is not None
and getattr(cfg, "thinking_budget", None) is not None
):
tb = cfg.thinking_budget
# Gemini Pro models REQUIRE thinking mode and reject budget=0 with
# 400 "Budget 0 is invalid. This model only works in thinking mode."
# The router caps budget to 0 for its fast (flash) model, but the
# SAME gemini provider config is reused for the deep/pro fallback —
# forwarding 0 there 400s the call and silently drops the turn.
# Only forward budget=0 to non-pro models; let pro fall back to the
# SDK default (auto thinking).
eff_model = (model or getattr(cfg, "model", "") or "")
if not (tb == 0 and "pro" in eff_model.lower()):
kwargs["thinking_budget"] = tb
try:
inst = self._registry.instantiate(name, **kwargs)
except TypeError:
# A plugin __init__ rejected an OPTIONAL kwarg (base_url /
# thinking_budget — not every brain accepts them). Retry, but NEVER
# drop ``model``: the old fallback re-instantiated with NO kwargs at
# all, so the brain fell back to its hardcoded DEFAULT_MODEL. For the
# OpenRouter gateway that default is anthropic/claude-opus-4.8 — the
# exact PAID model a spend-limited key 403s on, while the user's
# chosen FREE model would have answered (live forensic 2026-06-29:
# the wire carried opus though the chain logged nemotron:free). The
# endpoint/budget are re-resolved from config inside the plugin's
# _ensure_client, so dropping them here is safe; the model is
# essential and must survive (AP-21/AP-22, open-source single-key §3).
retry_kwargs: dict[str, Any] = {"model": model} if model else {}
try:
inst = self._registry.instantiate(name, **retry_kwargs)
except TypeError:
inst = self._registry.instantiate(name)
# Anti-drift guarantee (user mandate 2026-06-29): the model on the wire
# MUST be the SELECTED model. A brain silently running its hardcoded
# DEFAULT_MODEL — user picks GPT-5.5 but Opus runs, while the UI still
# shows GPT-5.5 — is the exact "wrong model used, shown right" defect.
# Every brain plugin stores its resolved model as ``self._model``; if a
# requested model did NOT survive construction, log it LOUDLY so the drift
# is visible instead of silent. Provider-agnostic (no provider/model
# special-case); the chosen-model contract tests lock this in.
if model:
actual = getattr(inst, "_model", None)
if actual is not None and actual != model:
log.error(
"MODEL DRIFT %s: requested model %r but the constructed brain "
"runs %r — the SELECTED model is not the one being used. This "
"is a bug (a silent DEFAULT_MODEL fallback), not expected.",
name, model, actual,
)
self._brain_cache[key] = inst
return inst
@property
def active_provider(self) -> str:
return self._active_name
# ------------------------------------------------------------------
# Dispatcher builder
# ------------------------------------------------------------------
def _build_dispatcher(
self,
brain: Brain,
*,
tools_override: dict[str, Tool] | None = None,
max_turns: int | None = None,
deadline_s: float | None = None,
reasoning_effort: ReasoningEffort | None = None,
delegated_voice: bool = False,
tool_context: dict[str, Any] | None = None,
loop_control: Any = None,
own_tools: Iterable[str] = (),
direct_tools: frozenset[str] | None = None,
) -> BrainDispatcher:
"""Builds the dispatcher with an optional tool override.
Bug fix 2026-05-01 (voice session 2026-04-30 22:38): when smalltalk is
clearly identified, ``tools_override={}`` is set — the LLM then has no
tools in its toolbox and cannot be tempted to hallucinate
``spawn_worker``. ``None`` (default) = full tool visibility.
``max_turns`` / ``deadline_s`` (2026-07-14): per-turn loop bounds for
delegated realtime voice turns — see ``_DELEGATE_MAX_TURNS`` /
``_DELEGATE_DEADLINE_S``. ``None`` keeps the dispatcher defaults.
``reasoning_effort`` (2026-07-17): forwarded onto every BrainRequest
of the turn. Delegated realtime voice turns pass ``"none"`` so a
thinking-by-default model never burns seconds of internal reasoning
per tool-loop round — see ``_DELEGATE_REASONING_EFFORT``.
``tool_context`` (2026-08-24): extra keys merged into every tool's
``ExecutionContext.config`` for this dispatcher's turns — scheduled
task turns pass ``{"delivery": "written"}`` so search results stop
asking for a spoken two-liner. ``None`` = no extra keys.
``delegated_voice`` (2026-07-17): appends the static speed contract
(``_DELEGATE_VOICE_DIRECTIVE``) — batch lookups, no repeats, answer
as soon as evidence suffices — to the system prompt of delegated
voice turns only, so classic chat prompts stay byte-identical.
The tool surface is then split into what the model is shown and
what stays callable behind ``find_tools`` (``_shortlist_tools``);
the turn's message log counts toward the budget — a delegated turn's
from ``_TURN_HISTORY_OVERRIDE``, a classic turn's from the live
``self._history`` (the same two sources ``_cu_context_lines`` reads).
``own_tools`` / ``direct_tools``: the caller's own hands, always
shown, and — for a caller whose role names the tools it works with —
the only others that are (``TurnOverride.tools_direct``).
"""
tools = tools_override if tools_override is not None else self._tools
system_prompt = self._build_system_prompt()
history = _TURN_HISTORY_OVERRIDE.get()
if history is None:
history = tuple(getattr(self, "_history", None) or ())
tools, deferred = self._shortlist_tools(
tools,
brain,
system_prompt=system_prompt,
history=history,
own_tools=own_tools,
direct_tools=direct_tools,
)
# Per-plugin usage guidance for whichever plugins are active this turn
# (the "MCP + thin skill" reliability layer). Appended last so it sits
# closest to the turn; only present when a plugin tool is in scope.
# Cards only for the tools the model is shown: guidance for a tool it
# cannot see spends the window on nothing.
cards = self._plugin_usage_cards_block(
{name: tool for name, tool in tools.items() if name not in deferred}
if deferred
else tools
)
if cards:
system_prompt = f"{system_prompt}\n\n{cards}"
if delegated_voice:
system_prompt = f"{system_prompt}\n\n{_DELEGATE_VOICE_DIRECTIVE}"
kwargs: dict[str, Any] = {}
if max_turns is not None:
kwargs["max_turns"] = max_turns
return BrainDispatcher(
brain,
tools=tools,
executor=self._tool_executor,
system_prompt=system_prompt,
max_tokens=self._config.brain.max_tokens,
deadline_s=deadline_s,
reasoning_effort=reasoning_effort,
tool_context=tool_context,
loop_control=loop_control,
deferred_tools=deferred,
**kwargs,
)
def _apply_turn_override_tools(
self, tools: dict[str, Tool] | None, override: TurnOverride
) -> dict[str, Tool]:
"""The turn's tool surface plus the override's extra hands, then its filter."""
base: dict[str, Tool] = dict(tools) if tools is not None else dict(self._tools)
base.update(override.tools_extra)
if override.tool_filter is not None:
base = override.tool_filter(base)
return base
@staticmethod
def _override_dispatch_kwargs(override: TurnOverride | None) -> dict[str, Any]:
"""Dispatcher kwargs for a caller-picked turn; ``{}`` for a classic one."""
if override is None:
return {}
kwargs: dict[str, Any] = {}
if override.reasoning_effort is not None:
kwargs["reasoning_effort"] = override.reasoning_effort
if override.tool_context:
kwargs["tool_context"] = dict(override.tool_context)
if override.max_turns is not None:
kwargs["max_turns"] = override.max_turns
if override.loop_control is not None:
kwargs["loop_control"] = override.loop_control
if override.tools_extra:
kwargs["own_tools"] = tuple(override.tools_extra)
if override.tools_direct is not None:
kwargs["direct_tools"] = override.tools_direct
return kwargs
async def render_surface_prompt(self, *, user_text: str) -> tuple[str, str]:
"""(system prompt, turn context) for an external agent that should BE Jarvis.
A subscription CLI seat on the typed chat runs its own loop, but the
head it runs with is this one: the same layers ``_build_system_prompt``
stacks for a voice turn (name, soul, persona, the assistant file, the
user's profile, people, contacts, the identity card, core memory, the
skills section, the tool-routing rules), the wiki context this turn's
text pulls in, and the per-turn context (date). Read-only:
nothing is stored on the manager, so a voice turn running alongside
sees no trace of it.
"""
base = self._build_system_prompt()
prompt = base
if self._wiki_injector is not None:
try:
prompt = await self._wiki_injector.maybe_inject(
user_text=user_text, system_prompt=base
)
except Exception: # noqa: BLE001 — the layers without the wiki are still Jarvis
log.debug("render_surface_prompt: wiki context skipped", exc_info=True)
try:
turn_context = self._build_turn_context()
except Exception: # noqa: BLE001 — the context block is a nicety
log.debug("render_surface_prompt: turn context skipped", exc_info=True)
turn_context = ""
return prompt, turn_context
def _build_tool_ack_emitter(
self, user_text: str
) -> Callable[[str, dict[str, Any]], Awaitable[None]] | None:
"""Grounded per-tool ack emitter for the voice turn (perceived latency).
Returns an async callback the tool-use loop awaits ONCE, the moment the
router brain has actually SELECTED a tool call — so the otherwise-silent
tool-execution + readback window speaks a short interim line. This
bridges the wait on slow turns (e.g. a cold email/calendar fetch, a
multi-tool research) where the persona forbids any spoken preamble
before the tool and round-2 has not started yet.
Contextual Interim Voice (2026-07-06 v2 spec): when the manager's
``ReadbackComposer`` has a live flash provider, the spoken text is
COMPOSED for this exact turn (user request + concrete action) instead
of drawn from a phrase pool — the pool line remains only as the
instant deterministic fallback (keyless install, breaker open,
timeout, rejected output). Composition + publish run fire-and-forget
so the tool-use loop is never delayed; ``[ack_brain].contextual_interim
= false`` is the kill switch back to pools-only.
Returns ``None`` when there is no bus, the feature is off
(``[ack_brain].grounded_tool_ack = false``), or the utterance is a
Voice-Control command (the action itself is the confirmation).
GROUNDED, not speculative: unlike the retired Flash-Brain preamble it
fires only after a real tool decision, never on suspicion. The fallback
words are rendered by ``generate_ack`` (skip-list-aware, so passive
reads / low-latency UI events stay silent) and the language is
re-resolved and re-scrubbed authoritatively at the speech layer, so the
reply-language pin and conversation stickiness still win there.
Publishing with ``source_layer="brain.router.ack"`` keeps every
pipeline gate on this source: the necessity commit-grace (speak only if
the brain is STILL busy), duplicate-wording dedup, the rate-limit
backstop, and the legacy one-ack-per-turn drop while the Flash-Brain
preamble is active.
"""
if self._bus is None:
return None
ack_cfg = getattr(self._config, "ack_brain", None) if self._config else None
if not getattr(ack_cfg, "grounded_tool_ack", True):
return None
from .ack_generator import (
describe_tool_action,
generate_ack,
is_voice_control_utterance,
)
if is_voice_control_utterance(user_text):
return None
bus = self._bus
language = _turn_phrase_language(self, user_text)
# Fire at most once per turn even if the provider chain retries the
# tool-use loop (a provider that emits tool_calls then errors would
# otherwise re-announce on the fallback provider's re-run).
fired = False
# Cross-utterance cooldown (2026-07-06 interim-ack redesign): the
# per-turn guard above cannot stop the NEXT utterance from acking
# again seconds later — forensically that produced the same spoken
# ack three times in one session. Checked at emit time (tool
# selection can lag turn start by seconds) against the manager-wide
# timestamp of the last PUBLISHED grounded ack.
min_gap_s = float(getattr(ack_cfg, "grounded_ack_min_gap_s", 20) or 0)
async def emit(tool_name: str, tool_args: dict[str, Any]) -> None:
nonlocal fired
if fired:
return
if min_gap_s > 0:
last = getattr(self, "_last_grounded_ack_monotonic", None)
if last is not None and (time.monotonic() - last) < min_gap_s:
log.debug(
"Grounded tool-ack suppressed — last ack %.1fs ago "
"(min gap %.0fs)", time.monotonic() - last, min_gap_s,
)
return
canned_text = generate_ack(tool_name, tool_args, language=language)
if canned_text is None: # skip-list tool (passive read / UI micro-event)
return
fired = True
self._last_grounded_ack_monotonic = time.monotonic()
async def _publish(text: str) -> None:
await bus.publish(
AnnouncementRequested(
text=text,
priority="normal",
language=language,
kind="preamble",
source_layer="brain.router.ack",
)
)
composer = getattr(self, "_readback_composer", None)
contextual = bool(getattr(ack_cfg, "contextual_interim", True))
if not (contextual and bool(getattr(composer, "has_llm", False))):
# Deterministic path (keyless install / kill switch): publish
# inline — sub-millisecond, the historical contract.
await _publish(canned_text)
return
action = describe_tool_action(tool_name, tool_args)
async def _compose_and_publish() -> None:
# Runs detached: composition must never delay tool execution
# (the loop already moved on) and must never raise. The
# pipeline's commit-grace re-checks necessity AFTER this
# composition lands, so the flash latency costs nothing.
text = canned_text
try:
from dodaios.voice.contextual_readback import ( # noqa: PLC0415
render_readback,
)
text = await render_readback(
composer,
instruction=(
f"You have JUST started {action} to answer the "
"user's request and it is taking a moment. In one "
"short sentence, tell the user what you are doing "
"RIGHT NOW, tied to their actual topic — an "
"in-progress bridge line, never a result."
),
language=language,
canned=lambda: canned_text,
facts={
"user_request": user_text[:200],
"current_action": action,
},
in_progress=True,
latency_budget_ms=1200,
)
except Exception as exc: # noqa: BLE001 — fall back to the pool line
log.debug("Contextual interim compose failed: %s", exc)
try:
await _publish(text)
except Exception as exc: # noqa: BLE001 — a publish fault must die here
log.warning("Interim ack publish failed: %s", exc)
tasks = getattr(self, "_interim_ack_tasks", None)
if tasks is None:
tasks = set()
self._interim_ack_tasks = tasks
task = asyncio.create_task(_compose_and_publish())
tasks.add(task)
task.add_done_callback(tasks.discard)
return emit
@property
def reply_language(self) -> str:
"""The active reply-language pin: ``auto`` | ``de`` | ``en`` | ``es``."""
return self._reply_language
@property
def force_spawn_mode(self) -> str:
"""The live ``brain.routing.force_spawn_mode``: strict/balanced/permissive.
The ONE live accessor for the setting. ``_should_force_spawn`` reads it
here, and ``dodaios.brain.spawn_gate.active_force_spawn_mode`` reads it
through the runtime reference to this manager — so the deterministic
path and the LLM gate can never end up in different modes on the same
turn. Unknown values normalise to the shipped default, never to a mode
the user did not ask for.
"""
return normalize_force_spawn_mode(
getattr(self._config.brain.routing, "force_spawn_mode", "")
)
@property
def conversation_language(self) -> str:
"""The sticky language of the conversation so far (any code, or "").
de/en/es/pt or a language without translated phrases ("tr", "fr", ...);
consumers narrow it with ``resolve_output_language``/``phrase_locale``.
Read by the speech pipeline and threaded into deterministic tool
readbacks so a thin interjection ("Now") stays in the running
conversation's language instead of flipping the whole turn (forensic
2026-06-18). Empty until a substantive turn establishes it; an explicit
``reply_language`` pin overrides it everywhere anyway.
"""
return self._conversation_language
def _update_turn_language(self, user_text: str) -> None:
"""Resolve this turn's language and maintain the sticky conversation
language, applied at the top of ``generate()``.
Stickiness and explicit corrections use the same central resolver as
realtime and speech output, including evidence for a switch. A pin
leaves ``_turn_detected_lang`` empty so ``_reply_language_directive``
uses the pin; genuinely ambiguous text stays ``"unknown"`` so the
directive keeps its soft "mirror the user" form.
"""
if self._reply_language in _REPLY_LANG_NAMES:
self._turn_detected_lang = ""
return
detected = resolve_conversation_language(
self._reply_language,
None,
user_text,
conversation_language=self._conversation_baseline(),
)
self._turn_detected_lang = detected
if TURN_LANGUAGE.get() is not None: # inside generate(): scope it to the turn
TURN_LANGUAGE.set(detected)
if is_known_language(detected):
self._conversation_language = detected
def _conversation_baseline(self) -> str:
"""The conversation language this turn continues.
A chat turn carries its session's own history (``history_override``):
its language comes from THAT conversation, so a crash, a restart or a
turn in another chat or on voice never changes it (forensic
2026-10-19: a Turkish chat answered in German, Spanish and English
after errors). A classic turn without a known language yet replays the
live history once.
"""
history = _TURN_HISTORY_OVERRIDE.get()
if history is not None:
# Only this chat's own history: never a language another chat or
# a voice call left in the shared field.
return conversation_language_from_history(history)
if self._conversation_language:
return self._conversation_language
return conversation_language_from_history(getattr(self, "_history", None) or ())
def set_reply_language(self, lang: str) -> None:
"""Live-switch the reply-language pin (desktop "Languages" view).
Takes effect on the next turn (the directive is rebuilt per call to
``_build_system_prompt``). Raises ``ValueError`` for unknown codes so a
bad REST payload surfaces as a 4xx instead of silently no-op'ing.
"""
code = lang.strip().lower() if isinstance(lang, str) else ""
if code not in _REPLY_LANGS:
raise ValueError(
f"unknown reply language {lang!r} (allowed: {sorted(_REPLY_LANGS)})"
)
self._reply_language = code
def _resolve_turn_lang(self) -> str:
"""The de/en/es/pt key this turn's output is localized to.
The single authoritative resolver consumed by every ``ResponseGenerated``
publish (success replies AND the total-failure apology) so the recorded
transcript language is consistent and never the binary ``_looks_german``
gate — which silently tags any non-German reply "en" and so drops Spanish
(Runtime Output Language doctrine). An explicit pin wins; in auto mode it
is THIS turn's language (set at the top of generate()), else the
conversation's. A language without translated phrases, or none at all,
is English (``DEFAULT_LOCALE``) — never German.
"""
lang = self._reply_language
if lang not in _REPLY_LANG_NAMES:
turn = _current_turn_language(self)
lang = turn if is_known_language(turn) else getattr(
self, "_conversation_language", ""
)
return lang if lang in _REPLY_LANG_NAMES else DEFAULT_LOCALE
def _next_provider_down_phrase(self, cause: str | None = None) -> str:
"""Localized 'I can't reach my model' apology + advance the rotation.
Spoken when the whole provider chain fails. ``cause`` (a classified
failure category) makes the phrase state WHY and the in-app fix —
still voice-safe, no provider names/URLs — the detailed diagnostic
stays logged, never spoken (live complaint 2026-06-01: the grok/
Anthropic billing message was read aloud while Gemini was active).
"""
phrase = _provider_down_phrase(
self._resolve_turn_lang(), self._provider_down_idx, cause
)
self._provider_down_idx += 1
return phrase
async def _provider_down_reply(
self, trace_uuid: UUID, cause: str | None = None
) -> str:
"""Total-failure apology, ALSO surfaced to the transcript.
Normal calls publish the phrase as ``ResponseGenerated`` so the
SessionRecorder records it as the turn's ``jarvis_text``. Internal
realtime delegates transfer that event ownership to their session,
which records what the user actually heard. The apology is deliberately
NOT appended to conversation history because a provider outage must not
pollute the LLM context for later turns.
"""
phrase = self._next_provider_down_phrase(cause)
# _next_provider_down_phrase already localized the phrase via
# _resolve_turn_lang; resolving again here is deterministic (same pin /
# detected-language inputs, the rotation index does not affect language)
# and only tags the transcript's jarvis_lang — NEVER _looks_german, which
# would mislabel a Spanish apology as English (Runtime Output Language).
await self._publish_response_generated(trace_id=trace_uuid, text=phrase)
return phrase
async def _publish_response_generated(self, *, trace_id: UUID, text: str) -> None:
"""Publish the public response event unless this call is an internal reply."""
if not _PUBLISH_RESPONSE_EVENT.get():
return
await self._bus.publish(
ResponseGenerated(
trace_id=trace_id,
text=text,
language=self._resolve_turn_lang(),
)
)
def _mandatory_lang_directive(self, name: str) -> str:
"""The hard MANDATORY reply-language pin for a named language.
Shared by an explicit ``brain.reply_language`` pin and the auto-mode
per-turn pin (``_turn_detected_lang``) so both carry identical, strong
wording that survives tool-synthesis.
"""
return (
f"REPLY LANGUAGE — MANDATORY: Always reply in {name}. Keep names, brands and "
"technical identifiers (e.g. Anthropic, GitHub, paths, code) untranslated."
)
def _reply_language_directive(self) -> str:
"""The reply-language instruction appended last to the system prompt.
Names the target language explicitly and is placed last so it wins by
recency; it must start with "REPLY LANGUAGE" (``cli_prompt_context``
cuts the block from there to the end). Pinned modes carve out proper
nouns / brand names / technical identifiers so e.g. "Anthropic" or
"GitHub" are never translated — the user's explicit requirement.
"""
name = _REPLY_LANG_NAMES.get(self._reply_language)
if name is not None:
return self._mandatory_lang_directive(name)
# auto mode: when THIS turn's language is confidently detected, pin it
# HARD with the same MANDATORY wording as an explicit pin. A soft
# "please mirror" line let the model anchor to German on clean English
# input — most visibly on tool-synthesis turns, where the question is
# far from the generation point.
# ``_turn_detected_lang`` is set per turn by generate(); ambiguous text
# detects as "unknown" (not in _REPLY_LANG_NAMES) and falls through to
# the soft mirror. The pin only changes when the user's language
# changes, so the cached system prefix stays stable within a
# single-language conversation.
# Any recognised language pins, not only the four with translated
# phrases: a Turkish conversation is answered in Turkish.
turn_name = language_name(_current_turn_language(self))
if turn_name is not None:
return self._mandatory_lang_directive(turn_name)
return (
"REPLY LANGUAGE: reply in the SAME language as the user's latest message "
"(Portuguese means European Portuguese, never Brazilian). Keep names, brands and "
"technical identifiers untranslated."
)
def _action_failed_phrase(self, user_text: str) -> str:
"""Localized leak-recovery fallback (live bug 2026-06-10 23:12).
Spoken when a provider leaked a tool_use block as text and the
recovery produced no speakable final. Was a hardcoded German string —
an English turn ("What's weather like tomorrow?") was answered in
German. A pinned reply language wins; ``auto`` follows the
conversation; anything else is English.
"""
return i18n_catalog.pick(_ACTION_FAILED_PHRASES, _turn_phrase_language(self, user_text))
def _phrase_language(self, user_text: str) -> str:
"""The de/en/es/pt language of a system phrase for *user_text*."""
return _turn_phrase_language(self, user_text)
def _direct_ack_language(self, user_text: str) -> str:
"""Resolve ``de``/``en``/``es`` for a DIRECT fast-path acknowledgement.
Mirrors :meth:`_action_failed_phrase`: an explicit ``reply_language``
pin (the desktop "Languages" view) wins; otherwise the turn's language
within the running conversation; anything else is English. The DIRECT
path runs off the LLM, so this is the only place the turn language can
be applied to the spoken acknowledgement.
"""
return _turn_phrase_language(self, user_text)
def _localize_direct_ack(
self, call: LocalToolCall, raw_output: str, lang: str
) -> str:
"""Localize a deterministic DIRECT-path acknowledgement.
The DIRECT local-action path surfaces the tool ``output`` VERBATIM to
the user (no LLM re-render), so a tool's hardcoded German success string
would otherwise reach an English/Spanish speaker untranslated (live bug
2026-06-15: an English "open my explorer" turn was acknowledged in
German). ``open_app`` is the one fast-path tool whose success output
is a spoken acknowledgement; translate only its leading German verb and
keep the suffix (the actual app / URL it reported). Any non-matching
output — a future tool, a test stand-in — passes through unchanged.
"""
if call.name != "open_app" or lang == "de":
return raw_output
de_prefix = _OPEN_APP_ACK_PREFIX["de"]
target_prefix = _OPEN_APP_ACK_PREFIX.get(lang)
if target_prefix is not None and raw_output.startswith(de_prefix):
return target_prefix + raw_output[len(de_prefix):]
return raw_output
def _build_system_prompt(self) -> str:
"""Builds the system prompt with Jarvis-Agent-style workspace injection.
Layer order (Jarvis-Agent priority map):
1. SOUL.md — Jarvis' own persona (who I am, tone rules)
2. DODAIOS_PERSONA.md — voice persona incl. the hang-up contract
3. USER.md — about the user (name, communication style, values, …)
4. people/ — list of known people in the user's environment
5. CoreMemory — legacy JSON facts (transitional, kept for back-compat)
6. _CORE_CONTRACT — honesty, routing and self-control facts
7. REPLY LANGUAGE — always last (machine contract)
"""
private = _TURN_OVERRIDE.get()
if private is not None and private.tool_context.get("tool_origin") == "society":
# An agent's own notebooks are its profile source. Do not append
# Jarvis' global USER.md, contacts, persona or ambient core memory.
parts = [
private.system_extra
or "Your private agent context is unavailable; do not invent it.",
_CORE_CONTRACT,
getattr(self, "_evidence_directive", ""),
# The briefing already carries the shared reply policy; sending
# it twice costs ~2.3k characters on every society API turn.
_WRITTEN_CHAT_RULES
if CONVERSATIONAL_RESPONSE_STYLE in (private.system_extra or "")
else _WRITTEN_CHAT_STYLE,
]
identity = getattr(self, "_active_turn_identity", None)
if identity:
parts.append(_provider_identity_directive(identity[0], identity[1], "this agent"))
parts.append(self._reply_language_directive())
return "\n\n".join(part for part in parts if part)
parts: list[str] = []
# The assistant's identity, placed first so it frames everything: the
# wake-word name (Dodaios is the app, never the assistant's
# name) plus its character from SOUL.md, read through an mtime cache
# so what the learning loop writes there reaches the next turn. The
# realtime and GPT-Live instructions build the same block
# (dodaios/brain/identity.py), so every surface answers "who are you"
# the same way.
name = resolve_assistant_name(getattr(self, "_config", None))
parts.append(
identity_block(
getattr(self, "_config", None),
path=getattr(getattr(self, "_soul", None), "path", None),
)
)
# Persona block from DODAIOS_PERSONA.md incl. the hang-up contract.
# The "effective" loader returns the user's custom system prompt when one
# is set in Settings (data/custom_system_prompt.md), else the packaged
# default. Read fresh each turn, so an edit/reset applies on the next turn
# without a restart. Empty string when nothing is available — no crash.
persona_block = load_effective_persona_prompt()
if persona_block:
parts.append(persona_block)
# User's own standing-instructions file (CLAUDE.md equivalent),
# named after the assistant (e.g. Assistant.md). Distinct from the persona: the
# user writes personal preferences here, and the block is framed so they
# refine behaviour but never override safety/confirmations. Read fresh each
# turn -> an edit applies on the next turn, no restart. A read fault must
# never break the prompt build.
try:
from dodaios.brain import agent_instructions as _agent_instructions
prefs_block = _agent_instructions.render_for_prompt(getattr(self, "_config", None))
if prefs_block:
parts.append(prefs_block)
except Exception: # noqa: BLE001
pass
if self._user_profile is not None:
try:
parts.append(self._user_profile.render_for_prompt())
except Exception: # noqa: BLE001
pass
# What Jarvis learned across earlier calls and chats (the background
# review loop in dodaios/memory/learning). A cached snapshot that only
# changes after a review writes, so it stays in the cached prefix.
try:
from dodaios.memory.learning.notebook import snapshot_block
learned_block = snapshot_block()
if learned_block:
parts.append(learned_block)
except Exception: # noqa: BLE001 — a notebook fault never breaks a prompt build
log.debug("learned notebook block unavailable", exc_info=True)
if self._people is not None:
try:
people_block = self._people.render_for_prompt()
if people_block:
parts.append(people_block)
except Exception: # noqa: BLE001
pass
# Chunk B (contacts): compact name-index of the user-curated contact
# book (names + relationship only; e-mails/phones/address fetched on
# demand via contact-lookup). None until Chunk A merges, "" when the
# book is empty — either way no block is injected. Defensive try/except
# so a store error never crashes the system-prompt build (AP-9-adjacent);
# ``getattr`` guard tolerates __init__-bypassing tests (see _tools above).
_contacts = getattr(self, "_contacts", None)
if _contacts is not None:
try:
contacts_block = _contacts.render_for_prompt(max_chars=8_000)
if contacts_block:
parts.append(contacts_block)
except Exception: # noqa: BLE001
pass
# Ambient personal knowledge: the standing identity card. A
# precomputed, deterministic distillation of the user's own profile
# page + core memory — no model call, hard-capped, and rebuilt only
# when its sources change, so it stays in the CACHED prefix in both
# prompt layouts (unlike the per-turn wiki snippets below, which move
# to the turn context in cache-optimized mode). Absent profile =
# empty string = no block. Defensive: ambient knowledge must never be
# able to break a prompt build.
try:
from dodaios.brain.identity_card import identity_card_block
_identity_block = identity_card_block(getattr(self, "_config", None))
if _identity_block:
parts.append(_identity_block)
except Exception: # noqa: BLE001
pass
if self._core_memory is not None:
# Mandatory: re-read BEFORE rendering. Otherwise the LLM only sees
# facts that existed at init time — UI additions and remember-tool
# writes from this process are in the file but not in the cache.
try:
self._core_memory.reload()
except Exception: # noqa: BLE001
pass
cm = self._core_memory.render_system_prompt_block()
# A safety cap only (the 2500-character cost cap was retired): cut,
# and mark the cut, only when the block really is longer.
if len(cm) > _CORE_MEMORY_MAX_CHARS:
cm = cm[:_CORE_MEMORY_MAX_CHARS] + "…"
parts.append(cm)
# Skills-Brain-Integration (Track B): surface the installed, active
# user skills so the router-tier brain can actually choose ``run_skill``
# for them. Without this block the ``run-skill`` tool is registered but
# the brain never learns which skills exist, so it is never selected.
# Static content (changes only on install/promote), so it stays in the
# cached system prefix — mirrors the capability block below. Defensive try/except:
# a renderer fault must never crash the system-prompt build. The lazy
# import is intentional so a monkeypatched renderer resolves correctly.
try:
from dodaios.skills.prompt_injection import (
render_available_skills_section,
)
from dodaios.skills.skill_context import try_get_skill_context
_skill_ctx = try_get_skill_context()
if _skill_ctx is not None:
_skills_section = render_available_skills_section(_skill_ctx.registry)
if _skills_section:
parts.append(_skills_section)
elif not self._skills_omit_warned:
# AD-S6: silently omitting the section was RC2 of "Jarvis
# never calls a skill" — warn once per manager lifetime.
self._skills_omit_warned = True
log.warning(
"skills section omitted: skill context not initialized"
)
except Exception: # noqa: BLE001
if not self._skills_omit_warned:
self._skills_omit_warned = True
log.warning(
"skills section omitted: renderer failed", exc_info=True
)
# CLI first-class capabilities (design 2026-06-10, §5.3): list the
# connected CLIs so the brain can pick them for matching requests.
# Mirrors the skills section above. Rendered from the shared registry
# published by the UI server; absent registry → section omitted.
try:
from dodaios.clis.prompt_section import render_connected_clis_section
from dodaios.clis.shared import get_active_registry
_cli_reg = get_active_registry()
if _cli_reg is not None:
_cli_section = render_connected_clis_section(_cli_reg)
if _cli_section:
parts.append(_cli_section)
except Exception: # noqa: BLE001
log.debug("connected-CLIs section omitted", exc_info=True)
# The lead's team card (2026-09-03): the agent society's roster with
# each agent's hands, plus the rule that "agent" means one of THEM.
# Without it Jarvis answered "which agents do you have" from the
# retired sub-agent system it was trained on while a freshly created
# Gmail agent stood on the island. Rendered from the roster snapshot
# (no IO), byte-stable between roster changes like the CLI section.
# Skipped on a society agent's own turn: that turn carries its own
# briefing (TurnOverride.system_extra), and a specialist must not be
# told it is the lead.
_turn_override = _TURN_OVERRIDE.get()
if _turn_override is None or not _turn_override.system_extra:
try:
from dodaios.society.lead_card import lead_card_section
_lead_card = lead_card_section(lead_name=name)
if _lead_card:
parts.append(_lead_card)
except Exception: # noqa: BLE001 — the card is a convenience, never a turn breaker
log.debug("lead card section omitted", exc_info=True)
# Evidence gate directive (per-turn, AD-CLI8): forces a tool call
# before any answer about an external-data domain. Empty on normal
# turns; set by generate() when the gate returns require_tool.
if self._evidence_directive:
parts.append(self._evidence_directive)
if self._system_prompt_extra:
parts.append(self._system_prompt_extra)
# Per-turn addendum (TurnOverride.system_extra): a surface's own
# briefing for THIS turn only; empty on every other turn.
if _turn_override is not None and _turn_override.system_extra:
parts.append(_turn_override.system_extra)
# The standing contract: honesty, research-versus-action routing and
# self-control facts. The assistant's name is in the identity block.
parts.append(_CORE_CONTRACT)
# Initiative (2026-10-07): every other rule about the end of a reply
# pulls towards "say nothing more", so without this the assistant never
# brought a grounded idea. The level ([brain] proactivity) is static
# between settings changes, so the rule stays in the cached prefix; the
# dated plans it may draw on are per-turn and ride with the date below.
parts.append(
_proactivity.directive(_proactivity.current_level(getattr(self, "_config", None)))
)
if not self._cache_optimized():
upcoming = self._upcoming_block()
if upcoming:
parts.append(upcoming)
# B5 Agent C: per-turn wiki context suffix. Set by generate() via
# maybe_inject() just before the first provider call, consumed here,
# and reset to "" in the finally-block of generate(). Empty string
# = no injection (no-op path, search returned nothing, or timed out).
# Wave 2 (omni-latency): wiki context also moves to the per-turn user
# message in cache-optimized mode (keeps the cached system prefix stable).
if self._wiki_context_suffix and not self._cache_optimized():
parts.append(self._wiki_context_suffix)
# Agentic IDE: while the user has the focused coding mode ON, this turn
# is answered inside their open workspace — the folder, the codebase
# profile, and what each named terminal (Mika, Nova, …) last printed.
# Off / no session = empty string = no block, so this is inert for every
# user who never opens the IDE. In cache-optimized mode the block rides
# the per-turn user message instead (see _build_turn_context), because
# it changes as the agents print and would otherwise break the cached
# system prefix every turn.
if not self._cache_optimized():
agentic_block = self._agentic_focus_block()
if agentic_block:
parts.append(agentic_block)
# Active-model self-awareness: tell THIS turn's actually-answering
# provider/model who it is, so a "which model are you?" question gets an
# honest answer instead of a guessed "Gemini" (forensic 2026-06-20: Grok
# was live and answering yet claimed to be Gemini). Set per fallback-chain
# attempt in generate(), where the real prov_name/model are known; absent
# on non-turn prompt builds (compression / wiki-delta base) → no block.
# Placed late for high recency; provider-stable across same-provider
# turns, so it stays prompt-cache-friendly. On a fallback the block's
# provider label changes between attempts within the turn, invalidating
# the prefix cache for the second attempt — acceptable, since a fallback
# is already a slow path (and matches the pre-existing per-turn mutable
# flags). getattr: tolerates __new__-constructed test managers that bypass
# __init__ (the attr is always set in __init__ for the production path).
identity = getattr(self, "_active_turn_identity", None)
if identity:
parts.append(
_provider_identity_directive(identity[0], identity[1], name)
)
# Written-turn style: typed chat answers are read on screen, so the
# voice persona's spoken-output rules must not govern them. Without
# this override the model drifts to emoji-heavy marketing copy.
# Byte-stable per delivery mode, so the prompt cache stays warm.
if _is_written_turn():
parts.append(_WRITTEN_CHAT_STYLE)
# Reply-language directive LAST — highest recency-salience, and
# cli_prompt_context cuts it from "REPLY LANGUAGE" to the end.
# Byte-stable across turns
# (only changes on an explicit language switch), so it stays prompt-
# cache-friendly.
parts.append(self._reply_language_directive())
return "\n\n".join(p for p in parts if p)
def _cache_optimized(self) -> bool:
"""True when the cache-optimized prompt layout (Wave 2) is enabled."""
perf = getattr(self._config, "performance", None)
return bool(getattr(perf, "cache_optimized_prompt", False))
def _is_pointer_intent(self, user_text: str) -> bool:
"""True when this is a deictic AI-Pointer turn ("worauf zeige ich?").
Cheap regex gate, honoured only when ``[pointer].enabled``. Drives the
per-turn grounding (scope images to the cursor crop, drop the full-screen
screenshot tool) so the brain answers from the cursor, not a screen guess.
"""
cfg = getattr(self._config, "pointer", None)
if not bool(getattr(cfg, "enabled", True)):
return False
try:
from dodaios.pointer.intent import is_pointing_intent # noqa: PLC0415
return is_pointing_intent(user_text)
except Exception: # noqa: BLE001 — gate must never block a turn
return False
def _start_pointer_task(self, user_text: str, is_smalltalk_turn: bool):
"""Launch the deictic AI-Pointer resolution as a background task (AP-9).
Returns an ``asyncio.Task`` resolving to ``(prompt_block, crop_image)``, or
``None`` when the feature is disabled or the turn is smalltalk. The task
does the regex deictic gate itself, so a non-pointing utterance completes
instantly with ``("", None)`` and a headless host fast-skips before any
worker-thread dispatch. Started before the vision-image await so it runs
concurrently rather than serially on the hot path. See
docs/plans/ai-pointer/DESIGN.md.
"""
try:
import asyncio # noqa: PLC0415
from dodaios.pointer.turn import resolve_turn_pointer
cfg = getattr(self._config, "pointer", None)
if not bool(getattr(cfg, "enabled", True)) or is_smalltalk_turn:
return None
return asyncio.create_task(
resolve_turn_pointer(
user_text,
enabled=True,
timeout_s=float(getattr(cfg, "timeout_s", 0.12)),
crop_radius=int(getattr(cfg, "crop_radius", 64)),
)
)
except Exception: # noqa: BLE001 — never crash a turn on pointer setup
log.debug("AI Pointer task launch skipped", exc_info=True)
return None
def _build_turn_context(self) -> str:
"""Per-turn dynamic context for the user message (cache-optimized mode).
Date/time + wiki context. Empty in legacy mode
(there these live in the system prompt instead). Riding on the user
message keeps the cached system prefix byte-stable across turns, which
is what actually lets the Gemini/Anthropic prompt cache hit.
"""
if not self._cache_optimized():
return ""
from datetime import datetime
# Deterministic English weekday. ``strftime('%A')`` renders the weekday
# name in the process locale ("Freitag" on German Windows, "vendredi" on
# French, a CJK string on a Chinese host), leaking a machine-locale,
# often non-English token into the LLM context. Index a fixed English
# tuple by ``weekday()`` (0=Monday) so the label reads the same English on
# every OS. The date is ISO-8601 (unambiguous internationally, unlike a
# dotted d.m.Y); wall-clock time stays local (``datetime.now``).
_weekdays_en = (
"Monday", "Tuesday", "Wednesday", "Thursday",
"Friday", "Saturday", "Sunday",
)
_now = datetime.now()
parts: list[str] = [
# Date/time belongs per-turn, never in the cached prefix (also fixes
# the missing BUG-005 date injection).
f"[Current date and time: {_weekdays_en[_now.weekday()]}, "
f"{_now.strftime('%Y-%m-%d %H:%M')}]"
]
private = _TURN_OVERRIDE.get()
if private is not None and private.tool_context.get("tool_origin") == "society":
return "\n\n".join(parts)
if self._wiki_context_suffix:
parts.append(self._wiki_context_suffix)
upcoming = self._upcoming_block()
if upcoming:
parts.append(upcoming)
agentic_block = self._agentic_focus_block()
if agentic_block:
parts.append(agentic_block)
return "\n\n".join(p for p in parts if p)
@staticmethod
async def _vault_recall(user_text: str) -> str:
"""Per-message memory recall, bounded to 150 ms so a busy disk never stalls a turn."""
from dodaios.memory.vault.runtime import turn_block
try:
return await asyncio.wait_for(asyncio.to_thread(turn_block, user_text), timeout=0.15)
except TimeoutError:
log.info("memory vault: per-message recall skipped (over 150 ms)")
return ""
def _upcoming_block(self) -> str:
"""Dated plans from the notebooks for the next two weeks (initiative grounding).
Pure cached read of the notebook files; ``""`` when initiative is off,
nothing is dated, or anything fails, so it can never break a turn.
"""
try:
return _proactivity.upcoming_block(
_proactivity.current_level(getattr(self, "_config", None))
)
except Exception: # noqa: BLE001 — grounding is a convenience, never a turn breaker
log.debug("initiative: upcoming block skipped", exc_info=True)
return ""
def _agentic_focus_block(self) -> str:
"""Workspace-awareness block while the Agentic IDE's focus mode is on.
Pure in-memory read (the session's cached project profile + each
terminal's ring buffer), so it stays off the latency budget (AP-9). Any failure degrades to no block — a coding-mode
convenience must never be able to break a voice turn.
"""
try:
from dodaios.agentic_ide.context import focus_context_block
return focus_context_block()
except Exception: # noqa: BLE001 - feature absent or mid-reload
return ""
# ------------------------------------------------------------------
# Explicit switching
# ------------------------------------------------------------------
async def switch(self, provider_name: str, *, persist: bool = False) -> None:
"""Switches the active provider.
Even switching to the ALREADY active provider has an effect: it acts
as the reset button for session caches (dead-list, brain-cache,
rate-tracker). Users typically click "Set as active" in the UI
immediately after setting an API key — this should bring the fresh key
into the chain right away rather than being a no-op.
Args:
provider_name: Provider ID (entry-point name) or voice alias.
persist: If True, the selection is written to jarvis.toml [brain]
primary and survives a restart.
"""
canonical = PROVIDER_ALIASES.get(provider_name.lower().strip(), provider_name)
async with self._lock:
if canonical in SUBAGENT_ONLY_BRAIN_PROVIDERS:
log.warning(
"Brain provider %r is subagent-only; ignoring main-brain switch.",
canonical,
)
self.last_persist_ok = False
return
if canonical == self._active_name:
# Re-activation of the already active provider — reset caches
# so a newly set key takes effect on the next turn (otherwise
# the provider stays in _dead_providers).
self._reset_provider_caches()
self.last_persist_ok = (
self._persist_primary(canonical) if persist else False
)
return
try:
self._get_brain(canonical, self._fast_model(canonical))
except KeyError:
log.error("Unbekannter Provider: %s", canonical)
self.last_persist_ok = False
return
previous = self._active_name
self._active_name = canonical
self._switched_to = canonical
# Keep deep_brain following the active provider on a runtime switch
# when there is no explicit cross-provider deep split (deep_brain
# tracked the previous active, or was never configured) — so switching
# to a frontier provider leads ALL intents, not just fast ones (mirror
# of the from_tier_config override rule; "Grok for everything" mandate
# 2026-06-20). A None/"" deep_brain must follow too, not stay stranded.
if not self._config.brain.deep_brain or self._config.brain.deep_brain == previous:
self._config.brain.deep_brain = canonical
self._reset_provider_caches()
self.last_persist_ok = (
self._persist_primary(canonical) if persist else False
)
await self._bus.publish(
BrainProviderSwitched(from_provider=previous, to_provider=canonical)
)
def _reset_provider_caches(self) -> None:
"""Clears session state that would block a freshly set key."""
self._dead_providers.clear()
self._dead_provider_models.clear()
self._brain_cache.clear()
self._rate_tracker.clear()
def reactivate_provider(self, provider: str) -> None:
"""Lifts the session-level deactivation of a provider.
Called by the ``SecretConfigured`` event handler when the user sets a
key via Sidebar → API Keys. Effects:
1. Provider leaves ``_dead_providers`` → returns to the chain.
2. Its brain cache entry is discarded so the next ``_get_brain``
call instantiates a fresh instance with the new key.
3. Any active rate-limit cooldown is also cleared — the user reset
clearly signals "I want to use this now".
Idempotent: calling twice is allowed and is a no-op with a clean cache.
"""
was_dead = provider in self._dead_providers
self._dead_providers.discard(provider)
self._dead_provider_models = {
k for k in self._dead_provider_models if k[0] != provider
}
keys_to_drop = [k for k in self._brain_cache
if k[0] == provider or str(k[0]).startswith(provider + "@")]
for k in keys_to_drop:
self._brain_cache.pop(k, None)
self._rate_tracker.clear(provider)
if was_dead or keys_to_drop:
log.info(
"Provider '%s' reactivated (dead=%s, brain_cache_dropped=%d)",
provider, was_dead, len(keys_to_drop),
)
def _active_has_usable_credential(self) -> bool:
"""Whether the currently active brain provider has a usable credential.
True iff an API key is present in any of the active provider's secret
slots, or a keyless provider is rescued by a connected OAuth login
(mirrors the pre-boot key check in ``from_tier_config`` so the two stay
consistent). Used by the ``SecretConfigured`` handler to decide whether a
fresh-install ``brain.primary`` default — which the downloader has no key
for — should yield to the provider the user just configured.
"""
from dodaios.core import config as _cfg_mod
from dodaios.core.config import PROVIDER_SECRET_CANDIDATES
active = self._active_name
specs = PROVIDER_SECRET_CANDIDATES.get(active)
if specs:
try:
if _cfg_mod.get_secret_any(specs):
return True
except Exception: # noqa: BLE001 — an unreadable keyring counts as "no key"
pass
return _keyless_provider_is_rescued_by_oauth(active)
def apply_provider_model(self, provider: str, model: str) -> bool:
"""Live-apply a model override for a brain provider (no restart).
The model picker in the API-Keys view persists the choice to jarvis.toml
AND calls this so the running brain uses the new model on the next turn.
The manager builds its config independently of ``app.state.config``, so
mutating that route-level config would NOT reach the brain — this method
updates the manager's OWN ``self._config`` and drops cached brain
instances for the provider so the next ``_get_brain`` rebuilds with the
new model.
An empty string resets the override to ``None`` (the provider then falls
back to its frontier default via ``_fast_model``).
Returns ``True`` iff ``provider`` is the currently active brain — i.e.
the change takes effect immediately. For an inactive provider the
override is stored and applies as soon as the user switches to it.
"""
from dodaios.core.config import BrainProviderConfig
canonical = PROVIDER_ALIASES.get(provider.lower().strip(), provider)
new_model = model.strip() or None
providers = self._config.brain.providers
pc = providers.get(canonical)
if pc is None:
providers[canonical] = BrainProviderConfig(model=new_model)
else:
try:
pc.model = new_model
except Exception: # noqa: BLE001 — frozen/validation: rebuild the block.
data = pc.model_dump() if hasattr(pc, "model_dump") else {}
data["model"] = new_model
providers[canonical] = BrainProviderConfig(**data)
# Drop cached instances for this provider so the new model is used; lift
# any session-level deactivation (mirrors ``reactivate_provider``). The
# scoped instances of a per-turn override ("<name>@<scope>") go too.
for key in [
k
for k in self._brain_cache
if k[0] == canonical or str(k[0]).startswith(canonical + "@")
]:
self._brain_cache.pop(key, None)
self._dead_providers.discard(canonical)
self._dead_provider_models = {
k for k in self._dead_provider_models if k[0] != canonical
}
return canonical == self._active_name
@staticmethod
def _persist_primary(name: str) -> bool:
"""Persist ``brain.primary`` to disk (all three layers via config_writer).
Returns ``True`` iff the write actually succeeded, ``False`` otherwise.
A failure is logged loudly (anti-silent-drop) so the caller can report
the real disk outcome up to the UI instead of echoing the request flag.
"""
# Lazy import: config_writer needs tomlkit (optional dep in the wizard path).
try:
from dodaios.core import config_writer
config_writer.set_brain_primary(name)
return True
except Exception as exc: # noqa: BLE001
log.error("Failed to persist brain.primary=%r: %s", name, exc)
return False
def _detect_switch_intent(self, text: str) -> str | None:
"""Strict gate-based detector — no more substring matching.
Delegates to `voice_command_gate.match_voice_command`, which only
returns a match for unambiguous patterns like "wechsel auf gemini".
Harmless sentences like "ich gehe auf meinem Weg" no longer match.
"""
match = match_voice_command(text)
if match is None or match.kind != "provider_switch":
return None
return match.target
def _detect_language_switch_intent(self, text: str) -> str | None:
"""Strict gate-based reply-language switch detector.
Delegates to ``voice_command_gate.match_voice_command`` and returns the
target code (de/en/es/auto) ONLY for an unambiguous language command
like "stell auf Englisch um". A harmless mention ("wie heißt das auf
Englisch?") returns None and reaches the brain normally.
"""
match = match_voice_command(text)
if match is None or match.kind != "language_switch":
return None
return match.target
def _apply_reply_language_switch(self, code: str) -> str:
"""Execute a recognised reply-language switch deterministically.
Mirrors the canonical ``PUT /api/settings/reply-language`` path (live
set + persist) but is reached in ``generate()`` BEFORE the force-spawn
heuristic, so a trivial config change never becomes a worker mission
(2026-06-22 forensic: "stell auf Englisch um" was dispatched as a worker
and failed, harness down). It runs without the LLM, so it works no
matter the active provider's tool-calling capability. Returns the spoken
confirmation, or "" for an unknown code (caller falls through).
"""
try:
self.set_reply_language(code) # live; ValueError on unknown code
except ValueError:
return ""
lang = self._reply_language
# Best-effort in-memory cfg agreement (a frozen model is not an error).
try:
self._config.brain.reply_language = lang # type: ignore[attr-defined]
except Exception as exc: # noqa: BLE001
log.debug("in-memory cfg.brain.reply_language update skipped: %s", exc)
# Persist as boot default — best-effort: a read-only / locked jarvis.toml
# must not break the live switch that already applied.
persisted = True
try:
from dodaios.core import config_writer
config_writer.set_reply_language(lang)
except Exception as exc: # noqa: BLE001
persisted = False
log.warning(
"reply-language persist failed (live switch still applied): %s", exc
)
log.info(
"reply-language switched to %r via deterministic voice gate (persisted=%s)",
lang, persisted,
)
if persisted:
if lang == "auto":
return i18n_catalog.t("brain.lang_switch_confirm_auto", self._resolve_turn_lang())
return i18n_catalog.pick(_LANG_SWITCH_CONFIRM, lang)
return i18n_catalog.pick(_LANG_SWITCH_CONFIRM_SESSION, lang)
def _detect_subagent_switch_intent(self, text: str) -> str | None:
"""Strict gate-based sub-agent (Heavy-Task worker) provider switch.
Delegates to ``voice_command_gate.match_voice_command``; returns the
spoken provider word ONLY for a sub-agent-qualified command like
"wechsle den Sub-Agent-Provider auf OpenAI". A bare "switch to gemini"
is a main-brain switch (kind=provider_switch) and returns None here.
"""
match = match_voice_command(text)
if match is None or match.kind != "subagent_switch":
return None
return match.target
async def _apply_subagent_provider_switch(self, word: str) -> str:
"""Execute a recognised sub-agent provider switch through the ONE
validated path (app_control.apply_provider_switch) instead of persisting
blindly. Maps the spoken word to a canonical slug, runs the same
credential validation the REST endpoint uses (Codex/Antigravity OAuth,
key presence), persists across all 3 layers (TOML + config-soll pin + ENV)
so the drift-guard cannot revert it, and renders an HONEST readback: the
real target on success, a named reason on failure, never a false "done".
Returns "" for an unknown word (caller falls through to the brain).
Forensic 2026-06-27: the old blind-persist path said "Erledigt" for an
unconnected provider and even when the persist threw.
"""
canonical = _SUBAGENT_VOICE_TO_CANONICAL.get(word.strip().lower())
if canonical is None:
return ""
from dodaios.brain.app_control import apply_provider_switch, resolve_running_cfg
try:
result = await apply_provider_switch(
"subagent", canonical, cfg=resolve_running_cfg()
)
except Exception as exc: # noqa: BLE001 — never crash the turn
log.warning("sub-agent voice switch failed: %s", exc)
result = {"ok": False, "error_kind": "other", "error": str(exc)}
lang = self._resolve_turn_lang()
if result.get("ok"):
new = str(result.get("new_provider") or canonical)
display = _SUBAGENT_DISPLAY.get(new, new)
log.info("sub-agent provider switched to %r via deterministic voice gate", new)
template = i18n_catalog.pick(_SUBAGENT_SWITCH_CONFIRM, lang)
return template.format(p=display)
display = _SUBAGENT_DISPLAY.get(canonical, canonical)
return _subagent_switch_failure_phrase(result, display, lang)
async def _apply_main_provider_switch(self, word: str) -> str:
"""Deterministic main-brain provider switch with an HONEST readback.
Mirrors ``_apply_subagent_provider_switch``: routes through the one
validated ``apply_provider_switch("brain", …)`` (credential / catalog /
subagent-only checks + live-apply) and speaks the CHECKED result. The
old path (``await self.switch(word); return ""``) was silent even on a
refused switch (audit 2026-06-27). Returns ``""`` for an unmappable word
so the caller falls through to the brain.
"""
canonical = PROVIDER_ALIASES.get(word.strip().lower())
if canonical is None:
return ""
from dodaios.brain.app_control import (
apply_provider_switch,
get_spec,
resolve_running_cfg,
)
try:
result = await apply_provider_switch("brain", canonical, cfg=resolve_running_cfg())
except Exception as exc: # noqa: BLE001
log.warning("main-brain voice switch failed: %s", exc)
result = {"ok": False, "error_kind": "other", "error": str(exc)}
lang = self._resolve_turn_lang()
spec = get_spec(str(result.get("new_provider") or canonical))
display = getattr(spec, "label", None) or canonical
if result.get("ok"):
log.info("main-brain provider switched to %r via deterministic voice gate", canonical)
template = i18n_catalog.pick(_PROVIDER_SWITCH_CONFIRM, lang)
return template.format(p=display)
return _provider_switch_failure_phrase(result, display, lang)
def _detect_cancel_intent(self, text: str) -> bool:
"""True when the user wants to cancel a running Jarvis-Agent task."""
match = match_voice_command(text)
return match is not None and match.kind == "cancel"
def _detect_depth_override(self, text: str) -> str | None:
"""Detects 'denk gründlich/schnell' → sticky override to deep/fast.
Uses the VoiceCommandGate for consistent pattern lists.
"""
match = match_voice_command(text)
if match is None:
return None
if match.kind == "depth_deep":
return "deep"
if match.kind == "depth_fast":
return "fast"
return None
# ------------------------------------------------------------------
# Force-Spawn-Heuristik (Persona-Mandat Phase 3)
# ------------------------------------------------------------------
def _get_routing_patterns(
self,
) -> tuple[re.Pattern[str], re.Pattern[str], re.Pattern[str]]:
"""Lazily compiles the three force-spawn regexes from BrainRoutingConfig."""
if self._routing_patterns is None:
cfg = self._config.brain.routing
self._routing_patterns = (
_build_verb_pattern(list(cfg.spawn_verbs)),
_build_marker_pattern(list(cfg.external_system_markers)),
_build_smalltalk_pattern(list(cfg.smalltalk_allowlist)),
)
return self._routing_patterns
def _get_heavy_research_patterns(
self,
) -> tuple[re.Pattern[str], re.Pattern[str]]:
"""Lazily compile the (verb, heaviness-marker) regexes for heavy-research
force-spawn from BrainRoutingConfig. Verbs use ``\\b<stem>\\w*\\b`` so
conjugations match; markers are word/phrase boundaries."""
if self._heavy_research_patterns is None:
cfg = self._config.brain.routing
verbs = list(getattr(cfg, "heavy_research_verbs", []) or [])
markers = list(getattr(cfg, "heavy_research_markers", []) or [])
self._heavy_research_patterns = (
_build_verb_pattern(verbs),
_build_marker_pattern(markers),
)
return self._heavy_research_patterns
def _is_heavy_research(self, user_text: str) -> bool:
"""True iff the utterance is HEAVY multi-step research/analysis that must
be OFFLOADED to a background mission, not answered inline on the deep
brain (where it blows the ~20 s voice budget and is beheaded — live bug
2026-06-14, a long-haul trip-research turn).
Conjunctive gate (precision over recall): a research/analysis VERB must
be present AND a heaviness signal — a horizon/multi-step/requirements
marker, OR >= ``heavy_research_min_verbs_multiclause`` verb matches
(multi-clause), OR length >= ``heavy_research_min_chars`` with a verb.
Length alone never spawns, so a quick "recherchier das mal kurz" stays
inline. Pure regex (AP-11 safe, cross-platform).
RETIRED from the spawn decision 2026-07-21 (strict mode is
explicit-only — ``_should_force_spawn`` no longer consults this
detector). Kept as a classifier for telemetry/tests and a possible
future opt-in.
"""
cfg = self._config.brain.routing
if not getattr(cfg, "heavy_research_enabled", True):
return False
t = (user_text or "").strip()
if not t:
return False
verb_re, marker_re = self._get_heavy_research_patterns()
verbs_found = verb_re.findall(t)
if not verbs_found:
return False # (A) no research/analysis verb → never heavy research
min_verbs = max(
2, int(getattr(cfg, "heavy_research_min_verbs_multiclause", 2))
)
if len(verbs_found) >= min_verbs:
return True # multi-clause "recherchier X und analysier Y"
if marker_re.search(t):
return True # verb + horizon / multi-step / requirements marker
min_chars = int(getattr(cfg, "heavy_research_min_chars", 120))
return len(t) >= min_chars # verb + sheer length
def _get_force_spawn_pattern(self) -> re.Pattern[str]:
"""Compile the strict-mode trigger-phrase regex (User-Mandate 2026-05-14).
Multi-word phrases are matched literal-substring, single-word
markers with `\\b` boundaries so 'spawn' matches 'spawn' /
'spawne' / 'spawnen' but not arbitrary substrings.
"""
if self._force_spawn_pattern is None:
phrases = list(self._config.brain.routing.force_spawn_phrases)
if not phrases:
self._force_spawn_pattern = _NEVER_MATCH_RE
else:
parts = [re.escape(p) for p in phrases]
# Each part is a literal substring; boundary handling
# mirrors `_build_smalltalk_pattern` so multi-word
# phrases like "deep dive" match without requiring word
# boundaries inside.
self._force_spawn_pattern = re.compile(
r"(?:^|\b)(?:" + "|".join(parts) + r")(?:\b|$)",
re.IGNORECASE,
)
return self._force_spawn_pattern
def set_mission_command_handlers(
self,
*,
status_fn: Callable[[str | None], Awaitable[str]] | None,
cancel_fn: Callable[[str | None], Awaitable[str]] | None,
) -> None:
"""Wires the status/cancel handlers for Jarvis-Agent mission reads.
Called by bootstrap (e.g. ``dodaios/missions/init.py`` or server
startup) once the MissionManager is ready.
AD-12 (status read via voice without spawn): when ``status_fn`` is
set, the ``generate()`` path deterministically calls
``status_fn(mission_id)`` on a detected status phrase instead of
asking the LLM or triggering a new Jarvis-Agent spawn.
AP-OC5: pattern-match-first discipline — when no handlers are
registered (e.g. tests, headless mode), the code falls back to the
normal force-spawn/tool-use path (no crash).
Args:
status_fn: ``async (mission_id: str | None) -> str`` — returns a
TTS-safe status announcement. ``mission_id=None`` means
"summarise all active missions".
cancel_fn: ``async (mission_id: str | None) -> str`` — cancels
mission(s) and returns a confirmation. ``mission_id=None``
means "cancel all active Jarvis-Agent missions".
"""
self._jarvis_agent_status_fn = status_fn
self._jarvis_agent_cancel_fn = cancel_fn
def own_message_recorder(self, recorder: Any, bus: Any) -> None:
"""Take ownership of the recorder the factory attached to ``bus``."""
self._message_recorder = (recorder, bus)
async def aclose(self) -> None:
"""Release what this brain owns: its message recorder and its store.
A brain built for one browser voice session used to keep both forever:
the recorder stayed on the shared bus (every later answer was recorded
once more per past session) and the store's aiosqlite connection, which
runs on a non-daemon thread, kept the process from exiting at shutdown.
Idempotent; never raises.
"""
owned = getattr(self, "_message_recorder", None)
self._message_recorder = None
if owned is not None:
recorder, bus = owned
try:
recorder.detach(bus)
except Exception: # noqa: BLE001 — closing must never raise
log.debug("message recorder detach failed", exc_info=True)
recall = getattr(self, "_recall", None)
if recall is not None and callable(getattr(recall, "close", None)):
try:
await recall.close()
except Exception: # noqa: BLE001 — closing must never raise
log.debug("recall store close failed", exc_info=True)
def _live_tool_names(self) -> tuple[str, ...]:
"""Names of every tool attached RIGHT NOW — the honest-refusal evidence.
Read fresh on every call and never cached: ``refresh_tools()`` replaces
``self._tools`` wholesale each time a CLI or MCP server connects, so a
snapshot taken earlier in the turn would be exactly the stale picture
the refusals are being fixed for (GT-16). ``_local_action_tools`` is
included because the deterministic fast path can serve a request just
as well as the brain surface can. The ``getattr`` guards tolerate
__init__-bypassing tests, like the other readers of ``_tools``.
"""
tools = dict(getattr(self, "_tools", None) or {})
tools.update(getattr(self, "_local_action_tools", None) or {})
override = _TURN_OVERRIDE.get()
if override is not None:
tools = self._apply_turn_override_tools(tools, override)
return tuple(sorted(tools))
def _check_unsupported_intent(self, user_text: str) -> str | None:
"""Agent-C capability gate: return a deterministic refusal when the
utterance has an action intent that no registered capability covers.
Returns ``None`` when:
- The CapabilityRegistry module is not yet deployed (graceful no-op).
- The utterance is smalltalk / Q&A (no action intent detected).
- A registered capability resolves the intent.
Returns a short, TTS-safe refusal string when:
- ``registry.has_action_intent(text)`` is True AND
- ``registry.resolve_intent(text)`` is None AND
- ``_is_smalltalk(text)`` is False.
No LLM call is made here — pure regex + registry lookup (AP-11).
"""
try:
from dodaios.core.capabilities import get_registry # type: ignore[import]
except Exception: # noqa: BLE001 — module not yet deployed
return None
try:
reg = get_registry()
t = (user_text or "").strip()
if not t:
return None
if self._is_smalltalk(t):
return None
# Empty/unseeded registry → step aside (fail-safe). has_action_intent
# matches the STATIC universal verb catalogue (seed-independent), so
# without this guard an unseeded registry refuses EVERY action
# utterance (resolve_intent is always None when nothing is
# registered) and pre-empts the force-spawn path. Mirrors the
# populated-guard in local_action_gate.match_local_action. Defense in
# depth behind the boot seed in brain/factory.build_default_brain —
# live bug 2026-05-25 ("Kannst du einen Subagent spawnen").
if not getattr(reg, "all", lambda: ())():
return None
# Desktop-control commands (compound open-and-operate, GUI verbs)
# are never "unsupported" — computer-use is the universal GUI
# integration and the fast path routes them there. Defense in depth
# so a sparse/older registry can't pre-empt that with the canned
# refusal (live bug 2026-05-25: "oeffne WhatsApp und schreib").
if _looks_like_desktop_control(_gate_normalize(t)):
return None
# 2026-06-01: the sub-agent is the universal capability for generic
# work (analyse/build/fix/code/research/git). Only a SPECIFIC
# external integration the worker cannot satisfy (mail/calendar/
# Spotify/social/delivery) is genuinely "unsupported". Everything
# else falls through to the force-spawn path so a sub-agent task is
# delegated natively instead of refused with "kann ich noch nicht" # i18n-allow
# (live forensic 2026-06-01: a sub-agent task was refused, then only
# spawned once the user said "Subagent" explicitly).
if not requires_external_integration(t):
return None
if reg.has_action_intent(t) and reg.resolve_intent(t) is None:
# GT-16: `resolve_intent` speaks for the registry, and the
# registry lags the tool surface — a plugin/CLI/MCP server
# connected mid-session is callable while the registry still
# knows nothing. Ask the LIVE tools before speaking a refusal;
# a tool named after the requested system means the capability
# is there and the turn must proceed. A wrong tool call is
# recoverable, a false "I can't do that" is the bug.
wanted = external_integration_terms(t)
if live_surface_covers(wanted, self._live_tool_names()):
log.info(
"Unsupported-intent refusal stood down: a tool on the "
"live surface covers %s — proceeding instead of "
"refusing (registry had not caught up).",
", ".join(wanted) or "the request",
)
return None
# Detect user language from text heuristic (simple: if latin
# chars + german umlaut present → DE, else EN).
_de_markers = re.search(r"[äöüÄÖÜß]|(?:bitte|kannst|schick|trag|sende)", t, re.I)
if _de_markers:
return (
"Das kann ich noch nicht. Mir fehlt dafür ein Werkzeug — "
"wenn du mir verrätst welches MCP oder welche Integration "
"zuständig wäre, kann ich's lernen."
)
return (
"I can't do that yet. I don't have a registered tool for it. "
"Tell me which MCP or integration should handle it and I can learn."
)
except Exception: # noqa: BLE001 — registry error must not crash generate()
log.debug("_check_unsupported_intent: registry error", exc_info=True)
return None
def _run_evidence_gate(self, user_text: str) -> EvidenceVerdict:
"""Defensive wrapper around ``check_evidence_domain`` (AD-CLI4..8).
Any infrastructure fault (missing config field, no shared CLI
registry, capabilities module error) degrades to PASS — the gate adds
behaviour, it must never block the voice path.
"""
from dodaios.brain.evidence_gate import EvidenceVerdict, check_evidence_domain
# AD-S3 (a matched skill IS the capability): a deterministically
# skill-matched turn already proves an installed integration owns this
# request — the gate must never overrule it. Live 2026-07-18 (voice
# session 18:31): the paired-capability sync had not reached this
# process' CapabilityRegistry, so a CONNECTED Google Calendar plugin
# turn — freshly matched to plugin-google_calendar — still got the
# deterministic "Ich habe aktuell keinen Kalenderzugriff" refusal # i18n-allow: quoted live refusal under discussion
# plus a CLI-setup detour. With the skill match as evidence the turn
# proceeds; a genuinely dead plugin still fails honestly through its
# tool's own "not connected" result.
if getattr(self, "_skill_turn_match", None) is not None:
log.info(
"Evidence gate stood down: turn is owned by matched skill %s "
"(AD-S3: a matched skill IS the capability)",
getattr(self._skill_turn_match, "name", "?"),
)
return EvidenceVerdict(kind="pass")
# A skill AUTHORING request names calendar / mail / music only as the
# content of the skill to be written; the capability that serves the
# turn is the create-skill tool, not those domains' connectors.
if getattr(self, "_skill_meta_turn", ""):
log.info(
"Evidence gate stood down: skill %s request — the skill tools "
"are the capability",
self._skill_meta_turn,
)
return EvidenceVerdict(kind="pass")
try:
cfg = self._config.brain.evidence_domains
if not cfg.enabled:
return EvidenceVerdict(kind="pass")
from dodaios.clis.capability_provider import (
connected_domain_tool_map,
merged_evidence_domains,
refusal_hint,
)
from dodaios.clis.shared import get_active_registry
from dodaios.core.capabilities import get_registry
cli_reg = get_active_registry()
domain_map = dict(
connected_domain_tool_map(cli_reg) if cli_reg is not None else {}
)
def _hint(domain: str, lang: str) -> str:
if cli_reg is None:
return ""
return refusal_hint(domain, cli_reg, lang)
return check_evidence_domain(
user_text,
enabled=cfg.enabled,
domains=merged_evidence_domains(cli_reg, cfg.domains)
if cli_reg is not None
else cfg.domains,
capability_registry=get_registry(),
domain_tool_map=domain_map,
refusal_hint_fn=_hint,
# Read HERE, at decision time (GT-16): refresh_tools() swaps
# self._tools out wholesale on every CLI/MCP connect, so any
# earlier snapshot is the stale picture that made the gate
# refuse a domain it could actually serve.
live_tool_names=self._live_tool_names(),
# The gate used to pick its refusal language by sniffing the
# utterance, which ignored the user's pin and knew only two
# languages — a Spanish user was told in English that there is
# no calendar access (OF-15). Resolved here with the same
# arguments the honesty phrase later uses, so one turn cannot
# speak two languages.
language=_turn_phrase_language(self, user_text),
)
except Exception: # noqa: BLE001
log.debug("evidence gate degraded to PASS", exc_info=True)
return EvidenceVerdict(kind="pass")
def _is_smalltalk(self, user_text: str) -> bool:
"""Pure smalltalk allowlist check — independent of spawn-verb logic.
Bug fix 2026-05-01 (voice session 2026-04-30 22:38): the user said
"es geht ab", the smalltalk allowlist did not match (phrase was
missing), force-spawn did nothing, the LLM had full tool visibility
and hallucinated a Jarvis-Agent spawn. Result: main Jarvis claimed to have
started tests that it never started.
Used in ``generate()`` to hide the spawn vehicles on clear smalltalk
turns (``_smalltalk_tool_override``), so the LLM can no longer spawn.
Greeting-prefix guard (live bug 2026-06-07, data/jarvis_desktop.log
18:19:07): the user said "Hallo, öffne ihn für mich". The allowlist i18n-allow
substring-matched the leading "Hallo", the turn was treated as
smalltalk, the action tools were hidden, and the brain spoke the
anti-silence refusal "Das kann ich gerade nicht ausführen — mir fehlt i18n-allow
dafür das passende Werkzeug." A greeting/politeness prefix in front of a i18n-allow
REAL command is NOT smalltalk: strip the leading greeting run and, if
what remains is itself a non-smalltalk action request, classify the turn
as a command (return False) so the tools stay visible and force-spawn
can fire. Standalone smalltalk ("Hallo", "Hallo, wie geht's?") and
greeting-less chit-chat ("was machst du") are unaffected.
2026-06-10 23:13 recurrence (same log): "Hey, what's the weather like
today?" — the original guard additionally required an ACTION verb in
the remainder, so a greeting-prefixed information QUESTION stayed
smalltalk, search_web was hidden, and the brain refused with the
anti-silence fallback. The greeting prefix must never change the
classification of the remainder: a non-smalltalk remainder keeps the
turn a real request, action verb or not (exactly as the same words
without the greeting would classify).
"""
t = (user_text or "").strip()
if not t:
return False
_, _, smalltalk_re = self._get_routing_patterns()
if not smalltalk_re.search(t):
return False
stripped = _GREETING_PREFIX_RE.sub("", t).strip()
if (
stripped # something survives the greeting
and stripped != t # a greeting prefix was removed
and not smalltalk_re.search(stripped) # the remainder isn't smalltalk too
):
return False
# Smalltalk-head/tail guard (live bug 2026-06-19, the Bill-Gates turn):
# a continuation-recombine glued the answered "Was geht ab?" turn onto a
# real command ("… mach mir den ältesten Bill-Gates-Post auf"). The
# allowlist matched the chit-chat part, so the WHOLE turn was demoted to
# a tool-less smalltalk turn — computer_use/spawn hidden, the deep brain
# spoke the no-op "Notiert …" and never opened the browser. When the
# utterance ALSO carries a clear action/request signal it is a COMMAND,
# not chit-chat: keep the action tools visible. See _ACTION_REQUEST_RE.
if _ACTION_REQUEST_RE.search(t):
return False
return True
# Back-compat alias for the read-only tool the smalltalk path used to keep
# by allowlist. The override is a HIDE-list now
# (``_SMALLTALK_HIDDEN_TOOL_NAMES``), so screenshot survives like every
# other non-spawn tool; the name is kept because external introspection
# (telemetry, eval harness) reads it. NOTE: `_gate_screen_tool` still runs
# AFTER the override and removes `screenshot` unless the utterance carries a
# visual-reference marker (2026-06-14 screen-narration guard) — the
# 2026-05-31 "Hallo, lies mir vor was oben links steht" case survives
# because "lies" / "oben links" / "steht" are markers.
_SMALLTALK_SAFE_TOOLS: frozenset[str] = frozenset({"screenshot"})
# Skill-aware routing guard (AD-S3, 2026-06-09 rebuild): the Skill matched
# for the CURRENT turn, set early in generate() and overwritten on every
# turn. While set, force-spawn and the local-action fast path stand down
# and run-skill stays visible even on smalltalk turns.
_skill_turn_match_fallback: Any | None = None
# Direct-trigger handoff (AD-S4): the speech pipeline / chat hook notes a
# trigger match here instead of macro-running it; generate() consumes it
# on the next call and injects the skill instructions into the turn.
_pending_forced_skill: tuple[str, str, str] | None = None
_skill_turn_content_fallback: str = ""
_skill_turn_source_fallback: str = "match"
_skill_injected_inline_fallback: bool = False
# Skill META turn (2026-08-18): the user talks ABOUT a skill — asks for a
# new one ("authoring": skill / routine / automation / workflow …) or wants
# one switched off, deleted, listed ("lifecycle"). Set by
# ``_match_skill_for_turn`` on every probe (``""`` otherwise); while set,
# the force-spawn guard and the evidence gate stand down and no domain
# skill may capture — the create-skill router tool / the skill
# app-commands are the capability that owns such a turn, whether or not
# the skill-creator builtin captured it. See dodaios/skills/authoring_request.py.
_skill_meta_turn: str = ""
# AD-S6: warn exactly once per manager lifetime when the AVAILABLE
# SKILLS section cannot be rendered (RC2 used to be silent).
_skills_omit_warned: bool = False
# Evidence gate (CLI first-class capabilities, 2026-06-10): per-turn
# mandatory-tool directive + the tool that must stay visible even on a
# smalltalk-classified turn ("was steht heute an" matches the smalltalk
# allowlist forms). Reset at the start of every generate() turn.
_evidence_directive: str = ""
_evidence_required_tool: str = ""
# True when the mandated tool this turn is a WRITE/create action (e.g.
# contact-upsert) rather than a read lookup — switches the honest backstop
# to write wording and lets a clarifying question stand. Reset per turn.
_evidence_required_is_write: bool = False
# The external-data domain (calendar/email/cloud/…) a READ mandate targets,
# so an unmet mandate's spoken fallback can NAME the capability instead of
# the generic "the tool" (B3, 2026-06-30). Reset per turn.
_evidence_required_domain: str = ""
def _local_skill_turn_state(self) -> _SkillTurnState | None:
state = _SKILL_TURN_STATE.get()
return state if state is not None and state.owner is self else None
@property
def _skill_turn_match(self) -> Any | None:
state = self._local_skill_turn_state()
if state is not None:
return state.match
return self.__dict__.get(
"_skill_turn_match_fallback",
type(self)._skill_turn_match_fallback,
)
@_skill_turn_match.setter
def _skill_turn_match(self, value: Any | None) -> None:
state = self._local_skill_turn_state()
if state is not None:
state.match = value
else:
self._skill_turn_match_fallback = value
@property
def _skill_turn_content(self) -> str:
state = self._local_skill_turn_state()
if state is not None:
return state.content
return self.__dict__.get(
"_skill_turn_content_fallback",
type(self)._skill_turn_content_fallback,
)
@_skill_turn_content.setter
def _skill_turn_content(self, value: str) -> None:
state = self._local_skill_turn_state()
if state is not None:
state.content = value
else:
self._skill_turn_content_fallback = value
@property
def _skill_turn_source(self) -> str:
state = self._local_skill_turn_state()
if state is not None:
return state.source
return self.__dict__.get(
"_skill_turn_source_fallback",
type(self)._skill_turn_source_fallback,
)
@_skill_turn_source.setter
def _skill_turn_source(self, value: str) -> None:
state = self._local_skill_turn_state()
if state is not None:
state.source = value
else:
self._skill_turn_source_fallback = value
@property
def _skill_injected_inline(self) -> bool:
state = self._local_skill_turn_state()
if state is not None:
return state.injected_inline
return self.__dict__.get(
"_skill_injected_inline_fallback",
type(self)._skill_injected_inline_fallback,
)
@_skill_injected_inline.setter
def _skill_injected_inline(self, value: bool) -> None:
state = self._local_skill_turn_state()
if state is not None:
state.injected_inline = bool(value)
else:
self._skill_injected_inline_fallback = bool(value)
def note_skill_trigger(
self, skill_name: str, *, content: str = "", source: str = "trigger"
) -> None:
"""Record a direct trigger match for the next generate() turn (AD-S4).
Called by the speech pipeline / desktop chat hook when the
TriggerMatcher fires. The skill is NOT executed here — generate()
resolves it, injects its instructions into the turn context (or
dispatches a mission for ``execution: mission`` skills), and the
normal brain turn produces the spoken answer.
"""
self._pending_forced_skill = (skill_name, content, source)
def _consume_pending_skill_trigger(self, user_text: str) -> None:
"""Fold a noted trigger into this turn's skill match (AD-S4)."""
pending = self._pending_forced_skill
self._pending_forced_skill = None
self._skill_turn_content = ""
self._skill_turn_source = "match"
if pending is None:
return
skill_name, content, source = pending
try:
from dodaios.skills.skill_context import try_get_skill_context
ctx = try_get_skill_context()
if ctx is None:
return
skill = ctx.registry.get(skill_name)
except Exception: # noqa: BLE001
log.warning("noted skill trigger %r could not be resolved", skill_name)
return
if self._skill_is_blocked(skill):
log.info("noted skill %r is block-tier — ignored", skill_name)
return
self._skill_turn_match = skill
self._skill_turn_content = content
self._skill_turn_source = source
def _skills_config(self) -> Any:
"""The ``[skills]`` config section.
Reads ``self._config`` directly rather than through a defensive
``getattr`` chain: an earlier draft looked up a mistyped attribute name
and silently fell back to defaults, which left shadow mode permanently
on and made every capture test fail for a reason nothing reported. A
wrong config read must be a crash, not a quiet behaviour change.
The section fallback stays, because an older ``jarvis.toml`` parsed by a
newer binary genuinely can lack it.
"""
from dodaios.core.config import SkillsConfig
section = getattr(self._config, "skills", None)
return section if section is not None else SkillsConfig()
def _match_skill_for_turn(self, user_text: str, lang: str = "auto") -> Any | None:
"""Deterministic skill-match probe (AD-S3). Returns the matched Skill or None.
Two channels, in strict order, through the ONE shared entry point
(``dodaios.skills.match_eval.evaluate_match``):
1. The author's voice-trigger regex — absolute precedence, unchanged.
Every utterance that worked before this method grew a second channel
still takes exactly the same path.
2. The deterministic relevance scorer — the paraphrase channel. Only
reached on a trigger MISS, so it is purely additive.
The relevance fallback is nested HERE rather than added as another gate
in ``generate()`` for one reason: every guard below (definitional
question, block tier, and — via the caller — AD-S9 and the local-action
stand-down) is then inherited structurally instead of re-implemented,
and the call site does not move.
Never raises — routing must not break when the skill subsystem is
absent (headless/mock boots).
"""
self._skill_relevance = None
self._skill_match_band = "none"
self._skill_match_class = ""
self._skill_meta_turn = ""
try:
from dodaios.skills import guards, match_eval, match_log
from dodaios.skills.autofire_policy import classify, may_capture
from dodaios.skills.skill_context import try_get_skill_context
ctx = try_get_skill_context()
if ctx is None:
# No registry to look anything up in — but a request ABOUT
# skills is still recognisable from the words alone, and the
# flag is what keeps the skill tools in charge of the turn.
from dodaios.skills.authoring_request import skill_meta_kind
self._skill_meta_turn = skill_meta_kind(user_text) or ""
return None
# Channel 0 (2026-08-12): the user NAMED a skill ("nutz den Skill
# X"). autofire_policy sanctions exactly this as the human path to
# any skill class, so it resolves deterministically and inherits
# trigger-grade rights — the prompt-only version of this promise
# converted to zero invocations in 14 live days. Still subject to
# the block-tier guard below via the shared decision flow.
from dodaios.skills.explicit_request import (
resolve_explicit_skill_request,
)
explicit = resolve_explicit_skill_request(user_text, ctx.registry)
if explicit is not None:
explicit_skill, explicit_decision = explicit
if self._skill_is_blocked(explicit_skill):
log.info(
"explicitly named skill %s is block-tier — not captured",
getattr(explicit_skill, "name", "?"),
)
self._record_skill_decision(
user_text, explicit_decision, lang=lang,
vetoed_by=guards.VETO_BLOCK_TIER, skill=explicit_skill,
)
return None
self._skill_match_band = explicit_decision.band
self._skill_match_class = classify(explicit_skill)
self._record_skill_decision(
user_text, explicit_decision, lang=lang,
skill=explicit_skill, fired=True,
)
return explicit_skill
# Channel 0.4 (2026-09-29): scheduled work for an agent ("a briefing
# every day at 8", "create a routine that …") is an agent routine.
# No skill captures it — neither the skill-creator (it wrote an
# inactive draft skill live) nor a briefing skill that would run
# once now instead of scheduling.
if "society-create-routine" in self._live_tool_names():
from dodaios.society.routine_intent import wants_agent_routine
if wants_agent_routine(user_text):
log.info("scheduled agent work — society-create-routine owns this turn")
return None
# Channel 0.5 (2026-08-18): the user asked to CREATE a skill
# ("erstell mir einen neuen Skill, der … mit YouTube Music …").
# Every service named inside that sentence is the CONTENT of the
# skill to be built, never a command to that service — yet the
# trigger channel below would hand the turn to whichever brand
# regex matches first (live 2026-08-18 17:51: plugin-youtube_music
# captured the authoring turn, the model burned the tool budget on
# `jarvisctl --help`, the user heard "Das hat gerade nicht
# geklappt"). Resolved BEFORE the trigger channel, deterministically:
# the skill-creator builtin captures with trigger-grade rights when
# it is active; when it is not, NO skill captures and the
# create-skill router tool owns the turn on its own.
from dodaios.skills.authoring_request import (
resolve_skill_authoring_request,
)
authoring = resolve_skill_authoring_request(user_text, ctx.registry)
if authoring is not None:
self._skill_meta_turn = authoring.kind
authoring_skill = authoring.skill
if authoring.kind == "lifecycle":
# "deaktiviere / lösch / zeig … den Skill X": the brand
# skill named inside must not run; the skill app-commands
# (skill-enable / skill-disable / skill-delete /
# skills-list) own the turn.
log.info(
"skill lifecycle request — no domain skill may capture "
"this turn; the skill app-commands own it"
)
self._record_skill_decision(
user_text, authoring.decision, lang=lang,
vetoed_by=guards.VETO_LIFECYCLE_REQUEST,
)
return None
if authoring_skill is None:
log.info(
"skill authoring request — no domain skill may capture "
"this turn; the create-skill tool owns it"
)
self._record_skill_decision(
user_text, authoring.decision, lang=lang,
vetoed_by=guards.VETO_AUTHORING_REQUEST,
)
return None
if self._skill_is_blocked(authoring_skill):
self._record_skill_decision(
user_text, authoring.decision, lang=lang,
vetoed_by=guards.VETO_BLOCK_TIER, skill=authoring_skill,
)
return None
log.info(
"skill authoring request → %s captures the turn "
"(services named inside the request are content, not commands)",
getattr(authoring_skill, "name", "?"),
)
self._skill_match_band = authoring.decision.band
self._skill_match_class = classify(authoring_skill)
self._record_skill_decision(
user_text, authoring.decision, lang=lang,
skill=authoring_skill, fired=True,
)
return authoring_skill
cfg = self._skills_config()
decision = match_eval.evaluate_match(
ctx.registry,
user_text,
lang=lang,
limit=max(3, int(getattr(cfg, "narrow_candidates", 3)) + 2),
use_relevance=bool(getattr(cfg, "relevance_enabled", True)),
fire_threshold=getattr(cfg, "fire_threshold", None),
hint_threshold=getattr(cfg, "hint_threshold", None),
)
if decision.top is None:
self._record_skill_decision(user_text, decision, lang=lang)
return None
try:
skill = ctx.registry.get(decision.top.skill_name)
except Exception: # noqa: BLE001
self._record_skill_decision(user_text, decision, lang=lang)
return None
# Unchanged guards, now shared by both channels. `evidence` is the
# RAW matched span, never a normalized token — the definitional
# guard re-escapes it against the original text, so a
# transliterated token would blind it on every umlaut word.
evidence = decision.top.evidence
if _is_definitional_question_about(user_text, evidence):
log.info(
"skill %s matched token %r but the turn is a definitional "
"question about it — not captured (answer it instead)",
getattr(skill, "name", "?"),
evidence,
)
self._record_skill_decision(
user_text, decision, lang=lang,
vetoed_by=guards.VETO_DEFINITIONAL, skill=skill,
)
return None
if self._skill_is_blocked(skill):
log.info(
"skill %s matched but is block-tier — turn not captured",
getattr(skill, "name", "?"),
)
self._record_skill_decision(
user_text, decision, lang=lang,
vetoed_by=guards.VETO_BLOCK_TIER, skill=skill,
)
return None
# Two music connectors, one domain: rematch BEFORE the
# disconnected veto. Live 2026-08-19 17:13: plugin-spotify won
# the trigger, the veto aborted capture, and the connected
# YouTube Music sibling never ran — the live model then
# announced a playlist with function_calls=0. A named service
# still wins; veto only if the winner is still disconnected.
skill = self._prefer_music_service(skill, user_text, ctx.registry)
if self._paired_plugin_disconnected(skill):
# Two connectors can serve one domain (Spotify and YouTube
# Music both answer "spiel Musik"). A paired skill whose plugin
# holds no usable credential must not capture the turn: it
# would steer the model at a tool that can only answer "not
# connected" while the connected sibling sits in the surface.
log.info(
"skill %s matched but its plugin is not connected — turn "
"not captured, routing stays with the live tool surface",
getattr(skill, "name", "?"),
)
self._record_skill_decision(
user_text, decision, lang=lang,
vetoed_by=guards.VETO_PLUGIN_NOT_CONNECTED, skill=skill,
)
return None
self._skill_match_band = decision.band
self._skill_match_class = classify(skill)
# A trigger hit keeps its historical unconditional capture: the
# author wrote that phrase precisely so it would fire, and changing
# that would be a behaviour regression, not a safety win.
if decision.source == match_eval.SOURCE_TRIGGER:
self._record_skill_decision(
user_text, decision, lang=lang, skill=skill, fired=True,
)
return skill
# --- relevance channel: capture is a privilege, not a default ---
self._skill_relevance = decision
allowed, veto = may_capture(
skill,
decision.band,
override=self._skill_autofire_override(skill),
min_band=str(getattr(cfg, "auto_fire_min_band", "fire")),
)
if not allowed:
log.info(
"relevance match %s (band=%s, class=%s) does not capture: %s",
getattr(skill, "name", "?"),
decision.band,
self._skill_match_class,
veto,
)
self._record_skill_decision(
user_text, decision, lang=lang, vetoed_by=veto, skill=skill,
)
return None
# Fallback mirrors the SkillsConfig default (False since
# 2026-08-12) so a duck-typed config cannot silently re-shadow.
if bool(getattr(cfg, "relevance_shadow", False)):
# Shadow mode: record what WOULD have happened, change nothing.
# The narrowed candidate hint still ships, so the model keeps
# the benefit while the maintainer reviews real decisions.
log.info(
"relevance match %s (band=%s) SHADOWED — would have captured "
"the turn; review GET /api/skills/match-log",
getattr(skill, "name", "?"),
decision.band,
)
self._record_skill_decision(
user_text, decision, lang=lang, skill=skill,
vetoed_by=guards.VETO_SHADOW_MODE, shadow=True,
)
return None
self._record_skill_decision(
user_text, decision, lang=lang, skill=skill, fired=True,
)
return skill
except Exception: # noqa: BLE001
return None
def _skill_autofire_override(self, skill: Any) -> str | None:
"""The user's persisted per-skill auto-fire choice, if any."""
try:
from dodaios.skills.prefs import load_autofire_prefs
return load_autofire_prefs().get(getattr(skill, "name", ""))
except Exception: # noqa: BLE001
return None
def _record_skill_decision(
self,
user_text: str,
decision: Any,
*,
lang: str = "auto",
vetoed_by: str = "",
skill: Any | None = None,
fired: bool = False,
shadow: bool = False,
) -> None:
"""Log the decision to the ring and the bus. Never raises, never blocks.
Emitted on EVERY evaluation, including "nothing matched" and every veto.
That completeness is the point: until now each veto was a ``log.info``
nobody reads, which is exactly why "my skill never fires" could not be
diagnosed.
"""
try:
from dodaios.skills import match_log
from dodaios.skills.autofire_policy import classify
autofire_class = classify(skill) if skill is not None else ""
match_log.record(
utterance=user_text,
decision=decision,
lang=lang,
vetoed_by=vetoed_by,
autofire_class=autofire_class,
fired=fired,
shadow=shadow,
)
except Exception: # noqa: BLE001
return
try:
from dodaios.skills.match_log import utterance_hash
from dodaios.skills.schema import SkillMatchEvaluated
top = getattr(decision, "top", None)
event = SkillMatchEvaluated(
source_layer="brain.manager",
utterance_hash=utterance_hash(user_text),
lang=lang,
source=str(getattr(decision, "source", "none")),
band=str(getattr(decision, "band", "none")),
winner=str(getattr(top, "skill_name", "") if top is not None else ""),
autofire_class=autofire_class,
vetoed_by=vetoed_by,
fired=fired,
shadow=shadow,
elapsed_us=int(getattr(decision, "elapsed_us", 0) or 0),
candidates=tuple(
(getattr(c, "skill_name", ""), round(float(getattr(c, "score", 0.0)), 4))
for c in (getattr(decision, "candidates", ()) or ())[:3]
),
)
loop = asyncio.get_running_loop()
loop.create_task(self._bus.publish(event))
except Exception: # noqa: BLE001
log.debug("SkillMatchEvaluated publish failed", exc_info=True)
def _previous_user_turn_text(self, *, use_history: bool) -> str:
"""Return the latest bounded user message from this task's history."""
override = _TURN_HISTORY_OVERRIDE.get()
history = (
tuple(override)
if override is not None
else tuple(self._history if use_history else ())
)
for message in reversed(history):
if getattr(message, "role", None) != "user":
continue
content = getattr(message, "content", "")
if isinstance(content, str) and content.strip():
return content.strip()[-1_200:]
return ""
def _recent_user_turn_texts(self, count: int, *, use_history: bool) -> tuple[str, ...]:
"""The last ``count`` user messages of this task's history, newest first."""
override = _TURN_HISTORY_OVERRIDE.get()
history = (
tuple(override)
if override is not None
else tuple(self._history if use_history else ())
)
found: list[str] = []
for message in reversed(history):
if len(found) >= count:
break
if getattr(message, "role", None) != "user":
continue
content = getattr(message, "content", "")
if isinstance(content, str) and content.strip():
found.append(content.strip()[-1_200:])
return tuple(found)
def _contextual_routing_state(
self, user_text: str, *, use_history: bool
) -> tuple[str, tuple[str, ...]]:
"""Return bounded context and live tools inherited by a follow-up.
The actual user message and tool arguments stay untouched. Only
deterministic skill/plugin/MCP selection sees the previous user turn,
and only when the shared planner identifies an explicit referential
follow-up. An unrelated request therefore cannot replay an old action.
"""
previous = self._previous_user_turn_text(use_history=use_history)
if not previous:
return user_text, ()
if not is_contextual_follow_up(user_text, (previous,)):
return user_text, ()
try:
plan = plan_turn(
user_text,
tool_names=tuple((getattr(self, "_tools", None) or {}).keys()),
context=(previous,),
)
except Exception: # noqa: BLE001 - context must never break a turn
return user_text, ()
live_tools = tuple(
name
for name in plan.required_capabilities
if name in (getattr(self, "_tools", None) or {})
)
contextual = (
f"Previous user request: {previous}\n"
f"Current referential follow-up: {user_text}"
)
return contextual, live_tools
@staticmethod
def _skill_is_blocked(skill: Any) -> bool:
"""True for risk_policy block-tier skills — they must never capture a
turn (mirrors the run-skill tool's block gate)."""
fm = getattr(skill, "frontmatter", None)
if fm is None:
return True
try:
return fm.risk_policy.default_tier == "block"
except Exception: # noqa: BLE001
return False
def _prefer_music_service(self, skill: Any, user_text: str, registry: Any) -> Any:
"""Swap a matched MUSIC skill for its sibling when the resolver says the
request belongs to the other service (see ``dodaios.core.music_service``).
Reads ``[music] preferred_service``. Never raises and never swaps to a
skill that is missing or whose plugin is not connected — a fault keeps
the match as it was."""
try:
from dodaios.core.music_constants import MUSIC_PLUGIN_IDS
from dodaios.core.music_service import resolve_music_service
fm = getattr(skill, "frontmatter", None)
plugin_id = str(getattr(fm, "plugin_id", "") or "").strip()
if plugin_id not in MUSIC_PLUGIN_IDS:
return skill
connected = [
pid for pid in MUSIC_PLUGIN_IDS if not self._plugin_disconnected(pid)
]
music_cfg = getattr(self._config, "music", None)
preferred = str(getattr(music_cfg, "preferred_service", "auto") or "auto")
target = resolve_music_service(
user_text, preferred=preferred, connected=connected, matched=plugin_id
)
if not target or target == plugin_id or target not in connected:
return skill
sibling = registry.get(f"plugin-{target}")
if sibling is None:
return skill
log.info(
"music request routed to %s instead of %s (preferred=%s, connected=%s)",
target, plugin_id, preferred, connected,
)
return sibling
except Exception as exc: # noqa: BLE001 — a routing nicety must never break a turn
log.debug("music preference routing skipped: %s", exc)
return skill
@classmethod
def _paired_plugin_disconnected(cls, skill: Any, *, store: Any | None = None) -> bool:
"""True when ``skill`` is paired to a CATALOG plugin whose credential is
absent or flagged for re-auth (see :meth:`_plugin_disconnected`)."""
fm = getattr(skill, "frontmatter", None)
plugin_id = str(getattr(fm, "plugin_id", "") or "").strip()
if not plugin_id:
return False
return cls._plugin_disconnected(plugin_id, store=store)
@staticmethod
def _plugin_disconnected(plugin_id: str, *, store: Any | None = None) -> bool:
"""True when catalog plugin ``plugin_id`` holds no usable credential.
Only catalog plugins are judged — every one of them authenticates, so
"no token" really means "not connected". A community skill naming an
unknown ``plugin_id`` is left alone: nothing here may veto a skill on
a guess. Any store or catalog fault answers False for the same reason
(a fault must never decide a turn). ``store`` is injectable for tests
(a fake with ``load``); the default is the real TokenStore.
The keyring read is synchronous and this sits on the turn path, so the
answer is remembered per plugin for a short while: one read per
plugin per :data:`_PAIRED_CONNECTION_TTL_S`, not one per matched turn.
A connect made inside that window merely routes without the skill's
guidance for a few seconds — the tool itself is callable at once."""
if not plugin_id:
return False
now = time.monotonic()
if store is None:
cached = _PAIRED_CONNECTION_CACHE.get(plugin_id)
if cached is not None and cached[0] > now:
return cached[1]
try:
from dodaios.marketplace.catalog_data import load_catalog
if load_catalog().by_id(plugin_id) is None:
return False
if store is None:
from dodaios.marketplace.token_store import TokenStore
store = TokenStore()
remember = True
else:
remember = False
tokens = store.load(plugin_id)
except Exception: # noqa: BLE001 — a store fault must not decide a turn
return False
disconnected = tokens is None or (
not getattr(tokens, "access", None) or bool(getattr(tokens, "needs_reauth", False))
)
if remember:
_PAIRED_CONNECTION_CACHE[plugin_id] = (now + _PAIRED_CONNECTION_TTL_S, disconnected)
return disconnected
def _render_skill_turn_hint(self) -> str | None:
"""Steering hint appended to the turn context on a skill-matched turn."""
skill = self._skill_turn_match
if skill is None:
return None
name = getattr(skill, "name", "")
return (
f"[Skill match] The user's request matches the installed skill "
f"`{name}` — call the run-skill tool with skill_name=\"{name}\" "
"now and follow the returned instructions, unless that is "
"clearly wrong."
)
def _skill_stand_downs_allowed(self) -> bool:
"""May this turn's matched skill suppress the other deterministic paths?
True for the historical case — an author's trigger, or an
instruction-only skill at FIRE — and False for anything the relevance
layer merely inferred about a tool-backed skill. In the False case the
skill still injects its instructions, but ``run-skill`` stays visible and
the local-action gate keeps precedence, which turns a wrong match from a
turn hijack into a suggestion the model can decline.
This distinction is the single most important safety property of the
relevance layer: capture is not all-or-nothing.
"""
skill = self._skill_turn_match
if skill is None:
return False
try:
from dodaios.skills.autofire_policy import stand_downs_allowed
from dodaios.skills.match_eval import BAND_FIRE, SOURCE_TRIGGER
except Exception: # noqa: BLE001
return True
# An author-written trigger keeps its unconditional historical rights.
if getattr(self, "_skill_relevance", None) is None:
return True
decision = self._skill_relevance
if getattr(decision, "source", "") == SOURCE_TRIGGER:
return True
return stand_downs_allowed(skill, getattr(decision, "band", BAND_FIRE))
def _drop_run_skill_when_inline_injected(self, tools: Any) -> Any:
"""Hide ``run-skill`` once a matched skill's instructions are already on
the turn context (``_skill_injected_inline``).
With the instructions inline (AD-S4) no tool call is needed; keeping
run-skill visible only tempts a weak model into a redundant, garbled
run-skill call — the gemini-fast ``<call:tool.run-skill ...>`` text leak
(forensic 2026-06-24). Dropping it makes skill execution provider- and
model-agnostic: every model just follows the injected instructions, no
tool call required. No-op when the skill was not inline-injected, or the
tool set is not a dict (intelligent-router lead path).
Kept ONLY while the turn's match is entitled to the full stand-down. A
relevance-inferred match on a tool-backed skill leaves ``run-skill``
visible on purpose: dropping it is what removes the model's ability to
signal "wrong skill", and the model needs that escape hatch exactly when
nobody stated an intent for this skill.
"""
if not getattr(self, "_skill_injected_inline", False):
return tools
if not isinstance(tools, dict):
return tools
if not self._skill_stand_downs_allowed():
return tools
return {k: v for k, v in tools.items() if k != "run-skill"}
#: Cap on the conditionally-injected instruction text for a NARROW match.
#: Bounded so one pathological skill body cannot flood a voice turn.
_NARROW_INJECTION_CHAR_CAP = 60_000
def _render_skill_candidate_hint(self, user_text: str = "") -> str | None:
"""Narrow the skill choice for a turn the matcher did NOT capture.
The router's real problem was never that skills are invisible — it is
that all the listed skills look equally plausible while ~26k tokens of
tool schemas compete for attention. This block puts the candidates that
actually scored right next to the user's message, where recency is
worth more than position in a long cached list.
2026-08-12 escalation ("skills never fire" rework): a name-and-blurb
hint measurably did nothing — 60 NARROW hints shipped over 14 live days
and the model called run-skill exactly zero times. The fast router
model does not convert a suggestion into a tool round trip. So for a
CLEAR top candidate that cannot dispatch anything, the hint now carries
the skill's full rendered instructions in a conditional frame — the
model only has to decide "is this what the user meant", not decide AND
remember to call a tool (mirrors Claude Code loading a skill's whole
instruction body once selected). The decision explicitly stays with
the model: a wrong candidate is ignored, never executed, so a skill is
still only ever used when it serves the request.
A dispatching-class candidate (mission execution, block tier, macro
body) NEVER gets its instructions inlined off an inferred match — its
body is a process-start directive, and no matcher may authorize that
(same line ``autofire_policy.may_capture`` draws). It keeps the plain
named hint, where the model must consciously call ``run-skill``.
Deliberately rides the PER-TURN context and never the cached system
prefix: rewriting that prefix per turn would break prompt caching on
every single turn, which costs far more than it could ever save.
Returns ``None`` on a captured turn, a dead scorer, or a weak ranking —
so the common case adds nothing at all.
"""
decision = getattr(self, "_skill_relevance", None)
if decision is None or self._skill_turn_match is not None:
return None
candidates = getattr(decision, "candidates", ()) or ()
if not candidates:
return None
cfg = self._skills_config()
limit = max(1, int(getattr(cfg, "narrow_candidates", 3)))
try:
from dodaios.skills.match_eval import BAND_NONE
from dodaios.skills.skill_context import try_get_skill_context
ctx = try_get_skill_context()
if ctx is None:
return None
registry = ctx.registry
except Exception: # noqa: BLE001
return None
# (candidate, skill, blurb) triples for every scoring candidate.
scored: list[tuple[Any, Any, str]] = []
for candidate in candidates:
if len(scored) >= limit:
break
if getattr(candidate, "band", BAND_NONE) == BAND_NONE:
continue
name = getattr(candidate, "skill_name", "")
try:
skill = registry.get(name)
except Exception: # noqa: BLE001
continue
frontmatter = getattr(skill, "frontmatter", None)
if frontmatter is None:
continue
description = (getattr(frontmatter, "description", "") or "").strip()
when_to_use = (getattr(frontmatter, "when_to_use", "") or "").strip()
blurb = f"{description} {when_to_use}".strip()[:400]
scored.append((candidate, skill, blurb))
if not scored:
return None
conditional = self._render_conditional_narrow_injection(
scored, ctx, user_text, decision
)
if conditional is not None:
return conditional
# Shared with the realtime session's own candidate hint — one wording,
# so the suggestion does not change shape depending on which engine is
# answering (dodaios/skills/prompt_injection.py).
from dodaios.skills.prompt_injection import render_skill_candidate_hint
return render_skill_candidate_hint(
[(str(getattr(s, "name", "")), b) for _, s, b in scored]
) or None
def _render_conditional_narrow_injection(
self,
scored: list[tuple[Any, Any, str]],
ctx: Any,
user_text: str,
decision: Any,
) -> str | None:
"""Full instructions for a clear, non-dispatching top candidate.
Returns ``None`` whenever the escalation conditions do not hold, so the
caller falls back to the plain named hint. Never raises.
"""
try:
from dodaios.skills.autofire_policy import CLASS_DISPATCHING, classify
from dodaios.skills.relevance import MARGIN_ABS
top_candidate, top_skill, top_blurb = scored[0]
if classify(top_skill) == CLASS_DISPATCHING:
return None
# Clear winner only: two near-tied candidates are genuine ambiguity
# and stay a short list the model disambiguates from.
margin = float(getattr(decision, "margin", 0.0) or 0.0)
if len(scored) > 1 and margin < MARGIN_ABS:
return None
instructions = ctx.runner.render_instructions(
top_skill,
args={
"content": "",
"utterance": user_text,
"_trigger": "relevance-hint",
},
)
except Exception: # noqa: BLE001
log.debug("conditional narrow injection failed", exc_info=True)
return None
if not instructions or not str(instructions).strip():
return None
text = str(instructions).strip()
if len(text) > self._NARROW_INJECTION_CHAR_CAP:
text = text[: self._NARROW_INJECTION_CHAR_CAP - 1] + "…"
name = getattr(top_skill, "name", "")
runner_up_lines = [
f"- `{getattr(s, 'name', '')}` — {b}" for _, s, b in scored[1:]
]
tail = (
(
"\nLower-scored alternatives (ranked suggestions, not a "
"verdict):\n" + "\n".join(runner_up_lines) + "\n"
"If one of those fits the request better, call the `run-skill` "
"tool with that name instead."
)
if runner_up_lines
else ""
)
return (
f"[Likely skill match — decide, then act] The user's request "
f"scored closest to the installed skill `{name}` — {top_blurb}\n"
"Judge from the user's ACTUAL words: if they are asking for what "
"this skill does — even loosely, in wording that is not the "
"trigger phrase — follow the instructions below NOW with your "
"available tools instead of answering freely, and never read them "
"aloud. If the request is genuinely about something else, ignore "
"this entire block and answer normally; do not mention the skill. "
"A skill is only ever used when it truly serves the request.\n"
f"--- skill instructions (`{name}`) ---\n"
f"{text}\n"
f"--- end of skill instructions ---{tail}"
)
def _render_skill_turn_injection(self, user_text: str) -> str | None:
"""Render the matched skill's instructions for direct turn injection.
AD-S4: a matched turn short-circuits the run-skill round trip — the
rendered instructions ride on the turn context, so the model executes
them in this very turn (guaranteed invocation). Publishes
``SkillInvoked``. Falls back to the steering hint when rendering
fails (the model can still call run-skill itself).
Sets ``_skill_injected_inline`` True ONLY when the real instructions
were injected (not the hint fallback) so the caller can hide run-skill
for the turn (provider-agnostic execution, no tool-call leak).
"""
self._skill_injected_inline = False
skill = self._skill_turn_match
if skill is None:
return None
name = getattr(skill, "name", "")
try:
from dodaios.skills.skill_context import try_get_skill_context
ctx = try_get_skill_context()
if ctx is None:
return self._render_skill_turn_hint()
instructions = ctx.runner.render_instructions(
skill,
args={
"content": self._skill_turn_content,
"utterance": user_text,
"_trigger": self._skill_turn_source,
},
)
except Exception: # noqa: BLE001
log.warning(
"skill instruction render failed for %s — hint fallback", name,
exc_info=True,
)
return self._render_skill_turn_hint()
self._publish_skill_invoked(name, source=self._skill_turn_source)
# The real instructions are now inline — the model needs no run-skill
# call; the caller drops that tool so a weak model cannot leak a garbled
# tool call (provider-agnostic skill execution).
self._skill_injected_inline = True
return (
f"[Skill instructions for `{name}` — the user's request matched "
"this installed skill]\n"
f"{instructions}\n\n"
"Follow these skill instructions now, step by step, using your "
"available tools; skip a step gracefully when its integration is "
"unavailable. Answer the user with the RESULT — never read the "
"instructions aloud. Report a step as done only after the tool "
"call that performs it has returned a successful result; if a "
"step cannot run, say plainly that it did not happen."
)
def _publish_skill_invoked(self, skill_name: str, *, source: str) -> None:
"""Fire-and-forget SkillInvoked publish (AD-S6 observability)."""
try:
from dodaios.skills.schema import SkillInvoked
event = SkillInvoked(
source_layer="brain.manager",
skill_name=skill_name,
source=source,
)
loop = asyncio.get_running_loop()
loop.create_task(self._bus.publish(event))
except Exception: # noqa: BLE001
log.debug("SkillInvoked publish failed", exc_info=True)
async def _maybe_dispatch_skill_mission(
self, user_text: str, *, trace_id: UUID | None = None
) -> str | None:
"""Dispatch an ``execution: mission`` skill as a worker brief (AD-S5).
Returns the optimistic ACK string when the mission was dispatched, or
``None`` for inline skills / when dispatch is impossible (the caller
then keeps the inline-injection path — AD-OE6: no silent drop).
"""
skill = self._skill_turn_match
if skill is None:
return None
fm = getattr(skill, "frontmatter", None)
if fm is None or getattr(fm, "execution", "inline") != "mission":
return None
tool = self._tools.get("spawn_worker")
if tool is None or self._tool_executor is None:
log.warning(
"mission skill %s matched but spawn_worker unavailable — "
"falling back to inline execution",
getattr(skill, "name", "?"),
)
return None
name = getattr(skill, "name", "")
try:
from dodaios.skills.skill_context import try_get_skill_context
ctx = try_get_skill_context()
if ctx is None:
return None
instructions = ctx.runner.render_instructions(
skill,
args={
"content": self._skill_turn_content,
"utterance": user_text,
"_trigger": self._skill_turn_source,
},
)
except Exception: # noqa: BLE001
log.warning(
"mission skill %s could not render — inline fallback", name,
exc_info=True,
)
return None
args = {
"utterance": (
f"Execute the installed skill '{name}' as a background "
f"mission. The user said: {user_text!r}\n\n"
f"Skill instructions:\n{instructions}"
),
"context_hints": [
f"Dispatched deterministically from the skill system "
f"(execution: mission, skill: {name})."
],
"action": "",
"target": "",
}
log.info("Mission skill dispatch: %s (%r)", name, user_text[:120])
try:
result = await self._tool_executor.execute(
tool,
args,
user_utterance=user_text,
trace_id=trace_id or uuid4(),
)
except Exception: # noqa: BLE001
log.warning("mission skill dispatch failed — inline fallback", exc_info=True)
return None
if not result.success:
log.warning(
"mission skill dispatch unsuccessful (%s) — inline fallback",
result.error,
)
return None
self._publish_skill_invoked(name, source=self._skill_turn_source)
return str(result.output or "")
def _smalltalk_tool_override(self) -> dict[str, Tool]:
"""Tool set visible on a smalltalk turn: everything but the spawn vehicles.
The 2026-05-01 incident this gate exists for was ONE tool class. The
user said "es geht ab", the allowlist did not match, the LLM had the
full surface and hallucinated a Jarvis-Agent spawn — Jarvis then claimed
to have started tests it never started. Hiding ``spawn_worker`` /
``multi_spawn`` removes exactly that, and an unwanted background agent
is the one tool whose wrong call is expensive and surprising.
Hiding EVERYTHING else was the bug on the other side (2026-08-17
review): smalltalk here is a substring allowlist, so a real request
that merely reads as chit-chat arrived at the model with no action tool
at all and could only be talked about. A tool the model declines to call
is free; a tool it cannot see is the failure users report. The genuinely
conversational turns still lose ``computer_use`` and the write/record
tools further down the chain — see
``_hide_action_tools_on_signalless_turn``.
A tool the deterministic layer mandated this turn is never hidden
("was steht heute an" can classify as smalltalk — AD-CLI8), and on a
skill-matched turn (AD-S3) ``run-skill`` stays visible so a
greeting-style trigger ("guten Morgen" → morning-routine) still fires.
"""
hidden = _SMALLTALK_HIDDEN_TOOL_NAMES
keep = {self._evidence_required_tool} if self._evidence_required_tool else set()
if self._skill_turn_match is not None:
keep.add("run-skill")
return {
n: t for n, t in self._tools.items()
if n not in hidden or n in keep
}
def _image_turn_tool_override(self) -> dict[str, Tool]:
"""Tool surface for a turn that carries a CAPTURED SCREEN image.
Historically hard ``{}`` — the reasoning being that pixels answer the
turn and that emptying the surface is what keeps Screen Context and
Computer-Use from both running for one utterance (docs/screen-context.md
§3.1a, maintainer mandate 2026-08-02). The first exception was a WRITE
mandate (code-review finding 2026-08-08): "erstell einen Ordner hier auf
dem Desktop" matches the screen-intent phrase "hier auf dem", the
explicit screen-context path attaches a screenshot, and a zeroed surface
blinded the very run_shell call the local-outcome mandate requires.
2026-08-17: the hide is now a narrow deny-list, because the boundary it
was standing in for is enforced where it actually belongs. A turn can
carry a screen image and still ask for an action — the image may come
from an earlier utterance, from an explicit attach, or from a mixed
request — and an emptied surface left the model describing a picture
with no way to do the thing that was asked. ``computer_use`` therefore
stays: every call runs through
``cu_gate.llm_computer_use_allowed`` first, which refuses a look request
even inside a live desktop episode, so the two paths still cannot both
run for one utterance. That gate reads the USER's utterance, never the
model's reasoning, so untrusted on-screen text cannot unlock it either.
What stays hidden is what injected screen text could otherwise start
unattended: the spawn vehicles and the deterministic record writes
(``_SCREEN_TURN_HIDDEN_TOOL_NAMES``) — minus any tool the deterministic
layer mandated this turn.
"""
keep = self._evidence_required_tool or ""
return {
n: t
for n, t in self._tools.items()
if (n not in _SCREEN_TURN_HIDDEN_TOOL_NAMES or n == keep)
# MCP tools are namespaced ``server/tool``. Their JSON-Schema
# unions brick Gemini (live 2026-08-31: Linear
# ``issue_fields.value.type = [string, number, boolean]``) and
# they bloat a look-at-screen prompt for every other provider.
# A mandated tool still survives.
and ("/" not in n or n == keep)
}
def _gate_screen_tool(
self,
tools: dict[str, Tool],
*,
user_text: str,
has_image: bool,
pointing_turn: bool = False,
) -> dict[str, Tool]:
"""Drop the on-demand ``screenshot`` tool on a turn that is not about the screen.
The validation the screen-narration bug needed (live 2026-06-14): a
small-talk / knowledge / cut-off fragment with no screen reference
("Kannst du mir sagen, was genau...") must not be able to invoke the
screenshot function and then narrate the screen. Confirm the utterance
is actually screen-related BEFORE offering the tool.
The tool stays available when an image is already attached, on a pointer
turn (which is by definition about the screen), or when the utterance
carries a visual-reference marker — the same ``should_attach_screenshot``
signal that gates passive image attach, so the marker-bearing screen
questions of 2026-05-31 ("lies mir vor was oben links steht") keep it.
Tradeoff: a genuinely screen-related question that matches no marker
loses the auto-screenshot fallback; the prompt then steers the brain to
say it cannot see the screen or ask, rather than fabricate one.
"""
if not isinstance(tools, dict) or "screenshot" not in tools:
return tools
if pointing_turn or has_image:
return tools
from dodaios.brain.vision_gate import should_attach_screenshot
if should_attach_screenshot(user_text):
return tools
return {n: t for n, t in tools.items() if n != "screenshot"}
@staticmethod
def _hide_screenshot_for_blind_brain(
tools: dict[str, Tool],
brain: Any,
*,
prov_name: str = "",
model: str | None = "",
) -> dict[str, Tool]:
"""Drop the ``screenshot`` tool when the answering brain has no vision.
A blind model that calls the tool is a guaranteed dead end: the
capture succeeds, its own protocol layer drops the image ("Provider
without vision support"), and the model honestly tells the user the
picture came back unusable (live 2026-08-06 20:52, grok-4.5 tool
loop). Gated on the runtime capability, never the provider name
(AP-21); the chain-level vision skip only covers images attached
BEFORE the turn, not ones a mid-loop tool call produces.
"""
if not isinstance(tools, dict) or "screenshot" not in tools:
return tools
if getattr(brain, "supports_vision", False) is True:
return tools
log.info(
"Hiding the screenshot tool from %s(%s): the model cannot "
"inspect images, so a capture could only dead-end.",
prov_name,
model,
)
return {n: t for n, t in tools.items() if n != "screenshot"}
def _shortlist_tools(
self,
tools: dict[str, Tool],
brain: Any,
*,
system_prompt: str,
history: Sequence[BrainMessage] | None,
own_tools: Iterable[str] = (),
direct_tools: frozenset[str] | None = None,
) -> tuple[dict[str, Tool], frozenset[str]]:
"""Decide which of the turn's tools the model is SHOWN.
Returns ``(tools, deferred names)``. Every tool stays in the dict and
stays callable; the deferred ones are not put in front of the model
and are reached through ``find_tools``
(``dodaios/brain/tool_shortlist.py``). With nothing deferred the dict comes back
untouched, which is every turn of a hosted model with room to spare.
Three reasons to defer, each on its own evidence:
* **The window.** Live 2026-08-27: a local 32k model, 221 tools, a
plain "Hallo" went out as 67,852 tokens and the server refused it.
The first answer dropped what did not fit, largest first — which
removed the richly described tools (a save tool with a real schema)
before a parameterless list tool, and a dropped tool was gone for
the turn. Now the everyday tools are shown first and the rest is
deferred, not lost.
* **A small model.** A window of ``_SMALL_WINDOW_TOKENS`` or less is
a small model, and a small model picks badly from a long list even
when the list fits: it is shown ``_SMALL_MODEL_DIRECT_TOOLS`` at
most. Gated on the declared window, never a provider name (AP-21).
* **The caller's role.** ``direct_tools`` names the tools an agent
works with; it is shown those and its own hands, on any provider.
The provider's own tool-count cap (``max_tools``) defers the same way.
The tool a deterministic gate mandated this turn, ``run-skill`` on a
skill match and the caller's own hands are always shown.
"""
nothing: frozenset[str] = frozenset()
# A real tool of that name leaves no room for the finder: show
# everything, as before.
if not isinstance(tools, dict) or not tools or FIND_TOOLS_NAME in tools:
return tools, nothing
try:
window = int(getattr(brain, "context_window", 0) or 0)
except (TypeError, ValueError):
# A malformed context window means 'unknown'; no trimming then.
window = 0
try:
max_tools = int(getattr(brain, "max_tools", 0) or 0)
except (TypeError, ValueError):
# A malformed tool limit means 'unknown'; no trimming then.
max_tools = 0
if window <= 0 and max_tools <= 0 and direct_tools is None:
return tools, nothing
keep: set[str] = {name for name in own_tools if name in tools}
mandated = getattr(self, "_evidence_required_tool", None)
if mandated:
keep.add(str(mandated))
if getattr(self, "_skill_turn_match", None) is not None:
keep.add("run-skill")
used = (
_approx_tokens(system_prompt)
+ _approx_history_tokens(history)
+ _CONTEXT_FIT_RESERVE_TOKENS
)
budget = max(window - used, 0) if window > 0 else None
# One slot of a provider's count cap is held for ``find_tools``.
limits = [max(max_tools - 1, 1)] if max_tools > 0 else []
if 0 < window <= _SMALL_WINDOW_TOKENS:
limits.append(_SMALL_MODEL_DIRECT_TOOLS + len(keep))
max_direct = min(limits) if limits else 0
only = None if direct_tools is None else {*direct_tools, *ROLE_BASE}
plan = plan_surface(
tools, keep=keep, budget_tokens=budget, max_direct=max_direct, only=only
)
if not plan.deferred:
return tools, nothing
reveal_tokens: int | None = None
if budget is not None:
# The finder and what it reveals need room of their own. When the
# window is what forced the split, hold that room back and choose
# again; otherwise the first lookup overflows the window that the
# shown tools already fill to the brim.
spent = sum(tool_tokens(name, tool) for name, tool in plan.direct.items())
headroom = budget - spent
if headroom < _REVEAL_RESERVE_TOKENS:
reveal_tokens = min(_REVEAL_RESERVE_TOKENS, budget // 3)
plan = plan_surface(
tools,
keep=keep,
budget_tokens=max(budget - reveal_tokens - _FINDER_TOKENS, 0),
max_direct=max_direct,
only=only,
)
else:
reveal_tokens = headroom - _FINDER_TOKENS
surface: dict[str, Tool] = dict(plan.direct)
surface[FIND_TOOLS_NAME] = cast(
Tool, FindToolsTool(plan.deferred, reveal_tokens=reveal_tokens)
)
surface.update(plan.deferred)
log.info(
"Tool surface for %s: %d of %d tools shown, %d behind find_tools "
"(window %s, prompt+history ~%d tokens, count limit %s). First deferred: %s",
getattr(brain, "name", type(brain).__name__),
len(plan.direct),
len(tools),
len(plan.deferred),
window or "undeclared",
used,
min(limits) if limits else "none",
", ".join(list(plan.deferred)[:5]),
)
return surface, frozenset(plan.deferred)
def _hide_spawn_on_knowledge_question(
self, tools: dict[str, Tool], user_text: str
) -> dict[str, Tool]:
"""Remove the spawn tools from a PLAIN knowledge/factual question's tool
surface so the router-LLM cannot reflexively delegate an answerable
question to a background worker.
Forensic 2026-06-27 (voice session 08:35): "Welche Unternehmen haben so
viel Speicherplatz?" — a pure factual question — was answered by the LLM
*choosing* ``spawn_worker`` ("ich ziehe einen Experten hinzu"), against
the router prompt's own rule ("NIEMALS spawn_worker fuer eine Frage, die
du mit 1-2 Suchanfragen beantworten kannst"). The deterministic
force-spawn gate correctly stands down on such a turn, but it only
*forces* spawns — it never *constrains* the LLM's own spawn reflex. This
mirrors the smalltalk tool-hide (2026-05-01): the surest way to stop a
wrong tool call is to not offer the tool. ``search_web`` / plugin reads /
``computer_use`` stay visible so the question is still answerable inline.
Narrow on purpose (no collateral spawn loss): fires ONLY on an actual
question (interrogative opener or "?") that carries NEITHER action intent
NOR an artifact-build request, and NEVER when the user explicitly named a
heavy-work vehicle ("Subagent" / "deep dive"). Pure regex + the existing
deterministic detectors (AP-11 safe, provider-agnostic). Defensive: any
fault returns the tools unchanged so a gate bug can never blind the brain.
"""
if not isinstance(tools, dict):
return tools
try:
t = (user_text or "").strip()
if not _is_plain_knowledge_question(t):
return tools
# User explicitly named the vehicle → respect it, never hide (AD-S9).
if self._is_explicit_heavy_request(t):
return tools
# A real desktop/action turn or an artifact-build request still needs
# the spawn tools — only a pure ANSWER question loses them.
if self._turn_has_action_intent(t) or self._research_wants_artifact(t):
return tools
return {n: tool for n, tool in tools.items() if n not in _SPAWN_TOOL_NAMES}
except Exception: # noqa: BLE001 — gate must never blind the brain
log.debug("knowledge-question spawn-hide gate failed", exc_info=True)
return tools
def _hide_agentic_ide_tools_without_workspace(
self, tools: dict[str, Tool]
) -> dict[str, Tool]:
"""Drop the pane-scoped Agentic-IDE tools when NO workspace is open.
A capability gate, not a keyword guess: without an open workspace
those tools can only fail, so hiding them loses nothing — and their
schemas are ~10 KB of input re-sent on every tool-loop iteration.
``agentic-ide-status`` and ``agentic-ide-resume`` always stay (see
_AGENTIC_IDE_WORKSPACE_TOOL_NAMES). Defensive: any fault returns
the tools unchanged so a gate bug can never blind the brain.
"""
if not isinstance(tools, dict):
return tools
try:
if not any(n in tools for n in _AGENTIC_IDE_WORKSPACE_TOOL_NAMES):
return tools
from dodaios.agentic_ide.session import get_registry as _ide_registry
if _ide_registry().session is not None:
return tools
return {
n: tool
for n, tool in tools.items()
if n not in _AGENTIC_IDE_WORKSPACE_TOOL_NAMES
}
except Exception: # noqa: BLE001 — gate must never blind the brain
log.debug("agentic-ide workspace tool gate failed", exc_info=True)
return tools
def _hide_artifact_tool_without_request(
self, tools: dict[str, Tool], user_text: str
) -> dict[str, Tool]:
"""Drop ``create_artifact`` from every turn that did not ask for one.
Maintainer mandate (2026-08-11, renewed 2026-08-23 for artifacts): a
page or picture is built when the user says they want to see
something — never because the assistant judged an answer would look
nicer as a dashboard. Prompt wording alone does not hold that line; a
tool the model cannot see is a line it cannot cross, so the
enforcement is structural. It also keeps a background mission on the
strongest model from being started on a whim.
The gate is ``dodaios.brain.artifact_gate.wants_artifact`` — pure regex,
no model in the detection path (AP-11). Defensive: any fault returns
the tools unchanged, so a gate bug can never blind the brain.
"""
if not isinstance(tools, dict) or _ARTIFACT_TOOL_NAME not in tools:
return tools
try:
from dodaios.brain.artifact_gate import wants_artifact # noqa: PLC0415
if wants_artifact(user_text or ""):
return tools
return {n: tool for n, tool in tools.items() if n != _ARTIFACT_TOOL_NAME}
except Exception: # noqa: BLE001 — gate must never blind the brain
log.debug("artifact request gate failed", exc_info=True)
return tools
@staticmethod
def _desktop_episode_is_live() -> bool:
"""True while a Computer-Use mission is running or has just ended.
The one honest signal that the conversation context still holds a
desktop plan a signalless turn could INHERIT: every launch route
registers its mission (voice fast path, LLM tool, REST, scheduled). It
is deliberately the same registry and the same window
``dodaios.brain.cu_gate`` consults for the mirror-image decision, so the
two readings of "are we in a desktop episode" cannot drift apart.
A failed probe answers "no episode": the default must be the full tool
surface, never a blinded one.
"""
try:
from dodaios.brain.cu_gate import FOLLOW_UP_WINDOW_S # noqa: PLC0415
from dodaios.harness.cu_run_registry import ( # noqa: PLC0415
has_recent_run,
)
return bool(has_recent_run(FOLLOW_UP_WINDOW_S))
except Exception: # noqa: BLE001 — never blind the brain on a probe
log.debug("desktop-episode probe failed", exc_info=True)
return False
def _turn_reads_as_conversation(self, user_text: str) -> bool:
"""True when the turn's own SHAPE says it asks for no record to be written.
Smalltalk or a plain question — the shapes the 2026-06-30 deep-dive
found exposed to the write/record tools ("does my budget fit?"). Each
detector is guarded on its own: ``_is_smalltalk`` needs the compiled
routing patterns, and a manager built without them must degrade to
"not obviously conversational" rather than take the whole gate down.
"""
try:
if self._is_smalltalk(user_text):
return True
except Exception: # noqa: BLE001 — pattern cache unavailable
log.debug("smalltalk probe failed in the signalless gate", exc_info=True)
return _is_plain_knowledge_question(user_text)
def _hide_action_tools_on_signalless_turn(
self, tools: dict[str, Tool], user_text: str
) -> dict[str, Tool]:
"""Withhold the consequential tools a turn could only have INHERITED.
Two distinct risks with two distinct pieces of evidence — and "the
action regex did not fire" is neither of them. The forensics:
1. **Inheritance (2026-06-27).** "Was geht ab?" → STT "Lask it up!" [en]
conf 0.509 → the router-LLM, reading a 30k-token context full of the
prior "open Discord, bridge-mine channel" command, re-ran that exact
computer_use plan on a turn that asked for nothing. That risk needs
something to inherit: a desktop episode that is live or just ended
(``_desktop_episode_is_live``). Cold, there is no prior plan in the
context to re-run.
2. **Write reflex (deep-dive 2026-06-30).** A "does my budget fit?" turn
carried google_calendar / contact-upsert / wiki-ingest /
update_profile in its surface. The evidence there is the turn's own
shape: smalltalk or a plain question asks for no record to be written
(``_turn_reads_as_conversation``).
What changed, and why (2026-08-17 review): the previous version hid both
sets from EVERY turn that missed ``is_open_app_intent`` /
``_looks_like_pc_control`` / the capability registry. That regex knows
"klick" and "Bildschirm"; it does not know "spiel Musik", "ruf Anna an"
or "trag das in meinen Kalender ein" — so those turns reached the model
with no vehicle at all and could only be talked about. Absence of a
keyword is not evidence of absence of intent. A tool the model declines
to call is free; a tool it cannot see is the bug users report.
Both protections above still fire, on their own evidence. A genuine
action signal (action-intent, artifact-build request, named spawn
vehicle, request framing) short-circuits the gate, the read-only ``screenshot``
tool is never hidden, and a tool the deterministic layer mandated this
turn is never stripped (AD-CLI8). Pure regex + registry lookups, no
model in the path (AP-11 safe). Any fault returns the tools unchanged so
a gate bug can never blind the brain.
"""
if not isinstance(tools, dict):
return tools
try:
t = (user_text or "").strip()
if not t:
return tools
# Any genuine ACTION signal keeps the consequential tools: an action
# intent (open-app / PC-control / names the screen surface / registry
# intent), an artifact-build request, an explicitly named spawn
# vehicle — or REQUEST FRAMING. The last one is the same signal
# ``_is_smalltalk`` already trusts to call a turn a command rather
# than chit-chat: "Kannst du Anna anrufen?" is question-SHAPED and
# would otherwise lose call-contact to the write-reflex half below,
# and "kannst du das nochmal machen?" is the corrective follow-up
# cu_gate's episode window exists to keep alive.
if (
self._turn_has_action_intent(t)
or self._research_wants_artifact(t)
or self._is_explicit_heavy_request(t)
or _ACTION_REQUEST_RE.search(t)
):
return tools
hidden: set[str] = set()
if self._desktop_episode_is_live():
hidden |= _INHERITABLE_ACTION_TOOL_NAMES
if self._turn_reads_as_conversation(t):
hidden |= _DETERMINISTIC_WRITE_TOOL_NAMES
if not hidden:
return tools
# NEVER strip a tool the deterministic layer already mandated this
# turn (a say-do write via resolve_save_mandate, or a calendar/email
# READ via the evidence gate), or those features regress (AD-CLI8).
mandated = getattr(self, "_evidence_required_tool", "") or ""
return {
n: tool
for n, tool in tools.items()
if n not in hidden or n == mandated
}
except Exception: # noqa: BLE001 — gate must never blind the brain
log.debug("signalless-turn action-hide gate failed", exc_info=True)
return tools
def _hide_spawn_when_plugin_tool_handles_turn(
self, tools: dict[str, Tool], user_text: str
) -> dict[str, Tool]:
"""Hide the spawn vehicles when a connected plugin tool's usage-card
keywords match the turn, so the router-LLM uses that (router-only) plugin
tool DIRECTLY instead of delegating to a worker that cannot reach it.
Forensic 2026-06-27 (voice session 17:44): "Schau mal nach, was in meinem
Google Calendar am 29. fuer Termine sind" — the router spawned a worker
("umfangreicheres Stueck Arbeit") which has NO google_calendar tool
(plugin tools are router-tier only, AP-5/AP-14) and answered "kann ich
nicht". The deterministic force-spawn gate stands down on such a turn, but
it never constrains the LLM's own spawn reflex. A plugin-tool turn must
never be delegated. Mirrors ``_hide_spawn_on_knowledge_question``: the
surest way to stop a wrong spawn is to not offer the spawn tool. The
matched plugin tool + ``search_web`` + reads stay visible, so the turn is
still answerable inline.
Narrow on purpose: stands down when the user explicitly named a heavy-work
vehicle ("Subagent" / "deep dive") or asked to BUILD an artifact
(file / report), both of which legitimately spawn. Pure regex + the
usage-card keyword gate (AP-9 cached / AP-11 safe, provider-agnostic).
Defensive: any fault returns the tools unchanged so a gate bug can never
blind the brain.
"""
if not isinstance(tools, dict):
return tools
try:
t = (user_text or "").strip()
if not t:
return tools
# An explicit heavy-work vehicle or an artifact-build request still
# legitimately spawns — never hide the spawn vehicles there.
if self._is_explicit_heavy_request(t) or self._research_wants_artifact(t):
return tools
from dodaios.marketplace.usage_cards.loader import load_usage_card
# A tool in the surface whose usage card matches => this is a
# plugin-tool turn. Native tools use their name as the card id
# (google_calendar); namespaced plugin tools use the id before "/".
for name in tools:
pid = name.partition("/")[0]
card = load_usage_card(pid)
if card is not None and card.matches(t):
return {
n: tool
for n, tool in tools.items()
if n not in _SPAWN_TOOL_NAMES
}
return tools
except Exception: # noqa: BLE001 — gate must never blind the brain
log.debug("plugin-tool spawn-hide gate failed", exc_info=True)
return tools
def _hide_run_skill_on_pc_control_turn(
self, tools: dict[str, Tool], user_text: str
) -> dict[str, Tool]:
"""Hide ``run-skill`` when the turn explicitly asks to operate THIS
computer's screen (open an app/terminal, click, type into a program),
so ``computer_use`` stays authoritative for the named desktop vehicle.
Forensic 2026-07-02 (voice session 20:28, turn 1): "ein Terminal
öffnen, Cloud-Code öffnen, … und für mich ein Prompt geben …
kompletten Deep-Dive machen … ob es irgendwelche Bugs gibt" — an
unambiguous desktop request (open a terminal, open Claude Code, type a
prompt into it). The SKILLS-FIRST router rule ("when in doubt, call
the skill") let the semantically-similar ``cloud-debug`` skill hijack
the turn: run-skill returned its mission directive, the model followed
neither it nor computer_use and spoke the dictated capability refusal
("mir fehlt dafür das passende Werkzeug"). The vehicle the user NAMED
(the desktop) must outrank a loose skill CONTENT match — and the
surest way to stop a wrong tool call is to not offer the tool (mirrors
the knowledge-question / plugin-tool hides above).
Narrow on purpose: fires ONLY when a deterministic pc-control /
open-app signal is present AND ``computer_use`` is actually in the
surface (a host without the CU harness keeps run-skill so the turn
stays handleable). Stands down when the user literally says "skill" —
an explicit skill request is its own vehicle. The deterministic
trigger-match inline path (AD-S4) is untouched: a skill whose OWN
trigger phrase matched rides the turn context before this gate and
needs no run-skill call. Pure regex + existing detectors (AP-11 safe,
provider-agnostic). Defensive: any fault returns the tools unchanged
so a gate bug can never blind the brain.
"""
if not isinstance(tools, dict):
return tools
try:
t = (user_text or "").strip()
if not t or "run-skill" not in tools or "computer_use" not in tools:
return tools
if not (is_open_app_intent(t) or _looks_like_pc_control(t)):
return tools
# User literally named a skill → that request wins, keep run-skill.
if _EXPLICIT_SKILL_REQUEST_RE.search(t):
return tools
return {n: tool for n, tool in tools.items() if n != "run-skill"}
except Exception: # noqa: BLE001 — gate must never blind the brain
log.debug("pc-control run-skill-hide gate failed", exc_info=True)
return tools
def _apply_plugin_relevance(
self, user_text: str, tools: dict[str, Tool]
) -> dict[str, Tool]:
"""Drop plugin tools (namespaced ``<id>/<tool>``) irrelevant to this turn.
Keyword-only, no LLM / no IO (AP-9). Native (non-namespaced) tools are
untouched. Defensive: any failure returns the unfiltered dict so a gate
bug can never blind the brain on the voice path.
"""
try:
from dodaios.marketplace.plugin_relevance import filter_plugin_tools
kept = filter_plugin_tools(user_text, list(tools.values()))
kept_names = {t.name for t in kept}
return {name: t for name, t in tools.items() if t.name in kept_names}
except Exception: # noqa: BLE001
log.debug("plugin relevance gate failed; using full tool set", exc_info=True)
return tools
def _suppress_plugins_covered_by_cli(
self, tools: dict[str, Tool], user_text: str = ""
) -> dict[str, Tool]:
"""Hide plugin/native tools whose CLI counterpart is connected (req 4).
A CLI runs a local subprocess and is cheaper than a plugin's MCP/API
hop, so when a CLI for a service is active its plugin is removed from the
turn's tool surface unless explicitly requested. Defensive: returns the tools
unchanged on any fault (never blind the brain on the voice path).
"""
try:
from dodaios.clis.capability_provider import (
suppress_plugin_tools_covered_by_cli,
)
return suppress_plugin_tools_covered_by_cli(tools, user_text)
except Exception: # noqa: BLE001
log.debug("plugin-CLI suppression failed; full tool set", exc_info=True)
return tools
def _plugin_usage_cards_block(self, tools: dict[str, Tool]) -> str:
"""Markdown block of usage cards for the plugins active in this turn.
Only the plugins whose tools are in ``tools`` (already relevance-gated)
contribute, so the prompt stays small. Returns ``""`` when no plugin
tools are active. Defensive: never raises on the prompt-build path.
"""
try:
from dodaios.marketplace.usage_cards.loader import load_usage_card
plugin_ids: list[str] = []
for name in tools:
pid, sep, _ = name.partition("/")
if sep and pid not in plugin_ids:
plugin_ids.append(pid)
blocks: list[str] = []
for pid in plugin_ids:
card = load_usage_card(pid)
if card and card.body:
blocks.append(f"### Plugin: {pid}\n{card.body}")
if not blocks:
return ""
return "## Connected plugins — how to use them\n\n" + "\n\n".join(blocks)
except Exception: # noqa: BLE001
log.debug("plugin usage-card block failed; omitting", exc_info=True)
return ""
async def _run_navigation_fast_path(
self,
user_text: str,
*,
trace_id: UUID | None = None,
) -> str | None:
"""Move the desktop UI to a section on a clear navigation command.
Navigation is a deterministic "dumb" action (AD-OE3): a spoken/typed
"zeig die Socials" / "open settings" switches the active sidebar section
WITHOUT the LLM, and crucially before the capability gate — which would
otherwise refuse it ('social' is an external-integration marker) — and
before force-spawn. Executes the ``navigate`` tool (which publishes
``NavigateSidebar`` for the frontend) and returns a short spoken
confirmation. Returns ``None`` when the utterance is not a navigation
request, so the normal path runs. Pure regex match, no LLM (AP-11).
"""
from dodaios.brain.navigation_intent import match_navigation_intent
section = match_navigation_intent(user_text)
if section is None:
return None
# User mandate (2026-06-15): an EXPLICIT heavy-work trigger ("subagent",
# "spawn", "openclaw", …) outranks this deterministic "dumb" navigation
# fast-path — exactly as it outranks the skill guard (AD-S9). A nav-tail
# combo like "Spawne einen Subagenten UND zeig mir die Socials" names the
# execution vehicle, so it must reach force-spawn rather than merely
# switch the sidebar section. Stand down and let the normal path spawn.
if self._is_explicit_heavy_request(user_text):
log.info(
"navigation fast-path stands down — explicit heavy-work trigger "
"in the utterance wins (mission, not a sidebar switch)."
)
return None
# An addressed terminal outranks a sidebar switch, for the same reason
# the desktop gate stands down for one a few lines below in ``generate``:
# whichever gate holds the MORE SPECIFIC evidence wins. Naming a running
# pane and telling it to do something is unambiguous; a section word that
# happens to appear in the same breath is not.
#
# Live bug 2026-07-29 17:04 (BUG-121): "Kannst du mal bitte Terminal T7
# prompten, … wieso das Resuming Feature nur bei claude Code Sessions
# funktioniert … oder bei Open Codes oder bei anderen Sessions" opened
# the Sessions section and returned. T7 was never briefed, and the live
# model narrated the briefing anyway. ``match_navigation_intent`` now
# binds its ingredients so that sentence no longer matches at all; this
# is the second layer, because a matcher fix alone leaves the class open
# for the next section word that lands next to a genuine cue.
# <!-- i18n-allow: quoted spoken transcript of the failing utterance -->
if self._agentic_ide_owns_turn(user_text):
log.info(
"navigation fast-path stands down — this turn addresses a "
"running Agentic-IDE terminal (more specific evidence)."
)
return None
tool = self._tools.get("navigate")
if tool is None or self._tool_executor is None:
return None
tid = trace_id or uuid4()
try:
await self._tool_executor.execute(
tool,
{"section": section},
user_utterance=user_text,
trace_id=tid,
)
except Exception: # noqa: BLE001 — navigation must never crash the turn
log.warning(
"navigation fast-path failed for section %r", section, exc_info=True
)
return None
label = section.replace("-", " ").title()
lang = self._spoken_reply_language(user_text)
return _NAVIGATION_ACK.get(lang, _NAVIGATION_ACK["en"]).format(label=label)
def _agentic_ide_owns_turn(self, user_text: str) -> bool:
"""True when this turn belongs to the open coding workspace.
Asked by the deterministic gates that would otherwise consume the turn
first — today the desktop/Computer-Use gate. The answer comes from
``intent.owns_turn``, the one precedence rule the force-spawn guard and
the spawn gate already share, so a fourth opinion cannot appear here.
Cost is a regex sweep over the in-memory session, no IO and no LLM
(AP-9 / AP-11), so it is safe to ask on every turn of the voice hot
path. Any fault answers "no": the workspace is an optional surface and
must never be able to divert a turn away from the path that would
otherwise have served it.
"""
try:
from dodaios.agentic_ide.intent import owns_turn
return owns_turn(user_text)
except Exception: # noqa: BLE001 - optional surface, never fatal
return False
async def _run_society_inventory_fast_path(
self, user_text: str, *, trace_id: UUID | None = None,
) -> str | None:
"""Answer a plain roster question from the actual read-only tool.
This happens before generic routing, acknowledgements and worker
selection. Never let a missing runtime turn a roster read into work.
"""
from dodaios.society.intent import is_inventory_question
if not is_inventory_question(user_text):
return None
out_lang = _turn_phrase_language(self, user_text)
unavailable = {
"de": "Ich kann die Agentenliste gerade nicht abrufen.", # i18n-allow
"en": "I cannot retrieve the agent roster right now.",
"es": "No puedo consultar la lista de agentes ahora.",
"pt": "Não consigo consultar a lista de agentes agora.",
}.get(out_lang, "I cannot retrieve the agent roster right now.")
tool = self._tools.get("society_status")
if tool is None or self._tool_executor is None:
return unavailable
try:
result = await self._tool_executor.execute(
tool, {}, user_utterance=user_text,
config_snapshot={"output_language": out_lang},
trace_id=trace_id or uuid4(),
)
except Exception: # noqa: BLE001 - preserve a truthful answer on storage failure
log.warning("society inventory lookup failed", exc_info=True)
return unavailable
return str(result.output or unavailable)
async def _run_agentic_ide_fast_path(
self,
user_text: str,
*,
trace_id: UUID | None = None,
consume_pending_voice_attachments: bool = False,
) -> str | None:
"""Deliver a spoken instruction to the addressed Agentic-IDE terminal.
The Agentic IDE's promise is that talking to a named pane makes that pane
work. Leaving that to the LLM's tool choice made it unreliable in exactly
the situation it matters most: on 2026-07-25 (voice session 15:47) "let
Kai do a deep dive" was swallowed by the force-spawn heuristic and became
an invisible background mission, and even without that collision a router
that is busy deciding between a dozen tools sometimes just answers in
prose. So the delivery is deterministic here, ahead of force-spawn — the
same shape as the navigation and local-action fast-paths.
What is NOT deterministic is the prompt itself: the composer
(``agentic_ide.prompt_composer``) rewrites the spoken sentence into a
briefed task with ``@file`` references. That is one bounded provider call
with a regex fallback, so the instruction is delivered either way.
Several panes may be addressed in one breath ("Iris und Bruno beide in
Deep Dive geben"). They are served CONCURRENTLY and reported
individually — see ``agentic_ide.fanout``, which exists because doing
this in a loop cannot fit in a voice turn and cannot report a partial
delivery honestly.
Returns ``None`` whenever this turn is not an addressed terminal, so the
normal path runs untouched.
"""
try:
from dodaios.agentic_ide import clarify as ide_clarify
from dodaios.agentic_ide import fanout as ide_fanout
from dodaios.agentic_ide import intent as ide_intent
except Exception: # noqa: BLE001 - optional surface
return None
try:
from dodaios.agentic_ide.session import get_registry
registry = get_registry()
session = registry.session
if session is None:
return None
candidates = [t.name for t in session.terminals]
# An answer to a pending "did you mean Ellis?" is claimed before
# anything else. It names no pane on its own ("ja") and carries no
# instruction, so every detector below would read it as ordinary
# conversation and the task the user already spoke would be lost a
# second time — which is worse than the silent miss the question
# replaced, because it also cost them a turn.
#
# The window classifies the answer under every supported language
# itself, so no per-turn language has to be resolved before it.
answered = ide_clarify.WINDOW.resolve_answer(user_text)
recent = getattr(self, "_last_ide_spawn", None)
if (
ide_intent.references_recent_fleet(user_text)
and recent is not None
and recent[0] == session.id
and time.monotonic() - recent[2] <= 300.0
):
recent_names = [name for name in recent[1] if session.find(name)]
if recent_names:
candidates = recent_names
addressed = ide_intent.detect_all(
user_text, names=candidates
)
if not addressed:
current = session.contextual_terminal()
visible = ide_intent.detect_visible(
user_text,
terminal=current.name if current is not None else None,
names=candidates,
)
if visible is not None:
addressed = [visible]
except Exception: # noqa: BLE001 - detection must never break a turn
return None
# Naming the spawn vehicle outranks the workspace: "spawn an agent that
# helps Kai" is a genuine background-worker request even with a
# workspace open. Asked through the shared rule rather than through
# ``names_spawn_vehicle`` directly, because that stand-down has two
# exceptions now (coding mode is on; the spawn words describe a PANE's
# work, "Alex should spawn sub-agents"), and a second hand-written copy
# of it here would strand exactly those turns: the spawn gate would
# refuse the mission, this fast path would refuse to type, and the user
# would get silence. Passed THIS path's roster — it may include a
# just-closed fleet the global one no longer lists.
if ide_intent.spawn_vehicle_outranks_workspace(user_text, names=candidates):
return None
out_lang = _turn_phrase_language(self, user_text)
# A clarified pane is briefed with the ORIGINAL utterance — the sentence
# that actually carried the work — not with the "yes" that confirmed it.
if answered is not None:
panes, original = answered
# Every pane the answer confirmed, not the first one: "Alex und
# Blaike, macht beide …" is ONE instruction for two agents, and a
# single "yes" has to brief both of them. Answering it with one
# pane is how the second agent of an addressed pair was lost (live
# 2026-07-27 19:07).
live = [name for name in panes if session.find(name) is not None]
if live:
log.info(
"Agentic IDE: clarified call-sign(s) resolved to %s",
", ".join(live),
)
return await self._deliver_agentic_ide_prompt(
session=session,
names=live,
utterance=original,
instruction="",
language=out_lang,
consume_pending_voice_attachments=(
consume_pending_voice_attachments
),
)
if not addressed:
# No pane was named with certainty — but the turn may still have
# MEANT one. A call-sign arrives through speech recognition, and the
# live 2026-07-27 failure was exactly this: "Ellis" came back as
# "Ilies", scored just under the acting threshold, and this path
# returned None without a word. Nothing reached the pane, nothing
# was said, and the live model — which never learns any of this —
# filled the silence by claiming an agent was working.
#
# Asking costs the user one word and cannot type a stranger's
# sentence into a coding agent, so uncertainty resolves to a
# question. ``detect_clarification`` decides when there is one to
# ask; it stands down for anything that is not addressing the
# workspace.
# "Du hast es gar nicht gepromptet." names no pane and carries no
# instruction, so everything above returns nothing — which is how
# the user ended up saying it twice while Jarvis apologised and
# promised a delivery it never made (BUG-121). The sentence is only
# meaningful against the turn before it, so that is where the work
# comes from.
# <!-- i18n-allow: quotes the spoken sentence that failed -->
retry = await self._retry_undelivered_agentic_ide_prompt(
user_text,
session=session,
candidates=candidates,
language=out_lang,
consume_pending_voice_attachments=(
consume_pending_voice_attachments
),
)
if retry is not None:
return retry
return self._ask_which_agentic_ide_terminal(
user_text, candidates=candidates, language=out_lang
)
found = addressed[0]
# A question about a pane is read-only: answer it from what that pane
# printed, and let the normal brain path phrase the answer with the
# focus-context block (which already carries the transcript tail).
if found.kind == ide_intent.KIND_REPORT:
return None
names = [item.terminal for item in addressed]
# A turn addresses a FLEET, and speech recognition may have carried
# only part of it across. "Alex und Blaike, macht beide einen Deep
# Dive" resolves Alex and mangles Blake, and this path used to brief
# Alex and say nothing at all about the rest — so the user heard one
# agent confirmed and believed two were working (live 2026-07-27
# 19:07). The pane that WAS understood still gets its brief; the one
# that was not becomes a question appended to the same answer.
leftover = self._agentic_ide_leftover_question(
user_text, candidates=candidates, claimed=names, language=out_lang
)
# NOTHING is spoken between here and the delivery verdict below, and that
# silence is the feature. A bridge line lived here for a few hours on
# 2026-07-27 to fill the prompt writer's 10-21 s, and it produced the
# worst possible failure the same day: announcements are not read out
# verbatim on a live call — ``deliver_announcement`` hands the text to
# the realtime model to RE-RENDER in its own words — and the model
# rendered the in-progress line as a finished action ("I have forwarded
# the bug to Alex") while nothing had reached the pane yet. On a turn
# whose delivery then failed, that sentence was the only thing the
# maintainer ever heard. Careful wording cannot fix this: any statement
# made before the work is done is a claim a downstream model is free to
# re-tense. So the only sentence this path emits is the per-pane verdict
# at the end, derived from what was actually typed into which terminal.
# Slow and true beats fast and wrong.
# Two agents told to "split the work between you" must get DIFFERENT
# briefs — the same sentence twice is two agents racing on one file.
# Only an explicit request plans a split: it costs a provider call, and
# "both of you run the tests" is one order for two agents. A division
# the user enumerated THEMSELVES ("one fixes the macOS bug, one the
# Linux bug") is exactly as explicit and takes the same path — without
# it, both panes received the whole enumeration and raced on the first
# slice (maintainer report 2026-08-12).
assignments: dict[str, str] | None = None
if len(names) > 1 and (
ide_intent.wants_split(user_text)
or ide_intent.distributes_tasks(found.instruction or user_text)
):
try:
from dodaios.agentic_ide import work_split as ide_split
plan = await ide_split.split(
found.instruction or user_text,
session=session,
count=len(names),
conversation=self._agentic_ide_conversation(user_text),
)
assignments = {
name: item.task
for name, item in zip(names, plan.assignments, strict=False)
}
log.info(
"Agentic IDE fan-out: work split %s across %d panes (%s)",
plan.split_by, len(assignments),
", ".join(a.area for a in plan.assignments),
)
except Exception: # noqa: BLE001 - an unplanned fleet still works
log.warning("Agentic IDE work split failed", exc_info=True)
assignments = None
verdict = await self._deliver_agentic_ide_prompt(
session=session,
names=names,
utterance=user_text,
instruction=found.instruction,
language=out_lang,
assignments=assignments,
consume_pending_voice_attachments=consume_pending_voice_attachments,
)
if leftover is not None:
# Armed only now: a question about the rest of the fleet is worth
# asking once the panes that WERE understood are actually briefed,
# and a delivery that failed on the way there should not leave a
# question standing about work nobody received.
need, question = leftover
ide_clarify.WINDOW.arm(need, question=question)
log.info(
"Agentic IDE: briefed %s, asking about %s",
", ".join(names),
" / ".join(need.offered),
)
return f"{verdict} {question}" if verdict else question
return verdict
def _agentic_ide_conversation(self, utterance: str) -> tuple[tuple[str, str], ...]:
"""The turns an addressed-pane instruction came out of, for the composer.
A spoken order to a pane points back into the conversation constantly —
"above all points two and three", "do that for the wake path too" — and
the coding agent receives the composed brief and nothing else. Live
2026-07-29 that gap produced a brief instructing two agents to
"incorporate points 2 and 3 from the current context": a pointer to
something they can never open, so the substance of the order reached
neither of them.
Read through ``_active_turn_history`` rather than ``self._history``
directly, because a realtime call keeps its own bounded context and
hands it to the delegated turn — on that path the shared buffer is
empty and this is the ONLY place the previous turns exist.
"""
from dodaios.agentic_ide import conversation as ide_conversation
try:
return ide_conversation.from_messages(
self._active_turn_history(), exclude=utterance
)
except Exception: # noqa: BLE001 - context is a bonus, never the turn
log.debug("Agentic IDE: conversation context unavailable", exc_info=True)
return ()
def _agentic_ide_delivery_signals(
self, session: Any
) -> tuple[Callable[[Any], None] | None, Callable[[Any], Awaitable[None]] | None]:
"""Put a SPOKEN delivery on screen: the writing beats, then the arrival.
Writing a brief is 10-30 s of quality-tier model work, and nothing on
screen said so when the order arrived by voice. Both signals existed
already — the composer's ``STAGE_*`` beats and ``AgenticIdePromptSent``
— but only the typed prompt bar's REST route published them, so a spoken
"T5, look at the transcript" left the whole app looking untouched until
the agent itself echoed the text half a minute later. Reported
2026-08-13: the bar showed no thinking state, "so you think it did not
work" — and then the pane was prompted 20 s later.
Deliberately the SAME events, not a spoken line: the clients already
render them (the pane's live status line, the delivery toast), and a
sentence spoken before the work is done is a claim a downstream model
re-tenses into "I have prompted T5" — the failure this whole path is
built to avoid.
Returns ``(None, None)`` without a bus. A publish that fails costs the
line, never the brief.
"""
bus = self._bus
if bus is None:
return None, None
from dodaios.agentic_ide.session import prompt_sent_event
from dodaios.core.events import AgenticIdeComposeProgress
session_id = str(getattr(session, "id", "") or "")
def _beat(notice: Any) -> None:
from dodaios.agentic_ide.prompt_composer import print_notice
# Keep the stdout/log line a headless install watches, exactly as
# the REST route does — the socket beat is an addition to it.
print_notice(
notice, speaker=resolve_assistant_name(getattr(self, "_config", None))
)
try:
loop = asyncio.get_running_loop()
except RuntimeError: # pragma: no cover - no loop, no clients
return
task = loop.create_task(
bus.publish(
AgenticIdeComposeProgress(
session_id=session_id,
terminal=str(getattr(notice, "terminal", "") or ""),
stage=str(getattr(notice, "stage", "") or ""),
message=str(getattr(notice, "message", "") or ""),
kind=str(getattr(notice, "kind", "") or ""),
source_layer="brain.agentic_ide_prompt",
)
)
)
# Fire-and-forget: a beat that cannot be delivered must never cost
# the brief, nor a warning about an unobserved task at teardown.
task.add_done_callback(lambda done: done.cancelled() or done.exception())
async def _delivered(term: Any) -> None:
await bus.publish(
prompt_sent_event(
session, term, source_layer="brain.agentic_ide_prompt"
)
)
return _beat, _delivered
async def _deliver_agentic_ide_prompt(
self,
*,
session: Any,
names: list[str],
utterance: str,
instruction: str,
language: str,
assignments: dict[str, str] | None = None,
consume_pending_voice_attachments: bool = False,
) -> str | None:
"""Compose and type one instruction into the addressed panes.
Shared by the addressed-terminal path and by the answer to a "did you
mean …?" question, so a clarified pane is briefed through exactly the
same composer and reported by exactly the same verdict line. A second
delivery site would be free to drift into announcing something it did
not do, which is the failure class this whole area exists to prevent.
No brain is pinned for the composer on purpose. An earlier version
handed it this turn's FAST router model to save 4-5 s, but that
optimised the wrong axis: the prompt is what the coding agent then
works from for minutes, and the maintainer's decision on 2026-07-25
was explicitly for the better prompt over the quicker handoff. The
composer resolves a quality-tier model itself and degrades to its
deterministic prompt when none is reachable.
"""
from dodaios.agentic_ide import fanout as ide_fanout
# Returning None here would hand the turn to the model with nothing to
# go on, and a model asked about a pane it cannot see answers from the
# user's own question — which is precisely how "I have let Alex know"
# was spoken over a terminal that had received nothing (2026-07-27).
# A delivery that did not happen is a fact worth saying out loud, so
# every exit below carries one; ``deliver`` itself never raises for a
# single pane, so reaching these means the whole fan-out fell over.
on_progress, on_delivered = self._agentic_ide_delivery_signals(session)
try:
result = await ide_fanout.deliver(
session=session,
terminals=names,
utterance=utterance,
instruction=instruction,
assignments=assignments,
conversation=self._agentic_ide_conversation(utterance),
include_pending_attachments=consume_pending_voice_attachments,
on_progress=on_progress,
on_delivered=on_delivered,
# Hanging up ends the order (maintainer decision 2026-08-13).
cancel_on_hangup=True,
)
except Exception: # noqa: BLE001 - never crash the turn over a pane
log.warning("Agentic IDE fast-path failed", exc_info=True)
return action_phrase(
"ide_prompt_sent_nobody", language, failed=_join_names(names, language)
)
if not result.deliveries:
log.warning(
"Agentic IDE fast-path: fan-out returned no verdicts for %s",
", ".join(names),
)
return action_phrase(
"ide_prompt_sent_nobody", language, failed=_join_names(names, language)
)
return _fanout_reply_line(result, language)
#: How long a "you never prompted it" complaint may reach back. Bounded to
#: the running conversation: past this, "do it again" is a fresh request and
#: replaying a stale sentence into a coding agent would be its own bug.
_IDE_RETRY_WINDOW_S = 300.0
async def _retry_undelivered_agentic_ide_prompt(
self,
user_text: str,
*,
session: Any,
candidates: list[str],
language: str,
consume_pending_voice_attachments: bool = False,
) -> str | None:
"""Deliver the PREVIOUS turn's briefing when the user says it never went.
Live failure 2026-07-29 17:04 (BUG-121). A briefing for T7 was consumed
by the navigation gate; Jarvis said it had briefed T7 anyway. The user
corrected it twice — "Du hast es gar nicht gepromptet", then "Das war
noch nicht geprompted" — and both corrections produced nothing at all,
because they name no pane and carry no instruction, so every detector
returned None and the live model was left to answer alone. It apologised
and promised a delivery it had no way to make. The third attempt only
worked because the model happened to call the action tool by itself.
<!-- i18n-allow: quotes the spoken sentences that failed -->
A complaint is not proof, so the pane's OWN receipt decides. If
``last_prompt_at`` says the briefing did arrive, this answers with the
clock time instead of typing the sentence a second time — an agent
briefed twice is two agents' worth of work on one task, and the honest
answer is what tells the user "it did not happen" from "I did not see it
happen". Only a pane with no receipt in the window is briefed.
"""
try:
from dodaios.agentic_ide import intent as ide_intent
except Exception: # noqa: BLE001 - optional surface
return None
if not ide_intent.reports_undelivered(user_text):
return None
previous = self._previous_user_turn_text(use_history=True)
if not previous:
return None
try:
addressed = ide_intent.detect_all(previous, names=candidates)
except Exception: # noqa: BLE001 - detection must never break a turn
return None
wanted = [
item.terminal
for item in addressed
if item.kind == ide_intent.KIND_PROMPT
]
if not wanted:
return None
now = time.time()
delivered: list[tuple[str, float]] = []
missing: list[str] = []
for name in wanted:
term = session.find(name)
if term is None:
continue
at = getattr(term, "last_prompt_at", None)
if at is not None and now - float(at) <= self._IDE_RETRY_WINDOW_S:
delivered.append((name, float(at)))
else:
missing.append(name)
if not missing:
if not delivered:
return None
name, at = delivered[0]
log.info(
"Agentic IDE: %s reported undelivered, but %s has a receipt "
"from %s — answering with the time instead of re-sending",
user_text[:60],
name,
time.strftime("%H:%M:%S", time.localtime(at)),
)
return action_phrase(
"ide_prompt_already_delivered",
language,
name=name,
time=time.strftime("%H:%M", time.localtime(at)),
)
log.info(
"Agentic IDE: retrying an undelivered briefing for %s from the "
"previous turn",
", ".join(missing),
)
return await self._deliver_agentic_ide_prompt(
session=session,
names=missing,
utterance=previous,
instruction="",
language=language,
consume_pending_voice_attachments=consume_pending_voice_attachments,
)
def _ask_which_agentic_ide_terminal(
self,
user_text: str,
*,
candidates: list[str],
language: str,
) -> str | None:
"""Ask which pane was meant, or ``None`` when there is nothing to ask.
The question is armed as a one-shot window: the user's next turn ("ja",
"Ellis") delivers the ORIGINAL instruction to the confirmed pane, so
clarifying costs one word rather than a repeated sentence.
"""
try:
from dodaios.agentic_ide import clarify as ide_clarify
except Exception: # noqa: BLE001 - optional surface
return None
try:
need = ide_clarify.detect_clarification(user_text, names=candidates)
except Exception: # noqa: BLE001 - a detector fault stays silent
return None
if need is None:
return None
question = self._agentic_ide_clarify_question(need, language)
ide_clarify.WINDOW.arm(need, question=question)
log.info(
"Agentic IDE: heard %r, asking whether %s was meant",
" / ".join(item.spoken for item in need.uncertain),
" / ".join(need.offered),
)
return question
@staticmethod
def _agentic_ide_clarify_question(
need: Any, language: str, *, also: bool = False
) -> str:
"""The spoken question for one uncertain call-sign, or for a list.
Three shapes, because they mean three different things and a user has
to be able to answer each with one word: one pane offered ("did you
mean Blake?"), one word that could be several panes ("Max OR
Maggie?"), and several garbled names in one list ("Alex AND Blake?").
Joining the last one with "or" would ask the user to pick between two
agents they had just addressed together.
"""
spoken = need.spoken
if len(need.uncertain) > 1:
heard = [item.spoken for item in need.uncertain]
spoken = action_phrase("join_and", language).join(
(", ".join(heard[:-1]), heard[-1])
)
offered = need.offered
if len(need.uncertain) == 1 and len(offered) == 1:
if also:
return action_phrase(
"ide_terminal_clarify_also",
language,
spoken=spoken,
names=offered[0],
)
return action_phrase(
"ide_terminal_clarify_one", language, spoken=spoken, name=offered[0]
)
# Alternatives for ONE word are offered with "or"; a list of separate
# names is joined with "and", because both were meant.
joiner = "join_and" if len(need.uncertain) > 1 else "join_or"
joined = action_phrase(joiner, language).join(
(", ".join(offered[:-1]), offered[-1])
)
return action_phrase(
"ide_terminal_clarify_also" if also else "ide_terminal_clarify_many",
language,
spoken=spoken,
names=joined,
)
def _agentic_ide_leftover_question(
self,
user_text: str,
*,
candidates: list[str],
claimed: list[str],
language: str,
) -> tuple[Any, str] | None:
"""A question about the addressees this turn named but did not resolve.
Returns ``(need, question)`` when the utterance addressed panes BEYOND
the ones about to be briefed, else ``None``. The caller arms it after
the delivery, so the user hears which agents really got the work before
being asked about the rest.
Nothing is asked when every uncertain word points at a pane that is
already being briefed — that is the same addressee reached twice, not a
second one.
"""
try:
from dodaios.agentic_ide import clarify as ide_clarify
from dodaios.agentic_ide import intent as ide_intent
need = ide_clarify.detect_clarification(user_text, names=candidates)
except Exception: # noqa: BLE001 - a detector fault stays silent
return None
already = {name.casefold() for name in claimed}
if need is not None and not all(
all(name.casefold() in already for name in item.candidates)
for item in need.uncertain
):
return need, self._agentic_ide_clarify_question(need, language, also=True)
# No word came close enough to name a pane — and a call-sign can be
# mangled past every threshold there is ("Dave" for a pool that holds
# none). What survives that is the COUNT the user stated out loud:
# "both of you" says two agents were addressed however badly the names
# travelled. Briefing one and saying nothing is the failure this
# catches — the user hears one name confirmed and believes two are
# working (live 2026-07-27 19:07).
try:
if not ide_intent.expects_several(user_text):
return None
except Exception: # noqa: BLE001 - a detector fault stays silent
return None
if len(claimed) > 1:
return None
rest = tuple(name for name in candidates if name.casefold() not in already)
if not rest:
return None
# Armed over every OTHER pane, so the next word ("Blake") delivers the
# original task. A bare "yes" decides nothing here and must not: there
# is no candidate to confirm, only panes to choose between.
unresolved = ide_clarify.ClarificationNeeded(
uncertain=(ide_clarify.UncertainName(spoken="", candidates=rest),),
utterance=user_text,
certain=tuple(claimed),
)
return unresolved, action_phrase(
"ide_terminal_who_else", language, names=", ".join(claimed)
)
async def _brief_spawned_agentic_ide_fleet(
self,
session: Any,
names: list[str],
user_text: str,
) -> None:
"""Brief newly mounted Codex panes once their real input lines exist."""
from dodaios.agentic_ide import fanout as ide_fanout
from dodaios.agentic_ide import intent as ide_intent
from dodaios.agentic_ide.fleet_actions import wait_for_prompt_ready
instruction = ide_intent.spawn_instruction(user_text)
# Read once, up front: this runs as a background task that outlives the
# turn, and the history it reads keeps moving underneath it.
spoken_before = self._agentic_ide_conversation(user_text)
assignments: dict[str, str] | None = None
# A brief BY KIND names its own panes ("prompt the claudes to fix the
# tests, the codex should update the docs"), so it outranks both the
# shared brief and a planned split: the user has already divided the
# work, and every pane of a kind the brief does not name stays blank —
# that silence is what was asked for. Without this, all panes of a
# mixed fleet received the ENTIRE enumeration as their own task
# (maintainer report 2026-08-12).
try:
group_tasks = ide_intent.spawn_group_tasks(user_text)
except Exception: # noqa: BLE001 - the shared brief is still usable
log.warning("Agentic IDE spawned-fleet group parse failed", exc_info=True)
group_tasks = {}
if group_tasks:
per_pane: dict[str, str] = {}
for name in names:
term = session.find(name)
kind = str(getattr(term, "agent", "") or "") if term is not None else ""
task = group_tasks.get(kind)
if task:
per_pane[name] = task
if per_pane:
assignments = per_pane
names = [name for name in names if name in per_pane]
log.info(
"Agentic IDE spawned-fleet briefing: per-kind tasks for %s",
", ".join(names),
)
# ``distributes_tasks`` reads the extracted TASK, never the utterance:
# the fleet description counts panes with the same words ("one Codex").
if assignments is None and len(names) > 1 and (
ide_intent.wants_split(user_text)
or ide_intent.distributes_tasks(instruction)
):
try:
from dodaios.agentic_ide import work_split as ide_split
plan = await ide_split.split(
instruction,
session=session,
count=len(names),
conversation=spoken_before,
)
assignments = {
name: item.task
for name, item in zip(names, plan.assignments, strict=False)
}
except Exception: # noqa: BLE001 - the common brief is still usable
log.warning("Agentic IDE spawned-fleet split failed", exc_info=True)
ready = await wait_for_prompt_ready(session, names)
missing = [name for name in names if name not in ready]
if missing:
log.warning(
"Agentic IDE spawned-fleet briefing: panes never became ready: %s",
", ".join(missing),
)
if not ready:
return
result = await ide_fanout.deliver(
session=session,
terminals=ready,
utterance=user_text,
instruction=instruction,
assignments=assignments,
conversation=spoken_before,
)
log.info(
"Agentic IDE spawned-fleet briefing: %d of %d prompts delivered",
len(result.delivered),
len(names),
)
async def _run_agentic_ide_close_fast_path(
self,
user_text: str,
*,
trace_id: UUID | None = None,
) -> str | None:
"""Close an explicitly requested terminal fleet without model routing."""
try:
from dodaios.agentic_ide import intent as ide_intent
from dodaios.agentic_ide.fleet_actions import (
close_agent_terminals,
terminals_closed_event,
)
from dodaios.agentic_ide.session import get_registry
request = ide_intent.detect_close_fleet(user_text)
except Exception: # noqa: BLE001 - optional surface
return None
if request is None:
return None
out_lang = _turn_phrase_language(self, user_text)
registry = get_registry()
session = registry.session
if session is None:
return action_phrase("ide_terminals_none_to_close", out_lang)
closed = await close_agent_terminals(registry, request.agent)
if not closed:
return action_phrase("ide_terminals_none_to_close", out_lang)
if self._bus is not None:
try:
await self._bus.publish(
terminals_closed_event(
session,
closed,
source_layer="brain.agentic_ide_close",
)
)
except Exception: # noqa: BLE001 - the terminals are already closed
log.warning("Agentic IDE close: UI notification failed", exc_info=True)
names = [term.name for term in closed]
return action_phrase(
"ide_terminals_closed",
out_lang,
count=len(names),
names=_join_names(names, out_lang),
)
async def _run_agentic_ide_spawn_fast_path(
self,
user_text: str,
*,
trace_id: UUID | None = None,
) -> str | None:
"""Open N more coding terminals when the user asks for them out loud.
"Spawn five more Claude Code terminals" is a workspace request, but it
opens with the word the force-spawn heuristic reads as "dispatch a
background agent" — so left to the router it becomes an invisible mission
worker instead of five panes. ``intent.detect_spawn`` claims the turn
(that precedence lives in ``intent.owns_turn``, which both routing gates
already consult) and this path carries it out.
Three things happen here that the REST route cannot do on its own:
1. **A workspace is opened when none is running.** The folder is the most
recently used one, and it is NAMED in the reply — it is an assumption,
and the user has to be able to hear a wrong one.
2. **The open UI is told.** Panes added from outside the workspace view
are invisible to it (it fetches its state once, on mount), so the new
pane list is published on the bus.
3. **The view is brought forward.** This is also what STARTS the agents:
``add_terminals`` creates the registry entries, and each agent's
pseudo-terminal spawns when its pane mounts.
Returns ``None`` on every turn that is not a terminal-spawn request, so
the normal path runs untouched.
"""
try:
from dodaios.agentic_ide import intent as ide_intent
from dodaios.agentic_ide.session import (
SessionError,
get_registry,
terminals_added_event,
)
except Exception: # noqa: BLE001 - optional surface
return None
# A question asked last turn is answered BEFORE anything is parsed
# again: "Codex" on its own is not a spawn request and would otherwise
# fall through to the ordinary brain, leaving the user's answer — and
# the fleet it was about — to evaporate.
answered = self._answer_pending_cli_question(user_text)
try:
request = answered or ide_intent.detect_spawn(user_text)
except Exception: # noqa: BLE001 - detection must never break a turn
return None
if request is None:
return None
out_lang = _turn_phrase_language(self, user_text)
from dodaios.voice.action_phrases import action_phrase
# The name did not clearly reach one CLI. ASK — this is the maintainer's
# directive of 2026-07-28 and the same rule the pane-name question
# follows: whatever is unsure becomes a question rather than an action,
# because the question costs one word and the guess costs an agent
# working on the wrong plan until somebody notices.
if request.uncertain_cli:
unclear = request.uncertain_cli[0]
self._pending_cli_choice = _PendingCliChoice(
groups=tuple(request.groups),
utterance=request.utterance,
candidates=unclear.candidates,
asked_at=time.monotonic(),
)
if len(unclear.candidates) == 1:
return action_phrase(
"ide_terminal_kind_unclear_one",
out_lang,
spoken=unclear.spoken,
first=unclear.candidates[0],
)
return action_phrase(
"ide_terminal_kind_unclear",
out_lang,
spoken=unclear.spoken,
first=unclear.candidates[0],
second=unclear.candidates[1],
)
registry = get_registry()
folder_label: str | None = None
#: Why a group of the fleet could not be opened, one sentence each.
#: Spoken back with the panes that DID open — a fleet that came up short
#: without saying so is the failure this whole path is shaped around.
refused: list[str] = []
# A CLI this app has no terminal kind for. It is answered even when it
# is the ONLY thing that was asked for, which is why it is collected
# before anything is opened.
for unknown in request.unsupported:
refused.append(
action_phrase(
"ide_terminal_kind_unknown",
out_lang,
name=unknown,
available=_available_terminal_kinds(),
)
)
if not request.groups:
# Nothing openable was asked for — the only CLI named is one this
# workspace does not have. Answering is the whole job here; opening
# a substitute pane would grant a request that was just refused.
return " ".join(refused) if refused else None
try:
if registry.session is None:
# No workspace open: take the most recent one. Reading the
# recents file is IO, so it goes to a thread — this path runs
# inside a voice turn.
from dodaios.agentic_ide import recents
entries = await asyncio.to_thread(recents.load)
if not entries:
return action_phrase("ide_terminals_nowhere", out_lang)
recent = entries[0]
fallback_agent = request.agent or _recent_agent(recent)
# One spec per pane, group by group: "5 Codex and 3 Claude Code
# terminals" is a mixed fleet, and collapsing it to one agent
# opened five of the first kind and silently dropped the rest
# (maintainer report 2026-07-26).
specs = [
{"agent": group.agent or fallback_agent}
for group in request.groups
for _ in range(group.count)
]
session = await registry.start(recent.path, specs)
created = list(session.terminals)
folder_label = recent.name
else:
created = []
for group in request.groups:
# One group's failure is that GROUP's failure.
#
# A CLI that is not installed, or one whose binary vanished,
# raises here — and letting that leave the loop threw away
# every group behind it, including the ones that would have
# opened perfectly well. "Two Claude, one Codex and one GLM"
# then produced nothing but a sentence about GLM. Each group
# is attempted on its own and what could not be opened is
# named at the end, so a mixed fleet degrades pane by pane
# instead of all at once.
try:
opened, _capped = await registry.add_terminals(
group.count, agent=group.agent
)
except SessionError as exc:
log.info(
"Agentic IDE spawn: %s group refused: %s",
group.agent or "inherited",
exc,
)
refused.append(str(exc))
continue
created.extend(opened)
if _capped:
# A pane failed to open mid-fleet. Stop rather than
# asking for the next group and hitting the same
# failure — the readback already reports the shortfall.
break
except SessionError as exc:
# A missing CLI, an unreadable folder: every one of these already
# carries a user-facing English sentence, and speaking it is more
# useful than a generic failure.
log.info("Agentic IDE spawn fast-path refused: %s", exc)
return str(exc)
except Exception: # noqa: BLE001 - never crash the turn over a pane
log.warning("Agentic IDE spawn fast-path failed", exc_info=True)
return None
if not created:
# Nothing opened. If a group said WHY, that sentence is the answer;
# otherwise the pane failed to start and the log says why.
if refused:
return " ".join(refused)
return action_phrase("ide_terminals_open_failed", out_lang)
session = registry.session
if session is not None and self._bus is not None:
try:
await self._bus.publish(
terminals_added_event(
session, created, source_layer="brain.agentic_ide_spawn"
)
)
# Bring the workspace forward so the panes are SEEN appearing —
# and so their agents boot, which only happens once a pane
# mounts. A no-op when the view is already active.
from dodaios.core.events import NavigateSidebar
await self._bus.publish(
NavigateSidebar(
section="agentic-ide",
source_layer="brain.agentic_ide_spawn",
trace_id=trace_id or uuid4(),
)
)
except Exception: # noqa: BLE001 - the panes exist either way
log.warning("Agentic IDE spawn: UI notification failed", exc_info=True)
names = [t.name for t in created]
if session is not None:
self._last_ide_spawn = (session.id, tuple(names), time.monotonic())
briefing_queued = bool(
session is not None and ide_intent.spawn_includes_task(user_text)
)
if briefing_queued and session is not None:
tasks = getattr(self, "_ide_background_tasks", None)
if tasks is None:
tasks = set()
self._ide_background_tasks = tasks
task = asyncio.create_task(
self._brief_spawned_agentic_ide_fleet(session, names, user_text),
name="agentic-ide-spawned-fleet-briefing",
)
tasks.add(task)
def _briefing_done(done: asyncio.Task[Any]) -> None:
tasks.discard(done)
if done.cancelled():
return
try:
done.result()
except Exception: # noqa: BLE001 - background failure is logged
log.warning(
"Agentic IDE spawned-fleet briefing failed",
exc_info=True,
)
task.add_done_callback(_briefing_done)
log.info(
"Agentic IDE spawn fast-path: opened %d pane(s) %s%s",
len(names),
names,
f" in {folder_label}" if folder_label else "",
)
line = _terminals_spawned_line(
names, requested=request.count, folder=folder_label, lang=out_lang
)
# A partial fleet says so in the same breath. The panes that opened are
# already named; without this the ones that did not simply were not
# mentioned, and a user who asked for four and got three had to count.
if refused:
line = f"{line} {' '.join(refused)}"
if briefing_queued:
line = f"{line} {action_phrase('ide_terminals_briefing_queued', out_lang)}"
return line
def _answer_pending_cli_question(self, user_text: str) -> Any | None:
"""The held fleet with its CLI filled in, or ``None``.
Consumes the question either way. A question that has been answered,
declined, or simply talked past must never open panes on a later turn —
the same rule the pane-name window follows, and for the same reason: a
forgotten "yes" that opens four terminals ten minutes later is worse
than never having asked.
Three shapes count as an answer, in falling directness: naming a CLI
("Codex", "Claude Code"), agreeing when only one was offered ("yes"),
and naming its position ("the first one"). Anything longer than a few
words is the user moving on.
"""
pending = getattr(self, "_pending_cli_choice", None)
if pending is None:
return None
text = (user_text or "").strip()
if not text:
return None
if time.monotonic() - pending.asked_at > _CLI_QUESTION_TTL_S:
self._pending_cli_choice = None
return None
if len(text.split()) > _CLI_ANSWER_MAX_WORDS:
# Not an answer. The question is spent rather than left armed: the
# user has moved on, and a stale question would answer a sentence
# they never meant as one.
self._pending_cli_choice = None
return None
from dodaios.agentic_ide import intent as ide_intent
chosen: str | None = None
# A CLI named outright wins, wherever in the short answer it sits.
for size in (3, 2, 1):
words = text.replace(",", " ").split()
for start in range(len(words) - size + 1):
agent = ide_intent.canonical_agent(" ".join(words[start : start + size]))
if agent is not None:
chosen = agent
break
if chosen is not None:
break
if chosen is None and len(pending.candidates) == 1:
# "Yes" answers a question that offered exactly one name. With two
# on the table it answers nothing, so it is not accepted there.
from dodaios.agentic_ide.clarify import classify_short_answer
if classify_short_answer(text) == "confirm":
chosen = ide_intent.canonical_agent(pending.candidates[0])
self._pending_cli_choice = None
if chosen is None:
return None
from dodaios.agentic_ide.intent import SpawnGroup, SpawnTerminalsRequest
groups = tuple(
SpawnGroup(count=g.count, agent=g.agent or chosen) for g in pending.groups
)
if not groups:
groups = (SpawnGroup(count=1, agent=chosen),)
log.info(
"Agentic IDE: the unclear CLI was answered with %s — opening %d pane(s)",
chosen,
sum(g.count for g in groups),
)
return SpawnTerminalsRequest(
count=sum(g.count for g in groups),
agent=groups[0].agent,
# The ORIGINAL request, so a brief that rode along with it still
# reaches the panes it was written for.
utterance=pending.utterance,
groups=groups,
)
def _is_explicit_heavy_request(self, user_text: str) -> bool:
"""Return whether the user semantically requested a heavy worker."""
text = (user_text or "").strip()
if not text or _is_spawn_decline(text) or _is_spawn_feature_reference(text):
return False
trigger = self._get_force_spawn_pattern().search(text)
if trigger is None:
return False
if _trigger_names_vehicle(trigger.group(0)):
return True
return not _looks_like_pc_control(text)
def _should_force_spawn(
self, user_text: str, *, source_layer: str | None = None
) -> bool:
"""Deterministic spawn guard for action requests.
Wave-4 migration: previously ``_should_force_sub_jarvis`` with
``spawn_sub_jarvis`` tool lookup. The Sub-Jarvis tier was replaced by
the Jarvis-Agent bridge — see docs/jarvis-agents-bridge.md §11.
Order (the real evaluation sequence — keep this in sync with the body):
0. Conversational source (drag-dropped mission recap) → False.
1. Fatal preconditions, in order → False: empty text; no
spawn_worker tool/executor; Whisper-FP sentinel; < 6 chars; no
viable heavy-worker provider. These run FIRST — a spawn is then
impossible or the transcript is noise.
2. Explicit spawn DECLINE (``_is_spawn_decline``) → False. **MUST
precede step 3** — the user negated the very trigger word the hoist
matches; checking it after the hoist would force-spawn the OPPOSITE
of "don't spawn a subagent" (live bug 2026-06-19, Turn 2).
3. Explicit heavy-work trigger (``force_spawn_phrases``) → True. The
user named the vehicle (AD-S9 / 2026-06-15 mandate); wins over
every AMBIGUOUS-spawn disambiguation guard below.
4. Disambiguation stand-downs → False: instructional question;
opinion/advice question; conversational coaching
(``_is_conversational_coaching``); pointer; navigation; smalltalk;
open-app; installed skill; connected-CLI capability; PC control.
5. The force-spawn mode decides what is left (``force_spawn_mode``):
``balanced`` (default) and ``permissive`` first run the EFFORT
test — a multi-step artefact brief → True (mandate 2026-08-18).
``strict`` skips it and stays explicit-only, so everything the
trigger in step 3 did not catch → False (mandate 2026-07-21).
``permissive`` additionally keeps the legacy heuristic: action
verb / external marker → True.
6. Otherwise → False.
"""
# A drag-dropped mission recap is a CONVERSATION about a FINISHED job,
# never new work — answer it inline regardless of what the quoted card
# text contains (doom-loop fixed 2026-06-16; see
# ``_NON_SPAWN_SOURCE_LAYERS``). Checked first so a leaked spawn trigger
# in the verbatim title cannot reach the explicit-trigger hoist below.
if source_layer is not None and source_layer in _NON_SPAWN_SOURCE_LAYERS:
return False
t = (user_text or "").strip()
if not t:
return False
from dodaios.society.lead_card import society_owns_task
if society_owns_task(t):
return False
if "spawn_worker" not in self._tools or self._tool_executor is None:
return False
# BUG-LIVE-04 (Recon-Agent 3, 2026-05-16): Whisper transcribes
# background TV / music / silence into well-known sentinel strings
# ("Untertitelung des ZDF für funk", "Vielen Dank fürs Zuschauen",
# "Musik", "Applaus", "you", "Tschüss", "Bis zum nächsten Mal").
# In permissive mode these matched action verbs and triggered
# heavy worker spawns that hung 630s and produced "Mission
# fehlgeschlagen" announcements — without the user having said
# anything. Filter the well-known seeds before the verb match.
lowered = t.lower().rstrip(".!? ").strip()
# H2 (2026-05-17): exact-only bucket runs first because it's the
# cheap O(1) set lookup; prefix bucket needs an O(N) sweep.
# `log` is the module-level logger bound at L73 -- BUG-026 fix.
if lowered in _WHISPER_FP_EXACT_ONLY:
log.info(
"force_spawn skipped: Whisper FP exact-only seed %r",
lowered,
)
return False
for _seed in _WHISPER_FP_PREFIX_OK:
if lowered == _seed or lowered.startswith(_seed + " "):
log.info(
"force_spawn skipped: Whisper FP prefix seed %r",
_seed,
)
return False
# Minimum-length gate: anything shorter than 6 chars after
# stripping is almost certainly a Whisper artefact, not an
# intentional command.
if len(lowered) < 6:
return False
# Force-spawn viability follows the WORKER, not the talker. The heavy
# worker is selected from [brain.sub_jarvis].provider and runs regardless
# of which provider talks to the user (dodaios/missions/init.py
# _select_subagent_worker_kind). The original BUG-017 (2026-05-13) guard
# gated on brain.primary, which silenced EVERY action request the moment
# the user switched the talker to grok / openai / codex / openrouter —
# re-introducing the "Das kann ich nicht ausführen" refusal through the
# LLM fallback path (live bug class, forensic 2026-06-07). See
# _heavy_worker_provider_viable.
if not self._heavy_worker_provider_viable():
return False
# Explicit spawn DECLINE wins over EVERYTHING below, including the
# negation-blind explicit-trigger hoist: when the user literally says
# "don't spawn a subagent" / "talk to me directly", the trigger word
# ("Subagent"/"spawn") they negated must NOT be read as a request. This
# is checked BEFORE the hoist precisely because the hoist substring-
# matches that same word and would force-spawn the opposite of the
# user's intent. Live bug 2026-06-19 (voice session 18:41, Turn 2).
if _is_spawn_decline(t):
log.info("force-spawn skipped: explicit spawn decline — answer inline")
return False
# The user NAMING the auto-spawn feature (complaining about it, asking to
# fix it) is talk ABOUT the feature, not a command. "Auto-Spawn" carries
# the substring "spawn" that the negation-blind vehicle hoist below matches
# at the hyphen boundary; without this stand-down, complaining about
# auto-spawn force-spawns the very thing complained about. Checked BEFORE
# the hoist, exactly like the decline guard. Live bug 2026-07-01 (voice
# session 21:26:44): "Auto-Spawn, das müssen wir erstmal fixen" spawned a
# full Opus mission whose heartbeats then spoke out of nowhere.
if _is_spawn_feature_reference(t):
log.info(
"force-spawn skipped: auto-spawn feature named, not commanded — inline"
)
return False
# An open Agentic-IDE terminal that is being ADDRESSED owns the turn.
# Checked BEFORE the explicit-trigger hoist for the same reason the two
# guards above are: the hoist matches a DEPTH marker, and "let Kai do a
# deep dive" carries one while meaning the exact opposite of a background
# mission. Live bug 2026-07-25 (voice session 15:47): that sentence
# dispatched a Codex worker into a fresh worktree while the terminal
# called Kai sat idle and the user saw nothing happen.
#
# ``owns_turn`` stands down when the user NAMES the spawn vehicle, so an
# explicit "spawn an agent that helps Kai" still force-spawns — the
# workspace claims ambiguous turns, never explicit delegation.
try:
from dodaios.agentic_ide.intent import owns_turn as _ide_owns_turn
if _ide_owns_turn(t):
log.info(
"force-spawn skipped: an open Agentic-IDE terminal is "
"addressed — the workspace handles this turn"
)
return False
except Exception: # noqa: BLE001 — optional surface, never breaks routing
pass
# User mandate (2026-06-15, "when I say subagent it MUST spawn"): an
# EXPLICIT heavy-work trigger that NAMES the execution vehicle
# ("subagent", "spawn", "openclaw", "delegate") is an UNAMBIGUOUS request
# to dispatch a worker, so it is checked FIRST — ahead of every
# disambiguation guard below (instructional / pointer / navigation /
# smalltalk / open-app / skill). Those guards exist only to suppress
# AMBIGUOUS, implicit spawns; they must never veto a request in which the
# user literally named the vehicle. Before this hoist, an explicit
# "Starte Jarvis-Agent" / "Spawne einen Subagenten und zeig …" was swallowed
# by the open-app / navigation guard and never spawned ("sometimes saying
# subagent doesn't spawn a subagent"). The fatal preconditions above (no
# tool/executor, Whisper-FP seed, min length, worker not viable) still
# win — they mean a spawn is impossible or the transcript is noise.
#
# A DEPTH marker ("deep dive", "gründlich", "umfassend", …) is NOT a
# vehicle name — it describes thoroughness and OVERLAPS with computer-use
# requests. It still force-spawns on its own ("Mach einen Deep Dive in
# meine Google Cloud Kosten") BUT it must NOT override an explicit
# on-screen / computer / browser request: "Mach einen Deep Dive mit
# Computer Use in meinem Chrome Browser …" is a Computer-Use turn, not a
# background mission. When the depth marker co-occurs with a pc-control
# signal we hand the computer-use-vs-spawn decision to the LLM router (it
# owns computer_use + the SYSTEM_PROMPT rule "Bildschirm/Browser bedienen
# ist computer_use, kein spawn_worker") instead of letting the keyword
# decide. This reuses the existing pc-control detector — no new
# signal-word list, no widening of force_spawn_phrases.
_trigger = self._get_force_spawn_pattern().search(t)
if self._is_explicit_heavy_request(t):
return True
if _trigger is not None:
log.info(
"force-spawn deferred to LLM: depth trigger %r + computer-use "
"request — router decides computer_use vs spawn",
_trigger.group(0),
)
return False
verb_re, marker_re, _smalltalk_re = self._get_routing_patterns()
if _is_instructional_question(t):
return False
# Opinion / advice / recommendation / decision questions, and casual
# question-openers, are CONVERSATION — the brain answers them inline,
# never a heavy-worker spawn. Guards the verb-collision false positive
# where an everyday word ("Frage" -> "frag", the filler "halt") trips
# has_action_intent and pushes a pure chat turn into
# _is_generic_subagent_work. Live bug 2026-06-19 (emigration turn). The
# explicit heavy-work trigger hoisted above still wins, so "spawn a
# subagent and tell me what you'd recommend" dispatches as asked.
if _is_opinion_advice_question(t):
log.info(
"force-spawn skipped: opinion/advice/conversational question — inline"
)
return False
# Conversational coaching ("hilf mir, intelligent zu fragen / klarer zu
# denken") is talk, not work — the brain answers inline and asks the
# user smart questions back. Guards the same verb-collision class as the
# opinion guard above: the coaching OBJECT is itself an action verb
# ("fragen" -> "frag"/"frage") that trips has_action_intent ->
# _is_generic_subagent_work. Live bug 2026-06-19 (voice session 18:41,
# Turn 1). The explicit heavy-work trigger hoisted above still wins.
if _is_conversational_coaching(t):
log.info(
"force-spawn skipped: conversational coaching request — inline"
)
return False
# AI Pointer: a deictic "what is this?" is a Q&A about the element under
# the cursor — answered inline from the pushed pointer context, NEVER a
# heavy-worker spawn. Guard here so a pointing verb like "zeige" cannot
# fall through to the permissive verb heuristic or generic-subagent
# detection. See docs/plans/ai-pointer/DESIGN.md.
try:
from dodaios.pointer.intent import is_pointing_intent # noqa: PLC0415
if is_pointing_intent(t):
return False
except Exception: # noqa: BLE001 — pointer gate must never block routing
pass
# UI navigation ("zeig die Socials", "open settings") is a deterministic
# dumb action handled by the navigation fast-path in generate() — never a
# heavy worker spawn. Guard here too so a navigation verb cannot fall
# through to the generic-subagent heuristic. See ADR-0011 "Navigate tool".
try:
from dodaios.brain.navigation_intent import ( # noqa: PLC0415
match_navigation_intent,
)
if match_navigation_intent(t) is not None:
return False
except Exception: # noqa: BLE001 — nav gate must never block routing
pass
# Greeting-aware smalltalk check (live bug 2026-06-07): a greeting prefix
# ("Hallo, öffne ...") must NOT block the spawn of the real command that # i18n-allow
# follows it. _is_smalltalk strips the greeting and re-evaluates.
if self._is_smalltalk(t):
return False
# Opening / launching an app is ALWAYS a computer-use task — a sub-agent
# worker runs in an isolated git worktree and has no desktop. The
# deterministic match_local_action path routes these to computer-use
# first; this guard is defense-in-depth so a conjugated open verb
# ("öffnest") can never fall through to a force-spawn (live bug
# 2026-06-08: "Ich möchte, dass du mir Hermes Agent öffnest, also …").
# BUT a genuine build-a-deliverable request ("build me a website",
# "generate a landing page for the product launch") must NOT be vetoed by
# an is_open_app_intent false positive (it trips on "launch" / English
# phrasings) — building a file/site/app is a mission, not opening an app.
# _research_wants_artifact requires a build VERB, so a real "open X"
# command (no build verb) still stands down to computer-use here.
if is_open_app_intent(t) and not self._research_wants_artifact(t):
return False
# NOTE: the EXPLICIT heavy-work trigger check (AD-S9, 2026-06-10) was
# hoisted to the top of this method (above every disambiguation guard)
# per the 2026-06-15 user mandate — see the comment there. It used to sit
# here, between the open-app guard and the skill guard, which let the
# open-app / navigation guards veto an explicit "Starte Jarvis-Agent" /
# "Spawne … und zeig …" before the trigger was ever evaluated.
# Skill-aware guard (AD-S3, 2026-06-09 rebuild): an utterance that
# matches an installed, active skill is the skill's turn — never a
# heavy-worker spawn. generate() sets _skill_turn_match early; the
# direct probe is defense-in-depth for callers outside generate().
if self._skill_turn_match is not None or self._match_skill_for_turn(t) is not None:
log.info("force-spawn skipped: utterance matches an installed skill")
return False
# A request to CREATE a skill is authored inline by the create-skill
# tool (one bounded LLM call, lands as a draft) — never a background
# mission, even when the skill-creator builtin is disabled and no skill
# captured the turn above.
if getattr(self, "_skill_meta_turn", ""):
log.info(
"force-spawn skipped: skill %s request — the skill tools own it",
self._skill_meta_turn,
)
return False
# A connected CLI's capability already covers this intent → prefer its
# cli_<name> tool, never a Computer-Use spawn (the CLI does it headless,
# no browser login). Mirrors the skill guard above for the CLI surface
# that capability_provider.sync_registry registers on connect. The
# explicit heavy-work trigger (hoisted to the top of this method) still
# wins, so the user can force a worker with "spawn"/"deep dive".
try:
from dodaios.core.capabilities import get_registry # noqa: PLC0415
_cap = get_registry().resolve_intent(t)
if _cap is not None and _cap.source == "cli":
log.info(
"force-spawn skipped: connected CLI %s covers the intent", _cap.id
)
return False
except Exception: # noqa: BLE001 — capability lookup must never break routing
pass
# A pc-control request (incl. an explicit "am Bildschirm / on screen")
# is computer-use, not a sub-agent — stand down. BUT a build-a-deliverable
# request that merely mentions the screen ("bau mir eine Website und zeig
# sie am Bildschirm") must still spawn the mission, so the artifact build
# wins over this stand-down (mirrors the open-app guard above).
# Proxy for "the brain can drive the desktop directly": this used to
# check ``dispatch_to_harness`` (removed from the router set 2026-06-28),
# so it now checks the live desktop tool ``computer_use``. Without the
# update the guard would never fire and a pure pc-control request could
# wrongly force a sub-agent spawn.
if (
"computer_use" in self._tools
and _looks_like_pc_control(t)
and not self._research_wants_artifact(t)
):
return False
# User-Mandate 2026-05-14: the permissive router used to spawn on every
# spawn_verb hit ("schreib", "mach", "zeig", "lies", ...), which fired
# heavy workers for everyday utterances, so strict became the default:
# spawn only when the user explicitly names a heavy-work trigger
# ("Jarvis-Agent", "Sub-Agent", "spawn", "deep dive", "gründliche
# Recherche", ...). Since 2026-08-18 the default is `balanced` — strict
# plus the effort route below — and the legacy verb/marker heuristic
# stays available via `brain.routing.force_spawn_mode = "permissive"`.
mode = self.force_spawn_mode
if mode in (FORCE_SPAWN_MODE_BALANCED, FORCE_SPAWN_MODE_PERMISSIVE):
# The EFFORT route (maintainer mandate 2026-08-18: "the goal is that
# he just DOES things without being told. Right now he doesn't even
# do the things you DO tell him."). Explicit-only left Jarvis unable
# to start work on its own judgement — "Bau mir eine Website mit
# Flask und einer Startseite" reached this line and became talk.
#
# This is the retired build-a-deliverable gate coming back NARROWER,
# not the retired gate coming back. That one fired on
# ``_research_wants_artifact`` alone — a build verb plus an artefact
# noun — so a bare "erstell ein Skript" dispatched a mission. The
# effort test demands the same deliverable PLUS a request shape,
# PLUS no cheap-scope word, PLUS the conversational stand-downs,
# PLUS a substance signal and two scope signals in total. It is
# deliberately reused from ``spawn_gate`` rather than restated here,
# so the deterministic path and the LLM gate judge effort with ONE
# test (the same reason ``addressed_pane_blocks_spawn`` delegates to
# ``intent.owns_turn``).
#
# Every stand-down above still wins: this runs last, after the
# smalltalk / Whisper-FP / instructional / opinion / coaching /
# pointer / skill / capability / pc-control guards.
if effort_warrants_delegation(t):
log.info(
"force-spawn: %s mode — the turn is a multi-step artefact "
"brief, delegating without a delegation keyword: %r",
mode,
t[:80],
)
return True
if mode != FORCE_SPAWN_MODE_PERMISSIVE:
# Maintainer mandate 2026-07-21 (voice session 07:46): a background
# agent starts ONLY on an explicit request — the user names the
# vehicle or a delegation/depth trigger (``force_spawn_phrases``;
# the AD-S9 hoist above already returned True for those). Every
# IMPLICIT strict-mode spawn path is retired:
# - generic sub-agent work (``_is_generic_subagent_work``,
# 2026-06-01): its ``has_action_intent`` verb catalogue collides
# with everyday nouns — the live trigger for this mandate was
# "…wann die beste Zeit ist, um … bei Hacker News und Post
# abzusetzen", where the noun "Post" matched the action verb
# "post" and dispatched a full mission for an info question;
# - heavy research with an artifact deliverable (Option A,
# 2026-06-15) and the build-a-deliverable gate (2026-06-21):
# a build command without delegation wording no longer spawns
# silently — the router LLM answers inline or OFFERS a
# background agent (``dodaios.brain.spawn_gate``), and the
# user's confirming yes unlocks exactly one spawn.
# The legacy verb/marker heuristic stays available via
# ``force_spawn_mode = "permissive"``. In ``balanced`` the effort
# route above already had its say, so reaching here means the turn
# is neither an explicit request nor a multi-step artefact brief.
log.info(
"force-spawn skipped: %s mode needs an explicit delegation "
"trigger — none in %r",
mode,
t[:80],
)
return False
if verb_re.search(t):
return True
if marker_re.search(t):
return True
return False
def _is_generic_subagent_work(self, t: str) -> bool:
"""True iff the utterance is generic, sub-agent-fulfillable work.
Mirrors the capability gate's class exactly — an action the registry
recognises that no capability resolves. A specific external integration
the worker cannot satisfy (mail/calendar/Spotify/social/delivery) is
excluded so it keeps the honest refusal. Defensive: an unavailable/empty
registry returns False (mirrors the empty-registry guard in
_check_unsupported_intent).
RETIRED from the spawn decision 2026-07-21 (strict mode is
explicit-only): ``has_action_intent``'s verb catalogue collides with
everyday nouns ("Post" → verb "post"), which dispatched a full mission
for a plain info question. Kept as a classifier for the refusal gate's
mirror logic and tests.
"""
if requires_external_integration(t):
return False
try:
from dodaios.core.capabilities import get_registry # type: ignore[import]
reg = get_registry()
if not getattr(reg, "all", lambda: ())():
return False
return bool(reg.has_action_intent(t) and reg.resolve_intent(t) is None)
except Exception: # noqa: BLE001 — registry error must not block spawn decision
return False
def _research_wants_artifact(self, t: str) -> bool:
"""True iff a (heavy-research) request asks for a BUILT ARTIFACT — a
file / report / document — rather than a spoken/written ANSWER.
Option A (2026-06-15): research whose deliverable is an ANSWER goes
INLINE via the router's search_web tool (fast, no critic friction);
research that builds a verifiable file OFFLOADS to a mission (the
Worker->Critic pipeline grades artifacts via git diff). The
discriminator: a named file / "into a file" instruction on its own, OR a
build/produce verb paired with a document noun. A research/analysis verb
(recherchier/analysier/compare/...) is NOT a build verb, so "research X
and compare Y" (an answer) does not match — it stays inline. Pure regex
(AP-11 safe, cross-platform); empty/blank text → False.
"""
text = t or ""
if not text.strip():
return False
if _NAMED_FILE_RE.search(text):
return True
return bool(_BUILD_VERB_RE.search(text) and _DOC_NOUN_RE.search(text))
def _heavy_worker_provider_viable(self) -> bool:
"""True when a heavy-worker backend can run a force-spawn, decoupled from
the talker provider (``brain.primary``).
The worker is ``[brain.sub_jarvis].provider`` (dodaios/missions/init.py
``_select_subagent_worker_kind``) and is chosen independently of which
provider talks to the user. A configured worker provider always maps to a
real worker (claude-api -> ClaudeDirectWorker, codex -> CodexDirectWorker,
else the Jarvis-Agent/default path), so it is viable for ANY talker — this is
what lets the user switch ``brain.primary`` to gemini / openai / codex
without silencing every action request (AP-6: never couple routing to a
hardcoded talker provider).
Only the LEGACY no-worker-configured path keeps the conservative
``brain.primary in {claude-api, gemini}`` check, because there the mission
factory may fall back to the Gemini API worker, which 403s on an account
without Gemini access (the original BUG-017, 2026-05-13)."""
try:
sub = getattr(self._config.brain, "worker", None)
worker_provider = (getattr(sub, "provider", "") or "").strip().lower()
except Exception: # noqa: BLE001 — config hiccup must not block dispatch
return True
if worker_provider:
return True
try:
primary = (self._config.brain.primary or "").strip().lower()
except Exception: # noqa: BLE001
primary = ""
return primary in ("claude-api", "gemini")
async def _honest_failure_readback(
self,
result: Any,
*,
user_text: str,
situation: str,
generic_key: str,
reason_key: str,
lang: str | None = None,
) -> str:
"""Honest, localized, opaque-token-free spoken readback for a FAILURE.
The single place every deterministic failure path (the DIRECT local
action, the force-spawn, the leaked-spawn / leaked-tool recovery) turns a
failed ``ToolResult`` into something speakable. It guarantees the user
NEVER hears the raw ``ToolResult.error`` — which is routinely the opaque
``"exit N"`` token (``dispatch_to_harness`` → ``f"exit {code}"``) that was
read out verbatim before (live forensic 2026-06-28: a harness failure was
spoken as the bare "exit 1").
It mirrors the Computer-Use path (:func:`cu_failure_readback`):
1. Pull a *human* reason from the result (stderr/stdout/error) via
:func:`extract_speakable_reason` — a bare ``exit N`` / numeric /
diagnostic token yields ``None``.
2. Route through the context-aware readback composer so the spoken line
reacts to THIS situation (no stock phrasing, the maintainer's
standing requirement) — handing it ONLY the clean reason as a fact,
never the opaque token.
3. Fall back to a localized canned phrase (de/en/es) — the reason
variant when a clean reason exists, the generic one otherwise — so an
en/es turn never gets a hardcoded German string and a failure is
never silently dropped.
"""
lang = lang or self._direct_ack_language(user_text)
reason = extract_speakable_reason(
getattr(result, "error", None), getattr(result, "output", None)
)
if reason:
facts: dict[str, object] | None = {"reason": reason}
instruction = f"{situation} The reason given was: {reason}"
# The composer rephrases the English cause itself — but only while
# it has a live model. The canned floor gets the cause already in
# the turn's language, so a dead flash slot cannot produce a
# half-translated sentence (live 2026-08-20: the Gemini ack slot
# answered 404 and then 429, and every readback came out canned).
spoken_reason = localize_failure_reason(reason, lang)
canned = lambda: action_phrase( # noqa: E731
reason_key, lang, reason=spoken_reason
)
else:
facts = None
instruction = situation
canned = lambda: action_phrase(generic_key, lang) # noqa: E731
return await render_readback(
getattr(self, "_readback_composer", None),
instruction=instruction,
language=lang,
canned=canned,
facts=facts,
)
def _cu_goal_with_context(self, goal: str) -> str:
"""Append bounded recent conversation context to a Computer-Use goal.
The deterministic local-action gate ships the raw current utterance as
the mission goal. Without the turns that defined the task, a follow-up
or correction turn hands the loop a vacuous goal and the verifier
passes against it (live forensic 2026-07-15 07:59: after a failed
Discord-announcement mission, "Ihr macht es doch mit Computer-Use." # i18n-allow: quoted German speech input from the forensic
became the whole goal — the loop opened Discord's Friends view and
announced success). Delegated turns carry their history in
``_TURN_HISTORY_OVERRIDE``; classic turns fall back to the live
``self._history``. No history → the goal stays bare.
"""
history = _TURN_HISTORY_OVERRIDE.get()
if history is None:
history = tuple(getattr(self, "_history", None) or ())
lines: list[str] = []
for message in history[-_CU_CONTEXT_MAX_MESSAGES:]:
role = "User" if getattr(message, "role", "") == "user" else "Assistant"
content = " ".join(str(getattr(message, "content", "") or "").split())
if not content:
continue
if len(content) > _CU_CONTEXT_MAX_MESSAGE_CHARS:
content = f"{content[:_CU_CONTEXT_MAX_MESSAGE_CHARS]} …"
lines.append(f"{role}: {content}")
if not lines:
return goal
context = "\n".join(lines)
return (
f"{goal}\n\n"
"CONVERSATION CONTEXT (recent turns, oldest first — the goal above "
"may refer back to these):\n"
f"{context}"
)
async def _run_local_action_fast_path(
self,
user_text: str,
*,
trace_id: UUID | None = None,
) -> str | None:
"""Execute narrow local actions before vision/provider work.
The tools used here are intentionally hidden from ``self._tools`` so
they never appear in the router LLM schema.
"""
if _TURN_OVERRIDE.get() is not None:
# Scoped chats must use their selected tools and approval context,
# not the voice shortcut's global desktop/browser tool set.
return None
local_cfg = getattr(self._config, "local_action", None)
if local_cfg is not None and not getattr(local_cfg, "enabled", True):
return None
if self._tool_executor is None:
return None
plan = match_local_action(
user_text,
lang=self._spoken_reply_language(user_text),
live_tool_names=self._live_tool_names(),
)
if plan is None:
return None
tid = trace_id or uuid4()
if plan.mode == LocalActionMode.UNSUPPORTED:
# The gate recognised an action request but no registered capability
# covers it. Speak its deterministic rejection (response_text)
# instead of dropping it and leaving the user with silence — the
# gate docstring mandates "route straight to TTS, skipping brain".
# Without this branch the plan fell through to `return None` and the
# rejection copy was lost.
return plan.response_text or None
if plan.mode == LocalActionMode.DIRECT:
outputs: list[str] = []
timeout_s = float(getattr(local_cfg, "direct_timeout_s", 3.0))
# The DIRECT path surfaces tool output verbatim (no LLM re-render),
# so the spoken acknowledgement must be localized HERE — the
# language pin/detection that governs LLM replies never reaches it.
ack_lang = self._direct_ack_language(user_text)
for call in plan.tool_calls:
tool = self._local_action_tools.get(call.name)
if tool is None:
return None
try:
result = await asyncio.wait_for(
self._tool_executor.execute(
tool,
dict(call.args),
user_utterance=user_text,
trace_id=tid,
),
timeout=timeout_s,
)
except TimeoutError:
await self._bus.publish(ActionExecuted(
trace_id=tid,
tool_name=call.name,
success=False,
duration_ms=int(timeout_s * 1000),
error=f"timeout after {timeout_s:.3g}s",
))
# Never speak the internal tool name + machine "timeout after
# 3s" string; a plain, localized line via the composer instead.
return await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"The action the user asked for took too long and was "
"stopped before it finished."
),
language=ack_lang,
canned=lambda: action_phrase("action_timeout", ack_lang),
)
if not result.success:
# NEVER return ``result.error`` verbatim — it is routinely the
# opaque ``exit N`` token (live forensic 2026-06-28: a harness
# failure was spoken as the bare "exit 1"). Route through the
# honest, localized, composer-backed readback instead.
return await self._honest_failure_readback(
result,
user_text=user_text,
situation=(
"An action the user asked for could not be completed."
),
generic_key="action_failed_generic",
reason_key="action_failed_reason",
lang=ack_lang,
)
if result.output is not None:
outputs.append(
self._localize_direct_ack(call, str(result.output), ack_lang)
)
return "\n".join(outputs)
if plan.mode == LocalActionMode.COMPUTER_USE:
tool = self._local_action_tools.get("dispatch_to_harness")
if tool is None:
# Never swallow this silently (contract §7): the gate matched a
# screen action but the fast path has no dispatcher. Falling
# through to the full brain turn is correct — the `computer_use`
# router tool carries its own preflight and speaks honestly —
# but the drop must be visible in the log, not invisible.
log.warning(
"CU fast path: 'dispatch_to_harness' is not registered in "
"_local_action_tools; handing the request to the brain turn "
"instead of running it deterministically (trace=%s)",
tid,
)
return None
# Resolve the turn language ONCE here (while it is current) for the
# availability refusal, the spoken cost messages, the immediate ACK,
# and the background readback — the offloaded task runs after the
# turn returns and must not read the per-turn state itself (live bug
# 2026-06-15).
cu_lang = self._direct_ack_language(user_text)
# Availability preflight (GT-19). The harness only works once the
# app wired its ComputerUseContext, and that happens only when
# [computer_use].enabled AND a vision engine exist (factory.py).
# Unwired, every step died deep inside the harness — but the ACK
# below had already promised "Mach ich", so the user heard a
# commitment, then nothing, then a failure up to 180 s later. Peek
# the singleton BEFORE dispatching and refuse immediately and
# honestly instead. Same guard the LLM tool path uses
# (plugins/tool/computer_use_tool.py::execute).
from dodaios.harness.computer_use_context import ( # noqa: PLC0415
peek_computer_use_context,
)
if peek_computer_use_context() is None:
log.warning(
"CU fast path: computer-use is not wired on this machine "
"([computer_use].enabled false or no vision engine); "
"refusing the screen action instead of acknowledging it "
"(trace=%s)",
tid,
)
return await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"Desktop control is switched off on this machine, so "
"you cannot do anything on the screen right now. It is "
"turned on with the config value "
"computer_use.enabled=true, followed by a restart."
),
language=cu_lang,
canned=lambda: action_phrase("cu_not_wired", cu_lang),
latency_budget_ms=900,
)
# A multi-step CU mission ("navigate to amazon, search, click") needs a
# generous OUTER cap — the harness has its own per-step timeout +
# step-budget + no-progress/consecutive-failure guards, so this is only
# a backstop. The old 30 s ``harness_timeout_s`` aborted legit
# multi-step missions; the router-tool path already used 120 s. The
# mission is OFFLOADED (immediate ACK), so a longer cap never blocks
# the spoken turn. Honour a larger configured value if set.
_configured_timeout = float(getattr(local_cfg, "harness_timeout_s", 30.0))
timeout_s = max(_configured_timeout, 180.0)
if _configured_timeout < 180.0:
log.debug(
"CU offload: harness_timeout_s=%.0fs raised to 180s floor "
"(offloaded multi-step mission; harness has its own per-step + "
"step-budget + no-progress guards)",
_configured_timeout,
)
if self._cost_meter is not None:
if self._cost_meter.is_in_cooldown():
return await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"A cost cooldown is active: the daily budget is used "
"up, so new requests resume only after the cooldown ends."
),
language=cu_lang,
canned=lambda: action_phrase("cost_cooldown", cu_lang),
)
if self._cost_meter.over_task_budget(tid):
return await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"The task budget for this conversation has been exceeded."
),
language=cu_lang,
canned=lambda: action_phrase("task_budget", cu_lang),
)
if self._cost_meter.over_daily_budget():
return await render_readback(
getattr(self, "_readback_composer", None),
instruction="The daily budget has been exceeded.",
language=cu_lang,
canned=lambda: action_phrase("daily_budget", cu_lang),
)
# Wave-4 latency fix: Computer-Use is OFFLOADED off the voice turn.
# Previously the harness was awaited inline for up to ~31 s, so a
# "do it on screen" command froze the spoken turn the whole time.
# Now we launch the harness as a BACKGROUND task and return an
# immediate ACK (AD-OE1); its outcome — success, failure, or timeout
# — is spoken at the next turn boundary via an
# AnnouncementRequested(kind="completion") readback (AD-OE5/OE6, zero
# silent drops). Harness identity comes from the gate; fall back to
# the canonical in-process harness name (routes to ComputerUseHarness,
# never a claude-cli worker spawn).
#
# Note: the result readback rides the announcement bus, which the
# voice pipeline speaks. A text-chat-initiated Computer-Use command
# therefore still executes and is ACK'd, but its result lands as a
# voice announcement rather than in the chat transcript — an
# acceptable trade for never freezing the spoken turn.
# HARNESS_NAME ("screenshot") is the REGISTERED in-process CU harness
# entry-point; "computer-use" is the router-tool name, NOT a harness,
# so the old fallback would KeyError in HarnessManager if plan.harness
# were ever empty. The gate always sets plan.harness=HARNESS_NAME, so
# this is hygiene — but use the correct constant (review 2026-06-09).
harness_name = plan.harness or HARNESS_NAME
bg_tasks = getattr(self, "_cu_background_tasks", None)
if bg_tasks is None:
bg_tasks = set()
self._cu_background_tasks = bg_tasks
task = asyncio.create_task(
self._run_computer_use_background(
tool=tool,
harness_name=harness_name,
# A follow-up/correction turn carries no task of its own —
# the goal inherits the recent turns that defined it.
prompt=self._cu_goal_with_context(plan.prompt or user_text),
timeout_s=timeout_s,
user_text=user_text,
trace_id=tid,
lang=cu_lang,
),
name="computer-use-background",
)
# Keep a strong reference so the task is not garbage-collected
# mid-flight, and drop it on completion.
bg_tasks.add(task)
task.add_done_callback(bg_tasks.discard)
# Optimistic ACK (AD-OE1). On the turn-critical path, so a TIGHT
# latency budget with the canned line as the instant fallback keeps
# intent->ACK well under SLO. in_progress=True: the work has not
# started, so a completion claim is rejected.
return await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"You are about to carry out the user's request directly on "
"the screen, in the background, and will report back when done."
),
language=cu_lang,
canned=lambda: action_phrase("cu_dispatch_ack", cu_lang),
facts={"user_request": user_text},
in_progress=True,
latency_budget_ms=900,
)
return None
@staticmethod
def _cu_failure_detail(output: Any) -> tuple[int | None, str | None]:
"""Pull ``(exit_code, human_detail)`` out of a CU harness failure result.
``dispatch_to_harness`` returns ``output`` as a dict with ``exit_code``
plus ``stderr``/``stdout`` — and the screenshot loop writes the model's
real ``fail`` reason into ``stderr`` (``"[cu] fail at <tag>: <reason>"``).
We surface that reason so the readback can forward it instead of the
opaque ``error="exit N"``. Best-effort: any non-dict / missing field
yields ``(None, None)`` and the readback degrades to the exit-code phrase.
"""
if not isinstance(output, dict):
return None, None
raw_code = output.get("exit_code")
exit_code: int | None
try:
exit_code = int(raw_code) if raw_code is not None else None
except (TypeError, ValueError):
exit_code = None
stderr = str(output.get("stderr") or "").strip()
stdout = str(output.get("stdout") or "").strip()
detail = stderr or stdout or None
return exit_code, detail
@staticmethod
def _cu_failure_diagnostic(
*, error: str | None, exit_code: int | None, detail: str | None
) -> str | None:
"""Compose the technical failure note for the TRANSCRIPT (never spoken).
The voice readback is humanized via ``cu_failure_readback`` ("…didn't
work on screen") — but the raw signal (the exit code plus the harness
reason) is still valuable for debugging, so it is carried alongside on
``AnnouncementRequested.detail`` -> ``SpeechSpoken.detail`` and shown in
the Transcription view (user request 2026-06-16). Returns None when
there is nothing diagnostic to record (e.g. a successful run). Capped so
the persisted payload stays small.
"""
base = (error or "").strip() or (
f"exit {exit_code}" if exit_code is not None else ""
)
reason = (detail or "").strip()
note = f"{base} · {reason}" if base and reason else (base or reason)
note = note.strip()
return note[:300] if note else None
async def _run_computer_use_background(
self,
*,
tool: Any,
harness_name: str,
prompt: str,
timeout_s: float,
user_text: str,
trace_id: UUID,
lang: str,
) -> None:
"""Run the Computer-Use harness off the voice turn and speak the result.
Launched fire-and-forget by ``_run_local_action_fast_path`` so the spoken
turn ACKs immediately (AD-OE1) instead of blocking up to ~31 s on the
harness. The outcome — success, failure, or timeout — is ALWAYS surfaced
as an ``AnnouncementRequested(kind="completion")`` readback
(AD-OE5/OE6: zero silent drops). Never raises — a background-task crash
must not leak into the event loop.
``lang`` is captured at dispatch and threaded in: this task runs AFTER
the turn returns, so ``self._turn_detected_lang`` may already belong to a
later turn — reading it here would speak the wrong language (live bug
2026-06-15: an English CU turn ended with the German "Erledigt.").
"""
text: str
# Technical failure note for the transcript (never spoken). Stays None
# on success; the failure branch fills it with the exit code + reason.
diag: str | None = None
try:
result = await asyncio.wait_for(
self._tool_executor.execute(
tool,
{
"harness": harness_name,
"prompt": prompt,
"timeout_s": timeout_s,
# Thread the turn's language to the in-harness verifier so
# its spoken `proof` matches the frame's language (live bug
# 2026-06-27: a German turn read back an English proof).
"env": {OUTPUT_LANGUAGE_ENV_KEY: lang},
},
user_utterance=user_text,
trace_id=trace_id,
),
timeout=timeout_s + 1.0,
)
if result.success:
# FORWARD the verifier's on-screen observation (sitting in the
# harness stdout) as the readback so an informational request
# ("...and check which tabs I have open") is actually answered —
# and NEVER ``str()`` the raw ``dispatch_to_harness`` result DICT
# ({'harness': ..., 'exit_code': ..., 'stdout': ..., 'cost_usd':
# ..., 'duration_ms': ...}), which used to leak verbatim into the
# spoken/chat turn (live bug 2026-06-22, voice "geh in die
# Einstellungen und öffne Bluetooth"; the scrubbed ``''`` key was
# the blacklisted word "harness"). This is the SUCCESS sibling of
# the ``cu_failure_readback`` humanization below and uses the same
# static parse as the ``computer_use`` tool path — no LLM (AP-11).
output = getattr(result, "output", None)
stdout = output.get("stdout") if isinstance(output, dict) else None
# The canned success line ALREADY forwards the verifier's signed
# on-screen observation (or a plain "Done."). Use it as the
# deterministic ground truth and let the composer only make it
# sound natural — honesty_bound so it can rephrase but never
# invent a detail the verifier did not report (ADR-0009). Off the
# turn path, so a generous budget; instant canned fallback.
canned_success = cu_success_readback(lang, stdout=stdout)
text = await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"The user's on-screen request just succeeded; tell them "
"naturally, keeping any on-screen detail that was observed."
),
language=lang,
canned=lambda: canned_success,
facts={"user_request": user_text, "result": canned_success},
honesty_bound=True,
latency_budget_ms=2500,
)
else:
err = getattr(result, "error", None)
exit_code, detail = self._cu_failure_detail(
getattr(result, "output", None)
)
# A user-initiated cancel (exit 130 — "auflegen" tripped the CU
# cancel token) is NOT an outcome the user is waiting on: it is
# the receipt of an abort they just triggered themselves. Speaking
# "the action was cancelled" is redundant, and — because the
# completion readback punches through the hangup gate (AD-OE5/OE6)
# and each offloaded mission cancels independently — it spams the
# phrase once per in-flight mission (live forensic 2026-06-27:
# three CU missions cancelled by one F1+F2 hangup spoke it three
# times). "auflegen" is a hard, immediately-silent kill-switch, so
# drop the readback entirely. AD-OE6's zero-silent-drop guards
# real outcomes (success / content failure / timeout) — those
# still announce below — not a self-triggered abort.
if exit_code == CU_CANCEL_EXIT_CODE:
log.info(
"CU background cancelled by user hangup (exit %d) — "
"no readback (auflegen = silent kill-switch)",
CU_CANCEL_EXIT_CODE,
)
return
canned_failure = cu_failure_readback(
lang, error=err, exit_code=exit_code, detail=detail,
)
# The canned failure line is already humanized + scrubbed (no raw
# exit code, only a speakable reason). Rephrase it naturally,
# honesty_bound so the spoken reason stays faithful to what the
# harness actually reported. Instant canned fallback.
text = await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"The user's on-screen request did not work; tell them "
"plainly and kindly, keeping any reason that was given."
),
language=lang,
canned=lambda: canned_failure,
facts={"user_request": user_text, "what_happened": canned_failure},
# Not a signed observation (ADR-0009 binds success readbacks);
# the digit + forbidden-vocab guards + strict persona keep it
# honest while allowing a natural failure phrasing.
honesty_bound=False,
latency_budget_ms=2500,
)
diag = self._cu_failure_diagnostic(
error=err, exit_code=exit_code, detail=detail,
)
except TimeoutError:
_secs = f"{timeout_s:.0f}"
text = await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"The on-screen task took too long and was stopped after "
f"{_secs} seconds."
),
language=lang,
canned=lambda: action_phrase("cu_timeout", lang, secs=_secs),
facts={"seconds": _secs},
latency_budget_ms=2000,
)
try:
await self._bus.publish(ActionExecuted(
trace_id=trace_id,
tool_name="dispatch_to_harness",
success=False,
duration_ms=int((timeout_s + 1.0) * 1000),
error=f"timeout after {timeout_s:.3g}s",
))
except Exception: # noqa: BLE001
log.debug("CU-background ActionExecuted publish failed", exc_info=True)
except Exception as exc: # noqa: BLE001 — a background crash must not leak
log.error("Computer-Use background task failed: %r", exc, exc_info=True)
text = await render_readback(
getattr(self, "_readback_composer", None),
instruction="Something went wrong while doing the task on screen.",
language=lang,
canned=lambda: action_phrase("cu_crashed", lang),
latency_budget_ms=2000,
)
# Ground the finished outcome in the LIVE conversation history so the
# model's NEXT turn knows the on-screen action ran and how it ended.
# The outcome is offloaded fire-and-forget and only ever rode the
# announcement bus (spoken, then gone) — it never re-entered _history,
# so the model believed the screen action SUCCEEDED (it saw only the
# optimistic ACK) and answered a follow-up "why didn't it work?" against
# a stale unrelated error (live forensic 2026-06-30: a failed Spotify
# screen action was explained with an old Google-Calendar auth error).
self._append_cu_outcome_to_history(
user_request=user_text, outcome_text=text, diagnostic=diag,
)
# AD-OE6 zero silent drops: ALWAYS speak the outcome at the next turn
# boundary (announcement -> scrub_for_voice -> TTS).
try:
await self._bus.publish(AnnouncementRequested(
text=text,
priority="normal",
language=lang,
# A background Computer-Use task reports the user's requested
# desktop action as the turn completion.
kind="completion",
detail=diag,
))
except Exception: # noqa: BLE001
log.debug("CU-background completion announce failed", exc_info=True)
def _append_cu_outcome_to_history(
self,
*,
user_request: str,
outcome_text: str,
diagnostic: str | None,
context_label: str = "on-screen-action",
) -> None:
"""Ground a finished background Computer-Use outcome in the live history.
A desktop action is offloaded fire-and-forget, so its outcome lands AFTER
the optimistic ACK ("On it, I'll do that on screen") was already appended
as the turn's assistant message. Without this, ``_history`` shows only the
ACK and the model never learns whether the screen action actually
succeeded — so a later "why didn't it work?" is answered against whatever
OTHER failure is still in context (live forensic 2026-06-30: a failed
Spotify screen action was explained with a stale Google-Calendar auth
error). Append an honest assistant note carrying the spoken outcome PLUS
the real technical reason — which the humanized spoken readback hides — so
the next turn is grounded in what actually happened. Pure in-memory
append, no LLM, no IO (off the hot path anyway). ``user_request`` is
accepted for call-site symmetry/debuggability; the ACK already names the
request in history, so the note stays compact.
"""
history = getattr(self, "_history", None)
if history is None:
return
spoken = (outcome_text or "").strip()
diag = (diagnostic or "").strip()
if not spoken and not diag:
return
note = spoken
if diag:
# The spoken readback is humanized to "didn't work on screen"; the
# model needs the REAL cause to answer a follow-up honestly. Mark it
# clearly as a non-spoken background detail so the model treats it as
# context, not as something it already said aloud.
note = (
f"{note}\n\n(Background {context_label} detail, not spoken aloud "
f"— for your context on a follow-up: {diag})"
).strip()
history.append(BrainMessage(role="assistant", content=note))
if len(history) > self._HISTORY_MAX:
self._history = history[-self._HISTORY_MAX:]
def _last_exchange_text(self) -> str | None:
"""Last user+assistant exchange as an ingest source ('write THAT').
``_history`` entries are real :class:`BrainMessage` instances —
``role`` is one of ``user``/``assistant``/``system``/``tool`` and
``content`` is either a plain string or a list of multimodal blocks
(dropped images etc.). Only plain-string user/assistant turns are
usable ingest source text; anything else is skipped, never raises.
"""
try:
items = list(self._active_turn_history())[-4:]
except Exception: # noqa: BLE001 — history shape is provider-owned
return None
parts: list[str] = []
for item in items:
role = getattr(item, "role", None)
text = getattr(item, "content", None)
if role in ("user", "assistant") and isinstance(text, str) and text.strip():
parts.append(f"{role}: {text.strip()}")
return "\n".join(parts[-2:]) or None
def _active_turn_history(self) -> list[BrainMessage]:
"""Return the context-local history when a caller supplied one."""
override = _TURN_HISTORY_OVERRIDE.get()
return list(override) if override is not None else self._history
async def _persisted_session_exchange_text(self) -> str | None:
"""Return the latest persisted exchange from the active voice session.
Realtime deliberately owns a small context-local history instead of
sharing ``self._history``. On its first delegated turn that history can
therefore be empty even though the session recorder already contains a
previous transcript. Resolve the existing live runtime objects lazily
and require an active session id before reading: an unscoped "latest"
lookup could copy text from a different conversation into the Wiki.
The runtime objects are intentionally accessed through
:mod:`dodaios.core.runtime_refs`; the brain layer neither imports the web
server nor depends on the concrete ``SessionStore`` type. Any partially
bootstrapped/headless runtime degrades to ``None``.
"""
try:
from dodaios.core import runtime_refs
pipeline = runtime_refs.get_speech_pipeline()
status_fn = getattr(pipeline, "voice_engine_status", None)
status = status_fn() if callable(status_fn) else {}
session_id = str(status.get("session_id") or "").strip()
if not session_id:
return None
app = runtime_refs.get_web_app()
store = getattr(getattr(app, "state", None), "session_store", None)
get_latest = getattr(store, "get_latest_user_turn", None)
if not callable(get_latest):
return None
turn = await asyncio.to_thread(get_latest, session_id=session_id)
except Exception: # noqa: BLE001 - persisted context is a soft fallback
log.debug("Persisted session-history lookup failed", exc_info=True)
return None
parts: list[str] = []
for role, value in (
("user", getattr(turn, "user_text", None)),
("assistant", getattr(turn, "jarvis_text", None)),
):
if isinstance(value, str) and value.strip():
parts.append(f"{role}: {value.strip()}")
return "\n".join(parts) or None
async def _run_wiki_ingest_fast_path(
self,
user_text: str,
*,
trace_id: UUID | None = None,
use_history: bool = True,
) -> str | None:
"""Deterministic explicit wiki-write path (spec A1-A3).
Explicit "write this to the wiki" commands must not depend on the
router LLM picking ``wiki-ingest`` (fresh-machine forensics Bug
12/18). Mirrors the Computer-Use offload: immediate localized
progress ack, background ingest, completion announcement AFTER the
write — the success phrase is generated from the tool result, so
it can never precede (or contradict) the file on disk.
"""
from dodaios.memory.wiki.intent import match_wiki_intent
if self._tool_executor is None:
return None
match = match_wiki_intent(
user_text,
prior_text=self._previous_user_turn_text(use_history=use_history),
)
if match is None:
return None
tool = self._tools.get("wiki-ingest")
if tool is None:
return None
lang = self._direct_ack_language(user_text)
content = match.content
if content is None:
content = self._last_exchange_text()
if content is None:
content = await self._persisted_session_exchange_text()
if not content or len(content.strip()) < 12:
return await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"The user asked to write something to the wiki but no "
"content could be determined; ask them to repeat it "
"with the content."
),
language=lang,
canned=lambda: action_phrase("wiki_nothing_to_save", lang),
)
tid = trace_id or uuid4()
bg_tasks = getattr(self, "_cu_background_tasks", None)
if bg_tasks is None:
bg_tasks = set()
self._cu_background_tasks = bg_tasks
task = asyncio.create_task(
self._run_wiki_ingest_background(
tool=tool,
text=content,
user_text=user_text,
trace_id=tid,
lang=lang,
),
name="wiki-ingest-background",
)
# Keep a strong reference so the task is not garbage-collected
# mid-flight, and drop it on completion (same pattern as the
# Computer-Use offload above — one shared retention set).
bg_tasks.add(task)
task.add_done_callback(bg_tasks.discard)
return await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"Briefly acknowledge that you are writing this to the wiki "
"right now. Do NOT claim it is already saved."
),
language=lang,
canned=lambda: action_phrase("wiki_saving", lang),
in_progress=True,
)
@staticmethod
def _short_wiki_failure_reason(diag: str | None) -> str:
"""Distil a wiki-ingest failure diagnostic into a short spoken cause.
Keeps only the first line/sentence, strips a bare ``exit N``-style
opaque token (a raw exit code must never be spoken — mirror of
``cu_failure_readback``'s guard), and caps the length so the failure
phrase stays one short clause. Returns ``""`` when nothing
presentable remains, in which case the caller falls back to the
reason-less ``wiki_save_failed`` phrase.
"""
raw = (diag or "").strip()
if not raw:
return ""
# First line, then the first sentence within that line.
first_line = raw.splitlines()[0].strip()
m = re.match(r"^(.*?[.!?])(?:\s|$)", first_line)
reason = (m.group(1) if m else first_line).strip()
# Strip a bare "exit N" opaque token (optionally bracketed) — never
# speak a raw exit code.
reason = re.sub(
r"\(?\s*exit\s*\d+\s*\)?", "", reason, flags=re.IGNORECASE
).strip(" .,:;-")
if len(reason) > 80:
reason = reason[:80].rstrip()
return reason
async def _run_wiki_ingest_background(
self,
*,
tool: Any,
text: str,
user_text: str,
trace_id: UUID,
lang: str,
) -> None:
"""Run wiki-ingest off the voice turn and announce the outcome.
Never raises; ALWAYS announces (zero silent drops) — mirrors
:meth:`_run_computer_use_background`. Nothing here is
user-cancellable, so there is no cancel branch.
"""
out: str
diag: str | None = None
try:
result = await asyncio.wait_for(
self._tool_executor.execute(
tool,
{"text": text, "source": "voice:wiki-command"},
user_utterance=user_text,
trace_id=trace_id,
),
timeout=90.0,
)
if result.success:
pages = ", ".join(
line.strip(" -")
for line in str(result.output or "").splitlines()
if line.strip().startswith("- ") and line.strip().endswith(".md")
)
canned_ok = (
action_phrase("wiki_saved_detail", lang, detail=pages)
if pages else action_phrase("wiki_saved", lang)
)
out = await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"The user's note was just written to their wiki; "
"confirm naturally, keeping the page name if given."
),
language=lang,
canned=lambda: canned_ok,
facts={"user_request": user_text, "result": canned_ok},
honesty_bound=True,
latency_budget_ms=2500,
)
else:
err = str(getattr(result, "error", "") or "").strip()
diag = err or "unknown"
# Keyless (canned) failure path is honest-with-cause: surface a
# short, speakable reason (mirrors wiki_saved_detail on success).
# The composer still gets the FULL diag via facts below.
short_reason = self._short_wiki_failure_reason(err)
canned_fail = (
action_phrase("wiki_save_failed_reason", lang, reason=short_reason)
if short_reason
else action_phrase("wiki_save_failed", lang)
)
out = await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"Writing the user's note to the wiki failed; tell "
"them plainly, keep the reason simple, and mention "
"they can check the wiki settings."
),
language=lang,
canned=lambda: canned_fail,
facts={"user_request": user_text, "what_happened": diag},
honesty_bound=False,
latency_budget_ms=2500,
)
except TimeoutError:
diag = "wiki-ingest timeout after 90s"
out = await render_readback(
getattr(self, "_readback_composer", None),
instruction="Writing the note to the wiki took too long and was stopped.",
language=lang,
canned=lambda: action_phrase("wiki_save_failed", lang),
latency_budget_ms=2000,
)
except Exception as exc: # noqa: BLE001 — background crash must not leak
log.error("wiki-ingest background task failed: %r", exc, exc_info=True)
diag = repr(exc)
out = await render_readback(
getattr(self, "_readback_composer", None),
instruction="Something went wrong while writing the note to the wiki.",
language=lang,
canned=lambda: action_phrase("wiki_save_failed", lang),
latency_budget_ms=2000,
)
self._append_cu_outcome_to_history(
user_request=user_text, outcome_text=out, diagnostic=diag,
)
try:
await self._bus.publish(AnnouncementRequested(
text=out,
priority="normal",
language=lang,
kind="completion",
detail=diag,
))
except Exception: # noqa: BLE001
log.debug("wiki-ingest completion announce failed", exc_info=True)
async def _on_cu_tool_completion(self, event: Any) -> None:
"""Mirror trusted asynchronous outcomes into the live brain history.
The voice fast-path grounds its CU outcome inline (``_run_computer_use_
background`` → :meth:`_append_cu_outcome_to_history`). The router-tier
``computer_use`` tool runs in its own module with NO ``_history`` access,
so it tags its completion announcement with
``source_layer=CU_TOOL_OUTCOME_LAYER`` and we mirror it here — same
grounding, so a text-chat / router-picked desktop action is in the
model's next-turn context too. A ``kind="subagent"`` event is the signed
terminal Jarvis-Agent readback and is also retained, including its
mission id/result URI, so a later question can retrieve the real files.
Other background announcements remain ignored.
Never raises — a bus subscriber that throws would break the pipeline
(AP-18). The fast-path leaves ``source_layer`` empty, so its outcome is
NOT double-recorded here.
"""
try:
source_layer = getattr(event, "source_layer", "")
kind = getattr(event, "kind", None)
if source_layer == CU_TOOL_OUTCOME_LAYER:
outcome_text = getattr(event, "text", "") or ""
context_label = "on-screen-action"
elif kind == "subagent":
# Label with the wake-word-derived brand: the model quotes this
# context in spoken answers, so a fixed product name would leak.
try:
from dodaios.brain.assistant_name import agent_brand
from dodaios.core.config import load_config
brand = agent_brand(load_config())
except Exception: # noqa: BLE001 — labeling must not break the mirror
from dodaios.brain.assistant_name import agent_brand_from_name
brand = agent_brand_from_name("")
outcome_text = (
f"{brand} mission result: "
f"{getattr(event, 'text', '') or ''}"
)
context_label = f"{brand} mission"
else:
return
self._append_cu_outcome_to_history(
user_request="",
outcome_text=outcome_text,
diagnostic=getattr(event, "detail", None),
context_label=context_label,
)
except Exception: # noqa: BLE001
log.debug("Background completion history mirror failed", exc_info=True)
async def _record_response_side_effects(
self,
*,
user_text: str,
response_text: str,
use_history: bool,
trace_id: UUID | None = None,
) -> None:
"""Apply the normal response side effects for non-provider paths too."""
if use_history:
self._history.append(BrainMessage(role="user", content=user_text))
self._history.append(BrainMessage(role="assistant", content=response_text))
if len(self._history) > 40:
self._history = self._history[-40:]
await self._publish_response_generated(
trace_id=trace_id or uuid4(),
text=response_text,
)
if self._curator is not None and not (
(profile_override := _TURN_OVERRIDE.get()) is not None
and profile_override.tool_context.get("tool_origin") == "society"
):
try:
asyncio.create_task(
self._curator.process_turn(user_text, response_text),
name="curator-process-turn",
)
except RuntimeError:
log.debug("Curator-Task nicht scheduled (kein Event-Loop)")
def has_pending_voice_confirm(self) -> bool:
"""True while a two-turn voice confirmation is awaiting the user's yes/no.
The speech pipeline consults this in ``_finish_after_response`` to keep
the session open until the answer lands — otherwise (in single-turn mode)
the turn finalizes and hangs up before the user can say "ja" (forensic
2026-06-26). Mirrors how ``_background_mission_in_flight`` keeps a running
mission's session alive.
"""
screen_pending = getattr(self, "_pending_screen_confirms", {})
if screen_pending:
now = time.monotonic()
expired = [
key
for key, pending in screen_pending.items()
if pending.expires_at <= now
]
for key in expired:
screen_pending.pop(key, None)
voice_screen_pending = any(
surface == "voice" for surface, _conversation_id in screen_pending
)
return self._pending_voice_confirm is not None or voice_screen_pending
async def _resolve_screen_context_turn(
self,
user_text: str,
*,
source_layer: str | None,
conversation_id: str | None,
allow_voice_confirm: bool,
trace_id: UUID,
) -> Any:
"""Resolve a one-shot screen look and its optional next-turn consent.
Screen consent is isolated by conversation surface and expires quickly.
A bare confirmation can therefore authorize only the proposal the user
just heard on that same surface; unrelated text drops the proposal and
continues as a normal turn.
"""
from dodaios.screen_context.intent import ( # noqa: PLC0415
cancelled_reply,
clarifying_question,
)
from dodaios.screen_context.turn import ( # noqa: PLC0415
TurnScreenContext,
screen_context_for_turn,
)
confirm_key = self._screen_confirm_key(
source_layer=source_layer,
conversation_id=conversation_id,
allow_voice_confirm=allow_voice_confirm,
)
pending_map = getattr(self, "_pending_screen_confirms", None)
if pending_map is None:
pending_map = self._pending_screen_confirms = {}
pending = pending_map.get(confirm_key)
now = time.monotonic()
if pending is not None and pending.expires_at <= now:
pending_map.pop(confirm_key, None)
pending = None
if pending is not None:
# Lazy import avoids pulling self-mod's confirmation graph into the
# brain manager at module import time.
from dodaios.voice.echo_confirmation import classify_response # noqa: PLC0415
verdict = classify_response(user_text, language=pending.lang)
if verdict == "confirm":
pending_map.pop(confirm_key, None)
return await screen_context_for_turn(
"",
locale=pending.lang,
bus=self._bus,
force=True,
trace_id=trace_id,
)
if verdict == "veto":
pending_map.pop(confirm_key, None)
return TurnScreenContext(
status="cancelled", message=cancelled_reply(pending.lang)
)
if verdict == "ambiguous":
pending.expires_at = now + _SCREEN_CONFIRM_TTL_S
return TurnScreenContext(
status="clarify", question=clarifying_question(pending.lang)
)
pending_map.pop(confirm_key, None)
locale = _turn_phrase_language(self, user_text)
outcome = await screen_context_for_turn(
user_text,
locale=locale,
bus=self._bus,
trace_id=trace_id,
allow_pending_appshot=_takes_pending_appshot(source_layer),
)
if outcome.status == "clarify":
pending_map[confirm_key] = _PendingScreenConfirm(
locale, now + _SCREEN_CONFIRM_TTL_S
)
return outcome
@staticmethod
def _screen_confirm_key(
*,
source_layer: str | None,
conversation_id: str | None,
allow_voice_confirm: bool,
) -> tuple[str, str]:
# The layer that NAMES itself wins. allow_voice_confirm used to decide
# this, which was fine only while voice was the sole surface passing
# it — desktop chat passes it too since 6e6287b9, so keying on the flag
# would drop both into one bucket and let a pending look proposal from
# one surface answer for the other.
surface = source_layer or ("voice" if allow_voice_confirm else "chat")
return (surface, conversation_id or "default")
def _has_pending_screen_confirm(
self,
*,
source_layer: str | None,
conversation_id: str | None,
allow_voice_confirm: bool,
) -> bool:
"""Return whether this exact conversation owns a live look proposal."""
key = self._screen_confirm_key(
source_layer=source_layer,
conversation_id=conversation_id,
allow_voice_confirm=allow_voice_confirm,
)
pending = self._pending_screen_confirms.get(key)
if pending is None:
return False
if pending.expires_at <= time.monotonic():
self._pending_screen_confirms.pop(key, None)
return False
return True
def _arm_voice_confirm(self, descriptor: dict[str, Any], user_text: str) -> None:
"""Turn N: record a deferred consequential action awaiting yes/no.
``descriptor`` is the tool-use loop's ``voice_confirm`` payload
(``{"trace_id": str, "tool_name": str}``). The language is resolved once
here (the turn's output language) and reused for both the classifier and
the outcome phrasing on turn N+1.
"""
trace_raw = descriptor.get("trace_id")
try:
tid = UUID(str(trace_raw))
except (ValueError, TypeError):
log.warning("voice-confirm: bad trace_id %r — not arming", trace_raw)
return
lang = _turn_phrase_language(self, user_text)
self._pending_voice_confirm = _PendingVoiceConfirm(
trace_id=tid, lang=lang, tool_name=str(descriptor.get("tool_name", "")),
)
log.info(
"voice-confirm armed: tool=%s trace=%s lang=%s",
self._pending_voice_confirm.tool_name, tid, lang,
)
async def _resume_voice_confirm(self, user_text: str) -> str | None:
"""Turn N+1: classify the user's yes/no and resolve the pending action.
Returns the spoken OUTCOME when the turn is consumed by the confirmation;
returns ``None`` when the pending action is dropped and the utterance must
be processed as a normal turn (the user said something unrelated — they
moved on, so the consequential action is abandoned, never executed).
"""
pending = self._pending_voice_confirm
if pending is None:
return None
# Lazy import: a top-level import of these would close a circular chain
# (dodaios.voice.echo_confirmation → dodaios.core.self_mod → writer →
# jarvis.brain → manager → echo_confirmation, half-initialized).
from dodaios.voice.echo_confirmation import classify_response
from dodaios.voice.tool_confirmation import format_confirm_outcome
verdict = classify_response(user_text, language=pending.lang)
if verdict == "confirm":
self._pending_voice_confirm = None
try:
result = await self._tool_executor.execute_confirmed(
pending.trace_id, user_utterance=user_text,
)
except Exception as exc: # noqa: BLE001
log.warning("voice-confirm execute failed: %s", exc)
# The user just said YES to this action; hearing only "that
# didn't work" leaves them nothing to correct with. The same
# opaque-token gate the result branch below relies on decides
# whether the exception text is speakable at all.
return format_confirm_outcome(
"failed",
pending.tool_name,
language=pending.lang,
detail=localize_failure_reason(
extract_speakable_reason(str(exc), None), pending.lang
)
or None,
)
kind = "done" if getattr(result, "success", False) else "failed"
return format_confirm_outcome(
kind,
pending.tool_name,
language=pending.lang,
detail=(
None
if kind == "done"
# Raw ``error`` is routinely the opaque ``exit N`` token the
# tool layer emits; the gate turns that into no detail at
# all rather than a machine word in the user's ear. There is
# no composer on this path at all, so the cause is localized
# deterministically or it stays English forever.
else localize_failure_reason(
extract_speakable_reason(
getattr(result, "error", None),
getattr(result, "output", None),
),
pending.lang,
)
or None
),
)
if verdict == "veto":
self._pending_voice_confirm = None
await self._cancel_pending_confirm(pending.trace_id)
return format_confirm_outcome(
"vetoed", pending.tool_name, language=pending.lang
)
if verdict == "ambiguous":
pending.reasks += 1
if pending.reasks > _MAX_CONFIRM_REASKS:
self._pending_voice_confirm = None
await self._cancel_pending_confirm(pending.trace_id)
return format_confirm_outcome(
"timeout", pending.tool_name, language=pending.lang
)
return format_confirm_outcome(
"unclear", pending.tool_name, language=pending.lang
)
# unknown: the user moved on. Drop the pending action (safe — never
# executed) and let this utterance run as a normal turn.
self._pending_voice_confirm = None
await self._cancel_pending_confirm(pending.trace_id)
return None
async def _cancel_pending_confirm(self, trace_id: UUID) -> None:
"""Best-effort cancel of a deferred action — never breaks the turn."""
try:
await self._tool_executor.cancel_pending(trace_id)
except Exception as exc: # noqa: BLE001
log.warning("voice-confirm cancel failed: %s", exc)
def _spoken_reply_language(self, user_text: str) -> str:
"""Language for a fixed spoken phrase this manager renders itself.
Resolved through the SAME call the router and every other spoken layer
make (``resolve_output_language`` with the pin, this turn's detected
language, the conversation stickiness and ``DEFAULT_LOCALE``), so a
canned phrase can never speak a different language than the reply
(AGENTS.md: the output language is decided once per turn).
"""
# getattr: lightweight managers built without __init__ (fakes, early
# boot paths) carry no turn state yet — that simply means "none known".
return _turn_phrase_language(self, user_text or "")
def _spawn_ack_language(self, user_text: str) -> str:
"""Resolve the language for the spoken spawn acknowledgement.
A pinned reply language (``brain.reply_language``, any supported
language) wins; otherwise detect from the user's words. The
spawn-announcement composer speaks every supported reply language;
undetectable text falls back to English, never German.
"""
return self._spoken_reply_language(user_text)
def _build_history_hints(
self,
*,
max_turns: int = 20,
max_chars_per_msg: int = 4_000,
) -> list[str]:
"""Formats the last N turn pairs as compact ``context_hints``.
Conversation memory bridge to the Jarvis-Agent worker (bug fix 2026-04-30,
wave-4 rebrand): the worker is architecturally stateless. Without this
bridge it does not know the previous turns, even when the user
explicitly refers to them ("erklaer mir das genauer",
"was war der zweite Punkt?").
One hint is emitted per user/assistant turn pair.
Truncated to ``max_chars_per_msg`` to prevent long replies from
bloating the worker context.
"""
history = self._active_turn_history()
if not history:
return []
recent = history[-(2 * max_turns):]
hints: list[str] = []
for i in range(0, len(recent) - 1, 2):
u = recent[i]
a = recent[i + 1]
if u.role != "user" or a.role != "assistant":
continue
u_text = str(u.content)[:max_chars_per_msg]
a_text = str(a.content)[:max_chars_per_msg]
hints.append(f"Earlier turn — User: {u_text!r} | Assistant: {a_text!r}")
if hints:
hints.insert(0, "Conversation context (recent turns, newest last):")
return hints
async def _force_spawn_worker(
self,
user_text: str,
*,
trace_id: UUID | None = None,
source_layer: str | None = None,
) -> str | None:
"""Starts ``spawn_worker`` deterministically, without LLM tool-choice.
Wave-4 migration: previously ``_force_spawn_sub_jarvis`` with the
``spawn_sub_jarvis`` tool. The Sub-Jarvis tier was replaced by the
Jarvis-Agent bridge — see docs/jarvis-agents-bridge.md §11.
Returns:
``None`` when the heuristic does not trigger or the tool is absent.
Otherwise the Jarvis-Agent output (the mission manager delivers a
TTS-safe shortened summary via the voice listener path). The caller
(``generate``) forwards the string as the final brain response.
"""
if not self._should_force_spawn(user_text, source_layer=source_layer):
return None
tool = self._tools.get("spawn_worker")
if tool is None or self._tool_executor is None:
return None
tid = trace_id or uuid4()
context_hints: list[str] = [
"Deterministically delegated: the user's turn matched an explicit "
"delegation trigger (or the opt-in permissive verb heuristic).",
]
# Bug fix 2026-04-30: pass conversation history to the worker so
# follow-up questions ("erklaer das genauer") do not spawn into a
# void. The stateless worker stays architecturally compliant — it
# receives a snapshot of the last turns as a hint, not the full
# manager state.
context_hints.extend(self._build_history_hints())
# Phase 5 (opt-in): include active-window hint so the Jarvis-Agent worker
# knows which app the user is currently working in. Default OFF
# (costs 200-400 ms latency, not worth it for every spawn). 250 ms
# timeout in the module; failure mode 4 (pywinauto crash) is caught.
try:
from dodaios.brain.vision_context import get_active_window_hint
vision_cfg = getattr(self._config, "vision", None)
hint = await get_active_window_hint(config=vision_cfg)
except Exception as exc: # noqa: BLE001
log.debug("Vision-Context-Probe failed (non-fatal): %s", exc)
hint = None
if hint:
context_hints.append(hint)
args = {
"utterance": user_text,
"context_hints": context_hints,
# Empty action: the force-spawn heuristic has no LLM
# interpretation. The spawn tool's announcement composer then
# phrases the spoken ACK itself (flash-LLM with the delegation
# persona, deterministic bilingual fallback) — see
# dodaios/brain/ack_brain/spawn_announcement.py. Live regression
# 2026-05-26 / redesign 2026-06-10: no canned template phrases.
"action": "",
"target": "",
# Turn language for the spoken ACK: honour a reply-language pin,
# otherwise detect from the user's words.
"language": self._spawn_ack_language(user_text),
}
log.info("Force-Spawn Jarvis-Agent: %r", user_text[:160])
# Stamp the turn's resolved output language so spawn_worker drives the
# spoken ACK + mission language from the ONE authoritative resolver on
# the force-spawn path too (the tool-use loop does this for brain
# function-calls; this caller must do it itself or ctx.config is empty
# and the language silently falls back — Runtime Output Language).
out_lang = _turn_phrase_language(self, user_text)
result = await self._tool_executor.execute(
tool,
args,
user_utterance=user_text,
config_snapshot={"output_language": out_lang},
trace_id=tid,
)
if not result.success:
return await self._honest_failure_readback(
result,
user_text=user_text,
situation="The background helper the user asked for could not be started.",
generic_key="spawn_failed_generic",
reason_key="spawn_failed_reason",
lang=out_lang,
)
return str(result.output or "")
async def _recover_leaked_spawn(
self,
response_text: str,
*,
user_text: str,
trace_id: UUID,
allowed_tools: Mapping[str, Tool],
) -> str | None:
"""Execute a ``spawn_worker`` call a provider leaked as TEXT.
Root cause (live repro 2026-05-24, mission "erstelle mir eine Datei
test-opus.md"): Gemini intermittently emits the ``spawn_worker``
tool_use block as the response content instead of invoking it. The raw
JSON then reaches TTS as "Es trat ein Fehler auf" and the delegated
Opus-4.7 sub-agent never runs — even though the brain *decided* to
delegate. This is a provider function-calling leak, independent of the
force-spawn heuristic (which stays strict).
If ``response_text`` carries such a leaked call, run it through the same
tool path ``_force_spawn_worker`` uses and return the spawn ACK;
otherwise return ``None`` (caller keeps the original text).
"""
leaked = _extract_leaked_spawn_call(response_text)
if leaked is None:
return None
tool = allowed_tools.get("spawn_worker")
if tool is None or self._tool_executor is None:
return None
utterance = str(leaked.get("utterance") or user_text).strip() or user_text
context_hints = [
"Recovered from a leaked tool_use block: the brain emitted the "
"spawn_worker call as text instead of executing it (provider "
"function-calling leak). Re-dispatched deterministically so the "
"sub-agent runs and the user is not left with a spoken error.",
*self._build_history_hints(),
]
args = {
"utterance": utterance,
"context_hints": context_hints,
# Prefer the brain-leaked interpretation; the spawn tool's
# announcement composer validates the leaked spoken_ack (if any)
# and otherwise phrases the ACK itself.
"action": str(leaked.get("action") or ""),
"target": str(leaked.get("target") or ""),
"spoken_ack": str(leaked.get("spoken_ack") or ""),
"language": (
str(leaked.get("language") or "")
or self._spawn_ack_language(user_text)
),
}
log.warning(
"Recovered leaked spawn_worker tool-call from brain text "
"(provider function-calling leak): %r", user_text[:160],
)
# Same authoritative-language stamping as the force-spawn path: without
# a config snapshot ctx.config is empty and spawn_worker's language
# falls back instead of honoring the resolver (Runtime Output Language).
out_lang = _turn_phrase_language(self, user_text)
result = await self._tool_executor.execute(
tool, args, user_utterance=user_text,
config_snapshot={"output_language": out_lang},
trace_id=trace_id,
)
if not result.success:
return await self._honest_failure_readback(
result,
user_text=user_text,
situation="The background helper the user asked for could not be started.",
generic_key="spawn_failed_generic",
reason_key="spawn_failed_reason",
lang=out_lang,
)
return _safe_recovered_text(result.output or "")
async def _recover_leaked_tool(
self,
response_text: str,
*,
user_text: str,
trace_id: UUID,
allowed_tools: Mapping[str, Tool],
) -> str | None:
"""Execute ANY tool a provider leaked as TEXT (generalises spawn-only).
Root cause (live repro 2026-05-25, voice "oeffne den Editor"): Gemini
emits the ``tool_use`` block (``open_app`` / ``dispatch_to_harness`` /
``cli_*`` …) as response *text* instead of invoking it. The
spawn-only :meth:`_recover_leaked_spawn` ignored every non-spawn tool,
so the raw JSON reached TTS (scrubbed to silence) and the action never
ran — while plain chit-chat (no tool) worked fine.
``spawn_worker`` keeps its specialised path (history hints, ACK).
Every other leaked tool runs through the same ``ToolExecutor`` a
structured tool_use would take. Returns a speakable result string, or
``None`` if there is no leak / the tool is not runnable.
"""
parsed = _extract_leaked_tool_call(response_text)
if parsed is None:
return None
name, inp = parsed
if name == "spawn_worker":
return await self._recover_leaked_spawn(
response_text,
user_text=user_text,
trace_id=trace_id,
allowed_tools=allowed_tools,
)
if self._tool_executor is None:
return None
tool = allowed_tools.get(name)
if tool is None:
return None
log.warning(
"Recovered leaked %s tool-call from brain text "
"(provider function-calling leak): %r", name, user_text[:160],
)
result = await self._tool_executor.execute(
tool, inp, user_utterance=user_text, trace_id=trace_id,
)
if not result.success:
# A failed cli_<name> call carries the real cause in stderr; speak
# it instead of the bare "exit N" error token (live repro
# 2026-06-17, gcloud billing budgets list -> exit 1).
if name.startswith(_CLI_TOOL_PREFIX):
return _safe_recovered_text(
_cli_failure_reason(
result.output,
result.error,
language=self._spoken_reply_language(user_text),
)
)
return await self._honest_failure_readback(
result,
user_text=user_text,
situation="An action the user asked for could not be carried out.",
generic_key="action_failed_generic",
reason_key="action_failed_reason",
)
# A read tool (search_web, wiki-recall, …) returns STRUCTURED data, not
# a spoken sentence. Render it to speakable text — ``str(result.output)``
# on a dict put a ``{``-prefixed repr on the wire that the streaming
# guard dropped as a "leak", so a successful search dead-ended in the
# canned action-failed phrase (live repro 2026-06-14 "Was hältst du von
# exp.com?"). See :func:`_render_recovered_tool_output`.
spoken = _render_recovered_tool_output(result.output)
if spoken:
return spoken
# Tool ran but produced nothing speakable (e.g. an empty search). Give a
# real spoken sentence, never silence and never the failure phrase.
lang = self._spoken_reply_language(user_text)
return _NOTHING_FOUND_PHRASE.get(lang, _NOTHING_FOUND_PHRASE["en"])
def _cancel_all_background_tasks(self) -> int:
"""Cancels all running background Jarvis-Agent tasks.
Matches via `task.get_name()` against the "jarvis-agent-" prefix (legacy
naming convention, kept for byte-for-byte agreement with the
`spawn_worker` tool's `create_task(...)` call).
Returns the number of cancelled tasks.
"""
cancelled = 0
try:
running = asyncio.all_tasks()
except RuntimeError:
# No running event loop (sync context) — nothing to cancel.
return 0
for task in running:
name = task.get_name() or ""
if name.startswith("jarvis-agent-") and not task.done():
task.cancel()
cancelled += 1
log.info("Cancelled %d background Jarvis-Agent task(s)", cancelled)
return cancelled
def _cancel_readback(self, count: int) -> str:
"""Honest spoken readback for a deterministic cancel: name the count, or
say plainly that nothing was running. Never silent (audit 2026-06-27)."""
lang = self._resolve_turn_lang()
if count > 0:
return i18n_catalog.pick(_CANCEL_CONFIRM, lang).format(n=count)
return i18n_catalog.pick(_CANCEL_NONE, lang)
def _depth_readback(self, level: str) -> str:
"""Honest spoken confirmation of a depth override. Never silent."""
lang = self._resolve_turn_lang()
table = _DEPTH_CONFIRM.get(level, _DEPTH_CONFIRM["deep"])
return i18n_catalog.pick(table, lang)
# ------------------------------------------------------------------
# Intent-Router → (provider, model) chain
# ------------------------------------------------------------------
def _picked_level(self, user_text: str) -> RoutingDecision:
if self._force_level == "deep":
return RoutingDecision(level="deep", reason="sticky-deep")
if self._force_level == "fast":
return RoutingDecision(level="fast", reason="sticky-fast")
return classify(user_text)
def _brain_can_call_tools(self, provider: str, model: str | None) -> bool:
"""Runtime tool-calling capability of a provider, capability-driven.
A brain may expose ``can_call_tools()`` to report it cannot emit
tool_calls right now (the subscription-CLI brains — Codex over the ChatGPT
login, Antigravity over the Google login — drop ALL tools). Falls back to
the static ``supports_tools`` ceiling, then True. Any error → True so the
chain is never blocked by a capability probe."""
try:
brain = self._get_brain(provider, model)
except Exception: # noqa: BLE001
return True
fn = getattr(brain, "can_call_tools", None)
if callable(fn):
try:
return bool(fn())
except Exception: # noqa: BLE001
return True
return bool(getattr(brain, "supports_tools", True))
def _active_can_call_tools(self) -> bool:
"""Whether the ACTIVE talker can emit tool_calls this turn."""
return self._brain_can_call_tools(
self._active_name, self._fast_model(self._active_name)
)
def _first_tool_capable_provider(
self, level: str, *, exclude: str | None = None
) -> tuple[str, str | None] | None:
"""First AVAILABLE provider that can emit tool_calls — used to lead a
tool/action turn when the active talker cannot. deep_brain first, then a
stable cross-provider order. Returns (name, model) or None when no
tool-capable provider is reachable (then the chain stays unchanged).
``exclude`` names the talker being led (the active brain by default;
a per-turn pick under an override)."""
skip = exclude if exclude is not None else self._active_name
available = set(self._registry.available())
order: list[str] = []
db = self._config.brain.deep_brain
if db:
order.append(db)
order += ["gemini", "claude-api", "openai", "openrouter", "grok", "nvidia"]
from dodaios.brain.voice_key import bills_voice_key
# The realtime voice key leads a turn only when no other provider can
# call tools (mandate 2026-09-29: that key pays for the voice call).
on_voice_key: tuple[str, str | None] | None = None
seen: set[str] = set()
for name in order:
if name in seen or name == skip or name not in available:
continue
seen.add(name)
# Skip providers dead-listed or rate-limited THIS session — the
# chain walk (see the dead_providers/rate_tracker checks at the
# top of the provider-chain loop below) already excludes them
# from actually answering, so picking one here as the "lead"
# left _router_lead_key pointing at an entry the chain would
# never reach: _is_router_lead misfired for the real lead and
# the toolless fall-through gate accepted a tool-incapable
# provider's answer as final.
if name in self._dead_providers:
continue
model = (
self._deep_model(name) if level in ("deep", "code")
else self._fast_model(name)
) or self._fast_model(name)
if not self._rate_tracker.is_available(name, model):
continue
if self._brain_can_call_tools(name, model):
if bills_voice_key(self._config, name):
on_voice_key = on_voice_key or (name, model)
continue
return (name, model)
return on_voice_key
def _turn_has_action_intent(self, user_text: str) -> bool:
"""Best-effort, provider-agnostic 'this turn wants a tool/desktop action'
using the EXISTING deterministic detectors (no new signal-word list).
Used only to decide whether a tool-incapable active talker should delegate
this turn — a pure conversation/knowledge turn returns False and stays on
the chosen provider."""
t = user_text or ""
if is_open_app_intent(t) or _looks_like_pc_control(t):
return True
try:
from dodaios.core.capabilities import get_registry # noqa: PLC0415
reg = get_registry()
if getattr(reg, "all", lambda: ())() and reg.has_action_intent(t):
return True
except Exception: # noqa: BLE001 — registry must never block routing
pass
return False
def _override_chain(
self, override: TurnOverride, level: str
) -> list[tuple[str, str | None]]:
"""The chain for a caller-picked turn: exactly the pick, no stand-in.
A person who chose a model in the chat gets that model or an honest
error — never a silent cross-provider fallback. A tool-incapable pick
does not authorize another provider to lead or bill this turn.
"""
pick: tuple[str, str | None] = (override.provider, override.model)
return [pick]
def _build_fallback_chain(self, level: str) -> list[tuple[str, str | None]]:
"""Returns a prioritised list of (provider, model) attempts."""
active = self._active_name
chain: list[tuple[str, str | None]] = []
# Reset the per-turn router-lead marker every build (a stale value would
# make the loop wrongly fall through). Set below only when we prepend an
# intelligent-router lead.
self._router_lead_key: tuple[str, str | None] | None = None
tool_lead: tuple[str, str | None] | None = None
override = _TURN_OVERRIDE.get()
if override is not None:
return self._override_chain(override, level)
# Capability-driven tool delegation (NOT a per-provider hardcode): the
# subscription-CLI brains (Codex over the ChatGPT login, Antigravity over
# the Google login) cannot emit tool_calls — can_call_tools() == False —
# so a tool turn reaching them is dropped/confabulated. We hand tool
# selection to a tool-capable provider; any future CLI brain inherits this.
if not self._active_can_call_tools():
intelligent = bool(
getattr(self._config.brain.routing, "intelligent_router", True)
)
if intelligent and getattr(self, "_turn_substantive", False):
# INTELLIGENT ROUTER (2026-06-21 mandate): a tool-capable provider
# LEADS every substantive turn and the LLM itself picks the tool
# via its tool-use loop + the router system prompt — no signal-word
# list decides the tool. If it picks NO tool (pure conversation),
# generate()'s chain loop FALLS THROUGH to the chosen talker (see
# ``_router_lead_key``), so the user keeps their selected brain's
# voice. The deterministic gates stay as high-precision guardrails.
helper = self._first_tool_capable_provider(level)
if helper is not None and helper[0] != active:
log.info(
"Intelligent router: %s cannot call tools — %s leads this "
"turn and picks the tool (falls through to %s if none).",
active, helper[0], active,
)
self._router_lead_key = helper
tool_lead = helper
chain.append(helper)
elif getattr(self, "_turn_needs_tools", False):
# Flag OFF (kill switch): the narrower action-intent delegation —
# delegate ONLY when a deterministic action signal fired, and let
# the tool-capable provider answer the whole turn (no fall-through).
helper = self._first_tool_capable_provider(level)
if helper is not None and helper[0] != active:
log.info(
"Tool delegation (legacy): %s cannot call tools — leading "
"this action turn with %s.", active, helper[0],
)
tool_lead = helper
chain.append(helper)
# 0. Deep/code intents: dedicated deep_brain first (e.g. gemini via
# subscription — bypasses /v1/messages API quota). Bug fix 2026-04-29:
# at level=deep the deep_model of the brain MUST be used (previously:
# _fast_model → gemini-3-flash for a deep request instead of
# gemini-3.1-pro-preview).
deep_brain = self._config.brain.deep_brain
# When the user has explicitly made a frontier SUBSCRIPTION brain the
# active one (codex via ChatGPT),
# it leads ALL turns — the deep_brain (e.g. gemini) must NOT jump ahead for
# deep/code intents, or the chosen brain would never actually answer a hard
# question despite being selected (it would silently fall through to the
# deep_brain). Other active brains keep the deep_brain routing unchanged.
if (
level in ("deep", "code")
and deep_brain
and deep_brain != active
and active != "codex"
and deep_brain in self._registry.available()
):
preferred_deep = self._deep_model(deep_brain) or self._fast_model(deep_brain)
chain.append((deep_brain, preferred_deep))
# 1. Active provider with the appropriate model for the level
fast = self._fast_model(active)
deep = self._deep_model(active)
if level == "fast":
if fast:
chain.append((active, fast))
if deep: # on Haiku rate-limit → try Opus in the same provider
chain.append((active, deep))
elif level in ("deep", "code"):
if deep:
chain.append((active, deep))
if fast: # if Opus fails, use Haiku (better than nothing)
chain.append((active, fast))
else:
if fast:
chain.append((active, fast))
# A registered provider may own its default model (local discovery or
# a subscription CLI's account default). Keep that choice on the chain.
if not fast and not deep and active in self._registry.available():
chain.append((active, None))
# 2. Explicit tier fallbacks from jarvis.toml. These must run before
# generic cross-provider probing so runtime matches healthcheck order.
available = set(self._registry.available())
for name, configured_model in self._configured_fallbacks:
if name not in available:
continue
m_fast = self._fast_model(name)
m_deep = self._deep_model(name)
preferred = configured_model or (m_deep if level in ("deep", "code") else m_fast)
chain.append((name, preferred or m_fast or m_deep))
# 3. Cross-provider fallbacks (same provider family first).
# Ollama completely removed (2026-04-21) — user decision, pure
# cloud/API provider chain.
cross_order = [
"claude-api", # separate Anthropic-Quota
"gemini", # Google AI Studio
"openrouter", # universal gateway
"openai",
"grok", # xAI Grok
"nvidia", # NVIDIA NIM (free dev tier)
]
for name in cross_order:
if name == active:
continue
if name not in available:
continue
m_fast = self._fast_model(name)
m_deep = self._deep_model(name)
preferred = m_deep if level in ("deep", "code") else m_fast
chain.append((name, preferred or m_fast or m_deep))
# Deduplicate (first instance wins) + filter dead providers.
# Dead = provider already failed with "no API key" in this session.
# Skip it so the voice turn does not run 8x sequentially against
# missing keys. Reset on provider switch or manager restart.
seen: set[tuple[str, str | None]] = set()
deduped: list[tuple[str, str | None]] = []
for item in chain:
if item in seen:
continue
if item[0] in self._dead_providers:
continue
seen.add(item)
deduped.append(item)
# A tool lead no other family could take, and a provider the person
# switched to themselves, stay on the chain.
keep = [entry for entry in deduped if entry[0] == self._switched_to == active]
if tool_lead is not None:
keep.append(tool_lead)
return self._keep_off_voice_key(
deduped,
keep=keep,
needs_tools=bool(getattr(self, "_turn_needs_tools", False)),
)
def _keep_off_voice_key(
self,
chain: list[tuple[str, str | None]],
*,
keep: Iterable[tuple[str, str | None]] = (),
needs_tools: bool = False,
) -> list[tuple[str, str | None]]:
"""Drop the realtime voice key's family while another provider remains.
Text turns, Telegram and scheduled routines never spend the key that
pays for the live voice call (mandate 2026-09-29). A single-key install
keeps it, and so do the ``keep`` entries (a tool lead no other family
could take, a provider the person switched to). Only a
provider that can take the turn right now counts as the alternative:
not rate-limited, and able to call tools when the turn needs them.
"""
from dodaios.brain.voice_key import without_voice_key
models: dict[str, str | None] = {}
for name, model in chain:
models.setdefault(name, model)
def can_answer(name: str) -> bool:
model = models.get(name)
if not self._rate_tracker.is_available(name, model):
return False
return not needs_tools or self._brain_can_call_tools(name, model)
kept = without_voice_key(self._config, chain, is_alternative=can_answer, keep=keep)
if len(kept) < len(chain):
log.debug(
"Voice key reserved for the live call — left out of this chain: %s",
sorted({name for name, _ in chain} - {name for name, _ in kept}),
)
return kept
# ------------------------------------------------------------------
# Generate — Haupt-Entrypoint
# ------------------------------------------------------------------
async def generate(
self,
user_text: str,
*,
use_history: bool = True,
trace_id: UUID | None = None,
text_consumer: Callable[[str], None] | None = None,
on_progress: Callable[[], None] | None = None,
source_layer: str | None = None,
conversation_id: str | None = None,
allow_voice_confirm: bool = False,
prefer_tool_model: bool = False,
emit_tool_ack: bool = True,
publish_response: bool = True,
history_override: Iterable[BrainMessage] | None = None,
force_output_language: str | None = None,
consume_pending_voice_attachments: bool = False,
turn_override: TurnOverride | None = None,
language_text: str | None = None,
) -> str:
"""Generate a turn, optionally leaving its public response event to the caller.
``publish_response=False`` suppresses only ``ResponseGenerated``. History,
curator work, tool execution, and every other turn side effect remain intact.
The context-local policy keeps concurrent classic and delegated calls isolated.
``history_override`` supplies caller-owned context for this turn without
mutating the manager's shared conversation buffer; combine it with
``use_history=False`` when the caller owns history persistence too.
``turn_override`` runs the turn on a caller-picked provider / model /
effort with extra tools and tool context (the typed chat's pick) —
the live brain, its config and its dead-lists are left untouched.
``language_text`` is what the conversation language is read from when
``user_text`` is not the person's own words (an internal "continue"
prompt): ``""`` keeps the conversation's language unchanged.
"""
token = _PUBLISH_RESPONSE_EVENT.set(bool(publish_response))
history_token = _TURN_HISTORY_OVERRIDE.set(
tuple(history_override) if history_override is not None else None
)
override_token = _TURN_OVERRIDE.set(turn_override)
# Armed ("" = no language yet); _update_turn_language fills it in.
language_token = TURN_LANGUAGE.set("")
from dodaios.core.image_references import active_scope
image_scope_token = active_scope.set(
"conversation:" + conversation_id if conversation_id else
"brain:" + str(id(self)) if use_history else "turn:" + str(trace_id or uuid4())
)
skill_state = _SkillTurnState(self)
skill_token = _SKILL_TURN_STATE.set(skill_state)
try:
return await self._generate(
user_text,
use_history=use_history,
trace_id=trace_id,
text_consumer=text_consumer,
on_progress=on_progress,
source_layer=source_layer,
conversation_id=conversation_id,
allow_voice_confirm=allow_voice_confirm,
prefer_tool_model=prefer_tool_model,
emit_tool_ack=emit_tool_ack,
force_output_language=force_output_language,
consume_pending_voice_attachments=(
consume_pending_voice_attachments
),
language_text=language_text,
)
finally:
# Keep the last completed turn inspectable for diagnostics/tests,
# while active concurrent turns continue reading their own
# ContextVar-backed state.
self._skill_turn_match_fallback = skill_state.match
self._skill_turn_content_fallback = skill_state.content
self._skill_turn_source_fallback = skill_state.source
self._skill_injected_inline_fallback = skill_state.injected_inline
_SKILL_TURN_STATE.reset(skill_token)
_TURN_OVERRIDE.reset(override_token)
TURN_LANGUAGE.reset(language_token)
active_scope.reset(image_scope_token)
_TURN_HISTORY_OVERRIDE.reset(history_token)
_PUBLISH_RESPONSE_EVENT.reset(token)
async def _generate(self, user_text: str, *args: Any, **kwargs: Any) -> str:
"""A voice turn. Its spend is published on ``BrainTurnCompleted`` with
the realtime/tool/pipeline split, so the ledger row the metered
provider writes underneath is tagged and not counted a second time."""
from dodaios.costs.ledger import usage_context
with usage_context("voice-turn"):
return await self._generate_untagged(user_text, *args, **kwargs)
async def _generate_untagged(
self,
user_text: str,
*,
use_history: bool = True,
trace_id: UUID | None = None,
text_consumer: Callable[[str], None] | None = None,
on_progress: Callable[[], None] | None = None,
source_layer: str | None = None,
conversation_id: str | None = None,
allow_voice_confirm: bool = False,
prefer_tool_model: bool = False,
emit_tool_ack: bool = True,
force_output_language: str | None = None,
consume_pending_voice_attachments: bool = False,
language_text: str | None = None,
) -> str:
# 1. Intercept meta-commands (cancel, switch, depth override).
# User request 2026-04-25: no standardised confirmation phrases
# ("OK, ich wechsle auf X", "Abgebrochen ..."). State changes remain
# functional; feedback runs visually via bus events
# (BrainProviderSwitched) or UI indicators. The pipeline stays silent
# on empty responses (see pipeline.py:937).
# AD-OE6 zero-silent-drop signal: reset per turn. Only the
# failure-diagnostic returns below flip it True; the meta-command
# early-returns ("") that follow correctly leave it False.
self._last_turn_all_failed = False
self._last_turn_suppressed = False
self._last_turn_executed_action_tool = False
# Clear last turn's provider identity so a helper prompt build before the
# fallback loop (wiki-delta base) does not carry a stale provider name.
self._active_turn_identity = None
turn_trace_id = trace_id or uuid4()
# Tool-surface self-heal (live 2026-07-13): a source that connects
# AFTER the boot's last BrainToolsChanged — or whose event is lost to a
# wedged plugin bootstrap — otherwise stays invisible for the WHOLE
# session and the model refuses with "tool not available". Cheap
# names-only drift check against the live CLI/plugin/MCP caches; one
# refresh_tools() when they diverge. Never raises.
from dodaios.brain.tool_surface import reconcile_tool_surface_async
await reconcile_tool_surface_async(self)
# Conversation use, never app boot: load the persistent team before
# planning or building the first prompt, even if Agents was never opened.
from dodaios.brain.factory import prepare_society_context
await prepare_society_context()
# auto mode: resolve this turn's language so _reply_language_directive()
# hard-pins it (a soft "mirror" drifts to German on tool-synthesis
# turns — live bug 2026-06-14: an English weather turn answered in
# German). Conversation stickiness: a thin interjection ("Now") inherits
# the running conversation language instead of flipping it (forensic
# 2026-06-18); ambiguous text stays "unknown" -> soft mirror; an explicit
# reply_language pin leaves it empty -> the directive uses the pin.
self._update_turn_language(user_text if language_text is None else language_text)
# Realtime-delegate language override (live 2026-07-23): the realtime
# session is the ONE authoritative resolver for a voice turn — its own
# model reply and the recorded jarvis_lang already consume that decision.
# A delegated jarvis_action turn must speak the SAME language instead of
# re-deriving it here from a possibly code-switched transcript, which let
# an English realtime conversation answer a memory-save turn in German
# ("Notiert ..."). Pin the caller-forced language so
# _reply_language_directive() hard-locks it; an explicit
# brain.reply_language pin still wins (checked first in that directive).
if (
is_known_language(force_output_language)
and self._reply_language not in _REPLY_LANG_NAMES
):
self._turn_detected_lang = force_output_language
if TURN_LANGUAGE.get() is not None:
TURN_LANGUAGE.set(force_output_language)
# Two-turn voice/chat confirmation resume (turn N+1). MUST run before the
# cancel-intent intercept: a "nein"/"stop" answer to a pending
# confirmation is a VETO of that one action, not a global cancel-all.
# Returns the spoken outcome (turn consumed) or None (user moved on →
# the pending action is dropped and this utterance runs as a normal turn).
screen_context = None
if self._pending_voice_confirm is not None:
resumed = await self._resume_voice_confirm(user_text)
if resumed is not None:
await self._record_response_side_effects(
user_text=user_text, response_text=resumed,
use_history=use_history, trace_id=turn_trace_id,
)
return resumed
# A veto such as "stop" belongs to the pending one-shot look, not to
# the global cancel-all gate below. Resolve only an already-armed,
# conversation-scoped proposal here; ordinary turns still take the
# cheap classifier at the normal Screen Context integration point.
if self._has_pending_screen_confirm(
source_layer=source_layer,
conversation_id=conversation_id,
allow_voice_confirm=allow_voice_confirm,
):
screen_context = await self._resolve_screen_context_turn(
user_text,
source_layer=source_layer,
conversation_id=conversation_id,
allow_voice_confirm=allow_voice_confirm,
trace_id=turn_trace_id,
)
if screen_context.ends_the_turn:
screen_reply = screen_context.question or screen_context.message or ""
await self._record_response_side_effects(
user_text=user_text,
response_text=screen_reply,
use_history=use_history,
trace_id=turn_trace_id,
)
return screen_reply
if self._detect_cancel_intent(user_text):
confirmation = self._cancel_readback(self._cancel_all_background_tasks())
await self._record_response_side_effects(
user_text=user_text,
response_text=confirmation,
use_history=use_history,
trace_id=turn_trace_id,
)
return confirmation
society_reply = await self._run_society_inventory_fast_path(
user_text, trace_id=turn_trace_id,
)
if society_reply is not None:
await self._record_response_side_effects(
user_text=user_text, response_text=society_reply,
use_history=use_history, trace_id=turn_trace_id,
)
return society_reply
# An addressed Agentic-IDE pane outranks every self-configuration gate
# below — the same precedence the desktop gate already honours further
# down (``_agentic_ide_owns_turn`` there), applied here because the
# config gates run FIRST and therefore get the only chance to be wrong.
#
# Live 2026-07-28 20:34, coding mode on, six panes open: a spoken
# order to brief two of them was claimed by the reply-language gate on
# three unrelated words scattered across the utterance. It applied the
# setting and returned, so ``_run_agentic_ide_fast_path`` below never
# ran and no agent was briefed — while the live model, which is told
# none of this, reported both as working. The gate's own proximity
# bound (``voice_command_gate._match_language_switch``) is the first
# fix; this is the second, because a config gate winning a turn that
# NAMES A RUNNING AGENT is wrong however plausible its match looked —
# briefing an agent and changing a setting are not things a user can
# mean at the same time.
#
# Deliberately NOT applied to the cancel intercept above: stopping work
# is a safety control and must keep working under every phrasing.
# Cheap enough for the hot path — an in-memory regex sweep, no IO and
# no model call (AP-9/AP-11) — and it answers "no" on any fault.
ide_owns_turn = self._agentic_ide_owns_turn(user_text)
switch_target = (
None if ide_owns_turn else self._detect_switch_intent(user_text)
)
if switch_target:
confirmation = await self._apply_main_provider_switch(switch_target)
if confirmation:
await self._record_response_side_effects(
user_text=user_text,
response_text=confirmation,
use_history=use_history,
trace_id=turn_trace_id,
)
return confirmation
# Deterministic reply-language switch — runs BEFORE the force-spawn
# heuristic so "stell auf Englisch um" sets brain.reply_language
# directly (live + persisted) instead of being dispatched as a worker
# mission (2026-06-22 forensic). Provider-independent: no LLM tool-call.
lang_switch = (
None if ide_owns_turn else self._detect_language_switch_intent(user_text)
)
if lang_switch:
confirmation = self._apply_reply_language_switch(lang_switch)
if confirmation:
await self._record_response_side_effects(
user_text=user_text,
response_text=confirmation,
use_history=use_history,
trace_id=turn_trace_id,
)
return confirmation
# Deterministic sub-agent (Heavy-Task worker) provider switch — same
# reasoning as the language switch: runs BEFORE the force-spawn/LLM path
# so "switch the sub-agent provider to X" sets brain.sub_jarvis.provider
# directly instead of escalating to a worker mission (2026-06-22 forensic).
subagent_switch = (
None if ide_owns_turn else self._detect_subagent_switch_intent(user_text)
)
if subagent_switch:
confirmation = await self._apply_subagent_provider_switch(subagent_switch)
if confirmation:
await self._record_response_side_effects(
user_text=user_text,
response_text=confirmation,
use_history=use_history,
trace_id=turn_trace_id,
)
return confirmation
depth_override = (
None if ide_owns_turn else self._detect_depth_override(user_text)
)
if depth_override in ("deep", "fast"):
self._force_level = depth_override
confirmation = self._depth_readback(depth_override)
await self._record_response_side_effects(
user_text=user_text,
response_text=confirmation,
use_history=use_history,
trace_id=turn_trace_id,
)
return confirmation
# AD-12 + AP-OC5 (Jarvis-Agent bridge wave-4 router): intercept status/cancel
# phrases via pattern match BEFORE the force-spawn heuristic
# misinterprets them as action verbs ("brich ab" contains the verb 'ab'
# and would otherwise trigger a new spawn). Pattern-match-first is
# mandatory — no LLM hallucination risk on "laeuft das noch?".
oc_match = match_mission_command(user_text)
if oc_match is not None:
log.info(
"Jarvis-Agent-Command recognized: intent=%s id=%s lang=%s text=%r",
oc_match.intent,
oc_match.mission_id,
oc_match.language,
user_text[:120],
)
if (
oc_match.intent == "status"
and self._jarvis_agent_status_fn is not None
):
response = await self._jarvis_agent_status_fn(oc_match.mission_id)
await self._record_response_side_effects(
user_text=user_text,
response_text=response,
use_history=use_history,
trace_id=turn_trace_id,
)
return response
if (
oc_match.intent == "cancel"
and self._jarvis_agent_cancel_fn is not None
):
response = await self._jarvis_agent_cancel_fn(oc_match.mission_id)
await self._record_response_side_effects(
user_text=user_text,
response_text=response,
use_history=use_history,
trace_id=turn_trace_id,
)
return response
# Pattern matched, but no handler registered — fall through to
# the normal path. Logging aids debugging ("why does the status
# read still spawn?": handlers not wired).
log.warning(
"Jarvis-Agent-Command match without a handler — fallback to "
"the normal generate path. Bootstrap must call "
"set_mission_command_handlers()."
)
routing_text, contextual_tool_names = self._contextual_routing_state(
user_text, use_history=use_history,
)
# Skill-aware routing guard (AD-S3): probe ONCE per turn, before any
# fast path can grab the utterance. "starte die Morgenroutine" is an
# is_open_app_intent hit AND a spawn-verb hit — without this early
# probe the skill never gets a chance (the root cause of "Jarvis
# never calls a skill"). Overwritten on every turn.
self._skill_turn_match = self._match_skill_for_turn(user_text)
# Evidence-gate state is strictly per-turn — a stale directive must
# never leak into a later prompt build (e.g. a skill turn that
# early-returns before the gate runs).
self._evidence_directive = ""
self._evidence_required_tool = ""
self._evidence_required_is_write = False
self._evidence_required_domain = ""
self._public_fact_prefetched = False
# AD-S4: a trigger noted by the speech pipeline / chat hook takes
# precedence — it carries the captured content and the source label.
self._consume_pending_skill_trigger(user_text)
if self._skill_turn_match is None and routing_text != user_text:
# Match the prior utterance independently before trying the
# composite routing context. Whole-utterance (``^...$``) plugin
# skill triggers cannot match the wrapper by design, yet they
# still own an explicitly referential follow-up.
previous_text = self._previous_user_turn_text(use_history=use_history)
if previous_text:
self._skill_turn_match = self._match_skill_for_turn(previous_text)
if self._skill_turn_match is None:
self._skill_turn_match = self._match_skill_for_turn(routing_text)
if self._skill_turn_match is not None:
self._skill_turn_source = "continuation"
# AD-S9: an explicit heavy-work trigger ("Sub-Agent", "Jarvis-Agent",
# "spawne", "deep dive", …) names the execution vehicle — the mission
# path owns such a turn, not the inline skill prompt. Live bug
# 2026-06-10 14:34: "spawne einen Sub-Agent … Gmail …" became a mute
# inline gmail-skill turn instead of a mission.
if (
self._skill_turn_match is not None
and self._is_explicit_heavy_request(user_text)
):
log.info(
"Skill match %s stands down — explicit heavy-work trigger in "
"the utterance wins (AD-S9: mission, not inline skill).",
getattr(self._skill_turn_match, "name", "?"),
)
self._skill_turn_match = None
# Wiki-write fast path (spec A1-A3): an explicit wiki target owns the
# turn before generic local-action, external-integration, or
# keyword-matched skill routing. The destination is authoritative;
# nouns inside the content (for example a trip to save as a fact) must
# never reinterpret the command as booking or dispatching that noun.
# Deterministic, model-independent, and confirm-after-write.
wiki_reply = await self._run_wiki_ingest_fast_path(
user_text,
trace_id=turn_trace_id,
use_history=use_history,
)
if wiki_reply is not None:
await self._record_response_side_effects(
user_text=user_text,
response_text=wiki_reply,
use_history=use_history,
trace_id=turn_trace_id,
)
return wiki_reply
# Sibling of AD-S9: a plugin/marketplace skill that merely keyword-
# matched an APP NAME ("Discord", "Spotify", "Slack") must NOT capture a
# turn the deterministic desktop-control gate owns. Computer-Use is the
# universal GUI integration — "open Discord and find the post on screen"
# must reach it even when the plugin's API/MCP integration is absent,
# instead of suppressing the local-action fast path and falling through
# to a tool-less CLI talker that hallucinates a permissions refusal.
# Live bug 2026-06-21 (sessions.db turn 67276501-…): plugin-discord
# matched the bare word "Discord", the antigravity deep brain (a CLI
# talker that drops all tools) then said "ich habe keinen Zugriff auf
# Discord". The gate decision is authoritative and precise: only a
# DIRECT open or a COMPUTER_USE plan stands the skill down — a pure
# dispatch ("schick eine Discord-Nachricht", gate → None/UNSUPPORTED)
# keeps its skill, and a non-app skill turn ("starte die Morgenroutine",
# gate → None) is untouched.
if self._skill_turn_match is not None:
_gate_plan = match_local_action(
user_text,
lang=self._spoken_reply_language(user_text),
live_tool_names=self._live_tool_names(),
)
_claiming = _gate_plan is not None and _gate_plan.mode in (
LocalActionMode.DIRECT,
LocalActionMode.COMPUTER_USE,
)
# A relevance-channel match that is not instruction-only yields to
# the desktop gate on ANY plan, not just a claiming one. The author
# of a trigger asked for their phrase to win, so trigger matches keep
# the narrower historical rule verbatim — this widening is additive
# and applies only to the new, inferred channel, where nobody stated
# an intent for the skill to beat local control.
if not _claiming and _gate_plan is not None and not self._skill_stand_downs_allowed():
_claiming = True
if _claiming and _gate_plan is not None:
log.info(
"Skill match %s stands down — the deterministic local-action "
"gate claims this turn as %s; Computer-Use owns it "
"(universal GUI integration, not a keyword-matched plugin).",
getattr(self._skill_turn_match, "name", "?"),
_gate_plan.mode.value,
)
self._skill_turn_match = None
if self._skill_turn_match is not None:
log.info(
"Skill-matched turn: %r → skill %s (fast paths stand down)",
user_text[:80],
getattr(self._skill_turn_match, "name", "?"),
)
# AD-S5: mission skills never run inline — dispatch the worker
# with the rendered instructions as the brief and return the
# optimistic ACK. Falls through to the inline path when the
# dispatch is not possible (AD-OE6: no silent drop).
mission_reply = await self._maybe_dispatch_skill_mission(
user_text, trace_id=turn_trace_id,
)
if mission_reply is not None:
await self._record_response_side_effects(
user_text=user_text,
response_text=mission_reply,
use_history=use_history,
trace_id=turn_trace_id,
)
return mission_reply
# Screen Context is a one-shot, explicit look request. It must run on
# the production BrainManager path before desktop-action routing: an
# ambiguous request asks first, a privacy refusal shuts every alternate
# screen path, and a successful capture owns the visual part of the turn.
if screen_context is None:
screen_context = await self._resolve_screen_context_turn(
user_text,
source_layer=source_layer,
conversation_id=conversation_id,
allow_voice_confirm=allow_voice_confirm,
trace_id=turn_trace_id,
)
if screen_context.ends_the_turn:
screen_reply = screen_context.question or screen_context.message or ""
await self._record_response_side_effects(
user_text=user_text,
response_text=screen_reply,
use_history=use_history,
trace_id=turn_trace_id,
)
return screen_reply
# An addressed Agentic-IDE terminal outranks the desktop gate — the
# mirror image of the skill stand-down just above, and for the same
# reason: whichever gate holds the MORE SPECIFIC evidence wins.
#
# Live bug 2026-07-26 09:44 (coding mode on, twelve panes open): "let
# Bruno do a deep dive and look into why you cannot paste text in the
# Agentic IDE" reached Computer-Use, which clicked into the workspace's
# own chat box and typed a prompt there — Jarvis operating its own UI by
# hand while the agent named in the sentence sat idle. The gate had
# matched the GUI verb "kopieren", a word that appears in that sentence
# as the DESCRIPTION of a bug, never as an order to copy anything. A
# single-verb matcher cannot tell "copy this" from "copying is broken",
# whereas naming a running pane is unambiguous.
#
# ``owns_turn`` is the shared precedence the force-spawn guard and the
# spawn gate already consult (it stands down by itself when the user
# names the background-worker vehicle), so this third consumer cannot
# drift away from them. The turn is not answered here — it simply stays
# available for the Agentic-IDE fast path a few lines below.
if (
not screen_context.has_image
and self._skill_turn_match is None
and not self._agentic_ide_owns_turn(user_text)
):
local_action = await self._run_local_action_fast_path(
user_text, trace_id=turn_trace_id,
)
if local_action is not None:
await self._record_response_side_effects(
user_text=user_text,
response_text=local_action,
use_history=use_history,
trace_id=turn_trace_id,
)
return local_action
# Navigation fast-path: a clear "go to section X" command moves the UI
# deterministically (a dumb action, AD-OE3). Placed BEFORE the capability
# gate — which would refuse "zeig die Socials" because 'social' is an
# external-integration marker — and before force-spawn. Pure regex, no
# LLM (AP-11). See ADR-0011 amendment "Navigate tool".
nav_reply = await self._run_navigation_fast_path(
user_text, trace_id=turn_trace_id,
)
if nav_reply is not None:
await self._record_response_side_effects(
user_text=user_text,
response_text=nav_reply,
use_history=use_history,
trace_id=turn_trace_id,
)
return nav_reply
# Agentic-IDE fleet close: "close all Codex terminals" is a concrete
# workspace action, not a question for the router to interpret. It runs
# before addressed delivery so the word "all" cannot become a prompt
# sent into the very panes the user asked to stop.
ide_close_reply = await self._run_agentic_ide_close_fast_path(
user_text, trace_id=turn_trace_id,
)
if ide_close_reply is not None:
await self._record_response_side_effects(
user_text=user_text,
response_text=ide_close_reply,
use_history=use_history,
trace_id=turn_trace_id,
)
return ide_close_reply
# Agentic-IDE fast-path: an instruction aimed at a named terminal of the
# open coding workspace is DELIVERED to that terminal, deterministically.
# Placed before force-spawn — whose depth-marker hoist used to swallow
# exactly these turns (live bug 2026-07-25: "let Kai do a deep dive"
# dispatched a background mission while Kai sat idle) — and before the
# capability gate. Placed AFTER navigation so a section command still
# moves the UI even when a pane happens to share that word. Returns None
# on every turn that does not address a terminal.
# Image-based assignments must reach workspace-orchestrate's scoped
# selection and materialization boundary, not the text-only fast paths.
from dodaios.core.image_references import get_store as image_reference_store
from dodaios.core.image_references import scope_for
visual_assignment = (
screen_context.has_image
or bool(getattr(self, "_pending_turn_images", {}).get(turn_trace_id))
or bool(getattr(self, "_pending_drop_images", ()))
or "Visual reference IDs" in user_text
or bool(image_reference_store().available(scope_for(trace_id=turn_trace_id)))
)
ide_reply = None if visual_assignment else await self._run_agentic_ide_fast_path(
user_text,
trace_id=turn_trace_id,
consume_pending_voice_attachments=consume_pending_voice_attachments,
)
if ide_reply is not None:
await self._record_response_side_effects(
user_text=user_text,
response_text=ide_reply,
use_history=use_history,
trace_id=turn_trace_id,
)
return ide_reply
# Agentic-IDE pane spawn: "spawn five more Claude Code terminals" opens
# five panes instead of dispatching a background mission. Same reason to
# be deterministic and to sit ahead of force-spawn as the path above —
# the utterance NAMES the spawn vehicle, so nothing but a narrower
# deterministic rule can keep it in the workspace. Runs after the
# addressed-terminal path because ``detect_spawn`` stands down for an
# addressed pane ("sag Mika, sie soll ein Terminal öffnen" is Mika's
# work), which makes the two mutually exclusive by construction.
ide_spawn_reply = (
None if visual_assignment else await self._run_agentic_ide_spawn_fast_path(
user_text, trace_id=turn_trace_id,
)
)
if ide_spawn_reply is not None:
await self._record_response_side_effects(
user_text=user_text,
response_text=ide_spawn_reply,
use_history=use_history,
trace_id=turn_trace_id,
)
return ide_spawn_reply
# Agent-C (capability-coupling): pre-generation capability gate.
# If the utterance looks like an action request but no registered
# capability covers it, return a deterministic "not supported" reply
# and skip both brain and the Jarvis-Agent worker. No LLM call, no latency cost
# (AP-11 compliant — pure regex + registry lookup).
# AD-S3: a matched skill IS the capability — the unsupported-intent
# refusal must not fire on a skill turn.
unsupported = (
None
if self._skill_turn_match is not None or screen_context.has_image
else self._check_unsupported_intent(user_text)
)
if unsupported is not None:
await self._record_response_side_effects(
user_text=user_text,
response_text=unsupported,
use_history=use_history,
trace_id=turn_trace_id,
)
return unsupported
# Persona mandate phase 3: deterministic force-spawn heuristic before
# the LLM tool-use loop. Prevents spawn reflex on ambiguous smalltalk
# inputs (see docs/persona-research.md section 2 — 60% empty smalltalk
# outputs from the reflexive LLM spawn path).
if screen_context.has_image:
forced_spawn = None
elif (
contextual_tool_names
and not self._is_explicit_heavy_request(user_text)
and not self._research_wants_artifact(user_text)
):
log.info(
"Force-spawn stood down for contextual live tool(s): %s",
", ".join(contextual_tool_names),
)
forced_spawn = None
elif (
_TURN_OVERRIDE.get() is not None
and not _TURN_OVERRIDE.get().allow_force_spawn # type: ignore[union-attr]
and not self._is_explicit_heavy_request(user_text)
):
# A caller-picked turn (the typed chat) IS the worker in its folder:
# the heuristic must not hand its work to a background mission. An
# explicit "spawn an agent for this" still spawns.
forced_spawn = None
else:
forced_spawn = await self._force_spawn_worker(
user_text, trace_id=turn_trace_id, source_layer=source_layer,
)
if forced_spawn is not None:
# Bug fix 2026-04-30: history update also in the force-spawn path.
# Previously returned directly → main Jarvis had no memory on the
# NEXT turn that this question was ever asked.
await self._record_response_side_effects(
user_text=user_text,
response_text=forced_spawn,
use_history=use_history,
trace_id=turn_trace_id,
)
return forced_spawn
# Evidence gate (AD-CLI4..AD-CLI8): questions about external-data
# domains (calendar/email/tasks/repos/deployments) are never answered
# from the model's head. Either a connected CLI covers the domain
# (mandatory-tool directive for this turn) or the answer is a
# deterministic honest refusal. Pure regex + registry lookup, no LLM
# (AP-11). Only MISSION skill turns returned above — an inline
# plugin-skill turn reaches this point, so _run_evidence_gate itself
# stands down on a matched skill (AD-S3); non-CLI capabilities
# (paired skills, router tools, MCP) make the gate stand down (PASS).
verdict = self._run_evidence_gate(user_text)
if verdict.kind == "honest_refusal":
await self._record_response_side_effects(
user_text=user_text,
response_text=verdict.refusal_text,
use_history=use_history,
trace_id=turn_trace_id,
)
return verdict.refusal_text
if verdict.kind == "require_tool" and (
_conversational_turn_suppresses_read_mandate(user_text)
):
# Opinion/advice/conversational turn: never FORCE a read tool — and so
# never void the answer — just because a domain keyword appeared. Live
# 2026-06-30 (Bora-Bora): "...bei meinem Budget bei 25.000 Euro ...
# passt es?" matched the cloud domain, the gate forced cli_gcloud, and
# the backstop then deleted the model's good travel answer. The tool
# stays in the surface, so the model keeps discretion to call it; it is
# just never forced. A bare data lookup ("Was sind meine Abrechnungen?")
# carries no opinion opener and stays gated (no confab regression).
log.info(
"Evidence gate stood down (conversational): domain=%s tool=%s "
"— answering inline, not forcing the tool.",
verdict.domain, verdict.tool_name,
)
elif verdict.kind == "require_tool":
log.info(
"Evidence gate: domain=%s requires tool %s this turn",
verdict.domain, verdict.tool_name,
)
self._evidence_directive = verdict.directive
self._evidence_required_tool = verdict.tool_name
# Persist the domain so the honest "couldn't reach X" fallback can
# NAME the capability (B3) instead of the generic "the tool".
self._evidence_required_domain = verdict.domain
# Say-do honesty guard for WRITES. The read evidence gate above never
# fires on a "save this" turn (it is not a lookup), so a confirmed offer
# ("ja, leg die an … die Mail ist …") or an explicit "merk dir, dass …"
# used to be answered with a chatty "Okay, sehr gut" and NO write call —
# nothing persisted (live session 2026-06-30). Mandate the right write
# tool this turn, reusing the evidence machinery: the prompt directive,
# the smalltalk tool-widening (_evidence_required_tool stays visible),
# and the unverified-answer backstop that catches a fake confirmation.
# resolve_save_mandate routes contact data → contact-upsert and a
# general fact → wiki-ingest. Only when the read gate did not already
# mandate a tool, and only if the target tool is actually registered (a
# deployment without contacts/wiki degrades to no mandate — never a
# mandate for a missing tool, §3 open-source).
if not self._evidence_required_tool:
from dodaios.brain.contact_intent import resolve_save_mandate
_save_mandate = resolve_save_mandate(user_text)
if _save_mandate is not None and _save_mandate[0] in (
getattr(self, "_tools", None) or {}
):
self._evidence_directive = _save_mandate[1]
self._evidence_required_tool = _save_mandate[0]
self._evidence_required_is_write = True
log.info(
"Say-do guard: save intent — mandating %s this turn",
_save_mandate[0],
)
# Say-do guard for LOCAL OUTCOMES (shell-consistency rework 2026-08-08).
# A natural file/folder/system request ("erstell einen Ordner auf dem
# Desktop") used to reach the LLM with run_shell merely OPTIONAL:
# whether the model mapped the outcome onto a shell command was model
# whim, and the capability block's "never invent tools" rule biased it
# towards the dictated refusal ("mir fehlt das passende Werkzeug")
# although the tool was registered and visible (maintainer report
# 2026-08-08 — a timer request worked, a folder request refused).
# Mirror the save mandate above: deterministically mandate run_shell so
# the directive + honest write backstop turn "sometimes works" into
# "always works or fails honestly". Never overrides an earlier mandate
# (read evidence / save — those are more specific), stands down on a
# skill-matched turn (AD-S3/AD-S9: a matched skill IS the capability
# and must not be steamrolled by a generic shell mandate), and
# degrades to no mandate when run_shell is not registered (§3
# open-source).
if not self._evidence_required_tool and self._skill_turn_match is None:
from dodaios.brain.local_outcome_gate import resolve_local_outcome_mandate
_local_mandate = resolve_local_outcome_mandate(user_text)
if _local_mandate is not None and _local_mandate[0] in (
getattr(self, "_tools", None) or {}
):
self._evidence_directive = _local_mandate[1]
self._evidence_required_tool = _local_mandate[0]
self._evidence_required_is_write = True
log.info(
"Local-outcome guard: file/system intent — mandating %s this turn",
_local_mandate[0],
)
# A society model can describe a routine without ever calling its
# configuration tool. Make the write mandatory on explicit creation
# turns, including a short confirmation after the details were agreed.
# The live surface check keeps this guard out of other chat surfaces.
if not self._evidence_required_tool and "society_propose_change" in self._live_tool_names():
from dodaios.society.routine_intent import requests_routine_creation
if requests_routine_creation(user_text):
self._evidence_directive = (
"MANDATORY THIS TURN: read society_routines, then save the routine with "
"society_propose_change (kind=routine, mode=apply) from the agreed details, "
"and verify it."
)
self._evidence_required_tool = "society_propose_change"
self._evidence_required_is_write = True
self._evidence_required_domain = "routine"
log.info("Society routine creation intent — mandating society_propose_change")
# Jarvis itself (voice and the lead chat) schedules an agent's
# recurring work through the society-create-routine app command. A
# request like "a briefing every day at 8" never says "routine" and
# used to end as an inactive draft skill (live 2026-09-29), so the
# recurrence alone makes the save mandatory.
if (
not self._evidence_required_tool
and "society-create-routine" in self._live_tool_names()
):
from dodaios.society.routine_intent import wants_agent_routine
if wants_agent_routine(user_text):
self._evidence_directive = (
"MANDATORY THIS TURN: scheduled work. Create the agent with "
"society-create-agent if it does not exist, then call society-create-routine "
"with a self-contained prompt and the schedule; never create-skill. Report "
"the returned next_run."
)
self._evidence_required_tool = "society-create-routine"
self._evidence_required_is_write = True
self._evidence_required_domain = "routine"
log.info("Recurring-work intent — mandating society-create-routine")
# A small on-device model answers public-fact questions from an
# unreliable memory and often skips search_web (live 2026-10-28: an
# invented train story with "[used tool search_web]" typed as text).
# Mandate the search for those turns; the backstop below keeps a short
# clarifying question and replaces any unsearched claim.
if not self._evidence_required_tool and self._skill_turn_match is None:
from dodaios.brain.app_control import LOCAL_PROVIDERS
from dodaios.brain.public_fact_gate import (
PUBLIC_FACT_DOMAIN,
SEARCH_TOOL,
public_fact_search_directive,
)
_pf_override = _TURN_OVERRIDE.get()
_pf_provider = (
str(getattr(_pf_override, "provider", "") or "")
if _pf_override is not None
else ""
) or str(getattr(self._config.brain, "primary", "") or "")
_pf_directive = public_fact_search_directive(
user_text,
provider=_pf_provider,
tool_names=self._live_tool_names(),
previous_user_text=self._previous_user_turn_text(use_history=use_history),
local_providers=LOCAL_PROVIDERS,
)
if _pf_directive is not None:
self._evidence_directive = _pf_directive
self._evidence_required_tool = SEARCH_TOOL
self._evidence_required_domain = PUBLIC_FACT_DOMAIN
log.info(
"Public-fact guard: on-device provider %s — mandating %s this turn",
_pf_provider,
SEARCH_TOOL,
)
# The small model calls the tool only now and then; run the one
# search here and hand it the results (the realtime grounding).
# A question naming no event ("an accident?") borrows its
# subject from the last turns, or is answered with a question.
from dodaios.brain.public_fact_gate import (
PUBLIC_FACT_CLARIFY_DIRECTIVE,
PUBLIC_FACT_CLARIFY_DOMAIN,
prefetch_public_fact_evidence,
public_fact_evidence_directive,
public_fact_search_query,
)
_pf_query = public_fact_search_query(
user_text, self._recent_user_turn_texts(2, use_history=use_history)
)
if _pf_query is None:
self._evidence_directive = PUBLIC_FACT_CLARIFY_DIRECTIVE
self._evidence_required_domain = PUBLIC_FACT_CLARIFY_DOMAIN
else:
_pf_evidence = await prefetch_public_fact_evidence(
_pf_query, trace_id=turn_trace_id
)
if _pf_evidence is not None:
self._evidence_directive = public_fact_evidence_directive(_pf_evidence)
self._public_fact_prefetched = True
elif not self._evidence_directive:
# A hosted model without tools (the print-mode Claude CLI) cannot
# search either (BC-250 2026-10-29: "je ne peux pas faire de
# recherche en direct ici" about the latest Artemis II news). Run
# the search for an explicitly fresh public fact and hand it the
# results; its own answer is never replaced afterwards. The cheap
# text check runs first: the capability probe builds the primary
# brain, which only a turn that needs a search may do.
from dodaios.brain.public_fact_gate import (
hosted_fresh_fact_query,
prefetch_public_fact_evidence,
public_fact_evidence_directive,
)
_pf_query = hosted_fresh_fact_query(
user_text,
provider=_pf_provider,
local_providers=LOCAL_PROVIDERS,
previous_user_text=self._previous_user_turn_text(use_history=use_history),
recent_user_texts=self._recent_user_turn_texts(2, use_history=use_history),
)
if _pf_query is not None and not self._brain_can_call_tools(
_pf_provider, self._fast_model(_pf_provider)
):
_pf_evidence = await prefetch_public_fact_evidence(
_pf_query, trace_id=turn_trace_id
)
if _pf_evidence is not None:
self._evidence_directive = public_fact_evidence_directive(_pf_evidence)
log.info(
"Public-fact search: tool-less provider %s answers from a "
"system-run %s",
_pf_provider,
SEARCH_TOOL,
)
# Phase 5 / ADR-0006: pre-call budget gate. Block rather than request
# when cooldown is active or the task/daily budget is exhausted.
trace_uuid = turn_trace_id
if self._cost_meter is not None:
if self._cost_meter.is_in_cooldown():
return ("Cost-Cooldown aktiv — Tagesbudget erschoepft. "
"Neue Anfragen werden erst nach dem Cooldown-Ende bearbeitet.")
if self._cost_meter.over_task_budget(trace_uuid):
return "Task-Budget fuer diese Konversation ueberschritten."
if self._cost_meter.over_daily_budget():
return "Tagesbudget ueberschritten."
# Smalltalk spawn-hide (bug fix 2026-05-01): on clearly identified
# smalltalk the spawn vehicles are hidden so the LLM cannot be tempted to
# hallucinate "spawn_worker" (see voice session 2026-04-30 22:38, "es
# geht ab" → fake spawn). Only those — the rest of the surface stays, so
# a request the substring allowlist merely READS as chit-chat still has
# something to act with (see _smalltalk_tool_override). Force-spawn
# already ran (smalltalk wins there against verb match); now we also
# constrain the LLM tool-choice path.
is_smalltalk_turn = self._is_smalltalk(user_text)
if is_smalltalk_turn:
log.info(
"Smalltalk-Turn → nur read-only Tools fuer LLM sichtbar: %r",
user_text[:80],
)
# 2. Router: which level applies?
decision = self._picked_level(user_text)
log.debug("Router-Decision: level=%s reason=%s", decision.level, decision.reason)
# 3. Build fallback chain and try each entry.
# Provider-agnostic tool routing flags (consumed by _build_fallback_chain):
# - _turn_substantive: a non-smalltalk turn. With the intelligent router
# on, a tool-capable provider LEADS such a turn for a tool-incapable
# talker and the LLM picks the tool (or falls through to the talker).
# - _turn_needs_tools: the narrower action-intent signal used as the
# flag-OFF (kill-switch) delegation. Reuses the deterministic detectors.
# Reset _router_lead_key here too so a monkeypatched _build_fallback_chain
# (tests / callers that replace it) never leaves a stale fall-through marker.
self._router_lead_key = None
self._turn_substantive = not is_smalltalk_turn
self._turn_needs_tools = (not is_smalltalk_turn) and self._turn_has_action_intent(
user_text
)
chain = self._build_fallback_chain(decision.level)
if prefer_tool_model:
# Realtime delegation runs on the Tool Model pick; hoisted BEFORE
# the empty-chain check so an all-dead chain keeps the honest
# provider-down diagnostic below.
chain = self._hoist_tool_model(chain)
if not chain:
# Empty chain means either (a) no providers registered or
# (b) all filtered out by _dead_providers (no key set).
# In production (b) is the common case — provide an actionable message.
self._last_turn_all_failed = True
# Keep the actionable provider/key diagnostic in the LOG (UI/console
# surface it), but SPEAK only a localized, provider-agnostic apology
# — never read setup hints or provider names aloud (AP-11/ADR-0010).
if self._dead_providers:
log.warning(
"Provider chain empty (all dead/keyless) — spoken fallback. "
"Diagnostic: %s",
_format_provider_chain_error([
(p, "", "missing_key", "no API key in this session")
for p in self._dead_providers
]),
)
else:
log.warning("No brain providers available — spoken fallback used.")
# An all-keyless chain has exactly one honest spoken cause.
return await self._provider_down_reply(trace_uuid, cause="missing_key")
history_override = _TURN_HISTORY_OVERRIDE.get()
# The typed chat's pick, if any: its own credential scope and no
# dead-listing — a chat key that fails must not silence the voice brain.
turn_override = _TURN_OVERRIDE.get()
history = (
list(history_override)
if history_override is not None
else (self._history if use_history else [])
)
_drop_in_hist = sum(
1 for m in history
if isinstance(getattr(m, "content", None), str)
and "\U0001F4CE" in m.content
)
if _drop_in_hist:
log.info(
"📎 DROP CONTEXT present in this turn's history: %d note(s), "
"use_history=%s, total history=%d",
_drop_in_hist, use_history, len(history),
)
last_exc: Exception | None = None
response_text = ""
used_provider: str | None = None
used_model: str | None = None
_turn_executed: set[str] = set() # tools that REALLY ran this turn
# AI Pointer (deictic push): launch the cursor-element resolution BEFORE
# the vision-image await so it overlaps with it instead of running serially
# after (AP-9: keep the deictic turn off the serial hot path). The task does
# the regex gate itself, so non-deictic turns complete instantly with
# ("", None) and fast-skip on a headless host. Awaited just below.
pointer_task = (
None
if screen_context.has_image
else self._start_pointer_task(user_text, is_smalltalk_turn)
)
if screen_context.has_image:
pending_images = getattr(self, "_pending_turn_images", None)
injected = pending_images.pop(trace_uuid, ()) if pending_images else ()
images = tuple(injected) + (
ImageBlock(
mime=screen_context.mime,
data_b64=base64.b64encode(screen_context.image).decode("ascii"),
source_hash=screen_context.source_hash,
),
)
else:
images = await self._collect_vision_images(
trace_id=trace_uuid,
user_text=user_text,
is_smalltalk=is_smalltalk_turn,
)
# Per-provider error aggregation for a meaningful user message when
# the whole chain fails. Pattern: (provider, model, kind, detail).
# kind ∈ {"rate_limit", "missing_key", "skipped_cooldown", "init_fail",
# "call_fail"}
provider_errors: list[tuple[str, str, str, str]] = []
# B5 Agent C: wiki context injection — run once before the provider
# loop so all providers in the fallback chain see the same enriched
# system prompt. The injector is a no-op when _wiki_injector is None
# (Agent B not merged, or [wiki_context].enabled = false).
# _wiki_context_suffix is reset in the finally block at the end of
# generate() to prevent stale context leaking into the next turn.
try:
if self._wiki_injector is not None and not (
turn_override is not None
and turn_override.tool_context.get("tool_origin") == "society"
):
base_prompt = self._build_system_prompt()
injected_prompt = await self._wiki_injector.maybe_inject(
user_text=user_text,
system_prompt=base_prompt,
)
# Store the delta (only the appended wiki block, not the whole
# prompt) so _build_system_prompt() can append it once without
# duplicating the rest of the prompt.
if injected_prompt != base_prompt:
# Extract only the appended wiki section
self._wiki_context_suffix = injected_prompt[len(base_prompt):]
else:
self._wiki_context_suffix = ""
except Exception: # noqa: BLE001
# Any unexpected error in the injector must never crash a voice turn.
log.warning("WikiContextInjector raised unexpectedly — skipping", exc_info=True)
self._wiki_context_suffix = ""
# Personal memory vault (ADR-0044): memories that match this message and
# are not in the always-on block ride along in the same per-turn slot.
if not (
turn_override is not None
and turn_override.tool_context.get("tool_origin") == "society"
):
recalled = await self._vault_recall(user_text)
if recalled:
self._wiki_context_suffix = "\n\n".join(
p for p in (self._wiki_context_suffix.strip(), recalled) if p
)
# Wave 2 (omni-latency): assemble the per-turn dynamic context (date +
# wiki) once. In cache-optimized mode it rides on the user
# message (keeping the cached system prompt stable); empty in legacy
# mode. Reused for every provider in the fallback chain below.
turn_context = self._build_turn_context()
if screen_context.note:
turn_context = (
f"{turn_context}\n\n{screen_context.note}"
if turn_context
else screen_context.note
)
# AD-S3/S4: on a skill-matched turn the rendered instructions ride on
# the per-turn context (guaranteed invocation, no run-skill round
# trip needed) — deterministic code, not a prompt-only hope. The
# cached system prefix stays byte-stable.
_skill_block = self._render_skill_turn_injection(user_text)
if _skill_block:
turn_context = (
f"{turn_context}\n\n{_skill_block}" if turn_context else _skill_block
)
else:
# No capture, but the deterministic scorer may still have found
# plausible candidates. Narrowing 20 undifferentiated bullets down
# to the 1-3 that actually score is the cheapest part of this whole
# change and the part with no blast radius: the model still decides.
_narrow_block = self._render_skill_candidate_hint(user_text)
if _narrow_block:
turn_context = (
f"{turn_context}\n\n{_narrow_block}"
if turn_context
else _narrow_block
)
# AI Pointer (deictic push): collect the result of the resolution started
# above. When the utterance points at the mouse cursor ("was ist das da?") # i18n-allow
# the resolved element rides on this turn's context + a tight crop is
# attached only when the element is unlabeled. Unrelated turns ("how's the
# weather?") yield ("", None). See docs/plans/ai-pointer/DESIGN.md.
pointer_block = ""
pointer_image: ImageBlock | None = None
if pointer_task is not None:
try:
pointer_block, pointer_image = await pointer_task
except Exception: # noqa: BLE001 — never crash a turn on pointer context
log.debug("AI Pointer per-turn injection skipped", exc_info=True)
pointer_block, pointer_image = "", None
# AI Pointer grounding (2026-06-02): a deictic pointer turn ("worauf zeige
# ich?") must be scoped to the CURSOR region so the brain answers from the
# cursor element/crop — it must NOT guess the pointing target from the
# full-screen permanent-vision image (the live "described something
# completely elsewhere" bug). On such a turn we (1) replace the full-screen
# image with the tight cursor crop (or none, for a labelled element),
# (2) drop the full-screen screenshot + inspect-pointer tools (below), and
# (3) inject a "do not guess" instruction when resolution failed.
pointing_turn = (not is_smalltalk_turn) and self._is_pointer_intent(user_text)
if pointing_turn and not screen_context.has_image:
images = (pointer_image,) if pointer_image is not None else ()
if not pointer_block:
pointer_block = (
"[AI Pointer] The user asked what they are pointing at, but the "
"element under the cursor could not be read right now. Tell them "
"you cannot tell what is under the cursor at the moment — do NOT "
"guess from the rest of the screen."
)
turn_context = (
f"{turn_context}\n\n{pointer_block}" if turn_context else pointer_block
)
# Drag-drop SILENT context: pictures parked by ``add_dropped_context``
# (a drop never triggers its own turn) are pulled into THIS real turn,
# once — added AFTER vision + AI-Pointer image logic so neither clobbers
# them. Cleared on consume; never re-sent on later turns.
_dropped_imgs = getattr(self, "_pending_drop_images", ()) or ()
if _dropped_imgs:
self._pending_drop_images = ()
images = tuple(_dropped_imgs) + tuple(images)
# Grounded per-tool ack (perceived-latency): built ONCE per turn so a
# provider-chain retry cannot double-announce. The loop fires it the
# moment a tool is actually selected; None when the feature is off or
# this is a Voice-Control utterance.
_tool_ack_emitter = (
self._build_tool_ack_emitter(user_text) if emit_tool_ack else None
)
vision_capable_seen = False
if images:
chain = self._lead_vision_chain(chain)
screen_turn_t0 = time.perf_counter() if images else None
for idx, (prov_name, model) in enumerate(chain):
# Skip providers already marked dead in THIS turn.
# Example: gemini-fast fails with missing_key → gemini-deep would
# still be in the chain but would fail for the same reason. Skip
# saves an avoidable subprocess/network call. An overridden turn
# runs on its own credential scope, so the voice brain's dead-list
# is not its truth.
if turn_override is None and prov_name in self._dead_providers:
continue
# Model-scoped dead-list: this exact (provider, model) took a
# billing rejection earlier THIS turn but the provider itself
# was kept alive because another model was still untried — see
# `_dead_provider_models`.
if turn_override is None and (prov_name, model) in self._dead_provider_models:
continue
# Circuit breaker: skip rate-limited providers during cooldown
if not self._rate_tracker.is_available(prov_name, model):
log.debug("Skip rate-limited: %s(%s)", prov_name, model)
provider_errors.append(
(prov_name, model, "skipped_cooldown",
"still in 30s rate-limit cooldown"))
continue
try:
# The classic call keeps its two-argument shape (tests and
# callers replace ``_get_brain`` with that signature); only an
# overridden turn asks for its own credential scope.
brain = (
self._get_brain(prov_name, model, scope=turn_override.credential_scope)
if turn_override is not None
else self._get_brain(prov_name, model)
)
except Exception as exc: # noqa: BLE001
last_exc = exc
msg = str(exc)
kind = _classify_provider_error(msg, default="init_fail")
# The status dots read what real turns did; the record keeps
# only the classification, never this message (AP-34). An
# overridden turn (an agent chat) runs on its own credential
# scope and model, so it is not the Brain tab's evidence.
if turn_override is None:
_health_ledger.record_failure(
prov_name, _health_ledger.MODALITY_BRAIN, exc, model=model
)
# On missing_key: remove provider from the chain for the rest
# of the session. Prevents each voice turn from running 8x
# sequentially against the same missing keys. Never for an
# overridden turn: its key is the chat's, not the voice's.
if (
turn_override is None
and kind in _DEAD_LIST_KINDS
and prov_name not in self._dead_providers
):
self._dead_providers.add(prov_name)
if kind == "missing_key":
log.warning(
"Provider %s ohne API-Key — fuer diese Session deaktiviert. "
"Setup: Sidebar -> API-Keys.", prov_name)
else:
log.warning(
"Provider %s account-blocked (Credit/Quota/Tier) — "
"fuer diese Session deaktiviert. Detail: %s",
prov_name, msg[:160])
else:
log.debug(
"Brain %s(%s) konnte nicht instantiiert werden: %s",
prov_name, model, exc)
provider_errors.append((prov_name, model, kind, msg[:200]))
continue
# Attached pixels are evidence, not decoration. A provider that
# cannot inspect them must never answer as though it had; skip it
# by runtime capability and preserve the normal cross-family retry
# order for the remaining vision-capable providers.
if images and getattr(brain, "supports_vision", False) is not True:
provider_errors.append(
(prov_name, model, "vision_unsupported", "vision unsupported")
)
log.info(
"Skipping %s(%s): this turn carries an image but the "
"provider does not advertise vision support",
prov_name,
model,
)
continue
if images:
vision_capable_seen = True
_turn_tools = (
# Captured-screen turn: the pixels answer it, but the surface is
# NARROWED, not emptied — a look glued to an action still needs
# its vehicle, and cu_gate enforces the look/operate boundary per
# call (see _image_turn_tool_override).
self._image_turn_tool_override()
if screen_context.has_image
else self._smalltalk_tool_override() if is_smalltalk_turn
# Non-smalltalk turn: drop plugin tools irrelevant to this
# utterance (progressive disclosure), then hide any plugin whose
# CLI counterpart is connected (req 4: CLI > plugin fallback).
else self._suppress_plugins_covered_by_cli(
self._apply_plugin_relevance(routing_text, self._tools), routing_text
)
)
# Skill inline-injected (AD-S4): drop run-skill so a weak model
# cannot make a redundant, garbled run-skill tool call — the
# gemini-fast ``<call:tool.run-skill ...>`` text leak. The
# instructions already ride on the turn context, so execution is
# provider-/model-agnostic (no tool call needed).
_turn_tools = self._drop_run_skill_when_inline_injected(_turn_tools)
# Knowledge-question spawn-hide (forensic 2026-06-27): a plain
# factual question ("Welche Unternehmen haben so viel Speicherplatz?")
# must not be able to reach spawn_worker — the router-LLM reflexively
# delegated it ("ich ziehe einen Experten hinzu") instead of answering
# inline. The deterministic force-spawn gate already stood down; this
# removes the spawn tools from the LLM surface so the reflex has no
# tool to grab. search_web / reads / computer_use stay visible.
if isinstance(_turn_tools, dict):
_turn_tools = self._hide_spawn_on_knowledge_question(
_turn_tools, user_text
)
# Signalless-turn action-hide (forensic 2026-06-27): inside a live
# desktop episode a turn with NO actionable signal of its own ("Was
# geht ab?" mis-heard as "Lask it up!" conf 0.509) must not reach
# computer_use/spawn — the router-LLM would otherwise INHERIT the
# previous turn's CU action from the conversation context. Outside an
# episode there is nothing to inherit and the vehicle stays.
if isinstance(_turn_tools, dict):
_turn_tools = self._hide_action_tools_on_signalless_turn(
_turn_tools, user_text
)
# Plugin-tool spawn-hide (forensic 2026-06-27, voice 17:44): "Schau
# mal nach was in meinem Google Calendar am 29. ist" spawned a worker
# ("umfangreicheres Stueck Arbeit") that has no google_calendar tool
# (plugin tools are router-tier only, AP-5/AP-14) -> "kann ich nicht".
# When a connected plugin's usage-card keywords match the turn, drop
# the spawn vehicles so the router uses the plugin tool DIRECTLY.
if isinstance(_turn_tools, dict):
_turn_tools = self._hide_spawn_when_plugin_tool_handles_turn(
_turn_tools, routing_text
)
# Agentic-IDE pane tools exist only relative to an OPEN workspace
# (2026-07-28 cost audit): with none open they can only fail,
# while their schemas ride every loop iteration. Status/resume
# always stay visible.
if isinstance(_turn_tools, dict):
_turn_tools = self._hide_agentic_ide_tools_without_workspace(
_turn_tools
)
# An artifact is built when the user asks to SEE something, never
# because an answer might look nicer as a page (maintainer mandate
# 2026-08-11). Structural, not prompt-level: on a turn that did not
# ask, the model never sees the tool — and never pays for its schema
# or starts a background mission.
if isinstance(_turn_tools, dict):
_turn_tools = self._hide_artifact_tool_without_request(
_turn_tools, user_text
)
# A referential follow-up that inherited a currently registered
# plugin/MCP tool remains inline even when that tool has no usage
# card. The explicit heavy-work and artifact requests above retain
# their normal mission path.
if (
isinstance(_turn_tools, dict)
and contextual_tool_names
and not self._is_explicit_heavy_request(user_text)
and not self._research_wants_artifact(user_text)
):
_turn_tools = {
name: tool
for name, tool in _turn_tools.items()
if name not in _SPAWN_TOOL_NAMES
}
# PC-control run-skill hide (forensic 2026-07-02, voice 20:28): "ein
# Terminal öffnen, Cloud-Code öffnen, … ein Prompt geben" — an
# explicit desktop request — was hijacked by the semantically-similar
# cloud-debug skill via the SKILLS-FIRST rule and dead-ended in the
# capability refusal. When the user names the desktop vehicle,
# computer_use is authoritative — drop run-skill from the surface.
if isinstance(_turn_tools, dict):
_turn_tools = self._hide_run_skill_on_pc_control_turn(
_turn_tools, user_text
)
# Scheduled work for an agent is a routine, never a draft skill
# with a cron line (live 2026-09-29: "every day at 8" became an
# inactive skill while the routine was reported as set up).
if (
isinstance(_turn_tools, dict)
and self._evidence_required_tool == "society-create-routine"
):
_turn_tools = {n: t for n, t in _turn_tools.items() if n != "create-skill"}
# AI Pointer: on a deictic pointer turn the cursor crop is already the
# only attached image, so drop the redundant ``inspect-pointer`` PULL
# tool (calling it produced an empty spoken answer — observed live).
# The full-screen ``screenshot`` tool is deliberately KEPT: removing it
# made the router refuse "Was siehst du hier?" with "I lack a tool"
# (the capability gate maps "see" to a vision tool). With the tool
# present there is no refusal, and the injected crop + prompt steer the
# brain to answer from the crop, not the whole screen. See
# docs/plans/ai-pointer/DESIGN.md.
if pointing_turn and isinstance(_turn_tools, dict):
_turn_tools = {
k: v for k, v in _turn_tools.items() if k != "inspect-pointer"
}
# Screen-relevance gate (2026-06-14): the on-demand ``screenshot``
# tool is only in scope when the utterance refers to the screen (or
# an image is attached / it is a pointer turn). On a plain
# conversation or cut-off small-talk fragment the brain must not be
# able to reach for — and then narrate — the screen.
if isinstance(_turn_tools, dict):
_turn_tools = self._gate_screen_tool(
_turn_tools,
user_text=user_text,
has_image=bool(images),
pointing_turn=pointing_turn,
)
# A brain that cannot inspect pixels must never be OFFERED the
# screenshot tool — see _hide_screenshot_for_blind_brain.
if isinstance(_turn_tools, dict):
_turn_tools = self._hide_screenshot_for_blind_brain(
_turn_tools, brain, prov_name=prov_name, model=model
)
if turn_override is not None:
# The caller's extra hands (a chat's folder tools) join the
# surface AFTER every gate above, and a plan-mode filter runs
# last — the gates decide what Jarvis may reach for, the
# override only adds a folder and, in plan mode, takes the
# writing hands away.
_turn_tools = self._apply_turn_override_tools(_turn_tools, turn_override)
# Active-model self-awareness: stamp the provider/model that is about
# to answer so _build_system_prompt injects the correct, specific
# self-identity (anti-"I'm Gemini" hallucination, forensic 2026-06-20).
# Set here — after dead/cooldown skips — so it always names the
# provider that genuinely runs this attempt, including a fallback win.
self._active_turn_identity = (prov_name, model)
# Delegated realtime voice turns get hard loop bounds so an
# unbounded delegate can never run away (live 2026-07-14: 14
# rounds / 66 s on "what is in my wiki"). They are ceilings, not
# targets — see _DELEGATE_MAX_TURNS for why the round budget and
# the wall clock carry different numbers. On either bound the loop
# forces ONE final tool-less round over the evidence already
# gathered, so the user still hears a grounded answer. Classic
# turns call with the unchanged signature (kwargs only on
# delegation).
_disp_kwargs: dict[str, Any] = (
{
"max_turns": _DELEGATE_MAX_TURNS,
"deadline_s": _DELEGATE_DEADLINE_S,
"reasoning_effort": _DELEGATE_REASONING_EFFORT,
"delegated_voice": True,
}
if prefer_tool_model
else self._override_dispatch_kwargs(turn_override)
)
await _settle_context_window(brain)
disp = self._build_dispatcher(
brain, tools_override=_turn_tools, **_disp_kwargs
)
# Intelligent router: the router LEAD must NOT stream its conversational
# text to TTS. On the streaming path (generate_stream) text_consumer
# speaks each chunk live DURING dispatch — so a no-tool router answer
# would be spoken and THEN the fall-through talker would speak again
# (double answer). Suppress the consumer for the lead: if it picks a
# tool, the result is surfaced by generate_stream's final reconciliation
# (nothing was yielded → it yields holder["final"]); if it picks none,
# the chosen talker streams the answer normally after the fall-through.
_is_router_lead = self._router_lead_key == (prov_name, model)
_attempt_consumer = None if _is_router_lead else text_consumer
try:
# CostMeter: start per-trace tracking (idempotent if already started).
if self._cost_meter is not None:
self._cost_meter.start(trace_uuid, prov_name, model)
agg = await disp.dispatch(
user_text,
images=images,
history=history,
trace_id=trace_id,
intent_level=decision.level,
evidence_required_tool=self._evidence_required_tool,
text_consumer=_attempt_consumer,
ack_emitter=_tool_ack_emitter,
on_progress=on_progress,
turn_context=turn_context,
reply_language=self._reply_language,
conversation_language=self._conversation_language,
voice_confirm=(allow_voice_confirm and self._voice_confirm_enabled),
)
# Post-call cost hook: aggregated usage → meter.
# The meter cancels on overrun via CancelToken (see ADR-0006);
# the pre-call gate above catches that on the next turn.
if self._cost_meter is not None and agg.usage:
usd = _estimate_usd_from_usage(self._cost_meter, model, agg.usage)
self._cost_meter.add(CostRecord(
trace_id=trace_uuid, provider=prov_name, model=model,
tokens_in=int(agg.usage.get("input_tokens", 0)),
tokens_out=int(agg.usage.get("output_tokens", 0)),
tokens_cache_hit=int(agg.usage.get("cache_hit_tokens", 0)),
usd=usd, timestamp_ns=time.time_ns(),
))
# Empty-Response-Guard: wenn der Provider zwar erfolgreich
# antwortet aber **leeren** Content liefert (Safety-Block,
# truncated-Response, Schema-Mismatch), behandeln wir das wie
# einen Soft-Fail und gehen zum naechsten Provider in der
# Chain. Frueher: response_text = "" + break → die globale
# `if not response_text`-Logik unten verschickte dann irrefuehrend
# "Provider X, Y unerreichbar" statt einen anderen Provider zu
# probieren. Empty != fail-permanently, aber empty != success.
#
# 2026-04-29 Fix: Tool-Calls + suppress_response sind LEGITIME
# leere Texte. Beispiel: spawn_worker ist fire-and-forget
# mit suppress_response=True; der Tool-Use-Loop setzt dann
# final_agg.text="" und finish_reason="suppress_response". Vorher
# hat das den Empty-Response-Guard getriggert, der dann zum
# naechsten Provider gefallen ist — der hat denselben Spawn
# nochmal probiert. Die Folge: 3 Provider gecallt, 2 Spawns
# abgelehnt, drittes fiel auf multi_spawn zurueck und
# scheiterte ebenfalls.
response_empty = not (agg.text or "").strip()
# A REQUESTED tool call only excuses empty text when a tool
# could actually have run. On a turn that offered NO tools at
# all — a Screen Context turn strips every one of them — a
# model-emitted call executed nothing by construction, so
# treating it as a legitimate silence is always wrong.
#
# Live 2026-08-02 09:58: "kannst du bitte schnell einen
# Screenshot machen?" captured the screen correctly, the one
# vision-capable provider in the chain answered with 1170
# tokens of reasoning, zero text and finish_reason=tool_calls,
# this guard read it as legitimate, no other provider was
# tried, and the user heard "that didn't work just now" while a
# fresh screenshot sat unused. Gating on ``_turn_tools`` keeps
# the tools-present behaviour byte-identical, so no executed
# side effect can ever be re-run by a fallback.
tool_calls_executed = bool(agg.tool_calls) and bool(_turn_tools)
suppressed = (agg.finish_reason == "suppress_response")
if response_empty and not tool_calls_executed and not suppressed:
log.warning(
"Brain %s(%s) lieferte leeren Content — "
"vermutlich Safety-Block oder Empty-Response. "
"Versuche naechsten Provider in der Chain.",
prov_name, model,
)
provider_errors.append((
prov_name, model, "empty_response",
"Provider gab leere Antwort zurueck (Safety/Schema?)",
))
continue
# INTELLIGENT ROUTER fall-through: this attempt is the tool-capable
# router LEAD that was prepended for a tool-incapable talker. It got
# first crack at tool selection; if it picked NO tool (pure
# conversation) and a chosen talker follows in the chain, discard
# its answer and fall through so the user keeps their selected
# brain's voice. A tool it DID select (tool_calls non-empty) breaks
# normally below and IS the turn's result. Placed BEFORE the events
# publish below, so the discarded router turn is not recorded as the
# turn; its cost was metered above (it genuinely ran). Reversible
# via [brain.routing].intelligent_router (then _router_lead_key is
# never set, so this never fires).
if (
self._router_lead_key == (prov_name, model)
and not tool_calls_executed
and idx < len(chain) - 1
):
log.info(
"Intelligent router: %s picked no tool — falling through to "
"%s for the conversational answer.",
prov_name, chain[idx + 1][0],
)
continue
response_text = agg.text
# Honest mid-answer error notice (AD-OE6): the model round
# AFTER tool execution died mid-stream (the provider sent
# finish_reason="error") and produced no text. The empty-
# response guard above is correctly skipped when tool calls
# exist, so without this branch the turn counts as a success
# with empty text and the user hears NOTHING (forensic
# 2026-07-05, session 3e27dd8e, 223k-token round). Do NOT
# fall through to the next provider — the executed tools
# would re-run their side effects; speak honestly instead.
if (
response_empty
and tool_calls_executed
and str(agg.finish_reason or "") == "error"
):
response_text = i18n_catalog.pick(
_MID_ANSWER_ERROR_PHRASES, self._resolve_turn_lang()
)
log.warning(
"Brain %s(%s): stream ended finish_reason=error AFTER "
"%d tool call(s) — speaking the honest mid-answer "
"error notice instead of an empty (silent) turn.",
prov_name, model, len(agg.tool_calls),
)
# Record whether THIS (winning) turn was a fire-and-forget
# ``suppress_response`` spawn, so the voice pipeline can stay
# silent for it but speak a clarifying question for a different
# empty turn (function_call/CU without speech). See
# ``SpeechPipeline._handle_silent_brain_turn``.
self._last_turn_suppressed = suppressed
# AD-OE6 companion signal #2: did THIS winning turn SUCCESSFULLY
# execute a desktop-action tool (computer_use / open_app / …)?
# If so and it produced no narration, the voice pipeline speaks
# a success confirmation instead of a clarifying question
# (live bug 2026-06-09). Read ``executed_tool_names`` — the tools
# that REALLY ran — not ``tool_calls`` (which also holds calls a
# guard blocked, e.g. computer_use refused on a how-to question);
# speaking "Erledigt." for a blocked action would be a lie.
executed = getattr(agg, "executed_tool_names", None) or set()
self._last_turn_executed_action_tool = bool(
set(executed) & _DESKTOP_ACTION_TOOL_NAMES
)
# Remember the tools that REALLY ran so the post-recovery
# evidence-gate enforcement (below) can tell whether a mandated
# tool was actually called this turn.
_turn_executed = set(executed)
used_provider, used_model = prov_name, model
if turn_override is None:
_health_ledger.record_success(
prov_name, _health_ledger.MODALITY_BRAIN, model=model
)
# Bug C Fix (2026-04-29) — BrainTurnStarted/Completed publishen
# NUR wenn der Brain-Call erfolgreich war (Stream lieferte
# Tokens oder Tool-Calls). Vorher: Event wurde publisht bevor
# _ensure_client crashte → Halluzinations-Tag in voice_turns
# ("openai/gpt-4o" ohne Key). Jetzt: wir wissen dass dieser
# Call wirklich Daten lieferte (`continue`-Pfade kommen hier
# nicht an), also schreiben wir nur den ECHTEN Provider in
# die Voice-Session-DB.
tokens_in_total = int(agg.usage.get("input_tokens", 0)) if agg.usage else 0
tokens_out_total = int(agg.usage.get("output_tokens", 0)) if agg.usage else 0
# Every plugin reports cache hits under the protocol key and
# keeps ``input_tokens`` to the uncached share.
tokens_cached_total = int(agg.usage.get("cache_hit_tokens", 0)) if agg.usage else 0
cost_usd_total = await _turn_cost_usd(
prov_name, model, tokens_in_total, tokens_out_total, tokens_cached_total
)
await self._bus.publish(BrainTurnStarted(
provider=prov_name,
model=model,
intent_level=decision.level,
))
await self._bus.publish(BrainTurnCompleted(
provider=prov_name,
model=model,
tokens_in=tokens_in_total,
tokens_out=tokens_out_total,
tokens_cached=tokens_cached_total,
cost_usd=cost_usd_total,
text_len=len(response_text or ""),
finish_reason=str(getattr(agg, "finish_reason", "ok") or "ok"),
))
if turn_override is not None:
turn_override.receipt.record(
provider=prov_name,
model=model,
tokens_in=tokens_in_total,
tokens_out=tokens_out_total,
cost_usd=cost_usd_total,
finish_reason=str(getattr(agg, "finish_reason", "ok") or "ok"),
)
if idx > 0:
log.info(
"Fallback-Hit: %s(%s) — %d provider übersprungen",
prov_name, model, idx,
)
if screen_turn_t0 is not None:
log.info(
"screen-turn answered by %s(%s) in %d ms (skipped=%d)",
prov_name,
model,
int((time.perf_counter() - screen_turn_t0) * 1000),
idx,
)
# Under an override the pick answering after its router
# lead is the plan, not a fallback: the sidebar and its
# "Brain -> X" toast follow this event, and the live brain
# did not move (review 2026-08-25).
if turn_override is None:
await self._bus.publish(BrainProviderSwitched(
from_provider=self._active_name,
to_provider=prov_name,
))
break
except Exception as exc: # noqa: BLE001
last_exc = exc
msg = str(exc)
# Classify FIRST so a terminal-billing 429 ("credits depleted",
# "insufficient_quota") is treated as a DEAD provider, not a
# transient rate-limit that keeps the empty provider leading the
# chain every turn (live forensic 2026-06-28: a depleted Gemini
# router bricked the whole turn even though OpenRouter was funded
# — AP-22). Only a genuinely transient 429 takes the cooldown path.
kind = _classify_provider_error(msg, default="call_fail")
# A window too small for one request says nothing about whether
# the provider works; recording it would turn its status dot
# red for a setting, not a fault.
if turn_override is None and kind != "local_context":
_health_ledger.record_failure(
prov_name, _health_ledger.MODALITY_BRAIN, exc, model=model
)
if kind == "rate_limit":
self._rate_tracker.mark_rate_limited(prov_name, model)
log.warning("Rate-Limited %s(%s) — 30s Cooldown aktiviert", prov_name, model)
provider_errors.append(
(prov_name, model, "rate_limit", "HTTP 429"))
else:
log.warning("Brain %s(%s) fehlgeschlagen: %s", prov_name, model, exc)
if (
turn_override is None
and kind in _DEAD_LIST_KINDS
and prov_name not in self._dead_providers
):
# account_blocked (e.g. a bare 402) is model-scoped when
# the SAME provider still has an untried model later in
# this turn's chain (a capped paid model with a funded
# free model behind it, tests/unit/brain/
# test_depleted_credits_classification.py covers only the
# classifier, not this chain policy). missing_key/bad_key
# are credential problems and stay provider-wide — a dead
# key blocks every model, not just this one.
remaining_model = any(
other_name == prov_name
and other_model != model
and (other_name, other_model) not in self._dead_provider_models
for other_name, other_model in chain[idx + 1:]
)
if kind == "account_blocked" and remaining_model:
self._dead_provider_models.add((prov_name, model))
log.warning(
"Model %s(%s) billing-blocked — anderes Modell "
"desselben Anbieters bleibt in dieser Kette aktiv.",
prov_name, model)
else:
self._dead_providers.add(prov_name)
log.warning(
"Provider %s fuer diese Session deaktiviert (%s) — die Kette "
"weicht auf einen anderen verfuegbaren Anbieter aus. "
"Setup: Sidebar -> API-Keys.", prov_name, kind)
# The local-context sentence ends with the setting to
# change; cutting it at 200 chars would drop exactly that.
detail = msg if kind == "local_context" else msg[:200]
provider_errors.append((prov_name, model, kind, detail))
# NOTE BUG-019 (2026-05-11): this generic ``continue`` does
# not touch the failing provider's *internal* state. For
# most providers that's correct (an HTTP error is purely
# transient). For Gemini specifically, however, a 403
# "CachedContent not found" means the locally-cached
# ``self._cached_content_name`` is stale — and because we
# don't clear it here, every subsequent voice turn re-uses
# the same dead cache id and re-fails, sending the whole
# fallback chain into the 40-second pipeline timeout and
# leaving the user with silent THINKING → LISTENING. The
# root-cause annotation lives at the actual failure site
# in ``dodaios/plugins/brain/gemini.py`` (search for
# "BUG-019 ROOT CAUSE"). The right place to fix this is
# *inside* the provider (catch the cache-not-found error,
# call its own ``invalidate_cache()``, retry without the
# cached_content field) — not by leaking Gemini-specific
# error matching into this cross-provider chain.
continue
# When `used_provider` is set, AT LEAST ONE provider completed the turn
# successfully — even if `response_text` is empty (e.g. suppress_response
# for fire-and-forget tools like spawn_worker). In that case do NOT
# return the "all failed" message — the UI receives feedback via bus events
# (JarvisAgentAnnouncement, etc.).
# B5 Agent C: reset per-turn wiki suffix regardless of outcome so
# stale context cannot leak into the next voice turn.
self._wiki_context_suffix = ""
if screen_context.has_image and not vision_capable_seen:
from dodaios.screen_context.intent import ( # noqa: PLC0415
no_vision_provider_reply,
)
language = _turn_phrase_language(self, user_text)
response_text = no_vision_provider_reply(language)
await self._record_response_side_effects(
user_text=user_text,
response_text=response_text,
use_history=use_history,
trace_id=trace_uuid,
)
return response_text
if used_provider is None:
self._last_turn_all_failed = True
log.error("Alle %d Provider-Versuche fehlgeschlagen. Letzter Fehler: %s",
len(chain), last_exc)
# Developer diagnostic → LOG only. The voice path gets a localized,
# provider-agnostic apology (live complaint 2026-06-01: the grok/
# Anthropic billing diagnostic was spoken while Gemini was active).
log.warning(
"Spoken fallback used instead of chain diagnostic: %s",
_format_provider_chain_error(provider_errors),
)
return await self._provider_down_reply(
trace_uuid, cause=_primary_provider_down_cause(provider_errors)
)
# Text-serialized calls are recovered inside BrainDispatcher's shared
# ToolUseLoop, where the exact turn-scoped tool surface, deadline,
# safety guards, and exactly-once tracking remain authoritative. Never
# re-parse and execute here against the manager-global tool registry:
# that old fallback bypassed per-turn plugin/screen/deadline gates.
# Two-turn voice/chat confirmation (turn N): the tool-use loop deferred a
# consequential tool and produced a confirmation QUESTION as its text.
# Arm the pending state and return the question directly — the leaked-tool
# recovery + evidence gate below do not apply to a deferral (no tool ran,
# nothing to recover; the answer is a question, not an unverified claim).
if (
getattr(agg, "finish_reason", "") == "voice_confirm_pending"
and getattr(agg, "voice_confirm", None)
):
self._arm_voice_confirm(agg.voice_confirm, user_text)
await self._record_response_side_effects(
user_text=user_text, response_text=agg.text,
use_history=use_history, trace_id=trace_uuid,
)
return agg.text
# ONE output-language resolution for every honesty phrase this turn
# (one resolver decides the turn for ALL layers). The two
# guards below used to resolve separately with DIFFERENT defaults
# ("de" here, DEFAULT_LOCALE there), so an undetectable turn could speak
# a German evidence fallback followed by an English honesty phrase in the
# same breath. All locales are equal — the shared DEFAULT_LOCALE decides.
honesty_lang = _turn_phrase_language(self, user_text)
# Evidence-gate enforcement (live repro 2026-06-17, session 296abc82):
# the gate MANDATED a tool this turn, but neither the normal tool loop
# nor the leaked-tool recovery above actually ran it — so the model's
# answer is unverified, at worst a confabulation ("the gcloud tool
# blocked execution because it classified the request as an explanatory
# question"). Replace it with an honest non-data fallback; never speak an
# answer a mandated read tool was supposed to ground. Shared-loop leak
# recovery has already populated ``_turn_executed`` when it succeeded.
if self._evidence_required_tool:
from dodaios.brain.public_fact_gate import (
PUBLIC_FACT_CLARIFY_DOMAIN,
PUBLIC_FACT_DOMAIN,
public_fact_answer_unverified,
public_fact_clarifying_question,
public_fact_unfulfilled_answer,
)
if self._evidence_required_domain == PUBLIC_FACT_CLARIFY_DOMAIN:
# Too vague to search: ask, in the conversation's language (the
# small model asked its own question in English on 2026-10-28).
_replacement = (
None
if self._last_turn_suppressed
else public_fact_clarifying_question(honesty_lang)
)
elif self._evidence_required_domain == PUBLIC_FACT_DOMAIN:
# The system search grounds the fact check only. It is not a
# tool the model ran, so it must not silence the action-honesty
# gate later in this turn.
_fact_executed = _turn_executed
if getattr(self, "_public_fact_prefetched", False):
_fact_executed = {*_turn_executed, self._evidence_required_tool}
_replacement = (
public_fact_unfulfilled_answer(honesty_lang)
if public_fact_answer_unverified(
response_text,
executed=_fact_executed,
suppressed=self._last_turn_suppressed,
)
else None
)
else:
_replacement = _unfulfilled_replacement(
required_tool=self._evidence_required_tool,
executed=_turn_executed,
response_text=response_text,
suppressed=self._last_turn_suppressed,
is_write=self._evidence_required_is_write,
lang=honesty_lang,
domain=self._evidence_required_domain,
)
if _replacement is not None:
log.warning(
"Mandated tool %s never ran (executed=%s, write=%s) — "
"replacing the unverified answer with an honest fallback.",
self._evidence_required_tool,
sorted(_turn_executed),
self._evidence_required_is_write,
)
response_text = _replacement
if turn_override is not None:
turn_override.receipt.mark_guard_failure("mandated_tool_unfulfilled")
# A "[used tool …]" line in the model's text is an imitation of the
# chat history marker, never a call (live 2026-10-28: an invented train
# story behind "[used tool search_web]"). A claimed search that never
# ran makes the whole answer a guess; any other marker is dropped.
from dodaios.brain.tool_marker import strip_tool_markers
_marker_free, _claimed_tools = strip_tool_markers(response_text)
if _claimed_tools:
_marker_executed = _turn_executed
if getattr(self, "_public_fact_prefetched", False):
_marker_executed = {*_turn_executed, "search_web"}
_phantom = sorted(set(_claimed_tools) - set(_marker_executed))
if "search_web" in _phantom:
from dodaios.brain.public_fact_gate import public_fact_unfulfilled_answer
log.warning(
"Model typed a search_web marker but no search ran — "
"replacing the unverified answer."
)
response_text = public_fact_unfulfilled_answer(honesty_lang)
if turn_override is not None:
turn_override.receipt.mark_guard_failure("unbacked_action_claim")
else:
if _phantom:
log.warning("Model typed markers for tools that never ran: %s", _phantom)
response_text = _marker_free
execution_evidence = set(_turn_executed)
full_action_fallback = not execution_evidence and has_unbacked_action_claim(response_text)
honest_response = replace_unbacked_action_claim(
response_text,
executed_tools=execution_evidence,
language=honesty_lang,
)
if honest_response != response_text:
log.warning(
"Blocked a model action promise with no execution evidence."
)
response_text = honest_response
if full_action_fallback and turn_override is not None:
turn_override.receipt.mark_guard_failure("unbacked_action_claim")
# 4. History + Events
if use_history:
self._history.append(BrainMessage(role="user", content=user_text))
self._history.append(BrainMessage(role="assistant", content=response_text))
if len(self._history) > 40:
self._history = self._history[-40:]
await self._publish_response_generated(
trace_id=trace_uuid,
text=response_text,
)
# Fire-and-forget: the curator extracts personal facts from the turn
# and merges them into USER.md / people/*.md in a controlled manner.
# Runs async, does not block the response.
if self._curator is not None and not (
(profile_override := _TURN_OVERRIDE.get()) is not None
and profile_override.tool_context.get("tool_origin") == "society"
):
try:
asyncio.create_task(
self._curator.process_turn(user_text, response_text),
name="curator-process-turn",
)
except RuntimeError:
# No running event loop (sync context) — skip.
log.debug("Curator-Task nicht scheduled (kein Event-Loop)")
return response_text
def inject_images_for_turn(
self, trace_id: UUID, images: tuple[ImageBlock, ...]
) -> None:
"""Attach ad-hoc ``images`` to the upcoming turn identified by ``trace_id``.
Used by the drag-drop intake (``dodaios/brain/drop_context.py``) so a
dropped picture reaches the multimodal brain. The images are consumed by
``_collect_vision_images`` on that turn and never carry over. A no-op for
an empty tuple. ``trace_id`` is unique per turn → race-free.
"""
if not images:
return
# Defensive: tolerate a manager built via __new__ (some unit tests bypass
# __init__), mirroring how _vision_provider is accessed via getattr.
if getattr(self, "_pending_turn_images", None) is None:
self._pending_turn_images = {}
self._pending_turn_images[trace_id] = tuple(images)
def add_dropped_context(
self, text: str, images: tuple[ImageBlock, ...] = ()
) -> None:
"""Stash drag-and-dropped content as SILENT conversation context.
A drop must NOT trigger a brain turn — the user keeps the normal speaking
flow, and the dropped content is simply remembered and used on the NEXT
real turn (a drop while idle is kept for next time; a drop mid-flow joins
the running context). The text is appended to history as a user-context
message so it is naturally in the next turn's context (and persists for
follow-ups); images are parked and consumed once by the next
``generate`` call. getattr-guarded for managers built via ``__new__``.
"""
if text and text.strip():
if getattr(self, "_history", None) is None:
self._history = []
self._history.append(BrainMessage(role="user", content=text.strip()))
if len(self._history) > 40:
self._history = self._history[-40:]
log.info(
"📎 DROP CONTEXT stashed: %d text chars, %d images "
"(history now %d msgs, pending drop images %d)",
len(text or ""), len(images),
len(getattr(self, "_history", []) or []),
len(getattr(self, "_pending_drop_images", ()) or ()) + len(images),
)
if images:
cur = getattr(self, "_pending_drop_images", ()) or ()
self._pending_drop_images = tuple(cur) + tuple(images)
async def _collect_vision_images(
self,
*,
trace_id: UUID,
user_text: str = "",
is_smalltalk: bool = False,
) -> tuple[ImageBlock, ...]:
"""Returns the current screen as an ImageBlock for the brain turn.
Factory/voice start the VisionContextProvider on the BrainManager.
Without this bridge, blobs were captured but the actual brain call
remained text-only.
"""
# Drag-drop: ad-hoc images injected for THIS turn win over (and bypass)
# the screen-vision path — a dropped picture matters, not the current
# screen, and it must arrive even with screen-vision off. Pop so it is
# used exactly once. getattr-guarded for managers built via __new__.
pending = getattr(self, "_pending_turn_images", None)
if pending:
injected = pending.pop(trace_id, None)
if injected:
return injected
# A turn under a WRITE mandate is an ACTION turn, not a vision turn
# (shell-consistency rework 2026-08-08): an attached image narrows the
# tool surface downstream (_image_turn_tool_override), and the mandated
# write tool is the one it must not lose. "erstell einen Ordner
# hier auf dem Desktop" carries the visual marker "hier auf" yet wants
# a shell action, not a screen answer — same for a mandated contact/
# wiki write. Read mandates are untouched (they never attach anyway:
# their data comes from the mandated tool, not the screen).
if getattr(self, "_evidence_required_is_write", False):
log.info("Vision-Inject skipped: write-mandate action turn")
return ()
vision = getattr(self, "_vision_provider", None)
vision_none = vision is None
paused = (
bool(getattr(vision, "is_paused", False))
if vision is not None
else None
)
log.info(
"Vision-Inject Diagnose: path=BrainManager vision_none=%s "
"is_paused=%s brain_provider=%s",
vision_none,
paused,
self._active_name,
)
if vision is None or paused:
return ()
# Wave 1 (omni-latency): conditional vision — skip the screenshot on
# confidently text-only turns (skip-when-safe). Keep the per-turn image
# tax only where the screen might actually matter. Anti-regression vs.
# 2026-04-28: when in doubt, the gate keeps the image.
perf = getattr(self._config, "performance", None)
if getattr(perf, "conditional_vision", False):
from dodaios.brain.vision_gate import should_attach_screenshot
if not should_attach_screenshot(user_text, is_smalltalk=is_smalltalk):
log.info("Vision-Inject skipped: text-only turn (%r)", user_text[:60])
return ()
try:
from dodaios.brain.router import _read_observation_image_b64
obs = await asyncio.wait_for(
vision.current(), timeout=_VISION_COLLECT_TIMEOUT_S
)
hash_prefix = (obs.screenshot_hash or "")[:16]
geometry = tuple(
getattr(obs, "monitor_geom", (0, 0, 0, 0))
or (0, 0, 0, 0)
)
width, height = (
(int(geometry[2]), int(geometry[3]))
if len(geometry) >= 4
else (0, 0)
)
capture_age_ms = max(
0, int((time.time_ns() - obs.timestamp_ns) / 1_000_000)
)
log.info(
"Vision-Inject Observation: screenshot_hash=%s "
"dimensions=%dx%d capture_age_ms=%d",
hash_prefix,
width,
height,
capture_age_ms,
)
mime, image_b64 = await _read_observation_image_b64(obs)
# Wave 1 (omni-latency): enforce max_image_kb (was dead config) —
# cap the per-turn payload before it ships; no-op if already small.
from dodaios.vision.image_budget import cap_image_b64
vcfg = getattr(getattr(self._config.brain, "router", None), "vision", None)
max_kb = int(getattr(vcfg, "max_image_kb", 0) or 0)
if max_kb > 0:
mime, image_b64 = cap_image_b64(mime, image_b64, max_kb * 1024)
log.info(
"Vision-Inject encoded: brain_provider=%s mime=%s "
"screenshot_hash=%s len_image_b64=%d",
self._active_name,
mime,
hash_prefix,
len(image_b64),
)
if self._bus is not None:
bytes_size = len(image_b64) * 3 // 4
age_ms = int((time.time_ns() - obs.timestamp_ns) / 1_000_000)
await self._bus.publish(VisionInjected(
trace_id=trace_id,
screenshot_hash=obs.screenshot_hash,
bytes_size=bytes_size,
capture_age_ms=age_ms,
))
return (
ImageBlock(
mime=mime,
data_b64=image_b64,
source_hash=obs.screenshot_hash,
),
)
except TimeoutError:
log.warning(
"Vision-Inject skipped: capture exceeded %.1fs — proceeding "
"text-only (no hot-path hang). brain_provider=%s",
_VISION_COLLECT_TIMEOUT_S,
self._active_name,
)
return ()
except Exception as exc: # noqa: BLE001
log.error(
"Vision-Inject fehlgeschlagen: path=BrainManager "
"brain_provider=%s exc=%r",
self._active_name,
exc,
exc_info=True,
)
return ()
# Pipeline-Adapter
async def __call__(self, text: str) -> str:
return await self.generate(text)
async def generate_stream(
self,
user_text: str,
*,
use_history: bool = True,
trace_id: UUID | None = None,
on_progress: Callable[[], None] | None = None,
allow_voice_confirm: bool = False,
conversation_id: str | None = None,
consume_pending_voice_attachments: bool = False,
) -> AsyncIterator[str]:
"""Latency sprint 1: streaming variant of ``generate``.
Yields each brain text chunk in real time. Tool-use loops run as
usual; pre-tool-use text is also streamed (the persona prompt forbids
fillers, so this is uncritical). Evidence-gated turns are buffered
until ``generate`` returns its authoritative final text, because the
post-call evidence or action-honesty enforcement may replace an
unverified stream.
``on_progress`` (stall-timeout signal): forwarded to the tool-use loop,
which pings it at every model-round + tool boundary. The speech pipeline
passes its ``_mark_brain_progress`` here so its *no-progress* deadline
resets while a vision/tool turn is genuinely working but streaming no
text (live bug 2026-06-01). ``None`` (default) is a no-op.
Consumed via an ``asyncio.Queue`` between the producer task
(``generate``) and the caller (``async for``). If the caller cancels
the generator, the producer is also cancelled.
Callers can reassemble the final aggregated text from the yielded
chunks themselves — a helper may be added later if needed.
"""
queue: asyncio.Queue[str | None] = asyncio.Queue()
sentinel: str | None = None
# generate() returns the FINAL text — recovery-corrected when a leaked
# tool_use was executed (see _recover_leaked_tool). Streaming previously
# discarded this (BUG-028 pattern), so a leaked action-tool reached TTS
# as raw JSON and the action was lost. We capture it here.
holder: dict[str, str | None] = {"final": None}
context = tuple(
str(message.content or "")
for message in (
(getattr(self, "_history", ()) or ())[-8:]
if use_history
else ()
)
)
action_buffered = plan_turn(user_text, context=context).requires_orchestrator
def _consumer(chunk: str) -> None:
# ``put_nowait`` because the consumer is called on the sync
# aggregator path (no await possible). Queue is unbounded.
try:
queue.put_nowait(chunk)
except Exception: # noqa: BLE001
pass
async def _producer() -> None:
try:
holder["final"] = await self.generate(
user_text,
use_history=use_history,
trace_id=trace_id,
text_consumer=_consumer,
on_progress=on_progress,
allow_voice_confirm=allow_voice_confirm,
conversation_id=conversation_id,
consume_pending_voice_attachments=(
consume_pending_voice_attachments
),
)
finally:
# Sentinel signals "brain is done (or crashed)".
queue.put_nowait(sentinel)
task = asyncio.create_task(_producer(), name="brain-stream-producer")
accumulated = ""
holding = False
held = ""
leaked = False
yielded = False
evidence_buffered = False
try:
while True:
chunk = await queue.get()
if chunk is sentinel:
break
accumulated += chunk
# A provider sometimes streams a tool_use block as TEXT instead
# of invoking it ("oeffne den Editor" -> open_app/dispatch JSON).
# Withhold those chunks so the raw JSON is never spoken (it would
# scrub to silence and the action would be lost). generate()
# recovers + executes the leaked tool and returns a speakable
# result, which we yield once the stream ends.
#
# A growing buffer cannot tell a leak from an answer that merely
# OPENS with a bracket — "[Doku](…)", a JSON example. So the
# shape test only HOLDS the chunks; the verdict is taken once,
# after the sentinel, on the finished buffer. Held prose is
# released there instead of being dropped for the rest of the
# turn, which is what used to swallow such answers whole.
if not holding and _may_be_tool_use_leak(accumulated):
holding = True
evidence_now = bool(getattr(self, "_evidence_required_tool", ""))
if evidence_now:
evidence_buffered = True
if holding:
held += chunk
continue
if evidence_now:
continue
if action_buffered:
continue
yield chunk
yielded = True
if holding:
leaked = _looks_like_tool_use_leak(accumulated)
if (
not leaked
and not evidence_buffered
and not action_buffered
and held.strip()
):
# Never a tool call — ordinary speech that happened to open
# with "[" or "{". The user gets the whole answer.
yield held
yielded = True
# Surface generate()'s authoritative final text whenever NOTHING was
# streamed to TTS — either because a leaked tool_use JSON was
# withheld, OR because the brain produced a STRUCTURED / suppress
# tool-call with no text chunks at all (dispatch_to_harness result,
# spawn_worker ACK, recovered tool). Without this the user hears
# silence on exactly those action turns — live repro 2026-05-25
# "oeffne mir Chrome" returned empty while plain chat worked. The
# old code only surfaced the final on the leaked-JSON path.
if leaked or not yielded or evidence_buffered or action_buffered:
final = (holder.get("final") or "").strip()
if final and not _looks_like_tool_use_leak(final):
yield final
elif leaked:
yield await render_readback(
getattr(self, "_readback_composer", None),
instruction=(
"A tool action was recognized but could not be "
"carried out; tell the user plainly."
),
language=self._direct_ack_language(user_text),
canned=lambda: self._action_failed_phrase(user_text),
)
finally:
if not task.done():
task.cancel()
try:
await task
except (asyncio.CancelledError, Exception): # noqa: BLE001
pass
# ------------------------------------------------------------------
# Summarize — for Jarvis-Agent-Announcements (Phase 5, Wave-4 rebrand)
# ------------------------------------------------------------------
async def summarize(self, text: str, *, max_tokens: int = 120) -> str:
"""Compresses text via the fast model of the active provider.
Purpose: TTS announcements in 1-2 sentences, suitable for speech output.
The stream is fully aggregated and capped at ~max_tokens * 4 characters
(rough UTF-8 token heuristic).
"""
if not text.strip():
return ""
brain = self._get_brain(self._active_name, self._fast_model(self._active_name))
system_prompt = (
"Du fasst Texte in 1-2 Saetzen zusammen, klar und praezise fuer "
"Sprachausgabe. Antworte ausschliesslich mit der Zusammenfassung."
)
req = BrainRequest(
messages=(
BrainMessage(
role="user",
content=f"Fasse in 1-2 Saetzen zusammen, klar und praezise fuer Sprachausgabe: {text}",
),
),
system=system_prompt,
temperature=0.3,
max_tokens=max_tokens,
stream=True,
)
agg = await aggregate(brain.complete(req))
summary = (agg.text or "").strip()
char_cap = max_tokens * 4
if len(summary) > char_cap:
summary = summary[:char_cap].rstrip()
return summary
# ------------------------------------------------------------------
# Tool-Registry
# ------------------------------------------------------------------
def set_tools(self, tools: dict[str, Tool]) -> None:
self._tools = dict(tools)
def add_tool(self, tool: Tool) -> None:
self._tools[tool.name] = tool
def clear_history(self) -> None:
self._history = []
self.__dict__.pop("_voice_history_seed", None)
def drop_last_turn(self, expected_user_text: str) -> bool:
"""Remove the most recent (user, assistant) pair when its user message
matches ``expected_user_text`` (whitespace-insensitive).
Used by the voice continuation-recombine path: when a combined turn
supersedes the immediately-preceding committed turn, the truncated half
must not be duplicated in history. Safe no-op when fewer than two
messages are buffered, when the tail is not a user/assistant pair, or
when the tail user text does not match — so it does nothing when the
prior turn was aborted before commit (the common interrupt case).
Returns ``True`` iff a pair was removed.
"""
if len(self._history) < 2:
return False
last = self._history[-1]
prev = self._history[-2]
if last.role != "assistant" or prev.role != "user":
return False
if (prev.content or "").strip() != (expected_user_text or "").strip():
return False
del self._history[-2:]
return True
# Roles the brain conversation buffer accepts for seeding. ``tool``
# messages need a tool_call_id pairing and are never seeded standalone;
# UI-only roles (e.g. ``preamble`` pre-ack bubbles) are not conversation.
_SEEDABLE_ROLES: frozenset[str] = frozenset({"user", "assistant", "system"})
# Same window the auto-append paths enforce (see the ``self._history =
# self._history[-40:]`` trims throughout generate()/force-spawn).
# Maintainer mandate 2026-08-24: full call memory, not a cost window.
_HISTORY_MAX: int = 400
def seed_history(self, turns: Iterable[Any]) -> None:
"""Preseed the conversation buffer with prior turns.
Replaces ``_history`` so a re-opened chat (text continuation via
``POST /api/chats/{kind}/{id}/resume``) or a "Speak in this
conversation" voice session (``.../speak``) continues coherently.
This is the single primitive behind both Chats-manager paths.
Pure in-memory, no LLM call and no I/O — safe to call before a voice
session is armed without touching the voice critical path (AP-9/AP-11).
Accepts an iterable of :class:`BrainMessage`, ``(role, text)`` tuples,
or ``{"role": ..., "content"|"text": ...}`` dicts. Entries whose role
is outside :attr:`_SEEDABLE_ROLES` (e.g. the UI-only ``preamble``
bubble) and entries with empty text are dropped. The result is capped
to :attr:`_HISTORY_MAX`, keeping the most recent turns — an empty
input therefore behaves like :meth:`clear_history`.
"""
self._history = self._seedable(turns)
# Explicit archive selection also seeds the next duplex call. Ordinary
# generated turns never fill this slot: unrelated calls must stay fresh.
self._voice_history_seed = tuple(self._history)
def _seedable(self, turns: Iterable[Any]) -> list[BrainMessage]:
"""``turns`` reduced to seedable messages, newest :attr:`_HISTORY_MAX` kept."""
seeded: list[BrainMessage] = []
for item in turns:
if isinstance(item, BrainMessage):
role: Any = item.role
content: Any = item.content
elif isinstance(item, dict):
role = item.get("role")
content = item.get("content", item.get("text"))
else:
try:
role, content = item
except (TypeError, ValueError):
continue
if role not in self._SEEDABLE_ROLES:
continue
if isinstance(content, str):
if not content.strip():
continue
elif not content:
continue
seeded.append(
item
if isinstance(item, BrainMessage)
else BrainMessage(role=role, content=content)
)
return seeded[-self._HISTORY_MAX :]
def set_voice_history_source(self, source: Callable[[], Iterable[Any]] | None) -> None:
"""Where a call without an explicit seed gets its starting history.
The front page's chat binds the chat a call continues
(``AgentChatService.bind_voice_chat``); the source answers with that
chat's turns at call start, so a second call in the same chat still
knows the first one. ``None`` returns to fresh calls.
"""
if source is None:
self.__dict__.pop("_voice_history_source", None)
else:
self._voice_history_source = source
def drop_voice_history_seed(self) -> None:
"""Forget an explicit seed nobody consumed, so the source answers instead."""
self.__dict__.pop("_voice_history_seed", None)
def take_voice_history_seed(self) -> tuple[BrainMessage, ...]:
"""Consume an explicit resume once, retaining the text brain's history.
A single dict pop transfers ownership even when desktop session setup
runs on a worker thread. Reconnects reuse the receiving call's copy.
Without an explicit seed the bound chat's history answers
(:meth:`set_voice_history_source`); an explicit empty seed — "new
voice chat" — still wins and starts the call fresh.
"""
if "_voice_history_seed" in self.__dict__:
history: tuple[BrainMessage, ...] = self.__dict__.pop("_voice_history_seed", ())
return history
source = self.__dict__.get("_voice_history_source")
if source is None:
return ()
try:
return tuple(self._seedable(source()))
except Exception: # noqa: BLE001 — a call without history beats no call
log.warning("voice history source failed; the call starts fresh", exc_info=True)
return ()
# ------------------------------------------------------------------
# Live reload for the CLI tool registry (CLI integration, task 2)
# ------------------------------------------------------------------
def refresh_tools(self) -> None:
"""Synchronous refresh for callers outside the running event loop."""
snapshot = self._build_tool_snapshot()
if snapshot is not None:
self._apply_tool_snapshot(snapshot)
async def refresh_tools_async(self) -> None:
"""Coalesce registry events and build snapshots without blocking the loop."""
self._tool_refresh_pending = True
task = getattr(self, "_tool_refresh_task", None)
if task is None or task.done():
async def refresh() -> None:
from dodaios.brain.tool_surface import live_tool_surface_fingerprint
while self._tool_refresh_pending:
self._tool_refresh_pending = False
before = live_tool_surface_fingerprint()
snapshot = await asyncio.to_thread(self._build_tool_snapshot)
if snapshot is not None:
self._apply_tool_snapshot(snapshot)
if live_tool_surface_fingerprint() != before:
self._tool_refresh_pending = True
task = asyncio.create_task(refresh(), name="brain-tool-refresh")
self._tool_refresh_task = task
# A cancelled subscriber/turn must not abandon a registry refresh that
# other subscribers are awaiting, or cause another concurrent build.
await asyncio.shield(task)
def _build_tool_snapshot(self):
"""Build replacement dictionaries while preserving the boot-time DI.
Plugin imports and entry-point scans can block for seconds on cold
storage. Running-loop callers execute this on a worker and publish
the complete result back on the loop. No tier means no replacement.
"""
tier = getattr(self, "_tier", None)
if not tier:
log.debug("refresh_tools: no tier set; skipping")
return
try:
# Lazy import: the factory may pull in heavy modules depending on
# config (vision, harness). The import happens only on refresh,
# not during BrainManager setup.
from dodaios.brain.factory import (
_load_local_action_tools,
_load_tools_for_tier,
_resolve_mission_manager,
)
from dodaios.harness.manager import HarnessManager
from dodaios.safety import (
ApprovalWorkflow,
RiskTierEvaluator,
ToolExecutor,
)
except Exception as exc: # noqa: BLE001
log.warning("refresh_tools: factory modules could not be imported: %s", exc)
return
try:
# Minimally invasive re-init for the tool load: the existing
# ToolExecutor is retained (risk policy + approval are session-stable);
# only the tool instances are re-instantiated.
executor = self._tool_executor
if executor is None:
# Fallback: build an executor so tools can still be loaded —
# in practice the manager always has one.
from dodaios.clis.risk_integration import make_cli_patterns_fn
evaluator = RiskTierEvaluator(
self._config.safety,
extra_patterns_fn=make_cli_patterns_fn(),
)
approval = ApprovalWorkflow(self._bus)
executor = ToolExecutor(
self._bus, evaluator, approval,
default_timeout_s=self._config.safety.tool_approval_timeout_s,
)
harness_manager = HarnessManager(bus=self._bus)
# This rebuild runs on EVERY CLI/MCP connect at boot ("Tool-Registry
# refreshed: 29 -> 107"). It must mirror the shared DI references
# the boot path passes, or the rebuilt tools lose their managers
# (live 2026-06-18: contact/spawn_worker went dark after the first
# CLI connected).
new_tools = _load_tools_for_tier(
tier,
bus=self._bus,
executor=executor,
harness_manager=harness_manager,
user_profile=self._user_profile,
people=self._people,
config=self._config,
mission_manager=_resolve_mission_manager(),
contacts=self._contacts,
)
new_local_action_tools = _load_local_action_tools(
bus=self._bus,
harness_manager=harness_manager,
config=self._config,
)
except Exception as exc: # noqa: BLE001
log.warning("refresh_tools: factory call failed: %s", exc)
return
return new_tools, new_local_action_tools
def _apply_tool_snapshot(self, snapshot) -> None:
new_tools, new_local_action_tools = snapshot
old_count = len(self._tools)
self._tools = new_tools
self._local_action_tools = new_local_action_tools
# Record what the sources looked like at THIS load, so the per-turn
# reconcile (tool_surface.maybe_reconcile_tool_surface) only fires on
# genuine drift after a missed BrainToolsChanged.
stamp_tool_surface(self)
log.info(
"Tool-Registry refreshed: %d -> %d tools",
old_count, len(new_tools),
)
def attach_to_bus(self, bus: EventBus | None = None) -> None:
"""Registers live-reload subscriptions on the event bus.
Called after the factory build (``factory.py``). Currently:
- ``BrainToolsChanged`` → ``refresh_tools()``
- ``SecretConfigured`` → ``reactivate_provider()`` for the brain
provider whose key was just set. Prevents a provider that already
failed with "no API key" from being excluded from the fallback chain
until the app is restarted.
- ``AnnouncementRequested`` (CU-tool-tagged) → mirror the router-tier
``computer_use`` outcome into the live history (subsystem-confusion fix).
Called separately rather than in ``__init__`` so BrainManager can be
constructed for tests without a bus subscription.
"""
from dodaios.core.events import (
AnnouncementRequested,
BrainToolsChanged,
SecretConfigured,
)
target_bus = bus or self._bus
if target_bus is None:
return
async def _on_tools_changed(ev: BrainToolsChanged) -> None:
log.info("BrainToolsChanged received (reason=%s); refreshing tools", ev.reason)
await self.refresh_tools_async()
target_bus.subscribe(BrainToolsChanged, _on_tools_changed)
target_bus.subscribe(AnnouncementRequested, self._on_cu_tool_completion)
async def _on_secret_configured(ev: SecretConfigured) -> None:
if ev.action != "set":
return
provider = _SECRET_KEY_TO_BRAIN.get(ev.key)
if not provider:
return
self.reactivate_provider(provider)
# Fresh-install heal (open-source AP-22/AP-23): on a first run there
# is no jarvis.toml, so brain.primary is the packaged code-default
# (e.g. claude-api) that the downloader has NO key for. Setting a key
# for a DIFFERENT provider used to leave that dead default active, so
# the brain kept reporting "not configured" even though a usable key
# was now present — the #1 fresh-laptop symptom. If the currently
# active provider has no usable credential, promote the provider the
# user just keyed to active and persist it. This is NOT the autonomous
# self-switch the USER-ONLY / provider_lock mandate forbids: it fires
# only in direct response to the user's OWN key-set action (the same
# path as a manual "Set as active" click, via config_writer — never
# the locked self-mod writer), and it never overrides a provider the
# user deliberately selected (one that already has a working key or
# OAuth login is left untouched).
if provider == self._active_name:
return # reactivate_provider already re-armed the active one
if self._active_has_usable_credential():
return
previous_active = self._active_name
try:
await self.switch(provider, persist=True)
log.info(
"Fresh-install heal: active brain %r had no usable "
"credential; promoted just-keyed provider %r to active and "
"persisted brain.primary.",
previous_active, provider,
)
except Exception: # noqa: BLE001 — a subscriber must never kill the bus (AP-18)
log.warning(
"auto-activate on key-set failed for provider %r",
provider, exc_info=True,
)
target_bus.subscribe(SecretConfigured, _on_secret_configured)
from dodaios.core.events import ConfigReloaded
async def _on_config_reloaded(ev: ConfigReloaded) -> None:
# Hot-reload the reply-language pin so a Self-Mod / Control-API write
# to ``brain.reply_language`` (SAFE, needs_restart=False) takes effect
# on the NEXT turn without an app restart. The event carries only the
# changed keys, so re-read the persisted value from disk. Never let a
# bad value (ValueError) escape — that would kill the bus (AP-18).
if "brain.reply_language" not in ev.changed_keys:
return
try:
import asyncio as _asyncio
from dodaios.core.config import load_config
# Off the event loop — load_config() is a blocking disk read and
# this subscriber fires on every SAFE-tier config write.
cfg = await _asyncio.to_thread(load_config)
raw = getattr(cfg.brain, "reply_language", "auto")
self.set_reply_language(normalize_reply_language(raw))
except Exception: # noqa: BLE001 — survive without a live switch
log.warning("reply-language hot-reload failed", exc_info=True)
target_bus.subscribe(ConfigReloaded, _on_config_reloaded)
async def _on_proactivity_reloaded(ev: ConfigReloaded) -> None:
# A voice "be less proactive" goes through Self-Mod (SAFE, no
# restart): re-read the persisted level and make it live for every
# surface on the next turn. Never raise into the bus (AP-18).
if "brain.proactivity" not in ev.changed_keys:
return
try:
import asyncio as _asyncio
from dodaios.core.config import load_config
cfg = await _asyncio.to_thread(load_config)
level = _proactivity.apply_level(getattr(cfg.brain, "proactivity", None))
self._config.brain.proactivity = level
except Exception: # noqa: BLE001 — survive without a live switch
log.warning("initiative hot-reload failed", exc_info=True)
target_bus.subscribe(ConfigReloaded, _on_proactivity_reloaded)
# ------------------------------------------------------------------
# Back-compat aliases (for existing tests)
# ------------------------------------------------------------------
@property
def _providers(self) -> dict[str, Brain]:
"""Back-compat: exposes the cache as {provider_name: active_instance}."""
out: dict[str, Brain] = {}
for (name, _model), inst in self._brain_cache.items():
out.setdefault(name, inst)
return out
@property
def _tool_executor_ref(self) -> ToolExecutor | None:
return self._tool_executor
def _get_or_create(self, name: str) -> Brain:
"""Back-compat wrapper — uses the config model when available."""
return self._get_brain(name, self._fast_model(name))
async def use_deep_model(self) -> bool:
deep = self._deep_model(self._active_name)
if not deep:
return False
self._force_level = "deep"
return True
async def use_fast_model(self) -> bool:
fast = self._fast_model(self._active_name)
if not fast:
return False
self._force_level = "fast"
return True
@property
def dispatcher(self) -> BrainDispatcher:
"""Back-compat: builds a dispatcher with the fast model of the active provider."""
brain = self._get_brain(self._active_name, self._fast_model(self._active_name))
return self._build_dispatcher(brain)
def _select_task_tools(self, allowed_tools: tuple[str, ...]) -> dict[str, Tool]:
"""Filter the live tool set down to a per-task allowlist.
Unknown grants (e.g. a plugin that isn't connected) are silently
skipped — the task runs with whatever of its allowlist is live.
A grant is matched by :func:`dodaios.tasks.grants.grant_matches`:
exact name, or the plugin prefix of a bridged MCP tool — the grant
``github`` covers every ``github/<tool>``. (Exact matching alone left
a routine with a ``github`` grant running with ZERO tools.)
A grant naming one of :data:`_TASK_ONLY_TOOLS` that is NOT in the live
(router) set is loaded from its entry point on demand: ``remember`` is
deliberately outside ``ROUTER_TOOLS`` (ADR-0011), yet a scheduled
task that was granted it must be able to store what it found. The
instance is cached per manager and only ever reaches the task's own
dispatcher — never the router surface.
"""
from dodaios.clis.capability_provider import equivalent_grants # noqa: PLC0415
from dodaios.tasks.grants import grant_matches # noqa: PLC0415
if not allowed_tools:
return {}
grants = equivalent_grants(allowed_tools)
selected = {
name: tool for name, tool in self._tools.items()
if any(grant_matches(grant, name) for grant in grants)
}
for grant in grants:
if grant in selected or grant not in _TASK_ONLY_TOOLS:
continue
tool = self._load_task_only_tool(grant)
if tool is not None:
selected[grant] = tool
return selected
def _load_task_only_tool(self, name: str) -> Tool | None:
"""Instantiate (once) an entry-point tool that only scheduled tasks
may use. Returns ``None`` — and logs why — when it cannot be built,
so the task runs with the rest of its allowlist."""
cache: dict[str, Tool | None] = self.__dict__.setdefault("_task_only_tool_cache", {})
if name in cache:
return cache[name]
from dodaios.core.entry_points import entry_points # noqa: PLC0415
tool: Tool | None = None
for ep in entry_points(group="jarvis.tool"):
if ep.name != name:
continue
try:
tool = ep.load()()
except Exception as exc: # noqa: BLE001 — a broken tool must not kill the task
log.warning("task-only tool %r failed to load: %s", name, exc)
tool = None
break
else:
log.warning("task-only tool %r has no entry point", name)
cache[name] = tool
return tool
async def run_task(
self,
*,
prompt: str,
allowed_tools: tuple[str, ...] = (),
model_tier: str = "auto",
trace_id: UUID | None = None,
prefer_api: bool = False,
) -> str:
"""Keep the selected agent and billing account for the entire scheduled turn."""
from dodaios.core.model_selection import (
operation_model,
use_operation_model,
worker_selection,
)
selected = operation_model.get() or worker_selection(self._config)
with use_operation_model(selected):
return await self._run_task_with_selection(
prompt=prompt,
allowed_tools=allowed_tools,
model_tier=model_tier,
trace_id=trace_id,
prefer_api=prefer_api,
)
async def _run_task_with_selection(
self,
*,
prompt: str,
allowed_tools: tuple[str, ...] = (),
model_tier: str = "auto",
trace_id: UUID | None = None,
prefer_api: bool = False,
) -> str:
"""Run one isolated agentic turn for a scheduled task.
The turn sees ONLY the allowlisted tools and runs with an EMPTY
history, so it never pollutes the live voice session's ``_history``
or sticky model level (a scheduled task fires off the chat path).
Tool calls still flow through the shared ``ToolExecutor`` — so
read-only (monitor-tier) plugins pass unattended while ask-tier
actions still hit the approval gate (which, with no human present,
means they block until the unattended-approval wave wires Option B).
An explicit agent selection stays fixed, including subscription tasks.
Until migration selects an agent, the legacy credential-ready provider
chain remains available — see :meth:`_task_provider_chain`.
A credential / credit / rate-limit
error (401/402/403/429 — the same classes the chat path dead-lists
or cools down) moves the SAME turn on to the next candidate; any
other error propagates so the runner records it in ``last_error``.
The persistent active provider is never switched.
``prefer_api`` is accepted so a routine whose owner seat already
failed (a CLI without Jarvis tools) can retry here without a
TypeError. This path is already the API provider chain.
Returns the final assistant text.
"""
del prefer_api
intent = "deep" if model_tier == "deep" else "fast"
# A routine whose prompt asks for its result as an artifact is granted
# the builder for that turn — the same explicit-word rule the chat gate
# applies, so "every morning at 8, my briefing as an artifact" works
# without the person knowing the tool has a grant of its own.
from dodaios.brain.artifact_gate import wants_artifact # noqa: PLC0415
if wants_artifact(prompt) and _ARTIFACT_TOOL_NAME not in allowed_tools:
allowed_tools = (*allowed_tools, _ARTIFACT_TOOL_NAME)
tools = self._select_task_tools(allowed_tools)
from dodaios.core.model_selection import operation_model, worker_selection
from dodaios.core.task_agent import (
dual_seat_subscription,
run_selected,
subscription_seat_off_loop,
)
selected = operation_model.get() or worker_selection(self._config)
if (
selected is not None
and await subscription_seat_off_loop(selected.provider) is not None
):
subscription = dual_seat_subscription(selected.provider)
if subscription is not None:
# A dual slot only gets its seat while that login answers. The
# sighting is what later keeps an unattended turn off the
# slot's per-token row when the login stops answering.
from dodaios.brain.background_policy import note_connected
await asyncio.to_thread(note_connected, subscription)
return await run_selected(
selection=selected, prompt=prompt, tool_names=tuple(tools), trace_id=trace_id
)
# The per-turn context (date/time, wiki) rides on the user
# message in cache-optimized mode; without it a scheduled turn did not
# know what day it was (BUG-212 — the morning brief prompts say "the
# date is in your context" and it was not). Legacy mode carries it in
# the system prompt and this stays empty.
try:
turn_context = self._build_turn_context()
except Exception: # noqa: BLE001 — the context block is a nicety
log.debug("run_task: turn context skipped", exc_info=True)
turn_context = ""
attempts = self._task_provider_chain(intent)
from dodaios.core.protocols import current_started_by_user
if not current_started_by_user.get():
# Nobody started this turn (a schedule, a trigger, a background
# start): it may only bill what background work may bill — a
# subscription or a local model, never a per-token key on its own.
attempts = await self._unattended_task_chain(attempts, selected)
failures: list[str] = []
original: Exception | None = None
for index, (name, model) in enumerate(attempts):
try:
brain = self._get_brain(name, model)
await _settle_context_window(brain)
dispatcher = self._build_dispatcher(
brain, tools_override=tools,
# ``unattended``: the tool-use loop feeds an unknown tool
# name back and continues instead of ending the turn on
# the spoken "missing tool" phrase (BUG-212).
tool_context={"delivery": "written", "unattended": True},
)
agg = await dispatcher.dispatch(
prompt, history=[], intent_level=intent, trace_id=trace_id,
turn_context=_scheduled_turn_context(turn_context, tools),
)
# This chain leads with the Tool Model, so its outcomes are the
# Tool Model tab's evidence.
_health_ledger.record_success(name, _health_ledger.MODALITY_TOOL, model=model)
return agg.text or ""
except Exception as exc:
kind = _classify_provider_error(str(exc), default="call_fail")
if kind not in _TASK_FALLBACK_KINDS:
raise
_health_ledger.record_failure(
name, _health_ledger.MODALITY_TOOL, exc, model=model
)
original = original or exc
failures.append(f"{name}: {_short_provider_error(exc)}")
remaining = attempts[index + 1:]
if remaining:
log.warning(
"run_task: %s rejected the turn (%s) — trying %s next",
name, kind, remaining[0][0],
)
continue
log.warning(
"run_task: %s rejected the turn (%s) and no further "
"credential-ready tool-capable provider is usable", name, kind,
)
if len(failures) == 1 and original is not None:
raise original
raise RuntimeError("all brain providers failed: " + "; ".join(failures))
async def _unattended_task_chain(
self,
attempts: list[tuple[str, str | None]],
selected: Any,
) -> list[tuple[str, str | None]]:
"""Hold an unattended turn's chain to the background policy.
- An explicit agent selection is the person's own choice and stays —
except a dual slot (one that is a subscription seat while its login
is ready and a per-token row otherwise). Its login is not ready here
(a ready one ran on the subscription above), so the row it fell back
to was never picked and follows the same policy as the automatic
chain.
- The automatic chain keeps only subscriptions and local models once a
subscription is connected; an install without one keeps its chain,
so a single-key download still works.
Nothing usable raises :class:`BackgroundDeferred` instead of billing a
key; the runner records the skipped run.
"""
from dodaios.brain.background_policy import BackgroundDeferred, background_providers
from dodaios.core.task_agent import dual_seat_subscription
if selected is not None:
provider = str(getattr(selected, "provider", "") or "")
if dual_seat_subscription(provider) is None:
return attempts
policy = await asyncio.to_thread(
background_providers, [name for name, _model in attempts]
)
if not policy.subscription_mode:
return attempts
kept = [(name, model) for name, model in attempts if policy.permits(name)]
dropped = [name for name, _model in attempts if not policy.permits(name)]
if kept:
if dropped:
log.info(
"run_task (unattended): skipping per-token providers %s; "
"background work stays on %s",
dropped, [name for name, _model in kept],
)
return kept
log.warning(
"run_task (unattended): no subscription or local model can run this "
"turn (%s); deferring instead of billing %s",
policy.reason, dropped,
)
raise BackgroundDeferred(
"No subscription or local model is available for this unattended run; "
"a paid API key is not used without your approval."
)
def _task_provider_chain(self, intent: str) -> list[tuple[str, str | None]]:
"""The providers a scheduled turn tries, in order.
The Tool Model leads (the provider and key the user set for tool
calls — ``[brain.tool_model]``, the "API Keys" section), then every
other credential-ready, tool-capable provider of a different family
(:meth:`_hoist_tool_model` over the automatic chain). The chat's
active provider is just one candidate in that chain, never the
anchor: it used to be the only one, and with OpenRouter at 0 credits
every automation died at its action step while a ready Vertex Tool
Model sat unused (BUG-212). Without any ready candidate the active
provider is tried alone so the caller sees its real error.
``deep`` turns swap in the provider's deep model; ``fast``/``auto``
run on the Tool Model's own model — the cheapest correct default for
an unattended background turn. Capped so an unattended run cannot
walk a long chain for minutes.
"""
from dodaios.core.model_selection import operation_model, worker_selection
selected = operation_model.get() or worker_selection(self._config)
if selected is not None:
return [(selected.provider, selected.model)]
try:
ready = self._hoist_tool_model(self._tool_model_base_chain())
except Exception: # noqa: BLE001 — a broken probe must not kill the task
log.debug("run_task: tool-model chain unavailable", exc_info=True)
ready = []
# A scheduled routine runs unattended; it spends the realtime voice key
# only when no other ready provider exists (mandate 2026-09-29).
ready = self._keep_off_voice_key(ready)
chain: list[tuple[str, str | None]] = []
for name, model in ready[:_TASK_MAX_ATTEMPTS]:
if intent == "deep":
model = self._deep_model(name) or model
chain.append((name, model))
if chain:
return chain
name = self._active_name
model = (
(self._deep_model(name) or self._fast_model(name))
if intent == "deep" else self._fast_model(name)
)
return [(name, model)]
def snapshot(self) -> dict[str, Any]:
return {
"active_provider": self._active_name,
"force_level": self._force_level,
"history_size": len(self._history),
"tools_available": sorted(self._tools.keys()),
"providers_available": self.available_providers(),
"providers_failed": self.failed_providers(),
"fast_model": self._fast_model(self._active_name),
"deep_model": self._deep_model(self._active_name),
}
#: Entry-point tools a scheduled task may be granted although they are NOT
#: router tools (ADR-0011 keeps the router a pure dispatcher). Loaded lazily
#: by ``_select_task_tools`` for the task's own dispatcher only. Never a
#: spawn tool (AP-5/AP-14).
_TASK_ONLY_TOOLS: frozenset[str] = frozenset({"remember"})
#: Error classes that make a scheduled task move on to the next provider
#: family: the dead-list kinds (missing/bad key, 402 credits) plus a rate limit.
_TASK_FALLBACK_KINDS: frozenset[str] = frozenset(
{"missing_key", "account_blocked", "bad_key", "rate_limit"}
)
#: Most providers one scheduled turn walks before it gives up (BUG-212).
_TASK_MAX_ATTEMPTS: int = 4
def _scheduled_turn_context(turn_context: str, tools: dict[str, Any]) -> str:
"""The per-turn context of an unattended scheduled turn.
The cached system prompt advertises skills, CLIs and the full tool
surface of a live conversation; a scheduled turn sees only its allowlist
and has nobody to ask. Say so ON the turn (never in the cached prefix),
naming the tools that exist, so the model neither reaches for ``run-skill``
nor ends with a question (BUG-212: the briefing tried the morning-routine
skill the prompt had advertised and died on "missing tool").
"""
names = ", ".join(sorted(tools)) or "none"
block = (
"[Scheduled run — unattended] This turn runs on a schedule with no one "
f"listening. The only tools that exist in this turn are: {names}. Do not "
"call any other tool. If more than one listed tool can do the job, use "
"whichever is connected and returns data — do not stop because the first "
"name you tried is missing. Do not ask questions or request permission; "
"work with the tools listed and answer with the finished result."
)
return f"{turn_context}\n\n{block}" if turn_context else block
def _short_provider_error(exc: Exception) -> str:
"""One readable line for ``last_error`` / the fallback summary — the
exception class and the first 160 characters of its message."""
from dodaios.tasks.runner import readable_error
# The same code + human-message extraction the Runs tab uses, so a
# two-provider failure reads "openrouter: 402 — Insufficient credits…;
# gemini: 429 — You exceeded your current quota…" and not two dumped
# JSON bodies of which only the first survives the length cap.
return readable_error(exc)[:160]
def _is_rate_limit_exc(exc: Exception) -> bool:
"""Heuristic: 429 / rate_limit_error / status_code=429."""
msg = str(exc).lower()
if "429" in msg or "rate_limit" in msg or "rate-limit" in msg:
return True
if "rate limit" in msg or "too many requests" in msg:
return True
# Anthropic-SDK-RateLimitError
if type(exc).__name__ == "RateLimitError":
return True
status = getattr(exc, "status_code", None)
if status == 429:
return True
return False
# Leak-recovery fallback variants — see BrainManager._action_failed_phrase.
_ACTION_FAILED_PHRASES: dict[str, str] = i18n_catalog.table("brain.action_failed")
# DIRECT local-action acknowledgement — see BrainManager._localize_direct_ack.
# open_app hardcodes a German launch acknowledgement that the DIRECT fast path
# surfaces VERBATIM (no LLM re-render), so its leading verb is translated to the
# turn language here (live bug 2026-06-15: an English "open my explorer" turn was
# acknowledged in German even with the English pin set). Only the verb prefix is
# swapped — the suffix (the actual app / URL the tool reported) is preserved
# untouched. The "de" entry MUST match open_app's literal prefix in
# dodaios/plugins/tool/open_app.py; a mismatch degrades safely to passthrough
# (the historical German string), never a crash.
_OPEN_APP_ACK_PREFIX: dict[str, str] = {
"de": "Gestartet:", # i18n-allow: spoken German TTS acknowledgement
"en": "Opened:",
"es": "Abierto:",
"pt": "Aberto:",
}
def _looks_german(text: str) -> bool:
"""True when *text* is clearly German.
Delegates to the canonical ``detect_text_language`` (the single source of
truth the pipeline uses for the turn language) instead of a private
stop-word list. The old heuristic compared two tiny hint lists with
``score_de >= score_en``, so any text with no recognised stop-word in
either list scored 0-0 and was declared German. A clean English sentence
("Could you please tell me which city ... in Australia?") therefore tied to
German and was acknowledged / labelled German (live bug 2026-06-14). The
canonical detector returns ``"unknown"`` on ambiguity, so English, Spanish
and zero-signal text are now correctly NOT German.
"""
return detect_text_language(text) == "de"
def _is_missing_key_exc(msg: str) -> bool:
"""Heuristic: provider reports a missing API key or invalid auth state."""
m = msg.lower()
return any(k in m for k in (
"kein grok-api-key", "kein gemini-api-key", "kein openai-api-key",
"kein anthropic-api-key", "kein claude-credential",
"kein openrouter-api-key", "kein xai-api-key",
"api_key not set", "api key not found",
"api_key is not set", "api key is not set",
"anthropic_api_key is not set", "openai_api_key is not set",
"gemini_api_key is not set", "xai_api_key is not set",
"api-key gefunden", "missing api key", "no api key",
"not configured",
"api-key nicht gesetzt", "apikey missing",
"not logged in", "please run /login", "credentials.json",
# Vertex AI's Google Cloud project path signs with Application Default
# Credentials; a host without a gcloud login or service account raises
# google-auth's DefaultCredentialsError ("Your default credentials were
# not found"). Live 2026-08-22 18:40/18:42: classified as call_fail,
# the keyless Tool Model led the chain on EVERY delegated voice turn and
# paid 7-10 s for the same miss before a working provider was tried.
"default credentials were not found", "defaultcredentialserror",
"application default credentials were not found",
))
def _is_account_blocked_exc(msg: str) -> bool:
"""Heuristic: provider account has a terminal auth/quota/billing problem.
Examples observed live (all 2026-04-29):
- Anthropic 400: ``Your credit balance is too low to access the
Anthropic API. Please go to Plans & Billing.``
- xAI 404: ``The model grok-4.1-fast does not exist or your team
e6d8f57e-... does not have access to it.``
- OpenAI 403: ``The model `o1-pro` is not available on your tier.``
- Gemini 403: ``Quota exceeded for ...`` (unlike 429 — terminal).
- OpenRouter 403: ``Key limit exceeded (total limit).`` (a funded account
whose per-key spend cap is used up — live probe 2026-06-30, AP-22).
These providers are dead for the session (a simple retry won't help).
BrainManager pushes them immediately into _dead_providers and emits a
user-actionable setup message instead of "provider unreachable".
"""
m = msg.lower()
# Billing / budget / quota wording is the SHARED canonical list (one source of
# truth with the test-badge classifier) — covers credit-balance, spend/key/total
# limit, insufficient_quota, depleted prepayment, out-of-credits, etc.
if any(k in m for k in BILLING_LIMIT_MARKERS):
return True
# Access / tier / subscription gates — terminal too, but not strictly "money".
return any(k in m for k in _ACCOUNT_ACCESS_MARKERS)
# Terminal access/tier/subscription wordings (NOT money — kept beside the shared
# billing markers so both flavours of "account blocked" live in one classifier).
_ACCOUNT_ACCESS_MARKERS: tuple[str, ...] = (
"your team", # xAI "your team ... does not have access"
"team does not have access",
"team_does_not_have_access",
"not available on your tier", # OpenAI tier gate
"subscription required",
"upgrade plan",
"upgrade your plan",
"billing required",
"billing not active",
"account is suspended",
)
def _http_status_code(msg: str) -> int | None:
"""First 4xx/5xx HTTP status embedded in a provider error string, else None.
The SDK serializes the numeric code into ``str(exc)`` ("Error code: 403 - …"
for the OpenAI/Anthropic families; "403 … PERMISSION_DENIED" for Gemini), so a
code-first decision works uniformly without importing any provider SDK — the
same approach the test-badge classifier uses.
"""
match = re.search(r"\b([45]\d\d)\b", msg)
return int(match.group(1)) if match else None
# The chain loop dead-lists exactly these kinds: a terminal credential/account state
# (no key stored, blocked/over-budget account, invalid key) must cross to another
# available provider family for the rest of the session. A transient ``rate_limit``
# is deliberately NOT here — it takes the 30s cooldown path and keeps the provider.
_DEAD_LIST_KINDS: frozenset[str] = frozenset({"missing_key", "account_blocked", "bad_key"})
# User-friendly labels per provider — what the user needs to do.
def _is_invalid_model_exc(msg: str) -> bool:
"""Heuristic: provider reports an unknown/invalid model ID.
Do NOT use when the error is more likely an account problem
(see `_is_account_blocked_exc`) — otherwise an account 404 would
incorrectly land as "config bug, fix jarvis.toml".
"""
if _is_account_blocked_exc(msg):
return False
m = msg.lower()
return any(k in m for k in (
"model_not_found", "model not found", "model does not exist",
"unknown model", "invalid model", "invalid_model",
"not a valid model", "unsupported model",
# OpenAI's 404 for a Responses-API-only model called over
# Chat-Completions ("This is not a chat model and thus not supported
# in the v1/chat/completions endpoint"). Live 2026-08-06: spoken as
# "network or provider issue", which sent the user hunting API keys.
"not a chat model",
))
#: How long a brain may take to say which context window it really has before
#: the turn goes ahead with the figure it already published.
_CONTEXT_SETTLE_TIMEOUT_S = 3.0
async def _settle_context_window(brain: Any) -> None:
"""Let a brain that has to ASK for its window do so before tools are fitted.
A hosted model's window is a constant on its class. A local server's is
whatever that server was started or loaded with, so the two local brains
expose ``prepare_context_window`` and learn it with one or two cached
round-trips. Without this the first turn is budgeted for a figure the
server may not run, and is then refused whole instead of having its tool
surface trimmed. Gated on the capability, never a provider name (AP-21);
a brain without the method is untouched. Bounded and never raises: a slow
or failing probe costs nothing but the better budget.
"""
prepare = getattr(brain, "prepare_context_window", None)
if not callable(prepare):
return
try:
await asyncio.wait_for(prepare(), timeout=_CONTEXT_SETTLE_TIMEOUT_S)
except Exception as exc: # noqa: BLE001 — the turn runs on the published figure
log.debug(
"Context window of %s not settled before the turn: %s",
getattr(brain, "name", type(brain).__name__),
exc,
)
#: Tokens held back from a brain's context window before its tool surface is
#: sized: the user's turn text, the per-turn context block, the plugin usage
#: cards and the first answer or tool round. Only a local brain has a window
#: small enough for this to matter — see ``_fit_tools_to_context_window``.
_CONTEXT_FIT_RESERVE_TOKENS = 4096
#: A declared window at or below this is a small model: it is shown a short
#: list of tools even when a longer one would fit (see ``_shortlist_tools``).
_SMALL_WINDOW_TOKENS = 32_768
#: How many tools such a model is shown besides the ones a turn pins.
_SMALL_MODEL_DIRECT_TOOLS = 24
#: Room held back for the definitions ``find_tools`` adds during a turn whose
#: window is already full, and for the finder itself with its index of names.
_REVEAL_RESERVE_TOKENS = 2_000
_FINDER_TOKENS = 700
#: Chars per token for the size estimate. Deliberately low: tool schemas are
#: JSON, which tokenizes denser than prose, and over-estimating costs a few
#: tools on a 32k window while under-estimating costs the whole turn.
_CONTEXT_FIT_CHARS_PER_TOKEN = 3
def _approx_tokens(text: str) -> int:
"""A conservative token estimate for ``text`` — no tokenizer needed."""
return len(text) // _CONTEXT_FIT_CHARS_PER_TOKEN + 1
def _approx_history_tokens(history: Sequence[BrainMessage] | None) -> int:
"""What the message log costs on the wire, by the same estimate."""
if not history:
return 0
total = 0
for msg in history:
content = getattr(msg, "content", "")
if isinstance(content, str):
total += _approx_tokens(content)
continue
try:
total += _approx_tokens(json.dumps(content, ensure_ascii=False, default=str))
except (TypeError, ValueError):
total += _approx_tokens(str(content))
return total
def _tool_surface_tokens(name: str, tool: Any) -> int:
"""What ONE tool costs on the wire: name, description and schema."""
return tool_tokens(name, tool)
def _fit_tools_to_context_window(
tools: dict[str, Tool],
*,
context_window: int,
used_tokens: int,
keep: Iterable[str] = (),
max_tools: int = 0,
) -> tuple[dict[str, Tool], list[str]]:
"""The tools that fit ``context_window`` and ``max_tools``, and the rest.
Returns ``(tools that fit, names passed over)``. A window or a tool cap
of ``0`` or less means the brain declared none. ``used_tokens`` is
everything else the request carries (system prompt, history, reserve);
what remains is the budget for tools.
The choice is made by ``plan_surface``: the everyday tools first, then
the rest in registry order, connected-server tools last — they are
additions to the app's own surface, each one a full JSON schema (live
2026-08-27: 131 of 221 tools came from three MCP servers). A tool that
does not fit is passed over and the next one tried. Names in ``keep``
always fit. When even the prompt alone exceeds the window nothing but
``keep`` is left.
"""
if (context_window <= 0 and max_tools <= 0) or not tools:
return tools, []
plan = plan_surface(
tools,
keep=keep,
budget_tokens=max(context_window - used_tokens, 0) if context_window > 0 else None,
max_direct=max(max_tools, 0),
)
if not plan.deferred:
return tools, []
passed = set(plan.deferred)
return {name: tool for name, tool in tools.items() if name not in passed}, list(plan.deferred)
#: Wordings with which providers refuse a request larger than the model's
#: context window. Per request, never per credential — so NOT in
#: ``_DEAD_LIST_KINDS`` and never a cooldown.
_CONTEXT_OVERFLOW_MARKERS: tuple[str, ...] = (
"exceeds the available context size", # llama.cpp / Ollama (live 2026-08-27)
"exceed_context_size", # the same server's error type
"context_length_exceeded", # OpenAI-compatible error code
"maximum context length", # OpenAI / OpenRouter wording
"prompt is too long", # Anthropic
"exceeds the maximum number of tokens", # Gemini ("input token count …")
)
def _is_context_overflow_exc(msg: str) -> bool:
"""True when the provider refused the request for its SIZE.
Until 2026-08-27 this fell through to the generic ``call_fail`` and the
user read "I can't reach my provider — check the network" for a request
the server had answered perfectly well, with a 400 that named the cause.
"""
m = msg.lower()
return any(marker in m for marker in _CONTEXT_OVERFLOW_MARKERS)
def _classify_provider_error(msg: str, *, default: str) -> str:
"""Central classifier for provider error strings.
Order is intentional:
1. missing_key (auth/config — important for the dead-list).
2. account_blocked (credit/quota/tier/budget — also dead-list, by wording).
3. invalid_model (config bug — different action: fix jarvis.toml).
0. local_context (a local server runs the model with a window too small
for this request — our own guard's wording, so it is checked first;
per request, never a dead-list or cooldown).
3b. context_overflow (the request is larger than the model's window —
per request, so neither dead-list nor cooldown; the spoken cause
names the size, not the network).
4. code-first terminal: a bare 401 -> bad_key, a bare 402 -> account_blocked
(dead-list; catches a live invalid key / Payment-Required that carries the
numeric code but no known wording).
5. rate_limit (transient — handled by its own cooldown path).
6. default (init_fail or call_fail — caller decides).
bad_key / account_blocked / missing_key all dead-list (``_DEAD_LIST_KINDS``)
so a terminal provider stops leading the chain; only rate_limit takes the
transient cooldown.
missing_key is checked before rate_limit so an auth error that happens to
contain "limit" (e.g. "exceeded the rate limit for this resource") is not
incorrectly classified as a 429 cooldown.
"""
# A local server's window is named by our own guard with a fixed wording;
# checked first so no other heuristic can read the sentence differently.
if LOCAL_CONTEXT_MARKER in msg.lower():
return "local_context"
if _is_missing_key_exc(msg):
return "missing_key"
if _is_account_blocked_exc(msg):
return "account_blocked"
if _is_invalid_model_exc(msg):
return "invalid_model"
if _is_context_overflow_exc(msg):
return "context_overflow"
m = msg.lower()
# Code-first terminal fallback for a 401/402 that carries the numeric HTTP code
# but NONE of the known wordings (a bare live "Error code: 401 - invalid x-api-key"
# / "Error code: 402 - Payment Required"). A 401 = invalid/expired/wrong-account
# key, a 402 = Payment-Required — both terminal, so the provider is dead-listed and
# stops leading the chain every turn (live log 2026-06-30: claude-api 401 with no
# Anthropic account was retried on every turn). 403/429 stay word-driven on purpose:
# a transient Gemini 403 "CachedContent not found" must NOT dead-list (BUG-019).
code = _http_status_code(m)
if code == 401:
return "bad_key"
if code == 402:
return "account_blocked"
if any(s in m for s in ("429", "rate_limit", "rate-limit",
"rate limit", "too many requests")):
return "rate_limit"
return default
def _keyless_provider_is_rescued_by_oauth(provider_name: str) -> bool:
"""True when a keyless provider must NOT be dead-listed at the pre-boot key
check because it authenticates via an OAuth login ON DISK, not an API key.
The subscription-CLI brains (codex over the ChatGPT login at ``~/.codex/auth.json``)
carry no entry in ``PROVIDER_SECRET_CANDIDATES``, so a ChatGPT-only user would
otherwise see ``codex`` pushed into ``_dead_providers`` → empty chain → every
chat AND voice turn bricks with the provider-down apology. The OAuth login IS a
usable credential. Open-source single-provider mandate (AP-22). Any import/probe
failure is treated as "not rescued" (fail-safe → dead-list).
Vertex AI is the second shape: its Google Cloud project path signs with
Application Default Credentials (a ``gcloud`` login, a service account,
workload identity), so a fully configured install stores no key in any of
the family's slots. The declarative ``KEYLESS_CREDENTIAL_PROBES`` table in
``app_control`` is the ONE place that names the probe, and it is the same
answer every provider card and every switch already gives — so this check
can never dead-list a family the UI shows as configured. Live 2026-08-17:
the check knew only key slots, pushed ``vertex`` into ``_dead_providers``
at every boot, and the router silently ran on the AI Studio account (whose
prepaid credit was empty) while the user's Vertex project sat idle.
"""
if provider_name == "codex":
try:
from dodaios.plugins.brain.codex import _codex_oauth_connected
return bool(_codex_oauth_connected())
except Exception: # noqa: BLE001
return False
try:
from dodaios.brain.app_control import _keyless_credential_present
return bool(_keyless_credential_present(provider_name))
except Exception as exc: # noqa: BLE001 — a failed probe is not a credential
log.debug("Keyless-credential rescue probe failed for %s: %s", provider_name, exc)
return False
_PROVIDER_SETUP_HINTS: dict[str, str] = {
"gemini": "GEMINI_API_KEY setzen (Key via https://aistudio.google.com/apikey)",
"claude-api": "ANTHROPIC_API_KEY setzen",
"openai": "OPENAI_API_KEY setzen",
"openrouter": "OPENROUTER_API_KEY setzen",
"grok": "Set XAI_API_KEY (key from console.x.ai)",
"nvidia": "Set NVIDIA_API_KEY (nvapi- key from build.nvidia.com)",
"ollama-local": "Ollama-Server starten (localhost:11434)",
"ollama-cloud": "Ollama-Cloud-Token setzen",
}
def _format_provider_chain_error(
errors: list[tuple[str, str, str, str]],
) -> str:
"""Builds a meaningful user message from the per-provider error list.
Prioritises root causes: when the **primary** provider has no key,
THAT is the main message. Rate limits are listed as secondary.
"""
if not errors:
return ("Keine Brain-Provider konfiguriert. "
"Setze mindestens GEMINI_API_KEY oder ANTHROPIC_API_KEY.")
missing_keys: list[str] = []
invalid_keys: list[str] = []
account_blocked: list[str] = []
vision_unsupported: list[str] = []
invalid_models: list[str] = []
context_overflow: list[str] = []
local_context: list[str] = []
rate_limited: list[str] = []
empty_responses: list[str] = []
other_fails: list[str] = []
for prov_name, _model, kind, _detail in errors:
if kind == "missing_key":
missing_keys.append(prov_name)
elif kind == "bad_key":
invalid_keys.append(prov_name)
elif kind == "account_blocked":
account_blocked.append(prov_name)
elif kind == "vision_unsupported":
vision_unsupported.append(prov_name)
elif kind == "invalid_model":
invalid_models.append(prov_name)
elif kind == "context_overflow":
context_overflow.append(prov_name)
elif kind == "local_context":
# The guard's own sentence carries the sizes and the setting.
local_context.append(_detail or prov_name)
elif kind in ("rate_limit", "skipped_cooldown"):
rate_limited.append(prov_name)
elif kind == "empty_response":
empty_responses.append(prov_name)
else:
other_fails.append(prov_name)
# Deduplicate while preserving order (first-listed priority).
def _uniq(xs: list[str]) -> list[str]:
seen: set[str] = set()
out: list[str] = []
for x in xs:
if x not in seen:
out.append(x)
seen.add(x)
return out
missing_keys = _uniq(missing_keys)
invalid_keys = _uniq(invalid_keys)
account_blocked = _uniq(account_blocked)
vision_unsupported = _uniq(vision_unsupported)
invalid_models = _uniq(invalid_models)
context_overflow = _uniq(context_overflow)
rate_limited = _uniq(rate_limited)
empty_responses = _uniq(empty_responses)
other_fails = _uniq(other_fails)
parts: list[str] = []
# 1. Setup hint for the most important missing keys (max 2).
# Priority: Sidebar → API Keys is the easiest setup path for non-coders.
# Specific ENV/CLI hints for power users come after.
if missing_keys:
hints = [
_PROVIDER_SETUP_HINTS.get(p, f"{p}: Setup pruefen")
for p in missing_keys[:2]
]
parts.append(
"Kein Brain-Key gefunden. Sidebar -> API-Keys oeffnen und "
f"einen Key setzen ({' oder '.join(hints)})."
)
# 1b. Invalid/expired key (a 401 — the stored key is rejected, not absent).
if invalid_keys:
parts.append(
f"Key abgelehnt bei {', '.join(invalid_keys)} (ungueltig oder abgelaufen). "
"Sidebar -> API-Keys: Key ersetzen."
)
# 2. Account block (credit/quota/tier) — user must take action
if account_blocked:
parts.append(
f"Account-Problem bei {', '.join(account_blocked)}: "
"Credit aufladen, Plan upgraden oder Modell-Tier freischalten. "
"Bei Anthropic: console.anthropic.com/settings/billing. "
"Bei xAI: console.x.ai/team/billing."
)
if vision_unsupported:
parts.append(
f"Kein Bildverstehen bei {', '.join(vision_unsupported)} — " # i18n-allow
"der Key ist da, aber das Modell sieht keine Bilder. " # i18n-allow
"Unter API-Keys einen Anbieter mit Bildverarbeitung aktivieren." # i18n-allow
)
if invalid_models:
parts.append(
f"Ungueltige Model-ID bei {', '.join(invalid_models)}. "
"jarvis.toml und TIER_DEFAULTS_BY_PROVIDER pruefen."
)
# 1c. The request was larger than the model's context window — a size
# problem of THIS request, not a network one (live 2026-08-27: a 32k
# local model, 221 tools, "check the network").
if context_overflow:
parts.append(
f"Anfrage zu gross fuer das Kontextfenster von {', '.join(context_overflow)}. "
"Modell mit groesserem Kontext waehlen, verbundene MCP-Server "
"reduzieren oder einen neuen Chat starten."
)
if local_context:
parts.append(" ".join(_uniq(local_context)))
# 2. Rate limits are listed as supplementary info
if rate_limited:
prefix = "Ausserdem rate" if parts else "Rate"
parts.append(
f"{prefix}-limited: {', '.join(rate_limited)}. "
"Einen Moment abwarten oder auf anderen Provider wechseln."
)
# 3. Empty responses (safety block) — separate user-actionable case
if empty_responses and not missing_keys and not invalid_models:
parts.append(
f"Provider {', '.join(empty_responses)} hat leer geantwortet "
"(vermutlich Safety-Filter). Anders formulieren oder anderen "
"Provider per UI aktivieren."
)
# 4. Other failures only mentioned when there is no clear root cause
if (not missing_keys and not invalid_models and not context_overflow
and not local_context
and not rate_limited and not empty_responses and other_fails):
parts.append(
f"Provider {', '.join(other_fails)} unerreichbar. "
"Netzwerk pruefen."
)
return " ".join(parts)