@dxos/plugin-assistant 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/containers/TracePanel/TracePanel.tsx

@@ -0,0 +1,257 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom';
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Data from 'effect/Data';
+import * as Duration from 'effect/Duration';
+import { pipe } from 'effect/Function';
+import React, { useCallback, useDeferredValue, useEffect, useMemo, useState } from 'react';
+
+import { Capabilities } from '@dxos/app-framework';
+import { useCapability, useAtomCapability, useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Process, Trace } from '@dxos/compute';
+import { Filter, Query } from '@dxos/echo';
+import { FeedTraceSink } from '@dxos/functions-runtime';
+import { EID } from '@dxos/keys';
+import { type Space } from '@dxos/react-client/echo';
+import { ScrollContainer } from '@dxos/react-ui';
+import { composable, composableProps } from '@dxos/react-ui';
+import { useAttentionAttributes } from '@dxos/react-ui-attention';
+import { Timeline, type Commit } from '@dxos/react-ui-components';
+import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import { mx } from '@dxos/ui-theme';
+
+import { ProcessTree, ProcessTreeProps } from '#components';
+import { buildExecutionGraph, type ExecutionGraph } from '#execution-graph';
+import { AssistantCapabilities } from '#types';
+
+export type TracePanelProps = AppSurface.SpaceArticleProps<Pick<ProcessTreeProps, 'onProcessTerminate'>>;
+
+export const TracePanel = composable<HTMLDivElement, TracePanelProps>(
+  ({ space, attendableId, onProcessTerminate, ...props }, forwardedRef) => {
+    const attentionAttrs = useAttentionAttributes(attendableId);
+    const { invokePromise } = useOperationInvoker();
+    const settings = useAtomCapability(AssistantCapabilities.Settings);
+    const tracePanelDebug = settings.tracePanelDebug ?? false;
+
+    // `useDeferredValue` batches update bursts, works together with `React.memo`.
+    // See the comment in `ProcessTreeContainer` for more details.
+    const { branches, commits, spanTree, details } = useDeferredValue(useExecutionGraph(space));
+
+    // Debug hatch (dev builds only): expose the raw trace messages (the exact `buildExecutionGraph`
+    // input) so a real trace can be captured as a test fixture. While the TracePanel is mounted, run
+    // `dxosDumpTrace()` in the console — it copies the serialized `Trace.Message[]` to the clipboard
+    // (and logs it). Gated on `import.meta.env.DEV` so it's stripped from production builds.
+    const traceMessages = useTraceMessages(space);
+    useEffect(() => {
+      if (!import.meta.env.DEV) {
+        return;
+      }
+      // Attach a debug hatch to the global object (a genuine global-augmentation boundary).
+      const debugGlobal = globalThis as typeof globalThis & { dxosDumpTrace?: () => string };
+      debugGlobal.dxosDumpTrace = () => {
+        const data = traceMessages.map((message) => ({
+          meta: message.meta,
+          isEphemeral: message.isEphemeral,
+          events: message.events,
+        }));
+        const json = JSON.stringify(data, null, 2);
+        // eslint-disable-next-line no-console
+        console.log(json);
+        void navigator.clipboard?.writeText(json);
+        return `dxosDumpTrace: ${data.length} message(s) copied to clipboard`;
+      };
+      return () => {
+        delete debugGlobal.dxosDumpTrace;
+      };
+    }, [traceMessages]);
+
+    const [selectedCommit, setSelectedCommit] = useState<Commit | undefined>();
+    const handleCommitSelect = useCallback(
+      (commit: Commit | undefined) => {
+        setSelectedCommit(commit);
+        if (commit?.link) {
+          const echoUri = EID.tryParse(commit.link);
+          const spaceId = echoUri ? EID.getSpaceId(echoUri) : undefined;
+          const objectId = echoUri ? EID.getEntityId(echoUri) : undefined;
+          if (spaceId && objectId) {
+            // TODO(dmaretskyi): Navigates, but fails to open.
+            void invokePromise(LayoutOperation.Open, {
+              subject: [`${spaceId}:${objectId}`],
+            });
+          }
+        }
+      },
+      [invokePromise, setSelectedCommit],
+    );
+
+    // Select current branch.
+    const [currentBranch, setCurrentBranch] = useState<string | null>(null);
+    const handleProcessSelect = useCallback(
+      (process: Process.Info) => {
+        const branch = branches.find((branch) => branch === process.pid.toString());
+        if (branch) {
+          setCurrentBranch(branch);
+        }
+      },
+      [branches],
+    );
+
+    return (
+      <div
+        {...composableProps(props, {
+          ...attentionAttrs,
+          classNames: mx(
+            'h-full grid divide-y divide-separator',
+            !tracePanelDebug && selectedCommit
+              ? 'grid-rows-[minmax(0,160px)_1fr_minmax(0,206px)]'
+              : 'grid-rows-[minmax(0,160px)_1fr]',
+          ),
+        })}
+        ref={forwardedRef}
+      >
+        <ProcessTreeContainer onProcessSelect={handleProcessSelect} onProcessTerminate={onProcessTerminate} />
+
+        <ScrollContainer.Root pin>
+          <ScrollContainer.Content thin>
+            <ScrollContainer.Fade />
+            <ScrollContainer.Viewport>
+              {tracePanelDebug ? (
+                <Syntax.Root data={spanTree}>
+                  <Syntax.Content>
+                    <Syntax.Viewport>
+                      <Syntax.Code className='text-xs' />
+                    </Syntax.Viewport>
+                  </Syntax.Content>
+                </Syntax.Root>
+              ) : (
+                <Timeline
+                  compact
+                  commits={commits}
+                  branches={branches}
+                  currentBranch={currentBranch}
+                  onSelect={handleCommitSelect}
+                />
+              )}
+            </ScrollContainer.Viewport>
+            <ScrollContainer.ScrollDownButton />
+          </ScrollContainer.Content>
+        </ScrollContainer.Root>
+
+        {!tracePanelDebug && selectedCommit && (
+          <Syntax.Root data={details[selectedCommit.id] ?? selectedCommit}>
+            <Syntax.Content>
+              <Syntax.Viewport>
+                <Syntax.Code className='text-xs' />
+              </Syntax.Viewport>
+            </Syntax.Content>
+          </Syntax.Root>
+        )}
+      </div>
+    );
+  },
+);
+
+// Stable ref.
+const atomEmpty = Atom.make(() => [] as const);
+
+type UseExecutionGraphOptions = {
+  eventLimit?: number;
+};
+
+const useExecutionGraph = (space: Space, { eventLimit }: UseExecutionGraphOptions = {}): ExecutionGraph => {
+  const monitor = useCapability(Capabilities.ProcessMonitor);
+  const processesAtom = monitor?.processTreeAtom ?? atomEmpty;
+
+  const atom = useMemo(
+    () => getExecutionGraph(space, processesAtom, { eventLimit }),
+    [space, processesAtom, eventLimit],
+  );
+
+  return useAtomValue(atom);
+};
+
+/**
+ * Atom of the raw trace messages for a space — the exact `Trace.Message[]` fed into
+ * `buildExecutionGraph`. Shared by the execution graph and the debug trace export.
+ */
+const getTraceMessagesAtom = (space: Space): Atom.Atom<readonly Trace.Message[]> =>
+  pipe(
+    space.db.query(FeedTraceSink.query).atom,
+    Atom.map(
+      (feeds) =>
+        // TODO(dmaretskyi): This should be possible in a single query with properly working limit(1) and feed > feed contents traversal.
+        space.db.query(
+          feeds.length > 0
+            ? Query.type(Trace.Message).from(feeds[0])
+            : (Query.select(Filter.nothing()) as Query.Query<never>),
+        ).atom,
+    ),
+    (atom) => Atom.make((get) => get(get(atom))),
+  );
+
+/**
+ * Returns the raw trace messages for a space (used by the debug trace export).
+ */
+const useTraceMessages = (space: Space): readonly Trace.Message[] => {
+  const atom = useMemo(() => getTraceMessagesAtom(space), [space]);
+  return useAtomValue(atom);
+};
+
+const getExecutionGraph = (
+  space: Space,
+  processesAtom: Atom.Atom<readonly Process.Info[]>,
+  { eventLimit = 100 }: UseExecutionGraphOptions = {},
+): Atom.Atom<ExecutionGraph> => {
+  const traceMessages = getTraceMessagesAtom(space);
+
+  const activeProcesses = pipe(
+    processesAtom,
+    Atom.debounce(Duration.millis(500)),
+    Atom.map((processes) =>
+      // `Data.array` does structural comparison on the array elements.
+      Data.array(
+        processes
+          .filter((process) => process.state === Process.State.RUNNING || process.state === Process.State.HYBERNATING)
+          .map(Data.struct),
+      ),
+    ),
+  );
+
+  return Atom.make((get) =>
+    buildExecutionGraph({
+      traceMessages: get(traceMessages),
+      activeProcesses: get(activeProcesses),
+      eventLimit,
+    }),
+  );
+};
+TracePanel.displayName = 'TracePanel';
+
+// Isolate `ProcessTree` updates from the rest of the panel.
+// TODO(dmaretskyi): Currently not useful since `useExecutionGraph` also pulls in the updates.
+const ProcessTreeContainer = ({
+  onProcessSelect,
+  onProcessTerminate,
+}: Pick<ProcessTreeProps, 'onProcessSelect' | 'onProcessTerminate'>) => {
+  const monitor = useCapability(Capabilities.ProcessMonitor);
+  const processes = useAtomValue(
+    useMemo(() => monitor?.processTreeAtom.pipe(Atom.debounce(Duration.millis(500))) ?? atomEmpty, [monitor]),
+  );
+
+  // `processes` updates in bursts (about 14 updates per navigation).
+  // `useDeferredValue` will debounce update propagation, returning stale value for short periods.
+  // NOTE: `ProcessTree` MUST use `React.memo`, otherwise this will not work.
+  const processesDeferred = useDeferredValue(processes);
+  return (
+    <ProcessTree
+      processes={processesDeferred}
+      onProcessSelect={onProcessSelect}
+      onProcessTerminate={onProcessTerminate}
+    />
+  );
+};

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

