@dxos/plugin-thread 0.8.4-main.422d1c7879 → 0.8.4-main.43cb759274

package/src/operations/restore-message.ts

@@ -4,22 +4,22 @@
 
 import * as Effect from 'effect/Effect';
 
+import { Operation } from '@dxos/compute';
 import { Obj, Ref, Relation } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
-import { Operation } from '@dxos/operation';
-import { ObservabilityOperation } from '@dxos/plugin-observability/operations';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
 import { Thread } from '@dxos/types';
 
-import { RestoreMessage } from './definitions';
+import { ThreadOperation } from '../types';
 
-const handler: Operation.WithHandler<typeof RestoreMessage> = RestoreMessage.pipe(
+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.change(thread, (thread) => {
+      Obj.update(thread, (thread) => {
         thread.messages.splice(messageIndex, 0, Ref.make(message));
       });
 

package/src/operations/restore.ts

@@ -5,13 +5,13 @@
 import * as Effect from 'effect/Effect';
 
 import { sleep } from '@dxos/async';
+import { Operation } from '@dxos/compute';
 import { Obj } from '@dxos/echo';
-import { Operation } from '@dxos/operation';
-import { ObservabilityOperation } from '@dxos/plugin-observability/operations';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
 
-import { Restore } from './definitions';
+import { ThreadOperation } from '../types';
 
-const handler: Operation.WithHandler<typeof Restore> = Restore.pipe(
+const handler: Operation.WithHandler<typeof ThreadOperation.Restore> = ThreadOperation.Restore.pipe(
   Operation.withHandler(
     Effect.fnUntraced(function* ({ thread, anchor }) {
       const db = Obj.getDatabase(thread);

package/src/operations/select.ts

@@ -5,12 +5,12 @@
 import * as Effect from 'effect/Effect';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
-import { Operation } from '@dxos/operation';
+import { Operation } from '@dxos/compute';
 
 import { ThreadCapabilities } from '../types';
-import { Select } from './definitions';
+import { ThreadOperation } from '../types';
 
-const handler: Operation.WithHandler<typeof Select> = Select.pipe(
+const handler: Operation.WithHandler<typeof ThreadOperation.Select> = ThreadOperation.Select.pipe(
   Operation.withHandler(
     Effect.fnUntraced(function* (input) {
       const registry = yield* Capability.get(Capabilities.AtomRegistry);

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

@@ -4,19 +4,19 @@
 
 import * as Effect from 'effect/Effect';
 
+import { Operation } from '@dxos/compute';
 import { Obj } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
-import { Operation } from '@dxos/operation';
-import { ObservabilityOperation } from '@dxos/plugin-observability/operations';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
 
-import { ToggleResolved } from './definitions';
+import { ThreadOperation } from '../types';
 
-const handler: Operation.WithHandler<typeof ToggleResolved> = ToggleResolved.pipe(
+const handler: Operation.WithHandler<typeof ThreadOperation.ToggleResolved> = ThreadOperation.ToggleResolved.pipe(
   Operation.withHandler(
     Effect.fnUntraced(function* (input) {
       const thread = input.thread;
 
-      Obj.change(thread, (thread) => {
+      Obj.update(thread, (thread) => {
         if (thread.status === 'active' || thread.status === undefined) {
           thread.status = 'resolved';
         } else if (thread.status === 'resolved') {

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/index.ts

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

package/src/translations.ts

@@ -4,13 +4,14 @@
 
 import { Type } from '@dxos/echo';
 import { type Resource } from '@dxos/react-ui';
+import { Channel } from '@dxos/types';
 
 import { meta } from '#meta';
-import { Channel } from '#types';
 
 export const translations = [
   {
     'en-US': {
+      // TODO(burdon): Thread.
       [Type.getTypename(Channel.Channel)]: {
         'typename.label': 'Channel',
         'typename.label_zero': 'Channels',

package/src/types/AgentIdentity.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+import { meta } from '#meta';
+
+/**
+ * Runtime identity of the comment-thread AI agent.
+ *
+ * Resolved via a Capability contribution at plugin activation, never stored on
+ * Thread.Thread. Renaming the agent globally (e.g. via plugin settings)
+ * immediately affects gating and sender metadata on every opted-in thread —
+ * past and future.
+ *
+ * - `name`: display name and @mention token (case-insensitive match).
+ * - `identityDid`: optional ECHO DID stamped on assistant messages.
+ * - `avatar`: optional icon hint.
+ */
+export interface AgentIdentity {
+  readonly name: string;
+  readonly identityDid?: string;
+  readonly avatar?: string;
+}
+
+export const AgentIdentity = Capability.make<AgentIdentity>(`${meta.id}.capability.agent-identity`);
+
+/**
+ * Built-in default identity used by ThreadPlugin when no host has contributed
+ * a stronger `AgentIdentity`. Hosts that want to override (e.g. a workspace-
+ * scoped bot record, a settings panel) must contribute their identity earlier
+ * in plugin order so `Capability.get` returns it first.
+ */
+export const DEFAULT_AGENT_IDENTITY: AgentIdentity = { name: 'Kai' };

package/src/types/ThreadCapabilities.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import { type Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { type Obj } from '@dxos/echo';
+import { type Thread } from '@dxos/types';
+
+import { meta } from '#meta';
+
+import { type ThreadState, type ViewStore } from '../types';
+
+export const Settings = Capability.make<Atom.Writable<import('./Settings').Settings>>(`${meta.id}.capability.settings`);
+
+/** Comment configuration contributed per typename by plugins that support commenting. */
+export type CommentConfig = AppCapabilities.CommentConfig;
+export const CommentConfig: Capability.InterfaceDef<AppCapabilities.CommentConfig> = AppCapabilities.CommentConfig;
+
+/** Thread state (drafts, toolbar state, current selection). */
+export const State = Capability.make<Atom.Writable<ThreadState>>(`${meta.id}.capability.state`);
+
+/** Per-subject view state (e.g., showResolvedThreads). */
+export const ViewState = Capability.make<Atom.Writable<ViewStore>>(`${meta.id}.capability.view-state`);
+
+/**
+ * Runs one comment-thread agent turn against a thread/subject pair.
+ *
+ * `run` may depend on `Capability.Service` so implementations can read
+ * `AgentIdentity` and any other contributed capabilities. The caller
+ * (RespondToThread operation handler) already provides `Capability.Service`.
+ *
+ * The default implementation (built atop AiSession) is not yet wired; storybook
+ * and tests contribute stub implementations via `Capability.contributes` to
+ * exercise the trigger plumbing without making network calls.
+ */
+export interface AgentRunner {
+  run(input: { thread: Thread.Thread; subject: Obj.Any }): Effect.Effect<void, Error, Capability.Service>;
+}
+
+export const AgentRunner = Capability.make<AgentRunner>(`${meta.id}.capability.agent-runner`);

package/src/types/ThreadOperation.ts

@@ -0,0 +1,225 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { SpaceSchema } from '@dxos/client-protocol';
+import { Operation } from '@dxos/compute';
+import { Collection, Database, Key, Obj, Ref, Type, DXN } from '@dxos/echo';
+import { Markdown } from '@dxos/plugin-markdown';
+import { Actor, AnchoredTo, Channel, Message, Thread } from '@dxos/types';
+
+import { meta } from '#meta';
+
+const makeKey = (name: string) => DXN.make(`${meta.id}.operation.${name}`);
+
+export const OnCreateSpace = Operation.make({
+  meta: { key: makeKey('onCreateSpace'), name: 'On Create Space', icon: 'ph--chat-text--regular' },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    space: SpaceSchema,
+    rootCollection: Type.getSchema(Collection.Collection),
+    isDefault: Schema.Boolean.pipe(Schema.optional),
+  }),
+  output: Schema.Void,
+});
+
+export const CreateChannel = Operation.make({
+  meta: { key: makeKey('createChannel'), name: 'Create Channel', icon: 'ph--hash--regular' },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    spaceId: Key.SpaceId,
+    name: Schema.optional(Schema.String),
+  }),
+  output: Schema.Struct({
+    object: Type.getSchema(Channel.Channel),
+  }),
+});
+
+export const AppendChannelMessage = Operation.make({
+  meta: {
+    key: makeKey('appendChannelMessage'),
+    name: 'Append Channel Message',
+    icon: 'ph--chat-text--regular',
+  },
+  // Note: Feed.FeedService is provided inside the handler from space.queues, not at the
+  // operation level — the runtime can't fulfill it without a space context.
+  services: [Capability.Service],
+  input: Schema.Struct({
+    channel: Type.getSchema(Channel.Channel),
+    sender: Actor.Actor,
+    text: Schema.String,
+  }),
+  output: Schema.Void,
+});
+
+export const Create = Operation.make({
+  meta: { key: makeKey('create'), name: 'Create Thread', icon: 'ph--chat-text--regular' },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    name: Schema.optional(Schema.String),
+    anchor: Schema.optional(Schema.String),
+    subject: Obj.Unknown,
+  }),
+  output: Schema.Void,
+});
+
+export const DeleteOutput = Schema.Struct({
+  thread: Type.getSchema(Thread.Thread).annotations({ description: 'The deleted thread.' }),
+  anchor: Type.getSchema(AnchoredTo.AnchoredTo).annotations({ description: 'The deleted anchor.' }),
+}).pipe(Schema.partial);
+
+export type DeleteOutput = Schema.Schema.Type<typeof DeleteOutput>;
+
+export const Delete = Operation.make({
+  meta: { key: makeKey('delete'), name: 'Delete Thread', icon: 'ph--trash--regular' },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    anchor: Type.getSchema(AnchoredTo.AnchoredTo),
+    subject: Obj.Unknown,
+    thread: Schema.optional(Type.getSchema(Thread.Thread)),
+  }),
+  output: DeleteOutput,
+});
+
+export const Select = Operation.make({
+  meta: { key: makeKey('select'), name: 'Select Thread', icon: 'ph--check--regular' },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    current: Schema.String,
+  }),
+  output: Schema.Void,
+});
+
+export const ToggleResolved = Operation.make({
+  meta: {
+    key: makeKey('toggleResolved'),
+    name: 'Toggle Resolved',
+    icon: 'ph--check-circle--regular',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    thread: Type.getSchema(Thread.Thread),
+  }),
+  output: Schema.Void,
+});
+
+export const AddMessage = Operation.make({
+  meta: { key: makeKey('addMessage'), name: 'Add Message', icon: 'ph--chat-text--regular' },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    subject: Obj.Unknown,
+    anchor: Type.getSchema(AnchoredTo.AnchoredTo),
+    sender: Actor.Actor,
+    text: Schema.String,
+  }),
+  output: Schema.Void,
+});
+
+export const DeleteMessageOutput = Schema.partial(
+  Schema.Struct({
+    message: Type.getSchema(Message.Message).annotations({ description: 'The deleted message.' }),
+    messageIndex: Schema.Number.annotations({ description: 'The index the message was at.' }),
+  }),
+);
+
+export type DeleteMessageOutput = Schema.Schema.Type<typeof DeleteMessageOutput>;
+
+export const DeleteMessage = Operation.make({
+  meta: { key: makeKey('deleteMessage'), name: 'Delete Message', icon: 'ph--trash--regular' },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    anchor: Type.getSchema(AnchoredTo.AnchoredTo),
+    subject: Obj.Unknown,
+    messageId: Schema.String,
+  }),
+  output: DeleteMessageOutput,
+});
+
+/**
+ * Restore a deleted thread (inverse of Delete).
+ */
+export const Restore = Operation.make({
+  meta: {
+    key: makeKey('restore'),
+    name: 'Restore Thread',
+    icon: 'ph--clock-counter-clockwise--regular',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    thread: Type.getSchema(Thread.Thread).annotations({ description: 'The thread to restore.' }),
+    anchor: Type.getSchema(AnchoredTo.AnchoredTo).annotations({ description: 'The anchor relation to restore.' }),
+  }),
+  output: Schema.Void,
+});
+
+/**
+ * Restore a deleted message (inverse of DeleteMessage).
+ */
+export const RestoreMessage = Operation.make({
+  meta: {
+    key: makeKey('restoreMessage'),
+    name: 'Restore Message',
+    icon: 'ph--clock-counter-clockwise--regular',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    anchor: Type.getSchema(AnchoredTo.AnchoredTo).annotations({ description: 'The anchor of the thread.' }),
+    message: Type.getSchema(Message.Message).annotations({ description: 'The message to restore.' }),
+    messageIndex: Schema.Number.annotations({ description: 'The index to restore the message at.' }),
+  }),
+  output: Schema.Void,
+});
+
+export const RespondToThread = Operation.make({
+  meta: {
+    key: makeKey('respondToThread'),
+    name: 'Respond to Thread',
+    description: 'Runs one comment-thread agent turn against the given thread + subject.',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    thread: Ref.Ref(Thread.Thread).annotations({ description: 'The thread to respond to.' }),
+    subject: Ref.Ref(Obj.Unknown).annotations({ description: 'The object the thread is anchored to.' }),
+  }),
+  output: Schema.Void,
+});
+
+export const SetAgentConfig = Operation.make({
+  meta: {
+    key: makeKey('setAgentConfig'),
+    name: 'Set Agent Config',
+    description: 'Updates thread.agent. Undefined config disables the agent.',
+  },
+  services: [Database.Service],
+  input: Schema.Struct({
+    thread: Ref.Ref(Thread.Thread).annotations({ description: 'The thread to configure.' }),
+    config: Schema.optional(Thread.AgentConfig).annotations({
+      description: 'New agent config; omit to disable.',
+    }),
+  }),
+  output: Schema.Void,
+});
+
+export const CreateProposals = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.function.thread.createProposals'),
+    name: 'Create Proposals',
+    description: 'Proposes a set of changes to a document.',
+    icon: 'ph--sparkle--regular',
+  },
+  input: Schema.Struct({
+    doc: Ref.Ref(Markdown.Document).annotations({
+      description: 'The ID of the document.',
+    }),
+    diffs: Schema.Array(Schema.String).annotations({
+      description: 'The diffs to propose for the document.',
+    }),
+  }),
+  output: Schema.Void,
+  services: [Database.Service],
+});

package/src/types/index.ts

@@ -2,6 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './capabilities';
-export * as Channel from './Channel';
 export * from './types';
+
+export * from './AgentIdentity';
+export * as Settings from './Settings';
+export * as ThreadCapabilities from './ThreadCapabilities';
+export * as ThreadOperation from './ThreadOperation';

package/src/types/types.ts

@@ -4,8 +4,6 @@
 
 import { AnchoredTo, Thread } from '@dxos/types';
 
-export * as Settings from './Settings';
-
 export interface ThreadModel {
   root: Thread.Thread;
 }

package/src/util.ts

@@ -9,18 +9,50 @@ import { type PublicKey } from '@dxos/react-client';
 import { type Identity } from '@dxos/react-client/halo';
 import { type Selection } from '@dxos/react-ui-attention';
 import { type MessageMetadata } from '@dxos/react-ui-thread';
-import { hexToFallback } from '@dxos/util';
+import { hexToFallback, toFallback } from '@dxos/util';
 
 export type MessagePropertiesProvider = (identityKey: PublicKey | undefined) => MessageMetadata;
 
-export const getMessageMetadata = (id: string, identity?: Identity): MessageMetadata => {
-  const fallback = hexToFallback(identity?.identityKey.toHex() ?? '0');
+/**
+ * Stable hash for an arbitrary string — used as the avatar-fallback seed for
+ * external senders who have no DXOS identity (e.g. Slack/Discord-synced
+ * messages). djb2-ish, only stability matters.
+ *
+ * Coerced to unsigned 32-bit via `>>> 0` because `toFallback` does a plain
+ * modulo against `idEmoji.length * idHue.length` and JavaScript's `%`
+ * preserves the sign of the dividend — a negative hash would index
+ * `idEmoji[-x]` and `idHue[-x]` to `undefined`, causing the avatar to fall
+ * through to `Avatar.Content`'s default red/ghost.
+ */
+const hashString = (s: string): number => {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) {
+    h = (h * 31 + s.charCodeAt(i)) | 0;
+  }
+  return h >>> 0;
+};
+
+export const getMessageMetadata = (
+  id: string,
+  identity?: Identity,
+  /**
+   * Externally-sourced sender info (Slack/Discord/etc). Used only when no
+   * matching DXOS `identity` is available — provides `name`/`email` for the
+   * author label and a stable seed for the avatar fallback.
+   */
+  fallbackSender?: { name?: string; email?: string },
+): MessageMetadata => {
+  const fallback = identity?.identityKey
+    ? hexToFallback(identity.identityKey.toHex())
+    : toFallback(hashString(fallbackSender?.name ?? fallbackSender?.email ?? '0'));
   return {
     id,
     authorId: identity?.did,
     authorName:
       identity?.profile?.displayName ??
-      (identity?.identityKey ? generateName(identity.identityKey.toHex()) : undefined),
+      (identity?.identityKey ? generateName(identity.identityKey.toHex()) : undefined) ??
+      fallbackSender?.name ??
+      fallbackSender?.email,
     authorAvatarProps: {
       hue: identity?.profile?.data?.hue ?? fallback.hue,
       emoji: identity?.profile?.data?.emoji ?? fallback.emoji,

package/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+//
+// Copyright 2026 DXOS.org
+//
+
+declare module '*.mdl?raw' {
+  const content: string;
+  export default content;
+}