@dxos/plugin-thread 0.8.4-main.ead640a → 0.8.4-main.effb148878

package/src/operations/create-proposals.ts

@@ -0,0 +1,49 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Array from 'effect/Array';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+
+import { computeDiffsWithCursors } from '@dxos/assistant';
+import { Operation } from '@dxos/compute';
+import { Database, Obj, Ref, Relation } from '@dxos/echo';
+import { createDocAccessor } from '@dxos/echo-db';
+import { AnchoredTo, Message, Thread } from '@dxos/types';
+
+import { ThreadOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.CreateProposals> = ThreadOperation.CreateProposals.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ doc, diffs }) {
+      const object = yield* Database.load(doc);
+      const content = yield* Effect.promise(() => object.content.load());
+      const accessor = createDocAccessor(content, ['content']);
+
+      yield* Function.pipe(
+        computeDiffsWithCursors(accessor, diffs),
+        Array.map(
+          Effect.fnUntraced(function* ({ cursor, text }) {
+            const proposal = Obj.make(Message.Message, {
+              created: new Date().toISOString(),
+              sender: { role: 'assistant' },
+              blocks: [{ _tag: 'proposal', text }],
+            });
+            const thread = Thread.make({ name: 'Proposal', messages: [Ref.make(proposal)], status: 'active' });
+            const relation = Relation.make(AnchoredTo.AnchoredTo, {
+              [Relation.Source]: thread,
+              [Relation.Target]: object,
+              anchor: cursor,
+            });
+            yield* Database.add(thread);
+            yield* Database.add(relation);
+          }),
+        ),
+        Effect.allWith({ concurrency: 'unbounded' }),
+      );
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/create.ts

@@ -0,0 +1,63 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+import { Obj, Relation } from '@dxos/echo';
+import { Markdown, MarkdownCapabilities } from '@dxos/plugin-markdown';
+import { linkedSegment } from '@dxos/react-ui-attention';
+import { AnchoredTo, Thread } from '@dxos/types';
+
+import { ThreadCapabilities } from '../types';
+import { ThreadOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.Create> = ThreadOperation.Create.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ name, anchor: _anchor, subject }) {
+      const registry = yield* Capability.get(Capabilities.AtomRegistry);
+      const stateAtom = yield* Capability.get(ThreadCapabilities.State);
+      const subjectId = Obj.getURI(subject);
+
+      // Inherit the markdown plugin's `commentAgentMode` setting when the
+      // subject is a Markdown.Document, so new comment threads on docs are
+      // opted-in (or not) based on the user's preference. Non-markdown
+      // subjects always get an un-opted thread (no agent).
+      const markdownSettingsAtoms = yield* Capability.getAll(MarkdownCapabilities.Settings);
+      const markdownSettingsAtom = markdownSettingsAtoms[0];
+      const commentAgentMode =
+        markdownSettingsAtom && Obj.instanceOf(Markdown.Document, subject)
+          ? registry.get(markdownSettingsAtom).commentAgentMode
+          : undefined;
+      const agent =
+        commentAgentMode && commentAgentMode !== 'off' ? { enabled: true, mode: commentAgentMode } : undefined;
+
+      const thread = Thread.make({ name, agent });
+      const anchor = Relation.make(AnchoredTo.AnchoredTo, {
+        [Relation.Source]: thread,
+        [Relation.Target]: subject,
+        anchor: _anchor,
+      });
+
+      const state = registry.get(stateAtom);
+      const existingDrafts = state.drafts[subjectId];
+      registry.set(stateAtom, {
+        ...state,
+        drafts: {
+          ...state.drafts,
+          [subjectId]: existingDrafts ? [...existingDrafts, anchor] : [anchor],
+        },
+      });
+
+      yield* Operation.invoke(ThreadOperation.Select, { current: Obj.getURI(thread) });
+      yield* Operation.invoke(LayoutOperation.UpdateCompanion, {
+        subject: linkedSegment('comments'),
+      });
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/delete-message.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Obj, Relation } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
+import { Thread } from '@dxos/types';
+
+import { ThreadOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.DeleteMessage> = ThreadOperation.DeleteMessage.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ subject, anchor, messageId }) {
+      const thread = Relation.getSource(anchor) as Thread.Thread;
+      const db = Obj.getDatabase(subject);
+      invariant(db, 'Database not found');
+
+      const msgIndex = thread.messages.findIndex((ref) => ref.target?.id === messageId);
+      const msg = thread.messages[msgIndex]?.target;
+      if (!msg) {
+        return { messageIndex: -1 };
+      }
+
+      if (msgIndex === 0 && thread.messages.length === 1) {
+        // TODO(wittjosiah): This doesn't support restoring the thread.
+        yield* Operation.invoke(ThreadOperation.Delete, { subject, anchor });
+        return { messageIndex: -1 };
+      }
+
+      Obj.update(thread, (thread) => {
+        thread.messages.splice(msgIndex, 1);
+      });
+
+      yield* Operation.schedule(ObservabilityOperation.SendEvent, {
+        name: 'threads.message.delete',
+        properties: {
+          spaceId: db.spaceId,
+          threadId: thread.id,
+          threadLength: thread.messages.length,
+          messageId,
+        },
+      });
+
+      return { message: msg, messageIndex: msgIndex };
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/delete.ts

@@ -0,0 +1,63 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { sleep } from '@dxos/async';
+import { Operation } from '@dxos/compute';
+import { Obj, Relation } from '@dxos/echo';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
+import { Thread } from '@dxos/types';
+
+import { ThreadCapabilities } from '../types';
+import { ThreadOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.Delete> = ThreadOperation.Delete.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ subject, anchor, thread: _thread }) {
+      const registry = yield* Capability.get(Capabilities.AtomRegistry);
+      const stateAtom = yield* Capability.get(ThreadCapabilities.State);
+      const thread = _thread ?? (Relation.getSource(anchor) as Thread.Thread);
+      const subjectId = Obj.getURI(subject);
+      const state = registry.get(stateAtom);
+      const draft = state.drafts[subjectId];
+      if (draft) {
+        const index = draft.findIndex((a: { id: string }) => a.id === anchor.id);
+        if (index !== -1) {
+          registry.set(stateAtom, {
+            ...state,
+            drafts: {
+              ...state.drafts,
+              [subjectId]: state.drafts[subjectId]?.filter((_, i) => i !== index),
+            },
+          });
+          return {};
+        }
+      }
+
+      const db = Obj.getDatabase(thread);
+      if (!db) {
+        return {};
+      }
+
+      // TODO(wittjosiah): Without sleep, rendering crashes at `Relation.setSource(anchor)`.
+      db.remove(anchor);
+      yield* Effect.promise(() => sleep(100));
+      db.remove(thread);
+
+      yield* Operation.schedule(ObservabilityOperation.SendEvent, {
+        name: 'threads.delete',
+        properties: {
+          spaceId: db.spaceId,
+          threadId: thread.id,
+        },
+      });
+
+      return { thread, anchor };
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/index.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const ThreadOperationHandlerSet = OperationHandlerSet.lazy(
+  () => import('./add-message'),
+  () => import('./append-channel-message'),
+  () => import('./create'),
+  () => import('./create-channel'),
+  () => import('./create-proposals'),
+  () => import('./delete'),
+  () => import('./delete-message'),
+  () => import('./on-create-space'),
+  () => import('./respond-to-thread'),
+  () => import('./restore'),
+  () => import('./restore-message'),
+  () => import('./select'),
+  () => import('./set-agent-config'),
+  () => import('./toggle-resolved'),
+);

package/src/operations/on-create-space.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+
+import { ThreadOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.OnCreateSpace> = ThreadOperation.OnCreateSpace.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ space, isDefault }) {
+      if (isDefault) {
+        return;
+      }
+
+      const { object: channel } = yield* Operation.invoke(ThreadOperation.CreateChannel, {
+        name: 'General',
+        spaceId: space.id,
+      });
+      space.db.add(channel);
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/respond-to-thread.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { Database } from '@dxos/echo';
+import { log } from '@dxos/log';
+
+import { ThreadCapabilities, ThreadOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.RespondToThread> = ThreadOperation.RespondToThread.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ thread: threadRef, subject: subjectRef }) {
+      const runner = yield* Capability.get(ThreadCapabilities.AgentRunner);
+      const thread = yield* Database.load(threadRef);
+      const subject = yield* Database.load(subjectRef);
+
+      yield* runner.run({ thread, subject }).pipe(
+        Effect.catchAll((error) =>
+          Effect.sync(() => {
+            log.warn('comment-thread agent failed', { threadId: thread.id, error });
+          }),
+        ),
+      );
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/restore-message.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Obj, Ref, Relation } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
+import { Thread } from '@dxos/types';
+
+import { ThreadOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.RestoreMessage> = ThreadOperation.RestoreMessage.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ anchor, message, messageIndex }) {
+      const thread = Relation.getSource(anchor) as Thread.Thread;
+      const db = Obj.getDatabase(thread);
+      invariant(db, 'Database not found');
+
+      Obj.update(thread, (thread) => {
+        thread.messages.splice(messageIndex, 0, Ref.make(message));
+      });
+
+      yield* Operation.schedule(ObservabilityOperation.SendEvent, {
+        name: 'threads.message.undo-delete',
+        properties: {
+          spaceId: db.spaceId,
+          threadId: thread.id,
+          messageId: message.id,
+        },
+      });
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/restore.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { sleep } from '@dxos/async';
+import { Operation } from '@dxos/compute';
+import { Obj } from '@dxos/echo';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
+
+import { ThreadOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.Restore> = ThreadOperation.Restore.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ thread, anchor }) {
+      const db = Obj.getDatabase(thread);
+      if (!db) {
+        return;
+      }
+
+      // TODO(wittjosiah): Without sleep, rendering crashes at `Relation.setSource(anchor)`.
+      db.add(thread);
+      yield* Effect.promise(() => sleep(100));
+      db.add(anchor);
+
+      yield* Operation.schedule(ObservabilityOperation.SendEvent, {
+        name: 'threads.undo-delete',
+        properties: {
+          spaceId: db.spaceId,
+          threadId: thread.id,
+        },
+      });
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/select.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+
+import { ThreadCapabilities } from '../types';
+import { ThreadOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.Select> = ThreadOperation.Select.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const registry = yield* Capability.get(Capabilities.AtomRegistry);
+      const stateAtom = yield* Capability.get(ThreadCapabilities.State);
+      const current = registry.get(stateAtom);
+      registry.set(stateAtom, { ...current, current: input.current });
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/set-agent-config.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Database, Obj } from '@dxos/echo';
+import { type Thread } from '@dxos/types';
+
+import { ThreadOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.SetAgentConfig> = ThreadOperation.SetAgentConfig.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ thread: threadRef, config }) {
+      const thread = yield* Database.load(threadRef);
+      Obj.update(thread, (thread) => {
+        (thread as Obj.Mutable<Thread.Thread>).agent = config;
+      });
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/toggle-resolved.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Obj } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
+
+import { ThreadOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.ToggleResolved> = ThreadOperation.ToggleResolved.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* (input) {
+      const thread = input.thread;
+
+      Obj.update(thread, (thread) => {
+        if (thread.status === 'active' || thread.status === undefined) {
+          thread.status = 'resolved';
+        } else if (thread.status === 'resolved') {
+          thread.status = 'active';
+        }
+      });
+
+      const db = Obj.getDatabase(thread);
+      invariant(db, 'Database not found');
+
+      yield* Operation.schedule(ObservabilityOperation.SendEvent, {
+        name: 'threads.toggle-resolved',
+        properties: {
+          spaceId: db.spaceId,
+          threadId: thread.id,
+        },
+      });
+    }),
+  ),
+);
+
+export default handler;

