| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328 |
- """The first-task catalog of onboarding's build beat: what the model may put on the build card.
- Pure. Gates read only hard facts (this OS, plugins installed this run, apps connected this run);
- whether a row fits the person is the model's call. ``agent/onboarding_flow.py`` checks the model's
- picks against ``eligible_tasks``; ``agent/onboarding_text.py`` renders each row's reminder.
- """
- from __future__ import annotations
- from collections.abc import Callable, Mapping
- from dataclasses import dataclass
- from typing import TYPE_CHECKING, Any
- if TYPE_CHECKING:
- from agent.onboarding_flow import Facts
- MAX_PICKS = 4
- MAX_LABEL = 32
- # The one fixed row: always last on the card, never one of the model's picks.
- FIXED_ID = "hermes"
- # The value a task the user names in words records; it is never on the card.
- OWN_ID = "own"
- @dataclass(frozen=True)
- class FirstTask:
- """``skills`` load first, before the work; an entry ``a|b`` means one of them, whichever fits.
- A plugin skill is written ``<catalog plugin>:<skill>``; :func:`task_skills` names it by the name it
- registered under on this install. ``goal`` finishes the sentence "Your job: ..."."""
- id: str
- label: str
- gate: Callable[[Facts, Mapping[str, Any]], bool]
- skills: tuple[str, ...]
- goal: str
- steps: tuple[str, ...]
- output: str
- quality: str
- done: str
- def _always(facts: Facts, picks: Mapping[str, Any]) -> bool:
- return True
- def _plugin(name: str) -> Callable[[Facts, Mapping[str, Any]], bool]:
- # The plugins card answers with every onboarding plugin installed, including ones from before this run.
- return lambda facts, picks: name in (picks.get("installed") or ())
- def _connected(facts: Facts, picks: Mapping[str, Any]) -> bool:
- return bool(picks.get("connected"))
- def _macos(facts: Facts, picks: Mapping[str, Any]) -> bool:
- return facts.os == "macos"
- FIRST_TASKS: tuple[FirstTask, ...] = (
- FirstTask(
- "hermes", "Explain how Hermes works", lambda facts, picks: False, ("hermes-agent", "claude-design", "p5js"),
- goal="build a living page that shows how Hermes works, from the real docs and this install",
- steps=(
- "Read https://hermes-agent.nousresearch.com/docs/llms.txt once with web_extract. Open a page only to "
- "check a fact you show.",
- "Read this install: the model, how many skills are installed, the connected apps, and what this chat did "
- "(tools called, skills loaded, their name and picks).",
- "Within a minute, open it in the preview pane with the title, those facts and three screen headings. "
- "Then fill one screen at a time.",
- "Screen 1, the agent loop: a pulse runs model, tool, result, back to the model, labelled with the tools "
- "this chat called.",
- "Screen 2, learning: a procedure becomes a skill that loads next time; memory keeps facts across chats. "
- "Use the skills this chat loaded.",
- "Screen 3, out in the world: cron jobs, connectors and messaging, one example each built on their apps.",
- ),
- output="One HTML file in ~/hermes-first-task/, three screens that each fill the pane with one animated "
- "graphic; open in the preview pane.",
- quality="Every name and number comes from the docs or this install. A few short lines per screen.",
- done="All three screens move and show real facts, and you said where the file is."),
- FirstTask(
- "games", "Tune my games for this PC", _plugin("nvidia-app"), ("nvidia-app:nvidia-app",),
- goal="optimise the games on this PC with NVIDIA App and show what changed",
- steps=(
- "Its tools are mcp__nvidia_app__nvapp_*. If none are listed, check without changing anything whether "
- "NVIDIA App is installed and running. Not installed: open https://www.nvidia.com/en-us/software/nvidia-app/ "
- "in the preview pane and say how to install it. Not running: say how to start it. Check again each time "
- "they say done.",
- "List the installed games and show them at once. If the driver status shows a newer Game Ready "
- "driver, say so in one line.",
- "Ask in one clarify which preset to apply (Performance, Visual or Recommended), naming the games.",
- "Apply it, then read each game back.",
- ),
- output="A before and after table in chat: one row per game, what changed.",
- quality="Only settings NVIDIA App reports and really changed. Never guess a value.",
- done="The changes are read back and in the table. Next-step idea: launch one of the games."),
- FirstTask(
- "broadcast", "Make my mic and camera pro", _plugin("nvidia-broadcast"), ("nvidia-broadcast:nvidia-broadcast",),
- goal="set up NVIDIA Broadcast so their mic and camera are ready for a call",
- steps=(
- "Its tools are mcp__nvidia_broadcast__*. If none are listed, check without changing anything whether "
- "NVIDIA Broadcast is installed and running. Not installed or too old: open "
- "https://www.nvidia.com/en-us/geforce/broadcasting/broadcast-app/ in the preview pane and offer the "
- "install as the skill says. Not running: say how to start it. Check again each time they say done.",
- "Read the devices and the effects this machine offers, then ask in one clarify what it is for: a "
- "meeting, a stream or a noisy room.",
- "Turn the effects on one at a time. After each, say what to look at or listen for in the Broadcast "
- "window.",
- ),
- output="A short list in chat: each effect, its device, before and after.",
- quality="Only effects Broadcast reports on this machine.",
- done="The effects are on and read back, and they know how to turn each one off."),
- FirstTask(
- "blender", "Build a 3D scene in Blender", _plugin("blender"), ("blender:blender",),
- goal="build a small 3D scene live in their open Blender, one visible step at a time",
- steps=(
- "Drive the open Blender with its mcp__blender__* tools. Never run Blender from the terminal.",
- "If Blender is not connected (no tools, or get_objects_summary fails), this is a first run: open "
- "https://www.blender.org/lab/mcp-server/ in the preview pane and walk them through it in a short list: "
- "Blender 5.1 or newer open; drag the page's Drag and Drop into Blender button into Blender twice (the "
- "first adds the Blender Lab repository, the second installs the add-on); allow Online access; start the "
- "MCP bridge on port 9876. Check again each time they say done.",
- "Offer three scene ideas in one clarify: two that fit them, one that shows off this machine.",
- "First capture their Blender window with get_screenshot_of_window_as_image, copy the image it saved "
- "over preview.png and open that in the preview pane, so they watch Hermes work. Then build it in a new "
- "scene named Hermes, in camera view, in four calls they can watch: ground and camera, main objects, "
- "materials and light, framing. After each, capture the window over preview.png again; the pane "
- "reloads it.",
- "Render one 1280x720 EEVEE still with render_viewport_to_path, copy the filepath it returns to "
- "render.png and open it in the pane. Look at it before you call it done: lit, not black, framed. Fix "
- "and re-render once at most.",
- "Save only the new scene with bpy.data.libraries.write as scene.blend, and the code as scene.py.",
- ),
- output="scene.blend, scene.py, preview.png and render.png in ~/hermes-first-task/; the render open in the "
- "preview pane.",
- quality="Made in their open Blender, never headless, never a placeholder.",
- done="The final still is shown and you named the files. Next-step idea: a turntable video or a GPU Cycles "
- "render."),
- FirstTask(
- "brief", "Brief me on today", _connected, ("claude-design",),
- goal="write today's brief from their connected apps",
- steps=(
- "Check the connected apps with manage_connections(action=\"status\").",
- "Read today from them: mail, calendar, messages, tasks. Read only.",
- "Show a first version early, then fill it in: what needs attention, what changed, what is next.",
- "Offer a morning cron job that sends the brief. Schedule it only on yes.",
- ),
- output="One designed HTML page in ~/hermes-first-task/, open in the preview pane.",
- quality="Every item comes from a connected app and says which one. Nothing invented.",
- done="The brief is shown and the morning job is set up or declined."),
- FirstTask(
- "week", "Recap my week on one page", _connected, ("weekly-review-planning", "claude-design"),
- goal="make one page that recaps their past seven days from the connected apps",
- steps=(
- "Check the connected apps with manage_connections(action=\"status\").",
- "Read the past seven days from them. Read only.",
- "Show a first version early, then fill it in: meetings, threads, work shipped, open loops.",
- "End with a short plan for next week built from the open loops.",
- ),
- output="One designed HTML page in ~/hermes-first-task/, open in the preview pane.",
- quality="Every item comes from a connected app and says which one. Nothing invented.",
- done="The page is shown with all five parts filled from real data."),
- FirstTask(
- "mac", "Set up my Mac helpers", _macos, ("apple-reminders", "apple-notes", "hermes-agent"),
- goal="set up their Mac helpers: one real reminder, one real note and a morning routine",
- steps=(
- "Ask in one clarify what the reminder and the note should be, with three concrete suggestions.",
- "Make the reminder in Reminders and the note in Notes with the skills.",
- "Propose a morning routine as a cron job: what it does and when. Schedule it only on yes.",
- ),
- output="The reminder and note in their apps and the cron job, each named in chat.",
- quality="Real items they asked for. No test items.",
- done="The reminder and note exist, and the morning job is set up or declined."),
- FirstTask(
- "notes", "Turn my notes into a wiki", _always, ("obsidian",),
- goal="turn their notes into a small linked wiki",
- steps=(
- "Ask which folder holds their notes. Never search the disk for it.",
- "Read the notes there and find the three main topics.",
- "Write an index page and three linked topic pages, each citing the notes it came from.",
- "Show the index page.",
- ),
- output="Four Markdown pages in ~/hermes-first-task/wiki/, unless they ask for their notes folder.",
- quality="Only what their notes say. Every link resolves.",
- done="The four pages exist, the links work and the index is shown."),
- FirstTask(
- "explain", "Explain a topic I care about", _always,
- ("grounded-citations", "claude-design", "p5js", "blocked-page-recovery"),
- goal="explain a topic they care about on one page built around a figure they can play with",
- steps=(
- "If the label they clicked names a topic, use it. Otherwise offer three guesses from what you know about "
- "them in one clarify.",
- "Within a minute, open it in the preview pane with the title and the figure already moving: the one "
- "mechanism that makes the topic click, which they can drag or tune.",
- "Research it with citations (load arxiv for a technical topic), then write short sections around the "
- "figure. End on the most surprising thing you found.",
- ),
- output="One HTML file in ~/hermes-first-task/, open in the preview pane, sources at the end.",
- quality="Every claim and every number in the figure is cited. Under 400 words of text.",
- done="The figure responds to input and every source is listed."),
- FirstTask(
- "youtube", "Turn a video into a page", _always, ("youtube-content", "claude-design", "p5js"),
- goal="turn one video into a page that lays its ideas out visually",
- steps=(
- "Ask for the video link.",
- "Get the transcript with the skill.",
- "Pull out the main ideas, each with a timestamp and a quote.",
- "Show a first version early, then lay the ideas out visually, with one figure where it helps.",
- ),
- output="One self-contained HTML file in ~/hermes-first-task/, open in the preview pane; each "
- "timestamp links to that moment in the video.",
- quality="Designed with claude-design. Quotes are exact words from the transcript.",
- done="The page is shown and every idea has its timestamp and quote."),
- FirstTask(
- "watch", "Watch something for me daily", _always,
- ("competitor-news-monitor|product-price-monitor", "grounded-citations"),
- goal="watch something for them every day and report here",
- steps=(
- "Ask what to watch in one clarify, with three concrete options from what you know about them.",
- "Run the first check now and report it with sources.",
- "Propose a daily cron job: when it runs and what it reports. Schedule it only on yes.",
- ),
- output="The first report in chat, and the daily cron job.",
- quality="Every finding has a source link. Nothing invented.",
- done="The first report is shown and the daily job is set up or declined."),
- FirstTask(
- "site", "Design a page for me", _always, ("claude-design", "popular-web-designs", "p5js"),
- goal="design one web page for them",
- steps=(
- "If you do not know what the page is for, ask in one line.",
- "Offer three design directions in one clarify.",
- "Show a first version early with a p5js hero, then refine the same file.",
- "Offer one variation.",
- ),
- output="One self-contained HTML file in ~/hermes-first-task/, open in the preview pane.",
- quality="Designed with the skills. Real content they gave you, never filler text.",
- done="The page is shown and a variation is offered."),
- FirstTask(
- "repo", "Map one of my repos", _always, ("codebase-inspection", "architecture-diagram", "github"),
- goal="map one of their code repositories on an architecture page",
- steps=(
- "Ask which repo, as a path or a URL, and ask before reading it.",
- "Show its language breakdown.",
- "Read its entry points and main modules.",
- "Draw the architecture page: the modules, how they connect, where to start reading.",
- ),
- output="One self-contained HTML file in ~/hermes-first-task/, open in the preview pane.",
- quality="Only modules that are really in the repo, named by their paths.",
- done="The page is shown and every box on it maps to a real path."),
- )
- # A task the user names in words: the same prompt shape, without a catalog row.
- OWN_TASK = FirstTask(
- OWN_ID, "", lambda facts, picks: False, ("hermes-agent",),
- goal="build the task they named in their own words",
- steps=(
- "Also load the skills that fit what they asked.",
- "If you know what it is, say the first slice in one line and start. If not, ask one short question "
- "(a clarify with three concrete options is fine).",
- "Cut a big ask to a first slice and say so in one line.",
- "Show a first version early, then refine it.",
- ),
- output="Whatever fits the task; a page is one self-contained HTML file, open in the preview pane.",
- quality="Real data only, designed with the skills when it is a page.",
- done="The first slice is shown and you said where its files are.")
- TASK_BY_ID = {task.id: task for task in FIRST_TASKS}
- EVERY_TASK_SKILL = "humanizer"
- def eligible_tasks(facts: Facts, picks: Mapping[str, Any]) -> tuple[FirstTask, ...]:
- """The rows the model may pick from on this machine and run, in catalog order."""
- return tuple(task for task in FIRST_TASKS if task.id != FIXED_ID and task.gate(facts, picks))
- def card_options(chosen: Any) -> list[dict]:
- """The build card: the model's picks as given, then the fixed row."""
- return [*(dict(option) for option in chosen or ()), {"id": FIXED_ID, "label": TASK_BY_ID[FIXED_ID].label}]
- def _option_error(option: Any, eligible: set[str], seen: set[str]) -> str | None:
- if not isinstance(option, Mapping) or not isinstance(option.get("id"), str):
- return 'each option is {"id": ..., "label": ...}'
- if option["id"] == FIXED_ID:
- return f"{FIXED_ID} is added last by itself; do not pick it"
- if option["id"] not in eligible:
- return f"{option['id']!r} is not an eligible id"
- if option["id"] in seen:
- return f"{option['id']!r} is picked twice"
- label = option.get("label")
- if not isinstance(label, str) or not label.strip():
- return f"the label for {option['id']} is empty"
- if len(label) > MAX_LABEL:
- return f'"{label}" is {len(label)} characters; the limit is {MAX_LABEL}. Shorten it'
- return None
- def pick_error(options: Any, facts: Facts, picks: Mapping[str, Any]) -> str | None:
- """Why the model's build picks are refused, naming the eligible ids; None when they are valid."""
- eligible = [task.id for task in eligible_tasks(facts, picks)]
- problems: list[str] = []
- if not isinstance(options, list) or not options:
- problems.append("options is required")
- elif len(options) > MAX_PICKS:
- problems.append(f"pick at most {MAX_PICKS}")
- else:
- # Every bad option is named at once, so one retry can fix them all.
- seen: set[str] = set()
- for option in options:
- if problem := _option_error(option, set(eligible), seen):
- problems.append(problem)
- elif isinstance(option, Mapping):
- seen.add(option["id"])
- if not problems:
- return None
- problem = "; ".join(problems)
- return (f'{problem}. Call setup_beat(beat="build", options=[{{"id": ..., "label": ...}}]) with up to '
- f"{MAX_PICKS} of these ids: {', '.join(eligible)}.")
- def task_skills(option: str, resolve_skill: Callable[[str], str | None]) -> list[str]:
- """The skills a task loads first, humanizer last, each by the name ``skill_view`` loads it with here:
- ``resolve_skill`` maps a written name to that name (a plugin skill's registered name differs from
- its ``<plugin>:<skill>`` form), or to None for a skill missing here, which is dropped."""
- names = [*TASK_BY_ID.get(option, OWN_TASK).skills, EVERY_TASK_SKILL]
- kept = []
- for entry in names:
- found = [resolved for name in entry.split("|") if (resolved := resolve_skill(name))]
- if found:
- kept.append(" or ".join(found))
- return kept
|