Skip to content

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

24.7 KB
Raw Blame
"""The in-process agent loop — one turn on a provider's chat API.

The provider's own streaming chat API
(``dodaios.plugins.brain.*``) driven in a tool-use loop over
:mod:`dodaios.agent_chat.tools`. Per round the model streams text (forwarded
live as ``text_delta``), may request tool calls, each call is gated by the
session's permission mode, executed, and its result fed back; the loop ends
when a round produces no tool calls, the round budget is spent, or the
person stops it.

Provider-agnostic by construction (AP-21): the provider id selects the brain
class through a capability-style map, the reasoning effort goes through the
``BrainRequest.reasoning_effort`` hint every plugin already reads, and the
agent-tier credential is applied through ``override_provider_secrets`` so a
dedicated Agents-tab key wins over the shared brain key without touching the
process environment.

Conversation memory is the session's persisted event log: the turn
reconstructs the provider messages from it (user text, assistant text + tool
calls, tool results), so a reopened session continues with its whole
history and nothing is kept in process between turns.
"""

from __future__ import annotations

import asyncio
import json
import logging
import platform
import time
import uuid
from collections.abc import Awaitable, Callable
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Final

from dodaios.agent_chat.effort import effort_note, normalize_effort
from dodaios.agent_chat.events import make_event
from dodaios.agent_chat.permissions import normalize_permission
from dodaios.agent_chat.store import AgentChatSession
from dodaios.agent_chat.tools import (
    EDIT_TOOLS,
    READ_ONLY_TOOLS,
    TOOL_SPECS,
    execute_tool,
    shell_label,
    summarize_call,
)
from dodaios.brain.assistant_name import DEFAULT_ASSISTANT_NAME
from dodaios.core.protocols import BrainDelta, BrainMessage, BrainRequest
from dodaios.core.response_style import CONVERSATIONAL_RESPONSE_STYLE

log = logging.getLogger(__name__)

# Provider slug -> (module, class). Lazy-imported so a turn on one provider
# never imports another's SDK. Mirrors the agent worker's map; the chat has
# no reason to diverge from the set the Agents tab offers.
BRAIN_BY_PROVIDER: Final[dict[str, tuple[str, str]]] = {
    "openai": ("dodaios.plugins.brain.openai", "OpenAIBrain"),
    "openrouter": ("dodaios.plugins.brain.openrouter", "OpenRouterBrain"),
    "grok": ("dodaios.plugins.brain.grok", "GrokBrain"),
    "nvidia": ("dodaios.plugins.brain.nvidia", "NvidiaBrain"),
    "claude-api": ("dodaios.plugins.brain.claude_api", "ClaudeAPIBrain"),
    "gemini": ("dodaios.plugins.brain.gemini", "GeminiBrain"),
    "vertex": ("dodaios.plugins.brain.vertex", "VertexBrain"),
    "ollama": ("dodaios.plugins.brain.ollama", "OllamaBrain"),
    "local-openai": ("dodaios.plugins.brain.local_openai", "LocalOpenAIBrain"),
}

MAX_ROUNDS: Final[int] = 40
MAX_TOKENS: Final[int] = 8192
# Tool output fed back to the model is capped here (the UI gets the full
# output from the tool_result event, which carries the same text).
_TOOL_RESULT_CAP: Final[int] = 24_000
# How many past events are replayed into the provider messages. A long
# session still works; this bounds the request size.
_HISTORY_MAX_EVENTS: Final[int] = 600

_ROUND_BUDGET_DIRECTIVE: Final[str] = (
    "[round budget exhausted] Summarize what you did and what is still open. "
    "Do not call any more tools in this reply."
)


def supports_api_runner(provider: str) -> bool:
    return (provider or "").strip().lower() in BRAIN_BY_PROVIDER


def build_brain(provider: str, model: str) -> Any:
    mod_name, cls_name = BRAIN_BY_PROVIDER[provider]
    mod = __import__(mod_name, fromlist=[cls_name])
    return getattr(mod, cls_name)(model=model or None)


