@dxos/compute 0.8.4-main.e8ec1fe → 0.8.4-main.f466a3d56e

package/package.json

@@ -1,70 +1,58 @@
 {
   "name": "@dxos/compute",
-  "version": "0.8.4-main.e8ec1fe",
-  "description": "Low-level compute API",
+  "version": "0.8.4-main.f466a3d56e",
+  "description": "Umbrella package for AI-aware DXOS compute primitives.",
   "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,
+  "sideEffects": false,
   "type": "module",
   "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"
+    },
+    "./StorageService": {
+      "source": "./src/StorageService.ts",
+      "types": "./dist/types/src/StorageService.d.ts",
+      "default": "./dist/lib/neutral/StorageService.mjs"
     },
     "./testing": {
       "source": "./src/testing/index.ts",
       "types": "./dist/types/src/testing/index.d.ts",
-      "browser": "./dist/lib/browser/testing/index.mjs",
-      "node": "./dist/lib/node-esm/testing/index.mjs"
+      "default": "./dist/lib/neutral/testing/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "testing": [
-        "dist/types/src/testing/index.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@preact/signals-core": "^1.12.1",
-    "effect": "3.18.3",
-    "lodash.defaultsdeep": "^4.6.1",
-    "@dxos/ai": "0.8.4-main.e8ec1fe",
-    "@dxos/async": "0.8.4-main.e8ec1fe",
-    "@dxos/debug": "0.8.4-main.e8ec1fe",
-    "@dxos/echo": "0.8.4-main.e8ec1fe",
-    "@dxos/functions": "0.8.4-main.e8ec1fe",
-    "@dxos/client": "0.8.4-main.e8ec1fe",
-    "@dxos/functions-runtime": "0.8.4-main.e8ec1fe",
-    "@dxos/invariant": "0.8.4-main.e8ec1fe",
-    "@dxos/keys": "0.8.4-main.e8ec1fe",
-    "@dxos/log": "0.8.4-main.e8ec1fe",
-    "@dxos/live-object": "0.8.4-main.e8ec1fe",
-    "@dxos/plugin-automation": "0.8.4-main.e8ec1fe",
-    "@dxos/context": "0.8.4-main.e8ec1fe",
-    "@dxos/protocols": "0.8.4-main.e8ec1fe",
-    "@dxos/schema": "0.8.4-main.e8ec1fe",
-    "@dxos/vendor-hyperformula": "0.8.4-main.e8ec1fe",
-    "@dxos/util": "0.8.4-main.e8ec1fe"
+    "@effect-atom/atom": "^0.5.1",
+    "@dxos/ai": "0.8.4-main.f466a3d56e",
+    "@dxos/errors": "0.8.4-main.f466a3d56e",
+    "@dxos/effect": "0.8.4-main.f466a3d56e",
+    "@dxos/invariant": "0.8.4-main.f466a3d56e",
+    "@dxos/echo": "0.8.4-main.f466a3d56e",
+    "@dxos/keys": "0.8.4-main.f466a3d56e",
+    "@dxos/log": "0.8.4-main.f466a3d56e",
+    "@dxos/protocols": "0.8.4-main.f466a3d56e",
+    "@dxos/vendor-kbn-handlebars": "0.8.4-main.f466a3d56e",
+    "@dxos/schema": "0.8.4-main.f466a3d56e"
   },
   "devDependencies": {
-    "@tldraw/indices": "^2.0.0-alpha.14",
-    "@types/lodash.defaultsdeep": "^4.6.6",
-    "@dxos/echo": "0.8.4-main.e8ec1fe",
-    "@dxos/echo-db": "0.8.4-main.e8ec1fe",
-    "@dxos/random": "0.8.4-main.e8ec1fe"
+    "effect": "3.20.0",
+    "vitest": "4.1.6"
   },
   "peerDependencies": {
-    "effect": "^3.13.3"
+    "effect": "3.20.0"
   },
   "publishConfig": {
     "access": "public"

package/src/Blueprint.ts

@@ -0,0 +1,303 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+
+import { ToolId } from '@dxos/ai';
+import { Annotation, Database, Filter, Migration, Obj, Type } from '@dxos/echo';
+import { BaseError } from '@dxos/errors';
+import { log } from '@dxos/log';
+
+import * as McpServer from './McpServer';
+import * as Operation from './Operation';
+import * as Template from './Template';
+
+/**
+ * Blueprint schema defines the structure for AI assistant blueprints.
+ * Blueprints contain instructions, tools, and artifacts that guide the AI's behavior.
+ * Blueprints may use tools to create and read artifacts, which are managed by the assistant.
+ *
+ * The registry `key` and `version` are stored in the object meta — access them via
+ * `Obj.getMeta(blueprint).key` and `Obj.getMeta(blueprint).version`.
+ */
+// TODO(burdon): Rename Skill?
+export const Blueprint = Schema.Struct({
+  /**
+   * Human-readable name of the blueprint.
+   */
+  name: Schema.String.annotations({
+    description: 'Human-readable name of the blueprint',
+  }),
+
+  /**
+   * Description of the blueprint's purpose and functionality.
+   */
+  description: Schema.optional(Schema.String).annotations({
+    description: "Description of the blueprint's purpose and functionality",
+  }),
+
+  /**
+   * Instructions that guide the AI assistant's behavior and responses.
+   * These are system prompts or guidelines that the AI should follow.
+   */
+  instructions: Template.Template.annotations({
+    description: "Instructions that guide the AI assistant's behavior and responses",
+  }),
+
+  /**
+   * Array of tools that the AI assistant can use when this blueprint is active.
+   */
+  tools: Schema.Array(ToolId).annotations({
+    description: 'Array of tools that the AI assistant can use when this blueprint is active',
+  }),
+
+  /**
+   * Whether an agent is allowed to auto-enable this blueprint in a conversation.
+   */
+  agentCanEnable: Schema.optional(Schema.Boolean).annotations({
+    description: 'Whether an agent is allowed to auto-enable this blueprint in a conversation.',
+  }),
+
+  /**
+   * Array of MCP servers that the AI assistant can use when this blueprint is active.
+   */
+  mcpServers: Schema.optional(Schema.Array(McpServer.McpServer)),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.blueprint',
+    version: '0.2.0',
+  }),
+  Annotation.LabelAnnotation.set(['name']),
+  Annotation.IconAnnotation.set({
+    icon: 'ph--blueprint--regular',
+    hue: 'sky',
+  }),
+);
+
+/**
+ * TypeScript type for Blueprint.
+ */
+export interface Blueprint extends Schema.Schema.Type<typeof Blueprint> {}
+
+type MakeProps = { key: string; version?: string; name: string } & Partial<Blueprint>;
+
+/**
+ * Create a new Blueprint.
+ * The `key` (and optional `version`) are stored in the object meta.
+ */
+export const make = ({ key, version, tools = [], instructions = Template.make(), ...props }: MakeProps) =>
+  Obj.make(Blueprint, {
+    [Obj.Meta]: { key, version },
+    tools,
+    instructions,
+    ...props,
+  });
+
+/**
+ * Get the registry key for a blueprint.
+ */
+export const getKey = (blueprint: Blueprint): string => {
+  const key = Obj.getMeta(blueprint).key;
+  if (key === undefined) {
+    throw new Error('Blueprint is missing the meta key.');
+  }
+  return key;
+};
+
+/**
+ * Get the registry version for a blueprint, if any.
+ */
+export const getVersion = (blueprint: Blueprint): string | undefined => Obj.getMeta(blueprint).version;
+
+/**
+ * Util to create tool definitions for a blueprint.
+ */
+export const toolDefinitions = ({
+  tools = [],
+  operations = [],
+}: {
+  tools?: string[];
+  operations?: Operation.Definition.Any[];
+}) => [...operations.map((op) => ToolId.make(op.meta.key)), ...tools.map((tool) => ToolId.make(tool))];
+
+/**
+ * Factory for the blueprints.
+ */
+export type Definition = {
+  key: string;
+  make: () => Blueprint;
+};
+
+//
+// Registry
+//
+
+/**
+ * Blueprint registry.
+ */
+export class Registry {
+  private readonly _blueprints: Blueprint[] = [];
+
+  constructor(blueprints: Blueprint[]) {
+    const seen = new Set<string>();
+    blueprints.forEach((blueprint) => {
+      const key = getKey(blueprint);
+      if (seen.has(key)) {
+        log.warn('duplicate blueprint', { key });
+      } else {
+        seen.add(key);
+        this._blueprints.push(blueprint);
+      }
+    });
+
+    this._blueprints.sort(({ name: a }, { name: b }) => a.localeCompare(b));
+  }
+
+  get blueprints(): Blueprint[] {
+    return this._blueprints;
+  }
+
+  getByKey(key: string): Blueprint | undefined {
+    return this._blueprints.find((blueprint) => Obj.getMeta(blueprint).key === key);
+  }
+
+  query(): Blueprint[] {
+    return this._blueprints;
+  }
+
+  updateBlueprints(): Effect.Effect<void, never, Database.Service> {
+    return Effect.gen(this, function* () {
+      const blueprints = yield* Database.runQuery(Filter.type(Blueprint));
+      for (const blueprint of blueprints) {
+        const blueprintKey = Obj.getMeta(blueprint).key;
+        if (!blueprintKey) {
+          continue;
+        }
+        const registryBlueprint = this.getByKey(blueprintKey);
+        if (!registryBlueprint) {
+          continue;
+        }
+        const source = Obj.clone(registryBlueprint, { deep: true });
+        Obj.update(blueprint, (blueprint) => {
+          void Obj.updateFrom(blueprint, source);
+        });
+      }
+    }).pipe(Effect.orDie);
+  }
+}
+
+export class RegistryService extends Context.Tag('@dxos/blueprints/RegistryService')<RegistryService, Registry>() {
+  static notAvailable = Layer.succeed(RegistryService, {
+    get blueprints(): Blueprint[] {
+      throw new Error('Blueprint registry not available');
+    },
+    getByKey(_key: string): Blueprint | undefined {
+      throw new Error('Blueprint registry not available');
+    },
+    query(): Blueprint[] {
+      throw new Error('Blueprint registry not available');
+    },
+    updateBlueprints() {
+      throw new Error('Blueprint registry not available');
+    },
+  } as unknown as Registry);
+}
+
+/**
+ * Resolves a blueprint from the registry.
+ * Does not check the local database for the blueprint.
+ */
+export const resolve = (key: string): Effect.Effect<Blueprint, NotFoundError, RegistryService> =>
+  Effect.gen(function* () {
+    const registry = yield* RegistryService;
+    const blueprint = registry.getByKey(key);
+    if (!blueprint) {
+      return yield* Effect.fail(new NotFoundError({ context: { key } }));
+    }
+    return blueprint;
+  });
+
+/**
+ * Upserts a blueprint into the database.
+ * If the blueprint already exists in the database, local blueprint is returned.
+ * Otherwise, it will be added.
+ */
+export const upsert = (key: string): Effect.Effect<Blueprint, NotFoundError, RegistryService | Database.Service> =>
+  Effect.gen(function* () {
+    const local = yield* Database.runQuery(Filter.and(Filter.type(Blueprint), Filter.key(key)));
+    if (local.length > 0) {
+      return local[0];
+    }
+    return yield* Database.add(Obj.clone(yield* resolve(key), { deep: true }));
+  });
+
+export class NotFoundError extends BaseError.extend('BlueprintNotFound', 'Blueprint not found') {}
+
+//
+// Legacy schemas and migrations.
+//
+
+/**
+ * Blueprint schema v0.1.0 — `key` is stored as a data property.
+ * @deprecated Use {@link Blueprint} (v0.2.0) instead; the `key` and `version` now live in the object meta.
+ */
+export const Blueprint_v0_1_0 = Schema.Struct({
+  /**
+   * Global registry ID.
+   * NOTE: The `key` property refers to the original registry entry.
+   */
+  key: Schema.String.annotations({
+    description: 'Unique registration key for the blueprint',
+  }),
+
+  name: Schema.String.annotations({
+    description: 'Human-readable name of the blueprint',
+  }),
+
+  description: Schema.optional(Schema.String),
+
+  instructions: Template.Template,
+
+  tools: Schema.Array(ToolId),
+
+  agentCanEnable: Schema.optional(Schema.Boolean),
+
+  mcpServers: Schema.optional(Schema.Array(McpServer.McpServer)),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.blueprint',
+    version: '0.1.0',
+  }),
+);
+
+export interface Blueprint_v0_1_0 extends Schema.Schema.Type<typeof Blueprint_v0_1_0> {}
+
+/**
+ * Migration from {@link Blueprint_v0_1_0} (v0.1.0) to {@link Blueprint} (v0.2.0).
+ * Moves `key` from the data section into the object meta.
+ */
+const _migration = Migration.define({
+  from: Blueprint_v0_1_0,
+  to: Blueprint,
+  transform: async (from) => ({
+    [Obj.Meta]: { key: from.key, version: '0.1.0' },
+    name: from.name,
+    description: from.description,
+    instructions: from.instructions,
+    tools: from.tools,
+    agentCanEnable: from.agentCanEnable,
+    mcpServers: from.mcpServers,
+  }),
+});
+
+/**
+ * Schema migrations exported by this module.
+ * Exported as an array for extensibility — append future versions here.
+ */
+export const migrations = [_migration];

