@dxos/plugin-assistant 0.8.4-main.406dc2a → 0.8.4-main.422d1c7879

package/src/containers/TracePanel/TracePanel.stories.tsx

@@ -0,0 +1,272 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom';
+import * as KeyValueStore from '@effect/platform/KeyValueStore';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import * as Schema from 'effect/Schema';
+import React, { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { AgentRequestBegin, AgentRequestEnd, CompleteBlock } from '@dxos/assistant';
+import { Database, Feed } from '@dxos/echo';
+import { Filter, Query } from '@dxos/echo';
+import { createFeedServiceLayer } from '@dxos/echo-db';
+import { Process, ServiceResolver, Trace } from '@dxos/functions';
+import { FeedTraceSink, ProcessManager } from '@dxos/functions-runtime';
+import { ObjectId } from '@dxos/keys';
+import { dbg } from '@dxos/log';
+import { OperationHandlerSet } from '@dxos/operation';
+import { ClientPlugin } from '@dxos/plugin-client';
+import { initializeIdentity } from '@dxos/plugin-client/testing';
+import { corePlugins } from '@dxos/plugin-testing';
+import { type Space, useSpaces } from '@dxos/react-client/echo';
+import { useQuery } from '@dxos/react-client/echo';
+import { IconButton, Panel, Toolbar } from '@dxos/react-ui';
+import { Timeline } from '@dxos/react-ui-components';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '../../translations';
+import { buildExecutionGraph } from './execution-graph';
+import { TracePanel } from './TracePanel';
+
+//
+// Helpers.
+//
+
+const delay = (ms: number) => Effect.promise(() => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+//
+// Simulated agent scenarios.
+//
+
+const agentScenarios: { prompt: string; tools: string[] }[] = [
+  {
+    prompt: 'Create an organization called "Cyberdyne Systems"',
+    tools: ['list-schemas', 'create-object'],
+  },
+  {
+    prompt: 'Search for all organizations and persons',
+    tools: ['list-schemas', 'query', 'query'],
+  },
+  {
+    prompt: 'Create a person named "John Connor"',
+    tools: ['create-object'],
+  },
+];
+
+/**
+ * Write a trace event and yield to the event loop so FeedTraceSink flushes it to ECHO before continuing.
+ */
+const writeAndFlush = <T,>(eventType: Trace.EventType<T>, payload: T) =>
+  Effect.gen(function* () {
+    yield* Trace.write(eventType, payload);
+    yield* Effect.promise(() => new Promise((resolve) => setTimeout(resolve, 100)));
+  });
+
+const SimulatedAgent = Process.make(
+  {
+    key: 'org.dxos.testing.process.agent',
+    input: Schema.Number,
+    output: Schema.Void,
+    services: [Trace.TraceService],
+  },
+  (ctx) =>
+    Effect.succeed({
+      onInput: (scenarioIndex: number) =>
+        Effect.gen(function* () {
+          const scenario = agentScenarios[scenarioIndex % agentScenarios.length];
+          const messageId = ObjectId.random();
+
+          // Agent begins processing.
+          yield* writeAndFlush(AgentRequestBegin, {});
+
+          // User message.
+          yield* writeAndFlush(CompleteBlock, {
+            messageId,
+            role: 'user',
+            block: { _tag: 'text', text: scenario.prompt },
+          });
+
+          // Simulate tool calls sequentially with delays.
+          for (const toolName of scenario.tools) {
+            const toolCallId = ObjectId.random();
+
+            // Tool call event.
+            yield* writeAndFlush(CompleteBlock, {
+              messageId,
+              role: 'assistant',
+              block: { _tag: 'toolCall', toolCallId, name: toolName, input: '{}', providerExecuted: false },
+            });
+
+            // Simulate tool execution time.
+            yield* delay(1_000 + Math.random() * 3_000);
+
+            // Tool result event.
+            yield* writeAndFlush(CompleteBlock, {
+              messageId,
+              role: 'assistant',
+              block: { _tag: 'toolResult', toolCallId, name: toolName, providerExecuted: false },
+            });
+          }
+
+          // Agent completes.
+          yield* writeAndFlush(AgentRequestEnd, {});
+          ctx.succeed();
+        }).pipe(Effect.orDie),
+      onAlarm: () => Effect.void,
+      onChildEvent: () => Effect.void,
+    }),
+);
+
+//
+// Story runtime — lightweight ProcessManager + FeedTraceSink.
+//
+
+type StoryRuntime = ManagedRuntime.ManagedRuntime<ProcessManager.ProcessManagerService, never>;
+
+const createStoryRuntime = (space: Space): StoryRuntime => {
+  const dbLayer = Database.layer(space.db);
+  const feedServiceLayer = createFeedServiceLayer(space.queues);
+  const traceSinkLayer = FeedTraceSink.layerLive.pipe(Layer.provide(dbLayer), Layer.provide(feedServiceLayer));
+
+  const layer = ProcessManager.layer().pipe(
+    Layer.provide(Layer.succeed(ServiceResolver.ServiceResolver, ServiceResolver.empty)),
+    Layer.provide(KeyValueStore.layerMemory),
+    Layer.provide(OperationHandlerSet.provide(OperationHandlerSet.empty)),
+    Layer.provideMerge(Registry.layer),
+    Layer.provide(traceSinkLayer),
+  );
+
+  return ManagedRuntime.make(layer);
+};
+
+//
+// Story component.
+//
+
+const DefaultStory = () => {
+  const [space] = useSpaces();
+  const runtimeRef = useRef<StoryRuntime | null>(null);
+  const invokeCounterRef = useRef(0);
+
+  useEffect(() => {
+    if (!space) {
+      return;
+    }
+
+    const runtime = createStoryRuntime(space);
+    runtimeRef.current = runtime;
+    return () => {
+      runtimeRef.current = null;
+      void runtime.dispose();
+    };
+  }, [space]);
+
+  const handleRunAgent = useCallback(() => {
+    const runtime = runtimeRef.current;
+    if (!runtime) {
+      return;
+    }
+
+    const scenarioIndex = invokeCounterRef.current++;
+    void runtime.runPromise(
+      Effect.gen(function* () {
+        const manager = yield* ProcessManager.ProcessManagerService;
+        const handle = yield* manager.spawn(SimulatedAgent);
+        yield* handle.submitInput(scenarioIndex);
+      }),
+    );
+  }, []);
+
+  if (!space) {
+    return <Loading />;
+  }
+
+  return (
+    <Panel.Root>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root>
+          <IconButton icon='ph--plus--regular' label='Start Agent' onClick={handleRunAgent} />
+        </Toolbar.Root>
+      </Panel.Toolbar>
+      <Panel.Content asChild>
+        <TracePanel role='article' space={space} attendableId={space.id} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+export const WithSnapshot: Story = {
+  render: () => {
+    const [space] = useSpaces();
+    const [feed] = useQuery(space?.db, FeedTraceSink.query);
+    const traceMessages = useQuery(
+      space?.db,
+      feed ? Query.select(Filter.everything()).from(feed) : Query.select(Filter.nothing()),
+    );
+    dbg(traceMessages);
+    const { commits, branches } = useMemo(() => buildExecutionGraph({ traceMessages }), [traceMessages]);
+    dbg(commits);
+    return <Timeline branches={branches} commits={commits} showTimestamp />;
+  },
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column' }),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        ClientPlugin({
+          types: [Feed.Feed, Trace.Message],
+          onClientInitialized: ({ client }) =>
+            Effect.promise(async () => {
+              await client.halo.createIdentity();
+              const data = await import('../../testing/data/trace-timeline.dx.json');
+              const space = await client.spaces.import({
+                filename: 'trace-events.dx.json',
+                contents: new TextEncoder().encode(JSON.stringify(data)),
+              });
+              await space.db.flush();
+            }),
+        }),
+      ],
+    }),
+  ],
+};
+
+const meta = {
+  title: 'plugins/plugin-assistant/containers/TracePanel',
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column' }),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        ClientPlugin({
+          types: [Feed.Feed, Trace.Message],
+          onClientInitialized: ({ client }) =>
+            Effect.gen(function* () {
+              yield* initializeIdentity(client);
+              const [space] = client.spaces.get();
+              yield* Effect.promise(() => space.waitUntilReady());
+            }),
+        }),
+      ],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/containers/TracePanel/TracePanel.tsx