@@ -0,0 +1,153 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import {
+  extractDxnsFromObject,
+  extractDxnFromString,
+  extractFirstDxnFromToolInput,
+  extractFirstDxnFromToolResult,
+} from './dxn-extractor';
+
+describe('dxn-extractor', () => {
+  describe('extractDxnFromString', () => {
+    test('extracts plain DXN from string', ({ expect }) => {
+      const result = extractDxnFromString('Found object echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts @-prefixed reference from string', ({ expect }) => {
+      const result = extractDxnFromString('Reference to @echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4 in text');
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts multiple references from string', ({ expect }) => {
+      const result = extractDxnFromString(
+        'Objects: echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4 and @echo://BBBBBBBBBBBBBBBBBBBBBBBBBB/01KG7R1ZXWFMWQ4DA1Q6TN1DG5',
+      );
+      expect(result).toHaveLength(2);
+    });
+
+    test('deduplicates DXNs', ({ expect }) => {
+      const result = extractDxnFromString(
+        'Same object echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4 and echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+      );
+      expect(result).toHaveLength(1);
+    });
+
+    test('returns empty array for string without DXNs', ({ expect }) => {
+      const result = extractDxnFromString('No DXNs here');
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe('extractDxnsFromObject', () => {
+    test('extracts IPLD-style reference { "/": "echo:..." }', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        '/': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+      });
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts @uri key reference { "@uri": "echo:..." }', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        '@uri': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+        name: 'Test',
+      });
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts reference block { _tag: "reference", reference: { uri: ... } }', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        _tag: 'reference',
+        reference: {
+          uri: 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+        },
+      });
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts DXN from nested object', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        data: {
+          items: [
+            {
+              ref: { '/': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4' },
+            },
+          ],
+        },
+      });
+      expect(result).toHaveLength(1);
+    });
+
+    test('extracts DXN from string property', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        message: 'Created object echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+      });
+      expect(result).toHaveLength(1);
+    });
+
+    test('extracts DXN from array', ({ expect }) => {
+      const result = extractDxnsFromObject([
+        { '/': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4' },
+        { '/': '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: { '/': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4' },
+      });
+      const result = extractFirstDxnFromToolInput(input);
+      expect(result?.toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts DXN from invalid JSON string', ({ expect }) => {
+      const input = 'Invalid JSON but contains echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4';
+      const result = extractFirstDxnFromToolInput(input);
+      expect(result?.toString()).toBe('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: { '/': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4' },
+      });
+      const dxn = extractFirstDxnFromToolResult(result);
+      expect(dxn?.toString()).toBe('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();
+    });
+  });
+});

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

