feat(desktop): visualize agent graph topology

apps/desktop/e2e-budget.json

@@ -5,6 +5,10 @@
     "Every spec below records the Electron-owned mechanism it needs. If you cannot name one, the test does not belong here."
   ],
   "specs": {
+    "agent-graph.spec.ts": {
+      "tests": 2,
+      "electron": "the panel renders a projection materialized through renderer, preload IPC, main, Runtime Host and SQLite; the liveness CSS and the scroll/focus geometry are asserted in the real compositor window"
+    },
     "composer-directory-reference.spec.ts": {
       "tests": 1,
       "electron": "the folder reference has to survive a renderer reload and still agree with the Host's session record"

apps/desktop/e2e/agent-graph.spec.ts

@@ -0,0 +1,209 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import type { Locator } from '@playwright/test';
+import { expect, test } from './fixtures';
+
+async function expectInsideViewport(target: Locator, viewport: Locator): Promise<void> {
+  await expect
+    .poll(async () => {
+      const targetBox = await target.evaluate((element) => {
+        const rect = element.getBoundingClientRect();
+        return { left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom };
+      });
+      const viewportBox = await viewport.evaluate((element) => {
+        const rect = element.getBoundingClientRect();
+        return {
+          left: rect.left + element.clientLeft,
+          top: rect.top + element.clientTop,
+          right: rect.left + element.clientLeft + element.clientWidth,
+          bottom: rect.top + element.clientTop + element.clientHeight,
+        };
+      });
+      const tolerance = 1;
+      return Boolean(
+        targetBox.left >= viewportBox.left - tolerance &&
+          targetBox.top >= viewportBox.top - tolerance &&
+          targetBox.right <= viewportBox.right + tolerance &&
+          targetBox.bottom <= viewportBox.bottom + tolerance,
+      );
+    })
+    .toBe(true);
+}
+
+function metadataValue(scope: Locator, label: string): Locator {
+  return scope
+    .locator('dt')
+    .filter({ hasText: label })
+    .locator('xpath=following-sibling::dd[1]');
+}
+
+async function expectMetadata(
+  scope: Locator,
+  label: string,
+  value: string | RegExp,
+): Promise<void> {
+  await expect(metadataValue(scope, label)).toHaveText(value);
+}
+
+test('keeps liveness signals in both views and respects reduced motion', async ({
+  agentGraphTopologyWindow: page,
+}) => {
+  const panel = page.getByRole('region', { name: 'Agent Graph', exact: true });
+  await expect(panel).toHaveAttribute('data-live', 'true');
+  await page.emulateMedia({ reducedMotion: 'no-preference' });
+  await page.evaluate(() => {
+    document.documentElement.removeAttribute('data-maka-e2e-fixture');
+    document.documentElement.removeAttribute('data-maka-reduced-motion');
+  });
+  const heartbeat = panel.locator('.maka-agent-graph-heartbeat');
+  const runningDot = panel.locator('.maka-agent-graph-status-dot[data-status="running"]').first();
+  await expect(heartbeat).toBeVisible();
+  await expect(heartbeat).toHaveAttribute('aria-hidden', 'true');
+  await expect(runningDot).toHaveCSS('animation-name', 'maka-agent-graph-dot-pulse');
+  await expect(runningDot).toHaveCSS('animation-iteration-count', 'infinite');
+  await panel.getByRole('radio', { name: 'List' }).click();
+  await expect(runningDot).toHaveCSS('animation-name', 'maka-agent-graph-dot-pulse');
+  await expect(runningDot).toHaveCSS('animation-iteration-count', 'infinite');
+
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+  await expect(heartbeat).toBeHidden();
+  await expect(runningDot).toHaveCSS('animation-iteration-count', '1');
+  await page.emulateMedia({ reducedMotion: 'no-preference' });
+  await page.evaluate(() => document.documentElement.setAttribute('data-maka-reduced-motion', 'true'));
+  await expect(heartbeat).toBeHidden();
+  await expect(runningDot).toHaveCSS('animation-iteration-count', '1');
+});
+
+test('inspects and follows an operator across graph views', async ({
+  agentGraphTopologyWindow: page,
+}) => {
+  const panel = page.getByRole('region', { name: 'Agent Graph', exact: true });
+  const topology = page.getByTestId('agent-graph-topology');
+
+  await expect
+    .poll(() =>
+      topology.evaluate((element) => ({
+        horizontal: element.scrollWidth > element.clientWidth,
+        vertical: element.scrollHeight > element.clientHeight,
+      })),
+    )
+    .toEqual({ horizontal: true, vertical: true });
+
+  const initialPublisherNode = topology.getByRole('button', { name: /^publisher\./u });
+  await initialPublisherNode.click();
+  await expect(initialPublisherNode).toBeFocused();
+  await expectInsideViewport(initialPublisherNode, topology);
+  await expectInsideViewport(initialPublisherNode, panel);
+  await expect(page.getByRole('region', { name: 'Operator details: publisher' })).toBeAttached();
+  await initialPublisherNode.click();
+
+  await panel.getByRole('radio', { name: 'List' }).click();
+  const publisherRow = panel
+    .getByTestId('agent-graph-list')
+    .locator(':scope > li')
+    .filter({ has: page.getByText('publisher', { exact: true }) });
+  await expect(publisherRow.getByText('Completed', { exact: true })).toBeVisible();
+  await expect(publisherRow).toContainText('1 more work item omitted');
+
+  const detailsButton = publisherRow.getByRole('button', {
+    name: 'View publisher details',
+  });
+  await detailsButton.click();
+  await expect(detailsButton).toBeFocused();
+  await expect(detailsButton).toHaveAttribute('aria-expanded', 'true');
+  const details = page.getByRole('region', { name: 'Operator details: publisher' });
+  await expect(details).toHaveAttribute('aria-busy', 'false');
+  const collection = (name: string) =>
+    details
+      .locator('.maka-agent-graph-details-collection')
+      .filter({ has: page.getByText(name, { exact: true }) });
+  const publisherSessionId = /^\["[a-f0-9]{64}","child-publisher"\]$/u;
+  const activations = collection('Activations');
+  const activation = activations.locator('li');
+  await expect(
+    metadataValue(activation, 'firstEventTime').locator(
+      'time[datetime="2026-05-22T02:59:57.000Z"]',
+    ),
+  ).toBeVisible();
+  await expect(
+    metadataValue(activation, 'lastEventTime').locator(
+      'time[datetime="2026-05-22T02:59:59.000Z"]',
+    ),
+  ).toBeVisible();
+  await expectMetadata(activation, 'lastRecordId', 'record-publisher-terminal');
+  await expectMetadata(activation, 'terminalRecordId', 'record-publisher-terminal');
+  await expectMetadata(activation, 'run.sessionId', publisherSessionId);
+  await expectMetadata(activation, 'run.agentRunId', 'run-publisher');
+  await expectMetadata(activation, 'run.turnId', 'turn-publisher');
+
+  const claims = collection('Claims');
+  const claim = claims.locator('li').filter({ hasText: 'claim-publisher' });
+  await expectMetadata(claim, 'intentId', 'intent-publisher');
+  await expectMetadata(claim, 'childSessionId', publisherSessionId);
+  await expect(
+    metadataValue(claim, 'claimedAt').locator('time[datetime="2026-05-22T02:59:56.000Z"]'),
+  ).toBeVisible();
+  await expectMetadata(claim, 'run.sessionId', publisherSessionId);
+  await expectMetadata(claim, 'run.agentRunId', 'run-publisher');
+  await expectMetadata(claim, 'run.turnId', 'turn-publisher');
+
+  const activity = collection('Recent activity');
+  const permissionRecord = activity.locator('li').filter({ hasText: 'record-publisher-permission' });
+  await expectMetadata(permissionRecord, 'activationId', 'activation-publisher');
+  await expectMetadata(permissionRecord, 'signals', 'attention: permission request');
+  await expect(
+    metadataValue(permissionRecord, 'eventTime').locator(
+      'time[datetime="2026-05-22T02:59:57.000Z"]',
+    ),
+  ).toBeVisible();
+  await expectMetadata(permissionRecord, 'run.sessionId', publisherSessionId);
+  await expectMetadata(permissionRecord, 'run.agentRunId', 'run-publisher');
+  await expectMetadata(permissionRecord, 'run.turnId', 'turn-publisher');
+  const terminalRecord = activity.locator('li').filter({ hasText: 'record-publisher-terminal' });
+  await expectMetadata(terminalRecord, 'activationId', 'activation-publisher');
+  await expectMetadata(terminalRecord, 'signals', 'terminal: completed');
+  await expect(
+    metadataValue(terminalRecord, 'eventTime').locator(
+      'time[datetime="2026-05-22T02:59:59.000Z"]',
+    ),
+  ).toBeVisible();
+  await expectMetadata(terminalRecord, 'run.sessionId', publisherSessionId);
+  await expectMetadata(terminalRecord, 'run.agentRunId', 'run-publisher');
+  await expectMetadata(terminalRecord, 'run.turnId', 'turn-publisher');
+  await expectInsideViewport(detailsButton, panel);
+  await expectInsideViewport(details.locator('.maka-agent-graph-details-heading'), panel);
+
+  await panel.getByRole('radio', { name: 'Topology' }).click();
+  const selectedNode = topology.locator('.maka-agent-graph-node[data-selected="true"]');
+  await expect(selectedNode).toContainText('publisher');
+  await expect(selectedNode).toContainText('1 more work item omitted');
+  await expectInsideViewport(selectedNode, topology);
+  await expectInsideViewport(selectedNode, panel);
+  await expect.poll(() => topology.evaluate((element) => element.scrollLeft)).toBeGreaterThan(0);
+
+  await panel.getByRole('button', { name: 'Collapse Agent Graph' }).click();
+  await panel.getByRole('button', { name: 'Expand Agent Graph' }).click();
+  await expectInsideViewport(selectedNode, topology);
+  await expectInsideViewport(selectedNode, panel);
+
+  await panel.getByRole('radio', { name: 'List' }).click();
+  await expectInsideViewport(detailsButton, panel);
+  await expectInsideViewport(details.locator('.maka-agent-graph-details-heading'), panel);
+});

apps/desktop/e2e/fixtures.ts

@@ -522,6 +522,7 @@ type E2eTestFixtures = {
   projectSidebarWindow: Page;
   parentRemovalWindow: Page;
   railRenderWindow: Page;
+  agentGraphTopologyWindow: Page;
   promptRailWindow: Page;
   partialHistoryWindow: Page;
   requestHeaderRowWindow: Page;
@@ -622,6 +623,15 @@ export const test = base.extend<E2eTestFixtures>({
       use,
     );
   },
+  agentGraphTopologyWindow: async ({}, use) => {
+    await withE2eWindow({
+      seed: false,
+      readinessSelector: '[data-testid="agent-graph-topology"]',
+      e2eFixtureScenario: 'agent-graph-topology',
+      locale: 'en',
+      showWindow: true,
+    }, use);
+  },
   // A multi-prompt transcript. Each cost assertion gets an isolated Host and
   // renderer so observation state cannot bleed between tests. The window is
   // shown because these cases drive the real compositor through CDP.

apps/desktop/renderer-architecture.json

@@ -1,9 +1,6 @@
 {
   "version": 1,
   "legacyRendererFiles": [
-    "src/renderer/agent-graph-panel-visibility.ts",
-    "src/renderer/agent-graph-panel.tsx",
-    "src/renderer/agent-graph-refresh.ts",
     "src/renderer/app-shell-chat-actions.ts",
     "src/renderer/app-shell-chrome-actions.tsx",
     "src/renderer/app-shell-command-actions.ts",
@@ -60,7 +57,6 @@
     "src/renderer/live-turn-reconciler.tsx",
     "src/renderer/live-turn-snapshot.ts",
     "src/renderer/local-memory-digest.ts",
-    "src/renderer/locales/agent-graph-copy.ts",
     "src/renderer/locales/artifact-copy.ts",
     "src/renderer/locales/browser-copy.ts",
     "src/renderer/locales/conversation-copy.ts",
@@ -716,7 +712,7 @@
         "nonTriviaTokens": 1408
       },
       "src/renderer/app-shell.tsx": {
-        "importDeclarations": 79,
+        "importDeclarations": 78,
         "bridgePaths": {
           "window.maka.attachments": 1,
           "window.maka.attachments.readBytes": 1,
@@ -801,7 +797,6 @@
         "actionFactories": [],
         "dependencyPaths": {
           "../preload/transcript-contract.js": 1,
-          "./agent-graph-panel": 1,
           "./app-shell-chat-actions": 1,
           "./app-shell-chrome-actions": 1,
           "./app-shell-context-compaction": 1,
@@ -826,6 +821,7 @@
           "./desktop-execution-boundary-surface": 1,
           "./desktop-slash-command": 1,
           "./error-boundary": 1,
+          "./features/agent-graph": 1,
           "./features/app-update/index.js": 1,
           "./features/conversation": 1,
           "./features/goals": 1,
@@ -892,7 +888,7 @@
           "@maka/ui/icons": 1,
           "react": 1
         },
-        "importSpecifiers": 121,
+        "importSpecifiers": 120,
         "nonTriviaTokens": 14996
       },
       "src/renderer/use-app-shell-composer-quotes.ts": {
@@ -1035,54 +1031,6 @@
         "actionFactories": [],
         "dependencyPaths": {}
       },
-      "src/renderer/agent-graph-panel-visibility.ts": {
-        "bridgePaths": {},
-        "environmentCapabilities": {},
-        "hookCalls": {},
-        "lifecycleMethods": {},
-        "unresolvedDependencies": 0,
-        "actionFactories": [],
-        "dependencyPaths": {}
-      },
-      "src/renderer/agent-graph-panel.tsx": {
-        "bridgePaths": {
-          "window.maka.graphs.getSnapshot": 1,
-          "window.maka.graphs.listCurrentEpochs": 1,
-          "window.maka.graphs.listEpochs": 2,
-          "window.maka.graphs.stop": 1,
-          "window.maka.graphs.subscribe": 1
-        },
-        "environmentCapabilities": {},
-        "hookCalls": {
-          "useEffect": 2,
-          "useRef": 4,
-          "useState": 9
-        },
-        "lifecycleMethods": {},
-        "unresolvedDependencies": 0,
-        "actionFactories": [],
-        "dependencyPaths": {
-          "./agent-graph-panel-visibility.js": 1,
-          "./agent-graph-refresh.js": 1,
-          "./locales/agent-graph-copy.js": 1,
-          "@astryxdesign/core/Banner": 1,
-          "@astryxdesign/core/Button": 1,
-          "@astryxdesign/core/EmptyState": 1,
-          "@astryxdesign/core/Spinner": 1,
-          "@maka/ui": 1,
-          "@maka/ui/icons": 1,
-          "react": 1
-        }
-      },
-      "src/renderer/agent-graph-refresh.ts": {
-        "bridgePaths": {},
-        "environmentCapabilities": {},
-        "hookCalls": {},
-        "lifecycleMethods": {},
-        "unresolvedDependencies": 0,
-        "actionFactories": [],
-        "dependencyPaths": {}
-      },
       "src/renderer/astryx-theme/type-scale.ts": {
         "bridgePaths": {},
         "environmentCapabilities": {},
@@ -1520,15 +1468,6 @@
         "actionFactories": [],
         "dependencyPaths": {}
       },
-      "src/renderer/locales/agent-graph-copy.ts": {
-        "bridgePaths": {},
-        "environmentCapabilities": {},
-        "hookCalls": {},
-        "lifecycleMethods": {},
-        "unresolvedDependencies": 0,
-        "actionFactories": [],
-        "dependencyPaths": {}
-      },
       "src/renderer/locales/artifact-copy.ts": {
         "bridgePaths": {},
         "environmentCapabilities": {},

apps/desktop/src/main/__tests__/agent-graph-panel-copy.test.ts

@@ -19,7 +19,7 @@
 
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
-import { getAgentGraphPanelCopy } from '../../renderer/locales/agent-graph-copy.js';
+import { getAgentGraphPanelCopy } from '../../renderer/features/agent-graph/testing.js';
 
 test('Traditional Chinese Agent Graph copy does not use Simplified fallbacks', () => {
   const copy = getAgentGraphPanelCopy('zh-TW');

apps/desktop/src/main/__tests__/agent-graph-panel-visibility.test.ts

@@ -25,7 +25,7 @@ import {
   isAgentGraphPanelDismissible,
   reconcileAgentGraphPanelDismissals,
   shouldShowAgentGraphPanel,
-} from '../../renderer/agent-graph-panel-visibility.js';
+} from '../../renderer/features/agent-graph/testing.js';
 
 describe('isAgentGraphLive', () => {
   it('treats in-flight statuses as live and settled ones as not', () => {