Dashboard: find the agents an application runs, and draw them

[benh]

Summary

The dashboard's call graph stopped at the agent boundary. A workflow that hands its work to a model showed up as one unremarkable method, and everything the model could then do to the application — every tool call back into a state type — was invisible, even though those are ordinary Reboot calls running under the same workflow. On the agent-wiki example the graph drew 5 calls between 4 state types and said nothing about the librarian, its 5 tools, or the calls they make; with this change it draws 11 calls between 4 state types and 1 agent.

How the analysis finds agents

It extends the existing static analysis in reboot/dashboard/backend/code_watcher.py and works the same way that analysis already recognizes Reboot calls: by asking pyright where a call's definition is, not by how the call is spelled.

• Runs. A call whose definition lands on one of Agent's entry points (run, iter, run_stream, run_stream_events) in reboot/agents/pydantic_ai/_agent.py is a run. Which entry point isn't recorded, since it doesn't change what the agent can reach. Runs are recorded on the servicer method, flattened through followed helpers.
• Only literally named, top-level agents, for now. The receiver has to resolve to an Agent(...) (or Agent.wrap(Agent(...))) with a string literal name=, bound to a name at the top level of a module, in the file running it or imported from another. That gives its name, model, system_prompt/instructions and description; only literals are read. The name, which the runtime requires to be unique, is the agent's identity: a run records it, and per-file records join on it. Anything else — a computed or missing name=, a factory, Agent.wrap of anything but a construction, held on self, bound inside a function, constructed where it's run, an alias, a parameter, an element of a collection, or a name bound twice at the top level — isn't resolved, and the run is a hazard of the method. Supporting more shapes can come later.
• Tools. A function whose decorator resolves to Agent.tool/tool_plain, the one way of giving an agent a tool that can always be followed. Each tool's body goes through the same analysis as a servicer method, so its Reboot calls, the runs it makes (agent-to-agent delegation), and its own method hazards are recorded.
• Everything that isn't followed is a typed hazard. Each place that can record a hazard has its own nested message with a oneof of the specific hazards possible there, each carrying what's written (rendered by ast.unparse), with optional fields where something may be absent: Servicer.Method.Hazard (run_on_unresolved_agent, override_on_unresolved_agent, ambiguous_call, each with the callee), Agent.Hazard (constructed_with for tools=/toolsets=/prepare_tools=, tool_registered_by_call, overridden), Agent.Run.Hazard (run_arguments for toolsets=/model=/instructions=, overridden when written inside an override's with), Agent.Tool.Hazard (prepared), and UnattributedHazard (tool_on_unresolved_agent, recorded per file). These are for a future ATTENTION section to show and toggle by case. builtin_tools= is left out, since those run in the model provider.
• ambiguous is a hazard too. Servicer.Method.ambiguous (and Agent.Tool.ambiguous) become Servicer.Method.Hazard.ambiguous_call, so everything the analysis didn't follow in a method is in one list.
• No positions. Nothing the analysis records is a line or column any more — including Servicer.line/character, which nothing read — so a file's records don't change when only the code around them moves.
• Per-file records. Like servicers, agents are recorded per file, because the watcher's cache is keyed by file. An agent met in several files has a record in each, joined on name. Reading Reboot's agents module is recorded as an external dependency, so upgrading reboot reanalyzes exactly the files that read it.

A fix to stored analyses (its own commit)

A restarted dashboard carries a file forward, unanalyzed, when its bytes and its dependencies' are unchanged, and the state recorded nothing about which analysis produced its results. After upgrading to a Reboot whose analysis records something new (agents, in this PR), unchanged files would go on showing what the older analysis found. The second commit, independent of agents, makes the state record code_analysis_version; a restart that finds a different one analyzes every file again, keeping the old records so the changelog doesn't report everything as added.

What the page shows

A card per agent, marked with 🤖 and tinted in the workflow colour, since an agent only ever runs inside a workflow: name, model, the first lines of the prompt, and a row per decorated tool. A run lands on the card's head as a runs arrow, folding into one counted arrow when the calling package is collapsed. Tools are drawn as workflow-coloured rings (they run in the workflow's context, but are called by the agent and declared by no API, which is also why unknown methods are rings), their calls leave their own rows dashed like a workflow's, and the cones light through the agent. Clicking the head opens the agent in the right-hand pane with the full prompt as written, its description, and each tool with its docstring and what it calls.

Not covered

The page doesn't draw hazards yet, which is the follow-up UI work. Agent changes don't produce changelog entries yet.

