fix(desktop): isolate agent graph feature

Generated-by: OpenAI Codex
Generated-by: Claude Code

Author: orangeCatDeveloper

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-app-update.ts",
     "src/renderer/app-shell-chat-actions.ts",
     "src/renderer/app-shell-chrome-actions.tsx",
@@ -880,7 +877,6 @@
         "dependencyPaths": {
           "../preload/bridge-contract.js": 1,
           "../preload/transcript-contract.js": 1,
-          "./agent-graph-panel": 1,
           "./app-shell-app-update": 1,
           "./app-shell-chat-actions": 1,
           "./app-shell-chrome-actions": 1,
@@ -908,6 +904,7 @@
           "./desktop-execution-boundary-surface": 1,
           "./desktop-slash-command": 1,
           "./error-boundary": 1,
+          "./features/agent-graph": 1,
           "./features/conversation": 1,
           "./features/goals": 1,
           "./features/module-hub": 1,
@@ -1133,57 +1130,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,
-          "@astryxdesign/core/Banner": 1,
-          "@astryxdesign/core/Button": 1,
-          "@astryxdesign/core/EmptyState": 1,
-          "@astryxdesign/core/Spinner": 1,
-          "@maka/core/ui-locale": 1,
-          "@maka/runtime-host/client": 1,
-          "@maka/runtime-host/protocol": 1,
-          "@maka/runtime/stream-graph-read-model": 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/app-update-install.ts": {
         "bridgePaths": {},
         "environmentCapabilities": {},

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

@@ -24,7 +24,7 @@ import {
   isAgentGraphPanelDismissible,
   reconcileAgentGraphPanelDismissals,
   shouldShowAgentGraphPanel,
-} from '../../renderer/agent-graph-panel-visibility.js';
+} from '../../renderer/features/agent-graph/testing.js';
 
 describe('isAgentGraphPanelDismissible', () => {
   it('allows hiding a graph that no longer has active work', () => {

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

@@ -24,7 +24,11 @@ import { act, createElement } from 'react';
 import { createRoot, type Root } from 'react-dom/client';
 import type { AgentGraphClientSnapshot } from '@maka/runtime/stream-graph-read-model';
 import type { AgentGraphEpochSummary } from '@maka/runtime-host/protocol';
-import { AgentGraphPanel } from '../../renderer/agent-graph-panel.js';
+import {
+  AgentGraphPanel,
+  AgentGraphServicesProvider,
+  type AgentGraphServices,
+} from '../../renderer/features/agent-graph/testing.js';
 
 type GraphListener = () => void;
 
@@ -112,6 +116,7 @@ function installGraphRenderer(
   renderSession(sessionId: string): Promise<void>;
   holdNextEpochList(sessionId: string): DeferredRead;
   holdNextSnapshot(graphId: string): DeferredRead;
+  holdNextInspection(operatorId: string): DeferredRead;
   holdNextStop(sessionId: string): DeferredRead;
   setCurrentWithoutNotification(next: AgentGraphClientSnapshot): void;
   notify(): void;
@@ -161,6 +166,7 @@ function installGraphRenderer(
   const listeners = new Set<GraphListener>();
   const epochListGates = new Map<string, DeferredReadGate>();
   const snapshotGates = new Map<string, DeferredReadGate>();
+  const inspectionGates = new Map<string, DeferredReadGate>();
   const stopGates = new Map<string, DeferredReadGate>();
   const stopCalls: Array<{ sessionId: string; expectedGraphId: string }> = [];
   let fullEpochReads = 0;
@@ -184,7 +190,7 @@ function installGraphRenderer(
       truncated: false,
     };
   };
-  (window as unknown as { maka: unknown }).maka = {
+  const services: AgentGraphServices = {
     graphs: {
       listEpochs: async (sessionId: string) => {
         fullEpochReads += 1;
@@ -216,6 +222,12 @@ function installGraphRenderer(
       },
       inspectOperator: async (sessionId: string, operatorId: string, graphId?: string) => {
         inspectionReads.set(operatorId, (inspectionReads.get(operatorId) ?? 0) + 1);
+        const gate = inspectionGates.get(operatorId);
+        if (gate) {
+          inspectionGates.delete(operatorId);
+          gate.markStarted();
+          await gate.waitForRelease;
+        }
         const snapshot = graphId ? snapshots.get(graphId) : undefined;
         const operator = snapshot?.operators.find((candidate) => candidate.operatorId === operatorId);
         if (!snapshot || snapshot.rootSessionId !== sessionId || !operator) {
@@ -275,6 +287,7 @@ function installGraphRenderer(
       },
     },
   };
+  (window as unknown as { maka: unknown }).maka = services;
 
   const container = document.querySelector('#root');
   assert.ok(container);
@@ -312,12 +325,16 @@ function installGraphRenderer(
     async renderSession(sessionId) {
       await act(async () => {
         root.render(
-          createElement(AgentGraphPanel, {
-            rootSessionId: sessionId,
-            enabled: true,
-            locale: 'en',
-            onOpenSession: () => undefined,
-          }),
+          createElement(
+            AgentGraphServicesProvider,
+            { services },
+            createElement(AgentGraphPanel, {
+              rootSessionId: sessionId,
+              enabled: true,
+              locale: 'en',
+              onOpenSession: () => undefined,
+            }),
+          ),
         );
         await Promise.resolve();
       });
@@ -332,6 +349,11 @@ function installGraphRenderer(
       snapshotGates.set(graphId, gate);
       return gate;
     },
+    holdNextInspection(operatorId) {
+      const gate = deferredReadGate();
+      inspectionGates.set(operatorId, gate);
+      return gate;
+    },
     holdNextStop(sessionId) {
       const gate = deferredReadGate();
       stopGates.set(sessionId, gate);
@@ -347,12 +369,16 @@ async function renderPanel(
   const harness = installGraphRenderer(initial);
   await act(async () => {
     harness.root.render(
-      createElement(AgentGraphPanel, {
-        rootSessionId: 'session-1',
-        enabled: true,
-        locale: 'en',
-        onOpenSession: () => undefined,
-      }),
+      createElement(
+        AgentGraphServicesProvider,
+        { services: (window as unknown as { maka: AgentGraphServices }).maka },
+        createElement(AgentGraphPanel, {
+          rootSessionId: 'session-1',
+          enabled: true,
+          locale: 'en',
+          onOpenSession: () => undefined,
+        }),
+      ),
     );
     await Promise.resolve();
   });
@@ -536,6 +562,47 @@ describe('AgentGraphPanel dismiss', () => {
     await act(async () => harness.root.unmount());
   });
 
+  it('keeps inspected details visible while a live refresh is pending', async () => {
+    const graph = snapshot({
+      graphId: 'graph-inspection-refresh',
+      status: 'active',
+      operators: [graphOperator('a', ['work-a'])],
+      work: [graphWork('work-a', 'a', 'Initial inspection detail')],
+    });
+    const harness = await renderPanel(graph);
+    const node = harness.container.querySelector('.maka-agent-graph-node');
+    assert.ok(node);
+    await act(async () => {
+      (node as HTMLElement).click();
+      await Promise.resolve();
+    });
+    const details = harness.container.querySelector(
+      '[aria-label="Operator details: agent-a"]',
+    );
+    assert.ok(details);
+    assert.match(details.textContent ?? '', /Initial inspection detail/);
+
+    const inspection = harness.holdNextInspection('a');
+    await harness.setSnapshot({
+      ...graph,
+      snapshotVersion: '2',
+      work: [graphWork('work-a', 'a', 'Refreshed inspection detail')],
+    });
+    await inspection.started;
+
+    assert.equal(details.getAttribute('aria-busy'), 'true');
+    assert.match(details.textContent ?? '', /Initial inspection detail/);
+    assert.doesNotMatch(details.textContent ?? '', /Refreshed inspection detail/);
+
+    await act(async () => {
+      inspection.release();
+      await Promise.resolve();
+    });
+    assert.equal(details.getAttribute('aria-busy'), 'false');
+    assert.match(details.textContent ?? '', /Refreshed inspection detail/);
+    await act(async () => harness.root.unmount());
+  });
+
   it('keeps keyboard order visual and reveals a retained selection', async () => {
     const harness = await renderPanel(
       snapshot({
@@ -670,17 +737,7 @@ describe('AgentGraphPanel dismiss', () => {
     const current = snapshot({ graphId: 'graph-2', status: 'active' });
     const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
     const harness = installGraphRenderer(current, [previous]);
-    await act(async () => {
-      harness.root.render(
-        createElement(AgentGraphPanel, {
-          rootSessionId: 'session-1',
-          enabled: true,
-          locale: 'en',
-          onOpenSession: () => undefined,
-        }),
-      );
-      await Promise.resolve();
-    });
+    await harness.renderSession('session-1');
 
     const selector = harness.container.querySelector('[role="combobox"]');
     assert.ok(selector);
@@ -869,17 +926,7 @@ describe('AgentGraphPanel dismiss', () => {
     const current = snapshot({ graphId: 'graph-2', status: 'active' });
     const previous = snapshot({ graphId: 'graph-1', status: 'completed' });
     const harness = installGraphRenderer(current, [previous]);
-    await act(async () => {
-      harness.root.render(
-        createElement(AgentGraphPanel, {
-          rootSessionId: 'session-1',
-          enabled: true,
-          locale: 'en',
-          onOpenSession: () => undefined,
-        }),
-      );
-      await Promise.resolve();
-    });
+    await harness.renderSession('session-1');
 
     const selector = harness.container.querySelector('[role="combobox"]');
     assert.ok(selector);

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

@@ -20,7 +20,7 @@
 import { deferred } from '@maka/core/test-only/async-primitives';
 import { strict as assert } from 'node:assert';
 import { describe, it } from 'node:test';
-import { createAgentGraphRefreshScheduler } from '../../renderer/agent-graph-refresh.js';
+import { createAgentGraphRefreshScheduler } from '../../renderer/features/agent-graph/testing.js';
 async function tick(): Promise<void> {
   await new Promise((resolve) => setImmediate(resolve));
 }

apps/desktop/src/main/__tests__/agent-graph-services-adapter.test.ts

@@ -0,0 +1,74 @@
+/*
+ * 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 { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+import type { MakaBridge } from '../../preload/bridge-contract.js';
+import { createDesktopAgentGraphServices } from '../../renderer/platform/desktop/create-agent-graph-services.js';
+
+describe('createDesktopAgentGraphServices', () => {
+  it('maps the narrow Graph contract to the Desktop bridge', async () => {
+    const calls: Array<{ name: string; args: unknown[] }> = [];
+    let changeHandler: (() => void) | undefined;
+    let changes = 0;
+    let disposed = 0;
+    const graphs = new Proxy(
+      {},
+      {
+        get: (_target, property) =>
+          (...args: unknown[]) => {
+            calls.push({ name: String(property), args });
+            if (property === 'subscribe') {
+              changeHandler = args[1] as () => void;
+              return () => {
+                disposed += 1;
+              };
+            }
+            return Promise.resolve(property);
+          },
+      },
+    );
+    const services = createDesktopAgentGraphServices({ graphs } as unknown as Pick<
+      MakaBridge,
+      'graphs'
+    >);
+
+    await services.graphs.listEpochs('session-1');
+    await services.graphs.listCurrentEpochs('session-1');
+    await services.graphs.getSnapshot('session-1', { graphId: 'graph-1' });
+    await services.graphs.inspectOperator('session-1', 'operator-1', 'graph-1');
+    await services.graphs.stop('session-1', 'graph-1');
+    const unsubscribe = services.graphs.subscribe('session-1', () => {
+      changes += 1;
+    });
+    changeHandler?.();
+    unsubscribe();
+
+    assert.deepEqual(calls, [
+      { name: 'listEpochs', args: ['session-1'] },
+      { name: 'listCurrentEpochs', args: ['session-1'] },
+      { name: 'getSnapshot', args: ['session-1', { graphId: 'graph-1' }] },
+      { name: 'inspectOperator', args: ['session-1', 'operator-1', 'graph-1'] },
+      { name: 'stop', args: ['session-1', 'graph-1'] },
+      { name: 'subscribe', args: ['session-1', changeHandler] },
+    ]);
+    assert.equal(changes, 1);
+    assert.equal(disposed, 1);
+  });
+});

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

@@ -30,7 +30,7 @@ import {
   layoutAgentGraph,
   revealAgentGraphNode,
   scheduledWorkPresentation,
-} from '../../renderer/agent-graph-topology.js';
+} from '../../renderer/features/agent-graph/testing.js';
 
 describe('layoutAgentGraph', () => {
   it('preserves graph operator status semantics', () => {

apps/desktop/src/renderer/app-shell.tsx

@@ -85,7 +85,7 @@ import {
 import { deriveWorkspaceReadinessRecovery } from './workspace-readiness-recovery';
 import { LiveTurnReconciler } from './live-turn-reconciler';
 import { useAppShellSessionUiReads } from './use-app-shell-session-ui-reads';
-import { AgentGraphPanel } from './agent-graph-panel';
+import { AgentGraphPanel } from './features/agent-graph';
 import { ChatComposerRegion } from './chat-composer-region';
 import {
   WorkbarHost,