@dxos/assistant-toolkit 0.8.4-main.ae835ea → 0.8.4-main.bcb3aa67d6

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/assistant-toolkit",
-  "version": "0.8.4-main.ae835ea",
+  "version": "0.8.4-main.bcb3aa67d6",
   "description": "Assistant toolkit, definitions, and utilities.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
   "type": "module",
@@ -11,55 +15,63 @@
     ".": {
       "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"
+    },
+    "./testing": {
+      "source": "./src/testing/index.ts",
+      "types": "./dist/types/src/testing/index.d.ts",
+      "default": "./dist/lib/neutral/testing/index.mjs"
     }
   },
-  "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@effect/ai": "0.29.1",
-    "@effect/ai-anthropic": "0.19.2",
-    "@effect/experimental": "0.56.0",
-    "@effect/platform": "^0.92.1",
-    "dfx": "^0.126.0",
+    "@effect/ai": "0.33.2",
+    "@effect/ai-anthropic": "0.23.0",
+    "@effect/experimental": "0.58.0",
+    "@effect/platform": "0.94.4",
+    "dfx": "^0.127.0",
     "exa-js": "^1.5.12",
-    "@dxos/ai": "0.8.4-main.ae835ea",
-    "@dxos/app-framework": "0.8.4-main.ae835ea",
-    "@dxos/assistant": "0.8.4-main.ae835ea",
-    "@dxos/blueprints": "0.8.4-main.ae835ea",
-    "@dxos/context": "0.8.4-main.ae835ea",
-    "@dxos/conductor": "0.8.4-main.ae835ea",
-    "@dxos/echo-db": "0.8.4-main.ae835ea",
-    "@dxos/echo": "0.8.4-main.ae835ea",
-    "@dxos/echo-protocol": "0.8.4-main.ae835ea",
-    "@dxos/edge-client": "0.8.4-main.ae835ea",
-    "@dxos/functions": "0.8.4-main.ae835ea",
-    "@dxos/errors": "0.8.4-main.ae835ea",
-    "@dxos/invariant": "0.8.4-main.ae835ea",
-    "@dxos/keys": "0.8.4-main.ae835ea",
-    "@dxos/log": "0.8.4-main.ae835ea",
-    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.ae835ea",
-    "@dxos/util": "0.8.4-main.ae835ea",
-    "@dxos/effect": "0.8.4-main.ae835ea",
-    "@dxos/plugin-markdown": "0.8.4-main.ae835ea",
-    "@dxos/schema": "0.8.4-main.ae835ea"
+    "@dxos/ai": "0.8.4-main.bcb3aa67d6",
+    "@dxos/app-framework": "0.8.4-main.bcb3aa67d6",
+    "@dxos/assistant": "0.8.4-main.bcb3aa67d6",
+    "@dxos/blueprints": "0.8.4-main.bcb3aa67d6",
+    "@dxos/conductor": "0.8.4-main.bcb3aa67d6",
+    "@dxos/context": "0.8.4-main.bcb3aa67d6",
+    "@dxos/echo": "0.8.4-main.bcb3aa67d6",
+    "@dxos/echo-protocol": "0.8.4-main.bcb3aa67d6",
+    "@dxos/edge-client": "0.8.4-main.bcb3aa67d6",
+    "@dxos/echo-db": "0.8.4-main.bcb3aa67d6",
+    "@dxos/effect": "0.8.4-main.bcb3aa67d6",
+    "@dxos/functions": "0.8.4-main.bcb3aa67d6",
+    "@dxos/functions-runtime": "0.8.4-main.bcb3aa67d6",
+    "@dxos/invariant": "0.8.4-main.bcb3aa67d6",
+    "@dxos/errors": "0.8.4-main.bcb3aa67d6",
+    "@dxos/keys": "0.8.4-main.bcb3aa67d6",
+    "@dxos/log": "0.8.4-main.bcb3aa67d6",
+    "@dxos/operation": "0.8.4-main.bcb3aa67d6",
+    "@dxos/plugin-markdown": "0.8.4-main.bcb3aa67d6",
+    "@dxos/client-protocol": "0.8.4-main.bcb3aa67d6",
+    "@dxos/react-ui": "0.8.4-main.bcb3aa67d6",
+    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.bcb3aa67d6",
+    "@dxos/react-ui-mosaic": "0.8.4-main.bcb3aa67d6",
+    "@dxos/schema": "0.8.4-main.bcb3aa67d6",
+    "@dxos/types": "0.8.4-main.bcb3aa67d6",
+    "@dxos/util": "0.8.4-main.bcb3aa67d6"
   },
   "devDependencies": {
-    "effect": "3.18.3",
-    "react": "~19.2.0",
-    "react-dom": "~19.2.0"
+    "effect": "3.20.0",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "@dxos/ui-theme": "0.8.4-main.bcb3aa67d6"
   },
   "peerDependencies": {
-    "effect": "^3.13.3",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "effect": "3.20.0",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "@dxos/ui-theme": "0.8.4-main.bcb3aa67d6"
   },
   "publishConfig": {
     "access": "public"

package/src/blueprints/automation/blueprint.ts

@@ -0,0 +1,109 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint } from '@dxos/blueprints';
+import { Ref } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { Trigger } from '@dxos/functions';
+import { Operation } from '@dxos/operation';
+
+const BLUEPRINT_KEY = 'dxos.org/blueprint/automation';
+
+const instructions = trim`
+  Automation allows you to automatically initiate actions based on events.
+  Automations are configured by creating a trigger that references a function.
+  Whenever event that matches the trigger occurs, the function is invoked.
+
+  ## Configuration
+
+  Triggers are configured by the properties of the Trigger object.
+  - enabled: Must be true for trigger to run.
+  - spec: Events that the trigger matches.
+  - function: Ref to a ${Operation.PersistentOperation.typename} object that will be invoked. Query the functions present in the space first, and reference them in the trigger.
+  - input: The spec of the input data that will be passed to the function.
+
+  ## Input patterns
+
+  Input to the invoked function is defined by the input property of the Trigger object.
+  It's an object that supports constants or template strings.
+
+  Example:
+
+  {
+    item: '{{event.item}}',
+    instructions: 'Summarize and perform entity-extraction'
+    mailbox: { '/': 'dxn:echo:AAA:ZZZ' }
+  }
+
+  ## Trigger kinds
+
+  - Timer: Triggered by a cron schedule.
+  - Queue: Subscribes and processes items begginging to end.
+            Note: queues are the same as feeds. The queue DXN should be of form: dxn:queue:data:<space-id>:<queue-id>.
+  - Subscription: Subscribes and processes database items based on a query.
+
+  Avoid: email and webhook triggers.
+
+  ## Editing triggers
+
+  Triggers are represented as objects of type ${Trigger.Trigger.typename}.
+  You need access to the Database blueprint to manipulate triggers.
+  Read trigger schema before manipulating triggers.
+  Having a Trigger object in the database is enough to setup an automation. 
+
+  ## Examples
+
+  Timer:
+
+  {
+    "function": { "/": "dxn:echo:AAA:ZZZ" },
+    "enabled": true,
+    "spec": {
+      "kind": "timer",
+      "cron": "*/5 * * * *"
+    }
+  }
+
+  Queue:
+
+  {
+    "function": { "/": "dxn:echo:AAA:ZZZ" },
+    "enabled": true,
+    "spec": {
+      "kind": "queue",
+      "queue": "dxn:queue:data:XXX:YYY"
+    }
+  }
+
+  Subscription:
+
+  {
+    "function": { "/": "dxn:echo:AAA:ZZZ" },
+    "enabled": true,
+    "spec": {
+      "kind": "subscription",
+      "query": { "ast": { "type": "select", "filter": { "type": "object", "typename": "dxn:type:org.dxos.type.person" } } }
+    }
+  }
+`;
+
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Triggers',
+    description: 'Trigger management and automation.',
+    instructions: {
+      source: Ref.make(Text.make(instructions)),
+    },
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
+
+export default blueprint;