@@ -0,0 +1,113 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom';
+import { useAtomValue } from '@effect-atom/atom-react';
+import { pipe } from 'effect/Function';
+import React, { useCallback, useMemo } from 'react';
+
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Filter, Query } from '@dxos/echo';
+import { AtomQuery } from '@dxos/echo-atom';
+import { Trace } from '@dxos/functions';
+import { FeedTraceSink, Process } from '@dxos/functions-runtime';
+import { DXN } from '@dxos/keys';
+import { useComputeRuntimeService } from '@dxos/plugin-automation/hooks';
+import { type Space } from '@dxos/react-client/echo';
+import { Panel } from '@dxos/react-ui';
+import { Timeline, type Commit } from '@dxos/react-ui-components';
+import { composable, mx } from '@dxos/ui-theme';
+
+import { ProcessTree } from '../../components';
+import { buildExecutionGraph } from './execution-graph';
+
+export type TracePanelProps = AppSurface.SpaceArticleProps;
+
+export const TracePanel = composable<HTMLDivElement, TracePanelProps>(({ space, ...props }, forwardedRef) => {
+  const { invokePromise } = useOperationInvoker();
+  const { branches, commits } = useExecutionGraph(space);
+
+  const handleCommitClick = useCallback(
+    (commit: Commit) => {
+      if (commit.link) {
+        const dxn = DXN.tryParse(commit.link)?.asEchoDXN();
+        if (dxn?.spaceId && dxn.echoId) {
+          // TODO(dmaretskyi): Navigates, but fails to open.
+          void invokePromise(LayoutOperation.Open, {
+            subject: [`${dxn.spaceId}:${dxn.echoId}`],
+          });
+        }
+      }
+    },
+    [invokePromise],
+  );
+
+  return (
+    <Panel.Root {...props} ref={forwardedRef}>
+      <Panel.Content className='grid grid-rows-[min-content_1fr]'>
+        <ActiveProcessList spaceId={space.id} />
+        <Timeline branches={branches} commits={commits} compact onCommitClick={handleCommitClick} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+});
+
+/**
+ * Separated into its own component because useComputeRuntimeService uses React's use() which requires a Suspense boundary.
+ */
+const ActiveProcessList = ({ spaceId }: { spaceId: Space['id'] }) => {
+  const runtime = useComputeRuntimeService(Process.ProcessMonitorService, spaceId);
+  const activeProcesses = useAtomValue(runtime?.processTreeAtom ?? atomEmpty);
+  if (activeProcesses.length === 0) {
+    return <div />;
+  }
+
+  return <ProcessTree classNames={mx('max-h-[8lh] px-2 border-b border-separator')} processes={activeProcesses} />;
+};
+
+// Stable ref.
+const atomEmpty = Atom.make(() => [] as const);
+
+type ExecutionGraph = {
+  branches: string[];
+  commits: Commit[];
+};
+
+type UseExecutionGraphOptions = {
+  eventLimit?: number;
+};
+
+const useExecutionGraph = (space: Space, { eventLimit }: UseExecutionGraphOptions = {}): ExecutionGraph => {
+  const atom = useMemo(() => getExecutionGraph(space, { eventLimit }), [space, eventLimit]);
+  return useAtomValue(atom);
+};
+
+const getExecutionGraph = (
+  space: Space,
+  { eventLimit = 100 }: UseExecutionGraphOptions = {},
+): Atom.Atom<ExecutionGraph> => {
+  return pipe(
+    AtomQuery.make(space.db, FeedTraceSink.query),
+    Atom.map((feeds) => {
+      // TODO(dmaretskyi): This should be possible in a single query with properly working limit(1) and feed > feed contents traversal.
+      return AtomQuery.make(
+        space.db,
+        feeds.length > 0
+          ? Query.type(Trace.Message).from(feeds[0])
+          : (Query.select(Filter.nothing()) as Query.Query<never>),
+      );
+    }),
+    (_) => Atom.make((get) => get(get(_))),
+    (_) =>
+      Atom.make((get) =>
+        buildExecutionGraph({
+          traceMessages: [...get(_)],
+          activeProcesses: [],
+          eventLimit,
+        }),
+      ),
+  );
+};

package/src/containers/TracePanel/dxn-extractor.test.ts

@@ -0,0 +1,153 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import {
+  extractDxnsFromObject,
+  extractDxnsFromString,
+  extractFirstDxnFromToolInput,
+  extractFirstDxnFromToolResult,
+} from './dxn-extractor';
+
+describe('dxn-extractor', () => {
+  describe('extractDxnsFromString', () => {
+    test('extracts plain DXN from string', ({ expect }) => {
+      const result = extractDxnsFromString('Found object dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts @dxn prefixed reference from string', ({ expect }) => {
+      const result = extractDxnsFromString('Reference to @dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4 in text');
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts multiple DXNs from string', ({ expect }) => {
+      const result = extractDxnsFromString(
+        'Objects: dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4 and @dxn:queue:data:SPACE:QUEUE:01KG7R1ZXWFMWQ4DA1Q6TN1DG5',
+      );
+      expect(result).toHaveLength(2);
+    });
+
+    test('deduplicates DXNs', ({ expect }) => {
+      const result = extractDxnsFromString(
+        'Same object dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4 and dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+      );
+      expect(result).toHaveLength(1);
+    });
+
+    test('returns empty array for string without DXNs', ({ expect }) => {
+      const result = extractDxnsFromString('No DXNs here');
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe('extractDxnsFromObject', () => {
+    test('extracts IPLD-style reference { "/": "dxn:..." }', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        '/': 'dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+      });
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts @dxn key reference { "@dxn": "dxn:..." }', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        '@dxn': 'dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+        name: 'Test',
+      });
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts reference block { _tag: "reference", reference: { dxn: ... } }', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        _tag: 'reference',
+        reference: {
+          dxn: 'dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+        },
+      });
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts DXN from nested object', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        data: {
+          items: [
+            {
+              ref: { '/': 'dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4' },
+            },
+          ],
+        },
+      });
+      expect(result).toHaveLength(1);
+    });
+
+    test('extracts DXN from string property', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        message: 'Created object dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+      });
+      expect(result).toHaveLength(1);
+    });
+
+    test('extracts DXN from array', ({ expect }) => {
+      const result = extractDxnsFromObject([
+        { '/': 'dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4' },
+        { '/': 'dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG5' },
+      ]);
+      expect(result).toHaveLength(2);
+    });
+
+    test('handles null and undefined', ({ expect }) => {
+      expect(extractDxnsFromObject(null)).toHaveLength(0);
+      expect(extractDxnsFromObject(undefined)).toHaveLength(0);
+    });
+  });
+
+  describe('extractFirstDxnFromToolInput', () => {
+    test('extracts DXN from JSON tool input', ({ expect }) => {
+      const input = JSON.stringify({
+        objectRef: { '/': 'dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4' },
+      });
+      const result = extractFirstDxnFromToolInput(input);
+      expect(result?.toString()).toBe('dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts DXN from invalid JSON string', ({ expect }) => {
+      const input = 'Invalid JSON but contains dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4';
+      const result = extractFirstDxnFromToolInput(input);
+      expect(result?.toString()).toBe('dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('returns undefined for input without DXNs', ({ expect }) => {
+      const input = JSON.stringify({ name: 'Test' });
+      const result = extractFirstDxnFromToolInput(input);
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('extractFirstDxnFromToolResult', () => {
+    test('extracts DXN from JSON tool result', ({ expect }) => {
+      const result = JSON.stringify({
+        created: { '/': 'dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4' },
+      });
+      const dxn = extractFirstDxnFromToolResult(result);
+      expect(dxn?.toString()).toBe('dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('returns undefined for undefined result', ({ expect }) => {
+      const dxn = extractFirstDxnFromToolResult(undefined);
+      expect(dxn).toBeUndefined();
+    });
+
+    test('returns undefined for result without DXNs', ({ expect }) => {
+      const result = JSON.stringify({ success: true });
+      const dxn = extractFirstDxnFromToolResult(result);
+      expect(dxn).toBeUndefined();
+    });
+  });
+});