hermes-agent/tools/setup_beat_tool.py

"""``setup_beat``: the one onboarding-only tool. It shows a beat's card through the desktop, waits
for the user (``CARD_TIMEOUT_S``), and returns their answer with a short reminder of the next beat.

The ``onboarding`` toolset carrying it is folded in only for the onboarding chat, at agent build
(``tui_gateway/methods_onboarding.py``). The run record is the session's ``onboarding_run``
(``agent/onboarding_record.py``); the order and the options are ``agent/onboarding_flow.py``.
"""

from __future__ import annotations

import json
import logging
from collections.abc import Callable, Mapping
from typing import Any

from agent import onboarding_flow as flow
from agent.onboarding_text import finish_reminder, reminder
from agent.onboarding_text import question as beat_question
from tools.registry import registry, tool_error

logger = logging.getLogger(__name__)

BEATS = ("next", *flow.BEAT_IDS, "done")


def _connected() -> dict:
    from tools.connectors.display import connected_slugs
    from tools.connectors.gateway.client import ConnectorClient

    return {"connected": sorted(connected_slugs(ConnectorClient()))}


def _installed() -> dict:
    from hermes_cli.plugin_catalog_presence import onboarding_names
    from hermes_cli.plugins_cmd import _catalog_installed_dir

    return {"installed": [name for name in onboarding_names() if _catalog_installed_dir(name) is not None]}


# A card closed without its own answer (words, a value, a skip, the deadline) still reports these.
_PRESENT = {"connectors": _connected, "plugins": _installed}


def _present(beat: str) -> dict | None:
    if (read := _PRESENT.get(beat)) is None:
        return None
    try:
        return read()
    except Exception:
        logger.warning("onboarding: could not read what the %s beat has on this machine", beat, exc_info=True)
        return None


def _direct_event(beat: str, args: Mapping[str, Any]) -> flow.Event | None:
    """An event the call carries in itself (no card): done, a value given in words, or a skip. Only the
    Skip setup button (onboarding.skip) ends onboarding early; the model never decides the user quit."""
    if beat == "done":
        return flow.Done()
    if args.get("skip"):
        return flow.Skipped(beat, _present(beat))
    value = args.get("value")
    return flow.Recorded(beat, value.strip(), _present(beat)) if isinstance(value, str) and value.strip() else None


def _reply_event(beat: str, reply: Mapping[str, Any] | None) -> flow.Event:
    reply = reply or {}
    said = reply.get("said")
    if beat == "name" and isinstance(said, str) and said.strip():
        # Words typed while the name card waits are the name, like its own text box.
        return flow.Answered(beat, {"name": said.strip()}, said.strip())
    if reply.get("wrote_instead"):
        # A message sent instead of answering: the desktop sends it as the user's next turn.
        return flow.Wrote(beat, _present(beat))
    answer = reply.get("answer")
    return flow.Answered(beat, answer) if isinstance(answer, dict) and answer else flow.TimedOut(beat, _present(beat))


def _skill_resolver() -> Callable[[str], str | None]:
    """A written first-task skill name -> the name skill_view loads it with here, or None. A plugin skill
    (``blender:blender``) resolves through the installed catalog plugin to its registered name."""
    from hermes_cli.plugins_activation_live import catalog_plugin_skill
    from tools.skills_tool import find_all_skills

    bundled = {skill["name"] for skill in find_all_skills()}
    return lambda name: catalog_plugin_skill(name) if ":" in name else (name if name in bundled else None)


def _result(step: flow.Step, beat: str | None = None, extra: str = "") -> str:
    facts = flow.Facts.from_stored(step.record["facts"])
    # Only a first task's reminder names skills; the skills scan is skipped for every other result.
    resolve_skill = _skill_resolver() if step.reminder.startswith("build_") else (lambda name: name)
    text = reminder(step.reminder, step.record, facts, beat, resolve_skill) + extra
    return json.dumps({**step.result, **({"reminder": text} if text else {})}, ensure_ascii=False)


def _connector_slugs() -> set[str] | None:
    """The connectors this account can connect, as the card lists them; None when the list is unreachable."""
    from tools.connectors.targets import hosted_names

    return hosted_names()


def _suggest_from(slugs: set[str] | None) -> str:
    # The model guesses an app's connector from what is installed (GitHub from the gh CLI); the card shows
    # only listed ones, so it names its suggestions from this list.
    return f" Suggest only connectors from this list, by these slugs: {', '.join(sorted(slugs))}." if slugs else ""


def _unlisted_suggestions(args: Mapping[str, Any]) -> str | None:
    """The refusal for connector suggestions the card cannot show, or None when every one is listed."""
    wanted = [str(slug).strip().lower() for slug in args.get("suggest") or () if str(slug).strip()]
    slugs = _connector_slugs() if wanted else None
    unlisted = [slug for slug in wanted if slugs is not None and slug not in slugs]
    if not unlisted:
        return None
    return json.dumps({"error": "not connectors here", "reminder": (
        f"No card shown: {', '.join(unlisted)} cannot be connected here. Do not mention them as connections."
        f"{_suggest_from(slugs)} Then call setup_beat(beat=\"connectors\", suggest=[...]) again, or without "
        "suggest when none fits.")}, ensure_ascii=False)