package/src/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const ThreadPlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { ThreadOperationHandlerSet } from './operations';

package/src/should-trigger-agent.test.ts

@@ -0,0 +1,72 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { type Message, type Thread } from '@dxos/types';
+
+import { shouldTriggerAgent } from './should-trigger-agent';
+
+// `shouldTriggerAgent` is a pure predicate over the schema shapes — these tests
+// build plain object literals shaped like Message/Thread to avoid the ECHO proxy's
+// `Obj.update`-only mutation guard.
+const makeMessage = (role: 'user' | 'assistant' | undefined, text: string): Message.Message =>
+  ({
+    created: new Date().toISOString(),
+    sender: role ? { role } : {},
+    blocks: [{ _tag: 'text', text }],
+  }) as unknown as Message.Message;
+
+const makeThread = (overrides: Partial<Thread.Thread> = {}): Thread.Thread =>
+  ({
+    status: 'active',
+    messages: [],
+    ...overrides,
+  }) as unknown as Thread.Thread;
+
+describe('shouldTriggerAgent', () => {
+  test('returns false when agent is undefined', ({ expect }) => {
+    expect(shouldTriggerAgent(makeThread(), makeMessage('user', 'hi'), 'echo')).toBe(false);
+  });
+
+  test('returns false when agent is disabled', ({ expect }) => {
+    const thread = makeThread({ agent: { enabled: false, mode: 'auto' } });
+    expect(shouldTriggerAgent(thread, makeMessage('user', 'hi'), 'echo')).toBe(false);
+  });
+
+  test('returns false on assistant-authored messages (self-loop guard)', ({ expect }) => {
+    const thread = makeThread({ agent: { enabled: true, mode: 'auto' } });
+    expect(shouldTriggerAgent(thread, makeMessage('assistant', 'hi'), 'echo')).toBe(false);
+  });
+
+  test('treats messages with no role as user messages (current CommentsCompanion pattern)', ({ expect }) => {
+    const thread = makeThread({ agent: { enabled: true, mode: 'auto' } });
+    expect(shouldTriggerAgent(thread, makeMessage(undefined, 'hi'), 'echo')).toBe(true);
+  });
+
+  test('returns false on resolved threads even when enabled', ({ expect }) => {
+    const thread = makeThread({ status: 'resolved', agent: { enabled: true, mode: 'auto' } });
+    expect(shouldTriggerAgent(thread, makeMessage('user', 'hi'), 'echo')).toBe(false);
+  });
+
+  test('auto mode fires on any user message', ({ expect }) => {
+    const thread = makeThread({ agent: { enabled: true, mode: 'auto' } });
+    expect(shouldTriggerAgent(thread, makeMessage('user', 'anything goes'), 'echo')).toBe(true);
+  });
+
+  test('mention mode does not fire without @name', ({ expect }) => {
+    const thread = makeThread({ agent: { enabled: true, mode: 'mention' } });
+    expect(shouldTriggerAgent(thread, makeMessage('user', 'hello world'), 'echo')).toBe(false);
+  });
+
+  test('mention mode fires on @name match (case-insensitive)', ({ expect }) => {
+    const thread = makeThread({ agent: { enabled: true, mode: 'mention' } });
+    expect(shouldTriggerAgent(thread, makeMessage('user', 'hey @Echo check this'), 'echo')).toBe(true);
+  });
+
+  test('mention mode requires the @ sigil, not just the name', ({ expect }) => {
+    const thread = makeThread({ agent: { enabled: true, mode: 'mention' } });
+    expect(shouldTriggerAgent(thread, makeMessage('user', 'echo location'), 'echo')).toBe(false);
+  });
+});