package/src/Credential.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Redacted from 'effect/Redacted';
+
+export type CredentialQuery = {
+  service?: string;
+};
+
+// TODO(dmaretskyi): Unify with other apis.
+// packages/sdk/schema/src/common/access-token.ts
+export type ServiceCredential = {
+  service: string;
+
+  // TODO(dmaretskyi): Build out.
+  apiKey?: string;
+};
+
+export class CredentialsService extends Context.Tag('@dxos/functions/CredentialsService')<
+  CredentialsService,
+  {
+    /**
+     * Query all.
+     */
+    queryCredentials: (query: CredentialQuery) => Promise<ServiceCredential[]>;
+
+    /**
+     * Get a single credential.
+     * @throws {Error} If no credential is found.
+     */
+    getCredential: (query: CredentialQuery) => Promise<ServiceCredential>;
+  }
+>() {
+  static getCredential = (query: CredentialQuery): Effect.Effect<ServiceCredential, never, CredentialsService> =>
+    Effect.gen(function* () {
+      const credentials = yield* CredentialsService;
+      return yield* Effect.promise(() => credentials.getCredential(query));
+    });
+
+  static getApiKey = (query: CredentialQuery): Effect.Effect<Redacted.Redacted<string>, never, CredentialsService> =>
+    Effect.gen(function* () {
+      const credential = yield* CredentialsService.getCredential(query);
+      if (!credential.apiKey) {
+        throw new Error(`API key not found for service: ${query.service}`);
+      }
+      return Redacted.make(credential.apiKey);
+    });
+}

