@dxos/plugin-thread 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 → 0.13.0

package/src/operations/index.ts

@@ -2,12 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-import * as Operation from '@dxos/compute/Operation';
-import * as OperationHandlerSet from '@dxos/compute/OperationHandlerSet';
-
-import { ThreadOperation } from '#types';
-
-export const ThreadOperationHandlerSet = OperationHandlerSet.lazy([
-  ThreadOperation.AppendChannelMessage.pipe(Operation.lazyHandler(() => import('./append-channel-message'))),
-  ThreadOperation.CreateChannel.pipe(Operation.lazyHandler(() => import('./create-channel'))),
-]);
+export * as ThreadOperationHandlerSet from './ThreadOperationHandlerSet.ts';

package/src/operations/open-direct.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Operation from '@dxos/compute/Operation';
+import { Database } from '@dxos/echo';
+
+import { ChannelBackend, ThreadOperation } from '#types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.OpenDirect> = ThreadOperation.OpenDirect.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ channel: channelRef, person: personRef }) {
+      const channel = yield* Database.load(channelRef);
+      const person = yield* Database.load(personRef);
+      const provider = yield* ChannelBackend.getProvider(channel);
+      const openDirect = yield* ChannelBackend.requireMember(provider, 'openDirect');
+      // As with sending, a backend refusal is an outcome the caller relays.
+      return yield* openDirect(channel, person).pipe(
+        Effect.map((thread) =>
+          thread === undefined
+            ? { reason: `The person has no ${provider.label} handle the channel can reach.` }
+            : { thread },
+        ),
+        Effect.catch((error) => Effect.succeed({ reason: error.message })),
+      );
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/send-to-channel.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Operation from '@dxos/compute/Operation';
+import { Database } from '@dxos/echo';
+import { Message } from '@dxos/types';
+
+import { ChannelBackend, ThreadOperation } from '#types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.SendToChannel> = ThreadOperation.SendToChannel.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ channel: channelRef, thread, text }) {
+      const channel = yield* Database.load(channelRef);
+      const provider = yield* ChannelBackend.getProvider(channel);
+      const message = Message.make({ sender: { role: 'assistant' }, blocks: [{ _tag: 'text', text }] });
+      const send =
+        thread === undefined
+          ? provider.send(channel, message)
+          : (yield* ChannelBackend.requireMember(provider, 'threads')).send(channel, thread, message);
+
+      // A backend refusal (closed DMs, missing permission) is an outcome the caller relays, not a failure.
+      return yield* send.pipe(
+        Effect.map((result) => ({ delivered: true, ...ChannelBackend.toReceipt(result) })),
+        Effect.catch((error) => Effect.succeed({ delivered: false, reason: error.message })),
+      );
+    }),
+  ),
+);
+
+export default handler;

package/src/plugin.test.ts

@@ -5,7 +5,7 @@
 import { describe, test } from 'vitest';
 
 import * as ClientPlugin from '@dxos/plugin-client/ClientPlugin';
-import { createComposerTestApp } from '@dxos/plugin-testing/harness';
+import * as Harness from '@dxos/plugin-testing/Harness';
 
 import { meta } from '#meta';
 import { ThreadPlugin } from '#plugin';