package/src/should-trigger-agent.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Message, type Thread } from '@dxos/types';
+
+/**
+ * Returns the concatenated text of all 'text' blocks on a message.
+ *
+ * Proposal blocks (assistant-authored markdown diffs) are intentionally
+ * excluded — gating mentions off a proposal text would be meaningless.
+ */
+export const textOf = (message: Message.Message | undefined): string => {
+  if (!message) {
+    return '';
+  }
+  return message.blocks
+    .filter((block): block is Extract<Message.Message['blocks'][number], { _tag: 'text' }> => block._tag === 'text')
+    .map((block) => block.text)
+    .join('\n');
+};
+
+/**
+ * Trigger gate for the comment-thread agent.
+ *
+ * Returns true iff the agent should respond to the latest message. All of:
+ *   - `thread.agent` exists and `enabled === true`
+ *   - `message.sender.role !== 'assistant'` (structural self-loop guard).
+ *     Note: user-authored messages typically have NO role set; only assistant
+ *     messages carry an explicit role.
+ *   - `thread.status !== 'resolved'`
+ *   - Either mode === 'auto', OR text contains an `@{agentName}` mention
+ *     (case-insensitive substring match; v1 — promote to a parser later).
+ */
+export const shouldTriggerAgent = (thread: Thread.Thread, message: Message.Message, agentName: string): boolean => {
+  if (!thread.agent?.enabled) {
+    return false;
+  }
+  if (message.sender.role === 'assistant') {
+    return false;
+  }
+  if (thread.status === 'resolved') {
+    return false;
+  }
+  if (thread.agent.mode === 'auto') {
+    return true;
+  }
+  const needle = '@' + agentName.toLowerCase();
+  return textOf(message).toLowerCase().includes(needle);
+};

