feat(desktop): add an operational topology view for Agent Graph
- Dominant language
- TypeScript
- Stars
- 5.4k
- Forks
- 502
- Avg merge
- 1d 2h
- Merged PRs (30d)
- 715
Description
## Problem
Maka Desktop already has an `AgentGraphPanel`, but it renders Graph state as a flat list of operators. Users can see aggregate progress, one status and wait reason per visible operator, selected result IDs, and links to child Sessions; they cannot see the topology that makes the feature a graph:
- which operators depend on which upstream operators;
- where work fans out or joins;
- why a downstream operator is waiting in the context of the whole flow;
- which path is currently running, blocked, failed, or complete;
- how dynamically added work changed the execution shape.
This makes a multi-stage Graph difficult to understand at a glance. The Runtime read model already exposes stable `operators`, `edges`, `work`, readiness, status, and omission metadata, so the missing piece is primarily a Desktop presentation and interaction surface.
The current architecture intentionally describes the panel as an operational inspection/stop view rather than a visual graph editor. This issue preserves that boundary: the goal is to make live delegated work understandable, not to add a decorative diagram or a workflow-authoring system.
## Desired outcome
Add a read-only operational topology view for Agent Graph in the delegated-work / session workbar surface planned by #1457.
The view should:
- render operators as nodes and declared dependencies as directed edges;
- make fan-out, chains, and fan-in/join structures legible;
- show node state (`not_started`, `waiting`, `runnable`, `running`, `blocked`, and terminal states) with text/icon semantics in addition to color;
- expose the most useful work instruction preview and wait reason without requiring users to open every child Session;
- let users select an operator to inspect its bounded details and open the linked child Session;
- update from the existing Graph invalidation/query contract while keeping layout reasonably stable as operators are added or statuses change;
- preserve a compact list/table alternative for accessibility, narrow windows, and cases where a graph layout is less useful;
- represent loading, empty, error, stopped, completed, and omitted/truncated states honestly;
- remain usable with larger bounded snapshots through pan/zoom, fit-to-view, incremental layout, or equivalent interaction;
- use the existing Desktop design system and support current themes.
Suggested acceptance scenarios:
1. A → B → C reads clearly as a sequential dependency chain.
2. A fans out to B and C, then B + C feed D; the join and D's waiting reason are visible.
3. One branch fails while another completes; the active and terminal paths remain distinguishable without relying only on color.
4. A supervisor adds an operator during execution; the view updates without resetting the user's selection or needlessly jumping the viewport.
5. A bounded snapshot reports omitted operators or edges; the UI states that the displayed topology is partial rather than implying completeness.
6. Selecting a node can open its child Session and inspect the data already exposed by `graphs.inspectOperator`.
7. Restart/reconnect reconstructs the same view from durable Graph state; renderer-local layout state is never treated as execution authority.
## Non-goals
- Creating, deleting, rewiring, or dragging Graph operators/edges to change execution.
- A general workflow editor or arbitrary cyclic graph authoring.
- Adding a second Graph/event store or deriving execution state from renderer state.
- Replacing the chronological trace / replay work from #1529 or the broader Session Inspector in #1625.
- Shipping a decorative graph before delegated-work status and waiting conditions remain understandable.
## Alternatives or workarounds
- Keep using the current flat operator list and open child Sessions one by one. This exposes individual status but hides dependency shape.
- Render only a chronological event timeline. Useful for diagnosis, but it answers “what happened when,” not “what depends on what now.”
- Generate a static Mermaid/DOT diagram. This does not provide live status, selection, child-session navigation, bounded omission handling, or reconnect behavior.
- Add the visualization as a standalone panel. #1457 and #2469 point toward one delegated-work surface, so folding the topology view into that surface avoids competing Graph UIs.
## Related
- #1341 — original supervised stream-graph design; its delivery plan explicitly deferred a full graph visualization / scalable explorer.
- #1457 — moves linked child Sessions and the existing Graph panel into the session workbar.
- #1529 — delivered the replayable control/data-plane timeline; Desktop timeline presentation remains a separate observability concern.
- #1625 — broader per-session causal timeline / Inspector.
- #2469 — product roadmap; this proposal is operational information architecture, not a decorative visualization.
Contributor guide
Research direction
Start with the existing AgentGraphPanel and the delegated-work/session workbar surface planned by #1457. Read the existing Graph invalidation/query contract and the data exposed by graphs.inspectOperator before defining the topology interaction. Done means the live view covers the listed acceptance scenarios, preserves a compact alternative, and does not treat renderer state as execution authority.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- electron, typescript
- Domain
- desktop
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 32/100