@dxos/plugin-assistant 0.8.4-main.7ace549 → 0.8.4-main.8baae0fced

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();
+    });
+  });
+});

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

@@ -0,0 +1,178 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { DXN } from '@dxos/keys';
+
+/**
+ * Patterns for extracting DXN references from tool call params/results.
+ *
+ * Supported formats:
+ * - `{ "/": "dxn:..." }` - IPLD-style encoded references
+ * - `{ "@dxn": "dxn:..." }` - Alternative format with @dxn key
+ * - `@dxn:...` - In-text references (with @ prefix)
+ * - `dxn:...` - Plain DXN strings
+ */
+
+/**
+ * Regex to match DXN strings in various formats.
+ * Matches: dxn:kind:part1:part2:...
+ */
+const DXN_PATTERN = /dxn:[a-zA-Z0-9]+(?::[a-zA-Z0-9@_-]+)+/g;
+
+/**
+ * Regex to match @dxn: prefixed references in text.
+ */
+const AT_DXN_PATTERN = /@(dxn:[a-zA-Z0-9]+(?::[a-zA-Z0-9@_-]+)+)/g;
+
+/**
+ * Extracts all DXN references from a string.
+ */
+export const extractDxnFromString = (text: string): DXN[] => {
+  const dxns: DXN[] = [];
+  const seen = new Set<string>();
+
+  // Match @dxn: prefixed references.
+  let match;
+  while ((match = AT_DXN_PATTERN.exec(text)) !== null) {
+    const dxnStr = match[1];
+    if (!seen.has(dxnStr)) {
+      const dxn = DXN.tryParse(dxnStr);
+      if (dxn) {
+        dxns.push(dxn);
+        seen.add(dxnStr);
+      }
+    }
+  }
+
+  // Match plain dxn: strings.
+  while ((match = DXN_PATTERN.exec(text)) !== null) {
+    const dxnStr = match[0];
+    if (!seen.has(dxnStr)) {
+      const dxn = DXN.tryParse(dxnStr);
+      if (dxn) {
+        dxns.push(dxn);
+        seen.add(dxnStr);
+      }
+    }
+  }
+
+  return dxns;
+};
+
+/**
+ * Extracts DXN references from a JSON object.
+ * Handles IPLD-style references `{ "/": "dxn:..." }` and `{ "@dxn": "dxn:..." }`.
+ */
+export const extractDxnsFromObject = (obj: unknown): DXN[] => {
+  const dxns: DXN[] = [];
+  const seen = new Set<string>();
+
+  const addDXN = (dxnStr: string) => {
+    if (!seen.has(dxnStr)) {
+      const dxn = DXN.tryParse(dxnStr);
+      if (dxn) {
+        dxns.push(dxn);
+        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 DXN.
+      if (value.startsWith('dxn:')) {
+        addDXN(value);
+      } else if (value.startsWith('@dxn:')) {
+        addDXN(value.slice(1));
+      }
+      // Also extract DXNs from within the string.
+      const extracted = extractDxnFromString(value);
+      for (const dxn of extracted) {
+        addDXN(dxn.toString());
+      }
+      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: { "/": "dxn:..." }
+      if ('/' in record && typeof record['/'] === 'string') {
+        const dxnStr = record['/'];
+        if (typeof dxnStr === 'string' && dxnStr.startsWith('dxn:')) {
+          addDXN(dxnStr);
+        }
+      }
+
+      // Check for @dxn key: { "@dxn": "dxn:..." }
+      if ('@dxn' in record && typeof record['@dxn'] === 'string') {
+        const dxnStr = record['@dxn'];
+        if (typeof dxnStr === 'string' && dxnStr.startsWith('dxn:')) {
+          addDXN(dxnStr);
+        }
+      }
+
+      // Check for reference blocks: { _tag: 'reference', reference: { dxn: ... } }
+      if (record._tag === 'reference' && record.reference && typeof record.reference === 'object') {
+        const ref = record.reference as Record<string, unknown>;
+        if (ref.dxn && typeof ref.dxn === 'string') {
+          addDXN(ref.dxn);
+        }
+      }
+
+      // 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): DXN | 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): DXN | 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';

package/src/containers/TracePanel/testing/simulated-agent.ts

@@ -0,0 +1,114 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AgentRequestBegin, AgentRequestEnd, CompleteBlock } from '@dxos/assistant';
+import { Process, Trace } from '@dxos/compute';
+import { ObjectId } from '@dxos/keys';
+
+export interface AgentScenario {
+  readonly prompt: string;
+  readonly tools: readonly string[];
+}
+
+/** Probability that any given run aborts with a simulated tool failure. */
+const FAILURE_PROBABILITY = 0.1;
+
+export const agentScenarios: readonly AgentScenario[] = [
+  {
+    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'],
+  },
+];
+
+const delay = (ms: number) => Effect.promise(() => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+
+/**
+ * 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)));
+  });
+
+/**
+ * Storybook fixture: a {@link Process} that emits a deterministic stream of agent trace events
+ * (request begin/end, user message, sequential tool calls with simulated latency).
+ *
+ * Input is a scenario index into {@link agentScenarios} (modulo the array length).
+ */
+export const SimulatedAgent = Process.make(
+  {
+    key: 'org.dxos.testing.process.agent',
+    input: Schema.Number,
+    output: Schema.Void,
+    services: [Trace.TraceService],
+  },
+  (ctx) =>
+    Effect.succeed({
+      onInput: (index: number) =>
+        Effect.gen(function* () {
+          const messageId = ObjectId.random();
+          const scenario = agentScenarios[index % agentScenarios.length];
+
+          // Decide upfront whether this run will fail (and at which tool) so the trace shows a partial sequence.
+          const failAtToolIndex =
+            Math.random() < FAILURE_PROBABILITY ? Math.floor(Math.random() * scenario.tools.length) : -1;
+
+          // 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 [index, toolName] of scenario.tools.entries()) {
+            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);
+
+            if (index === failAtToolIndex) {
+              ctx.fail(new Error(`Simulated failure in tool '${toolName}'`));
+              return;
+            }
+
+            // 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,
+    }),
+);

package/src/containers/TracePanel/testing/snapshot-playback.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Dispatch, type SetStateAction, useEffect, useRef, useState } from 'react';
+
+/**
+ * Interval (ms) between auto-played trace messages in the snapshot playback story.
+ */
+export const PLAYBACK_INTERVAL_MS = 250;
+
+export const STEP_STORAGE_KEY = 'plugin-assistant.trace-panel.snapshot.step';
+
+/**
+ * `useState<number>` that hydrates from and persists to `localStorage`.
+ * The third tuple member is `true` iff a valid value was loaded on first render.
+ */
+export const useLocalStorageNumber = (
+  key: string,
+  initial: number,
+): [number, Dispatch<SetStateAction<number>>, boolean] => {
+  const initRef = useRef<{ value: number; hydrated: boolean } | null>(null);
+  if (initRef.current === null) {
+    let value = initial;
+    let hydrated = false;
+    if (typeof window !== 'undefined') {
+      const stored = window.localStorage.getItem(key);
+      const parsed = stored === null ? Number.NaN : Number(stored);
+      if (Number.isInteger(parsed) && parsed >= 0) {
+        value = parsed;
+        hydrated = true;
+      }
+    }
+    initRef.current = { value, hydrated };
+  }
+
+  const [value, setValue] = useState(initRef.current.value);
+  useEffect(() => {
+    if (typeof window !== 'undefined') {
+      window.localStorage.setItem(key, String(value));
+    }
+  }, [key, value]);
+
+  return [value, setValue, initRef.current.hydrated];
+};

package/src/containers/TriggerStatus/TriggerStatus.tsx

@@ -0,0 +1,129 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useMemo } from 'react';
+
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { type InvocationsState } from '@dxos/functions-runtime';
+import { useTriggerRuntimeControls } from '@dxos/plugin-automation/hooks';
+import { StatusBar } from '@dxos/plugin-status-bar/components';
+import { useObject } from '@dxos/react-client/echo';
+import { IconButton, Popover, useTranslation } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+
+type TriggerStatusState = 'disabled' | 'idle' | 'running' | 'edge' | 'error';
+
+const getIcon = (state: TriggerStatusState): string => {
+  switch (state) {
+    case 'disabled':
+      return 'ph--lightning-slash--regular';
+    case 'idle':
+      return 'ph--lightning--regular';
+    case 'edge':
+      return 'ph--lightning--regular';
+    case 'running':
+      return 'ph--lightning--fill';
+    case 'error':
+      return 'ph--warning--regular';
+  }
+};
+
+const getIconClassNames = (state: TriggerStatusState): string | undefined => {
+  switch (state) {
+    case 'running':
+      return 'animate-pulse text-accent-text';
+    case 'error':
+      return 'text-error-text';
+    default:
+      return undefined;
+  }
+};
+
+export type SpaceStatusProps = AppSurface.SpaceArticleProps;
+
+export const SpaceStatus = ({ space }: SpaceStatusProps) => {
+  const { t } = useTranslation(meta.id);
+  const { state } = useTriggerRuntimeControls(space.db);
+  const isEnabled = state?.enabled ?? false;
+  const [properties] = useObject(space.properties);
+  const computeEnvironment = properties.computeEnvironment ?? 'local';
+
+  // Determine the current trigger status state.
+  const triggerState: TriggerStatusState = useMemo(() => {
+    if (computeEnvironment === 'edge') {
+      return 'edge';
+    }
+
+    if (!isEnabled) {
+      return 'disabled';
+    }
+
+    // Check if there's any pending invocation.
+    const hasPending = state?.invocations.some((invocation) => invocation.result === null);
+    if (hasPending) {
+      return 'running';
+    }
+
+    // Check if the last invocation failed.
+    const lastInvocation = state?.invocations.at(-1);
+    if (lastInvocation?.result?._tag === 'Failure') {
+      return 'error';
+    }
+
+    return 'idle';
+  }, [computeEnvironment, isEnabled, state?.invocations]);
+
+  return (
+    <Popover.Root>
+      <Popover.Trigger asChild>
+        <StatusBar.Item>
+          <IconButton
+            icon={getIcon(triggerState)}
+            iconOnly
+            label={t(`trigger-status-${triggerState}.label`)}
+            classNames={getIconClassNames(triggerState)}
+          />
+        </StatusBar.Item>
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Content side='left'>
+          <TriggerStatusPopover
+            state={triggerState}
+            currentFunctionName={
+              state?.invocations.at(-1)?.function?.meta.name ?? state?.invocations.at(-1)?.function?.meta.key
+            }
+            lastInvocation={state?.invocations.at(-1)}
+          />
+          <Popover.Arrow />
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+};
+
+type TriggerStatusPopoverProps = {
+  state: TriggerStatusState;
+  currentFunctionName?: string;
+  lastInvocation?: InvocationsState;
+};
+
+const TriggerStatusPopover = ({
+  state,
+  currentFunctionName,
+  lastInvocation, // TODO(burdon): Show.
+}: TriggerStatusPopoverProps) => {
+  const { t } = useTranslation(meta.id);
+
+  return (
+    <div className='flex flex-col gap-2 p-2 w-[240px]'>
+      <div className='flex flex-col gap-1'>
+        <div className='text-sm'>{t(`trigger-status-${state}.label`)}</div>
+        {currentFunctionName && state === 'running' && (
+          <div className='text-xs text-description'>{currentFunctionName}</div>
+        )}
+      </div>
+    </div>
+  );
+};

package/src/containers/TriggerStatus/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { SpaceStatus, SpaceStatus as default } from './TriggerStatus';

package/src/containers/index.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export const AgentArticle: ComponentType<any> = lazy(() => import('./AgentArticle'));
+export const AgentProperties: ComponentType<any> = lazy(() => import('./AgentProperties'));
+export const BlueprintArticle: ComponentType<any> = lazy(() => import('./BlueprintArticle'));
+export const ChatCompanion: ComponentType<any> = lazy(() => import('./ChatCompanion'));
+export const ChatArticle: ComponentType<any> = lazy(() => import('./ChatArticle'));
+export const ChatDialog: ComponentType<any> = lazy(() => import('./ChatDialog'));
+export const PlanArticle: ComponentType<any> = lazy(() => import('./PlanArticle'));
+export const RoutineArticle: ComponentType<any> = lazy(() => import('./RoutineArticle'));
+export const RoutineList: ComponentType<any> = lazy(() => import('./RoutineList'));
+export const TracePanel: ComponentType<any> = lazy(() => import('./TracePanel'));
+export const TriggerStatus: ComponentType<any> = lazy(() => import('./TriggerStatus'));