def _card(beat: str, step: flow.Step, args: Mapping[str, Any]) -> dict:
    facts = flow.Facts.from_stored(step.record["facts"])
    card = flow.BEAT_BY_ID[beat].card(facts, step.record["picks"])
    if beat == "name":
        from agent.onboarding_facts import suggested_name

        # The account name goes to the card only; the model reads it if the user picks it.
        card = {"suggested": name} if (name := suggested_name()) else {}
    if beat == "connectors":
        card = {"suggested": [str(slug) for slug in args.get("suggest") or () if str(slug).strip()]}
    return card


def setup_beat_tool(args: Mapping[str, Any], *, db=None, session_id: str = "", tool_call_id: str = "",
                    callback: Callable[[dict], dict | None] | None = None,
                    end_turn: Callable[[], object] | None = None) -> str:
    """``callback(payload) -> {answer?} | {said} | {wrote_instead: true} | None`` asks the desktop to show
    ``{beat, question, card}`` and blocks until the user answers or the card closes. ``end_turn`` ends the
    agent's turn once this result is in: a card the user wrote past, whose message is the next turn."""
    from agent import onboarding_record as records

    beat = args.get("beat")
    if beat not in BEATS:
        return tool_error(f"beat must be one of: {', '.join(BEATS)}.")
    record = records.load(db, session_id)
    if record is None:
        return tool_error("Onboarding is not running in this chat.")
    if beat != "next" and (event := _direct_event(beat, args)) is not None:
        return _result(records.advance(db, session_id, event))
    if beat == "next":
        beat = flow.next_beat(record) if flow.is_active(record) else None
        if beat is None:
            return json.dumps({"next": "done", "reminder": finish_reminder(record)} if flow.is_active(record)
                              else {"error": "Onboarding is over in this chat; it is a normal chat now."})
    if callback is None:
        return tool_error("setup_beat cards show only in the Hermes desktop app.")
    if beat == "connectors" and (refused := _unlisted_suggestions(args)):
        return refused
    shown = records.advance(db, session_id, flow.Shown(beat, tool_call_id, args.get("options"), args.get("suggest")))
    if shown.result:  # refused, or a beat this machine skips
        extra = _suggest_from(_connector_slugs()) if shown.reminder == "offer_first" else ""
        return _result(shown, extra=extra)
    question = str(args.get("question") or "").strip() or beat_question(beat, (record.get("facts") or {}).get("locale"))
    reply = callback({"beat": beat, "question": question, "card": _card(beat, shown, args),
                      "tool_call_id": tool_call_id or None})
    after = records.load(db, session_id)
    if after is not None and after["phase"] == flow.PHASE_SKIPPED:
        # Skip setup closed the card (onboarding.skip already wrote the record).
        return _result(flow.Step(after, {"skipped_all": True}, "skip_all"))
    event = _reply_event(beat, reply)
    result = _result(records.advance(db, session_id, event), beat)
    if isinstance(event, flow.Wrote) and end_turn is not None:
        # Otherwise the model answers a card the user moved past while their message waits for the turn to end.
        end_turn()
    return result


SETUP_BEAT_SCHEMA = {
    "name": "setup_beat",
    "description": (
        "Run the first-run onboarding in this chat. Shows the card for a beat and waits for the user, then "
        "returns their answer and what to do next. beat=next shows the next beat. Pass value to record an answer "
        "they gave in words, skip to record that they skipped a beat. The build card needs options: your picks "
        "from the list its reminder gives. beat=done ends onboarding after the first "
        "build is shown and its close card is answered. Nothing here ends it early: a user who wants to stop "
        "presses Skip setup."
    ),
    "parameters": {
        "type": "object",
        "required": ["beat"],
        "properties": {
            "beat": {"type": "string", "enum": list(BEATS)},
            "question": {"type": "string", "description": "Your line above the card."},
            "value": {"type": "string", "description": "Record an answer given in words (a name, or an option id). No card."},
            "skip": {"type": "boolean", "description": "They skipped this beat in words. No card."},
            "suggest": {"type": "array", "items": {"type": "string"},
                        "description": "connectors only: slugs pinned as Suggested."},
            "options": {"type": "array", "maxItems": 4, "description": "build only: up to four picks, ids from the list.",
                        "items": {"type": "object", "required": ["id", "label"],
                                  "properties": {"id": {"type": "string"},
                                                 "label": {"type": "string", "maxLength": 32}}}},
        },
    },
}


registry.register(
    name="setup_beat", toolset="onboarding", schema=SETUP_BEAT_SCHEMA,
    # The agent loop runs it inline with the session's record and card callback
    # (agent/inline_tool_executors.py); a bare registry dispatch has neither.
    handler=lambda args, **kw: setup_beat_tool(args),
    emoji="🎛",
)