@dxos/protocols 0.8.4-main.fbb7a13 → 0.8.4-main.fcc0d83b33

package/src/edge/registry.ts

@@ -0,0 +1,125 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+/**
+ * Hydrated plugin metadata, mirroring the @dxos/app-framework `Plugin.Meta` shape.
+ *
+ * Defined locally rather than imported from @dxos/app-framework to keep the protocols
+ * package free of UI/runtime dependencies. Consumers can treat decoded values as
+ * `Plugin.Meta` directly.
+ */
+export const PluginMetaSchema = Schema.Struct({
+  id: Schema.String.pipe(Schema.nonEmptyString()),
+  name: Schema.String.pipe(Schema.nonEmptyString()),
+  description: Schema.optional(Schema.String),
+  author: Schema.optional(Schema.String),
+  homePage: Schema.optional(Schema.String),
+  source: Schema.optional(Schema.String),
+  screenshots: Schema.optional(Schema.Array(Schema.String)),
+  tags: Schema.optional(Schema.Array(Schema.String)),
+  icon: Schema.optional(Schema.String),
+  iconHue: Schema.optional(Schema.String),
+});
+export type PluginMeta = Schema.Schema.Type<typeof PluginMetaSchema>;
+
+/**
+ * Health signal the registry service attaches to a hydrated entry when a refresh fails.
+ * Clients surface the appropriate badge or filter entries based on this field.
+ */
+export const PluginHealthSchema = Schema.Literal('ok', 'release-missing', 'manifest-invalid', 'repo-unavailable');
+export type PluginHealth = Schema.Schema.Type<typeof PluginHealthSchema>;
+
+/**
+ * Filename of the entry module every plugin must publish at the root of its bundle.
+ * The host dynamic-imports `<manifest URL base>/index.mjs` directly — no per-plugin
+ * configuration. `composerPlugin` outputs the bundle under this name so plugin authors
+ * never have to think about it.
+ */
+export const PLUGIN_ENTRY_FILENAME = 'index.mjs';
+
+/**
+ * Shape of the manifest-asset JSON the registry service fetches from each plugin's latest release.
+ *
+ * Emitted by `@dxos/app-framework/vite-plugin`'s `composerPlugin` (see
+ * `MANIFEST_ASSET_NAME`). Lists every file the plugin needs at runtime — the entry
+ * module ({@link PLUGIN_ENTRY_FILENAME}) plus any sibling CSS, code-split chunks,
+ * fonts, etc. — so the host can eagerly precache the whole bundle for offline use.
+ * Paths in `assets` are relative to the manifest's URL.
+ */
+export const PluginManifestSchema = Schema.Struct({
+  ...PluginMetaSchema.fields,
+  /** Plugin version (semver). Sourced from the publishing project's `package.json`. */
+  version: Schema.String.pipe(Schema.nonEmptyString()),
+  /**
+   * Relative paths of every file the plugin needs at runtime, including the entry.
+   * Must include {@link PLUGIN_ENTRY_FILENAME}; consumers verify on parse.
+   */
+  assets: Schema.Array(Schema.String).pipe(Schema.minItems(1)),
+});
+export type PluginManifest = Schema.Schema.Type<typeof PluginManifestSchema>;
+
+/**
+ * Single hydrated plugin entry returned by the registry service.
+ */
+export const PluginEntrySchema = Schema.Struct({
+  /** GitHub repository in `owner/name` form. Empty string for entries sourced from a `manifestUrl`. */
+  repo: Schema.String,
+  /** Plugin metadata from the repo's latest-release `manifest.json`. */
+  meta: PluginMetaSchema,
+  /**
+   * URL of the plugin's `manifest.json`. Composer's URL loader fetches this, eagerly caches
+   * every declared asset via the platform `PluginAssetCache`, then dynamic-imports the entry.
+   * The URL must be CORS-safe and have its declared assets reachable as siblings.
+   */
+  moduleUrl: Schema.String,
+  /** Release tag the entry was resolved from (e.g. `v0.1.0`). Empty string for `manifestUrl` entries. */
+  releaseTag: Schema.String,
+  /** Health signal set by the service when an entry fails to refresh. */
+  health: PluginHealthSchema,
+  /** Unix ms when this entry was last successfully hydrated. */
+  hydratedAt: Schema.Number,
+});
+export type PluginEntry = Schema.Schema.Type<typeof PluginEntrySchema>;
+
+/**
+ * Response body of `GET /registry/plugins`.
+ */
+export const GetPluginsResponseBodySchema = Schema.Struct({
+  /** Wire-format schema version, pinned to 1. */
+  version: Schema.Literal(1),
+  /** Hydrated entries. Order matches the order in the upstream catalog manifest. */
+  plugins: Schema.Array(PluginEntrySchema),
+  /** Unix ms timestamp of the most recent successful refresh cycle. */
+  refreshedAt: Schema.Number,
+});
+export type GetPluginsResponseBody = Schema.Schema.Type<typeof GetPluginsResponseBodySchema>;
+
+/**
+ * A catalog entry. Two flavours:
+ *  - `{ repo }`: the registry service hydrates from the GitHub repo's latest release.
+ *    Used by the production catalog.
+ *  - `{ manifestUrl }`: the registry service skips GitHub and fetches the manifest directly.
+ *    Used for local development against an in-progress plugin (e.g. served by `vite preview`)
+ *    so authors can iterate without publishing a release.
+ */
+export const RegistryEntrySchema = Schema.Union(
+  Schema.Struct({ repo: Schema.String.pipe(Schema.nonEmptyString()) }),
+  Schema.Struct({ manifestUrl: Schema.String.pipe(Schema.nonEmptyString()) }),
+);
+export type RegistryEntry = Schema.Schema.Type<typeof RegistryEntrySchema>;
+
+/**
+ * Shape of the catalog manifest published in the upstream community-plugins repo.
+ * Extra keys (e.g. `$schema`) are permitted.
+ */
+export const RegistryManifestSchema = Schema.Struct(
+  {
+    version: Schema.Literal(1),
+    plugins: Schema.Array(RegistryEntrySchema),
+  },
+  Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+);
+export type RegistryManifest = Schema.Schema.Type<typeof RegistryManifestSchema>;

