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
"""FastAPI + WebSocket server for the desktop UI (Phase 1a).
Responsibilities:
- REST endpoints for health, config read-only, plugin discovery, debug.
- WebSocket `/ws` with welcome frame, bus forwarding, input validation.
- Optional static mount for the React build under `dist/` (production mode).
Explicitly NOT here:
- Channel-adapter logic (in `dodaios/channels/web.py`).
- The React build itself (Agent 5).
- Single-instance focus logic (only a placeholder endpoint).
"""
from __future__ import annotations
import asyncio
import math
import mimetypes
import os
import time
from collections.abc import Callable
from pathlib import Path, PurePosixPath
from typing import TYPE_CHECKING, Any
from uuid import uuid4
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, Response
from fastapi.routing import APIRoute
from fastapi.staticfiles import StaticFiles
from loguru import logger
from pydantic import BaseModel, ValidationError
from starlette.routing import Match
from starlette.types import Scope
from dodaios import __version__
from dodaios.core.bus import EventBus, get_default_bus
from dodaios.core.config import JarvisConfig, resolve_config_path
from dodaios.core.events import (
AnnouncementRequested,
ErrorOccurred,
Event,
MessageSent,
SystemStarted,
TerminalClosed,
TerminalCommandExecuted,
TerminalOutput,
TerminalSpawned,
VoiceBootStatus,
)
from dodaios.core.registry import list_all_plugins
from dodaios.terminal import PtyManager, discover_shells, get_shell
from .fast_bootstrap import ASSET_SUFFIXES
from .schema import (
WSAudioLevel,
WSCommand,
WSMessageIn,
WSWelcome,
event_to_ws_envelope,
)
from .spa_build import (
build_is_complete,
holding_page_html,
missing_build_watch,
recover_conflicted_index,
)
from .surface_security import SurfaceSecurity, set_browser_login_required
if TYPE_CHECKING:
import uvicorn
WEB_DIR = Path(__file__).resolve().parent
DIST_DIR = WEB_DIR / "dist"
INDEX_FILE = DIST_DIR / "index.html"
ASSETS_DIR = DIST_DIR / "assets"
# The Verse ships pre-rendered plates and 3D models; Windows' MIME registry
# does not know these types, and a wrong type makes the WebView refuse them.
for _suffix, _media_type in (
(".avif", "image/avif"),
(".glb", "model/gltf-binary"),
(".hdr", "image/vnd.radiance"),
):
mimetypes.add_type(_media_type, _suffix)
# Max time a single WS push to one browser client may take. A healthy
# localhost ``send_json`` is sub-50 ms; exceeding this means the client is
# stalled or half-open (TCP not yet torn down, send buffer full). Because the
# WS forwarder is a bus *wildcard* subscriber, an unbounded send would freeze
# the whole event bus and stall the voice / Computer-Use dispatch paths
# (BUG-CU-STALL, AP-18). On timeout we drop the client so the bus is not
# re-throttled every event; the browser reconnects on its own.
_WS_SEND_TIMEOUT_S = 3.0
# Level samples are disposable animation data. If the socket is busy, discard
# a sample instead of letting a visual update queue behind functional frames.
_WS_LEVEL_SEND_TIMEOUT_S = 0.25
# Society joins its watchers (2 s), then browser owners (17 s). Leave another
# 3 s for stores and containment cleanup before reporting an incomplete stop.
_SOCIETY_SHUTDOWN_TIMEOUT_S = 22.0
# How long the realtime transport warm is held back after boot. Warming can
# spawn a provider's app-server and verify a live account, so it must not
# compete with the wake-model load and the brain/MCP build for CPU and disk
# (AP-26). A few seconds still lands it long before a realistic first wake
# word, which is the entire point of warming.
REALTIME_WARM_BOOT_DELAY_S = 5.0
# Shared with the desktop shell's warm worker (``dodaios/ui/desktop_app.py``).
# Both surfaces schedule onto ONE event loop in a desktop boot, so the task
# name is what keeps that boot from warming the same transports twice.
REALTIME_WARM_TASK_NAME = "realtime-transport-warm"
_REGISTRY_BOOTSTRAP_STOP_TIMEOUT_S = 5.0
def _is_backend_path(path: str) -> bool:
"""Paths the SPA catch-all must never claim: the API and the sockets."""
return path == "/api" or path.startswith(("/api/", "/ws"))
def _follow_main_saved() -> bool:
"""``[agentic_ide] follow_main`` as saved now (the in-memory config is read at boot)."""
try:
from dodaios.core.config import load_config
return bool(getattr(load_config().agentic_ide, "follow_main", False))
except Exception as exc: # noqa: BLE001 -- an unreadable file means "not opted in"
logger.debug("Follow main: the configuration could not be read: {}", exc)
return False
class _SpaFallbackRoute(APIRoute):
"""The SPA catch-all, invisible to API and socket paths.
A plain ``GET /{full_path:path}`` partially matches EVERY path, so the
router answered an unknown ``POST /api/...`` with 405 and ``Allow: GET`` —
pointing a client at a GET that does not exist — and a bare ``GET /api``
with the SPA's HTML. Declining backend paths lets the router answer
honestly: 404 for a route that does not exist, 405 only for a real route
asked with the wrong method.
"""
def matches(self, scope: Scope) -> tuple[Match, Scope]:
if scope.get("type") == "http" and _is_backend_path(scope.get("path", "")):
return Match.NONE, {}
return super().matches(scope)
class MemoryFactBody(BaseModel):
"""Body of ``POST``/``DELETE /api/memory/facts``.
Typed so a non-string ``fact`` is a 422 at the boundary instead of an
``AttributeError`` (500) inside the handler.
"""
fact: str
category: str = "general"
def _is_backend_path(path: str) -> bool:
"""Paths the SPA catch-all must never claim: the API and the sockets."""
return path == "/api" or path.startswith(("/api/", "/ws"))
class _SpaFallbackRoute(APIRoute):
"""The SPA catch-all, invisible to API and socket paths.
A plain ``GET /{full_path:path}`` partially matches EVERY path, so the
router answered an unknown ``POST /api/...`` with 405 and ``Allow: GET`` —
pointing a client at a GET that does not exist — and a bare ``GET /api``
with the SPA's HTML. Declining backend paths lets the router answer
honestly: 404 for a route that does not exist, 405 only for a real route
asked with the wrong method.
"""
def matches(self, scope: Scope) -> tuple[Match, Scope]:
if scope.get("type") == "http" and _is_backend_path(scope.get("path", "")):
return Match.NONE, {}
return super().matches(scope)
class WebServer:
"""In-process uvicorn + FastAPI, run by the orchestrator loop."""
def __init__(
self, cfg: JarvisConfig, bus: EventBus | None = None, *,
defer_feature_routes: bool = False,
) -> None:
self._defer_feature_routes = defer_feature_routes
self.cfg = cfg
# Deferred boot work belongs to this server instance. Explicit handles
# let stop() drain it before pytest/asyncio tears the event loop down.
self._anyio_pool_warm_task: asyncio.Task[None] | None = None
self._deferred_reload_task: asyncio.Task[None] | None = None
self.bus = bus if bus is not None else get_default_bus()
self._clients: dict[str, WebSocket] = {}
self._client_send_locks: dict[str, asyncio.Lock] = {}
self._mic_level_sessions: set[str] = set()
self._mic_level_unsub: Callable[[], None] | None = None
self._mic_level_latest = 0.0
# The assistant's own voice, from dodaios.audio.level_tap. It rides the
# SAME frame and the same coalescing as the microphone: two directions
# of one conversation, one ~30 Hz channel, so adding it costs no extra
# WebSocket traffic.
self._tts_level_latest = 0.0
self._tts_level_unsub: Callable[[], None] | None = None
self._mic_level_revision = 0
self._mic_level_task: asyncio.Task[None] | None = None
self._server: uvicorn.Server | None = None
self._serve_task: asyncio.Task[None] | None = None
# PTY manager for the desktop-app terminal view. Sessions are
# global per server instance — they survive WS reconnects, but
# not a server shutdown (see stop()).
self._pty = PtyManager()
# Per-terminal line buffer for audit events.
self._pty_input_buffers: dict[str, str] = {}
self._pty_shell_ids: dict[str, str] = {}
# Skill registry: watched on user_skills_dir() after first-run bootstrap.
# The watcher starts in ``start()`` once the event loop is running.
self._skill_registry: Any | None = None
# Doc registry: watched on default_doc_roots(); its derived FTS5 index
# is process-local. Watcher also starts in ``start()``.
self._doc_registry: Any | None = None
self._cli_registry: Any | None = None
self._plugin_registry: Any | None = None
self._cli_bootstrap_task: asyncio.Task[None] | None = None
self._plugin_bootstrap_task: asyncio.Task[None] | None = None
# Marketplace OAuth refresh belongs to the shared WebServer lifecycle,
# not to one launcher. The actual scheduler is created with call_soon
# at the end of start(), after the serving/readiness path has returned;
# the pending handle also makes repeated start() calls idempotent.
self._refresh_scheduler: Any | None = None
self._refresh_scheduler_start_handle: asyncio.Handle | None = None
# Local models self-check (badge only): started next to the refresh
# scheduler, i.e. after the serving path returned — never on boot.
self._local_models_health_monitor: Any | None = None
# Local server autostart: one task a few seconds after the serving
# path returned; starts nothing unless local models are in use.
self._local_models_autostart_task: asyncio.Task[None] | None = None
self._refresh_registry_tasks: set[asyncio.Task[Any]] = set()
self._refresh_scheduler_stopping = False
# Realtime transport pre-warm — scheduled at the end of start() so the
# headless/browser-only boot path gets the same warm the desktop shell
# runs. Cancelled in stop().
self._realtime_warm_task: asyncio.Task[None] | None = None
# Board stack is populated in _setup_board() (in the _build_app path).
self._board_aggregator: Any | None = None
self._board_aggregator_task: asyncio.Task[None] | None = None
self._board_evaluator: Any | None = None
self._bio_scheduler: Any | None = None
self._bio_generator: Any | None = None
# Voice-session recorder — runs alongside the EventBus, populated in
# _init_session_stack(). None while the recorder is disabled.
self._session_recorder: Any | None = None
# Phase-5 task stack (tasks view). _init_task_stack() populates
# all three; without wiring /api/tasks returns 503 (see BUG-007).
self._task_store: Any | None = None
self._task_scheduler: Any | None = None
self._task_runner: Any | None = None
self._task_scheduler_task: asyncio.Task[None] | None = None
self._task_cancel_token: Any | None = None
# Phase B5 wiki write-wiring handle — shutdown() called in stop().
self._wiki_integration_handle: Any | None = None
# Phase B3 wiki live-reload watchdog handle — shutdown() called in stop().
self._wiki_watcher: Any | None = None
self._channel_chat_bridge: Any | None = None
# Pre-Thinking-Ack (Flash-Brain) bridge: translate AnnouncementRequested
# events with kind="preamble" into MessageSent(role="preamble") so the
# chat view in the desktop UI can render them as muted pre-ack bubbles.
# Other kinds (completion / info / None — used by MissionAnnouncer and
# other producers) flow through the existing wildcard WS forward
# unchanged. See docs/superpowers/specs/2026-05-11-pre-thinking-ack-
# flash-brain-design.md §4.
self.bus.subscribe(AnnouncementRequested, self._forward_preamble_to_chat)
# An owed result reaches a live call through the speech pipeline; an
# install without one (headless, browser voice only) hands it over here.
from dodaios.live.announcements import deliver_to_live_call
self.bus.subscribe(AnnouncementRequested, deliver_to_live_call)
from dodaios.core import runtime_refs
from dodaios.missions.tool_approvals import (
MissionToolApprovalCoordinator,
MissionToolAutoApprover,
)
self._mission_tool_approvals = MissionToolApprovalCoordinator(self.bus)
# Mission-scoped tool pre-authorization (ADR-0031): answers the
# approval gate for tools a mission's broker grant pre-authorizes
# ([phase6.safety].auto_approve_tool_families), full audit chain
# preserved. Registered in runtime_refs because the WorkerToolBroker
# lives below the web layer (same pattern as the supervisor gateway).
self._mission_tool_auto_approver = MissionToolAutoApprover(self.bus)
runtime_refs.set_mission_tool_auto_approver(self._mission_tool_auto_approver)
self.app: FastAPI = self._build_app()
self.app.state.refresh_scheduler = None
from dodaios.ui.deferred_setup import DeferredSetup
self._feature_setup = DeferredSetup(
lambda: self._finish_app_setup(self.app), ready=not defer_feature_routes
)
if not defer_feature_routes:
self._publish_app()
async def _forward_delegation_to_chat(self, event: Any) -> None:
"""Persist a result in its originating chat without starting another model turn."""
service = getattr(self.app.state, "agent_chat", None)
if service is None:
return
session = service.store.get_session(event.session_id)
if session is None or session.surface != "jarvis":
return
await service.post_notice(event.session_id, {
"kind": "coding_result", "agent_name": event.agent_name,
"assignment_id": event.request_id, "status": event.status,
"text": event.text, "report": event.report,
})
async def _forward_preamble_to_chat(self, event: AnnouncementRequested) -> None:
"""Bridge AnnouncementRequested(kind="preamble") → MessageSent.
The chat WebSocket's wildcard forward already ships every bus event
to the frontend, but the chat history view only renders MessageSent
envelopes. Flash-Brain pre-ack output is published as
AnnouncementRequested(kind="preamble") so the TTS pipeline picks it
up; this handler additionally publishes a MessageSent(role="preamble",
text=event.text) so the chat history shows the same line as a muted
pre-ack bubble.
Other kinds (completion / info / None) are intentionally untouched —
MissionAnnouncer and other producers rely on the existing flow.
"""
if event.kind != "preamble":
return
text = (event.text or "").strip()
if not text:
return
await self.bus.publish(
MessageSent(
thread_id="preamble",
role="preamble",
text=text,
source_layer="ui.web.preamble_bridge",
)
)
# ------------------------------------------------------------------
# App-Factory
# ------------------------------------------------------------------
def _build_app(self) -> FastAPI:
app = FastAPI(
title="Dodaios — Admin/UI API",
version=__version__,
# Swagger UI on ``/api/_swagger`` — the semantic ``/api/docs``
# path belongs to the doc-browser router (see docs_routes.py).
docs_url="/api/_swagger",
openapi_url="/api/openapi.json",
)
# CORS only for the Vite dev server — production serves the frontend
# from dist/ and needs no cross-origin requests.
vite_dev_url = self.cfg.ui.vite_dev_url if self.cfg.ui.dev_mode else None
if vite_dev_url:
app.add_middleware(
CORSMiddleware,
allow_origins=[vite_dev_url],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
twilio_cfg = getattr(getattr(self.cfg, "integrations", None), "twilio", None)
public_urls = tuple(
value
for value in (
getattr(twilio_cfg, "public_base_url", ""),
getattr(
getattr(self.cfg, "marketplace", None),
"public_callback_base_url",
"",
),
)
if value
)
# The security boundary must wrap every router and both HTTP and WS.
# It is added after CORS so Starlette places it outside the CORS layer:
# hostile Host/Origin values never reach route code or preflight logic.
# Seed the browser-lock flag from the loaded config so the boundary's
# lazy raw-TOML read never disagrees with what the app actually loaded
# (JARVIS_CONFIG overrides, in-memory test configs, wizard defaults).
_browser_lock_on = bool(
getattr(getattr(self.cfg, "ui", None), "require_browser_login", False)
)
set_browser_login_required(_browser_lock_on)
if not _browser_lock_on:
logger.info(
"Browser lock is off (the default): loopback requests are served "
"without a credential. Anything relaying this port to a network "
"re-exposes the instance — turn on 'Ask for the key in the "
"browser' before forwarding it."
)
app.add_middleware(
SurfaceSecurity,
vite_dev_url=vite_dev_url,
public_urls=public_urls,
)
self._register_rest_routes(app)
self._register_ws_route(app)
# Registries constructed here defer their blocking disk scan
# (``reload_sync`` — globbing + FTS indexing, ~hundreds of ms) off the
# boot critical path. The scans run after uvicorn is listening (see
# ``start()``); nothing at BOOT_READY needs the skill/doc lists (the
# brain builds its own skill context; the Skills view tolerates an empty
# registry, while Docs can trigger its own shared on-demand load). Each
# entry is (label, registry).
self._pending_reloads: list[tuple[str, Any]] = []
# Skill-registry setup: bootstrap (copy builtin skills) + create the
# registry. reload_sync() is deferred (see _pending_reloads). The
# watchdog watcher is only activated in ``start()``.
self._setup_skill_registry(app)
# Doc registry: curated reader-guide discovery under ``docs/product/``,
# FTS5 index. The watchdog is likewise only activated in ``start()``.
self._setup_doc_registry(app)
# CLI-tool registry — holds the catalog + prober + auth + usage log in
# the same state object shared by the REST routes and the brain launcher.
self._setup_cli_registry(app)
# Plugin-Tool-Registry — wired marketplace plugins as live brain tools.
self._setup_plugin_registry(app)
# Make the config available to the routes (e.g. admin-pass check in
# skills_routes). Other routes will use it too going forward.
app.state.config = self.cfg
app.state.bus = self.bus
# Voice boot-readiness mirror. WS events are one-shot, so a tab that
# connects after warm-up finished would never see VoiceBootStatus.
# Persist the latest state on this (long-lived) server instance for
# GET /api/voice/status to read — deliberately NOT on app.state, whose
# ASGI lifecycle could outrace the bus subscriber on shutdown.
#
# When the local voice stack is disabled (JARVIS_VOICE=0 — headless,
# VPS, browser-mic-only), there is nothing to warm up and the pipeline
# never emits VoiceBootStatus, so seed ready=True. Otherwise the
# frontend's "starting up" banner would hang forever even though the
# user can already type (and use browser voice). A real voice pipeline
# starts at ready=False (warmup_start) and flips True via the subscriber
# below, so this seed only ever sticks when voice is genuinely off.
_voice_disabled = os.environ.get("JARVIS_VOICE", "").strip().lower() in (
"0",
"off",
"false",
)
self._voice_ready = _voice_disabled
# Synchronous routes run on anyio's thread pool, which grows ON the
# loop and shrinks after ten idle seconds — a start that blocked the
# loop for 15 s on 2026-08-27 (BUG-189). Workers stay resident from
# here on; a handful is brought up once voice reports ready, below.
from dodaios.core.loop_executor import keep_anyio_workers_alive
keep_anyio_workers_alive()
self._anyio_pool_warmed = False
async def _track_voice_ready(event: VoiceBootStatus) -> None:
# A bus subscriber must never raise (AP-18); setting a plain
# instance bool cannot fail, and the warm-up below only schedules.
self._voice_ready = event.voice_usable
if event.ready:
self._schedule_anyio_pool_warm()
self.bus.subscribe(VoiceBootStatus, _track_voice_ready)
if not self._defer_feature_routes:
self._finish_app_setup(app)
return app
def _finish_app_setup(self, app: FastAPI) -> None:
"""Install optional surfaces before any consumer receives this app.
Desktop defers this work behind local voice warmup. Headless and other
callers retain eager construction. The shared bus, skill registry and
voice-status subscriber already exist before this method runs.
"""
# Sub-agent registry (dashboard feature) — subscribes to the bus immediately.
try:
from dodaios.agents import JarvisAgentRegistry
sub_agent_registry = JarvisAgentRegistry(bus=self.bus)
sub_agent_registry.attach()
app.state.sub_agent_registry = sub_agent_registry
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("JarvisAgentRegistry setup failed")
app.state.sub_agent_registry = None
# Wire in the MCP, tool, provider, profile, task, skills, CLI, and
# sub-agents routes — lazy import avoids cycles.
from dodaios.runs.routes import router as runs_router
from dodaios.runs.runs_ws import router as runs_ws_router
from .agent_accounts_routes import router as agent_accounts_router
from .agent_chat_routes import router as agent_chat_router
from .attention_routes import router as attention_router
from .agent_mcp_routes import router as agent_mcp_router
from .agent_runtime_routes import router as agent_runtime_router
from .agentic_ide_git_routes import router as agentic_ide_git_router
from .agentic_ide_routes import router as agentic_ide_router
from .agentic_ide_scm_routes import router as agentic_ide_scm_router
from .antigravity_routes import router as antigravity_router
from .app_actions_routes import router as app_actions_router
from .appshot_routes import router as appshot_router
from .board_routes import (
board_router as board_meta_router,
)
from .board_routes import (
router as board_router,
)
from .browser_profile_routes import router as browser_profile_router
from .chat_library_routes import router as chat_library_router
from .chats_routes import router as chats_router
from .claude_routes import router as claude_router
from .cli_routes import router as cli_router
from .clipboard_routes import router as clipboard_router
from .commands_routes import router as commands_router
from .computer_use_routes import router as computer_use_router
from .computers_routes import router as computers_router
from .contacts_routes import router as contacts_router
from .control_routes import router as control_router
from .costs_routes import router as costs_router
from .custom_api_routes import router as custom_api_router
from .deck_routes import router as deck_router
from .desktop_routes import router as desktop_router
from .diagnostics_routes import router as diagnostics_router
from .dictation_routes import router as dictation_router
from .dictionary_routes import router as dictionary_router
from .docs_routes import router as docs_router
from .dodaiosx_routes import router as jarvisx_router
from .downloads_routes import router as downloads_router
from .drop_routes import router as drop_router
from .federation_proxy_routes import router as federation_proxy_router
from .feedback_routes import router as feedback_router
from .friends_routes import router as friends_router
from .frontier_routes import router as frontier_router
from .grok_build_routes import router as grok_build_router
from .ide_browser_routes import router as ide_browser_router
from .ide_skills_routes import router as ide_skills_router
from .live_routes import router as live_router
from .local_models_assistant_routes import (
router as local_models_assistant_router,
)
from .local_models_routes import router as local_models_router
from .local_voice_routes import router as local_voice_router
from .marketplace_publish_routes import router as marketplace_publish_router
from .marketplace_routes import router as marketplace_router
from .mcp_routes import router as mcp_router
from .memory_vault_routes import router as memory_vault_router
from .personal_memory_routes import router as personal_memory_router
from .mission_billing_routes import router as mission_billing_router
from .missions_auth import router as missions_auth_router
from .missions_pty_routes import router as missions_pty_router
from .missions_routes import router as missions_router
from .missions_ws_routes import (
ConnectionManager as _MissionsConnMgr,
)
from .missions_ws_routes import (
router as missions_ws_router,
)
from .onboarding_routes import router as onboarding_router
from .outputs_routes import router as outputs_router
from .permissions_routes import router as permissions_router
from .games_routes import router as games_router
from .pets_routes import router as pets_router
from .preview_routes import router as preview_router
from .profile_routes import router as profile_router
from .provider_routes import router as provider_router
from .review_routes import router as review_router
from .routine_hooks_routes import router as routine_hooks_router
from .runtime_gateway_routes import router as runtime_gateway_router
from .screen_context_routes import router as screen_context_router
from .self_build_routes import router as self_build_router
from .self_mod_routes import router as self_mod_router
from .server_pairing_routes import router as server_pairing_router
from .sessions_routes import router as sessions_router
from .settings_routes import router as settings_router
from .setup_report_routes import router as setup_report_router
from .setup_routes import router as setup_router
from .skills_routes import router as skills_router
from .socials_routes import router as socials_router
from .society_browser_routes import router as society_browser_router
from .society_figure_routes import router as society_figure_router
from .society_routes import router as society_router
from .soul_routes import router as soul_router
from .starter_plan_routes import router as starter_plan_router
from .sub_agents_routes import router as sub_agents_router
from .tasks_routes import router as tasks_router
from .team_thread_routes import router as team_thread_router
from .telephony_routes import router as telephony_router
from .tool_model_routes import router as tool_model_router
from .tools_routes import router as tools_router
from .update_routes import router as update_router
from .voice_call_routes import router as voice_call_router
from .wallpaper_routes import router as wallpaper_router
from .wiki_routes import router as wiki_router
from .wiki_ws import router as wiki_ws_router
from .workflows_routes import router as workflows_router
from .workspace_clis_routes import router as workspace_clis_router
from .workspace_routes import router as workspace_router
# Conductor is an external package in the same monorepo. Import
# defensively — anyone who checks out the repo without conductor would
# otherwise get an ImportError here at server boot.
try:
from conductor.api import router as conductor_router
except ImportError as exc:
logger.warning("Conductor module not available: {} — Conductor view stays empty", exc)
conductor_router = None
app.include_router(mcp_router)
# Connect-flow for the Agent MCP surface: what it offers, which
# clients this box has, and writing the entry into their config.
app.include_router(agent_mcp_router)
app.include_router(tools_router)
app.include_router(tool_model_router)
# Jarvis' OWN tools, offered outwards over MCP so an agent-chat session
# drives Jarvis instead of a bare workspace. Key-gated like the rest of
# the Control API; mounted raw because the transport streams.
from dodaios.ui.web.mcp_server_routes import build_mcp_asgi_app
# ONE mount, two surfaces, dispatched inside on the rest of the path:
# "" is Jarvis' own tools, "/agents" is the agent ecosystem. A second
# Starlette mount on the longer path would never match a request
# without a trailing slash — see mcp_server_routes._surface_for.
app.mount("/api/control/mcp", build_mcp_asgi_app())
# Event-loop diagnostics (read-only) — names the owner of an AP-20
# cancellation busy-loop from inside the loop; see diagnostics_routes.
app.include_router(diagnostics_router)
app.include_router(provider_router)
# Local voice card (setup, status, self-test) — ADR-0037.
app.include_router(local_voice_router)
app.include_router(live_router)
from dodaios.agent_chat.tasks import run_subscription_task
from dodaios.core.task_agent import register_runner
register_runner(run_subscription_task)
# Local models section: inventory / unload / delete behind the
# pull-capable card (same capability gate as the pull routes).
app.include_router(local_models_router)
# The section's setup assistant — same capability gate, its own chat
# surface on the Agents tier.
app.include_router(local_models_assistant_router)
app.include_router(antigravity_router)
app.include_router(claude_router)
app.include_router(grok_build_router)
# Several subscriptions per coding CLI, switchable without a logout.
app.include_router(agent_accounts_router)
app.include_router(control_router)
# Native window chrome and the editor tool windows; headless hosts
# answer honestly with a fallback URL.
app.include_router(desktop_router)
# The picture behind the tiled section layout.
app.include_router(wallpaper_router)
app.include_router(ide_browser_router)
app.include_router(profile_router)
app.include_router(settings_router)
app.include_router(soul_router)
app.include_router(permissions_router)
# In-app updater (GET status / POST apply). Managed-install only — see
# dodaios/ui/web/update_routes.py; refuses to self-reset a dev checkout.
app.include_router(update_router)
# Share-safe cross-device setup report (read-only) — names why THIS
# install behaves differently from another device (triage).
app.include_router(setup_report_router)
# Starter plans + the one-time "all set" readiness note.
app.include_router(starter_plan_router)
# Frontier auto-switch modal API (GET pending / POST ack) + Self-Mod
# read/restore API. Both were the last route modules left unmounted; the
# 404 on /api/frontier/pending silently broke the desktop auto-switch
# modal too, not just the `jarvis frontier` CLI command.
app.include_router(frontier_router)
app.include_router(self_mod_router)
app.include_router(routine_hooks_router)
app.include_router(tasks_router)
app.include_router(skills_router)
app.include_router(docs_router)
app.include_router(cli_router)
# Spend & Tokens — a read model over sessions/missions/agent-chat.
app.include_router(costs_router)
# Command Registry — the one machine-readable catalog of app commands
# (consumed by the app-command brain tool, the UI, CLI, and docs gen).
app.include_router(commands_router)
app.include_router(friends_router)
app.include_router(marketplace_router)
app.include_router(custom_api_router)
app.include_router(marketplace_publish_router)
app.state.friend_registry = None
app.state.channel_manager = None
app.state.channel_chat_bridge = None
# Twilio telephony voice agent (webhook + media WS + REST status/config).
# Degrades gracefully when the `twilio` extra is not installed (AD-T8).
app.include_router(telephony_router)
from dodaios.telephony.status import TelephonyManager
app.state.telephony_manager = TelephonyManager()
# Browser-microphone voice bridge (B2): /ws/audio — the headless/VPS
# voice path via the browser's own mic/speaker, no sounddevice. Always
# mounted; checked at connect time: realtime mode always serves it,
# pipeline mode while [browser_voice].enabled is on (the default).
from dodaios.browser_voice.route import router as browser_voice_router
app.include_router(browser_voice_router)
app.include_router(sub_agents_router)
app.include_router(outputs_router)
app.include_router(downloads_router)
app.include_router(clipboard_router)
# Socials section — project social-media links (pure file store, no Brain dep).
app.include_router(socials_router)
# In-app feedback / bug-report form → Discord webhook.
app.include_router(feedback_router)
# "Make It Yours" multi-agent workspace (/api/workspace/*).
# Provides agent detection, workspace launch planning, and PTY WebSocket
# for in-app Claude Code / Codex terminals (xterm panes, not OS windows).
app.include_router(workspace_router)
app.include_router(workspace_clis_router)
# Agentic IDE (/api/agentic-ide/*) — a chosen folder plus named terminals
# running Claude Code / Codex, addressable by voice ("what is Mika
# doing?") and promptable from Jarvis. Reuses the same PTY stack as the
# workspace above; adds the folder picker, call-signs, transcripts, and
# the focused coding mode.
# Before the IDE router, so its /{…} paths never shadow /git/….
app.include_router(agentic_ide_scm_router)
app.include_router(agentic_ide_git_router)
app.state.team_threads = None
app.include_router(team_thread_router)
# "Built for you": the self-building ledger (/api/self-build/*).
app.state.self_build = None
app.include_router(self_build_router)
# The Skills tab's library of saved Markdown prompts (/api/agentic-ide/skills/*).
app.include_router(ide_skills_router)
app.include_router(agentic_ide_router)
# The pane-activity sweep has no bus of its own (the registry is a plain
# holder by design); this is the one place that holds one, so the sweep
# is told where a changed reading goes. A reference, not work — nothing
# runs until a workspace is opened (AP-26).
from dodaios.agentic_ide import notifications as ide_notifications
ide_notifications.set_publisher(self.bus.publish)
# The project/chat library behind the chat surface's sidebar. Pure file
# store, no Brain and no session dependency — it lists on a fresh
# install with no keys and answers headless.
app.include_router(chat_library_router)
# Contacts section — user-curated address book (pure file store, no Brain dep).
app.include_router(contacts_router)
# Settings -> Computers: the user's own servers and local VMs over SSH.
app.include_router(server_pairing_router)
app.include_router(computers_router)
# Desktop pets — the `pet` overlay style's pets, look and visibility.
app.include_router(pets_router)
app.include_router(games_router)
app.include_router(dictionary_router)
# Dictation mode — hold to speak, text lands in the focused field.
# Mounted so every action is also `jarvis api dictation <op>`, which is
# the documented Wayland path (no app-owned global shortcuts there).
app.include_router(dictation_router)
# The voice orb's click — call / hangup without speaking the wake word.
app.include_router(voice_call_router)
app.include_router(workflows_router)
if conductor_router is not None:
app.include_router(conductor_router)
app.include_router(preview_router)
app.include_router(board_router)
app.include_router(board_meta_router)
app.include_router(federation_proxy_router)
# Phase 8.5 — review-pipeline read-only UI (Plan §6.5).
app.include_router(review_router)
# One-shot, intent-driven screen look. Answers honestly (not 503) on a
# machine with no display, so `jarvis api screen-context status` is a
# valid capability probe everywhere.
app.include_router(screen_context_router)
# Appshots: the front window as conversation context, on a shortcut,
# a button or a spoken request. Captures through Screen Context.
app.include_router(app_actions_router)
app.include_router(appshot_router)
app.include_router(jarvisx_router)
# The mission deck's pictures: the last Screen-Context capture (one
# frame, in memory, TTL) and Computer-Use frames by content hash.
app.include_router(deck_router)
# Voice-session transcription view (sidebar -> "Transcription").
# Returns 503 as long as app.state.session_store isn't set.
app.include_router(sessions_router)
# Run Inspector — forensic lens over the same voice sessions. Read-only;
# 503 until app.state.session_store is set, like sessions_router.
app.include_router(runs_router)
app.include_router(runs_ws_router)
# Chats conversation manager — unified text+voice history, resume +
# "Speak in this conversation". Reuses chat_store + session_store +
# brain + speech_pipeline from app.state (graceful 503s when absent).
app.include_router(chats_router)
# Agent chat — the typed front-page chat as an agent session on the
# agent-tier providers (dodaios/agent_chat). The service is built on
# first use by the routes (store = data/agent_chat.db) so nothing
# opens on the boot path (AP-26); stop() cancels running turns.
app.state.agent_chat = None
app.state.agent_chat_factory = self._build_agent_chat_service
app.include_router(attention_router)
app.include_router(agent_chat_router)
from .agent_server_routes import router as agent_server_router
app.include_router(agent_server_router)
# Agent society (dodaios/society) — the roster, the typed board, the
# scheduler and the mission bridge. Built on the first /api/society
# call from the factory (store = data/society.db); nothing opens on
# the boot path (AP-26).
app.state.society = None
app.state.society_factory = self._build_society_runtime
# The router-tier voice tools reach the same runtime through the
# brain factory's lazy resolver (AD-OC1).
from dodaios.brain.factory import set_society_factory
set_society_factory(self._build_society_runtime)
app.include_router(society_router)
app.include_router(agent_runtime_router)
app.include_router(runtime_gateway_router)
from .mars_routes import router as mars_router
app.include_router(mars_router)
app.include_router(society_browser_router)
app.include_router(browser_profile_router)
app.include_router(society_figure_router)
app.include_router(drop_router)
# The Jarvis Verse level system (dodaios/progression): a bus listener
# that pays XP for real achievements. Constructing it opens nothing;
# start() subscribes it and the ledger opens on the first award.
from dodaios.progression import ProgressionService
from .progression_routes import router as progression_router
progression_data_dir = Path(
getattr(getattr(self.cfg, "memory", None), "data_dir", None) or "data"
)
self._progression = ProgressionService(
progression_data_dir / "progression.db",
bus=self.bus,
pet_id=lambda: str(getattr(getattr(self.cfg, "ui", None), "pet_id", "") or ""),
)
app.state.progression = self._progression
app.include_router(progression_router)
# The Unreal Verse host (dodaios/verse_host): status, launch and the
# verse.bridge/1 socket. Nothing starts until the first show.
from .verse_routes import router as verse_router
app.include_router(verse_router)
# Default: no recorder wired up — _init_session_stack() in start()
# sets this once it succeeds.
app.state.session_store = None
# Phase-6 mission stack — token issuance is behind SurfaceSecurity;
# mission WS and PTY then perform their narrower hello-frame auth too.
app.include_router(missions_auth_router)
app.include_router(missions_router)
# Paid-API fallback switch for missions (Settings; never voice/agents).
app.include_router(mission_billing_router)
app.include_router(missions_ws_router)
app.include_router(missions_pty_router)
# Computer-Use run control (deep-dive 2026-07-15, H-09): start/list/
# inspect/cancel desktop goals — auto-exposed as `jarvis api
# computer-use <op>` by the dynamic CLI layer.
app.include_router(computer_use_router)
# Phase B9 — Obsidian Setup Wizard (detect install + register vault).
app.include_router(setup_router)
# First-time onboarding guide (/api/onboarding/*).
app.include_router(onboarding_router)
# Phase B3 — Wiki view (read-only REST API over the Obsidian vault).
app.include_router(wiki_router)
# Path-addressed Memory section API (index, reader, map, edits).
app.include_router(memory_vault_router)
# Personal memory vault API (ADR-0044): items, history, export, import.
app.include_router(personal_memory_router)
# Phase B3 — Desktop wiki view live-reload WS endpoint.
# Forwards WikiPageChanged events from the shared EventBus to
# subscribed UI clients. WikiWatcher is started in start().
app.include_router(wiki_ws_router)
# ConnectionManager singleton for the global event stream. Attached
# to MissionBus.subscribe_all() in start().
app.state.missions_ws_manager = _MissionsConnMgr()
# MissionManager + Kontrollierer are wired lazily in start()
# (they need a running event loop for aiosqlite). Default is None,
# so the REST routes return 503 instead of crashing.
app.state.mission_manager = None
app.state.kontrollierer = None
app.state.mission_tool_approvals = self._mission_tool_approvals
# Board aggregator (personal-mastery dashboard) — the aggregator is
# run as a background task in start(); the store is read-only and
# available immediately.
self._setup_board(app)
# Preview registry — subscribed to PreviewServerStarted/Closed events.
try:
from dodaios.preview.registry import PreviewRegistry
preview_registry = PreviewRegistry(bus=self.bus)
preview_registry.attach()
app.state.preview_registry = preview_registry
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("PreviewRegistry setup failed")
app.state.preview_registry = None
# The SPA catch-all must remain after every API router.
self._register_static_or_spa(app)
def _publish_app(self) -> None:
# Deferred construction runs in a thread, but publication belongs to
# the owner loop after prepare() checks its stopping fence. A late
# builder must never publish an app whose teardown has already begun.
from dodaios.core import runtime_refs
runtime_refs.set_web_app(self.app)
async def prepare_app(self) -> None:
"""Complete the route graph before ASGI publication or service startup."""
await self._feature_setup.prepare()
self._publish_app()
#: Breathing room between "voice is ready" and bringing anyio's workers
#: up. Ready is the end of the heavy boot work, not of the box's — the
#: wake models have just loaded and the frontend is still mounting.
_ANYIO_WARM_DELAY_S = 5.0
def _schedule_anyio_pool_warm(self) -> None:
"""Bring a few anyio workers up, once, at the first calm moment.
Every start happens on the loop (anyio leaves no other way), so the
one place to pay for it is right after boot, before the first click —
never on the boot path itself (AP-26). Idempotent: the ready event
can arrive more than once (warm-up, then the watchdog).
"""
if self._anyio_pool_warmed:
return
self._anyio_pool_warmed = True
async def _warm() -> None:
from dodaios.core.loop_executor import warm_anyio_worker_pool
try:
await asyncio.sleep(self._ANYIO_WARM_DELAY_S)
resident = await warm_anyio_worker_pool()
except Exception as exc: # noqa: BLE001 — a pool that grows lazily is
# yesterday's behaviour, not a boot failure
logger.opt(exception=exc).debug("anyio pool warm-up did not complete")
return
logger.info("anyio worker pool warmed: {} thread(s) resident", resident)
self._anyio_pool_warm_task = asyncio.create_task(
_warm(), name="anyio-pool-warm"
)
async def _voice_ready_watchdog(self, deadline_s: float = 45.0) -> None:
"""Release boot waiters after a failed warm-up without promising speech.
The startup banner + "STARTING…" status flip to listening ONLY when a
``VoiceBootStatus(ready=True)`` arrives (mirrored by /api/voice/status).
The pipeline emits it at the end of warm-up — but if construction crashes
or an un-timed model download/load wedges warm-up, that event is never
published and the banner sticks forever even though the user can already
type (permanent "Getting ready to listen"). This backstop fires once,
well past a healthy cold boot (voice-usable budget ≤ 20 s, AP-26), and
releases boot waiters. A genuine ready flips ``_voice_ready`` first, in
which case this is a silent no-op. ``detail="watchdog_timeout"`` marks the
signal as a degraded release (voice may be offline until restart), not a
real "you can speak now".
"""
try:
await asyncio.sleep(deadline_s)
except asyncio.CancelledError:
return
if self._voice_ready:
return
logger.warning(
"Voice-ready watchdog fired after {:.0f}s — the speech pipeline never "
"signalled ready (a construction crash or a wedged warm-up load). "
"Releasing boot waiters; voice remains unavailable until the pipeline "
"confirms listening.",
deadline_s,
)
# Set the endpoint mirror first so /api/voice/status is correct even if
# the bus publish below fails; the WS event then updates live tabs.
self._voice_ready = False
try:
await self.bus.publish(VoiceBootStatus(ready=True, detail="watchdog_timeout"))
except Exception as exc: # noqa: BLE001 — mirror already set; never crash
logger.debug("watchdog VoiceBootStatus publish failed: %s", exc)
def _setup_board(self, app: FastAPI) -> None:
"""Initialize the board store + aggregator + evaluator + BioGenerator.
The store is read-only and ready immediately (creates an empty DB
on the first query, so the UI mount doesn't hit a 500). The
aggregator runs in ``start()`` as a background task; the evaluator
and the BioScheduler subscribe to the bus there.
"""
try:
from dodaios.board.aggregator import BoardAggregator
from dodaios.board.bio_brain import BIO_TIMEOUT_S, resolve_bio_brain
from dodaios.board.evaluator import AchievementEvaluator
from dodaios.board.insights import BoardInsights
from dodaios.board.insights import default_sources as insight_sources
from dodaios.board.profile import BioGenerator, BioStore
from dodaios.board.scheduler import BioScheduler
from dodaios.board.store import BoardStore
from dodaios.core.paths import board_db_path, user_data_dir, user_logs_dir
db_path = board_db_path()
jsonl_dir = user_logs_dir()
jsonl_dir.mkdir(parents=True, exist_ok=True)
# The board's rich source is the durable voice-session store
# (sessions.db), not the flight-recorder JSONL (which is empty on
# most installs). Resolved exactly like bootstrap_sessions does —
# a bare CWD-relative path would silently starve the board of its
# source whenever the app starts from a different directory.
sessions_db_path = self._resolve_sessions_db_path()
aggregator = BoardAggregator(
jsonl_dir=jsonl_dir,
db_path=db_path,
sessions_db_path=sessions_db_path,
)
store = BoardStore(db_path=db_path)
insights = BoardInsights(
insight_sources(
data_dir=Path(self.cfg.memory.data_dir),
sessions_db=sessions_db_path,
board_db=db_path,
)
)
evaluator = AchievementEvaluator(db_path=db_path, bus=self.bus)
bio_store = BioStore(db_path=db_path)
# Optional data-source paths (missions, self-mod).
# If the file/DB doesn't exist, the block just silently drops out
# of the prompt — no error. Paths come from ``user_data_dir()``,
# not relative strings, so an app restart in a different CWD
# doesn't starve the generator of its data.
data_root = user_data_dir() / "data"
recall_db = data_root / "memory.db"
missions_db = data_root / "missions.db"
self_mod_log = data_root / "self_mod.log"
bio_cfg = self.cfg.board.bio
cfg = self.cfg
def _bio_brain_resolver() -> Any:
# Lazy: capture cfg + bus from the closure, so a later
# provider switch via the UI takes effect immediately
# (the resolver invalidates its cache via ConfigReloaded).
# Background billing rule: subscription or local model once a
# subscription is connected, never a per-token key.
return resolve_bio_brain(cfg, bus=self.bus)
bio_generator = BioGenerator(
brain_resolver=_bio_brain_resolver,
store=store,
bio_store=bio_store,
jsonl_dir=jsonl_dir,
recall_db_path=recall_db,
missions_db_path=missions_db,
self_mod_log_path=self_mod_log,
temperature=bio_cfg.temperature,
max_tokens=bio_cfg.max_tokens,
timeout_s=BIO_TIMEOUT_S,
reply_language=lambda: self.cfg.brain.reply_language,
)
# Hook-driven: rewrites the bio on unlocked achievements, never on
# a timer or at boot.
scheduler = BioScheduler(
generator=bio_generator,
bio_store=bio_store,
bus=self.bus,
)
self._board_aggregator = aggregator
self._board_aggregator_task: asyncio.Task[None] | None = None
self._board_evaluator = evaluator
self._bio_scheduler = scheduler
self._bio_generator = bio_generator
app.state.board_aggregator = aggregator
app.state.board_store = store
app.state.board_insights = insights
app.state.achievement_evaluator = evaluator
app.state.bio_generator = bio_generator
app.state.bio_store = bio_store
logger.info(
"Board ready (jsonl={}, db={}, achievements={})",
jsonl_dir,
db_path,
len(evaluator.list_all()),
)
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("Board setup failed — /board returns empty")
self._board_aggregator = None
self._board_aggregator_task = None
self._board_evaluator = None
self._bio_scheduler = None
self._bio_generator = None
app.state.board_aggregator = None
app.state.board_store = None
app.state.board_insights = None
app.state.achievement_evaluator = None
app.state.bio_generator = None
app.state.bio_store = None
def _setup_skill_registry(self, app: FastAPI) -> None:
"""First-run bootstrap + attach the SkillRegistry to ``app.state``.
Failure cases (e.g. a read-only filesystem in the test runner) are
not fatal — the UI then shows "No skills" instead of crashing.
"""
try:
from dodaios.skills.bootstrap import ensure_user_skills_dir
from dodaios.skills.prefs import load_state_overrides
from dodaios.skills.registry import SkillRegistry
skills_root = ensure_user_skills_dir()
registry = SkillRegistry(
root=skills_root,
bus=self.bus,
state_prefs_loader=load_state_overrides,
)
self._skill_registry = registry
app.state.skill_registry = registry
# reload_sync() (disk glob + parse) is deferred off the boot critical
# path — run after uvicorn is listening (start()).
self._pending_reloads.append(("SkillRegistry", registry))
logger.info("SkillRegistry created (scan deferred) from {}", skills_root)
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"SkillRegistry setup failed — Skills view stays empty"
)
app.state.skill_registry = None
def _setup_doc_registry(self, app: FastAPI) -> None:
"""Bring up the doc registry + populate the FTS5 index initially.
Roots = ``default_doc_roots()`` (see ``dodaios/core/paths.py``).
The derived FTS index is process-local and rebuilt on every start. A
shared on-disk WAL made unrelated dev worktrees and overlapping restart
processes block the Docs view indefinitely on Windows.
Failure cases (unreadable roots, unavailable FTS5 support) are not
fatal — the UI surfaces a retryable load error instead of crashing.
"""
try:
from dodaios.core.paths import default_doc_roots
from dodaios.docs.registry import DocRegistry
roots = default_doc_roots()
registry = DocRegistry(
roots=roots,
index_db=None,
bus=self.bus,
)
self._doc_registry = registry
app.state.doc_registry = registry
# The initial Markdown scan + FTS index build is deferred off the
# boot critical path and runs after uvicorn is listening (start()).
self._pending_reloads.append(("DocRegistry", registry))
logger.info("DocRegistry created (scan deferred) for {} roots", len(roots))
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("DocRegistry setup failed — Docs view stays empty")
app.state.doc_registry = None
def _setup_cli_registry(self, app: FastAPI) -> None:
"""Set up the ``CliToolRegistry`` and run the catalog probe asynchronously.
The constructor creates the registry without probing (non-blocking).
An asyncio task is scheduled in ``start()`` that runs ``bootstrap()`` —
until then the endpoints return ``status=checking`` for all entries.
Failure cases: read-only FS or DB lock → no crash, just an empty registry.
"""
try:
from dodaios.clis.registry import CliToolRegistry
from dodaios.clis.shared import set_active_registry
registry = CliToolRegistry(bus=self.bus)
self._cli_registry = registry
app.state.cli_registry = registry
# Shared state: from here on, CliToolLoader and make_cli_patterns_fn
# see the same instance — the LLM gets the real connected CLIs as
# tools, not an empty catalog copy.
set_active_registry(registry)
logger.info(
"CliToolRegistry created ({} catalog entries, bootstrap pending)",
len(registry.catalog().all()),
)
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"CliToolRegistry setup failed — CLIs view stays empty"
)
app.state.cli_registry = None
def _setup_plugin_registry(self, app: FastAPI) -> None:
"""Construct the PluginToolRegistry (non-blocking) and publish it.
Mirror of _setup_cli_registry: the bootstrap (which opens an MCPClient
per connected plugin) is scheduled as a background task in start(). The
shared handle lets the plugin-tools loader + the marketplace routes see
the SAME instance on the SAME bus.
"""
try:
from dodaios.marketplace.plugin_registry import PluginToolRegistry
from dodaios.marketplace.plugin_shared import set_active_plugin_registry
registry = PluginToolRegistry(bus=self.bus)
self._plugin_registry = registry
app.state.plugin_registry = registry
set_active_plugin_registry(registry)
logger.info("PluginToolRegistry created (bootstrap pending)")
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"PluginToolRegistry setup failed — plugins stay worker-only"
)
app.state.plugin_registry = None
self._plugin_registry = None
# ------------------------------------------------------------------
# REST
# ------------------------------------------------------------------
def _register_rest_routes(self, app: FastAPI) -> None:
from dodaios.core.instance import current_instance as _ci
def _instance_name() -> str:
return _ci().name
cfg = self.cfg
bus = self.bus
@app.get("/api/health")
async def health() -> dict[str, Any]:
# ``instance`` lets the frontend badge a dev window as such
# (``dodaios.core.instance``): "default" or "dev".
return {"ok": True, "version": __version__, "instance": _instance_name()}
@app.post("/api/ui/shell-painted", status_code=204, response_model=None)
async def shell_painted() -> Response:
# FastBootstrap consumes this acknowledgement during warm-up. A
# browser can paint after the full FastAPI app has already taken
# over, so the live app must accept the same POST as an idempotent
# no-op instead of returning FastAPI's 405 Method Not Allowed.
return Response(status_code=204)
@app.get("/api/config")
async def get_config() -> dict[str, Any]:
# Read-only snapshot — secrets are, by design, never in the config.
return cfg.model_dump()
@app.get("/api/plugins")
async def get_plugins() -> dict[str, list[str]]:
try:
return list_all_plugins()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("Plugin discovery failed")
return {}
@app.post("/api/debug/emit-test-event")
async def emit_test_event() -> dict[str, Any]:
evt = SystemStarted(version=__version__, source_layer="ui.web.debug")
await bus.publish(evt)
return {
"ok": True,
"event": "SystemStarted",
"trace_id": str(evt.trace_id),
}
@app.post("/api/window/focus")
async def window_focus() -> dict[str, Any]:
# Placeholder until the desktop shell replaces this with a real
# raise. Headless / VPS has no window: ok=False so a later
# desktop launch does not treat this ACK as "I brought a window
# forward" and silently exit (BUG-182).
return {"ok": False, "focused": False, "reason": "no_window"}
@app.get("/api/brain/status")
async def brain_status() -> dict[str, Any]:
"""Returns the currently active brain provider + model.
The frontend uses this on mount to initialize the sidebar footer
correctly (instead of assuming the hardcoded "claude-api"
default). Live switches still arrive via the WS event
``BrainProviderChanged``.
"""
brain = getattr(app.state, "brain", None)
# BrainManager exposes `active_provider`. MockBrain only has `name`.
# Fast-boot deferral: the heavy BrainManager build runs in a
# background thread, so `app.state.brain` is None for the first
# ~850 ms while uvicorn already serves. In that window fall back to
# the configured primary provider — it already names the brain that
# WILL become active — instead of "unknown", which would freeze the
# sidebar footer on a bare "—" until a manual provider switch (the
# mount-fetch is one-shot and nothing re-fetches once the build
# finishes).
provider = (
getattr(brain, "active_provider", None)
or getattr(brain, "name", None)
or cfg.brain.primary
or "unknown"
)
prov_cfg = cfg.brain.providers.get(provider)
model = getattr(prov_cfg, "model", None) if prov_cfg else None
return {"provider": provider, "model": model or "unknown"}
@app.get("/api/voice/status")
async def voice_status() -> dict[str, Any]:
"""Return the current voice boot-readiness flag.
The frontend reads this on mount to initialize the "voice starting"
badge correctly — the ``VoiceBootStatus`` WS event is one-shot, so a
late-connecting UI would miss it. The value is maintained by the bus
subscriber in ``_build_app`` on the server instance.
"""
return {"ready": bool(getattr(self, "_voice_ready", False))}
async def _jarvis_agent_status_snapshot() -> dict[str, Any]:
"""Jarvis-Agent bridge status for the settings view (Wave 3).
Read-only snapshot:
* ``configured`` — is the ``[harness.jarvis_agent]`` block
(legacy alias: ``[harness.openclaw]``) present in jarvis.toml?
* ``enabled`` — bridge toggle from the block
* ``binary_path`` — configured path
* ``binary_detected`` — resolver result (PATH + .cmd/.ps1/.exe)
* ``version_pin`` — AD-21 pin (None when the block is missing)
* ``brain_primary`` — active SUBAGENT provider
(``[brain.sub_jarvis].provider``); falls back to ``brain.primary``
only when no subagent provider is set. NOT the router
brain — the subagent runs the heavy tasks.
* ``provider_slug`` — worker slug of the active subagent
provider per AD-6 (claude-api->claude-cli)
* ``model_resolved`` — override from config OR the frontier-deep
model of the active subagent provider
* ``mapping`` — the full slug-mapping table
Contract: docs/jarvis-agents-bridge.md §4.3 wizard/setup extension.
The endpoint returns NO secrets — only a boolean for whether a key is set.
"""
import shutil
from .agent_status import subscription_statuses
codex_bin = getattr(getattr(cfg, "codex", None), "binary_path", "") or None
auth_statuses = await subscription_statuses(codex_bin)
oc_cfg = cfg.harness.jarvis_agent
router_primary = (cfg.brain.primary or "").lower()
try:
from dodaios.missions.worker_runtime.provider_map import (
MAPPINGS,
canonical_worker_provider,
to_worker_slug,
)
except Exception: # noqa: BLE001
MAPPINGS = () # type: ignore[assignment]
to_worker_slug = None # type: ignore[assignment]
canonical_worker_provider = None # type: ignore[assignment]
# The HEAVY-TASK subagent runs on ``[brain.worker].provider`` —
# NOT on ``brain.primary`` (that is only the lightweight router
# brain). Mark the brain that ACTUALLY executes heavy tasks as
# active; fall back to the router brain only when no subagent
# provider is configured (worker then uses its default chain).
# Mirrors dodaios/missions/init.py::_worker_factory so the displayed
# brain never drifts from the worker that runs. (Bug 2026-05-28:
# the UI showed Gemini active while heavy work ran on Claude.)
sub_cfg = getattr(cfg.brain, "worker", None)
sub_raw = getattr(sub_cfg, "provider", None) if sub_cfg is not None else None
sub_provider = (
canonical_worker_provider(sub_raw)
if canonical_worker_provider is not None
else None
)
primary = sub_provider or router_primary
# Model: an explicit ``[brain.sub_jarvis].model`` wins; else the
# active provider's deep_model (frontier) from
# ``[brain.providers.<provider>]``.
sub_model_override = getattr(sub_cfg, "model", None) if sub_cfg is not None else None
prov_cfg = cfg.brain.providers.get(primary)
primary_deep_model = (sub_model_override or "").strip() or (
getattr(prov_cfg, "deep_model", None) or getattr(prov_cfg, "model", None)
if prov_cfg
else None
)
provider_slug: str | None = None
if to_worker_slug is not None:
try:
provider_slug = to_worker_slug(primary)
except Exception: # noqa: BLE001
provider_slug = None
model_resolved: str | None = None
if oc_cfg is not None and oc_cfg.model:
model_resolved = oc_cfg.model
elif provider_slug and primary_deep_model:
model_resolved = f"{provider_slug}/{primary_deep_model}"
binary_path = oc_cfg.binary_path if oc_cfg is not None else "openclaw"
def _detect_binary() -> str | None:
"""Resolve the bridge binary — up to four full PATH scans."""
found = shutil.which(binary_path)
if found:
return found
for ext in (".cmd", ".ps1", ".exe"):
cand = shutil.which(binary_path + ext)
if cand:
return cand
return None
# Off the loop: a PATH scan walks every directory on PATH, and on a
# long Windows PATH that is the slowest thing this route does. Left
# inline it froze every other section for as long as it took.
binary_detected: str | None = await asyncio.to_thread(_detect_binary)
from dodaios.brain.assistant_name import agent_brand
from dodaios.core.config import (
get_jarvis_agent_secret,
get_provider_secret,
get_secret,
jarvis_agent_secret_slot,
)
from dodaios.ui.web.provider_spec import get_spec
# Display brand follows the wake-word-derived assistant name.
brand = agent_brand(cfg)
def _key_flags(
slot: tuple[str, str] | None, provider: str
) -> tuple[bool, bool]:
"""Whether a dedicated and/or a shared credential exists."""
try:
dedicated = bool(slot and get_secret(slot[0], env_fallback=slot[1]))
shared = bool(get_provider_secret(provider))
except Exception: # noqa: BLE001 — one unreadable store hides no other row
return False, False
return dedicated, shared
mapping_rows = []
for mapping in MAPPINGS:
slot = jarvis_agent_secret_slot(mapping.jarvis)
secret_key = slot[0] if slot else None
# Off the loop: each of these reads the OS credential store,
# which blocks for as long as that store feels like taking.
dedicated_key_set, shared_key_set = await asyncio.to_thread(
_key_flags, slot, mapping.jarvis
)
api_key_set = dedicated_key_set or shared_key_set
oauth_connected = False
oauth_stale = False
# Claude subscription auth is owned by the CLI. Its status
# command covers platform-native stores such as macOS Keychain;
# the legacy bearer-file check only preserves the recoverable
# expired state for older Linux/Windows installs.
if mapping.jarvis == "claude-api":
try:
from dodaios.claude_credentials import (
freshest_claude_oauth,
)
auth_status = auth_statuses["claude"]
oauth_connected = bool(
auth_status.connected and auth_status.mode == "subscription"
)
snapshot_status = freshest_claude_oauth().status
oauth_stale = not oauth_connected and snapshot_status == "expired"
except Exception: # noqa: BLE001
oauth_connected = False
oauth_stale = False
spec = get_spec(mapping.jarvis)
# A keyless local provider has nothing to save, so every
# credential question below has to answer differently for it.
# Without this the card demanded "save a dedicated ollama key
# on this card", offered a field for a key that does not exist,
# and refused activation — a local-only install could pick no
# worker at all. Read off the card's own auth mode, never a
# provider name (AP-21).
keyless = bool(spec and spec.auth_mode == "none")
# claude-api is dual-billed like Codex/Antigravity: the Claude Max
# subscription (claude CLI OAuth login) OR an Anthropic API key.
# Every other MAPPINGS provider bills per token on an API account.
row_billing = (
"local"
if keyless
else "subscription_or_api"
if mapping.jarvis == "claude-api"
else "api"
)
credential_source = (
"dedicated"
if dedicated_key_set
else "legacy_shared"
if shared_key_set
else "oauth"
if oauth_connected or oauth_stale
else "none"
)
mapping_rows.append(
{
"jarvis": mapping.jarvis,
"worker_slug": mapping.worker_slug,
"env_var": mapping.env_var,
"env_fallback": mapping.env_fallback,
# Readiness, not credential presence: a keyless card is
# ready the moment it exists, and gating it on a key it
# never has locked it out of the picker entirely.
"key_set": (
True if keyless else api_key_set or oauth_connected or oauth_stale
),
"api_key_set": api_key_set,
"dedicated_key_set": dedicated_key_set,
"shared_key_set": shared_key_set,
"oauth_connected": oauth_connected,
"oauth_stale": oauth_stale,
"credential_source": "none" if keyless else credential_source,
# No key field on a card with no key slot.
"secret_key": None if keyless else secret_key,
"keyless": keyless,
# The card's own name, so the picker stops showing raw
# ids like "local-openai" next to "xAI Grok".
"label": spec.label if spec else mapping.jarvis,
"dashboard_url": spec.dashboard_url if spec else None,
"credential_help": (
f"Runs on your own hardware — no key, nothing leaves "
f"this machine. Configure its server on the "
f"{spec.label} card under Brain."
if keyless and spec
else f"Dedicated {brand} key for {spec.label}. "
"It is not used by Brain or Realtime."
if spec
else f"Dedicated {brand} API key."
),
"is_active_brain": mapping.jarvis == primary,
"billing": row_billing,
}
)
# Codex is a DIRECT worker (CodexDirectWorker) with no worker slug,
# so it is not in MAPPINGS. Surface it as an explicit selectable
# subagent row. Backed by the ChatGPT subscription (OAuth) OR an
# OpenAI API key — "key_set" is true when either is present.
try:
codex_status = auth_statuses["codex"]
codex_connected = codex_status.connected
codex_installed = codex_status.installed
except Exception: # noqa: BLE001
codex_connected = False
codex_installed = False
try:
codex_key = bool(
get_secret(
"codex_openai_api_key",
env_fallback="CODEX_OPENAI_API_KEY",
)
)
except Exception: # noqa: BLE001
codex_key = False
mapping_rows.append(
{
"jarvis": "openai-codex",
"openclaw": "codex-cli (direct)",
"env_var": "ChatGPT-OAuth",
"env_fallback": "OPENAI_API_KEY",
"key_set": codex_connected or (codex_installed and codex_key),
"api_key_set": codex_key,
"dedicated_key_set": codex_key,
"shared_key_set": False,
"oauth_connected": codex_connected,
"credential_source": (
"oauth" if codex_connected else "dedicated" if codex_key else "none"
),
"secret_key": "codex_openai_api_key",
"dashboard_url": "https://platform.openai.com/api-keys",
# Framed as the ALTERNATIVE to the ChatGPT login — the old
# wording made the subscription card look like it required
# an OpenAI API key (user report 2026-07-17).
"credential_help": (
"No ChatGPT login? Paste an OpenAI API key instead — "
"Codex then bills per token. Not used by Brain or "
"Realtime."
),
"is_active_brain": primary == "openai-codex",
# ChatGPT subscription OAuth OR an OpenAI API key.
"billing": "subscription_or_api",
}
)
# Antigravity is a DIRECT worker (GoogleCliWorker over the official
# agy/Gemini CLI) with no worker slug, so it is not in MAPPINGS —
# the Google sibling of Codex. Dual billing, mirror of Codex: the
# installed Google CLI plus either its subscription OAuth login or
# a Gemini API key (per token). A key cannot replace the executable.
antigravity_status = None
try:
from dodaios.google_cli.auth_service import (
antigravity_provider_ready,
)
antigravity_status = auth_statuses["google"]
antigravity_connected = (
antigravity_status.connected and antigravity_status.mode == "oauth-personal"
)
except Exception: # noqa: BLE001
antigravity_connected = False
try:
antigravity_key = bool(get_jarvis_agent_secret("gemini"))
except Exception: # noqa: BLE001
antigravity_key = False
antigravity_ready = (
antigravity_provider_ready(
antigravity_status,
api_key_present=antigravity_key,
)
if antigravity_status is not None
else False
)
mapping_rows.append(
{
"jarvis": "antigravity",
"openclaw": "agy-cli (direct)",
"env_var": "Google-OAuth",
"env_fallback": "GEMINI_API_KEY",
# The worker DRIVES the agy/Gemini CLI — a Gemini API key
# alone, with no CLI on the machine, must never render the
# card "Ready" (Windows test-machine report 2026-07-18:
# Antigravity showed Ready although never installed, then
# every run died at spawn). Mirrors the Codex row's
# installed-gate below.
"key_set": antigravity_ready,
"api_key_set": antigravity_key,
"dedicated_key_set": False,
"shared_key_set": False,
"oauth_connected": antigravity_connected,
"credential_source": (
"oauth"
if antigravity_connected
else "gemini_agent_key"
if antigravity_key
else "none"
),
"secret_key": None,
"dashboard_url": None,
"credential_help": None,
"is_active_brain": primary == "antigravity",
# Google subscription OAuth OR a Gemini API key.
"billing": "subscription_or_api",
}
)
# Grok Build is a DIRECT worker (GrokBuildDirectWorker over the
# official grok CLI) with no worker slug, so it is not in MAPPINGS.
# SuperGrok / X Premium+ subscription only — the xAI API-key path
# stays on the separate ``grok`` card.
grok_build_status = None
try:
from dodaios.grok_build_auth import (
grok_build_provider_ready,
)
grok_build_status = auth_statuses["grok"]
grok_build_connected = (
grok_build_status.connected and grok_build_status.mode == "subscription"
)
except Exception: # noqa: BLE001
# A probe that cannot answer means "not connected" on this
# overview row, which is the safe reading and one the user can
# see. The Agents tab runs the same check and reports the real
# cause there; this row must never take the whole page down.
grok_build_connected = False
grok_build_ready = (
grok_build_provider_ready(grok_build_status)
if grok_build_status is not None
else False
)
mapping_rows.append(
{
"jarvis": "grok-build",
"openclaw": "grok-cli (direct)",
"env_var": "SuperGrok-OAuth",
"env_fallback": None,
"key_set": grok_build_ready,
"api_key_set": False,
"dedicated_key_set": False,
"shared_key_set": False,
"oauth_connected": grok_build_connected,
"credential_source": "oauth" if grok_build_connected else "none",
"secret_key": None,
"dashboard_url": None,
"credential_help": None,
"is_active_brain": primary == "grok-build",
"billing": "subscription",
"label": "Grok Build",
}
)
return {
"configured": oc_cfg is not None,
"enabled": bool(oc_cfg.enabled) if oc_cfg else False,
"binary_path": binary_path,
"binary_detected": binary_detected,
"version_pin": oc_cfg.version if oc_cfg else None,
"time_cap_min": oc_cfg.time_cap_min if oc_cfg else None,
"concurrency": oc_cfg.concurrency if oc_cfg else None,
"state_dir_root": oc_cfg.state_dir_root if oc_cfg else None,
"brain_primary": primary,
"provider_slug": provider_slug,
"model_override": oc_cfg.model if oc_cfg else None,
# The dedicated subagent LLM pin ([brain.sub_jarvis].model);
# empty/None means "provider's deep model" (model_resolved).
"sub_model_override": sub_model_override,
"model_resolved": model_resolved,
"mapping": mapping_rows,
}
pending_agent_status: asyncio.Task[dict[str, Any]] | None = None
@app.get("/api/jarvis-agent/status")
async def jarvis_agent_status() -> dict[str, Any]:
"""Read bridge configuration and provider credential readiness without secrets."""
nonlocal pending_agent_status
from .agent_status import observe_status_result
# Several windows ask together. Share only unfinished work so a new
# read after a login or config change still gets a fresh snapshot.
if pending_agent_status is None or pending_agent_status.done():
pending_agent_status = asyncio.create_task(_jarvis_agent_status_snapshot())
pending_agent_status.add_done_callback(observe_status_result)
return await asyncio.shield(pending_agent_status)
@app.get("/api/memory/facts")
async def get_memory_facts() -> dict[str, Any]:
"""Returns the core memory (persona, user facts, preferences).
The frontend shows this in the notes view, so the user can see
what Jarvis has remembered. core_memory.json is automatically
injected into the system prompt on the next brain call — so this
view is a read-only mirror of the persistent memory state.
"""
from dodaios.core.config import DATA_DIR
from dodaios.memory import CORE_MEMORY_FILENAME, CoreMemory
from .error_text import LOG_HINT
try:
mem = CoreMemory.load(DATA_DIR / CORE_MEMORY_FILENAME)
return {"ok": True, "data": mem.all()}
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("Memory read error")
return {"ok": False, "error": "memory read failed. " + LOG_HINT, "data": {}}
@app.post("/api/memory/facts")
async def add_memory_fact(payload: MemoryFactBody) -> dict[str, Any]:
"""User-driven add from the UI."""
from dodaios.core.config import DATA_DIR
from dodaios.memory import CORE_MEMORY_FILENAME, CoreMemory
from .error_text import LOG_HINT
fact = payload.fact.strip()
category = payload.category.strip() or "general"
if not fact:
return {"ok": False, "error": "fact is missing"}
try:
mem = CoreMemory.load(DATA_DIR / CORE_MEMORY_FILENAME)
mem.add_fact(fact, category=category)
return {"ok": True, "data": mem.all()}
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("Memory write error")
return {"ok": False, "error": "memory write failed. " + LOG_HINT}
@app.delete("/api/memory/facts")
async def delete_memory_fact(payload: MemoryFactBody) -> dict[str, Any]:
"""User-driven remove from the UI."""
from dodaios.core.config import DATA_DIR
from dodaios.memory import CORE_MEMORY_FILENAME, CoreMemory
from .error_text import LOG_HINT
fact = payload.fact.strip()
category = payload.category.strip() or "general"
if not fact:
return {"ok": False, "error": "fact is missing"}
try:
mem = CoreMemory.load(DATA_DIR / CORE_MEMORY_FILENAME)
ok = mem.remove_fact(fact, category=category)
return {"ok": ok, "data": mem.all()}
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("Memory delete error")
return {"ok": False, "error": "memory delete failed. " + LOG_HINT}
@app.get("/api/terminal/shells")
async def terminal_shells() -> dict[str, Any]:
"""Returns all shells installed on this system.
The frontend uses this to populate the shell dropdown with only
available options — no "command not found" on spawn.
"""
return {"shells": [{"id": s.id, "label": s.label} for s in discover_shells()]}
# ------------------------------------------------------------------
# WebSocket
# ------------------------------------------------------------------
def _register_ws_route(self, app: FastAPI) -> None:
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket) -> None:
await self._handle_ws(ws)
async def _handle_ws(self, ws: WebSocket) -> None:
await ws.accept()
session_id = str(uuid4())
send_lock = asyncio.Lock()
self._clients[session_id] = ws
self._client_send_locks[session_id] = send_lock
welcome = WSWelcome(session_id=session_id, version=__version__)
def _drop_stalled_client() -> None:
"""Detach this WS client so a wedged socket cannot keep blocking
the event bus (AP-18). The receive loop's ``finally`` does the
same cleanup; doing it here too is idempotent and stops the bleed
immediately instead of waiting for the OS TCP timeout."""
self._remove_ws_client(session_id)
try:
self.bus._wildcard_subscribers.remove(_forward) # type: ignore[attr-defined]
except ValueError:
pass
async def _forward(event: Event) -> None:
if session_id not in self._clients:
return
try:
envelope = event_to_ws_envelope(event)
async with send_lock:
# Bounded send: a stalled/half-open client must NEVER block
# the bus (BUG-CU-STALL). On timeout we drop the client.
await asyncio.wait_for(ws.send_json(envelope), timeout=_WS_SEND_TIMEOUT_S)
except WebSocketDisconnect:
_drop_stalled_client()
except TimeoutError:
logger.warning(
"WS client dropped — send stalled >{}s (a wedged tab must "
"never freeze the event bus) session_id={} event={}",
_WS_SEND_TIMEOUT_S,
session_id,
type(event).__name__,
)
_drop_stalled_client()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"WS forward failed",
session_id=session_id,
event=type(event).__name__,
)
self.bus.subscribe_all(_forward)
try:
async with send_lock:
await ws.send_json(welcome.model_dump())
# Welcome must remain the first frame. Register this session only
# after it has arrived, then lazily tap the already-open native mic.
self._mic_level_sessions.add(session_id)
self._ensure_mic_level_bridge()
while True:
try:
raw = await ws.receive_json()
except WebSocketDisconnect:
break
except RuntimeError as exc:
# The socket is gone — e.g. starlette raises
# RuntimeError('WebSocket is not connected ...') after an
# unclean client disconnect instead of WebSocketDisconnect.
# `continue` here re-calls receive_json on the dead socket
# forever: a ~9 MB/s traceback log-storm that wedges the
# event loop and triggers a self-restart cancelling every
# in-flight mission (live incident 2026-06-14). Treat it as
# a disconnect and leave the loop.
logger.opt(exception=exc).warning(
"WS receive aborted; closing connection",
session_id=session_id,
)
break
except Exception as exc: # noqa: BLE001
# A failed receive leaves the socket state uncertain. Treat
# every read error as terminal so a dead socket can never
# spin in this loop (AP-20).
logger.opt(exception=exc).warning(
"WS receive failed; closing connection",
session_id=session_id,
)
try:
await self.bus.publish(
ErrorOccurred(
layer="ui.web.ws",
error_type=type(exc).__name__,
message=str(exc),
recoverable=False,
source_layer="ui.web.ws",
)
)
except Exception as publish_exc: # noqa: BLE001
logger.opt(exception=publish_exc).warning(
"WS receive failure could not be published",
session_id=session_id,
)
break
await self._route_incoming(session_id, raw, send_lock)
except WebSocketDisconnect:
pass
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).error(
"WS handler aborted",
session_id=session_id,
)
await self.bus.publish(
ErrorOccurred(
layer="ui.web.ws",
error_type=type(exc).__name__,
message=str(exc),
recoverable=False,
source_layer="ui.web.ws",
)
)
finally:
# Unsubscribe to avoid a memory leak.
try:
self.bus._wildcard_subscribers.remove(_forward) # type: ignore[attr-defined]
except ValueError:
pass
self._remove_ws_client(session_id)
try:
await ws.close()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug(
"WebSocket was already closed", session_id=session_id
)
def _ensure_mic_level_bridge(self) -> None:
"""Tap both voice levels while a web UI is connected.
The microphone and the assistant's own output. ``level_tap`` only
computes its RMS while something is subscribed, so a web client
connecting is what turns that measurement on — and disconnecting turns
it back off.
"""
if self._mic_level_unsub is not None or not self._mic_level_sessions:
return
# Lazy import keeps audio modules off the web server's startup path.
from dodaios.audio import level_tap, mic_level
loop = asyncio.get_running_loop()
def _receive(level: float) -> None:
try:
loop.call_soon_threadsafe(self._queue_mic_level, float(level))
except RuntimeError as exc:
# Shutdown can close the event loop between the audio callback
# and this handoff. The subscriber is removed during teardown.
logger.opt(exception=exc).debug("Microphone level loop is closed")
def _receive_tts(level: float) -> None:
try:
loop.call_soon_threadsafe(self._queue_tts_level, float(level))
except RuntimeError as exc:
logger.opt(exception=exc).debug("Output level loop is closed")
self._mic_level_unsub = mic_level.subscribe(_receive)
self._tts_level_unsub = level_tap.subscribe(_receive_tts)
def _stop_mic_level_bridge(self) -> None:
unsubscribe = self._mic_level_unsub
self._mic_level_unsub = None
unsubscribe_tts = self._tts_level_unsub
self._tts_level_unsub = None
self._mic_level_latest = 0.0
self._tts_level_latest = 0.0
self._mic_level_revision += 1
if unsubscribe is not None:
unsubscribe()
if unsubscribe_tts is not None:
unsubscribe_tts()
task = self._mic_level_task
if task is not None and task is not asyncio.current_task() and not task.done():
task.cancel()
self._mic_level_task = None
def _remove_ws_client(self, session_id: str) -> WebSocket | None:
ws = self._clients.pop(session_id, None)
self._client_send_locks.pop(session_id, None)
self._mic_level_sessions.discard(session_id)
if not self._mic_level_sessions:
self._stop_mic_level_bridge()
return ws
def _queue_mic_level(self, level: float) -> None:
"""Coalesce audio-thread samples into at most one pending send task."""
if not self._mic_level_sessions:
return
self._mic_level_latest = min(1.0, max(0.0, level)) if math.isfinite(level) else 0.0
self._mic_level_revision += 1
if self._mic_level_task is None or self._mic_level_task.done():
self._mic_level_task = asyncio.create_task(self._drain_mic_levels())
def _queue_tts_level(self, level: float) -> None:
"""Same coalescing as the microphone, for the assistant's own voice."""
if not self._mic_level_sessions:
return
self._tts_level_latest = min(1.0, max(0.0, level)) if math.isfinite(level) else 0.0
self._mic_level_revision += 1
if self._mic_level_task is None or self._mic_level_task.done():
self._mic_level_task = asyncio.create_task(self._drain_mic_levels())
async def _drain_mic_levels(self) -> None:
"""Send only the freshest level; functional WS traffic has priority."""
sent_revision = -1
try:
while self._mic_level_sessions and sent_revision != self._mic_level_revision:
sent_revision = self._mic_level_revision
frame = WSAudioLevel(
input=self._mic_level_latest,
output=self._tts_level_latest,
).model_dump()
await asyncio.gather(
*(
self._send_mic_level(session_id, frame)
for session_id in tuple(self._mic_level_sessions)
)
)
finally:
if self._mic_level_task is asyncio.current_task():
self._mic_level_task = None
async def _send_mic_level(self, session_id: str, frame: dict[str, Any]) -> None:
ws = self._clients.get(session_id)
send_lock = self._client_send_locks.get(session_id)
if ws is None or send_lock is None:
return
async def _send() -> None:
async with send_lock:
if self._clients.get(session_id) is ws:
await ws.send_json(frame)
try:
await asyncio.wait_for(_send(), timeout=_WS_LEVEL_SEND_TIMEOUT_S)
except TimeoutError:
# This sample is already stale; the next one will replace it.
return
except WebSocketDisconnect:
self._remove_ws_client(session_id)
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("Microphone level send failed", session_id=session_id)
stale_ws = self._remove_ws_client(session_id)
if stale_ws is not None:
try:
await stale_ws.close()
except Exception as close_exc: # noqa: BLE001
logger.opt(exception=close_exc).debug(
"Microphone level socket close failed",
session_id=session_id,
)
async def _route_incoming(
self,
session_id: str,
raw: Any,
send_lock: asyncio.Lock,
) -> None:
"""Validates and dispatches an incoming WS frame."""
if not isinstance(raw, dict):
await self.bus.publish(
ErrorOccurred(
layer="ui.web.ws",
error_type="InvalidFrame",
message=f"Expected dict, got {type(raw).__name__}",
recoverable=True,
source_layer="ui.web.ws",
)
)
return
frame_type = raw.get("type")
try:
if frame_type == "message":
msg = WSMessageIn.model_validate(raw)
thread_id = (msg.metadata or {}).get("thread_id", session_id)
await self.bus.publish(
MessageSent(
thread_id=thread_id,
role="user",
text=msg.content,
source_layer="ui.web.ws",
)
)
elif frame_type == "command":
cmd = WSCommand.model_validate(raw)
await self._handle_command(session_id, cmd, send_lock)
else:
await self.bus.publish(
ErrorOccurred(
layer="ui.web.ws",
error_type="UnknownFrameType",
message=f"type={frame_type!r}",
recoverable=True,
source_layer="ui.web.ws",
)
)
except ValidationError as exc:
logger.warning("WS frame validation error", errors=exc.errors())
await self.bus.publish(
ErrorOccurred(
layer="ui.web.ws",
error_type="ValidationError",
message=str(exc),
recoverable=True,
source_layer="ui.web.ws",
)
)
except WebSocketDisconnect:
# A reply frame (pong, terminal.spawned) hit a closed socket — that
# is the receive loop's business, not a failed command.
raise
except Exception as exc: # noqa: BLE001 — one bad frame must not end the session
# A handler failing on one frame (a malformed terminal.resize, a
# PTY write error) used to escape into _handle_ws, which closed the
# whole UI event socket. Report it and keep the connection.
action = raw.get("action") if frame_type == "command" else None
logger.opt(exception=exc).warning(
"WS frame handler failed", frame_type=frame_type, action=action
)
await self.bus.publish(
ErrorOccurred(
layer="ui.web.ws",
error_type="CommandFailed" if frame_type == "command" else "FrameFailed",
message=f"{action or frame_type} failed: {type(exc).__name__}",
recoverable=True,
source_layer="ui.web.ws",
)
)
async def _handle_command(
self,
session_id: str,
cmd: WSCommand,
send_lock: asyncio.Lock,
) -> None:
if cmd.action == "ping":
ws = self._clients.get(session_id)
if ws is not None:
async with send_lock:
await ws.send_json({"type": "pong", "payload": cmd.payload})
elif cmd.action == "test_event":
await self.bus.publish(SystemStarted(version=__version__, source_layer="ui.web.ws.cmd"))
elif cmd.action == "terminal.spawn":
await self._handle_terminal_spawn(session_id, cmd.payload, send_lock)
elif cmd.action == "terminal.input":
await self._handle_terminal_input(cmd.payload)
elif cmd.action == "terminal.resize":
self._handle_terminal_resize(cmd.payload)
elif cmd.action == "terminal.close":
self._handle_terminal_close(cmd.payload)
elif cmd.action == "stt_dictate":
await self._handle_dictation(cmd.payload)
elif cmd.action == "mission.inject":
await self._handle_mission_inject(session_id, cmd.payload)
# provider_switch/set_state now run over REST (POST /api/brain/switch
# or POST /api/secrets/{key}). Duplicate code paths removed here.
async def _handle_mission_inject(self, session_id: str, payload: dict[str, Any]) -> None:
"""Drag-drop a mission card → inject it into the live conversation.
Composes a bounded, human-readable user turn from the card's own data
and publishes it as a normal ``MessageSent``. The existing brain
dispatcher then answers it (spoken on voice, shown in chat) and the
text lands in ``BrainManager._history`` so follow-ups stay in context.
A distinct ``source_layer`` marks the turn for traceability AND is the
signal the router uses to exempt a recap from force-spawn — a dropped
card is DISCUSSED inline, never re-dispatched as a new mission. The
brain dispatcher still runs the turn (only ``"chat"``/``"brain:mock"``
are skipped), so it answers exactly like a typed message.
"""
from dodaios.ui.web.mission_inject import (
MISSION_INJECT_SOURCE_LAYER,
compose_mission_inject_text,
)
text = compose_mission_inject_text(payload)
if not text:
logger.debug("mission.inject: empty/unparseable payload — ignored")
return
thread_id = str(payload.get("thread_id") or session_id)
await self.bus.publish(
MessageSent(
thread_id=thread_id,
role="user",
text=text,
source_layer=MISSION_INJECT_SOURCE_LAYER,
)
)
async def _handle_dictation(self, payload: dict[str, Any]) -> None:
"""Start/stop chat mic-dictation on the live SpeechPipeline.
Transcribe-only: the pipeline streams ``DictationTranscript`` events
(forwarded to the browser by the wildcard subscriber) straight into the
chat input — it never reaches the brain. Resolves the pipeline via
``runtime_refs``; if there is none (headless / voice disabled) it emits a
recoverable error + a toast instead of crashing (cloud-first no-op).
"""
from dodaios.core.runtime_refs import get_speech_pipeline
mode = str(payload.get("mode", "start"))
# "chat" (default) fills the composer; "insert" is dictation mode —
# the transcript is pasted into the focused field of whatever app is in
# front. The chat mic button never sends "insert".
target = "insert" if str(payload.get("target", "chat")) == "insert" else "chat"
pipeline = get_speech_pipeline()
if pipeline is None:
# Headless / voice disabled — no server mic. Recoverable, not fatal:
# surface it as an ErrorOccurred (the frontend already handles that
# event) and return. Cloud-first no-op.
await self.bus.publish(
ErrorOccurred(
layer="ui.web.dictation",
error_type="DictationUnavailable",
message="Dictation needs a server microphone (not available in this mode).",
recoverable=True,
source_layer="ui.web.ws",
)
)
return
try:
if mode == "stop":
pipeline.stop_dictation()
else:
started = pipeline.start_dictation(target=target, source="ws")
if not started:
await self.bus.publish(
ErrorOccurred(
layer="ui.web.dictation",
error_type="DictationBusy",
message="Mic is busy — can't start dictation right now.",
recoverable=True,
source_layer="ui.web.ws",
)
)
except Exception as exc: # noqa: BLE001 — never crash the WS loop
logger.warning("dictation command failed", error=str(exc))
# ------------------------------------------------------------------
# Terminal-Command-Handler
# ------------------------------------------------------------------
async def _handle_terminal_spawn(
self,
session_id: str,
payload: dict[str, Any],
send_lock: asyncio.Lock,
) -> None:
shell_id = str(payload.get("shell", "pwsh"))
cols = int(payload.get("cols", 120) or 120)
rows = int(payload.get("rows", 30) or 30)
cwd = payload.get("cwd")
cwd_str = str(cwd) if cwd else None
shell = get_shell(shell_id)
if shell is None:
await self.bus.publish(
ErrorOccurred(
layer="ui.web.terminal",
error_type="ShellNotFound",
message=f"Shell {shell_id!r} not installed",
recoverable=True,
source_layer="ui.web.terminal",
)
)
return
bus = self.bus
async def _on_output(terminal_id: str, data: str) -> None:
await bus.publish(
TerminalOutput(
terminal_id=terminal_id,
data=data,
source_layer="ui.web.terminal",
)
)
async def _on_closed(terminal_id: str, exit_code: int) -> None:
self._pty_input_buffers.pop(terminal_id, None)
self._pty_shell_ids.pop(terminal_id, None)
await bus.publish(
TerminalClosed(
terminal_id=terminal_id,
exit_code=exit_code,
source_layer="ui.web.terminal",
)
)
try:
session = await self._pty.spawn(
shell_argv=shell.argv,
shell_id=shell.id,
cwd=cwd_str,
cols=cols,
rows=rows,
on_output=_on_output,
on_closed=_on_closed,
)
except RuntimeError as exc:
await self.bus.publish(
ErrorOccurred(
layer="ui.web.terminal",
error_type="PtySpawnFailed",
message=str(exc),
recoverable=True,
source_layer="ui.web.terminal",
)
)
return
self._pty_input_buffers[session.terminal_id] = ""
self._pty_shell_ids[session.terminal_id] = shell.id
await self.bus.publish(
TerminalSpawned(
terminal_id=session.terminal_id,
shell_id=shell.id,
pid=session.pid,
source_layer="ui.web.terminal",
)
)
# Direct response frame with terminal_id, so the frontend can
# unambiguously match up multiple parallel spawn requests.
ws = self._clients.get(session_id)
if ws is not None:
async with send_lock:
await ws.send_json(
{
"type": "terminal.spawned",
"payload": {
"terminal_id": session.terminal_id,
"shell_id": shell.id,
"pid": session.pid,
},
}
)
async def _handle_terminal_input(self, payload: dict[str, Any]) -> None:
terminal_id = str(payload.get("terminal_id", ""))
data = str(payload.get("data", ""))
if not terminal_id or not data:
return
if not self._pty.write(terminal_id, data):
return
# Audit log: maintain the line buffer, emit a command on \r/\n.
buf = self._pty_input_buffers.get(terminal_id, "")
for ch in data:
if ch in ("\r", "\n"):
line = buf.strip()
if line:
await self.bus.publish(
TerminalCommandExecuted(
terminal_id=terminal_id,
shell_id=self._pty_shell_ids.get(terminal_id, ""),
command=line,
source_layer="ui.web.terminal.audit",
)
)
buf = ""
elif ch in ("\x7f", "\b"):
# Backspace — remove the last character from the buffer
buf = buf[:-1]
elif ch >= " ":
buf += ch
# We ignore other control chars (Ctrl-C etc.) in the buffer.
# Memory cap for extremely long pasted lines.
if len(buf) > 4096:
buf = buf[-4096:]
self._pty_input_buffers[terminal_id] = buf
def _handle_terminal_resize(self, payload: dict[str, Any]) -> None:
terminal_id = str(payload.get("terminal_id", ""))
cols = int(payload.get("cols", 0) or 0)
rows = int(payload.get("rows", 0) or 0)
if terminal_id and cols > 0 and rows > 0:
self._pty.resize(terminal_id, cols, rows)
def _handle_terminal_close(self, payload: dict[str, Any]) -> None:
terminal_id = str(payload.get("terminal_id", ""))
if terminal_id:
self._pty.close(terminal_id)
# ------------------------------------------------------------------
# Static / SPA
# ------------------------------------------------------------------
def _register_static_or_spa(self, app: FastAPI) -> None:
if self.cfg.ui.dev_mode:
return
# An install without dist/ would otherwise sit on "Updating…" forever
# with nothing in the log (issue #1057).
missing_build_watch.note_startup(INDEX_FILE)
if ASSETS_DIR.is_dir():
app.mount(
"/assets",
StaticFiles(directory=str(ASSETS_DIR)),
name="assets",
)
@app.get("/", include_in_schema=False, response_model=None)
async def _spa_root() -> FileResponse | HTMLResponse:
# Off the loop: deciding between the index and the holding page
# reads index.html and stats every asset it references. On a disk
# that is busy paging in a cold boot that took long enough to show
# up in a loop-stall stack (2026-08-26, BUG-189).
return await asyncio.to_thread(self._spa_index_response)
async def _spa_fallback(
full_path: str,
) -> FileResponse | HTMLResponse | JSONResponse:
# API and socket paths never reach this handler: _SpaFallbackRoute
# declines them, so the router answers 404 / 405 itself.
try:
target = (DIST_DIR / full_path).resolve()
dist_root = DIST_DIR.resolve()
if target.is_file() and dist_root in target.parents:
return FileResponse(str(target))
except (OSError, ValueError):
pass
# A missing asset (image/script/font) gets an honest 404, never the
# SPA index: an <img> that receives HTML with a 200 renders as a
# permanently broken image — the browser treats the load as a
# success and never retries (sidebar-logo regression, 2026-07-18).
if PurePosixPath(full_path).suffix.lower() in ASSET_SUFFIXES:
return JSONResponse({"detail": "Not Found"}, status_code=404)
return await asyncio.to_thread(self._spa_index_response)
app.router.add_api_route(
"/{full_path:path}",
_spa_fallback,
methods=["GET"],
include_in_schema=False,
response_model=None,
route_class_override=_SpaFallbackRoute,
)
def _spa_index_response(self) -> FileResponse | HTMLResponse:
# An index.html whose own entry bundle is not on disk is worse than no
# index.html at all: the window paints the boot splash, the module
# script 404s, and nothing further runs — no React, no bundle watch, no
# preload recovery — so the only thing left is the 20-second blank-window
# watchdog. A rebuild deletes dist/assets while leaving the previous
# index.html in place for about two seconds (measured 2026-08-22), and
# every window that loads during those two seconds is stuck there. The
# holding page below says what is happening and comes back on its own.
# See dodaios/ui/web/spa_build.py.
if INDEX_FILE.is_file() and build_is_complete(INDEX_FILE, DIST_DIR):
missing_build_watch.clear()
return FileResponse(
str(INDEX_FILE),
headers={
"Cache-Control": "no-store, max-age=0",
"Pragma": "no-cache",
},
)
recovered = recover_conflicted_index(INDEX_FILE, DIST_DIR)
if recovered is not None:
missing_build_watch.clear()
return HTMLResponse(
content=recovered,
headers={
"Cache-Control": "no-store, max-age=0",
"Pragma": "no-cache",
},
)
return self._spa_placeholder_response(
build_missing=missing_build_watch.observe(INDEX_FILE)
)
@staticmethod
def _spa_placeholder_response(*, build_missing: bool = False) -> HTMLResponse:
"""The boot splash, while dist/ is between two builds.
It is deliberately the SAME splash the window opens with — same ground,
same ring, same assistant name — because a rebuild is not a different
program taking over the window. Resolving the theme is left to a two-line
inline script reading the very key `frontend/index.html` reads, which
also takes a synchronous `load_config()` off the one event loop that is
simultaneously serving every asset of the build that is landing.
It waits for a COMPLETE build instead of reloading on a timer: the page
polls the entry document and reloads only once the answer is no longer
itself. A blind `<meta http-equiv="refresh">` reloads into the same
half-written dist over and over, which is the flicker rather than the
cure.
"""
return HTMLResponse(
content=holding_page_html(build_missing=build_missing),
status_code=200,
headers={
"Cache-Control": "no-store, max-age=0",
"Pragma": "no-cache",
},
)
# ------------------------------------------------------------------
# Lifecycle
# ------------------------------------------------------------------
def _schedule_marketplace_refresh_scheduler(self) -> None:
"""Start marketplace token refresh after the current boot turn.
Both desktop and headless launch through :meth:`start`. Deferring the
small amount of catalog/keyring setup until the loop gets control back
keeps it off the readiness-critical path, while the stored handle makes
the operation exactly-once even if start is invoked again before the
callback runs.
"""
if self._refresh_scheduler is not None or self._refresh_scheduler_start_handle is not None:
return
self._refresh_scheduler_stopping = False
loop = asyncio.get_running_loop()
self._refresh_scheduler_start_handle = loop.call_soon(
self._start_marketplace_refresh_scheduler
)
def _start_main_follower(self) -> None:
"""Keep a git checkout's app on the newest main, when the person opted in.
The follower is a daemon thread whose first look waits well past boot;
here it is only created. ``[agentic_ide] follow_main`` is re-read every
round, so the toggle takes effect without a restart.
"""
app = self.app
def enabled() -> bool:
return bool(getattr(self.cfg.agentic_ide, "follow_main", False)) or _follow_main_saved()
def idle() -> bool:
kontrollierer = getattr(app.state, "kontrollierer", None)
running = getattr(kontrollierer, "running_mission_ids", None)
if callable(running) and running():
return False
from dodaios.live.runtime import active
if any(getattr(session, "is_active", False) for session in active()):
return False
from dodaios.core.runtime_refs import get_speech_pipeline
pipeline = get_speech_pipeline()
in_session = getattr(pipeline, "is_session_active", None)
return not (callable(in_session) and in_session())
def restart() -> bool:
desktop = getattr(app.state, "desktop_app", None)
request = getattr(desktop, "request_restart", None)
return bool(request()) if callable(request) else False
try:
from dodaios.core.main_follow import start_follower
start_follower(enabled=enabled, idle=idle, restart=restart)
except Exception as exc: # noqa: BLE001 -- following main is a convenience, never a boot blocker
logger.opt(exception=exc).warning("Follow main did not start.")
def _start_local_models_health_monitor(self) -> None:
"""The Local models self-check task (best-effort, exactly once, off the boot path)."""
if self._local_models_health_monitor is not None:
return
try:
from dodaios.local_models.health_monitor import HealthMonitor
monitor = HealthMonitor(lambda: self.cfg)
monitor.start()
except Exception as exc: # noqa: BLE001 -- a badge must never block boot
logger.opt(exception=exc).warning("Local models health monitor did not start.")
return
self._local_models_health_monitor = monitor
async def _stop_local_models_health_monitor(self) -> None:
monitor = self._local_models_health_monitor
self._local_models_health_monitor = None
if monitor is not None:
try:
await monitor.stop()
except Exception as exc: # noqa: BLE001 -- shutdown stays best-effort
logger.opt(exception=exc).debug("Local models health monitor stop failed.")
def _schedule_local_models_autostart(self) -> None:
"""Start the local model server with Jarvis when it is wanted and in use.
Best-effort, exactly once, off the boot path: the task sleeps a few
seconds first, then decides from the config (autostart on AND a role
or the active brain uses the server) and starts/warms accordingly.
"""
if self._local_models_autostart_task is not None:
return
try:
from dodaios.local_models.autostart import schedule
self._local_models_autostart_task = schedule(lambda: self.cfg)
except Exception as exc: # noqa: BLE001 -- a convenience must never block boot
logger.opt(exception=exc).warning("Local models autostart did not schedule.")
async def _stop_local_models_autostart(self) -> None:
task = self._local_models_autostart_task
self._local_models_autostart_task = None
if task is None or task.done():
return
task.cancel()
try:
await task
except asyncio.CancelledError:
pass
except Exception as exc: # noqa: BLE001 -- shutdown stays best-effort
logger.opt(exception=exc).debug("Local models autostart stop failed.")
def _start_marketplace_refresh_scheduler(self) -> None:
"""Create the periodic OAuth refresh task (best-effort, exactly once)."""
self._refresh_scheduler_start_handle = None
if self._refresh_scheduler is not None:
return
try:
from dodaios.marketplace.connect_helpers import (
build_handler_from_catalog,
connected_plugin_ids,
)
from dodaios.marketplace.refresh_scheduler import RefreshScheduler
from dodaios.marketplace.token_store import TokenStore
token_store = TokenStore()
def _refresh_live_session(plugin_id: str) -> None:
registry = self._plugin_registry
if registry is None or self._refresh_scheduler_stopping:
return
task = asyncio.create_task(
registry.refresh_credentials(plugin_id),
name=f"plugin-refresh:{plugin_id}",
)
self._refresh_registry_tasks.add(task)
def _consume_refresh_result(done: asyncio.Task[Any]) -> None:
self._refresh_registry_tasks.discard(done)
if done.cancelled():
return
try:
done.result()
except Exception as exc: # noqa: BLE001 -- background isolation
logger.opt(exception=exc).warning(
"Marketplace live-session refresh failed for {}.",
plugin_id,
)
task.add_done_callback(_consume_refresh_result)
scheduler = RefreshScheduler(
plugin_ids_fn=lambda: connected_plugin_ids(token_store),
store=token_store,
build_handler=build_handler_from_catalog,
on_refreshed=_refresh_live_session,
)
scheduler.start()
except Exception as exc: # noqa: BLE001 -- refresh must never block boot
logger.opt(exception=exc).warning(
"Marketplace refresh scheduler did not start; connected OAuth plugins may expire."
)
return
self._refresh_scheduler = scheduler
self.app.state.refresh_scheduler = scheduler
logger.info(
"Marketplace refresh scheduler started; connected OAuth tokens "
"will be renewed in the background."
)
def _schedule_credential_migration(self) -> None:
"""Copy keys from the renamed credential service once, off the boot path (AP-26).
A daemon thread in the main instance only, started with a delay; reads
never depend on it (``get_secret`` falls back to the legacy service),
so a process that skips it loses nothing.
"""
try:
from dodaios.core.identity_credentials import schedule_credential_migration
schedule_credential_migration()
except Exception as exc: # noqa: BLE001 -- a background copy must never block boot
logger.opt(exception=exc).warning("Credential copy did not schedule.")
def _schedule_distribution_check(self) -> None:
"""Warn once, off the boot path (AP-26), when both package names are installed."""
try:
from dodaios.core.distribution import schedule_duplicate_distribution_check
schedule_duplicate_distribution_check()
except Exception as exc: # noqa: BLE001 -- a diagnostic must never block boot
logger.opt(exception=exc).debug("Duplicate distribution check did not schedule.")
def _schedule_appshot_shortcut(self) -> None:
"""Arm the global appshot shortcut once the wake model has loaded.
Off the boot path (AP-26): the key reader and the hotkey backend load
native libraries. Headless hosts arm nothing and say so in the log.
"""
try:
loop = asyncio.get_running_loop()
except RuntimeError:
logger.debug("Appshot shortcut not scheduled — no running event loop.")
return
async def _arm() -> None:
from dodaios.appshot.hotkey import start_appshot_shortcut
from dodaios.core import runtime_refs as _rr
await _rr.await_wake_model_ready(timeout=12.0)
try:
await start_appshot_shortcut(self.bus)
except Exception as exc: # noqa: BLE001 - voice/chat work without it
logger.opt(exception=exc).warning("Appshot shortcut could not start")
self._appshot_shortcut_task = loop.create_task(_arm(), name="appshot-shortcut")
def _schedule_realtime_transport_warm(self) -> None:
"""Pre-open the selected realtime transports off the boot path.
``run.bat --headless`` and every browser-only install boot through this
server and never through the desktop shell, so without this hook they
paid the realtime provider's whole cold start inside the user's first
call — for a subscription transport a spawned app-server plus a live
account check. Every OS reaches it the same way; nothing here is
desktop- or Windows-specific.
Exactly-once by construction: the desktop shell starts its own warm
worker under :data:`REALTIME_WARM_TASK_NAME` before it awaits
:meth:`start`, and both run on the same loop, so an already-live task
of that name means this boot is already covered. Whether warming is
appropriate at all stays the factory's decision — it skips itself when
realtime is not the configured voice mode and warms only explicitly
selected providers.
"""
existing = self._realtime_warm_task
if existing is not None and not existing.done():
return
try:
loop = asyncio.get_running_loop()
except RuntimeError:
# No loop (a synchronous start in a test harness): nothing to warm
# onto, and boot must not care.
logger.debug("Realtime transport warm not scheduled — no running event loop.")
return
for task in asyncio.all_tasks(loop):
if task.get_name() == REALTIME_WARM_TASK_NAME and not task.done():
logger.debug(
"Realtime transport warm already running on this loop — "
"not scheduling a second one."
)
return
self._realtime_warm_task = loop.create_task(
self._warm_realtime_transports(), name=REALTIME_WARM_TASK_NAME
)
async def _warm_realtime_transports(self) -> None:
"""Warm the explicitly selected realtime transports once, after boot.
Advisory by contract and never silent (AP-30): a failure here changes
nothing except that the first call pays the cold start it pays today,
and it says so at warning level.
"""
try:
# Spawn-only prestart BEFORE the boot delay: the managed local
# server loads its models for 45-90 s in a SEPARATE process, so
# firing its spawn first costs the boot nothing and moves local
# voice readiness forward by the whole delay. The full warm below
# keeps its delay — it is what spawns app-servers and verifies
# accounts inside THIS process.
from dodaios.realtime.factory import realtime_prespawn_transports
await realtime_prespawn_transports(self.cfg)
except asyncio.CancelledError:
raise
except Exception as exc: # noqa: BLE001 -- prespawn is advisory, never fatal
logger.opt(exception=exc).debug(
"Realtime transport prespawn failed — the regular warm below "
"still covers the start."
)
try:
await asyncio.sleep(REALTIME_WARM_BOOT_DELAY_S)
from dodaios.realtime.factory import realtime_warm_selected_transports
await realtime_warm_selected_transports(self.cfg)
except asyncio.CancelledError:
raise
except Exception as exc: # noqa: BLE001 -- warming is advisory, never fatal
logger.opt(exception=exc).warning(
"Realtime transport warm failed — the first realtime call will "
"pay the provider's cold start."
)
async def _stop_marketplace_refresh_scheduler(self) -> None:
"""Cancel a pending start and stop the live refresh task, if any."""
self._refresh_scheduler_stopping = True
handle = self._refresh_scheduler_start_handle
self._refresh_scheduler_start_handle = None
if handle is not None:
handle.cancel()
scheduler = self._refresh_scheduler
self._refresh_scheduler = None
self.app.state.refresh_scheduler = None
if scheduler is not None:
try:
await scheduler.stop()
except Exception as exc: # noqa: BLE001 -- shutdown stays best-effort
logger.opt(exception=exc).warning("Marketplace refresh scheduler stop failed.")
# A successful token refresh may already have queued a live MCP-session
# rebuild. Drain those tasks before PluginToolRegistry.stop(); otherwise
# a late task can reconnect a client after registry shutdown and leak it.
pending = list(self._refresh_registry_tasks)
for task in pending:
task.cancel()
if pending:
await asyncio.gather(*pending, return_exceptions=True)
self._refresh_registry_tasks.clear()
async def start(
self,
host: str = "127.0.0.1",
port: int | None = None,
*,
start_serving: bool = True,
) -> None:
"""Run the boot init chain. When ``start_serving`` is False the uvicorn
server is NOT started — the caller already serves this app's ASGI
callable (the fast-boot bootstrap in launcher.py serves a holding app on
the port and delegates to ``self.app`` once this init chain completes).
"""
# Just-in-time permissions: the service publishes PermissionNeeded /
# PermissionResolved through this bus, from any thread, onto this loop.
# FIRST, so a consumer that asks while the rest of start() runs is heard.
# It stores two references and probes nothing (AP-26); the desktop app
# already did the same right after the ctor, before the speech task.
from dodaios.platform.permission_service import attach_bus as _attach_permission_bus
_attach_permission_bus(self.bus, asyncio.get_running_loop())
# Which data directory holds the agents, chats and settings this run
# shows: a switched JARVIS_DATA_DIR otherwise looks like lost data.
from dodaios.core.config import log_data_dir_once
log_data_dir_once()
await self.prepare_app()
import uvicorn
# Boot profiling (opt-in via JARVIS_BOOT_PROFILE=1; zero behavior change
# otherwise). Emits one machine-readable ``[BOOT_PROFILE] <phase>=<ms>``
# line per phase to stdout so the boot-timing harness
# (scripts/measure_boot.py) can attribute cold-start cost without an LLM
# or a log-level change. NEVER on the voice critical path.
_boot_profile = os.environ.get("JARVIS_BOOT_PROFILE") == "1"
_boot_last = time.perf_counter()
def _boot_mark(_name: str) -> None:
nonlocal _boot_last
_now = time.perf_counter()
if _boot_profile:
print(
f"[BOOT_PROFILE] {_name}={(_now - _boot_last) * 1000.0:.1f}",
flush=True,
)
_boot_last = _now
# Cloud-first fail-closed: never expose a non-loopback bind without a
# Control API key — the key, not the bind address, is the boundary.
from dodaios.core import control_key as _control_key
from dodaios.ui.web.control_auth import assert_bind_safe
resolved_port = port if port is not None else self.cfg.ui.admin_api_port
# Desktop bootstrap already owns the listener. CLI agents still need
# its address to mount Jarvis' scoped tools, including Browser-Use.
from dodaios.core import runtime_refs as _runtime_refs
_runtime_refs.set_api_base_url(f"http://127.0.0.1:{resolved_port}")
# Announce each change of the passive provider-health record on the bus;
# the existing /ws fan-out carries it to every open window, whose status
# dots then re-read (no poll, no extra socket — AP-33). Registering is
# cheap: nothing is read or started until the first outcome arrives.
from dodaios.brain.provider_health_ledger import publish_changes_to
publish_changes_to(self.bus, asyncio.get_running_loop())
if start_serving:
assert_bind_safe(host, _control_key.get_control_key())
config = uvicorn.Config(
app=self.app,
host=host,
port=resolved_port,
log_level=self.cfg.telemetry.log_level.lower(),
lifespan="on",
loop="asyncio",
)
server = uvicorn.Server(config)
self._server = server
self._serve_task = asyncio.create_task(server.serve())
deadline = asyncio.get_running_loop().time() + 5.0
while not server.started:
if asyncio.get_running_loop().time() > deadline:
raise TimeoutError(
f"uvicorn server on {host}:{resolved_port} not ready within 5s"
)
if self._serve_task.done():
exc = self._serve_task.exception()
if exc is not None:
raise exc
raise RuntimeError("uvicorn.Server.serve() exited before 'started'")
await asyncio.sleep(0.05)
else:
# Bootstrap fast-boot path: a separate server already serves on the
# port and delegates to self.app once this init chain finishes.
self._server = None
self._serve_task = None
_boot_mark("uvicorn_serve")
# The Unreal Verse host launches nothing at start; with the dev_bridge
# flag on it renews the editor's discovery file (contract 1).
try:
from .verse_routes import start_verse_host
await start_verse_host(self.app, resolved_port)
except Exception: # noqa: BLE001 -- the Verse never blocks the app start
logger.opt(exception=True).warning("Verse host start step failed")
# Voice-ready UI backstop (permanent "starting up" bug): the frontend's
# startup banner + top-left "STARTING…" status clear ONLY on a
# VoiceBootStatus(ready=True). If the speech pipeline crashes during
# construction or an un-timed model load wedges warm-up, that event never
# fires and the UI hangs forever. Arm a watchdog that force-releases the UI
# after a generous deadline — but only when voice is meant to warm up
# (else _voice_ready is already seeded True and there is nothing to wait
# for, e.g. JARVIS_VOICE=0 / headless).
if not self._voice_ready:
self._voice_ready_watchdog_task = asyncio.create_task(
self._voice_ready_watchdog(), name="voice-ready-watchdog"
)
else:
# Voice is off, so no ready event will ever arrive to trigger
# this; the end of the deferred phase is the calm moment instead.
self._schedule_anyio_pool_warm()
# Phase-6 mission stack — MissionManager with a DB path derived from
# the config's memory data_dir (same folder as data/jarvis.db, its
# own file data/missions.db). Recovery runs in start().
try:
await self._init_mission_stack()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"MissionManager init failed — /api/missions returns 503"
)
_boot_mark("mission_stack")
# Screenshot retention: auto-delete old Vision / Flight-Recorder blobs
# (data/flight_recorder/blobs/) after the configured window. Runs a
# one-shot boot sweep plus a periodic background task.
try:
await self._init_screenshot_retention()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"Screenshot retention init failed — blobs will not be auto-pruned"
)
_boot_mark("screenshot_retention")
# Flight-recorder audit log: attach the wildcard JSONL event recorder so
# there is a replayable audit trail of what Jarvis did (every event,
# incl. every Computer-Use action). It was defined but never wired at
# boot, so telemetry.flight_recorder=true logged nothing (audit #14).
try:
await self._init_flight_recorder()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"Flight recorder init failed — the audit log will be inactive"
)
_boot_mark("flight_recorder")
# Phase B5 wiki write-wiring — SessionRollupWorker + WikiCurator.
# Subscribes to IdleEntered; gracefully disabled when wiki_integration
# is not configured or enabled is False.
try:
await self._init_wiki_integration()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"WikiIntegration init failed — wiki write-wiring inactive"
)
try:
from dodaios.memory.wiki.health import health as _wiki_health
_wiki_health.record_bootstrap(False, error=str(exc))
except Exception: # noqa: BLE001 — health recording must never break boot
logger.debug("wiki health.record_bootstrap(False) failed", exc_info=True)
_boot_mark("wiki_integration")
# The self-building loop's ledger: opens self_build.db, nothing else at
# boot. Observers and builders register themselves later.
try:
from dodaios.self_build.service import start as start_self_build
_self_build = start_self_build(
Path(self.cfg.memory.data_dir), lambda: self.cfg, publish=self.bus.publish
)
self.app.state.self_build = _self_build
_self_build.start_sweeper()
from dodaios.self_build.app import install_in_app
install_in_app(_self_build, self.app.state, self.bus)
from dodaios.self_build.code import install as install_code_builder
install_code_builder(_self_build, self.app.state)
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"self-build ledger init failed — nothing will be self-built this run"
)
# Jarvis' own self-learning loop: two bus subscriptions, nothing else
# at boot. Reviews run later in the background (dodaios/memory/learning).
try:
from dodaios.memory.learning.loop import start_learning
start_learning(self.cfg, self.bus)
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"Learning loop init failed — the assistant will not learn this run"
)
# Reconcile the derived FTS5 index after readiness. This repairs stale
# rows after a vault switch without extending the startup critical path.
try:
self._init_wiki_boot_index(background=True)
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"WikiBootIndex-Init failed — vault search may return no hits "
"until the first page write or a manual reindex"
)
_boot_mark("wiki_boot_index")
# Phase B3 wiki live-reload — start the WikiWatcher so file
# changes in the vault publish WikiPageChanged events that the
# /api/wiki/live WS endpoint forwards to the desktop tab.
try:
self._init_wiki_watcher()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"WikiWatcher init failed — desktop wiki live-reload inactive"
)
_boot_mark("wiki_watcher")
# Voice-session recorder + store for the transcription view.
# Sub-setup: runs sync (SQLite-WAL, no async loop needed), but is
# run in start() so the EventBus is guaranteed to be alive.
try:
self._init_session_stack()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"SessionRecorder init failed — /api/sessions returns 503"
)
_boot_mark("session_stack")
# Phase-5 task stack (tasks view). TaskStore lives additively in
# data/jarvis.db (ADR-0003); the scheduler runs as an asyncio loop
# terminated by the CancelToken in stop().
try:
await self._init_task_stack()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("TaskStack init failed — /api/tasks returns 503")
_boot_mark("task_stack")
# Start the skill hot-reload watcher once the loop is stable.
if self._skill_registry is not None:
try:
self._skill_registry.start_watcher(asyncio.get_running_loop())
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"SkillRegistry watcher start failed — no hot-reload"
)
# Doc hot-reload watcher, likewise. watchdog observes its own
# observer thread per root.
if self._doc_registry is not None:
try:
self._doc_registry.start_watcher(asyncio.get_running_loop())
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"DocRegistry watcher start failed — no hot-reload"
)
# These owners must settle before shutdown closes their registries.
self._schedule_registry_bootstraps()
# Board aggregator as a never-ending task. run_forever() does an
# on-startup run first and then sleeps 6h (Plan §5-A Decision #2).
if self._board_aggregator is not None:
self._board_aggregator_task = asyncio.create_task(
self._board_aggregator.run_forever(interval_s=6 * 3600),
name="board-aggregator",
)
# Achievement evaluator on the bus. Phase B.
if self._board_evaluator is not None:
try:
self._board_evaluator.attach()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("AchievementEvaluator.attach() failed")
# Level system on the bus: pays XP for finished turns, tasks and quests.
progression = getattr(self, "_progression", None)
if progression is not None:
try:
progression.attach()
except Exception as exc: # noqa: BLE001 - levels are optional, the app is not
logger.opt(exception=exc).warning("ProgressionService.attach() failed")
# Bio scheduler — subscribes to achievement unlocks only. It starts no
# task and generates nothing here; the brain is resolved per
# generation, when a board event actually asks for one.
if self._bio_scheduler is not None:
try:
self._bio_scheduler.start()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("BioScheduler.start() failed")
# Friends-Stack: FriendRegistry + ChannelManager. Started as a BACKGROUND
# task so a slow Telegram/Discord network connect (bot login / getUpdates
# handshake — observed ~4 s, and a 409 retry storm on a restart overlap)
# does not delay backend-ready and, with it, the speech warm-up. Channels
# are background transports — nothing user-visible needs them live before
# voice; /api/friends + /api/socials 503 until the stack is up (the route
# guards already handle the brief app.state.channel_manager=None window).
async def _init_channel_stack_guarded() -> None:
try:
await self._init_channel_stack()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"ChannelStack init failed — /api/friends returns 503"
)
self._channel_stack_task = asyncio.create_task(
_init_channel_stack_guarded(), name="channel-bootstrap"
)
# Run the deferred registry disk scans (skill + doc reload_sync) off the
# boot critical path. Each is a blocking glob + FTS index build (~hundreds
# of ms) that nothing at BOOT_READY needs — the views tolerate an empty
# registry until the scan lands. Run in a worker thread so the scan never
# stalls the event loop; sequential so two SQLite writers don't contend.
if self._pending_reloads:
pending = list(self._pending_reloads)
self._pending_reloads.clear()
# Docs are user-facing and can be opened immediately after the
# shell appears. Keep the scans sequential, but put Docs ahead of
# the authoring-only skill catalog once the wake gate releases.
pending.sort(key=lambda item: item[0] != "DocRegistry")
async def _run_deferred_reloads() -> None:
# Yield until the wake model is loaded before these blocking disk
# scans start their worker thread —
# otherwise they steal CPU/disk from the custom-wake base/cpu
# model load and can extend its time. NO-OP on headless / voice-off
# (returns immediately); bounded so a stuck wake load never blocks
# the scans. The Docs view can request the same load immediately.
from dodaios.core import runtime_refs as _rr
await _rr.await_wake_model_ready(timeout=12.0)
for label, registry in pending:
try:
if label == "DocRegistry":
# Shares the on-demand route lock: if the user
# already opened Docs this becomes an instant no-op.
await registry.ensure_loaded()
else:
await asyncio.to_thread(registry.reload_sync)
logger.info(
"{} deferred scan complete ({} entries)",
label,
len(registry.list()),
)
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"{} deferred reload failed — view stays empty", label
)
self._deferred_reload_task = asyncio.create_task(
_run_deferred_reloads(), name="deferred-registry-reload"
)
_boot_mark("watchers_and_background")
# Schedule last: callers regain control and publish the ready app before
# catalog/keyring reads or refresh network calls can begin. This shared
# hook covers normal desktop, headless, and direct WebServer starts.
self._schedule_marketplace_refresh_scheduler()
self._start_local_models_health_monitor()
self._start_main_follower()
self._schedule_local_models_autostart()
# Same reasoning, and the same three boot paths: a headless or
# browser-only install has no desktop shell to warm the realtime
# transport for it.
self._schedule_realtime_transport_warm()
self._schedule_appshot_shortcut()
self._schedule_credential_migration()
self._schedule_distribution_check()
# Browser provisioning includes a Chromium probe and may need Linux
# system libraries. Leave it to explicit browser use/setup; boot and
# shell-paint acknowledgements must keep headless installations usable.
# Existing Mars work recovers with zero clients. The deferred helper
# performs its existence probe and runtime composition after boot yields.
from .mars_routes import schedule_mars_resume
data_dir = Path(getattr(getattr(self.cfg, "memory", None), "data_dir", None) or "data")
schedule_mars_resume(self.app.state, data_dir)
async def _init_screenshot_retention(self) -> None:
"""Auto-delete captured screenshot blobs older than the configured
window (default 10 days).
Jarvis captures screenshots into ``data/flight_recorder/blobs/`` for
in-session context (Vision system + Flight-Recorder event blobs); they
are throwaway afterwards and otherwise grow without bound (observed:
~91k files / ~38 GB). Runs a one-shot sweep at boot plus a periodic
background task. ``flight_recorder_retention_days = 0`` disables it.
"""
from dodaios.telemetry.retention import (
DEFAULT_RETENTION_INTERVAL_SECONDS,
retention_task,
sweep_old_blobs,
)
retention_days = self.cfg.telemetry.flight_recorder_retention_days
if retention_days <= 0:
logger.info(
"Screenshot retention disabled (flight_recorder_retention_days={})",
retention_days,
)
return
# The same directory the writers use, NOT cfg.memory.data_dir. The
# production writer is the Vision ScreenshotSource
# (dodaios/vision/engine.py constructs it with no blob_dir → falls back
# to _DEFAULT_BLOB_DIR in dodaios/vision/screenshot.py =
# flight_recorder_dir()/blobs). It ignores cfg.memory.data_dir, so
# deriving from that key would make the sweep a silent no-op whenever
# data_dir is overridden.
from dodaios.core.paths import flight_recorder_dir as _flight_recorder_dir
flight_recorder_dir = _flight_recorder_dir()
# The one-shot boot sweep is pure cleanup of old blobs — nothing
# downstream consumes its stats (they are only logged). Awaiting it sat
# on the boot path before the voice pipeline could start. Fold it into
# the front of the (already background) retention task so _init returns
# immediately; the same task reference is still cancelled on shutdown.
async def _boot_sweep_then_retain() -> None:
try:
stats = await sweep_old_blobs(
flight_recorder_dir=flight_recorder_dir,
retention_days=retention_days,
)
if stats["removed"] > 0:
logger.info(
"Screenshot retention boot sweep: removed={} freed={:.1f} MB (cutoff={}d)",
stats["removed"],
stats["bytes_freed"] / (1024 * 1024),
retention_days,
)
else:
logger.debug(
"Screenshot retention boot sweep: nothing older than {}d",
retention_days,
)
except Exception: # noqa: BLE001 — cleanup never blocks/breaks boot
logger.warning("Screenshot retention boot sweep failed", exc_info=True)
await retention_task(
flight_recorder_dir=flight_recorder_dir,
retention_days=retention_days,
interval_seconds=DEFAULT_RETENTION_INTERVAL_SECONDS,
)
self._screenshot_retention_task = asyncio.create_task(_boot_sweep_then_retain())
async def _init_flight_recorder(self) -> None:
"""Attach the flight-recorder audit log to the EventBus (ADR-0007).
Writes every event as a JSONL line under ``data/flight_recorder/`` — a
replayable audit trail of what Jarvis did, including every Computer-Use
action. Gated on ``telemetry.flight_recorder`` (default on); the recorder
is held on ``app.state`` for later flush/close on shutdown. The recorder
auto-flushes every second, and oversized event blobs land under
``blobs/`` which the screenshot-retention task already prunes.
"""
from dodaios.core.paths import flight_recorder_dir
from dodaios.telemetry.recorder import attach_flight_recorder
rec = attach_flight_recorder(
self.bus,
enabled=self.cfg.telemetry.flight_recorder,
data_dir=flight_recorder_dir(),
)
if rec is None:
logger.info("Flight recorder disabled (telemetry.flight_recorder=false)")
return
self._flight_recorder = rec
self.app.state.flight_recorder = rec
logger.info("Flight recorder attached — events -> data/flight_recorder/*.jsonl")
async def _init_mission_stack(self) -> None:
"""Phase-6 production wiring: bootstrap_missions() returns the
complete stack (manager, Kontrollierer, budget, voice listener,
cleanup task), including safety hooks and the WS-manager bus bridge.
"""
from dodaios.missions.init import bootstrap_missions
data_dir = Path(self.cfg.memory.data_dir)
# Startup wiring runs before this stack accepts work.
data_dir.mkdir(parents=True, exist_ok=True) # noqa: ASYNC240
db_path = data_dir / "missions.db"
# Isolation root: <repo_parent>/jarvis-agent-outputs/ (preferred; falls back
# to <repo_parent>/sub-agents-outputs/ if only the old dir exists — see
# resolve_outputs_root). The repo root is 4 levels above dodaios/ui/web/server.py:
# server.py -> web -> ui -> jarvis -> repo.
repo_root = WEB_DIR.parent.parent.parent
# Test/benchmark isolation seam: an explicit JARVIS_ISOLATION_ROOT
# redirects the mission worktree container (and, with it, the startup
# cleanup sweep) away from the SHARED production outputs dir.
# Unset in production → unchanged behavior. Critical because
# ``startup_sweep`` is filesystem-driven (removes any entry older than
# cleanup_days by mtime, not DB-gated): without this seam an isolated
# headless boot (e.g. scripts/measure_boot.py) would sweep real mission
# outputs older than 14 days.
from dodaios.missions.isolation.worktree import (
resolve_outputs_root,
resolve_readable_outputs_roots,
)
_iso_override = os.environ.get("JARVIS_ISOLATION_ROOT")
if _iso_override:
isolation_root = Path(_iso_override)
else:
isolation_root = resolve_outputs_root(repo_root)
# Fail-closed primary-instance gate: POSITIVE proof is required.
# Only the launcher process, after confirming it holds the
# single-instance lock, sets JARVIS_PRIMARY_INSTANCE="1".
# Any other caller — smoke scripts, eval harnesses, --no-lock parallel
# sessions, or anything that simply does not set the variable — gets
# _is_primary=False and will NOT run the crash_recovery sweep.
# This prevents side-processes from sweeping the desktop app's live
# missions to FAILED('crash_recovery') (the 98-of-286 false-failure
# bucket, forensic 2026-05-31, missions 019e7095 / 019e6fea).
_is_primary = os.environ.get("JARVIS_PRIMARY_INSTANCE") == "1"
result = await bootstrap_missions(
db_path=db_path,
isolation_root=isolation_root,
repo_root=repo_root,
recover_missions=_is_primary,
tts_speak_fn=None, # TTS wiring comes from DesktopApp once voice is live
brain_caller=None, # The decomposer runs in heuristic-only mode
# Welle-4 Y: pass the speech bus through for MissionAnnouncer, so
# mission-completion events land as AnnouncementRequested on the
# global bus — pipeline._on_announcement subscribes there.
speech_bus=self.bus,
# Defaults from jarvis.toml [phase6.*] (all overridable via cfg later)
safety_enabled=True,
# User mandate 2026-05-31 ("no budget at all", frontier-quality-
# over-cost): the per-mission/daily cost cap is DISABLED so a long,
# high-quality Opus mission is never aborted mid-work for cost. The
# per_mission_usd/daily_usd values below are inert while disabled.
budget_enabled=False,
per_mission_usd=5.0,
daily_usd=50.0,
cleanup_days=14,
cleanup_startup_sweep=True,
cleanup_daily=False,
max_workers=5,
)
self.app.state.mission_manager = result["manager"]
self.app.state.kontrollierer = result["kontrollierer"]
self.app.state.missions_budget = result["budget"]
self.app.state.mission_announcer = result["mission_announcer"]
# Mission-Bus -> global-bus bridge that re-publishes terminal missions
# as MissionCompleted so the Tasks scheduler can drive When-Then rules.
self.app.state.mission_event_bridge = result["mission_event_bridge"]
# outputs_routes.py uses this to render the Outputs view; it would
# otherwise have to re-derive the same WEB_DIR.parent.parent.parent
# walk and would silently drift if the launcher layout changes.
self.app.state.outputs_root = isolation_root
self.app.state.outputs_roots = resolve_readable_outputs_roots(repo_root)
self._missions_voice_listener = result["voice_listener"]
self._missions_cleanup_task = result["cleanup_task"]
# Welle-4 wiring: the spawn_worker tool in the brain needs both the
# MissionManager AND the Kontrollierer. The brain is built in
# DesktopApp._start_speech_and_orb via build_default_brain() — the
# singleton setters make both available there (lazy resolve via
# _resolve_mission_manager / _resolve_kontrollierer).
# Without the Kontrollierer setter, the voice path would dispatch a
# mission but nothing would trigger run_mission — the mission would
# stay PENDING and the user would hear no answer (BUG-016).
try:
from dodaios.brain.factory import (
set_kontrollierer,
set_mission_manager,
set_worker_bootstrap_failed,
)
set_mission_manager(result["manager"])
set_kontrollierer(result["kontrollierer"])
set_worker_bootstrap_failed(False)
self.app.state.worker_available = True
except Exception as exc: # noqa: BLE001
logger.warning(
"set_mission_manager/kontrollierer wiring failed — "
"spawn_worker is disabled for this run: %s",
exc,
)
# Surface the failure for both downstream readers:
# - `self.app.state.worker_available` lets REST routes and
# UI components show an explicit "worker unavailable" hint
# instead of permanently rendering "loading" / "pending".
# - the factory-level singleton lets the Brain's spawn_worker
# tool short-circuit at execute()-time with an honest
# "could not be initialized" message instead of the
# transient "not ready yet" the in-progress path returns.
self.app.state.worker_available = False
try:
from dodaios.brain.factory import set_worker_bootstrap_failed
set_worker_bootstrap_failed(True)
except Exception as inner_exc: # noqa: BLE001
logger.warning(
"set_worker_bootstrap_failed wiring failed: %s",
inner_exc,
)
# WS bridge: the Phase-4 ConnectionManager is subscribed to the bus.
ws_mgr = getattr(self.app.state, "missions_ws_manager", None)
if ws_mgr is not None:
result["manager"].bus.subscribe_all(ws_mgr.fanout)
# Welle-4 follow-up: bridge MissionBus -> SubAgentRegistry so the
# Sub-Agents board lights up. The legacy publishers for
# JarvisAgentTaskStarted/Completed were removed in the migration; without
# this hook the dashboard stays empty even while missions are flowing.
registry = getattr(self.app.state, "sub_agent_registry", None)
if registry is not None:
registry.attach_mission_bus(result["manager"].bus)
recovered = result["recovered_mission_ids"]
sweep = result["sweep_stats"]
logger.info(
"Phase-6 stack online (db={}, recovered={}, sweep={}/{}/{} scanned/removed/errors)",
db_path,
len(recovered),
sweep["scanned"],
sweep["removed"],
sweep["errors"],
)
# Periodic recovery re-sweep (2026-06-10, mission 019eb25c): boot
# recovery runs ONCE and — correctly — skips a mission whose owner still
# looks live (active-guard). But that guard is boot-only: when the owning
# instance dies AFTER boot, the orphan stays non-terminal (e.g.
# CRITIQUING) in the DB and UI forever ("missions never find an end").
# This timer re-runs the SAME conservative, active-guarded sweep so an
# orphan is finalized on the next tick once it crosses the unchanged
# staleness threshold. Gated on the same primary-instance flag as boot
# recovery — a secondary/--no-lock instance must never sweep a primary's
# live missions. Cancelled on shutdown (see start()'s cleanup path).
if _is_primary:
from dodaios.missions.recovery import periodic_recovery_sweep
self._missions_resweep_task = asyncio.create_task(
periodic_recovery_sweep(result["manager"].store),
name="mission-recovery-resweep",
)
# Missions parked in WAITING_CAPACITY resume from their checkpoint
# once their own subscription has capacity again — never on another
# provider or a paid key (dodaios/missions/capacity.py). Primary
# instance only, like the sweep: two instances must not both
# resume one mission.
from dodaios.missions.capacity import capacity_resume_loop
self._missions_resume_task = asyncio.create_task(
capacity_resume_loop(result["kontrollierer"].resume_waiting_missions),
name="mission-capacity-resume",
)
async def _init_wiki_integration(self) -> None:
"""Phase B5 wiki write-wiring: bootstrap SessionRollupWorker + WikiCurator.
Subscribes to ``IdleEntered``; writes session digests into the
Obsidian vault at session end. No-op when
``cfg.wiki_integration.enabled`` is False.
"""
from dodaios.memory.wiki.integration import bootstrap_wiki_integration
from dodaios.memory.wiki.page import MarkdownPageRepository
wiki_cfg = self.cfg.wiki_integration
if not wiki_cfg.enabled:
logger.info("wiki_integration: disabled — skipping bootstrap")
try:
from dodaios.memory.wiki.health import health as _wiki_health
_wiki_health.record_bootstrap(False, error="disabled in config")
except Exception: # noqa: BLE001 — health recording must never break boot
logger.debug("wiki health.record_bootstrap(disabled) failed", exc_info=True)
return
repo = MarkdownPageRepository()
from dodaios.memory.wiki.vault_root import resolve_vault_root
vault_root = resolve_vault_root(wiki_cfg.vault_root).path
def _wiki_scheduler_factory(*, curator): # noqa: ANN001, ANN202
"""Build the CuratorScheduler (cooldown + VaultLock, Wave-2 B4).
Gates the Stage-2 consolidation drain; the consolidator itself is
attached later via ``scheduler.attach_consolidator``.
"""
from dodaios.memory.wiki.lock import VaultLock
from dodaios.memory.wiki.scheduler import CuratorScheduler
sched_cfg = self.cfg.wiki_scheduler
lock_path = Path(sched_cfg.lock_path)
if not lock_path.is_absolute():
lock_path = Path.cwd() / lock_path
return CuratorScheduler(
curator=curator,
lock=VaultLock(
lock_path,
stale_after_seconds=int(sched_cfg.lock_stale_after_seconds),
),
config=sched_cfg,
)
handle = await bootstrap_wiki_integration(
bus=self.bus,
repo=repo,
vault_root=vault_root,
config=wiki_cfg,
brain_caller=None, # curator uses BrainProviderRegistry internally
scheduler_factory=_wiki_scheduler_factory,
)
self._wiki_integration_handle = handle
logger.info("wiki_integration: bootstrap_wiki_integration succeeded")
# No periodic re-review of voice sessions: the six-hourly auto-backfill
# was removed on 2026-09-30 together with the per-turn and end-of-call
# extraction (it billed paid keys while nobody was at the PC). The
# manual POST /api/wiki/backfill is the explicit control.
try:
from dodaios.memory.wiki.health import health as _wiki_health
_wiki_health.record_bootstrap(True)
except Exception: # noqa: BLE001 — health recording must never break boot
logger.debug("wiki health.record_bootstrap(True) failed", exc_info=True)
def _init_wiki_boot_index(self, *, background: bool = False) -> None:
"""Rebuild the derived FTS view against the active vault.
Production uses a daemon thread after app readiness (AP-26). Tests and
explicit callers may keep the synchronous default for deterministic
verification.
"""
import sqlite3
import threading
from dodaios.memory.wiki.db_path import resolve_wiki_db_path
from dodaios.memory.wiki.fts_index import rebuild_index
def _resume_semantic_search() -> None:
# Semantic search, when the user switched it on: its own thread
# loads the model and encodes only the pages that changed. Called
# on every way out of this function, so the switch always learns
# an honest state, also when there is no vault to search.
try:
from dodaios.memory.wiki import semantic_setup
semantic_setup.resume(self.cfg)
except Exception: # noqa: BLE001 - the word search stands on its own
logger.opt(exception=True).warning(
"wiki_boot_index: semantic search could not be resumed"
)
wiki_cfg = self.cfg.wiki_integration
if not wiki_cfg.enabled:
_resume_semantic_search()
return
from dodaios.memory.wiki.vault_root import resolve_vault_root
vault_root = resolve_vault_root(wiki_cfg.vault_root).path
if not vault_root.is_dir():
logger.info("wiki_boot_index: vault missing — skipping ({})", vault_root)
_resume_semantic_search()
return
db_path = resolve_wiki_db_path(self.cfg.memory.data_dir)
def _reconcile() -> None:
db_path.parent.mkdir(parents=True, exist_ok=True)
conn = sqlite3.connect(str(db_path), check_same_thread=False)
try:
indexed = rebuild_index(vault_root, conn)
logger.info(
"wiki_boot_index: reconciled {} page(s) from {} into {}",
indexed,
vault_root,
db_path,
)
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"wiki_boot_index: background reconciliation failed"
)
try:
from dodaios.memory.wiki.health import health as _wiki_health
_wiki_health.record_chain_failure(f"wiki index reconciliation failed: {exc}")
except Exception: # noqa: BLE001
logger.debug("wiki index health recording failed", exc_info=True)
finally:
conn.close()
# Behind the word index, so it never competes with start-up (AP-26).
_resume_semantic_search()
if background:
thread = threading.Thread(
target=_reconcile,
name="jarvis-wiki-index-reconcile",
daemon=True,
)
thread.start()
self._wiki_index_thread = thread
return
_reconcile()
def _init_wiki_watcher(self) -> None:
"""Phase B3 — start the WikiWatcher for desktop live-reload.
Watches the configured vault root and publishes WikiPageChanged
events on the shared bus. Failures are logged but never raised;
the desktop app must boot when the vault is empty or watchdog
cannot start an observer.
"""
from dodaios.memory.wiki.db_path import resolve_wiki_db_path
from dodaios.memory.wiki.vault_root import resolve_vault_root
from dodaios.memory.wiki.watcher import WikiWatcher
wiki_cfg = self.cfg.wiki_integration
if not wiki_cfg.enabled:
logger.info("wiki_watcher: wiki_integration disabled — skipping")
return
vault_root = resolve_vault_root(wiki_cfg.vault_root).path
db_path = resolve_wiki_db_path(self.cfg.memory.data_dir)
watcher = WikiWatcher(
vault_root=vault_root,
bus=self.bus,
db_path=db_path,
)
try:
started = watcher.start()
except FileNotFoundError as exc:
logger.warning("wiki_watcher: vault missing: {}", exc)
return
except PermissionError as exc:
logger.warning("wiki_watcher: permission denied: {}", exc)
return
if not started:
logger.info("wiki_watcher: did not start — live-reload inactive")
return
self._wiki_watcher = watcher
self.app.state.wiki_watcher = watcher
logger.info("wiki_watcher: started for vault {}", vault_root)
async def _init_task_stack(self) -> None:
"""Phase-5 task-queue wiring (BUG-007).
Builds the TaskStore + TaskRunner + TaskScheduler, runs the
startup cleanup for ``running`` tasks (app exit), and starts
the scheduler loop as a background task.
The runner is wired with the brain so agentic (``agent``) tasks run a
tool-restricted turn unattended (read-only/monitor-tier plugins pass;
ask-tier still gates). ``speak``/``harness_dispatch`` actions still
have no TTS/harness here — those remain follow-up wiring. The UI is
live regardless (list + cancel + detail timeline) since the routes
only touch store + scheduler.
"""
from dodaios.control.cancel import CancelToken
from dodaios.tasks.approval_bridge import TaskAutoApprover
from dodaios.tasks.runner import TaskRunner
from dodaios.tasks.scheduler import TaskScheduler
from dodaios.tasks.store import TaskStore
data_dir = Path(self.cfg.memory.data_dir)
# Startup wiring runs before this stack accepts work.
data_dir.mkdir(parents=True, exist_ok=True) # noqa: ASYNC240
# Tasks share the DB with memory (ADR-0003) — an additive schema.
db_path = data_dir / "jarvis.db"
store = TaskStore(db_path)
await store.init()
# Crash recovery: all running -> interrupted, plus an error log entry.
recovered = await store.cleanup_interrupted()
if recovered:
logger.info(
"TaskStack: cleaned up {} interrupted tasks from the previous run",
recovered,
)
retired = await store.retire_catalogue_tasks()
if retired:
logger.info(
"TaskStack: cancelled {} schedules from the retired automations catalogue",
retired,
)
# Wire the brain so agentic (`agent`) tasks can run a tool-restricted
# turn unattended. app.state.brain is set before server.start() (see
# launcher.py); a headless Mock-Brain without run_task falls back to
# None → agent tasks fail cleanly instead of crashing.
brain = getattr(self.app.state, "brain", None)
agent_brain = brain if (brain is not None and hasattr(brain, "run_task")) else None
# Unattended pre-authorization: agent tasks whose plugins were toggled
# write/full auto-approve those ask-tier calls for their own turn.
auto_approver = TaskAutoApprover(self.bus)
# Harness dispatch (deep-dive 2026-07-15, H-02): the UI offers
# scheduled Computer-Use actions (taskSpec.ts thenKind "computer_use"
# -> harness_dispatch), but this runner shipped without a
# HarnessManager, so every such task failed at runtime with
# "HarnessManager not configured". The manager is cheap to construct
# (entry-point class scan; instances build lazily on first dispatch).
from dodaios.harness.manager import HarnessManager
def workflow_services():
return (
getattr(self.app.state, "workflow_store", None),
getattr(self.app.state, "workflow_runner", None),
)
runner = TaskRunner(
store=store,
bus=self.bus,
harness_manager=HarnessManager(bus=self.bus),
agent_brain=agent_brain,
auto_approver=auto_approver,
result_sink=self._society_routine_result,
owned_agent_runner=self._run_society_routine,
owned_action_guard=self._guard_society_routine_action,
workflow_services=workflow_services,
)
scheduler = TaskScheduler(
store=store, bus=self.bus, runner=runner, workflow_services=workflow_services,
)
scheduler.attach_owner_gate(self._society_owner_retired)
scheduler.bind_bus()
await scheduler.hydrate()
cancel_token = CancelToken()
scheduler_task = asyncio.create_task(
scheduler.run(cancel_token), name="task-scheduler-loop"
)
self._task_store = store
self._task_runner = runner
self._task_scheduler = scheduler
self._task_cancel_token = cancel_token
self._task_scheduler_task = scheduler_task
# Routes read from app.state — see tasks_routes.py:28
self.app.state.task_store = store
self.app.state.task_scheduler = scheduler
self.app.state.task_runner = runner
logger.info(
"TaskStack live (db={}, recovered={}, hydrated={} scheduled)",
db_path,
recovered,
len(scheduler._heap),
)
def _read_sessions_toml_section(self) -> dict:
"""The raw ``[sessions]`` section from the config file (may be empty).
That section is NOT in the Pydantic tree (see assumption A-2 in the
Phase-7 bootstrap), hence tomllib directly.
"""
toml_path = resolve_config_path()
if not toml_path.exists():
return {}
try:
import tomllib
with toml_path.open("rb") as fh:
raw = tomllib.load(fh)
return raw.get("sessions", {}) or {}
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning(
"Could not read the [sessions] section from jarvis.toml — using defaults"
)
return {}
def _resolve_sessions_db_path(self) -> Path:
"""Absolute path to sessions.db, shared by recorder and board.
The default lives in ``cfg.memory.data_dir`` itself — the directory
every other SQLite store of this app uses (chats, missions, friends) —
so a second instance of the app (``dodaios.core.instance``, which points
``memory.data_dir`` at ``data-dev/``) keeps its sessions apart from the
default app's. An explicit relative ``[sessions].db_path`` is anchored
at the data-dir parent (the repo root, as before), an absolute one is
taken as is; neither depends on the process CWD. The shipped default
string ``"data/sessions.db"`` (present in every jarvis.toml) IS the
default and follows the data dir like an absent key.
"""
section = self._read_sessions_toml_section()
raw = section.get("db_path")
if not raw or Path(str(raw)) == Path("data/sessions.db"):
return Path(self.cfg.memory.data_dir) / "sessions.db"
db_path = Path(str(raw))
if not db_path.is_absolute():
db_path = Path(self.cfg.memory.data_dir).parent / db_path
return db_path
def _init_session_stack(self) -> None:
"""Voice-session recorder + store for the transcription view.
Bootstrap analogous to ``_init_mission_stack``, but sync — the store
uses sqlite3 + threading.Lock (see ``dodaios/sessions/store.py``).
"""
from dodaios.sessions.init import bootstrap_sessions
# Defaults match jarvis.toml [sessions] (enabled=true,
# data/sessions.db, retention 30d). User can override via TOML.
section = self._read_sessions_toml_section()
enabled = bool(section.get("enabled", True))
try:
retention_days = int(section.get("retention_days", 30))
except (TypeError, ValueError):
retention_days = 30
if not enabled:
logger.info("Voice-session recorder disabled via [sessions].enabled=false")
return
db_path = self._resolve_sessions_db_path()
db_path.parent.mkdir(parents=True, exist_ok=True)
result = bootstrap_sessions(
bus=self.bus,
db_path=db_path,
enabled=True,
retention_days=retention_days,
)
self.app.state.session_store = result["store"]
self._session_recorder = result["recorder"]
logger.info("Session recorder online (db={}, retention={}d)", db_path, retention_days)
# Spoken turns also appear in the Jarvis agent chat (Voice | Chat):
# the mirror files each completed voice turn into the newest
# jarvis-surface session without answering it. Best-effort — the
# voice path stays untouched when the chat is unavailable.
try:
from dodaios.agent_chat.voice_mirror import VoiceChatMirror
from .agent_chat_routes import _service_from_state
state = self.app.state
def _mirror_service() -> Any:
try:
return _service_from_state(state)
except Exception: # noqa: BLE001 — mirroring stays best-effort
return None
self._voice_chat_mirror = VoiceChatMirror(_mirror_service)
self._voice_chat_mirror.attach(self.bus)
except Exception as exc: # noqa: BLE001 — never break boot for the mirror
logger.debug("Voice chat mirror init failed: {}", exc)
async def _init_channel_stack(self) -> None:
"""Bootstraps FriendRegistry + ChannelManager + starts all channels.
The Friends UI works even without Telegram (FriendRegistry is always
there). TelegramChannel lands in ``start_errors`` when the token is
missing, without blocking the other channels.
"""
from dodaios.channels.bootstrap import bootstrap_channels
from dodaios.channels.chat_bridge import ChannelChatBridge
# data_dir might not exist on every branch under cfg.memory;
# fall back to ./data so the code stays branch-portable.
data_dir = Path("data")
try:
mem_dir = getattr(self.cfg, "memory", None)
if mem_dir is not None and getattr(mem_dir, "data_dir", None):
data_dir = Path(mem_dir.data_dir)
except Exception: # noqa: BLE001, S110 — portable data-dir fallback
pass
data_dir.mkdir(parents=True, exist_ok=True)
friends_db = data_dir / "friends.db"
# Telegram/Discord configs from integrations.* (branch-portable via getattr)
tg_cfg = None
dc_cfg = None
integrations = getattr(self.cfg, "integrations", None)
from dodaios.core.instance import current_instance
if not current_instance().owns_ambient_duties:
# A second (dev) instance of the app must not poll the same bot
# tokens as the live one — Telegram answers a second getUpdates
# poller with 409 and both would answer the user's friends. The
# Friends registry still comes up; only the channels stay off.
logger.info(
"Friends-Stack: chat channels stay off in instance '{}' "
"(they belong to the default app)",
current_instance().name,
)
elif integrations is not None:
tg_cfg = getattr(integrations, "telegram", None)
dc_cfg = getattr(integrations, "discord", None)
manager, registry = await bootstrap_channels(
bus=self.bus,
telegram_config=tg_cfg,
discord_config=dc_cfg,
friends_db_path=friends_db,
auto_start=True,
)
self.app.state.friend_registry = registry
self.app.state.channel_manager = manager
bridge = ChannelChatBridge(bus=self.bus, manager=manager)
bridge.start()
self._channel_chat_bridge = bridge
self.app.state.channel_chat_bridge = bridge
if "telegram" in manager.started():
logger.info("Friends-Stack live: Telegram-Channel aktiv")
else:
errs = manager.start_errors().get("telegram")
if errs:
logger.info("Friends-Stack live: Telegram-Channel disabled ({})", errs)
else:
logger.info("Friends-Stack live: Telegram-Channel disabled (config off)")
async def _society_routine_result(
self,
tags: tuple[str, ...],
text: str,
status: str,
*,
details: dict[str, str] | None = None,
) -> None:
"""A routine tagged ``agent:<id>`` reports its result into that agent's
own chat (the ecosystem card promises it). Tasks never import the
society; this is the one seam. Every failure is logged, never raised
into the task. ``details`` (a skipped run's ``reason_code``,
``provider`` and ``routine``) ride along on the notice so the chat
words the reason in the reader's language."""
from dodaios.society.routines import agent_id_from_tags
from dodaios.society.runtime import current_runtime
agent_id = agent_id_from_tags(tags)
if agent_id is None:
return
try:
runtime = current_runtime()
if runtime is None:
factory = getattr(self.app.state, "society_factory", None)
if factory is None:
return
runtime = self.app.state.society or factory()
self.app.state.society = runtime
await runtime.ensure_started()
agent = await runtime.roster.get(agent_id)
if agent is None:
logger.info("routine result for unknown society agent {}", agent_id)
return
await runtime.post_chat_notice(
agent,
{
"kind": "society_result",
"status": status,
"text": text[:4000],
"agent_id": agent.agent_id,
"agent_name": agent.name,
"source": "routine",
**{key: str(value)[:200] for key, value in (details or {}).items()},
},
)
except Exception: # noqa: BLE001 — the task already recorded its result; delivery is best effort
logger.warning("society: routine result not delivered to {}", agent_id, exc_info=True)
async def _society_owner_retired(self, tags: tuple[str, ...]) -> bool:
"""Whether a task belongs to a retired (archived) society agent."""
from dodaios.society.routines import agent_id_from_tags
from dodaios.society.runtime import current_runtime
agent_id = agent_id_from_tags(tags)
if agent_id is None:
return False
runtime = current_runtime()
if runtime is None:
runtime = self._build_society_runtime()
self.app.state.society = runtime
await runtime.ensure_started()
agent = await runtime.roster.get(agent_id)
return agent is not None and str(agent.state) == "archived"
async def _guard_society_routine_action(self, tags: tuple[str, ...]) -> None:
from dodaios.society.routine_runner import guard_owned_routine
from dodaios.society.runtime import current_runtime
runtime = current_runtime()
if runtime is None:
runtime = self._build_society_runtime()
self.app.state.society = runtime
await runtime.ensure_started()
await guard_owned_routine(runtime, tags)
async def _run_society_routine(
self, task_id: str, tags: tuple[str, ...], prompt: str, cancel: Any
) -> str | None:
from dodaios.society.routine_runner import run_owned_routine
from dodaios.society.routines import agent_id_from_tags
from dodaios.society.runtime import current_runtime
if agent_id_from_tags(tags) is None:
return None
runtime = current_runtime()
if runtime is None:
runtime = self._build_society_runtime()
self.app.state.society = runtime
await runtime.ensure_started()
return await run_owned_routine(runtime, task_id, tags, prompt, cancel)
def _build_society_runtime(self) -> Any:
"""Build the agent-society runtime on first use (see society_routes).
Every collaborator is a getter over ``app.state`` so the runtime
follows the live mission manager, budget tracker, brain tool surface
and skill registry — whichever of them exists at call time.
"""
from dodaios.society.runtime import SocietyRuntime, SocietyRuntimeClosed
state = self.app.state
if getattr(state, "society_stopping", False):
raise SocietyRuntimeClosed("society runtime stopped")
data_dir = Path(getattr(getattr(self.cfg, "memory", None), "data_dir", None) or "data")
if getattr(state, "society", None) is not None:
return state.society
def _manager() -> Any | None:
return getattr(state, "mission_manager", None)
def _mission_bus() -> Any | None:
manager = getattr(state, "mission_manager", None)
return getattr(manager, "bus", None) if manager is not None else None
def _budget() -> Any | None:
return getattr(state, "missions_budget", None)
def _tools() -> Any | None:
brain = getattr(state, "brain", None)
tools = getattr(brain, "_tools", None)
return tools if tools is not None and hasattr(tools, "items") else None
def _skills() -> Any | None:
registry = getattr(state, "skill_registry", None)
if registry is None:
return None
lister = getattr(registry, "all", None) or getattr(registry, "list", None)
try:
return list(lister()) if callable(lister) else None
except Exception: # noqa: BLE001 — the catalog then shows no skills
return None
from dodaios.society.chat_binding import make_deliver_hook
from .agent_chat_routes import _service_from_state
# Board messages addressed to an agent wake its canonical chat on the
# agent-chat service (built lazily by its own factory).
deliver = make_deliver_hook(
lambda: _service_from_state(state),
lambda: self.cfg,
)
def _society_plugin_state() -> tuple[list[str], set[str]]:
from dodaios.marketplace.catalog_data import load_catalog
from dodaios.marketplace.connect_helpers import usable_plugin_ids
return [spec.id for spec in load_catalog().plugins], usable_plugin_ids()
state.society = SocietyRuntime(
data_dir,
mission_manager=_manager,
mission_bus=_mission_bus,
budget_tracker=_budget,
brain_tools=_tools,
skills=_skills,
deliver=deliver,
chat_service=lambda: _service_from_state(state),
cfg=lambda: self.cfg,
# The island learns of a figure's new place through the app bus the
# WebSocket forwards (SocietyCheckpointChanged).
plugin_state=_society_plugin_state,
event_publish=self.bus.publish,
app_bus=self.bus,
task_services=lambda: (
getattr(state, "task_store", None), getattr(state, "task_scheduler", None)
),
)
def browser_brain(agent: Any) -> Any:
from dodaios.agent_chat.browser_model import browser_model_for_agent
return browser_model_for_agent(self.cfg, agent)
state.society.browser.live.model_resolver = browser_brain
state.society.browser.live.executor = lambda: getattr(
getattr(state, "brain", None), "_tool_executor", None
)
return state.society
def _build_agent_chat_service(self) -> Any:
"""Build the agent-chat service on first use (see agent_chat_routes)."""
from dodaios.agent_chat.service import AgentChatService
from dodaios.agent_chat.store import AgentChatStore
from dodaios.brain.assistant_name import DEFAULT_ASSISTANT_NAME, resolve_assistant_name
data_dir = Path(getattr(getattr(self.cfg, "memory", None), "data_dir", None) or "data")
store = AgentChatStore(data_dir / "agent_chat.db")
def _name() -> str:
try:
return resolve_assistant_name(self.cfg)
except Exception: # noqa: BLE001 — the name is cosmetic
return DEFAULT_ASSISTANT_NAME
from dodaios.core.events import DelegationResultReady
# Install on first chat use, keeping result tracking off the boot path.
self.bus.unsubscribe(DelegationResultReady, self._forward_delegation_to_chat)
self.bus.subscribe(DelegationResultReady, self._forward_delegation_to_chat)
service = AgentChatService(store, assistant_name=_name, bus=lambda: self.bus)
# "Needs you" list and notifier: one event listener, nothing on boot.
from dodaios.agent_chat.attention import install as install_attention
install_attention(
service,
publish=self.bus.publish,
society=lambda: getattr(self.app.state, "society", None),
)
return service
def _schedule_registry_bootstraps(self) -> None:
"""Start registry discovery after composition without delaying readiness."""
async def bootstrap(registry: Any, label: str) -> None:
try:
await registry.bootstrap()
except Exception as exc: # noqa: BLE001 -- other registries remain usable
logger.opt(exception=exc).warning("{} registry bootstrap failed", label)
for registry, attribute, label in (
(self._cli_registry, "_cli_bootstrap_task", "cli"),
(self._plugin_registry, "_plugin_bootstrap_task", "plugin"),
):
existing = getattr(self, attribute, None)
if registry is not None and (existing is None or existing.done()):
setattr(self, attribute, asyncio.create_task(
bootstrap(registry, label), name=f"{label}-registry-bootstrap",
))
async def _stop_registry_bootstraps(self) -> bool:
"""Cancel both owners before awaiting either one's resource cleanup."""
owners = {
attribute: task
for attribute in ("_cli_bootstrap_task", "_plugin_bootstrap_task")
if (task := getattr(self, attribute, None)) is not None
}
for task in owners.values():
if not task.done() and not task.cancelling():
task.cancel()
if not owners:
return True
done, pending = await asyncio.wait(
set(owners.values()), timeout=_REGISTRY_BOOTSTRAP_STOP_TIMEOUT_S,
)
for attribute, task in owners.items():
if task in done:
if not task.cancelled() and (error := task.exception()) is not None:
logger.warning("Registry bootstrap stopped with {}", type(error).__name__)
setattr(self, attribute, None)
if pending:
logger.warning("{} registry bootstrap owner(s) still stopping", len(pending))
return not pending
async def stop(self) -> None:
from dodaios.core import runtime_refs
appshot_task = getattr(self, "_appshot_shortcut_task", None)
if appshot_task is not None:
appshot_task.cancel()
await asyncio.gather(appshot_task, return_exceptions=True)
self._appshot_shortcut_task = None
try:
from dodaios.appshot.hotkey import stop_appshot_shortcut
await stop_appshot_shortcut()
except Exception:
logger.opt(exception=True).warning("Appshot helpers failed to stop")
# Ask a running Verse to save and quit (lifecycle.quit app_quit) and
# delete the dev discovery file that holds a token.
try:
from .verse_routes import stop_verse_host
await stop_verse_host(self.app)
except Exception: # noqa: BLE001 -- independent resources must still shut down
logger.opt(exception=True).warning("Verse host stop failed")
if runtime_refs.get_web_app() is self.app:
runtime_refs.set_web_app(None)
# A cancelled setup waiter cannot stop its worker thread. Join it
# before closing board/stores/subscriptions that it may still create.
try:
await self._feature_setup.stop()
except Exception as exc: # noqa: BLE001 -- close partial setup too
logger.opt(exception=exc).warning("Application feature setup failed during shutdown")
# Fence lazy creation even when no Society owner exists yet. The shared
# brain factory and HTTP surface can still be called while shutdown awaits.
self.app.state.society_stopping = True
from .mars_routes import stop_mars_station
# Fence station creation before any other shutdown await can interleave
# with a pending boot recovery or first HTTP request.
mars_shutdown_failure: str | None = None
try:
await stop_mars_station(self.app.state)
except Exception as exc: # noqa: BLE001 -- independent resources must still shut down
# The helper retains its stop latch and pending owner references.
# Keep only the type: cleanup failures can contain private payloads.
mars_shutdown_failure = type(exc).__name__
logger.warning("Mars station cleanup incomplete ({})", mars_shutdown_failure)
registry_bootstraps_stopped = await self._stop_registry_bootstraps()
# A short-lived server can stop before these delayed boot helpers run.
# Own and drain them here instead of leaving asyncio.run()/pytest to
# discover them during loop teardown. Stop the deferred registry reload
# before its registries are closed below so shutdown cannot race a scan.
for attr in ("_anyio_pool_warm_task", "_deferred_reload_task"):
task = getattr(self, attr, None)
setattr(self, attr, None)
if task is not None and not task.done():
task.cancel()
await asyncio.gather(task, return_exceptions=True)
society = getattr(self.app.state, "society", None)
society_shutdown_failure: str | None = None
if society is not None:
try:
# The runtime owns delivery tasks, subscriptions and SQLite as
# well as the browser. Leaving its store open prevents exit.
await asyncio.wait_for(society.close(), timeout=_SOCIETY_SHUTDOWN_TIMEOUT_S)
except Exception as exc: # noqa: BLE001 -- finish independent cleanup below
society_shutdown_failure = type(exc).__name__
logger.warning("Society runtime cleanup incomplete ({})", society_shutdown_failure)
self._mic_level_sessions.clear()
self._stop_mic_level_bridge()
try:
from dodaios.memory.learning.loop import stop_learning
await stop_learning()
except Exception as exc: # noqa: BLE001 -- finish independent cleanup below
logger.opt(exception=exc).debug("Learning loop stop failed")
team_threads = getattr(self.app.state, "team_threads", None)
if team_threads is not None:
# Before the chat turns end: a coordinator that sees its members'
# turns cancelled under it would read that as members failing.
try:
await team_threads.close()
except Exception as exc: # noqa: BLE001 -- finish independent cleanup below
logger.opt(exception=exc).debug("team threads close failed")
agent_chat = getattr(self.app.state, "agent_chat", None)
if agent_chat is not None:
try:
await agent_chat.cancel_all()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("agent chat cancel_all failed")
# Stop token refresh before the plugin registry so an in-flight refresh
# cannot enqueue a live-session rebuild while that registry is closing.
await self._stop_marketplace_refresh_scheduler()
await self._stop_local_models_health_monitor()
await self._stop_local_models_autostart()
# Stop the skill watcher, otherwise the watchdog thread stays behind
# as a zombie and prevents the process from exiting.
if self._skill_registry is not None:
try:
self._skill_registry.stop_watcher()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("SkillRegistry watcher stop failed")
# Close the doc watcher + FTS5 connection.
if self._doc_registry is not None:
try:
self._doc_registry.close()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("DocRegistry close failed")
# Unset the shared CLI registry — otherwise the module singleton keeps
# a reference to a "dead" registry when the server restarts.
try:
from dodaios.clis.shared import set_active_registry
set_active_registry(None)
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("CLI shared-registry cleanup failed: {}", exc)
# Symmetric teardown for the plugin registry: unset the module singleton
# AND stop the registry so each connected plugin's MCPClient (with its
# AsyncExitStack / subprocess) is closed cleanly. Without this, an
# in-process restart (--no-lock parallel dev, test teardown) would leave
# a stale shared handle and leaked MCP sessions.
# A timed-out bootstrap may still hold the registry lock while cleaning
# up. Keep both references for a later stop attempt; closing it now can
# block indefinitely on that same lock.
if (
self._plugin_registry is not None
and getattr(self, "_plugin_bootstrap_task", None) is None
):
try:
from dodaios.marketplace.plugin_shared import set_active_plugin_registry
set_active_plugin_registry(None)
await self._plugin_registry.stop()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("PluginToolRegistry cleanup failed: {}", exc)
self._plugin_registry = None
self.app.state.plugin_registry = None
# Cleanly stop the board-aggregator task before uvicorn goes down. The
# run_forever() loop catches CancelledError itself and re-raises it.
if self._board_aggregator_task is not None:
self._board_aggregator_task.cancel()
try:
await asyncio.wait_for(self._board_aggregator_task, timeout=2.0)
except (TimeoutError, asyncio.CancelledError):
pass
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("Board-aggregator shutdown error")
self._board_aggregator_task = None
# Voice-ready backstop watchdog: usually already finished (it fires once
# and returns), but cancel it if a shutdown lands inside its deadline so
# it is never orphaned as a pending task at loop close.
_watchdog_task = getattr(self, "_voice_ready_watchdog_task", None)
if _watchdog_task is not None:
_watchdog_task.cancel()
try:
await asyncio.wait_for(_watchdog_task, timeout=2.0)
except (TimeoutError, asyncio.CancelledError):
pass
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("voice-ready watchdog shutdown: {}", exc)
self._voice_ready_watchdog_task = None
# Realtime transport warm: usually finished long before a shutdown, but
# a stop inside its boot delay must not orphan it at loop close.
_warm_task = self._realtime_warm_task
self._realtime_warm_task = None
if _warm_task is not None and not _warm_task.done():
_warm_task.cancel()
try:
await asyncio.wait_for(_warm_task, timeout=2.0)
except (TimeoutError, asyncio.CancelledError):
pass
except Exception as exc: # noqa: BLE001 -- shutdown stays best-effort
logger.opt(exception=exc).debug("Realtime transport warm shutdown: {}", exc)
if self._bio_scheduler is not None:
try:
await self._bio_scheduler.stop()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("BioScheduler.stop(): {}", exc)
progression = getattr(self, "_progression", None)
if progression is not None:
try:
progression.close()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("ProgressionService.close(): {}", exc)
if self._board_evaluator is not None:
try:
self._board_evaluator.close()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("AchievementEvaluator.close(): {}", exc)
if self._board_aggregator is not None:
try:
self._board_aggregator.close()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("Board-Aggregator close(): {}", exc)
# Phase B5 wiki write-wiring: unsubscribe + drain in-flight rollup task.
wiki_handle = getattr(self, "_wiki_integration_handle", None)
if wiki_handle is not None:
try:
await wiki_handle.shutdown()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("WikiIntegration.shutdown() failed")
self._wiki_integration_handle = None
# Phase B3 wiki live-reload: stop the watchdog observer cleanly
# before uvicorn unwinds. The bus is still alive at this point
# so any final debounce-fired events can publish without raising.
wiki_watcher = getattr(self, "_wiki_watcher", None)
if wiki_watcher is not None:
try:
await wiki_watcher.shutdown()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("WikiWatcher.shutdown() failed")
self._wiki_watcher = None
# Terminate PTY sessions before uvicorn goes down — prevents reader
# threads from trying to write into a closed loop.
try:
self._pty.close_all()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("PTY cleanup failed")
# Cleanly shut down the Phase-6 mission stack — closing the
# connection closes the SQLite DB. Cancel the periodic recovery
# re-sweep + cleanup task BEFORE the store closes (otherwise the
# re-sweep ticks against a closed connection).
resweep_task = getattr(self, "_missions_resweep_task", None)
if resweep_task is not None:
resweep_task.cancel()
try:
await asyncio.wait_for(resweep_task, timeout=2.0)
except (TimeoutError, asyncio.CancelledError):
pass
self._missions_resweep_task = None
# The resume timer stops here; a mission it already resumed runs in its
# own task and is finalized by cancel_all_running below.
resume_task = getattr(self, "_missions_resume_task", None)
if resume_task is not None:
resume_task.cancel()
try:
await asyncio.wait_for(resume_task, timeout=2.0)
except (TimeoutError, asyncio.CancelledError): # expected while stopping the timer
pass
self._missions_resume_task = None
cleanup_task = getattr(self, "_missions_cleanup_task", None)
if cleanup_task is not None:
cleanup_task.cancel()
try:
await asyncio.wait_for(cleanup_task, timeout=2.0)
except (TimeoutError, asyncio.CancelledError):
pass
self._missions_cleanup_task = None
# Screenshot-retention background task (opt-in via retention_days > 0).
screenshot_task = getattr(self, "_screenshot_retention_task", None)
if screenshot_task is not None:
screenshot_task.cancel()
try:
await asyncio.wait_for(screenshot_task, timeout=2.0)
except asyncio.CancelledError:
pass
except TimeoutError:
logger.warning("retention_task: did not stop within 2s — may be blocking on I/O")
self._screenshot_retention_task = None
# Flush + close the flight-recorder audit log so the last buffered events
# reach disk before shutdown (it otherwise auto-flushes every ~1s).
recorder = getattr(self, "_flight_recorder", None)
if recorder is not None:
try:
await recorder.flush()
await recorder.close()
except Exception as exc: # noqa: BLE001 — shutdown best-effort
logger.opt(exception=exc).debug("Flight recorder close: {}", exc)
self._flight_recorder = None
# Finalize in-flight missions BEFORE the store closes: a restart used
# to kill the process with missions still running, leaving them
# non-terminal until the recovery re-sweep buried them 30 min later as
# opaque crash_recovery/ERROR cards (live missions 019eb27f/019eb288,
# 2026-06-10 19:24). cancel_all_running flips each to an honest
# CANCELLED('app_shutdown') and awaits the dying run tasks briefly.
kontrollierer = getattr(self.app.state, "kontrollierer", None)
cancel_all = getattr(kontrollierer, "cancel_all_running", None)
if cancel_all is not None:
try:
await cancel_all(reason="app_shutdown")
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("In-flight mission finalize on shutdown failed")
try:
await self._mission_tool_approvals.deny_all(reason="app_shutdown")
except Exception as exc: # noqa: BLE001 - shutdown remains best-effort
logger.opt(exception=exc).warning("Pending mission tool approval cleanup failed")
mission_manager = getattr(self.app.state, "mission_manager", None)
if mission_manager is not None:
try:
await mission_manager.stop()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("MissionManager.stop() failed")
self.app.state.mission_manager = None
self.app.state.kontrollierer = None
# Shut down the Phase-5 task stack: cancel the scheduler loop, wait
# for running runner tasks (max 2s), close the store.
if self._task_scheduler is not None and self._task_cancel_token is not None:
try:
self._task_cancel_token.cancel("server_shutdown")
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("Task-CancelToken.cancel(): {}", exc)
if self._task_scheduler_task is not None:
self._task_scheduler_task.cancel()
try:
await asyncio.wait_for(self._task_scheduler_task, timeout=2.0)
except (TimeoutError, asyncio.CancelledError):
pass
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("TaskScheduler loop shutdown error: {}", exc)
self._task_scheduler_task = None
if self._task_scheduler is not None:
try:
await self._task_scheduler.shutdown()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).debug("TaskScheduler.shutdown(): {}", exc)
if self._task_store is not None:
try:
await self._task_store.close()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("TaskStore.close() failed")
self._task_scheduler = None
self._task_store = None
self._task_runner = None
self._task_cancel_token = None
self.app.state.task_store = None
self.app.state.task_scheduler = None
self.app.state.task_runner = None
# Detach the voice-session recorder from the bus + close the DB connection.
recorder = getattr(self, "_session_recorder", None)
store = getattr(self.app.state, "session_store", None)
if recorder is not None or store is not None:
try:
from dodaios.sessions.init import shutdown_sessions
shutdown_sessions({"store": store, "recorder": recorder})
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("SessionRecorder shutdown failed")
self._session_recorder = None
self.app.state.session_store = None
channel_manager = getattr(self.app.state, "channel_manager", None)
friend_registry = getattr(self.app.state, "friend_registry", None)
channel_bridge = getattr(self, "_channel_chat_bridge", None)
if channel_bridge is not None:
try:
await channel_bridge.stop()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("ChannelChatBridge shutdown failed")
self._channel_chat_bridge = None
self.app.state.channel_chat_bridge = None
if channel_manager is not None or friend_registry is not None:
try:
from dodaios.channels.bootstrap import shutdown_channels
if channel_manager is not None and friend_registry is not None:
await shutdown_channels(channel_manager, friend_registry)
elif channel_manager is not None:
await channel_manager.stop_all()
elif friend_registry is not None:
await friend_registry.close()
except Exception as exc: # noqa: BLE001
logger.opt(exception=exc).warning("ChannelStack shutdown failed")
self.app.state.channel_manager = None
self.app.state.friend_registry = None
if self._server is not None:
self._server.should_exit = True
if self._serve_task is not None:
try:
await asyncio.wait_for(self._serve_task, timeout=5.0)
except TimeoutError:
logger.warning("uvicorn shutdown timeout — force-cancel")
self._serve_task.cancel()
self._server = None
self._serve_task = None
# A recall store nobody closed keeps a non-daemon aiosqlite thread, and
# the process could not exit until systemd killed it (BC-250 2026-10-29).
try:
from dodaios.memory.recall import close_open_recall_stores
closed = await close_open_recall_stores()
if closed:
logger.info("Closed {} recall store(s) left open", closed)
except Exception as exc: # noqa: BLE001 - shutdown continues best-effort
logger.opt(exception=exc).warning("Recall store cleanup failed")
# Browser/desktop realtime owners must release their ephemeral threads
# before their shared process is reaped. Keep this unconditional: a
# failed startup can complete the Codex handshake before uvicorn marks
# itself running, and that process still needs bounded teardown.
try:
from dodaios.codex_app_server import close_shared_codex_app_servers
await close_shared_codex_app_servers()
except Exception as exc: # noqa: BLE001 - shutdown continues best-effort
logger.opt(exception=exc).warning("Codex subscription app-server cleanup failed")
if mars_shutdown_failure is not None:
# Report incomplete Mars cleanup only after unrelated browser, chat,
# plugin, watcher, terminal and server resources have been released.
raise RuntimeError(f"mars_station_shutdown_incomplete ({mars_shutdown_failure})")
if society_shutdown_failure is not None:
raise RuntimeError(f"society_runtime_shutdown_incomplete ({society_shutdown_failure})")
if not registry_bootstraps_stopped:
raise RuntimeError("registry_bootstrap_shutdown_incomplete")
@property
def running(self) -> bool:
return self._server is not None and self._server.started