@@ -13,8 +13,8 @@ import { ThreadPlugin } from '#plugin';
 const moduleId = (name: string) => `${meta.profile.key}.module.${name}`;
 
 describe('ThreadPlugin', () => {
-  test('modules activate on the expected events', async ({ expect }) => {
-    await using harness = await createComposerTestApp({
+  test('modules activate on the expected events', { timeout: 60_000 }, async ({ expect }) => {
+    await using harness = await Harness.createComposerTestApp({
       plugins: [ClientPlugin.make({}), ThreadPlugin()],
     });
 

package/src/translations.ts

@@ -3,7 +3,7 @@
 //
 
 import { Type } from '@dxos/echo';
-import { type Resource } from '@dxos/react-ui';
+import type * as Theme from '@dxos/react-ui/Theme';
 import { Channel } from '@dxos/types';
 
 import { meta } from '#meta';
@@ -95,4 +95,4 @@ export const translations = [
       },
     },
   },
-] as const satisfies Resource[];
+] as const satisfies Theme.Resource[];

package/src/types/ChannelBackend.test.ts

@@ -8,8 +8,8 @@ import { describe, test } from 'vitest';
 
 import { Feed } from '@dxos/echo';
 
-import { buildChannelFormSchema, resolveProvider } from './ChannelBackend';
-import * as ThreadCapabilities from './ThreadCapabilities';
+import { buildChannelFormSchema, resolveProvider } from './ChannelBackend.ts';
+import * as ThreadCapabilities from './ThreadCapabilities.ts';
 
 describe('channel-backend helpers', () => {
   test('resolveProvider finds by kind', ({ expect }) => {

package/src/types/ChannelBackend.ts

@@ -2,11 +2,29 @@
 // Copyright 2026 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
-import { SchemaAST } from '@dxos/effect';
+import * as Capability from '@dxos/app-framework/Capability';
+import { type Database, type Feed, Filter, Query } from '@dxos/echo';
+import * as SchemaAST from '@dxos/effect/SchemaAST';
+import { BaseError } from '@dxos/errors';
+import { type Channel, Message } from '@dxos/types';
 
-import * as ThreadCapabilities from './ThreadCapabilities';
+import * as ThreadCapabilities from './ThreadCapabilities.ts';
+import type * as ThreadOperation from './ThreadOperation.ts';
+
+/** No contributed provider handles the channel's `backend.kind` (its plugin is disabled or absent). */
+export class ChannelBackendNotFoundError extends BaseError.extend(
+  'ChannelBackendNotFoundError',
+  'No channel backend handles this channel.',
+) {}
+
+/** The channel's backend lacks an optional member the caller needs (`openDirect`, `threads`, `connection`). */
+export class ChannelBackendUnsupportedError extends BaseError.extend(
+  'ChannelBackendUnsupportedError',
+  'The channel backend does not support this.',
+) {}
 
 /** Finds the provider matching a `Channel.backend.kind`. */
 export const resolveProvider = (
@@ -14,6 +32,52 @@ export const resolveProvider = (
   kind: string,
 ): ThreadCapabilities.ChannelBackendProvider | undefined => providers.find((provider) => provider.kind === kind);
 
+/** The contributed provider for a channel, or a typed failure naming the missing kind. */
+export const getProvider: (
+  channel: Channel.Channel,
+) => Effect.Effect<ThreadCapabilities.ChannelBackendProvider, ChannelBackendNotFoundError, Capability.Service> =
+  Effect.fnUntraced(function* (channel) {
+    const providers = yield* Capability.getAll(ThreadCapabilities.ChannelBackend);
+    const provider = resolveProvider(providers, channel.backend.kind);
+    if (!provider) {
+      return yield* Effect.fail(new ChannelBackendNotFoundError({ context: { kind: channel.backend.kind } }));
+    }
+    return provider;
+  });
+
+/** Narrows a provider to one that has the optional member `name`, or fails naming what is missing. */
+export const requireMember = <K extends 'openDirect' | 'threads' | 'connection'>(
+  provider: ThreadCapabilities.ChannelBackendProvider,
+  name: K,
+): Effect.Effect<NonNullable<ThreadCapabilities.ChannelBackendProvider[K]>, ChannelBackendUnsupportedError> => {
+  const member = provider[name];
+  return member === undefined
+    ? Effect.fail(
+        new ChannelBackendUnsupportedError({
+          message: `The ${provider.label} channel backend does not support ${name}.`,
+          context: { kind: provider.kind, member: name },
+        }),
+      )
+    : Effect.succeed(member);
+};
+
+/** A provider's send result as a receipt; a backend with nothing to report yields an empty one. */
+export const toReceipt = (result: ThreadCapabilities.SendResult): ThreadOperation.SendReceipt =>
+  typeof result === 'object' ? result : {};
+
+/**
+ * Subscribes to the messages appended to a feed, firing immediately; returns the unsubscribe.
+ * Shared by every backend whose messages live in (or are mirrored into) an ECHO feed.
+ */
+export const subscribeFeed = (
+  db: Database.Database,
+  feed: Feed.Feed,
+  onMessages: (messages: readonly Message.Message[]) => void,
+): (() => void) => {
+  const result = db.query(Query.select(Filter.type(Message.Message)).from(feed));
+  return result.subscribe(() => onMessages(result.results), { fire: true });
+};
+
 /** Throws if two providers share a `kind` (which would make resolution order-dependent). */
 export const assertUniqueKinds = (providers: readonly ThreadCapabilities.ChannelBackendProvider[]): void => {
   const seen = new Set<string>();

package/src/types/ThreadCapabilities.ts

@@ -4,15 +4,39 @@
 
 // @import-as-namespace
 
-import * as Effect from 'effect/Effect';
+import type * as Effect from 'effect/Effect';
 import type * as Schema from 'effect/Schema';
 
 import * as Capability from '@dxos/app-framework/Capability';
 import { type Obj } from '@dxos/echo';
-import { type Channel, type Message } from '@dxos/types';
+import { type Channel, type Message, type Person } from '@dxos/types';
 
 import { meta } from '#meta';
 
+import type * as ThreadOperation from './ThreadOperation.ts';
+
+/** What a backend reports about a post; `void` when it has nothing to report. */
+export type SendResult = ThreadOperation.SendReceipt | void;
+
+/**
+ * Threads inside a channel, for backends that have them (Discord threads and DM channels).
+ * Thread ids are backend-scoped strings, always paired with the channel they belong to.
+ */
+export interface ChannelThreads {
+  send: (
+    channel: Channel.Channel,
+    thread: string,
+    message: Message.Message,
+  ) => Effect.Effect<SendResult, Error, Capability.Service>;
+}
+
+/** A connection that must be started (a bot gateway, an IRC socket). */
+export interface ChannelConnection {
+  start: (channel: Channel.Channel) => Effect.Effect<ThreadOperation.ConnectionStatus, Error, Capability.Service>;
+  stop: (channel: Channel.Channel) => Effect.Effect<ThreadOperation.ConnectionStatus, Error, Capability.Service>;
+  status: (channel: Channel.Channel) => Effect.Effect<ThreadOperation.ConnectionStatus, Error, Capability.Service>;
+}
+
 /**
  * A pluggable message backend for a `Channel`. Providers are contributed by
  * plugins and resolved by `Channel.backend.kind`.
@@ -37,10 +61,23 @@ export interface ChannelBackendProvider {
    * list immediately and on every change. Returns an unsubscribe function.
    */
   subscribe: (channel: Channel.Channel, onMessages: (messages: readonly Message.Message[]) => void) => () => void;
-  /** Sends a message through the backend. */
-  send: (channel: Channel.Channel, message: Message.Message) => Effect.Effect<void, Error, Capability.Service>;
+  /** Sends a message through the backend; fails with a reason a person can act on. */
+  send: (channel: Channel.Channel, message: Message.Message) => Effect.Effect<SendResult, Error, Capability.Service>;
   /** Whether the channel is read-only. Defaults to "channel has foreign-key Obj.Meta". */
   readOnly?: (channel: Channel.Channel) => boolean;
+  /**
+   * Opens a direct conversation with a person through the channel's account (a Discord DM),
+   * returning its thread id; `undefined` when the person has no handle this backend knows.
+   * The person's handle is the backend's business, read from `Person.identities`.
+   */
+  openDirect?: (
+    channel: Channel.Channel,
+    person: Person.Person,
+  ) => Effect.Effect<string | undefined, Error, Capability.Service>;
+  /** Threads inside the channel (Discord threads and DM channels). */
+  threads?: ChannelThreads;
+  /** A connection that must be started; absent means the backend is always available. */
+  connection?: ChannelConnection;
 }
 
 /** Registry of channel-message backends. Collect with `Capability.getAll`. */

package/src/types/ThreadOperation.ts

@@ -8,11 +8,8 @@ import * as Schema from 'effect/Schema';
 
 import * as Capability from '@dxos/app-framework/Capability';
 import * as Operation from '@dxos/compute/Operation';
-import { DXN, Key, Type } from '@dxos/echo';
-// Person is referenced in Actor.Actor's inferred type; importing it allows TypeScript to name
-// it in the emitted .d.ts for AppendChannelMessage.
-// eslint-disable-next-line unused-imports/no-unused-imports
-import { Actor, Channel, type Person } from '@dxos/types';
+import { Database, DXN, Key, Ref, Type } from '@dxos/echo';
+import { Actor, Channel, Person } from '@dxos/types';
 
 export const CreateChannel = Operation.make({
   meta: {
@@ -50,3 +47,115 @@ export const AppendChannelMessage = Operation.make({
   }),
   output: Schema.Void,
 });
+
+/**
+ * What a backend reports about a message it posted. `properties` are stamped on the copy a caller
+ * records locally, so a mirror of that record (EDGE's Discord bot) can tell it was already posted.
+ */
+export const SendReceipt = Schema.Struct({
+  messageIds: Schema.optional(Schema.Array(Schema.String).annotate({ description: 'Backend ids of the posts.' })),
+  properties: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+});
+
+export interface SendReceipt extends Schema.Schema.Type<typeof SendReceipt> {}
+
+/** Whether a backend's connection (a bot gateway, an IRC socket) is up. */
+export const ConnectionStatus = Schema.Struct({
+  running: Schema.Boolean,
+  /** Backend-specific state name, e.g. a gateway's `connecting` or `ready`. */
+  state: Schema.optional(Schema.String),
+  detail: Schema.optional(Schema.String.annotate({ description: 'A short human-readable summary.' })),
+  error: Schema.optional(Schema.String.annotate({ description: 'Why the connection last failed.' })),
+});
+
+export interface ConnectionStatus extends Schema.Schema.Type<typeof ConnectionStatus> {}
+
+/** Sends text to a channel, or to a thread inside it, through the channel's backend. */
+export const SendToChannel = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.thread.sendToChannel'),
+    name: 'Send to channel',
+    description: "Sends a message to a channel, or to a thread inside it, through the channel's backend.",
+    icon: 'ph--paper-plane-tilt--regular',
+  },
+  services: [Database.Service, Capability.Service],
+  input: Schema.Struct({
+    channel: Ref.Ref(Channel.Channel).annotate({ description: 'The channel to send to.' }),
+    thread: Schema.optional(
+      Schema.String.annotate({ description: 'A backend-scoped thread id (a Discord thread or DM channel id).' }),
+    ),
+    text: Schema.String.annotate({ description: 'The message.' }),
+  }),
+  output: Schema.Struct({
+    delivered: Schema.Boolean,
+    ...SendReceipt.fields,
+    reason: Schema.optional(Schema.String.annotate({ description: 'Why the message was not delivered.' })),
+  }),
+});
+
+/** Opens (or finds) a direct conversation with a person through the channel's account. */
+export const OpenDirect = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.thread.openDirect'),
+    name: 'Open direct conversation',
+    description:
+      "Opens a direct conversation (a DM) with a person through the channel's account; returns its thread id.",
+    icon: 'ph--user-circle--regular',
+  },
+  services: [Database.Service, Capability.Service],
+  input: Schema.Struct({
+    channel: Ref.Ref(Channel.Channel).annotate({ description: 'The channel whose account sends the direct message.' }),
+    person: Ref.Ref(Person.Person).annotate({ description: 'The person to reach.' }),
+  }),
+  output: Schema.Struct({
+    thread: Schema.optional(
+      Schema.String.annotate({ description: 'The direct thread id; pass it to sendToChannel as `thread`.' }),
+    ),
+    reason: Schema.optional(Schema.String.annotate({ description: 'Why the person cannot be reached directly.' })),
+  }),
+});
+
+/** Starts the channel's connection (or reconfigures a running one). */
+export const ConnectChannel = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.thread.connectChannel'),
+    name: 'Connect channel',
+    description: "Starts the channel backend's connection, e.g. a bot gateway.",
+    icon: 'ph--play--regular',
+  },
+  services: [Database.Service, Capability.Service],
+  input: Schema.Struct({
+    channel: Ref.Ref(Channel.Channel).annotate({ description: 'The channel to connect.' }),
+  }),
+  output: Schema.Struct({ status: ConnectionStatus }),
+});
+
+/** Stops the channel's connection. */
+export const DisconnectChannel = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.thread.disconnectChannel'),
+    name: 'Disconnect channel',
+    description: "Stops the channel backend's connection.",
+    icon: 'ph--stop--regular',
+  },
+  services: [Database.Service, Capability.Service],
+  input: Schema.Struct({
+    channel: Ref.Ref(Channel.Channel).annotate({ description: 'The channel to disconnect.' }),
+  }),
+  output: Schema.Struct({ status: ConnectionStatus }),
+});
+
+/** Reports the channel's connection status. */
+export const GetChannelStatus = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.thread.getChannelStatus'),
+    name: 'Get channel status',
+    description: "Reports whether the channel backend's connection is up.",
+    icon: 'ph--pulse--regular',
+  },
+  services: [Database.Service, Capability.Service],
+  input: Schema.Struct({
+    channel: Ref.Ref(Channel.Channel).annotate({ description: 'The channel to report on.' }),
+  }),
+  output: Schema.Struct({ status: ConnectionStatus }),
+});

