apache / apache/maka

feat(desktop): add an operational topology view for Agent Graph

Open
#2,596 1 comment 0 reactions 0 assignees View on GitHub
enhancement help wanted stale
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.