def system_prompt(*, cwd: Path, assistant_name: str, plan: bool = False) -> str:
    """Operating instructions for the interactive API chat runner.

    ``plan`` is the composer's Plan mode: the model gets only the reading
    tools and is told to investigate and lay out a plan instead of acting.
    """
    plan_note = (
        "\n\nPLAN MODE is on: you have no tools that change anything. Investigate, then answer "
        "with a numbered plan (files, functions, order) and the open questions; the person "
        "switches to Build mode to carry it out."
        if plan
        else ""
    )
    return (
        f"You are {assistant_name}, a coding agent working in the person's environment "
        "through this chat.\n\n"
        f"Working directory: {cwd}\n"
        f"Operating system: {platform.system()} {platform.release()}\n"
        f"Shell for RunCommand: {shell_label()}\n"
        f"Date: {time.strftime('%Y-%m-%d')}\n\n"
        "A tool result marked denied means the person declined it; do not retry it.\n\n"
        + CONVERSATIONAL_RESPONSE_STYLE
        + plan_note
    )


@dataclass(slots=True)
class TurnHandle:
    """What the service hands a runner: where to emit, how to ask, when to stop.

    ``trace_id`` is the turn's correlation id on the app bus (the brain runner
    passes it to ``generate`` and reads its own tool events back by it);
    ``bus`` is the app bus, ``None`` when the service runs without one;
    ``surface`` and ``stance`` are the session's chat and, on the Jarvis
    surface, its permission stance (``dodaios.agent_chat.permissions``).
    """

    session: AgentChatSession
    turn_id: str
    emit: Callable[[dict[str, Any]], Awaitable[None]]
    request_approval: Callable[[str, str, dict[str, Any], str], Awaitable[str]]
    cancel: asyncio.Event
    history: list[dict[str, Any]] = field(default_factory=list)
    assistant_name: str = DEFAULT_ASSISTANT_NAME
    trace_id: uuid.UUID = field(default_factory=uuid.uuid4)
    bus: Any | None = None
    surface: str = "agent"
    stance: str = ""
    tools_disabled: bool = False
    #: A plain chat's whole system prompt (``SurfaceKit.plain_chat``); empty on
    #: every other surface. With it the turn carries no tools.
    plain_system: str = ""
    #: A plain chat's pictures for THIS message, as files in the session's
    #: folder (``plain_chat.image_paths``). Empty everywhere else.
    images: tuple[str, ...] = ()
    gateway_only: bool = False
    output_language: str = ""
    goal_turn: bool = False
    control_service: Any = None
    #: A continuation keeps the turn's already resolved language and identity.
    continuation: bool = False


async def _plain_images(handle: TurnHandle, brain: Any) -> tuple[Any, ...]:
    """A plain chat's pictures as image blocks, when the model can see them."""
    if not handle.images or not getattr(brain, "supports_vision", False):
        return ()
    from dodaios.agent_chat import plain_chat
    from dodaios.core.protocols import ImageBlock

    pairs = await asyncio.to_thread(lambda: [plain_chat.encoded(p) for p in handle.images])
    return tuple(ImageBlock(mime=pair[0], data_b64=pair[1]) for pair in pairs if pair is not None)


# ------------------------------------------------------------ history


