@dxos/protocols 0.8.4-main.fffef41 → 0.8.4-staging.ac66bdf99f

package/src/{edge.ts → edge/edge.ts}

@@ -8,11 +8,25 @@ import { BaseError } from '@dxos/errors';
 import { invariant } from '@dxos/invariant';
 import { SpaceId } from '@dxos/keys';
 
+/**
+ * HTTP header sent on every Edge request to classify traffic for metering.
+ */
+export const EDGE_CLIENT_TAG_HEADER = 'X-DXOS-Client-Tag';
+
 // TODO(burdon): Rename EdgerRouterEndpoint.
 // If we would rename it, we need to be careful to not break composer production.
 export enum EdgeService {
   AUTOMERGE_REPLICATOR = 'automerge-replicator',
+  /**
+   * Control feed replicator (hypercore append only logs) for the space.
+   */
+  // TODO(mykola): Remove once we migrate to keyhive for access control.
   FEED_REPLICATOR = 'feed-replicator',
+  /**
+   * Feed replicator (ordered data list) for the space.
+   */
+  // TODO(mykola): Rename to FEED_REPLICATOR when we migrate to keyhive for access control.
+  QUEUE_REPLICATOR = 'queue-replicator',
   SWARM = 'swarm',
   SIGNAL = 'signal',
   STATUS = 'status',
@@ -23,13 +37,15 @@ export type EdgeSuccess<T> = {
   data: T;
 };
 
-export type SerializedError = {
-  code?: string;
-  message?: string;
-  context?: Record<string, unknown>;
-  stack?: string;
-  cause?: SerializedError;
-};
+const _SerializedError = Schema.Struct({
+  name: Schema.optional(Schema.String),
+  message: Schema.optional(Schema.String),
+  context: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+  stack: Schema.optional(Schema.String),
+  cause: Schema.optional(Schema.suspend(() => SerializedError)),
+});
+export interface SerializedError extends Schema.Schema.Type<typeof _SerializedError> {}
+export const SerializedError: Schema.Schema<SerializedError, SerializedError, never> = _SerializedError;
 
 export type EdgeErrorData = { type: string } & Record<string, any>;
 
@@ -37,11 +53,6 @@ export type EdgeErrorData = { type: string } & Record<string, any>;
  * This is the shape of the error response from the Edge service,
  * when the error is gracefully handled, the Response will be an object with this shape and have status code 200.
  */
-// TODO(dmaretskyi): Refactor this type to just be { success: false, error: SerializedError }
-// reason -> error.message
-// cause -> error.cause
-// errorData.type -> error.code
-// ...errorData -> error.context
 export type EdgeFailure = {
   /**
    * Branded Type.
@@ -50,11 +61,11 @@ export type EdgeFailure = {
   /**
    * An explanation of why the call failed. Used mostly for logging and monitoring.
    */
-  reason: string;
+  message: string;
   /**
    * Cause Error captured on the EDGE service to aid debugging on the client.
    */
-  cause?: SerializedError;
+  error?: SerializedError;
   /**
    * Information that can be used to retry the request such that it will succeed, for example:
    * 1. { type: 'auth_required', challenge: string }
@@ -62,16 +73,16 @@ export type EdgeFailure = {
    * 2. { type: 'user_confirmation_required', dialog: { title: string, message: string, confirmation_payload: string } }
    *    Requires showing a confirmation dialog to a user and retrying the request with confirmation_payload included
    *    if the user confirms.
-   * When errorData is returned simply retrying the request won't have any effect.
-   * EdgeHttpClient should parse well-known errorData into Error types and throw.
+   * When data is returned simply retrying the request won't have any effect.
+   * EdgeHttpClient should parse well-known data into Error types and throw.
    */
-  errorData?: EdgeErrorData;
+  data?: EdgeErrorData;
 };
 
 /**
  * Represents a body response from the Edge service.
  */
-export type EdgeBody<T> = EdgeSuccess<T> | EdgeFailure;
+export type EdgeEnvelope<T> = EdgeSuccess<T> | EdgeFailure;
 
 /**
  * Use this to create a response from the Edge service.
@@ -92,21 +103,32 @@ export const EdgeResponse = Object.freeze({
     );
   },
   failure: ({
-    reason,
-    cause,
-    errorData,
+    message,
+    error,
+    errorEncoded,
+    data,
     shouldRetryAfter,
     status = 500,
   }: {
     /**
      * An explanation of why the call failed. Used mostly for logging and monitoring.
      */
-    reason: string;
+    message: string;
     /**
      * Error that caused the failure.
      * Useful for debugging.
+     *
+     * Use only one of the fields `error` or `errorEncoded`.s
+     */
+    error?: Error;
+    /**
+     * Encoded Error that caused the failure.
+     * Useful for debugging.
+     *
+     * Use only one of the fields `error` or `errorEncoded`.
      */
-    cause?: Error;
+    errorEncoded?: SerializedError;
+
     /**
      * Information that can be used to retry the request such that it will succeed, for example:
      * 1. { type: 'auth_required', challenge: string }
@@ -114,10 +136,10 @@ export const EdgeResponse = Object.freeze({
      * 2. { type: 'user_confirmation_required', dialog: { title: string, message: string, confirmation_payload: string } }
      *    Requires showing a confirmation dialog to a user and retrying the request with confirmation_payload included
      *    if the user confirms.
-     * When errorData is returned simply retrying the request won't have any effect.
-     * EdgeHttpClient should parse well-known errorData into Error types and throw.
+     * When data is returned simply retrying the request won't have any effect.
+     * EdgeHttpClient should parse well-known data into Error types and throw.
      */
-    errorData?: EdgeErrorData;
+    data?: EdgeErrorData;
     /**
      * If provided, this request will be marked as retryable and the client will wait for the specified number of milliseconds before retrying.
      * If not provided, the client will not retry the request.
@@ -138,9 +160,9 @@ export const EdgeResponse = Object.freeze({
     return new Response(
       JSON.stringify({
         success: false,
-        reason,
-        errorData,
-        cause: cause ? ErrorCodec.encode(cause) : undefined,
+        message,
+        data,
+        error: error ? ErrorCodec.encode(error) : errorEncoded,
       } satisfies EdgeFailure),
       {
         status,
@@ -232,20 +254,19 @@ export type UploadFunctionRequest = {
    * Runtime cannot be changed once the function was deployed.
    * @default Runtime.WORKERS_FOR_PLATFORMS
    */
-  runtime?: Runtime;
+  runtime?: FunctionRuntimeKind;
 };
 
 /**
  * Note: Do not change the values of these enums, this values are stored in the FunctionVersions database.
  */
