@dxos/plugin-observability 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

package/package.json

@@ -1,78 +1,116 @@
 {
   "name": "@dxos/plugin-observability",
-  "version": "0.8.4-main.fffef41",
+  "version": "0.8.4-staging.60fe92afc8",
   "description": "DXOS app framework plugin for hooking up app observability",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
-  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": true,
   "type": "module",
+  "imports": {
+    "#capabilities": {
+      "source": "./src/capabilities/index.ts",
+      "types": "./dist/types/src/capabilities/index.d.ts",
+      "default": "./dist/lib/neutral/capabilities/index.mjs"
+    },
+    "#components": {
+      "source": "./src/components/index.ts",
+      "types": "./dist/types/src/components/index.d.ts",
+      "default": "./dist/lib/neutral/components/index.mjs"
+    },
+    "#meta": {
+      "source": "./src/meta.ts",
+      "types": "./dist/types/src/meta.d.ts",
+      "default": "./dist/lib/neutral/meta.mjs"
+    },
+    "#operations": {
+      "source": "./src/operations/index.ts",
+      "types": "./dist/types/src/operations/index.d.ts",
+      "default": "./dist/lib/neutral/operations/index.mjs"
+    },
+    "#plugin": {
+      "source": {
+        "workerd": "./src/ObservabilityPlugin.workerd.ts",
+        "node": "./src/ObservabilityPlugin.node.ts",
+        "default": "./src/ObservabilityPlugin.ts"
+      },
+      "types": "./dist/types/src/ObservabilityPlugin.d.ts",
+      "workerd": "./dist/lib/neutral/ObservabilityPlugin.workerd.mjs",
+      "node": "./dist/lib/neutral/ObservabilityPlugin.node.mjs",
+      "default": "./dist/lib/neutral/ObservabilityPlugin.mjs"
+    },
+    "#translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "default": "./dist/lib/neutral/translations.mjs"
+    },
+    "#types": {
+      "source": "./src/types/index.ts",
+      "types": "./dist/types/src/types/index.d.ts",
+      "default": "./dist/lib/neutral/types/index.mjs"
+    }
+  },
   "exports": {
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": "./dist/lib/node-esm/index.mjs"
+      "default": "./dist/lib/neutral/index.mjs"
     },
