@dxos/compute 0.8.4-main.fd6878d → 0.9.0

package/package.json

@@ -1,76 +1,60 @@
 {
   "name": "@dxos/compute",
-  "version": "0.8.4-main.fd6878d",
-  "description": "Low-level compute API",
+  "version": "0.9.0",
+  "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",
-  "imports": {
-    "#hyperformula": {
-      "source": "hyperformula",
-      "types": "hyperformula",
-      "default": "./dist/vendor/hyperformula.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"
+    },
+    "./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.9.0",
-    "effect": "3.17.7",
-    "hyperformula": "^2.7.1",
-    "lodash.defaultsdeep": "^4.6.1",
-    "@dxos/async": "0.8.4-main.fd6878d",
-    "@dxos/client": "0.8.4-main.fd6878d",
-    "@dxos/debug": "0.8.4-main.fd6878d",
-    "@dxos/context": "0.8.4-main.fd6878d",
-    "@dxos/echo-db": "0.8.4-main.fd6878d",
-    "@dxos/echo-schema": "0.8.4-main.fd6878d",
-    "@dxos/functions": "0.8.4-main.fd6878d",
-    "@dxos/invariant": "0.8.4-main.fd6878d",
-    "@dxos/keys": "0.8.4-main.fd6878d",
-    "@dxos/live-object": "0.8.4-main.fd6878d",
-    "@dxos/log": "0.8.4-main.fd6878d",
-    "@dxos/schema": "0.8.4-main.fd6878d",
-    "@dxos/echo": "0.8.4-main.fd6878d",
-    "@dxos/protocols": "0.8.4-main.fd6878d",
-    "@dxos/util": "0.8.4-main.fd6878d"
+    "@effect-atom/atom": "^0.5.3",
+    "@effect/platform": "0.96.1",
+    "@dxos/ai": "0.9.0",
+    "@dxos/echo": "0.9.0",
+    "@dxos/errors": "0.9.0",
+    "@dxos/effect": "0.9.0",
+    "@dxos/invariant": "0.9.0",
+    "@dxos/keys": "0.9.0",
+    "@dxos/log": "0.9.0",
+    "@dxos/protocols": "0.9.0",
+    "@dxos/schema": "0.9.0",
+    "@dxos/vendor-kbn-handlebars": "0.9.0"
   },
   "devDependencies": {
-    "@tldraw/indices": "^2.0.0-alpha.14",
-    "@types/lodash.defaultsdeep": "^4.6.6",
-    "@dxos/echo-schema": "0.8.4-main.fd6878d",
-    "@dxos/echo-db": "0.8.4-main.fd6878d",
-    "@dxos/random": "0.8.4-main.fd6878d"
+    "effect": "3.21.3",
+    "vitest": "4.1.7",
+    "@dxos/echo-client": "0.9.0"
   },
   "peerDependencies": {
-    "effect": "^3.13.3"
+    "effect": "3.21.3"
   },
   "publishConfig": {
     "access": "public"

package/src/Blueprint.ts

@@ -0,0 +1,224 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { ToolId } from '@dxos/ai';
+import { DXN, Annotation, Database, Filter, Migration, Obj, Registry, Type, URI } from '@dxos/echo';
+import { BaseError } from '@dxos/errors';
+
+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(
+  Annotation.LabelAnnotation.set(['name']),
+  Annotation.IconAnnotation.set({ icon: 'ph--blueprint--regular', hue: 'sky' }),
+  Type.makeObject(DXN.make('org.dxos.type.blueprint', '0.2.0')),
+);
+
+/**
+ * TypeScript type for Blueprint.
+ */
+export type Blueprint = Type.InstanceType<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(DXN.getName(op.meta.key))), ...tools.map((tool) => ToolId.make(tool))];
+
+/**
+ * Factory for the blueprints.
+ */
+export type Definition = {
+  key: string;
+  make: () => Blueprint;
+};
+
+/**
+ * Returns the canonical URI used to reference this blueprint in the registry.
+ * Valid DXN keys produce `dxn:<key>`; other keys use the raw key as a URI.
+ * Use this URI with `Ref.fromURI` to bind a blueprint without cloning it to the DB.
+ *
+ * TODO(wittjosiah): Should use Obj.getURI instead once it supports options to prefer meta key over EID.
+ */
+export const registryURI = (key: string): URI.URI => (DXN.tryMake(`dxn:${key}`) ?? URI.make(key)) as URI.URI;
+
+/**
+ * Resolves a blueprint from the registry by its meta key.
+ * Does not check the local database for the blueprint.
+ */
+export const resolve = (key: string): Effect.Effect<Blueprint, NotFoundError, Registry.Service> =>
+  Effect.gen(function* () {
+    const results = yield* Registry.runQuery(Filter.and(Filter.type(Blueprint), Filter.key(key)));
+    const blueprint = results[0];
+    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, the local (possibly forked) copy is returned as-is.
+ * Otherwise, a fresh copy is cloned from the registry and added.
+ * @deprecated Since we're using a registry we no longer need to store blueprints in the database.
+ */
+// TODO(dmaretskyi): Remove.
+export const upsert = (key: string): Effect.Effect<Blueprint, NotFoundError, Registry.Service | Database.Service> =>
+  Effect.gen(function* () {
+    const local = yield* Database.query(Filter.and(Filter.type(Blueprint), Filter.key(key))).run;
+    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.makeObject(DXN.make('org.dxos.type.blueprint', '0.1.0')));
+
+export type Blueprint_v0_1_0 = Type.InstanceType<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/Header.test.ts

@@ -0,0 +1,132 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as HttpClient from '@effect/platform/HttpClient';
+import * as HttpClientRequest from '@effect/platform/HttpClientRequest';
+import * as HttpClientResponse from '@effect/platform/HttpClientResponse';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { describe, test } from 'vitest';
+
+import { EffectEx } from '@dxos/effect';
+
+import * as Credential from './Credential';
+import * as Header from './Header';
+
+describe('Header.byokLayer', () => {
+  test('attaches X-BYOK header when a credential is found for the provider host', async ({ expect }) => {
+    const sink: { lastHeader?: string } = {};
+
+    const program = Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient;
+      yield* client.execute(HttpClientRequest.get('http://internal/provider/anthropic/messages'));
+    });
+
+    const runnable = program.pipe(
+      Effect.provide(
+        Header.byokLayer('anthropic.com').pipe(
+          Layer.provide(captureHeaderClient(sink)),
+          Layer.provide(credentialsLayer([{ service: 'anthropic.com', apiKey: 'sk-ant-user' }])),
+        ),
+      ),
+    );
+    await EffectEx.runAndForwardErrors(runnable as Effect.Effect<void>);
+
+    expect(sink.lastHeader).toBe('sk-ant-user');
+  });
+
+  test('does not attach X-BYOK when no credential is found', async ({ expect }) => {
+    const sink: { lastHeader?: string } = {};
+
+    const program = Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient;
+      yield* client.execute(HttpClientRequest.get('http://internal/provider/anthropic/messages'));
+    });
+
+    const runnable = program.pipe(
+      Effect.provide(
+        Header.byokLayer('anthropic.com').pipe(
+          Layer.provide(captureHeaderClient(sink)),
+          Layer.provide(credentialsLayer([])),
+        ),
+      ),
+    );
+    await EffectEx.runAndForwardErrors(runnable as Effect.Effect<void>);
+
+    expect(sink.lastHeader).toBeUndefined();
+  });
+
+  test('does not attach X-BYOK when the matching credential has no apiKey', async ({ expect }) => {
+    const sink: { lastHeader?: string } = {};
+
+    const program = Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient;
+      yield* client.execute(HttpClientRequest.get('http://internal/provider/anthropic/messages'));
+    });
+
+    const runnable = program.pipe(
+      Effect.provide(
+        Header.byokLayer('anthropic.com').pipe(
+          Layer.provide(captureHeaderClient(sink)),
+          Layer.provide(credentialsLayer([{ service: 'anthropic.com' }])),
+        ),
+      ),
+    );
+    await EffectEx.runAndForwardErrors(runnable as Effect.Effect<void>);
+
+    expect(sink.lastHeader).toBeUndefined();
+  });
+
+  test('forwards the request unchanged when queryCredentials throws', async ({ expect }) => {
+    const sink: { lastHeader?: string; called?: boolean } = {};
+    const failingCredentials = Layer.succeed(Credential.CredentialsService, {
+      queryCredentials: async () => {
+        throw new Error('database unreachable');
+      },
+      getCredential: async () => {
+        throw new Error('database unreachable');
+      },
+    });
+
+    const program = Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient;
+      sink.called = true;
+      yield* client.execute(HttpClientRequest.get('http://internal/provider/anthropic/messages'));
+    });
+
+    const runnable = program.pipe(
+      Effect.provide(
+        Header.byokLayer('anthropic.com').pipe(
+          Layer.provide(captureHeaderClient(sink)),
+          Layer.provide(failingCredentials),
+        ),
+      ),
+    );
+    await EffectEx.runAndForwardErrors(runnable as Effect.Effect<void>);
+
+    expect(sink.called).toBe(true);
+    expect(sink.lastHeader).toBeUndefined();
+  });
+});
+
+const captureHeaderClient = (sink: { lastHeader?: string }) =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) => {
+      sink.lastHeader = request.headers['x-byok'];
+      return Effect.succeed(HttpClientResponse.fromWeb(request, new Response('ok')));
+    }),
+  );
+
+const credentialsLayer = (credentials: Credential.ServiceCredential[]) =>
+  Layer.succeed(Credential.CredentialsService, {
+    queryCredentials: async ({ service }) => credentials.filter((credential) => credential.service === service),
+    getCredential: async ({ service }) => {
+      const credential = credentials.find((entry) => entry.service === service);
+      if (!credential) {
+        throw new Error(`Credential not found for service: ${service}`);
+      }
+      return credential;
+    },
+  });