-export enum Runtime {
+export const FunctionRuntimeKind = Schema.Enums({
   // https://developers.cloudflare.com/cloudflare-for-platforms/workers-for-platforms/
-  WORKERS_FOR_PLATFORMS = 'WORKERS_FOR_PLATFORMS',
+  WORKERS_FOR_PLATFORMS: 'WORKERS_FOR_PLATFORMS',
   // https://developers.cloudflare.com/workers/runtime-apis/bindings/worker-loader/
-  WORKER_LOADER = 'WORKER_LOADER',
-  // Local worker dispatcher for testing.
-  TEST = 'TEST',
-}
+  WORKER_LOADER: 'WORKER_LOADER',
+});
+export type FunctionRuntimeKind = Schema.Schema.Type<typeof FunctionRuntimeKind>;
 
 export type UploadFunctionResponseBody = {
   functionId: string;
@@ -408,15 +429,15 @@ const MAX_ERROR_DEPTH = 3;
  */
 export const ErrorCodec = Object.freeze({
   encode: (err: Error, depth: number = 0): SerializedError => ({
-    code: 'code' in err ? (err as any).code : undefined,
+    name: 'name' in err ? err.name : (err as any).code || 'Error',
     message: err.message,
     stack: err.stack,
     cause: err.cause instanceof Error && depth < MAX_ERROR_DEPTH ? ErrorCodec.encode(err.cause, depth + 1) : undefined,
   }),
   decode: (serializedError: SerializedError, depth: number = 0): Error => {
     let err: Error;
-    if (typeof serializedError.code === 'string') {
-      err = new BaseError(serializedError.code, {
+    if (typeof serializedError.name === 'string') {
+      err = new BaseError(serializedError.name, {
         message: serializedError.message ?? 'Unknown error',
         cause:
           serializedError.cause && depth < MAX_ERROR_DEPTH
@@ -475,3 +496,109 @@ export const EdgeHttpErrorCodec = Object.freeze({
     return ErrorCodec.decode(body.error);
   },
 });
+
+//
+// Data management.
+//
+
+export type ListSpacesRequest = { limit?: number; cursor?: string; order?: 'asc' | 'desc' };
+export type ListSpacesResponse = {
+  spaces: SpaceActivityEntry[];
+  cursor?: string;
+  limit: number;
+};
+
+export type ListActiveIdentitiesRequest = { cursor?: string; limit?: number };
+export type ListActiveIdentitiesResponse = {
+  identities: {
+    identityKey: string;
+    haloSpaceId: string | null;
+    createdAt: string | null;
+    agentKey: string | null;
+    hasRecovery: boolean;
+  }[];
+  cursor?: string;
+  complete: boolean;
+  totalCount: number;
+};
+
+export type InspectSpaceRequest = { spaceId: string };
+export type InspectSpaceResponse = {
+  spaceId: string;
+  metadata: { createdAt: string; identityKey?: string; status?: 'active' | 'deleting' } | null;
+  members: {
+    count: number;
+    list: { identityKey: string; role?: string; agentKey?: string }[];
+  };
+  controlFeeds: {
+    replicationProgress: { [feedKey: string]: { replicated: number; processed: number } };
+  };
+  echo: {
+    dataFeeds: {
+      count: number;
+      totalBlocks: number;
+      byNamespace: { namespace: string; feeds: { feedId: string; blockCount: number }[] }[];
+    };
+    documentCount: number;
+    objectCount: number;
+    deletedObjectCount: number;
+    indexedDocumentCount: number;
+    objectsByType: { typeDxn: string; count: number }[];
+    indexerStatus: {
+      indexingInProgress: boolean;
+      cursors: { indexName: string; sourceName: string; resourceId: string | null; cursor: string | number }[];
+      totalChanges: number;
+    };
+  };
+  usageInLast30Days: {
+    lastActivity: string | null;
+    wsEvents: number;
+    httpEvents: number;
+    totalEvents: number;
+  } | null;
+  durableObjects: { type: string; doId: string }[];
+};
+
+export type InspectIdentityRequest = { identityKey: string };
+export type InspectIdentityResponse = {
+  identityKey: string;
+  agentKey: string | null;
+  haloSpaceId: string | null;
+  hasRecovery: boolean;
+  routerDoId: string;
+  agentDoId: string | null;
+  ownedFunctions: { id: string; name: string; versionCount: number }[];
+  spaces: InspectSpaceResponse[];
+};
+
+/** Matches the SerializedSpace format from @dxos/echo-db, extended with spaceId. */
+export type SpaceExportPayload = {
+  version: number;
+  timestamp: string;
+  spaceId: string;
+  objects: Record<string, unknown>[];
+};
+
+export type SpaceActivityEntry = {
+  spaceId: string;
+  lastActivity: string;
+  totalEvents: number;
+  metadata: { createdAt: string; identityKey?: string; status?: 'active' | 'deleting' } | null;
+};
+
+export type SpaceExportResult = {
+  spaceId: string;
+  downloadPath: string;
+  downloadUrl: string;
+  expiresAt: string;
+  objectCount: number;
+  sizeBytes: number;
+};
+
+export type ExportSpaceRequest = { spaceId: string; origin: string };
+
+export type DeleteSpaceRequest = { spaceId: string };
+export type DeleteSpaceResponse = { status: string; spaceId: string };
+
+export type DeleteIdentityRequest = { identityKey: string };
+export type DeleteIdentityResponse = { status: string; identityKey: string };

package/src/{edge-error.ts → edge/errors.ts}

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type EdgeErrorData, type EdgeFailure, EdgeHttpErrorCodec, ErrorCodec } from './edge.js';
+import { type EdgeErrorData, type EdgeFailure, EdgeHttpErrorCodec, ErrorCodec } from './edge.ts';
 
 // TODO(burdon): Reconcile with @dxos/errors.
 /**
@@ -16,11 +16,11 @@ import { type EdgeErrorData, type EdgeFailure, EdgeHttpErrorCodec, ErrorCodec }
 export class EdgeCallFailedError extends Error {
   public static fromUnsuccessfulResponse(response: Response, body: EdgeFailure): EdgeCallFailedError {
     const error = new EdgeCallFailedError({
-      reason: body.reason,
-      errorData: body.errorData,
-      isRetryable: body.errorData == null && response.headers.has('Retry-After'),
+      message: body.message,
+      data: body.data,
+      isRetryable: body.data == null && response.headers.has('Retry-After'),
       retryAfterMs: getRetryAfterMillis(response),
-      cause: body.cause ? ErrorCodec.decode(body.cause) : undefined,
+      cause: body.error ? ErrorCodec.decode(body.error) : undefined,
     });
 
     return error;
@@ -28,7 +28,7 @@ export class EdgeCallFailedError extends Error {
 
   public static async fromHttpFailure(response: Response): Promise<EdgeCallFailedError> {
     return new EdgeCallFailedError({
-      reason: `HTTP code ${response.status}: ${response.statusText}.`,
+      message: `HTTP code ${response.status}: ${response.statusText}.`,
       isRetryable: isRetryableCode(response.status),
       retryAfterMs: getRetryAfterMillis(response),
       cause: await EdgeHttpErrorCodec.decode(response),
@@ -37,27 +37,26 @@ export class EdgeCallFailedError extends Error {
 
   public static fromProcessingFailureCause(cause: Error): EdgeCallFailedError {
     return new EdgeCallFailedError({
-      reason: 'Error processing request.',
+      message: 'Error processing request.',
       isRetryable: true,
       cause,
     });
   }
 
-  readonly reason: string;
-  readonly errorData?: EdgeErrorData;
+  readonly data?: EdgeErrorData;
   readonly isRetryable?: boolean;
   readonly retryAfterMs?: number;
 
   constructor(args: {
-    reason: string;
+    message: string;
     isRetryable?: boolean;
-    errorData?: EdgeErrorData;
+    data?: EdgeErrorData;
     retryAfterMs?: number;
     cause?: Error;
   }) {
-    super(args.reason, { cause: args.cause });
-    this.reason = args.reason;
-    this.errorData = args.errorData;
+    super(args.message, { cause: args.cause });
+    this.message = args.message;
+    this.data = args.data;
     this.retryAfterMs = args.retryAfterMs;
     this.isRetryable = Boolean(args.isRetryable);
   }
@@ -66,9 +65,9 @@ export class EdgeCallFailedError extends Error {
 export class EdgeAuthChallengeError extends EdgeCallFailedError {
   constructor(
     public readonly challenge: string,
-    errorData: EdgeErrorData,
+    data: EdgeErrorData,
   ) {
-    super({ reason: 'Auth challenge.', errorData, isRetryable: false });
+    super({ message: 'Auth challenge.', data, isRetryable: false });
   }
 }
 

package/src/edge/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './edge.ts';
+export * as EdgeFunctionEnv from './EdgeFunctionEnv.ts';
+export * from './errors.ts';
+export * from './registry.ts';

package/src/edge/registry.ts

@@ -0,0 +1,96 @@
+//
+// 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),
+  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>;
+
+/**
+ * Shape of the manifest-asset JSON the registry service fetches from each plugin's latest release.
+ * Extends {@link PluginMetaSchema} with an optional override for the module bundle filename
+ * (defaults to `plugin.mjs`).
+ */
+export const PluginManifestSchema = Schema.Struct({
+  ...PluginMetaSchema.fields,
+  moduleFile: Schema.optional(Schema.String),
+});
+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. */
+  repo: Schema.String.pipe(Schema.nonEmptyString()),
+  /** Plugin metadata from the repo's latest-release `manifest.json`. */
+  meta: PluginMetaSchema,
+  /**
+   * URL from which Composer can dynamic-import the plugin module. The registry service is
+   * responsible for returning a URL that is CORS-safe for browser `import()` (e.g. served or
+   * proxied by the service itself); clients pass this value directly to the URL loader.
+   */
+  moduleUrl: Schema.String,
+  /** Release tag the entry was resolved from (e.g. `v0.1.0`). */
+  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>;
+
+/**
+ * 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(
+      Schema.Struct({
+        repo: Schema.String,
+      }),
+    ),
+  },
+  Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+);
+export type RegistryManifest = Schema.Schema.Type<typeof RegistryManifestSchema>;

package/src/errors/base-errors.ts

@@ -2,43 +2,25 @@
 // Copyright 2021 DXOS.org
 //
 
-// TODO(dmaretskyi): Reconcile with @dxos/errors
-
 /**
  * NOTE: Messages should be sentences (Start with a capital letter and end with a period).
  * Errors can optionally include a JSON context object.
  */
-export class BaseError extends Error {
-  constructor(
-    readonly code: string,
-    message?: string,
-    readonly context?: Record<string, any>,
-  ) {
-    // TODO(dmaretskyi): Error.cause.
-    super(message ?? code);
-    this.name = code;
-    // NOTE: Restores prototype chain (https://stackoverflow.com/a/48342359).
-    Object.setPrototypeOf(this, new.target.prototype);
-  }
-}
-
-// TODO(dmaretskyi): Consider common error classes with error codes:
-// throw new SystemError(ERROR_CODE_OUT_OF_MEMORY, 'Out of memory', { a: 1, b: 2 });
+import { BaseError } from '@dxos/errors';
 
 /**
  * User facing API Errors.
  * E.g., something was misconfigured.
  */
-export class ApiError extends BaseError {}
+export class ApiError extends BaseError.extend('ApiError') {}
 
 /**
  * Internal system errors.
  * E.g., unexpected/unrecoverable runtime error.
  */
-export class SystemError extends BaseError {}
+export class SystemError extends BaseError.extend('SystemError') {}
 
 /**
  * Database errors.
  */
-// TODO(wittjosiah): Same as ApiError?
-export class DatabaseError extends BaseError {}
+export class DatabaseError extends BaseError.extend('DatabaseError') {}

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,12 +4,12 @@
 
 import { describe, expect, test } from 'vitest';
 
-import { ApiError } from './base-errors.js';
+import { ApiError } from './base-errors.ts';
 
 describe('Errors', () => {
   test('test', async () => {
     const runTest = async () => {
-      throw new ApiError('Test error');
+      throw new ApiError({ message: 'Test error' });
     };
 
     await expect(runTest()).rejects.toThrowError('Test error');