-    "./types": {
-      "source": "./src/types/index.ts",
-      "types": "./dist/types/src/types/index.d.ts",
-      "browser": "./dist/lib/browser/types/index.mjs",
-      "node": "./dist/lib/node-esm/types/index.mjs"
+    "./plugin": {
+      "source": "./src/plugin.ts",
+      "types": "./dist/types/src/plugin.d.ts",
+      "default": "./dist/lib/neutral/plugin.mjs"
+    },
+    "./translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "default": "./dist/lib/neutral/translations.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "types": [
-        "dist/types/src/types/index.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@preact-signals/safe-react": "^0.9.0",
-    "@preact/signals-core": "^1.12.1",
-    "effect": "3.18.3",
-    "localforage": "^1.10.0",
-    "@dxos/async": "0.8.4-main.fffef41",
-    "@dxos/context": "0.8.4-main.fffef41",
-    "@dxos/echo": "0.8.4-main.fffef41",
-    "@dxos/local-storage": "0.8.4-main.fffef41",
-    "@dxos/invariant": "0.8.4-main.fffef41",
-    "@dxos/log": "0.8.4-main.fffef41",
-    "@dxos/live-object": "0.8.4-main.fffef41",
-    "@dxos/app-framework": "0.8.4-main.fffef41",
-    "@dxos/observability": "0.8.4-main.fffef41",
-    "@dxos/plugin-graph": "0.8.4-main.fffef41",
-    "@dxos/react-client": "0.8.4-main.fffef41",
-    "@dxos/protocols": "0.8.4-main.fffef41",
-    "@dxos/react-ui-form": "0.8.4-main.fffef41",
-    "@dxos/react-ui-stack": "0.8.4-main.fffef41",
-    "@dxos/util": "0.8.4-main.fffef41"
+    "@effect-atom/atom-react": "^0.5.0",
+    "effect": "3.21.3",
+    "@dxos/app-framework": "0.8.4-staging.60fe92afc8",
+    "@dxos/app-toolkit": "0.8.4-staging.60fe92afc8",
+    "@dxos/client": "0.8.4-staging.60fe92afc8",
+    "@dxos/compute": "0.8.4-staging.60fe92afc8",
+    "@dxos/effect": "0.8.4-staging.60fe92afc8",
+    "@dxos/invariant": "0.8.4-staging.60fe92afc8",
+    "@dxos/keys": "0.8.4-staging.60fe92afc8",
+    "@dxos/log": "0.8.4-staging.60fe92afc8",
+    "@dxos/observability": "0.8.4-staging.60fe92afc8",
+    "@dxos/util": "0.8.4-staging.60fe92afc8",
+    "@dxos/react-ui-form": "0.8.4-staging.60fe92afc8"
   },
   "devDependencies": {
-    "@effect-atom/atom-react": "^0.3.4",
-    "@effect/platform": "0.92.1",
-    "@types/react": "~19.2.2",
-    "react": "~19.2.0",
-    "vite": "7.1.9",
-    "@dxos/react-ui": "0.8.4-main.fffef41",
-    "@dxos/storybook-utils": "0.8.4-main.fffef41",
-    "@dxos/react-ui-theme": "0.8.4-main.fffef41"
+    "@effect-atom/atom-react": "^0.5.0",
+    "@effect/platform": "0.96.1",
+    "@types/react": "~19.2.7",
+    "react": "~19.2.3",
+    "vite": "^8.0.16",
+    "@dxos/plugin-testing": "0.8.4-staging.60fe92afc8",
+    "@dxos/react-ui": "0.8.4-staging.60fe92afc8",
+    "@dxos/storybook-utils": "0.8.4-staging.60fe92afc8",
+    "@dxos/ui-theme": "0.8.4-staging.60fe92afc8"
   },
   "peerDependencies": {
-    "@effect-atom/atom-react": "^0.3.4",
-    "@effect/platform": "^0.80.12",
-    "effect": "^3.13.3",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "@dxos/react-ui": "0.8.4-main.fffef41",
-    "@dxos/react-ui-theme": "0.8.4-main.fffef41"
+    "@effect-atom/atom-react": "^0.5.0",
+    "@effect/platform": "0.96.1",
+    "effect": "3.21.3",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "@dxos/react-ui": "0.8.4-staging.60fe92afc8",
+    "@dxos/ui-theme": "0.8.4-staging.60fe92afc8"
   },
   "publishConfig": {
     "access": "public"

package/src/ObservabilityPlugin.node.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability, Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
+import { Operation, OperationHandlerSet } from '@dxos/compute';
+
+import { meta } from '#meta';
+import { ObservabilityOperation } from '#types';
+
+// TODO(wittjosiah): Hook up.
+export const ObservabilityPlugin = Plugin.define(meta).pipe(
+  AppPlugin.addOperationHandlerModule({
+    activate: Capability.lazy('OperationHandler', () =>
+      Promise.resolve({
+        default: Capability.makeModule<OperationHandlerSet.OperationHandlerSet>(
+          Effect.fnUntraced(function* () {
+            return Capability.contributes(
+              Capabilities.OperationHandler,
+              OperationHandlerSet.make(Operation.withHandler(ObservabilityOperation.SendEvent, () => Effect.void)),
+            );
+          }),
+        ),
+      }),
+    ),
+  }),
+  Plugin.make,
+);
+
+export default ObservabilityPlugin;

package/src/ObservabilityPlugin.test.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { createComposerTestApp } from '@dxos/plugin-testing/harness';
+
+import { ObservabilityPlugin } from '#plugin';
+
+import { meta } from './meta';
+
+const moduleId = (name: string) => `${meta.id}.module.${name}`;
+
+describe('ObservabilityPlugin', () => {
+  test('modules activate on the expected events', async ({ expect }) => {
+    await using harness = await createComposerTestApp({
+      // TODO(wittjosiah): Align browser and node variant option types.
+      plugins: [ObservabilityPlugin({} as any)],
+    });
+
+    // OperationHandler fires automatically (ProcessManagerPlugin fires SetupProcessManager during Startup).
+    expect(harness.manager.getActive()).toContain(moduleId('OperationHandler'));
+  });
+});

package/src/ObservabilityPlugin.ts

@@ -2,69 +2,88 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Capabilities, Events, allOf, contributes, defineModule, definePlugin } from '@dxos/app-framework';
+import * as Effect from 'effect/Effect';
+
+import { ActivationEvent, ActivationEvents, Capability, Plugin } from '@dxos/app-framework';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
 import { type Observability } from '@dxos/observability';
 
 import {
-  AppGraphBuilder,
   ClientReady,
-  IntentResolver,
-  ObservabilityCapabilities,
   ObservabilitySettings,
   ObservabilityState,
+  OperationHandler,
+  PrivacyNotice,
   ReactSurface,
-} from './capabilities';
-import { ClientReadyEvent, ObservabilityEvents } from './events';
-import { meta } from './meta';
-import { translations } from './translations';
+} from '#capabilities';
+import { meta } from '#meta';
+import { translations } from '#translations';
+import { ObservabilityCapabilities, ObservabilityEvents } from '#types';
 
 export type ObservabilityPluginOptions = {
   namespace: string;
-  observability: () => Promise<Observability>;
+  observability: () => Promise<Observability.Observability>;
+  /**
+   * Optional callback invoked by the help/feedback UI to download captured logs.
+   * When omitted the "Download logs" action is hidden.
+   */
+  downloadLogs?: () => void | Promise<void>;
 };
 