package/src/LayerSpec.ts

@@ -0,0 +1,91 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Layer from 'effect/Layer';
+import * as Types from 'effect/Types';
+
+import { SpaceId, DXN } from '@dxos/keys';
+
+import type * as Process from './Process';
+
+// @import-as-namespace
+
+export const TypeId = '~@dxos/functions/LayerSpec' as const;
+export type TypeId = typeof TypeId;
+
+/**
+ * Opaque layer with introspectable tags.
+ */
+export interface LayerSpec {
+  readonly [TypeId]: TypeId;
+
+  readonly affinity: Affinity;
+  readonly requires: readonly Context.Tag<any, any>[];
+  readonly provides: readonly Context.Tag<any, any>[];
+
+  // opaque service creation function, layer provides the specified services and requires the specified requirements.
+  readonly make: (context: LayerContext) => Layer.Layer<unknown, never, unknown>;
+}
+
+/**
+ * Affinity defines the lifetime and scope of a service.
+ *
+ * - `application` - single service instance is available throughout the entire application.
+ * - `space` - service is instantiated per space.
+ * - `process` - separate service instance is created and destroyed for each process.
+ */
+export type Affinity = 'application' | 'space' | 'process';
+
+/**
+ * Provides context for service resolution.
+ */
+// TODO(dmaretskyi): Consider making this type dependant on the specified service affinity.
+export interface LayerContext {
+  /**
+   * Under which space the process is running.
+   * Space affinity and up only.
+   */
+  readonly space?: SpaceId;
+
+  /**
+   * DXN of the conversation feed the process is running in.
+   * Process affinity only.
+   */
+  readonly conversation?: DXN.String;
+
+  /**
+   * Under which process the process is running.
+   * Process affinity only.
+   */
+  readonly process?: Process.ID;
+}
+
+interface MakeOpts {
+  readonly affinity: Affinity;
+  readonly requires: readonly Context.Tag<any, any>[];
+  readonly provides: readonly Context.Tag<any, any>[];
+}
+
+/**
+ * Make a service.
+ */
+export const make = <const Opts extends Types.NoExcessProperties<MakeOpts, Opts>>(
+  opts: Opts,
+  make: (
+    context: LayerContext,
+  ) => Layer.Layer<
+    Context.Tag.Identifier<Opts['provides'][number]>,
+    never,
+    Context.Tag.Identifier<Opts['requires'][number]>
+  >,
+): LayerSpec => {
+  return {
+    [TypeId]: TypeId,
+    affinity: opts.affinity,
+    requires: opts.requires,
+    provides: opts.provides,
+    make: make as any,
+  };
+};

