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

package/src/translations.ts

@@ -4,95 +4,94 @@
 
 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';
+import { meta } from '#meta';
 
 export const translations = [
   {
     'en-US': {
+      // TODO(burdon): Thread.
       [Type.getTypename(Channel.Channel)]: {
-        'typename label': 'Channel',
-        'typename label_zero': 'Channels',
-        'typename label_one': 'Channel',
-        'typename label_other': 'Channels',
-        'object name placeholder': 'New channel',
-        'rename object label': 'Rename channel',
-        'delete object label': 'Delete channel',
+        'typename.label': 'Channel',
+        'typename.label_zero': 'Channels',
+        'typename.label_one': 'Channel',
+        'typename.label_other': 'Channels',
+        'object-name.placeholder': 'New channel',
+        'add-object.label': 'Add channel',
+        'rename-object.label': 'Rename channel',
+        'delete-object.label': 'Delete channel',
+        'object-deleted.label': 'Channel deleted',
       },
       [meta.id]: {
-        'plugin name': 'Chat',
-        'channel title label': 'Title',
-        'message placeholder': 'Reply…',
-        'activity message': 'Processing…',
-        'anonymous label': 'Anonymous',
-        'delete message block label': 'Delete message block',
-        'detached thread label': 'Referenced content was removed',
-        'delete thread label': 'Delete thread',
-        'resolve thread label': 'Resolve thread',
-        'thread deleted label': 'Thread deleted',
-        'message deleted label': 'Message deleted',
-        'comments heading': 'Comments',
-        'chat heading': 'Chat',
-        'draft button': 'DRAFT',
-        'no comments title': 'Comments',
-        'no comments message':
+        'plugin.name': 'Chat',
+        'channel-title.label': 'Title',
+        'message.placeholder': 'Reply…',
+        'activity.message': 'Processing…',
+        'anonymous.label': 'Anonymous',
+        'delete-message-block.label': 'Delete message block',
+        'detached-thread.label': 'Referenced content was removed',
+        'delete-thread.label': 'Delete thread',
+        'resolve-thread.label': 'Resolve thread',
+        'thread-deleted.label': 'Thread deleted',
+        'message-deleted.label': 'Message deleted',
+        'comments.heading': 'Comments',
+        'chat.heading': 'Chat',
+        'draft.button': 'DRAFT',
+        'no-comments.title': 'Comments',
+        'no-comments.message':
           'Click on the <commentIcon></commentIcon> button in the document toolbar to create a comment thread on the selected text.',
-        'toggle show resolved': 'Show resolved',
-        'unnamed object threads label': 'Threads',
-        'mark as resolved label': 'Mark as resolved',
-        'mark as unresolved label': 'Mark as unresolved',
-        'save message label': 'Save',
-        'edit message label': 'Edit',
-        'delete message label': 'Delete message',
-        'accept proposal label': 'Accept proposal',
-        'open comments panel label': 'Show Comments',
-        'comments label': 'Comments',
-        'show all label': 'All comments',
-        'show unresolved label': 'Unresolved comments',
+        'toggle-show-resolved.label': 'Show resolved',
+        'unnamed-object-threads.label': 'Threads',
+        'mark-as-resolved.label': 'Mark as resolved',
+        'mark-as-unresolved.label': 'Mark as unresolved',
+        'save-message.label': 'Save',
+        'edit-message.label': 'Edit',
+        'delete-message.label': 'Delete message',
+        'accept-proposal.label': 'Accept proposal',
+        'open-comments-panel.label': 'Show Comments',
+        'comments.label': 'Comments',
+        'show-all.label': 'All comments',
+        'show-unresolved.label': 'Unresolved comments',
+        'add-comment.label': 'Add comment',
 
-        'channel companion label': 'Channel',
-        'call panel label': 'Active Call',
+        'channel-companion.label': 'Channel',
+        'call-panel.label': 'Active Call',
 
-        'display name label': 'Display name',
-        'display name description': 'Set your display name before joining a meeting.',
-        'display name input placeholder': 'Enter your name',
-        'set display name label': 'Continue',
+        'display-name.label': 'Display name',
+        'display-name.description': 'Set your display name before joining a meeting.',
+        'display-name-input.placeholder': 'Enter your name',
+        'set-display-name.label': 'Continue',
 
-        'call tab label': 'Call',
-        'meeting status title': 'Calls',
-        'share meeting link label': 'Share meeting',
-        'show webrtc stats title': 'WebRTC Stats',
-        'show calls history title': 'Service History',
+        'call-tab.label': 'Call',
+        'meeting-status.title': 'Calls',
+        'share-meeting-link.label': 'Share meeting',
+        'show-webrtc-stats.title': 'WebRTC Stats',
+        'show-calls-history.title': 'Service History',
 
-        'meeting summary label': 'Summary',
-        'summarize label': 'Summarize',
-        'summarizing label': 'Creating summary...',
-        'create summary message': 'A summary doesn’t exist for this meeting yet. Create one now?',
+        'meeting-summary.label': 'Summary',
+        'summarize.label': 'Summarize',
+        'summarizing.label': 'Creating summary...',
+        'create-summary.message': 'A summary doesn’t exist for this meeting yet. Create one now?',
 
-        'join call': 'Join',
-        'leave call': 'Leave',
+        'icon-pin.label': 'Pin video',
+        'icon-unpin.label': 'Unpin video',
+        'icon-wave.label': 'Waving',
+        'icon-muted.label': 'Muted',
+        'join-call.button': 'Join',
+        'leave-call.button': 'Leave',
+        'mic-on.button': 'Unmute',
+        'mic-off.button': 'Mute',
+        'camera-on.button': 'Turn camera on',
+        'camera-off.button': 'Turn camera off',
+        'camera-off.label': 'Camera off',
+        'raise-hand.button': 'Raise hand',
+        'lower-hand.button': 'Lower hand',
+        'screenshare-on.button': 'Share screen',
+        'screenshare-off.button': 'Stop streaming',
 
-        'lobby participants_zero': 'No participants',
-        'lobby participants_one': '1 participant',
-        'lobby participants_other': '{{count}} participants',
-
-        'icon pin': 'Pin video',
-        'icon unpin': 'Unpin video',
-        'icon wave': 'Waving',
-        'icon muted': 'Muted',
-        'icon speaking': 'Speaking',
-
-        'mic on': 'Unmute',
-        'mic off': 'Mute',
-        'camera on': 'Turn camera on',
-        'camera off': 'Turn camera off',
-        'camera off label': 'Camera off',
-
-        'raise hand': 'Raise hand',
-        'lower hand': 'Lower hand',
-        'screenshare on': 'Share screen',
-        'screenshare off': 'Stop streaming',
+        'channel-toolbar.title': 'Channel actions',
+        'start-video-call.menu': 'Start video call',
       },
     },
   },

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

@@ -0,0 +1,10 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+export const Settings = Schema.mutable(Schema.Struct({}));
+export interface Settings extends Schema.Schema.Type<typeof Settings> {}

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,217 @@
+//
+// 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 } from '@dxos/echo';
+import { Markdown } from '@dxos/plugin-markdown';
+import { Actor, AnchoredTo, Channel, Message, Thread } from '@dxos/types';
+
+import { meta } from '#meta';
+
+const THREAD_OPERATION = `${meta.id}.operation`;
+
+export const OnCreateSpace = Operation.make({
+  meta: { key: `${THREAD_OPERATION}.on-create-space`, 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: `${THREAD_OPERATION}.create-channel`, 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: `${THREAD_OPERATION}.append-channel-message`,
+    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: `${THREAD_OPERATION}.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: `${THREAD_OPERATION}.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: `${THREAD_OPERATION}.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: `${THREAD_OPERATION}.toggle-resolved`, 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: `${THREAD_OPERATION}.add-message`, 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: `${THREAD_OPERATION}.delete-message`, 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: `${THREAD_OPERATION}.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: `${THREAD_OPERATION}.restore-message`,
+    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: `${THREAD_OPERATION}.respond-to-thread`,
+    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: `${THREAD_OPERATION}.set-agent-config`,
+    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: 'org.dxos.function.thread.create-proposals',
+    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,5 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-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

@@ -2,104 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import * as Schema from 'effect/Schema';
-
-import { Type } from '@dxos/echo';
-import { EchoObjectSchema, SpaceSchema } from '@dxos/react-client/echo';
-import { Collection } from '@dxos/schema';
-import { Actor, AnchoredTo, Message, Thread } from '@dxos/types';
-
-import { meta } from '../meta';
-
-import * as Channel from './Channel';
-
-export namespace ThreadAction {
-  export class onCreateSpace extends Schema.TaggedClass<onCreateSpace>()(`${meta.id}/action/on-space-created`, {
-    input: Schema.Struct({
-      space: SpaceSchema,
-      rootCollection: Collection.Collection,
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class CreateChannel extends Schema.TaggedClass<CreateChannel>()(`${meta.id}/action/create-channel`, {
-    input: Schema.Struct({
-      spaceId: Type.SpaceId,
-      name: Schema.optional(Schema.String),
-    }),
-    output: Schema.Struct({
-      object: Channel.Channel,
-    }),
-  }) {}
-
-  export class CreateChannelThread extends Schema.TaggedClass<CreateChannelThread>()(
-    `${meta.id}/action/create-channel-thread`,
-    {
-      input: Schema.Struct({
-        channel: Channel.Channel,
-      }),
-      output: Schema.Struct({
-        object: Thread.Thread,
-      }),
-    },
-  ) {}
-
-  export class Create extends Schema.TaggedClass<Create>()(`${meta.id}/action/create`, {
-    input: Schema.Struct({
-      name: Schema.optional(Schema.String),
-      anchor: Schema.optional(Schema.String),
-      subject: EchoObjectSchema,
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class Delete extends Schema.TaggedClass<Delete>()(`${meta.id}/action/delete`, {
-    input: Schema.Struct({
-      anchor: AnchoredTo.AnchoredTo,
-      subject: EchoObjectSchema,
-      thread: Schema.optional(Thread.Thread),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class Select extends Schema.TaggedClass<Select>()(`${meta.id}/action/select`, {
-    input: Schema.Struct({
-      current: Schema.String,
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class ToggleResolved extends Schema.TaggedClass<ToggleResolved>()(`${meta.id}/action/toggle-resolved`, {
-    input: Schema.Struct({
-      thread: Thread.Thread,
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class AddMessage extends Schema.TaggedClass<AddMessage>()(`${meta.id}/action/add-message`, {
-    input: Schema.Struct({
-      subject: EchoObjectSchema,
-      anchor: AnchoredTo.AnchoredTo,
-      sender: Actor.Actor,
-      text: Schema.String,
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class DeleteMessage extends Schema.TaggedClass<DeleteMessage>()(`${meta.id}/action/delete-message`, {
-    input: Schema.Struct({
-      anchor: AnchoredTo.AnchoredTo,
-      subject: EchoObjectSchema,
-      messageId: Schema.String,
-      message: Schema.optional(Message.Message),
-      messageIndex: Schema.optional(Schema.Number),
-    }),
-    output: Schema.Void,
-  }) {}
-}
-
-export const ThreadSettingsSchema = Schema.mutable(Schema.Struct({}));
-export type ThreadSettingsProps = Schema.Schema.Type<typeof ThreadSettingsSchema>;
+import { AnchoredTo, Thread } from '@dxos/types';
 
 export interface ThreadModel {
   root: Thread.Thread;
@@ -113,6 +16,7 @@ export type ThreadState = {
   /** Object toolbar state. */
   toolbar: Record<string, boolean>;
   /** In-memory draft threads. */
+  // TODO(burdon): Drafts are getting lost.
   drafts: Record<string, AnchoredTo.AnchoredTo[]>;
   current?: string | undefined;
 };

package/src/util.ts

@@ -5,22 +5,54 @@
 import * as Match from 'effect/Match';
 
 import { generateName } from '@dxos/display-name';
-import { type Selection } from '@dxos/plugin-attention';
 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,