package/src/errors/encoding.ts

@@ -2,9 +2,8 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type Error as SerializedErrorProto } from '../proto/gen/dxos/error.js';
-
-import { reconstructError } from './helpers.js';
+import { type Error as SerializedErrorProto } from '../proto/gen/dxos/error.ts';
+import { reconstructError } from './helpers.ts';
 
 export const encodeError = (err: any): SerializedErrorProto => {
   if (typeof err === 'object' && err?.message) {

package/src/errors/errors.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { ApiError } from './base-errors.js';
+import { ApiError } from './base-errors.ts';
 
 describe('Errors', () => {
   test('test', async () => {

package/src/errors/errors.ts

@@ -5,9 +5,8 @@
 import { BaseError } from '@dxos/errors';
 import { PublicKey } from '@dxos/keys';
 
-import type { ObjectId } from '../types.js';
-
-import { registerError, registerErrorMessageContext, registerErrorNoArgs } from './helpers.js';
+import type { ObjectId } from '../types.ts';
+import { registerError, registerErrorMessageContext, registerErrorNoArgs } from './helpers.ts';
 
 /**
  * Thrown when request was terminated because the RPC endpoint has been closed.

package/src/errors/helpers.ts

@@ -5,7 +5,7 @@
 import { BaseError } from '@dxos/errors';
 import { invariant } from '@dxos/invariant';
 
-import { type Error as SerializedErrorProto } from '../proto/gen/dxos/error.js';
+import { type Error as SerializedErrorProto } from '../proto/gen/dxos/error.ts';
 
 export const reconstructError = (error: SerializedErrorProto) => {
   const { name, message, context } = error;

package/src/errors/index.ts

@@ -2,8 +2,8 @@
 // Copyright 2022 DXOS.org
 //
 
-export * from './encoding.js';
-export * from './errors.js';
-export * from './helpers.js';
-export * from './base-errors.js';
-export * from './parameter.js';
+export * from './encoding.ts';
+export * from './errors.ts';
+export * from './helpers.ts';
+export * from './base-errors.ts';
+export * from './parameter.ts';

package/src/index.ts

@@ -2,17 +2,14 @@
 // Copyright 2021 DXOS.org
 //
 
-// TODO(burdon): Why export .js?
-
-export * from './automerge.js';
-export * from './edge/index.js';
-export * from './errors/index.js';
-export * from './indexing.js';
-export * from './messenger.js';
-export * from './profile-archive.js';
-export * from './queue.js';
-export * from './space-archive.js';
-export * from './storage.js';
-export * from './tracing.js';
-export type * from './types.js';
-export * as FunctionProtocol from './FunctionProtocol.js';
+export * from './automerge.ts';
+export * from './edge/index.ts';
+export * from './errors/index.ts';
+export * from './indexing.ts';
+export * from './messenger.ts';
+export * from './profile-archive.ts';
+export * from './space-archive.ts';
+export * from './storage.ts';
+export type * from './types.ts';
+export * as FunctionProtocol from './FunctionProtocol.ts';
+export * as FeedProtocol from './FeedProtocol.ts';

package/src/indexing.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { ObjectPointerVersion, objectPointerCodec } from './indexing.js';
+import { ObjectPointerVersion, objectPointerCodec } from './indexing.ts';
 
 describe('Indexing object pointer codec', () => {
   test('getVersion', async () => {

package/src/proto/dxos/client/queue.proto

@@ -2,7 +2,6 @@ syntax = "proto3";
 
 package dxos.client.services;
 
-import "google/protobuf/struct.proto";
 import "google/protobuf/empty.proto";
 
 
@@ -34,9 +33,12 @@ message QueueQuery {
 }
 
 message QueueQueryResult {
-  repeated google.protobuf.Struct objects = 1;
+  /// JSON-encoded object payloads. Each entry is a serialized ObjectJSON.
+  /// We use JSON strings instead of google.protobuf.Struct because Struct
+  /// coerces `undefined` to `null`, corrupting optional fields.
+  repeated string objects = 1;
 
-  /// Cursor to query the next items. Can be passed to `after` in query to keep querying. 
+  /// Cursor to query the next items. Can be passed to `after` in query to keep querying.
   string next_cursor = 2;
 
   string prev_cursor = 3;
@@ -50,7 +52,8 @@ message InsertIntoQueueRequest {
   string subspace_tag = 1;
   string space_id = 2;
   string queue_id = 3;
-  repeated google.protobuf.Struct objects = 4;
+  /// JSON-encoded object payloads. Each entry is a serialized ObjectJSON.
+  repeated string objects = 4;
 }
 
 message DeleteFromQueueRequest {
@@ -60,8 +63,19 @@ message DeleteFromQueueRequest {
   repeated string object_ids = 4;
 }
 
+message SyncQueueRequest {
+  string subspace_tag = 1;
+  string space_id = 2;
+  string queue_id = 3;
+  /// Whether to push local changes to the server. Defaults to true.
+  optional bool should_push = 4;
+  /// Whether to pull remote changes from the server. Defaults to true.
+  optional bool should_pull = 5;
+}
+
 service QueueService {
   rpc QueryQueue(QueryQueueRequest) returns (QueueQueryResult);
   rpc InsertIntoQueue(InsertIntoQueueRequest) returns (google.protobuf.Empty);
   rpc DeleteFromQueue(DeleteFromQueueRequest) returns (google.protobuf.Empty);
+  rpc SyncQueue(SyncQueueRequest) returns (google.protobuf.Empty);
 }

package/src/proto/dxos/client/services.proto

@@ -72,6 +72,7 @@ message Platform {
     BROWSER = 0;
     SHARED_WORKER = 1;
     NODE = 2;
+    DEDICATED_WORKER = 3;
   }
 
   PLATFORM_TYPE type = 1;
@@ -331,6 +332,8 @@ message Space {
   optional PipelineState pipeline = 3;
   optional dxos.error.Error error = 4;
   optional dxos.echo.metadata.EdgeReplicationSetting edge_replication = 6;
+  repeated string tags = 7;
+  dxos.halo.credentials.MembershipPolicy membership_policy = 8;
 
   repeated SpaceMember members = 10;
   optional dxos.keys.PublicKey creator = 11;
@@ -341,6 +344,11 @@ message Space {
 
 // TODO(burdon): Create type for epoch?
 
+message CreateSpaceRequest {
+  repeated string tags = 1;
+  dxos.halo.credentials.MembershipPolicy membership_policy = 2;
+}
+
 message UpdateSpaceRequest {
   dxos.keys.PublicKey space_key = 1;
 
@@ -435,12 +443,22 @@ message JoinBySpaceKeyRequest {
 }
 
 message SpaceArchive {
+  enum Format {
+    // Tar-based binary archive (default).
+    BINARY = 0;
+    // JSON encoding of {@link dxos.echo.db.SerializedSpace}.
+    JSON = 1;
+  }
+
   string filename = 1;
   bytes contents = 2;
+  optional Format format = 3;
 }
 
 message ExportSpaceRequest {
   string space_id = 1;
+  // Archive format to produce. Defaults to BINARY.
+  optional SpaceArchive.Format format = 2;
 }
 
 message ExportSpaceResponse {
@@ -457,7 +475,7 @@ message ImportSpaceResponse {
 }
 
 service SpacesService {
-  rpc CreateSpace(google.protobuf.Empty) returns (Space);
+  rpc CreateSpace(CreateSpaceRequest) returns (Space);
   rpc UpdateSpace(UpdateSpaceRequest) returns (google.protobuf.Empty);
   rpc QuerySpaces(google.protobuf.Empty) returns (stream QuerySpacesResponse);
 

package/src/proto/dxos/config.proto

@@ -59,7 +59,7 @@ message Module {
   optional string id = 8;   // TODO(burdon): Ensured FQ (e.g., 'dxos.app.xxx')
   optional string name = 1; // TODO(burdon): Replace with id (or key?)
   optional string type = 2; // TODO(burdon): Define namespace (e.g.,
-                            // 'dxos.org/type/frame' vs. 'dxos.type.frame')
+                            // 'org.dxos.type.frame')
 
   // TODO(burdon): Developer info message.
 
@@ -84,6 +84,17 @@ message Module {
 
 message Runtime {
   message Client {
+    /// Where client services run. Drives `createClientServices` routing.
+    enum ServicesMode {
+      UNSPECIFIED_SERVICES_MODE = 0;
+      /// Run services in the same thread as the client.
+      HOST = 1;
+      /// Run services in a SharedWorker (single instance shared across tabs).
+      SHARED_WORKER = 2;
+      /// Run services in a dedicated Worker elected via a lock (leader/follower).
+      DEDICATED_WORKER = 3;
+    }
+
     message Storage {
       enum StorageDriver {
         RAM = 0;
@@ -98,6 +109,20 @@ message Runtime {
         JSONDOWN = 12;
       }
 
+      /// Storage backing for SQLite (indexes & persistent state). The caller must supply the
+      /// matching worker factory / path — `createClientServices` does not pick a mode from the
+      /// presence of options.
+      enum SqliteMode {
+        UNSPECIFIED_SQLITE_MODE = 0;
+        /// Ephemeral in-memory SQLite. Indexes are rebuilt on each start.
+        MEMORY = 1;
+        /// OPFS-backed SQLite running in a dedicated worker (browser).
+        /// Requires `createOpfsWorker` to be passed to `createClientServices`.
+        OPFS = 2;
+        /// File-backed SQLite (Node/Bun). Uses `data_root` to locate the database file.
+        FILE = 3;
+      }
+
       optional bool persistent = 1;
       optional StorageDriver key_store = 2;
       optional StorageDriver data_store = 3;
@@ -107,6 +132,9 @@ message Runtime {
        * @deprecated
        */
       optional bool space_fragmentation = 5;
+
+      /// Backing store for SQLite runtimes. Defaults to MEMORY when unset.
+      optional SqliteMode sqlite_mode = 6;
     }
 
     message Log {
@@ -156,7 +184,24 @@ message Runtime {
 
     optional EdgeFeatures edge_features = 11;
 
-    optional bool enable_local_queues = 13;
+    /// Observability group attached as metadata to signaling requests.
+    /// NOTE: When running through a shared worker, subsequent client connections can refresh this
+    /// value (last-writer-wins); the first client still determines the worker's other config.
+    optional string observability_group = 13;
+
+    /// Enable telemetry metadata attached to signaling requests.
+    /// NOTE: When running through a shared worker, subsequent client connections can refresh this
+    /// value (last-writer-wins); the first client still determines the worker's other config.
+    optional bool signal_telemetry_enabled = 14;
+
+    /// Use in-process (single-client) coordinator for dedicated-worker mode.
+    /// Bypasses SharedWorker; used for WKWebView where the coordinator SharedWorker port is unreliable.
+    optional bool single_client_mode = 15;
+
+    /// Deployment mode for client services. Read by `createClientServices` to select between
+    /// in-process (HOST), SharedWorker, and dedicated Worker runtimes. Required when no
+    /// `remote_source` is configured.
+    optional ServicesMode services_mode = 16;
   }
 
   message App {

package/src/proto/dxos/echo/metadata.proto

@@ -54,6 +54,9 @@ message SpaceMetadata {
   /// Space key.
   dxos.keys.PublicKey key = 1;
 
+  /// Immutable tags assigned at space creation time.
+  repeated string tags = 12;
+
   /// ACTIVE, INACTIVE, etc.
   optional dxos.client.services.SpaceState state = 10;
 

package/src/proto/dxos/edge/messenger.proto

@@ -76,9 +76,19 @@ message Message {
   /// Maybe be used to address a service at EDGE, but also to address components inside the client.
   optional string service_id = 20;
 
+  optional TraceContext trace_context = 21;
+
   optional google.protobuf.Any payload = 100;
 }
 
+/// W3C Trace Context propagation (https://www.w3.org/TR/trace-context/).
+message TraceContext {
+  /// W3C `traceparent` header value (e.g. "00-<trace-id>-<parent-id>-<trace-flags>").
+  string traceparent = 1;
+  /// W3C `tracestate` header value; vendor-specific key-value pairs.
+  optional string tracestate = 2;
+}
+
 //
 // Swarms are used to publish and subscribe to messages based on a topic.
 //

package/src/proto/dxos/halo/credentials.proto

@@ -28,9 +28,18 @@ import "dxos/keys.proto";
 // First message written to initial Feed in a new Space.
 //
 
+enum MembershipPolicy {
+  /// Members can be invited by admins/owners.
+  INVITE = 0;
+  /// No new members can be added after genesis.
+  LOCKED = 1;
+}
+
 // [ASSERTION]
 message SpaceGenesis {
   dxos.keys.PublicKey space_key = 1; // Feeds belong to Spaces.
+  repeated string tags = 2;
+  MembershipPolicy membership_policy = 3;
 }
 
 //
@@ -60,6 +69,9 @@ message SpaceMember {
   dxos.keys.PublicKey space_key = 1;
   Role role = 2;
 
+  /// Immutable tags assigned at space creation time.
+  repeated string tags = 6;
+
   // TODO(burdon): Identity key?
   optional ProfileDocument profile = 3;
 
@@ -163,6 +175,8 @@ enum DeviceType {
   UNKNOWN = 0;
   BROWSER = 1;
   NATIVE = 2;
+  // TODO(wittjosiah): Rename "agent" to avoid naming collision with AI agents.
+  // TODO(wittjosiah): Unknown, Browser, CLI, Desktop, Mobile, Custodian?
   AGENT = 3;
   AGENT_MANAGED = 4;
   MOBILE = 5;
@@ -188,6 +202,7 @@ message DeviceProfile {
 }
 
 /// [ASSERTION]: Sets default space for identity.
+/// @deprecated Default space is no longer managed by the SDK. Existing credentials are ignored.
 message DefaultSpace {
   string space_id = 1;
 }

package/src/proto/dxos/iframe.proto

@@ -15,9 +15,6 @@ message StartRequest {
   string origin = 1;
   /// Key for the iframe resource lock used to determine when the service is closing.
   optional string lock_key = 2;
-  // TODO(nf): extract or remove?
-  optional string observabilityGroup = 3;
-  optional bool signalTelemetryEnabled = 4;
 }
 
 /// Iframe-to-worker RPCs.

package/src/proto/dxos/rpc.proto

@@ -29,11 +29,18 @@ message RpcMessage {
   }
 }
 
+/// W3C trace context carried across RPC boundaries.
+message TraceContext {
+  string traceparent = 1;
+  optional string tracestate = 2;
+}
+
 message Request {
   int32 id = 1;
   string method = 2;
   google.protobuf.Any payload = 3;
   bool stream = 4;
+  optional TraceContext trace_context = 5;
 }
 
 message Response {

package/src/proto/dxos/tracing.proto

@@ -30,42 +30,6 @@ message ResourceLink {
   google.protobuf.Struct attributes = 4;
 }
 
-message Span {
-  int32 id = 1;
-  optional int32 parent_id = 2;
-  optional int32 resource_id = 3;
-  string method_name = 4;
-
-  // TODO(dmaretskyi): Figure out proper sub-millisecond timestamp type.
-  string start_ts = 5;
-  optional string end_ts = 6;
-
-  optional dxos.error.Error error = 11;
-}
-
-message StreamTraceEvent {
-  message ResourceAdded {
-    Resource resource = 1;
-  }
-
-  message ResourceRemoved {
-    int32 id = 1;
-  }
-
-  message SpanAdded {
-    Span span = 1;
-  }
-
-  message LogAdded {
-    dxos.client.services.LogEntry log = 1;
-  }
-
-  repeated ResourceAdded resource_added = 1;
-  repeated ResourceRemoved resource_removed = 2;
-  repeated SpanAdded span_added = 3;
-  repeated LogAdded log_added = 4;
-}
-
 message Metric {
   message Counter {
     double value = 1;
@@ -110,7 +74,3 @@ message Metric {
     Custom custom = 199;
   }
 }
-
-service TracingService {
-  rpc StreamTrace(google.protobuf.Empty) returns (stream StreamTraceEvent);
-}

package/src/proto/gen/dxos/agent/dashboard.ts

@@ -66,8 +66,7 @@ import * as example_testing_data from "../../example/testing/data.js";
 import * as example_testing_rpc from "../../example/testing/rpc.js";
 import * as google_protobuf from "../../google/protobuf.js";
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/dashboard.proto}
+ * Defined in: `../../../dxos/agent/dashboard.proto`
  */
 export interface AgentStatus {
     status: AgentStatus.Status;
@@ -88,8 +87,7 @@ export namespace AgentStatus {
         OFF = 1
     }
     /**
-     * Defined in:
-     *   {@link file://./../../../dxos/agent/dashboard.proto}
+     * Defined in: `../../../dxos/agent/dashboard.proto`
      */
     export interface Memory {
         /**
@@ -104,8 +102,7 @@ export namespace AgentStatus {
     }
 }
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/dashboard.proto}
+ * Defined in: `../../../dxos/agent/dashboard.proto`
  */
 export interface PluginState {
     id: string;

package/src/proto/gen/dxos/agent/echoproxy.ts

@@ -66,8 +66,7 @@ import * as example_testing_data from "../../example/testing/data.js";
 import * as example_testing_rpc from "../../example/testing/rpc.js";
 import * as google_protobuf from "../../google/protobuf.js";
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/echo-proxy.proto}
+ * Defined in: `../../../dxos/agent/echo-proxy.proto`
  */
 export interface Config {
     /**

package/src/proto/gen/dxos/agent/epoch.ts

@@ -66,8 +66,7 @@ import * as example_testing_data from "../../example/testing/data.js";
 import * as example_testing_rpc from "../../example/testing/rpc.js";
 import * as google_protobuf from "../../google/protobuf.js";
 /**
- * Defined in:
- *   {@link file://./../../../dxos/agent/epoch.proto}
+ * Defined in: `../../../dxos/agent/epoch.proto`
  */
 export interface EpochMonitorConfig {
     /**