package/src/McpServer.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+/**
+ * MCP server connection spec — the minimal fields needed to dial an MCP server.
+ *
+ * Used as a value type embedded in blueprints and passed to runtime session connect logic.
+ * The user-facing ECHO object (`@dxos/assistant-toolkit` `McpServer`) composes this struct
+ * and adds instance-level fields (`name`, `enabled`) and ECHO annotations.
+ */
+export const McpServer = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional).annotations({
+    description: 'Human-readable name of the MCP server',
+  }),
+
+  url: Schema.String.annotations({
+    description: 'URL of the MCP server',
+  }),
+
+  /**
+   * Transport protocol. Prefer `'http'` (Streamable HTTP) for new servers; `'sse'` is
+   * kept for compatibility with servers that haven't migrated and is deprecated per
+   * the MCP SDK. Clients support both during the migration period.
+   */
+  protocol: Schema.Union(Schema.Literal('http'), Schema.Literal('sse')).annotations({
+    description: 'Transport protocol of the MCP server (prefer "http"; "sse" deprecated)',
+  }),
+
+  /**
+   * Optional API key sent with requests.
+   * Persisted in plaintext when stored on a space-replicated ECHO object — see the
+   * `@dxos/assistant-toolkit` `McpServer` type for security implications.
+   */
+  apiKey: Schema.optional(Schema.String).annotations({
+    description: 'Optional API key sent with requests',
+  }),
+});
+
+export interface McpServer extends Schema.Schema.Type<typeof McpServer> {}