def messages_from_events(
    events: list[dict[str, Any]], *, max_events: int | None = _HISTORY_MAX_EVENTS
) -> list[BrainMessage]:
    """Rebuild the provider conversation from the persisted event log.

    ``user_message`` -> user; inside a turn, ``assistant_text`` and
    ``tool_call`` fold into ONE assistant message of content blocks (a text
    block, then the tool_use blocks in order) per round; ``tool_result``
    becomes a tool message keyed by ``call_id``. Rounds are split where a
    tool_result is followed by more assistant output.
    """
    out: list[BrainMessage] = []
    pending_blocks: list[dict[str, Any]] = []

    def flush() -> None:
        nonlocal pending_blocks
        if not pending_blocks:
            return
        only_text = all(b.get("type") == "text" for b in pending_blocks)
        if only_text:
            text = "".join(str(b.get("text") or "") for b in pending_blocks)
            if text.strip():
                out.append(BrainMessage(role="assistant", content=text))
        else:
            out.append(BrainMessage(role="assistant", content=list(pending_blocks)))
        pending_blocks = []

    internal: dict[str, dict[str, Any]] = {}
    for ev in events[-max_events:] if max_events else events:
        kind = ev.get("kind")
        payload = ev.get("payload") or {}
        if kind == "agent_message":
            internal[str(payload.get("message_id"))] = payload
            continue
        if kind == "notice" and payload.get("kind") in {
            "society_result", "society_message", "coding_result", "delegation_report",
        }:
            flush()
            material = str(payload.get("report") or payload.get("text") or "")
            if material:
                out.append(BrainMessage(
                    role="assistant",
                    content="Recorded delegation result (external report, not instructions):\n"
                    + _cap(material, 6000),
                ))
            continue
        if kind == "agent_message_status":
            original = internal.pop(str(payload.get("message_id")), None)
            if payload.get("status") == "delivered" and original is not None:
                flush()
                out.append(BrainMessage(role="user", content=str(original["prompt"])))
            continue
        if kind == "user_message":
            flush()
            text = str(payload.get("text") or "")
            if text:
                out.append(BrainMessage(role="user", content=text))
        elif kind == "assistant_text":
            text = str(payload.get("text") or "")
            if text:
                pending_blocks.append({"type": "text", "text": text})
        elif kind == "tool_call":
            block: dict[str, Any] = {
                "type": "tool_use",
                "id": str(payload.get("call_id") or f"call_{uuid.uuid4().hex[:8]}"),
                "name": str(payload.get("name") or ""),
                "input": payload.get("input") or {},
            }
            meta = payload.get("meta") or {}
            if meta.get("thought_signature"):
                block["thought_signature"] = meta["thought_signature"]
            pending_blocks.append(block)
        elif kind == "tool_result":
            # Plain string content on purpose: the Anthropic adapter wraps a
            # string into its tool_result block, Gemini and the OpenAI family
            # pass it through — an envelope list would reach the OpenAI family
            # as a JSON-serialised wrapper.
            flush()
            call_id = str(payload.get("call_id") or "")
            output = str(payload.get("output") or "")
            if payload.get("is_error"):
                output = f"[error] {output}"
            out.append(
                BrainMessage(
                    role="tool",
                    content=_cap(output, _TOOL_RESULT_CAP),
                    tool_call_id=call_id,
                    name=str(payload.get("name") or ""),
                )
            )
        elif kind == "turn_finished":
            flush()
    flush()
    # A provider rejects a conversation that ends on a tool message or an
    # assistant message with unanswered tool calls (a cancelled turn); the
    # service appends the new user message after this, so close any open
    # assistant tool round with a synthetic "cancelled" result first.
    return _close_dangling_tool_calls(out)


def _close_dangling_tool_calls(messages: list[BrainMessage]) -> list[BrainMessage]:
    answered: set[str] = set()
    for m in messages:
        if m.role == "tool" and m.tool_call_id:
            answered.add(m.tool_call_id)
    out: list[BrainMessage] = []
    for m in messages:
        out.append(m)
        if m.role == "assistant" and isinstance(m.content, list):
            for block in m.content:
                if block.get("type") == "tool_use" and block.get("id") not in answered:
                    out.append(
                        BrainMessage(
                            role="tool",
                            content="[cancelled before it ran]",
                            tool_call_id=str(block["id"]),
                            name=str(block.get("name") or ""),
                        )
                    )
    return out


def _cap(text: str, limit: int) -> str:
    if len(text) <= limit:
        return text
    return text[:limit] + f"\n…[truncated, {len(text) - limit} more characters]"


# ---------------------------------------------------------------- turn