package/src/types/index.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-export * as ChannelBackend from './ChannelBackend';
-export * as ThreadCapabilities from './ThreadCapabilities';
-export * as ThreadEvents from './ThreadEvents';
-export * as ThreadOperation from './ThreadOperation';
+export * as ChannelBackend from './ChannelBackend.ts';
+export * as ThreadCapabilities from './ThreadCapabilities.ts';
+export * as ThreadEvents from './ThreadEvents.ts';
+export * as ThreadOperation from './ThreadOperation.ts';

package/dist/lib/chunk-paths.mjs

@@ -1,8 +0,0 @@
-import * as GraphPath from "@dxos/app-toolkit/GraphPath";
-import { Channel } from "@dxos/types";
-//#region src/paths.ts
-var { getSectionPath: getChannelsPath, getObjectPath: getChannelPath } = GraphPath.createTypeSectionPaths(Channel.Channel, { groupId: GraphPath.GroupSegments.communications });
-//#endregion
-export { getChannelsPath as n, getChannelPath as t };
-
-//# sourceMappingURL=chunk-paths.mjs.map

package/dist/lib/chunk-paths.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"chunk-paths.mjs","names":[],"sources":["../../src/paths.ts"],"sourcesContent":["//\n// Copyright 2025 DXOS.org\n//\n\nimport * as GraphPath from '@dxos/app-toolkit/GraphPath';\nimport { Channel } from '@dxos/types';\n\nconst { getSectionPath: getChannelsPath, getObjectPath: getChannelPath } = GraphPath.createTypeSectionPaths(\n  Channel.Channel,\n  { groupId: GraphPath.GroupSegments.communications },\n);\n\nexport { getChannelPath, getChannelsPath };\n"],"mappings":";;;AAOA,IAAM,EAAE,gBAAgB,iBAAiB,eAAe,mBAAmB,UAAU,uBACnF,QAAQ,SACR,EAAE,SAAS,UAAU,cAAc,eAAe,CACpD"}

package/dist/lib/operations.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"operations.mjs","names":[],"sources":["../../src/operations/index.ts"],"sourcesContent":["//\n// Copyright 2025 DXOS.org\n//\n\nimport * as Operation from '@dxos/compute/Operation';\nimport * as OperationHandlerSet from '@dxos/compute/OperationHandlerSet';\n\nimport { ThreadOperation } from '#types';\n\nexport const ThreadOperationHandlerSet = OperationHandlerSet.lazy([\n  ThreadOperation.AppendChannelMessage.pipe(Operation.lazyHandler(() => import('./append-channel-message'))),\n  ThreadOperation.CreateChannel.pipe(Operation.lazyHandler(() => import('./create-channel'))),\n]);\n"],"mappings":";;;;AASA,IAAa,4BAA4B,oBAAoB,KAAK,CAChE,gBAAgB,qBAAqB,KAAK,UAAU,kBAAkB,OAAO,qCAA2B,CAAC,GACzG,gBAAgB,cAAc,KAAK,UAAU,kBAAkB,OAAO,6BAAmB,CAAC,CAC5F,CAAC"}