package/src/testing/data.ts

@@ -0,0 +1,49 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Obj, Ref } from '@dxos/echo';
+import { IdentityDid } from '@dxos/keys';
+import { random } from '@dxos/random';
+import { type Identity } from '@dxos/react-client/halo';
+import { Message, Thread } from '@dxos/types';
+
+export const createCommentThread = (identity: Identity): Thread.Thread => {
+  return Thread.make({
+    name: 'Comment',
+    messages: random.helpers.multiple(
+      () =>
+        Ref.make(
+          Obj.make(Message.Message, {
+            created: new Date().toISOString(),
+            sender: {
+              identityDid: random.datatype.boolean() ? identity.did : IdentityDid.random(),
+            },
+            blocks: [{ _tag: 'text', text: random.lorem.sentences(3) }],
+          }),
+        ),
+      { count: { min: 2, max: 3 } },
+    ),
+    status: 'active',
+  });
+};
+
+export const createProposalThread = (identity: Identity): Thread.Thread => {
+  return Thread.make({
+    name: 'Proposal',
+    messages: random.helpers.multiple(
+      () =>
+        Ref.make(
+          Obj.make(Message.Message, {
+            created: new Date().toISOString(),
+            sender: {
+              identityDid: random.datatype.boolean() ? identity.did : IdentityDid.random(),
+            },
+            blocks: [{ _tag: 'proposal', text: random.lorem.sentences(3) }],
+          }),
+        ),
+      { count: { min: 1, max: 1 } },
+    ),
+    status: 'active',
+  });
+};

package/src/testing/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './stories';
+export * from './data';