"""``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="🎛", )