@@ -0,0 +1,166 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { URI } from '@dxos/keys';
+
+/**
+ * Patterns for extracting references from tool call params/results.
+ *
+ * Supported formats:
+ * - `{ "/": "echo:…" | "dxn:…" }` - IPLD-style encoded references
+ * - `{ "@uri": "echo:…" }` - Self URI key
+ * - `@echo:…` / `@dxn:…` - In-text references (with @ prefix)
+ * - `echo:…` / `dxn:…` - Plain URI strings
+ */
+
+/**
+ * Regex matching a canonical reference URI: an `echo:` EID or a `dxn:<nsid>[:<version>]` type DXN.
+ */
+const URI_PATTERN = /(?:echo:\/{1,3}[A-Za-z0-9/]+|dxn:[a-zA-Z][a-zA-Z0-9-]*(?:\.[a-zA-Z0-9-]+)+(?::\d+\.\d+\.\d+)?)/g;
+
+/**
+ * Regex matching an `@`-prefixed reference URI in text.
+ */
+const AT_URI_PATTERN = new RegExp(`@(${URI_PATTERN.source})`, 'g');
+
+/**
+ * Extracts all reference URIs from a string.
+ */
+export const extractDxnFromString = (text: string): URI.URI[] => {
+  const dxns: URI.URI[] = [];
+  const seen = new Set<string>();
+
+  const add = (uri: string) => {
+    if (!seen.has(uri)) {
+      dxns.push(URI.make(uri));
+      seen.add(uri);
+    }
+  };
+
+  // Match @-prefixed references.
+  let match;
+  while ((match = AT_URI_PATTERN.exec(text)) !== null) {
+    add(match[1]);
+  }
+
+  // Match plain URI strings.
+  while ((match = URI_PATTERN.exec(text)) !== null) {
+    add(match[0]);
+  }
+
+  return dxns;
+};
+
+/**
+ * Extracts DXN references from a JSON object.
+ * Handles IPLD-style references `{ "/": "dxn:..." }` and `{ "@dxn": "dxn:..." }`.
+ */
+export const extractDxnsFromObject = (obj: unknown): URI.URI[] => {
+  const dxns: URI.URI[] = [];
+  const seen = new Set<string>();
+
+  const addDxn = (dxnStr: string) => {
+    if (!seen.has(dxnStr)) {
+      dxns.push(URI.make(dxnStr));
+      seen.add(dxnStr);
+    }
+  };
+
+  const traverse = (value: unknown): void => {
+    if (value === null || value === undefined) {
+      return;
+    }
+
+    if (typeof value === 'string') {
+      // Check if the string itself is a reference URI.
+      if (value.startsWith('echo:') || value.startsWith('dxn:')) {
+        addDxn(value);
+      } else if (value.startsWith('@echo:') || value.startsWith('@dxn:')) {
+        addDxn(value.slice(1));
+      }
+      // Also extract references from within the string.
+      const extracted = extractDxnFromString(value);
+      for (const dxn of extracted) {
+        addDxn(dxn);
+      }
+      return;
+    }
+
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        traverse(item);
+      }
+      return;
+    }
+
+    if (typeof value === 'object') {
+      const record = value as Record<string, unknown>;
+
+      // Check for IPLD-style reference: { "/": "echo:…" | "dxn:…" }
+      if ('/' in record && typeof record['/'] === 'string') {
+        const refStr = record['/'];
+        if (typeof refStr === 'string' && (refStr.startsWith('echo:') || refStr.startsWith('dxn:'))) {
+          addDxn(refStr);
+        }
+      }
+
+      // Check for self URI key: { "@uri": "echo:…" }
+      const selfUri = record['@uri'];
+      if (typeof selfUri === 'string' && (selfUri.startsWith('dxn:') || selfUri.startsWith('echo:'))) {
+        addDxn(selfUri);
+      }
+
+      // Check for reference blocks: { _tag: 'reference', reference: { uri: ... } }
+      if (record._tag === 'reference' && record.reference && typeof record.reference === 'object') {
+        const ref = record.reference as Record<string, unknown>;
+        const refUri = ref.uri;
+        if (typeof refUri === 'string' && (refUri.startsWith('echo:') || refUri.startsWith('dxn:'))) {
+          addDxn(refUri);
+        }
+      }
+
+      // Recursively traverse all properties.
+      for (const key of Object.keys(record)) {
+        traverse(record[key]);
+      }
+    }
+  };
+
+  traverse(obj);
+  return dxns;
+};
+
+/**
+ * Extracts the first DXN from a tool call input string (JSON).
+ */
+export const extractFirstDxnFromToolInput = (input: string): URI.URI | undefined => {
+  try {
+    const parsed = JSON.parse(input);
+    const dxns = extractDxnsFromObject(parsed);
+    return dxns[0];
+  } catch {
+    // If JSON parsing fails, try to extract from the raw string.
+    const dxns = extractDxnFromString(input);
+    return dxns[0];
+  }
+};
+
+/**
+ * Extracts the first DXN from a tool result string (JSON).
+ */
+export const extractFirstDxnFromToolResult = (result: string | undefined): URI.URI | undefined => {
+  if (!result) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(result);
+    const dxns = extractDxnsFromObject(parsed);
+    return dxns[0];
+  } catch {
+    // If JSON parsing fails, try to extract from the raw string.
+    const dxns = extractDxnFromString(result);
+    return dxns[0];
+  }
+};

package/src/containers/TracePanel/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { TracePanel } from './TracePanel';
+
+export * from './TracePanel';
+
+export default TracePanel;

package/src/containers/TracePanel/testing/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './simulated-agent';
+export * from './snapshot-playback';