@dxos/plugin-assistant 0.8.4-main.c4373fc → 0.8.4-main.d9fc60f731

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

@@ -0,0 +1,319 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React, { PropsWithChildren, type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { useProcessManagerRuntime } from '@dxos/app-framework/ui';
+import { addEventListener } from '@dxos/async';
+import { Process, Trace } from '@dxos/compute';
+import { ProcessManager } from '@dxos/compute-runtime';
+import { Feed, Filter, Query } from '@dxos/echo';
+import { FeedTraceSink } from '@dxos/functions-runtime';
+import { log } from '@dxos/log';
+import { AutomationPlugin } from '@dxos/plugin-automation/testing';
+import { ClientPlugin } from '@dxos/plugin-client/testing';
+import { initializeIdentity } from '@dxos/plugin-client/testing';
+import { corePlugins } from '@dxos/plugin-testing';
+import { useQuery, useSpaces } from '@dxos/react-client/echo';
+import { IconButton, Panel, ScrollContainer, Toolbar } from '@dxos/react-ui';
+import { Timeline } from '@dxos/react-ui-components';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { buildExecutionGraph } from '#execution-graph';
+import { AssistantPlugin } from '#plugin';
+import { translations } from '#translations';
+
+// TODO(dmaretskyi): testing.ts module shadows the ./testing dir.
+import { initClientFromSpaceSnapshot } from '../../testing/snapshot';
+import { PLAYBACK_INTERVAL_MS, STEP_STORAGE_KEY, SimulatedAgent, useLocalStorageNumber } from './testing';
+import { TracePanel } from './TracePanel';
+
+type BaseStoryProps = PropsWithChildren<{
+  toolbar: ReactNode;
+}>;
+
+const BaseStory = ({ children, toolbar }: BaseStoryProps) => (
+  <Panel.Root>
+    <Panel.Toolbar asChild>{toolbar}</Panel.Toolbar>
+    <Panel.Content asChild>{children}</Panel.Content>
+  </Panel.Root>
+);
+
+const DefaultStory = () => {
+  const [space] = useSpaces();
+  const runtime = useProcessManagerRuntime();
+
+  const handleStart = useCallback(() => {
+    if (!runtime) {
+      return;
+    }
+
+    void runtime.runPromise(
+      Effect.gen(function* () {
+        const manager = yield* ProcessManager.Service;
+        const handle = yield* manager.spawn(SimulatedAgent);
+        yield* handle.submitInput(Math.floor(Math.random() * 1_000));
+        log.info('submitInput', { handle });
+      }),
+    );
+  }, [runtime]);
+
+  // TODO(burdon): Implement.
+  const handleStop = useCallback(
+    (process: Process.Info) => {
+      log.info('stop', { process });
+    },
+    [runtime],
+  );
+
+  return (
+    <BaseStory
+      toolbar={
+        <Toolbar.Root>
+          <IconButton icon='ph--plus--regular' label='Start Agent' onClick={handleStart} />
+        </Toolbar.Root>
+      }
+    >
+      <TracePanel space={space} attendableId={space.id} onProcessTerminate={handleStop} />
+    </BaseStory>
+  );
+};
+
+const SnapshotStory = () => {
+  const [space] = useSpaces();
+  const [feed] = useQuery(space?.db, FeedTraceSink.query);
+
+  // All messages.
+  const allMessages = useQuery(
+    space?.db,
+    feed ? Query.select(Filter.everything()).from(feed) : Query.select(Filter.nothing()),
+  );
+
+  // Sort by first event timestamp so playback order is chronological regardless of query ordering.
+  const sortedMessages = useMemo(
+    () => [...allMessages].sort((a, b) => (a.events[0]?.timestamp ?? 0) - (b.events[0]?.timestamp ?? 0)),
+    [allMessages],
+  );
+
+  const total = sortedMessages.length;
+  const [step, setStep, stepHydrated] = useLocalStorageNumber(STEP_STORAGE_KEY, 0);
+  const [playing, setPlaying] = useState(false);
+
+  useEffect(() => {
+    setStep((current) => Math.min(Math.max(current, 0), total));
+  }, [total, setStep]);
+
+  // Start with all messages loaded once the snapshot first arrives; afterwards the user controls `step`.
+  // Skip the auto-init if we restored a value from localStorage so we don't clobber the user's last position.
+  const hasInitializedRef = useRef(false);
+  useEffect(() => {
+    if (!hasInitializedRef.current && total > 0) {
+      hasInitializedRef.current = true;
+      if (!stepHydrated) {
+        setStep(total);
+      }
+    }
+  }, [total, stepHydrated, setStep]);
+
+  const visibleMessages = useMemo(() => sortedMessages.slice(0, step), [sortedMessages, step]);
+  const { commits, branches } = useMemo(
+    () => buildExecutionGraph({ traceMessages: visibleMessages }),
+    [visibleMessages],
+  );
+
+  // Auto-play steps forward until we reach the end.
+  useEffect(() => {
+    if (!playing) {
+      return;
+    }
+    const id = window.setInterval(() => {
+      setStep((current) => {
+        if (current >= total) {
+          setPlaying(false);
+          return current;
+        }
+        return current + 1;
+      });
+    }, PLAYBACK_INTERVAL_MS);
+    return () => window.clearInterval(id);
+  }, [playing, total]);
+
+  // Handlers.
+  const handleNext = useCallback(() => setStep((current) => Math.min(current + 1, total)), [total]);
+  const handlePrev = useCallback(() => setStep((current) => Math.max(current - 1, 0)), []);
+  const handleReset = useCallback(() => {
+    setStep(0);
+    setPlaying(false);
+  }, []);
+  const handleShowAll = useCallback(() => {
+    setStep(total);
+    setPlaying(false);
+  }, [total]);
+  const handleTogglePlay = useCallback(() => setPlaying((previous) => !previous), []);
+
+  // Keyboard shortcuts: ←/h step back, →/l step forward, space play/pause, r reset, e/End show all.
+  useEffect(() => {
+    return addEventListener(window, 'keydown', (event: KeyboardEvent) => {
+      const target = event.target as HTMLElement | null;
+      if (target?.tagName === 'INPUT' || target?.tagName === 'TEXTAREA' || target?.isContentEditable) {
+        return;
+      }
+
+      switch (event.key) {
+        case 'ArrowRight':
+        case 'l':
+          event.preventDefault();
+          handleNext();
+          break;
+        case 'ArrowLeft':
+        case 'h':
+          event.preventDefault();
+          handlePrev();
+          break;
+        case ' ':
+          event.preventDefault();
+          handleTogglePlay();
+          break;
+        case 'r':
+          event.preventDefault();
+          handleReset();
+          break;
+        case 'e':
+        case 'End':
+          event.preventDefault();
+          handleShowAll();
+          break;
+      }
+    });
+  }, [handleNext, handlePrev, handleTogglePlay, handleReset, handleShowAll]);
+
+  return (
+    <ScrollContainer.Root pin>
+      <BaseStory
+        toolbar={
+          <Toolbar.Root>
+            <IconButton iconOnly icon='ph--skip-back--regular' label='Reset (R)' onClick={handleReset} />
+            <IconButton iconOnly icon='ph--caret-left--regular' label='Step back (← / H)' onClick={handlePrev} />
+            <IconButton
+              iconOnly
+              icon={playing ? 'ph--pause--regular' : 'ph--play--regular'}
+              label={playing ? 'Pause (Space)' : 'Play (Space)'}
+              onClick={handleTogglePlay}
+            />
+            <IconButton iconOnly icon='ph--caret-right--regular' label='Step forward (→ / L)' onClick={handleNext} />
+            <IconButton iconOnly icon='ph--skip-forward--regular' label='Show all (E / End)' onClick={handleShowAll} />
+            <Toolbar.Text className='text-right text-sm tabular-nums opacity-70'>
+              {step} / {total}
+            </Toolbar.Text>
+          </Toolbar.Root>
+        }
+      >
+        <ScrollContainer.Content thin>
+          <ScrollContainer.Viewport>
+            <Timeline branches={branches} commits={commits} showTimestamp />
+          </ScrollContainer.Viewport>
+          <ScrollContainer.ScrollDownButton />
+          <ScrollContainer.Fade />
+        </ScrollContainer.Content>
+      </BaseStory>
+    </ScrollContainer.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-assistant/containers/TracePanel',
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column', classNames: 'w-(--dx-complementary-sidebar-size) overflow-hidden' }),
+    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());
+            }),
+        }),
+        AssistantPlugin(),
+        AutomationPlugin(),
+      ],
+    }),
+  ],
+};
+
+export const WithSnapshot: Story = {
+  render: SnapshotStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column', classNames: 'w-(--dx-complementary-sidebar-size)' }),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        ClientPlugin({
+          types: [Feed.Feed, Trace.Message],
+          onClientInitialized: initClientFromSpaceSnapshot(() => import('../../testing/data/trace-timeline.dx.json')),
+        }),
+        AutomationPlugin(),
+      ],
+    }),
+  ],
+};
+
+export const WithRemoteSnapshot: Story = {
+  render: SnapshotStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column', classNames: 'w-(--dx-complementary-sidebar-size)' }),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        ClientPlugin({
+          types: [Feed.Feed, Trace.Message],
+          onClientInitialized: initClientFromSpaceSnapshot(
+            () => import('../../testing/data/trace-timeline-remote.dx.json'),
+          ),
+        }),
+        AutomationPlugin(),
+      ],
+    }),
+  ],
+};
+
+export const WithRemoteMultipleSnapshot: Story = {
+  render: SnapshotStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column', classNames: 'w-(--dx-complementary-sidebar-size)' }),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        ClientPlugin({
+          types: [Feed.Feed, Trace.Message],
+          onClientInitialized: initClientFromSpaceSnapshot(
+            () => import('../../testing/data/trace-timeline-multiple.dx.json'),
+          ),
+        }),
+        AutomationPlugin(),
+      ],
+    }),
+  ],
+};