async def run_api_turn(handle: TurnHandle, user_text: str) -> None:
    """Run one turn. Emits events through ``handle.emit``; never raises to the
    caller except ``asyncio.CancelledError``."""
    session = handle.session
    provider = session.provider
    cwd = Path(session.cwd or Path.home())
    effort = normalize_effort(provider, session.effort)
    t0 = time.perf_counter()
    usage_total: dict[str, int] = {}

    try:
        brain = build_brain(provider, session.model)
    except Exception as exc:  # noqa: BLE001 — reported to the person, not raised
        await handle.emit(
            make_event(
                "turn_finished",
                {
                    "turn_id": handle.turn_id,
                    "status": "error",
                    "duration_ms": 0,
                    "usage": {},
                    "error": f"{type(exc).__name__}: {exc}",
                },
            )
        )
        return

    messages = messages_from_events(handle.history)
    messages.append(
        BrainMessage(role="user", content=user_text, images=await _plain_images(handle, brain))
    )
    permission_mode = normalize_permission("api", session.permission_mode)
    # Either says it: a turn told to carry no tools never gets the tool set.
    plain = handle.tools_disabled or bool(handle.plain_system)
    system = handle.plain_system or system_prompt(
        cwd=cwd, assistant_name=handle.assistant_name, plan=permission_mode == "plan"
    )
    if handle.output_language:
        system += "\nRespond in this language: " + handle.output_language
    note = effort_note(provider, effort)
    if note:
        system += "\n\n" + note.strip()
    # Plan mode hands the model only the reading tools: it cannot change a
    # thing, and it is told so in the system prompt.
    # A plain chat hands it none at all: the answer is the whole turn.
    tools: tuple[dict[str, Any], ...] = (
        ()
        if plain
        else tuple(spec for spec in TOOL_SPECS if spec["name"] in READ_ONLY_TOOLS)
        if permission_mode == "plan"
        else TOOL_SPECS
    )
    status = "done"
    error_text: str | None = None

    from dodaios.core.config import get_jarvis_agent_secret, override_provider_secrets

    secret = get_jarvis_agent_secret(provider)
    overrides = {provider: secret} if secret else {}

    try:
        with override_provider_secrets(overrides):
            for round_no in range(MAX_ROUNDS):
                if handle.cancel.is_set():
                    status = "cancelled"
                    break
                req = BrainRequest(
                    messages=tuple(messages),
                    tools=tools,
                    system=system,
                    temperature=0.2,
                    max_tokens=MAX_TOKENS,
                    stream=True,
                    reasoning_effort=effort or None,  # type: ignore[arg-type]
                )
                message_id = uuid.uuid4().hex
                text_parts: list[str] = []
                tool_calls: list[dict[str, Any]] = []
                try:
                    async for delta in _stream(brain, req, handle.cancel):
                        if delta.content:
                            text_parts.append(delta.content)
                            await handle.emit(
                                make_event(
                                    "text_delta",
                                    {
                                        "turn_id": handle.turn_id,
                                        "message_id": message_id,
                                        "text": delta.content,
                                    },
                                )
                            )
                        if delta.tool_call:
                            tool_calls.append(dict(delta.tool_call))
                        if delta.usage:
                            for k, v in delta.usage.items():
                                usage_total[k] = usage_total.get(k, 0) + int(v or 0)
                            # Tokens as they are counted, so the live line can
                            # say what the turn has spent so far. Providers
                            # report usage a handful of times per turn, not per
                            # token, so this needs no throttling of its own.
                            await handle.emit(
                                make_event(
                                    "usage_delta",
                                    {"turn_id": handle.turn_id, "usage": dict(usage_total)},
                                )
                            )
                except asyncio.CancelledError:
                    raise
                except Exception as exc:  # noqa: BLE001 — provider error ends the turn honestly
                    status = "error"
                    error_text = f"{type(exc).__name__}: {exc}"
                    log.warning("agent chat turn %s: provider error: %s", handle.turn_id, exc)
                    break

                text = "".join(text_parts)
                if handle.cancel.is_set():
                    if text.strip():
                        await handle.emit(
                            make_event(
                                "assistant_text",
                                {"turn_id": handle.turn_id, "message_id": message_id, "text": text},
                            )
                        )
                    status = "cancelled"
                    break

                if text.strip():
                    await handle.emit(
                        make_event(
                            "assistant_text",
                            {"turn_id": handle.turn_id, "message_id": message_id, "text": text},
                        )
                    )

                if not tool_calls or plain:
                    break

                # Record the assistant round (text + tool_use blocks) for the
                # next request.
                blocks: list[dict[str, Any]] = []
                if text:
                    blocks.append({"type": "text", "text": text})
                for tc in tool_calls:
                    tc.setdefault("id", f"call_{uuid.uuid4().hex[:8]}")
                    block = {
                        "type": "tool_use",
                        "id": tc["id"],
                        "name": tc.get("name", ""),
                        "input": tc.get("input", {}) or {},
                    }
                    if tc.get("thought_signature"):
                        block["thought_signature"] = tc["thought_signature"]
                    blocks.append(block)
                messages.append(BrainMessage(role="assistant", content=blocks))

                for tc in tool_calls:
                    if handle.cancel.is_set():
                        status = "cancelled"
                        break
                    name = str(tc.get("name") or "")
                    args = tc.get("input") or {}
                    if not isinstance(args, dict):
                        try:
                            args = json.loads(str(args))
                        except (TypeError, ValueError):
                            args = {}
                    call_id = str(tc["id"])
                    meta = (
                        {"thought_signature": tc["thought_signature"]}
                        if tc.get("thought_signature")
                        else {}
                    )
                    await handle.emit(
                        make_event(
                            "tool_call",
                            {
                                "turn_id": handle.turn_id,
                                "call_id": call_id,
                                "name": name,
                                "input": args,
                                "summary": summarize_call(name, args),
                                "meta": meta,
                            },
                        )
                    )
                    t_tool = time.perf_counter()
                    output, is_error = await _run_gated_tool(
                        handle, permission_mode, call_id, name, args, cwd
                    )
                    if output == _PERMISSION_UPGRADED:
                        permission_mode = "auto"
                        output, is_error = await execute_tool(name, args, cwd=cwd)
                    await handle.emit(
                        make_event(
                            "tool_result",
                            {
                                "turn_id": handle.turn_id,
                                "call_id": call_id,
                                "name": name,
                                "output": output,
                                "is_error": is_error,
                                "duration_ms": int((time.perf_counter() - t_tool) * 1000),
                            },
                        )
                    )
                    fed = f"[error] {output}" if is_error else output
                    messages.append(
                        BrainMessage(
                            role="tool",
                            content=_cap(fed, _TOOL_RESULT_CAP),
                            tool_call_id=call_id,
                            name=name,
                        )
                    )
                if status == "cancelled":
                    break
                if round_no == MAX_ROUNDS - 2:
                    # Last round: no tools, summarize.
                    tools = ()
                    messages.append(BrainMessage(role="user", content=_ROUND_BUDGET_DIRECTIVE))
    except asyncio.CancelledError:
        status = "cancelled"
        raise
    finally:
        await handle.emit(
            make_event(
                "turn_finished",
                {
                    "turn_id": handle.turn_id,
                    "status": status,
                    "duration_ms": int((time.perf_counter() - t0) * 1000),
                    "usage": usage_total,
                    "error": error_text,
                },
            )
        )