package/src/blueprints/automation/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { default as AutomationBlueprint } from './blueprint';

package/src/blueprints/blueprint-manager/blueprint.test.ts

@@ -0,0 +1,130 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { AiContextService, AiConversationService } from '@dxos/assistant';
+import { AssistantTestLayer } from '@dxos/assistant/testing';
+import { Blueprint } from '@dxos/blueprints';
+import { TestHelpers } from '@dxos/effect/testing';
+import { FunctionInvocationService } from '@dxos/functions';
+import { ObjectId } from '@dxos/keys';
+
+import { BlueprintManagerHandlers, QueryBlueprints, EnableBlueprints } from './functions';
+import DatabaseBlueprint from '../database/blueprint';
+import MarkdownBlueprint from '../markdown/blueprint';
+import ResearchBlueprint from '../research/blueprint';
+
+ObjectId.dangerouslyDisableRandomness();
+
+const TestLayer = AssistantTestLayer({
+  aiServicePreset: 'edge-remote',
+  operationHandlers: BlueprintManagerHandlers,
+  types: [Blueprint.Blueprint],
+  blueprints: [DatabaseBlueprint.make(), MarkdownBlueprint.make(), ResearchBlueprint.make()],
+  tracing: 'pretty',
+});
+
+const provideTestLayers = Effect.provide(AiConversationService.layerNewQueue().pipe(Layer.provideMerge(TestLayer)));
+
+describe('Blueprint Manager', () => {
+  it.effect(
+    'query-blueprints: returns all registered blueprints',
+    Effect.fnUntraced(
+      function* (_) {
+        const result = yield* FunctionInvocationService.invokeFunction(QueryBlueprints, {});
+        expect(result).toHaveLength(3);
+        const keys = result.map((blueprint: Blueprint.Blueprint) => blueprint.key);
+        expect(keys).toContain('org.dxos.blueprint.database');
+        expect(keys).toContain('org.dxos.blueprint.markdown');
+        expect(keys).toContain('org.dxos.blueprint.research');
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 30_000 },
+  );
+
+  it.effect(
+    'enable-blueprints: enables blueprints with agentCanEnable=true',
+    Effect.fnUntraced(
+      function* (_) {
+        const { enabled, rejected } = yield* FunctionInvocationService.invokeFunction(EnableBlueprints, {
+          keys: ['org.dxos.blueprint.database'],
+        });
+        expect(enabled).toHaveLength(1);
+        expect(enabled[0].key).toBe('org.dxos.blueprint.database');
+        expect(rejected).toHaveLength(0);
+
+        const { binder } = yield* AiContextService;
+        const bound = binder.getBlueprints();
+        expect(bound.some((bp: Blueprint.Blueprint) => bp.key === 'org.dxos.blueprint.database')).toBe(true);
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 30_000 },
+  );
+
+  it.effect(
+    'enable-blueprints: rejects blueprints without agentCanEnable',
+    Effect.fnUntraced(
+      function* (_) {
+        const { enabled, rejected } = yield* FunctionInvocationService.invokeFunction(EnableBlueprints, {
+          keys: ['org.dxos.blueprint.research'],
+        });
+        expect(enabled).toHaveLength(0);
+        expect(rejected).toHaveLength(1);
+        expect(rejected[0].key).toBe('org.dxos.blueprint.research');
+
+        const { binder } = yield* AiContextService;
+        const bound = binder.getBlueprints();
+        expect(bound.some((bp: Blueprint.Blueprint) => bp.key === 'org.dxos.blueprint.research')).toBe(false);
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 30_000 },
+  );
+
+  it.effect(
+    'enable-blueprints: mixed keys enables only allowed ones',
+    Effect.fnUntraced(
+      function* (_) {
+        const { enabled, rejected } = yield* FunctionInvocationService.invokeFunction(EnableBlueprints, {
+          keys: ['org.dxos.blueprint.database', 'org.dxos.blueprint.markdown', 'org.dxos.blueprint.research'],
+        });
+        expect(enabled).toHaveLength(2);
+        const enabledKeys = enabled.map((bp: Blueprint.Blueprint) => bp.key);
+        expect(enabledKeys).toContain('org.dxos.blueprint.database');
+        expect(enabledKeys).toContain('org.dxos.blueprint.markdown');
+        expect(rejected).toHaveLength(1);
+        expect(rejected[0].key).toBe('org.dxos.blueprint.research');
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 30_000 },
+  );
+
+  it.effect(
+    'enable-blueprints: unknown keys are rejected with reason',
+    Effect.fnUntraced(
+      function* (_) {
+        const { enabled, rejected } = yield* FunctionInvocationService.invokeFunction(EnableBlueprints, {
+          keys: ['org.dxos.blueprint.nonexistent'],
+        });
+        expect(enabled).toHaveLength(0);
+        expect(rejected).toHaveLength(1);
+        expect(rejected[0].key).toBe('org.dxos.blueprint.nonexistent');
+        expect(rejected[0].reason).toContain('not found');
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 30_000 },
+  );
+});

package/src/blueprints/blueprint-manager/blueprint.ts

@@ -0,0 +1,49 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint, Template } from '@dxos/blueprints';
+import { trim } from '@dxos/util';
+
+import { QueryBlueprints, EnableBlueprints } from './functions';
+
+const BLUEPRINT_KEY = 'org.dxos.blueprint.blueprint-manager';
+
+const make = () =>
+  Blueprint.make({
+    key: BLUEPRINT_KEY,
+    name: 'Blueprint Manager',
+    description: 'Query and enable blueprints in the current conversation.',
+    instructions: Template.make({
+      source: trim`
+        You can query available blueprints and enable them in the current conversation.
+        Use [query-blueprints] to refresh the list of available blueprints.
+        Use [enable-blueprints] to enable blueprints by their keys. Always call [query-blueprints] first.
+        Only blueprints with agentCanEnable=true can be enabled by the agent.
+
+        <available_blueprints>
+        {{#each blueprints}}
+        - {{key}} "{{name}}"{{#if description}} -- {{description}}{{/if}}{{#if agentCanEnable}} [agent-can-enable]{{/if}}
+        {{/each}}
+        </available_blueprints>
+
+        NOTE: You must enable the blueprint to use it, only then the tools from that blueprint will appear.
+      `,
+      inputs: [
+        {
+          name: 'blueprints',
+          kind: 'function',
+          function: QueryBlueprints.meta.key,
+        },
+      ],
+    }),
+    tools: Blueprint.toolDefinitions({ operations: [QueryBlueprints, EnableBlueprints] }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
+
+export default blueprint;

package/src/blueprints/blueprint-manager/functions/definitions.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { AiContextService } from '@dxos/assistant';
+import { Blueprint } from '@dxos/blueprints';
+import { Database } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+export const QueryBlueprints = Operation.make({
+  meta: {
+    key: 'org.dxos.function.blueprint-manager.query-blueprints',
+    name: 'Query blueprints',
+    description: 'Queries available blueprints.',
+  },
+  input: Schema.Struct({}),
+  output: Schema.Array(Blueprint.Blueprint),
+  services: [Blueprint.RegistryService],
+});
+
+export const EnableBlueprints = Operation.make({
+  meta: {
+    key: 'org.dxos.function.blueprint-manager.enable-blueprints',
+    name: 'Enable blueprints',
+    description:
+      'Enables blueprints in the current conversation by their keys. Only blueprints with agentCanEnable=true can be enabled. Always call [query-blueprints] first to discover available blueprint keys.',
+  },
+  input: Schema.Struct({
+    keys: Schema.Array(Schema.String).annotations({
+      description: 'The keys of the blueprints to enable.',
+      examples: [['org.dxos.blueprint.markdown', 'org.dxos.blueprint.database']],
+    }),
+  }),
+  output: Schema.Struct({
+    enabled: Schema.Array(Blueprint.Blueprint),
+    rejected: Schema.Array(
+      Schema.Struct({
+        key: Schema.String,
+        reason: Schema.String,
+      }),
+    ),
+  }),
+  services: [Blueprint.RegistryService, Database.Service, AiContextService],
+});

package/src/blueprints/blueprint-manager/functions/enable-blueprints.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { AiContextService } from '@dxos/assistant';
+import { Blueprint } from '@dxos/blueprints';
+import { Ref } from '@dxos/echo';
+import { Operation } from '@dxos/operation';
+
+import { EnableBlueprints } from './definitions';
+
+export default EnableBlueprints.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ keys }) {
+      const registry = yield* Blueprint.RegistryService;
+      const enabled: Blueprint.Blueprint[] = [];
+      const rejected: { key: string; reason: string }[] = [];
+
+      for (const key of keys) {
+        const blueprint = registry.getByKey(key);
+        if (!blueprint) {
+          rejected.push({ key, reason: 'Blueprint not found in registry.' });
+          continue;
+        }
+        if (!blueprint.agentCanEnable) {
+          rejected.push({ key, reason: 'Blueprint does not allow agent auto-enable (agentCanEnable is not set).' });
+          continue;
+        }
+        const dbBlueprint = yield* Blueprint.upsert(key).pipe(Effect.orDie);
+        enabled.push(dbBlueprint);
+      }
+
+      if (enabled.length > 0) {
+        yield* AiContextService.bindContext({
+          blueprints: enabled.map(Ref.make),
+        });
+      }
+
+      return { enabled, rejected };
+    }),
+  ),
+);

package/src/blueprints/blueprint-manager/functions/index.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export * from './definitions';
+
+export const BlueprintManagerHandlers = OperationHandlerSet.lazy(
+  () => import('./query-blueprints'),
+  () => import('./enable-blueprints'),
+);

package/src/blueprints/blueprint-manager/functions/query-blueprints.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Blueprint } from '@dxos/blueprints';
+import { Operation } from '@dxos/operation';
+
+import { QueryBlueprints } from './definitions';
+
+export default QueryBlueprints.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      const registry = yield* Blueprint.RegistryService;
+      return registry.query();
+    }),
+  ),
+);

package/src/blueprints/blueprint-manager/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { default as BlueprintManagerBlueprint } from './blueprint';
+export { QueryBlueprints, EnableBlueprints, BlueprintManagerHandlers } from './functions';