package/src/Header.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as HttpClient from '@effect/platform/HttpClient';
+import * as HttpClientRequest from '@effect/platform/HttpClientRequest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { BYOK_HEADER } from '@dxos/protocols';
+
+import * as Credential from './Credential';
+
+/**
+ * Wraps an `HttpClient` so outbound requests carry `X-BYOK: <apiKey>` whenever the active space
+ * has an `AccessToken` for `providerHost`. Lookup failures pass the request through unchanged.
+ */
+export const byokLayer = (
+  providerHost: string,
+): Layer.Layer<HttpClient.HttpClient, never, HttpClient.HttpClient | Credential.CredentialsService> =>
+  Layer.effect(
+    HttpClient.HttpClient,
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient;
+      const credentials = yield* Credential.CredentialsService;
+      return HttpClient.mapRequestEffect(client, (request) =>
+        Effect.gen(function* () {
+          const matches = yield* Effect.tryPromise(() => credentials.queryCredentials({ service: providerHost })).pipe(
+            Effect.orElseSucceed((): Credential.ServiceCredential[] => []),
+          );
+          const apiKey = matches.find((credential) => credential.apiKey)?.apiKey;
+          return apiKey ? HttpClientRequest.setHeader(request, BYOK_HEADER, apiKey) : request;
+        }),
+      );
+    }),
+  );

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, type URI } 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;
+
+  /**
+   * URI of the conversation feed the process is running in.
+   * Process affinity only.
+   */
+  readonly conversation?: URI.URI;
+
+  /**
+   * 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,
+  };
+};