_PERMISSION_UPGRADED: Final[str] = "\0permission-upgraded\0"


async def _run_gated_tool(
    handle: TurnHandle,
    permission_mode: str,
    call_id: str,
    name: str,
    args: dict[str, Any],
    cwd: Path,
) -> tuple[str, bool]:
    """Ask first when the mode says so; run otherwise.

    The ladder (dodaios/agent_chat/permissions.py): ``ask`` asks for every
    mutating tool; ``accept-edits`` lets Write/Edit through and asks for
    RunCommand; ``auto`` asks for nothing; ``plan`` never reaches here (the
    model has no mutating tools) but is treated like ``ask`` if it did.
    """
    if name in READ_ONLY_TOOLS or permission_mode == "auto":
        return await execute_tool(name, args, cwd=cwd)
    if permission_mode == "accept-edits" and name in EDIT_TOOLS:
        return await execute_tool(name, args, cwd=cwd)
    decision = await handle.request_approval(call_id, name, args, summarize_call(name, args))
    if decision == "deny":
        return "Denied by the user.", True
    if decision == "cancel":
        return "Cancelled.", True
    if decision == "allow_always":
        return _PERMISSION_UPGRADED, False
    return await execute_tool(name, args, cwd=cwd)


async def _stream(brain: Any, req: BrainRequest, cancel: asyncio.Event):
    """Iterate the brain stream, ending early when ``cancel`` is set."""
    from dodaios.costs.ledger import usage_context

    # The chat store records this turn's usage itself (``turn_finished``).
    with usage_context("agent-chat"):
        agen = brain.complete(req)
    try:
        while True:
            if cancel.is_set():
                return
            nxt = asyncio.ensure_future(agen.__anext__())
            waiter = asyncio.ensure_future(cancel.wait())
            done, _ = await asyncio.wait({nxt, waiter}, return_when=asyncio.FIRST_COMPLETED)
            if waiter in done and nxt not in done:
                nxt.cancel()
                return
            waiter.cancel()
            try:
                delta: BrainDelta = nxt.result()
            except StopAsyncIteration:
                return
            yield delta
    finally:
        aclose = getattr(agen, "aclose", None)
        if aclose is not None:
            try:
                await aclose()
            except Exception as exc:  # noqa: BLE001 — closing a half-read stream may raise
                log.debug("agent chat: closing the provider stream raised %s", exc)