package/src/containers/TracePanel/TracePanel.tsx

@@ -0,0 +1,213 @@
+//
+// 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, 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 { AtomQuery } from '@dxos/echo-atom';
+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));
+
+    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);
+};
+
+const getExecutionGraph = (
+  space: Space,
+  processesAtom: Atom.Atom<readonly Process.Info[]>,
+  { eventLimit = 100 }: UseExecutionGraphOptions = {},
+): Atom.Atom<ExecutionGraph> => {
+  const traceMessages = 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.
+      AtomQuery.make(
+        space.db,
+        feeds.length > 0
+          ? Query.type(Trace.Message).from(feeds[0])
+          : (Query.select(Filter.nothing()) as Query.Query<never>),
+      ),
+    ),
+    (atom) => Atom.make((get) => get(get(atom))),
+  );
+
+  const activeProcesses = pipe(
+    processesAtom,
+    Atom.debounce(Duration.millis(100)),
+    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(monitor?.processTreeAtom ?? atomEmpty);
+
+  // `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 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 = extractDxnFromString('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 = extractDxnFromString(
+        'Objects: dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4 and @dxn:queue:data:SPACE:QUEUE:01KG7R1ZXWFMWQ4DA1Q6TN1DG5',
+      );
+      expect(result).toHaveLength(2);
+    });
+
+    test('deduplicates DXNs', ({ expect }) => {
+      const result = extractDxnFromString(
+        'Same object dxn:echo:@:01KG7R1ZXWFMWQ4DA1Q6TN1DG4 and dxn: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 { "/": "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();
+    });
+  });
+});