Commits

Each commit builds and passes the dashboard tests on its own, and each analysis commit records as hazards whatever it doesn't follow yet.

1. Agents: test that override(tools=...) reaches a run and is memoized
2. Dashboard: analyze every file again when the analysis changes — CODE_ANALYSIS_VERSION
3. Dashboard: stop recording where a servicer is written — drops Servicer.line/character
4. Dashboard: record where a method runs an agent — every run is a Servicer.Method.Hazard.run_on_unresolved_agent
5. Dashboard: find the agents a method runs — Agent, Agent.Run, literally named top-level agents, Agent.Run.Hazard
6. Dashboard: read an agent adopted with Agent.wrap where it is made
7. Dashboard: find the tools an agent has, and what they do — decorated tools, runs made by tools, Agent.Hazard, Agent.Tool.Hazard, UnattributedHazard
8. Dashboard: say what an override changes about an agent
9. Dashboard: draw the agents an application runs — the page
10. Dashboard: record an ambiguous call as a method's hazard
11. Dashboard: spell out Servicer.Method.Call rather than alias it

Testing

• The first commit adds a regression test to agent_tests.py: a tool given with agent.override(tools=[...]) reaches a run inside the override and is memoized across a workflow retry. That depends on each entry point building its wrapped toolsets before installing its own tools=[], and nothing covered it.
• Agent tests in code_watcher_tests.py: runs through all four entry points; decorated tools; an agent constructed in another file; delegation and cycles; runs whose agent can't be resolved (factory, alias, annotated and untyped parameters, collection element) and an override of one; only literally named top-level agents resolved (computed or missing names, factories, self, function-local, inline and twice-bound ones are hazards), with records unchanged when code moves down; Agent.wrap of a construction, and of anything else; per-run and override changes; tool registrations that aren't followed; the analysis version; and reconstitution from stored state. //tests/reboot/dashboard:code_watcher_tests_py passes on every commit from the third on, and every target under //tests/reboot/dashboard/... and //reboot/dashboard/... passes on the UI commit and the last, as does //tests/reboot/agents/pydantic_ai:agent_tests_py. Locally, ImplementationWatcherTest needed Envoy 1.38.4 on PATH, because the dev container still ships 1.38.2.
• Checked by hand against reboot/examples/agent-wiki in the browser (before the analysis was narrowed to top-level agents and hazards were restructured; agent-wiki's librarian is a top-level agent, and the page reads none of the changed fields): the card, the runs edge from Wiki.ingest, the tool edges, both cones, the collapsed-package fold, and the pane.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LRFggUcgVpLqhgb7h1cK6H

[aviator-app]

Current Aviator status

Aviator will automatically update this comment as the status of the PR changes.
Comment /aviator refresh to force Aviator to re-examine your PR (or learn about other /aviator commands).

This pull request is currently open (not queued).

How to merge

To merge this PR, comment /aviator merge or add the mergequeue-ready label.

---

See the real-time status of this PR on the Aviator webapp.

Use the Aviator Chrome Extension to see the status of your PR within GitHub.

[github-actions]

These sibling TypeLinks can collide on their React key. countCalls folds on a key that includes how, so (stateType, method) is not unique within a GraphTool.calls array:

reboot/reboot/dashboard/web/src/callgraph.ts

Lines 130 to 132 in 15eb421

	for (const call of calls ?? []) {
	const key = `${call.stateType}|${call.method}|${call.how}`;
	const already = counted.get(key);

A tool body that reaches the same method two ways — await Depot.ref(id).look(context) alongside Depot.ref(id).schedule(when=...).look(context) — yields two GraphCalls differing only in how (CALL vs SCHEDULE; the backend appends each call with no dedup), and both render here with key="shop.v1.Depot.look", which is a duplicate-key warning and unreliable reconciliation. This is the first place in the dashboard that renders GraphCalls as keyed siblings, so nothing on main already establishes this pattern — and features.ts guards the same ${stateTypeName}.${methodName} string with an explicit seen set for exactly this reason.

Suggested change

	key={`${call.stateTypeName}.${call.methodName}`}
	key={`${call.stateTypeName}.${call.methodName}|${call.how}`}

Worth noting separately: with the key fixed, the two entries still render as byte-identical links, since neither how nor count is shown. Deduplicating the list on (stateTypeName, methodName) instead, or surfacing how in the label, may be closer to what the pane wants.

[github-actions]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[github-actions]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.