-export const ObservabilityPlugin = definePlugin<ObservabilityPluginOptions>(meta, ({ namespace, observability }) => [
-  defineModule({
-    id: `${meta.id}/module/observability`,
-    activatesOn: Events.Startup,
-    activate: async () => contributes(ObservabilityCapabilities.Observability, await observability()),
-  }),
-  defineModule({
-    id: `${meta.id}/module/settings`,
-    activatesOn: Events.SetupSettings,
+export const ObservabilityPlugin = Plugin.define<ObservabilityPluginOptions>(meta).pipe(
+  AppPlugin.addSurfaceModule({ activate: ReactSurface }),
+  AppPlugin.addTranslationsModule({ translations }),
+  Plugin.addModule(({ observability }) => ({
+    id: 'observability',
+    activatesOn: ActivationEvents.Startup,
+    activate: () =>
+      Effect.gen(function* () {
+        const obs = yield* Effect.tryPromise(() => observability());
+        return Capability.contributes(ObservabilityCapabilities.Observability, obs);
+      }),
+  })),
+  Plugin.addModule({
+    activatesOn: AppActivationEvents.SetupSettings,
     activate: ObservabilitySettings,
   }),
-  defineModule({
-    id: `${meta.id}/module/state`,
-    activatesOn: Events.Startup,
-    activatesAfter: [ObservabilityEvents.StateReady],
+  Plugin.addModule(({ namespace }) => ({
+    id: Capability.getModuleTag(ObservabilityState),
+    activatesOn: ActivationEvents.Startup,
+    firesAfterActivation: [ObservabilityEvents.StateReady],
     activate: () => ObservabilityState({ namespace }),
+  })),
+  Plugin.addModule(({ namespace }) => ({
+    id: 'namespace',
+    activatesOn: ActivationEvents.Startup,
+    activate: () => Effect.succeed(Capability.contributes(ObservabilityCapabilities.Namespace, namespace)),
+  })),
+  Plugin.addModule(({ downloadLogs }) => ({
+    id: 'log-downloader',
+    activatesOn: ActivationEvents.Startup,
+    activate: () =>
+      Effect.succeed(
+        downloadLogs !== undefined ? Capability.contributes(ObservabilityCapabilities.LogDownloader, downloadLogs) : [],
+      ),
+  })),
+  AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
+  Plugin.addModule({
+    activatesOn: ActivationEvent.make('org.dxos.plugin.client.event.identity-created'),
+    activate: PrivacyNotice,
   }),
-  defineModule({
-    id: `${meta.id}/module/translations`,
-    activatesOn: Events.SetupTranslations,
-    activate: () => contributes(Capabilities.Translations, translations),
-  }),
-  defineModule({
-    id: `${meta.id}/module/intent-resolver`,
-    activatesOn: Events.SetupIntentResolver,
-    activate: (context) => IntentResolver({ context, namespace }),
-  }),
-  defineModule({
-    id: `${meta.id}/module/react-surface`,
-    activatesOn: Events.SetupReactSurface,
-    activate: ReactSurface,
-  }),
-  defineModule({
-    id: `${meta.id}/module/app-graph-builder`,
-    activatesOn: Events.SetupAppGraph,
-    activate: AppGraphBuilder,
-  }),
-  defineModule({
-    id: `${meta.id}/module/client-ready`,
-    activatesOn: allOf(Events.DispatcherReady, ObservabilityEvents.StateReady, ClientReadyEvent),
-    activate: async (context) => {
-      return ClientReady({ context, observability: await observability(), namespace });
-    },
-  }),
-]);
+  Plugin.addModule(({ namespace, observability }) => ({
+    id: Capability.getModuleTag(ClientReady),
+    activatesOn: ActivationEvent.allOf(
+      ActivationEvents.ProcessManagerReady,
+      ObservabilityEvents.StateReady,
+      ObservabilityEvents.ClientReadyEvent,
+    ),
+    activate: () =>
+      Effect.gen(function* () {
+        const obs = yield* Effect.tryPromise(() => observability());
+        return yield* ClientReady({ namespace, observability: obs });
+      }),
+  })),
+  Plugin.make,
+);
+
+export default ObservabilityPlugin;

package/src/ObservabilityPlugin.workerd.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability, Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
+import { Operation, OperationHandlerSet } from '@dxos/compute';
+
+import { meta } from '#meta';
+import { ObservabilityOperation } from '#types';
+
+export const ObservabilityPlugin = Plugin.define(meta).pipe(
+  AppPlugin.addOperationHandlerModule({
+    activate: Capability.lazy('OperationHandler', () =>
+      Promise.resolve({
+        default: Capability.makeModule<OperationHandlerSet.OperationHandlerSet>(
+          Effect.fnUntraced(function* () {
+            return Capability.contributes(
+              Capabilities.OperationHandler,
+              OperationHandlerSet.make(Operation.withHandler(ObservabilityOperation.SendEvent, () => Effect.void)),
+            );
+          }),
+        ),
+      }),
+    ),
+  }),
+  Plugin.make,
+);
+
+export default ObservabilityPlugin;

package/src/capabilities/client-ready.ts

@@ -2,97 +2,65 @@
 // Copyright 2025 DXOS.org
 //
 
-import {
-  Capabilities,
-  LayoutAction,
-  type PluginContext,
-  SettingsAction,
-  contributes,
-  createIntent,
-} from '@dxos/app-framework';
-import { type Observability, setupTelemetryListeners } from '@dxos/observability';
+import * as Effect from 'effect/Effect';
 
-import { meta } from '../meta';
-import { ObservabilityAction } from '../types';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { log } from '@dxos/log';
+import { type Observability, ObservabilityProvider } from '@dxos/observability';
 
-import { ClientCapability, ObservabilityCapabilities } from './capabilities';
+import { ObservabilityCapabilities, ObservabilityOperation } from '#types';
 
-type ClientReadyOptions = {
-  context: PluginContext;
+export type ClientReadyOptions = {
   namespace: string;
-  observability: Observability;
+  observability: Observability.Observability;
 };
 
-export default async ({ context, namespace, observability }: ClientReadyOptions) => {
-  const manager = context.getCapability(Capabilities.PluginManager);
-  const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
-  const state = context.getCapability(ObservabilityCapabilities.State);
-  const client = context.getCapability(ClientCapability);
+export default Capability.makeModule(
+  Effect.fnUntraced(function* ({ observability }: ClientReadyOptions) {
+    const manager = yield* Capability.get(Capabilities.PluginManager);
+    const { invokePromise } = yield* Capability.get(Capabilities.OperationInvoker);
+    const client = yield* Capability.get(ObservabilityCapabilities.ClientCapability);
 
-  const sendPrivacyNotice = async () => {
-    const environment = client?.config?.values.runtime?.app?.env?.DX_ENVIRONMENT;
-    const notify =
-      environment && environment !== 'ci' && !environment.endsWith('.local') && !environment.endsWith('.lan');
-    if (!state.notified && notify) {
-      await dispatch(
-        createIntent(LayoutAction.AddToast, {
-          part: 'toast',
-          subject: {
-            id: `${meta.id}/notice`,
-            title: ['observability toast label', { ns: meta.id }],
-            description: ['observability toast description', { ns: meta.id }],
-            duration: Infinity,
-            icon: 'ph--info--regular',
-            actionLabel: ['observability toast action label', { ns: meta.id }],
-            actionAlt: ['observability toast action alt', { ns: meta.id }],
-            closeLabel: ['observability toast close label', { ns: meta.id }],
-            onAction: () => dispatch(createIntent(SettingsAction.Open, { plugin: meta.id })),
-          },
-        }),
-      );
-
-      state.notified = true;
+    // Ensure errors are tagged with enabled plugins to help with reproductions.
+    const enabledPlugins = manager.getEnabled();
+    log('client-ready: tagging enabled plugins', { count: enabledPlugins.length });
+    for (const plugin of enabledPlugins) {
+      observability.setTags({ [`pluginEnabled-${plugin}`]: 'true' }, 'errors');
     }
-  };
 
-  // Ensure errors are tagged with enabled plugins to help with reproductions.
-  manager.enabled.map((plugin) => observability?.setTag(`pluginEnabled-${plugin}`, 'true', 'errors'));
+    log('client-ready: sending page.load event');
+    yield* Effect.tryPromise(() =>
+      invokePromise(ObservabilityOperation.SendEvent, {
+        name: 'page.load',
+        properties: {
+          // TODO(wittjosiah): These apis are deprecated. Is there a better way to find this information?
+          loadDuration: window.performance.timing.loadEventEnd - window.performance.timing.loadEventStart,
+        },
+      }),
+    );
+    log('client-ready: page.load event sent');
 
-  await dispatch(
-    createIntent(ObservabilityAction.SendEvent, {
-      name: 'page.load',
-      properties: {
-        // TODO(wittjosiah): These apis are deprecated. Is there a better way to find this information?
-        loadDuration: window.performance.timing.loadEventEnd - window.performance.timing.loadEventStart,
-      },
-    }),
-  );
+    // Each provider is logged individually because some provider setups perform
+    // RPC calls (e.g. runtimeMetricsProvider awaits SystemService.getPlatform());
+    // a hung worker pipe surfaces as a missing "added" log, so the last
+    // "adding ..." line points to the stall.
+    log('client-ready: adding identity data provider');
+    yield* observability.addDataProvider(ObservabilityProvider.Client.identityProvider(client.services.services));
+    log('client-ready: identity data provider added');
 
-  // Start client observability (i.e. not running as shared worker)
-  // TODO(nf): how to prevent multiple instances for single shared worker?
-  const cleanup = setupTelemetryListeners(namespace, client, observability);
+    log('client-ready: adding network metrics data provider');
+    yield* observability.addDataProvider(ObservabilityProvider.Client.networkMetricsProvider(client.services.services));
+    log('client-ready: network metrics data provider added');
 
-  await Promise.all([
-    observability.setIdentityTags(client.services.services),
-    observability.startRuntimeMetrics(client),
-    observability.startNetworkMetrics(client.services.services),
-    observability.startSpacesMetrics(client, namespace),
-  ]);
+    log('client-ready: adding runtime metrics data provider');
+    yield* observability.addDataProvider(ObservabilityProvider.Client.runtimeMetricsProvider(client.services.services));
+    log('client-ready: runtime metrics data provider added');
 
-  if (client.halo.identity.get()) {
-    await sendPrivacyNotice();
-  } else {
-    const subscription = client.halo.identity.subscribe(async (identity) => {
-      if (identity && observability) {
-        await sendPrivacyNotice();
-        await observability.setIdentityTags(client.services.services);
-        subscription.unsubscribe();
-      }
-    });
-  }
+    log('client-ready: adding space metrics data provider');
+    yield* observability.addDataProvider(ObservabilityProvider.Client.spacesMetricsProvider(client));
+    log('client-ready: space metrics data provider added');
 
-  return contributes(ObservabilityCapabilities.Observability, observability, async () => {
-    cleanup();
-    await observability.close();
-  });
-};
+    log('client-ready: contributing observability capability');
+    return Capability.contributes(ObservabilityCapabilities.Observability, observability, () => observability.close());
+  }),
+);

package/src/capabilities/index.ts

@@ -2,13 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-import { lazy } from '@dxos/app-framework';
+import { Capability } from '@dxos/app-framework';
+import { OperationHandlerSet } from '@dxos/compute';
 
-export const AppGraphBuilder = lazy(() => import('./app-graph-builder'));
-export const ClientReady = lazy(() => import('./client-ready'));
-export const IntentResolver = lazy(() => import('./intent-resolver'));
-export const ReactSurface = lazy(() => import('./react-surface'));
-export const ObservabilitySettings = lazy(() => import('./settings'));
-export const ObservabilityState = lazy(() => import('./state'));
+import type { ClientReadyOptions } from './client-ready';
 
-export * from './capabilities';
+export const ClientReady = Capability.lazy<ClientReadyOptions>('ClientReady', () => import('./client-ready'));
+export const PrivacyNotice = Capability.lazy('PrivacyNotice', () => import('./privacy-notice'));
+export const OperationHandler = Capability.lazy<OperationHandlerSet.OperationHandlerSet>(
+  'OperationHandler',
+  () => import('./operation-handler'),
+);
+export const ReactSurface = Capability.lazy('ReactSurface', () => import('./react-surface'));
+export const ObservabilitySettings = Capability.lazy('ObservabilitySettings', () => import('./settings'));
+export const ObservabilityState = Capability.lazy('ObservabilityState', () => import('./state'));

package/src/capabilities/operation-handler.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import type { OperationHandlerSet } from '@dxos/compute';
+
+import { ObservabilityOperationHandlerSet } from '#operations';
+
+export default Capability.makeModule<OperationHandlerSet.OperationHandlerSet>(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(Capabilities.OperationHandler, ObservabilityOperationHandlerSet);
+  }),
+);

package/src/capabilities/privacy-notice.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { LayoutOperation, SettingsOperation } from '@dxos/app-toolkit';
+
+import { meta } from '#meta';
+import { ObservabilityCapabilities } from '#types';
+
+/**
+ * Shows the privacy notice toast once when an identity is first created.
+ * Activates on `ClientEvents.IdentityCreated` — which only fires for genuinely
+ * new identities, not for recovered or joined ones — so no HALO device-count
+ * checks or session-storage flags are needed.
+ */
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const { invokePromise } = yield* Capability.get(Capabilities.OperationInvoker);
+    const registry = yield* Capability.get(Capabilities.AtomRegistry);
+    const stateAtom = yield* Capability.get(ObservabilityCapabilities.State);
+    const client = yield* Capability.get(ObservabilityCapabilities.ClientCapability);
+
+    const environment = client?.config?.values.runtime?.app?.env?.DX_ENVIRONMENT;
+    const notify =
+      environment && environment !== 'ci' && !environment.endsWith('.local') && !environment.endsWith('.lan');
+
+    const state = registry.get(stateAtom);
+    if (!state.notified && notify) {
+      yield* Effect.tryPromise(() =>
+        invokePromise(LayoutOperation.AddToast, {
+          id: `${meta.id}.notice`,
+          title: ['observability-toast.label', { ns: meta.id }],
+          description: ['observability-toast.description', { ns: meta.id }],
+          duration: Infinity,
+          icon: 'ph--info--regular',
+          actionLabel: ['observability-toast-action.label', { ns: meta.id }],
+          actionAlt: ['observability-toast-action.alt', { ns: meta.id }],
+          closeLabel: ['observability-toast-close.label', { ns: meta.id }],
+          onAction: () => invokePromise(SettingsOperation.Open, { plugin: meta.id }),
+        }),
+      );
+      registry.set(stateAtom, { ...registry.get(stateAtom), notified: true });
+    }
+
+    return [];
+  }),
+);