@dxos/assistant-toolkit 0.8.4-main.e8ec1fe → 0.8.4-main.fcfe5033a5

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@dxos/assistant-toolkit",
-  "version": "0.8.4-main.e8ec1fe",
+  "version": "0.8.4-main.fcfe5033a5",
   "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,57 +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.21.1",
-    "@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.e8ec1fe",
-    "@dxos/assistant": "0.8.4-main.e8ec1fe",
-    "@dxos/blueprints": "0.8.4-main.e8ec1fe",
-    "@dxos/app-framework": "0.8.4-main.e8ec1fe",
-    "@dxos/context": "0.8.4-main.e8ec1fe",
-    "@dxos/echo-db": "0.8.4-main.e8ec1fe",
-    "@dxos/conductor": "0.8.4-main.e8ec1fe",
-    "@dxos/echo-protocol": "0.8.4-main.e8ec1fe",
-    "@dxos/edge-client": "0.8.4-main.e8ec1fe",
-    "@dxos/effect": "0.8.4-main.e8ec1fe",
-    "@dxos/echo": "0.8.4-main.e8ec1fe",
-    "@dxos/errors": "0.8.4-main.e8ec1fe",
-    "@dxos/functions": "0.8.4-main.e8ec1fe",
-    "@dxos/keys": "0.8.4-main.e8ec1fe",
-    "@dxos/functions-runtime": "0.8.4-main.e8ec1fe",
-    "@dxos/log": "0.8.4-main.e8ec1fe",
-    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.e8ec1fe",
-    "@dxos/schema": "0.8.4-main.e8ec1fe",
-    "@dxos/invariant": "0.8.4-main.e8ec1fe",
-    "@dxos/plugin-markdown": "0.8.4-main.e8ec1fe",
-    "@dxos/types": "0.8.4-main.e8ec1fe",
-    "@dxos/util": "0.8.4-main.e8ec1fe"
+    "@dxos/ai": "0.8.4-main.fcfe5033a5",
+    "@dxos/app-framework": "0.8.4-main.fcfe5033a5",
+    "@dxos/assistant": "0.8.4-main.fcfe5033a5",
+    "@dxos/blueprints": "0.8.4-main.fcfe5033a5",
+    "@dxos/client-protocol": "0.8.4-main.fcfe5033a5",
+    "@dxos/conductor": "0.8.4-main.fcfe5033a5",
+    "@dxos/context": "0.8.4-main.fcfe5033a5",
+    "@dxos/echo": "0.8.4-main.fcfe5033a5",
+    "@dxos/echo-db": "0.8.4-main.fcfe5033a5",
+    "@dxos/effect": "0.8.4-main.fcfe5033a5",
+    "@dxos/edge-client": "0.8.4-main.fcfe5033a5",
+    "@dxos/errors": "0.8.4-main.fcfe5033a5",
+    "@dxos/echo-protocol": "0.8.4-main.fcfe5033a5",
+    "@dxos/functions": "0.8.4-main.fcfe5033a5",
+    "@dxos/invariant": "0.8.4-main.fcfe5033a5",
+    "@dxos/functions-runtime": "0.8.4-main.fcfe5033a5",
+    "@dxos/log": "0.8.4-main.fcfe5033a5",
+    "@dxos/react-ui": "0.8.4-main.fcfe5033a5",
+    "@dxos/plugin-markdown": "0.8.4-main.fcfe5033a5",
+    "@dxos/react-ui-syntax-highlighter": "0.8.4-main.fcfe5033a5",
+    "@dxos/react-ui-mosaic": "0.8.4-main.fcfe5033a5",
+    "@dxos/schema": "0.8.4-main.fcfe5033a5",
+    "@dxos/util": "0.8.4-main.fcfe5033a5",
+    "@dxos/types": "0.8.4-main.fcfe5033a5",
+    "@dxos/keys": "0.8.4-main.fcfe5033a5",
+    "@dxos/operation": "0.8.4-main.fcfe5033a5"
   },
   "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.fcfe5033a5"
   },
   "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.fcfe5033a5"
   },
   "publishConfig": {
     "access": "public"

package/src/blueprints/automation/blueprint.ts

@@ -0,0 +1,108 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint } from '@dxos/blueprints';
+import { Ref } from '@dxos/echo';
+import { Trigger } from '@dxos/functions';
+import { Operation } from '@dxos/operation';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+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.conversations.json

@@ -0,0 +1 @@
+{"conversations":[{"parameters":{"model":"@anthropic/claude-opus-4-6","stream":true,"tools":[{"name":"query-blueprints","description":"Queries available blueprints.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}},{"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.","inputSchema":{"type":"object","required":["keys"],"properties":{"keys":{"type":"array","items":{"type":"string"},"description":"The keys of the blueprints to enable.","examples":[["org.dxos.blueprint.markdown","org.dxos.blueprint.database"]]}},"additionalProperties":false}},{"name":"refresh-blueprints","description":"Updates the blueprints saved to the database with the latest version from the registry. Sometimes blueprints in the database can become outdated. Use this function to pull in the latest versions.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}]},"prompt":{"content":[{"role":"system","content":"You can call blueprint manager tools. When asked to refresh or sync blueprints from the registry,\ncall the refresh blueprints tool once and then stop.\n\n## Blueprints Definitions\n\n<blueprint>\n  You can query available blueprints and enable them in the current conversation.\n  Use [query-blueprints] to refresh the list of available blueprints.\n  Use [refresh-blueprints] to update blueprint objects stored in the database from the built-in registry when they have drifted.\n  Use [enable-blueprints] to enable blueprints by their keys. Always call [query-blueprints] first.\n  Only blueprints with agentCanEnable=true can be enabled by the agent.\n  \n  <available_blueprints>\n  - org.dxos.blueprint.database \"Database\" -- Query and manipulate objects in the ECHO database. [agent-can-enable]\n  - org.dxos.blueprint.markdown \"Markdown\" -- Work with markdown documents. [agent-can-enable]\n  - org.dxos.blueprint.research \"Research\" -- Researches the web and creates structured data.\n  </available_blueprints>\n  \n  NOTE: You must enable the blueprint to use it, only then the tools from that blueprint will appear.\n</blueprint>","options":{}},{"role":"user","content":"Refresh blueprints from the registry so database copies match the built-in definitions.","options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01TBTMGS3U1dSyujvADu5sV7","modelId":"claude-opus-4-6","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"reasoning-start","id":"0","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"The user wants to refresh blueprints","metadata":{}},{"type":"reasoning-delta","id":"0","delta":" from the registry.","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{"anthropic":{"type":"thinking","signature":"EvIBClkIDBgCKkB80YOcko364VSaulfRzM8X76fyNXMnETkUUFoQcYpg3o7JCxnTb9ja4DC5rFEIzSicbmTYjXBq1JLzZZkSAcy9Mg9jbGF1ZGUtb3B1cy00LTY4ABIMfcn16jEiZ4g9FNh8GgwaXU83DG0p7kZNgmoiMHkhZF/0sINKrWl2dk944tPJZcL7iozZSBbyoSljWkuwPm2wyoCoyEnQq8Fh/oTVKipHb5R/moX69znTniGyL9IWD/+E1gsQlBRU0HASMJDBrG0q1xUUV//caZbNPboZrFdCXnjSb7DZJMZRwLeqrS4mIIJlPs/SkKUYAQ=="}}},{"type":"reasoning-end","id":"0","metadata":{}},{"type":"text-start","id":"1","metadata":{}},{"type":"text-delta","id":"1","delta":"I'll refresh the blueprints from the registry now to ensure the database copies are up to date.","metadata":{}},{"type":"text-end","id":"1","metadata":{}},{"type":"tool-params-start","id":"toolu_015Euwfup8HAM1CjYav9Tubf","name":"refresh-blueprints","providerExecuted":false,"metadata":{}},{"type":"tool-params-delta","id":"toolu_015Euwfup8HAM1CjYav9Tubf","delta":"","metadata":{}},{"type":"tool-params-end","id":"toolu_015Euwfup8HAM1CjYav9Tubf","metadata":{}},{"type":"finish","reason":"tool-calls","usage":{"inputTokens":1144,"outputTokens":80,"totalTokens":1224},"metadata":{"anthropic":{"usage":{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"input_tokens":1144,"output_tokens":8,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"@anthropic/claude-opus-4-6","stream":true,"tools":[{"name":"query-blueprints","description":"Queries available blueprints.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}},{"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.","inputSchema":{"type":"object","required":["keys"],"properties":{"keys":{"type":"array","items":{"type":"string"},"description":"The keys of the blueprints to enable.","examples":[["org.dxos.blueprint.markdown","org.dxos.blueprint.database"]]}},"additionalProperties":false}},{"name":"refresh-blueprints","description":"Updates the blueprints saved to the database with the latest version from the registry. Sometimes blueprints in the database can become outdated. Use this function to pull in the latest versions.","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}]},"prompt":{"content":[{"role":"system","content":"You can call blueprint manager tools. When asked to refresh or sync blueprints from the registry,\ncall the refresh blueprints tool once and then stop.\n\n## Blueprints Definitions\n\n<blueprint>\n  You can query available blueprints and enable them in the current conversation.\n  Use [query-blueprints] to refresh the list of available blueprints.\n  Use [refresh-blueprints] to update blueprint objects stored in the database from the built-in registry when they have drifted.\n  Use [enable-blueprints] to enable blueprints by their keys. Always call [query-blueprints] first.\n  Only blueprints with agentCanEnable=true can be enabled by the agent.\n  \n  <available_blueprints>\n  - org.dxos.blueprint.database \"Database\" -- Query and manipulate objects in the ECHO database. [agent-can-enable]\n  - org.dxos.blueprint.markdown \"Markdown\" -- Work with markdown documents. [agent-can-enable]\n  - org.dxos.blueprint.research \"Research\" -- Researches the web and creates structured data.\n  </available_blueprints>\n  \n  NOTE: You must enable the blueprint to use it, only then the tools from that blueprint will appear.\n</blueprint>","options":{}},{"role":"user","content":"Refresh blueprints from the registry so database copies match the built-in definitions.","options":{}},{"role":"assistant","content":[{"type":"reasoning","text":"The user wants to refresh blueprints from the registry.","options":{}},{"type":"text","text":"I'll refresh the blueprints from the registry now to ensure the database copies are up to date.","options":{}},{"type":"tool-call","id":"toolu_015Euwfup8HAM1CjYav9Tubf","name":"refresh-blueprints","params":{},"providerExecuted":false,"options":{}}],"options":{}},{"role":"tool","content":[{"type":"tool-result","id":"toolu_015Euwfup8HAM1CjYav9Tubf","name":"refresh-blueprints","isFailure":false,"result":{},"providerExecuted":false,"options":{}}],"options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01SR6yhAEXWUYe4x4rQj1C7s","modelId":"claude-opus-4-6","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"text-start","id":"0","metadata":{}},{"type":"text-delta","id":"0","delta":"The blueprints stored","metadata":{}},{"type":"text-delta","id":"0","delta":" in the database have been updated to match the latest built-in registry definitions. Everything should now be in sync.","metadata":{}},{"type":"text-end","id":"0","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":1187,"outputTokens":31,"totalTokens":1218},"metadata":{"anthropic":{"usage":{"cache_creation":{"ephemeral_1h_input_tokens":0,"ephemeral_5m_input_tokens":0},"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"input_tokens":1187,"output_tokens":5,"server_tool_use":null,"service_tier":"standard"}}}}]}]}

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

@@ -0,0 +1,199 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { MemoizedAiService } from '@dxos/ai/testing';
+import { AiContextService, AiSessionService } from '@dxos/assistant';
+import { AssistantTestLayer } from '@dxos/assistant/testing';
+import { Blueprint } from '@dxos/blueprints';
+import { Database, DXN, Obj, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { ObjectId } from '@dxos/keys';
+import { Operation } from '@dxos/operation';
+import { trim } from '@dxos/util';
+
+import DatabaseBlueprint from '../database/blueprint';
+import MarkdownBlueprint from '../markdown/blueprint';
+import ResearchBlueprint from '../research/blueprint';
+import BlueprintManagerDefinition from './blueprint';
+import { BlueprintManagerHandlers, EnableBlueprints, QueryBlueprints } from './functions';
+
+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(AiSessionService.layerNewFeed().pipe(Layer.provideMerge(TestLayer)));
+
+/**
+ * Gets the conversation DXN for passing to Operation.invoke options.
+ */
+const getConversationDxn = Effect.gen(function* () {
+  const session = yield* AiSessionService;
+  return Obj.getDXN(session.feed).toString() as DXN.String;
+});
+
+describe('Blueprint Manager', () => {
+  it.effect(
+    'query-blueprints: returns all registered blueprints',
+    Effect.fnUntraced(
+      function* (_) {
+        const conversation = yield* getConversationDxn;
+        const result = yield* Operation.invoke(QueryBlueprints, {}, { conversation });
+        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 conversation = yield* getConversationDxn;
+        const { enabled, rejected } = yield* Operation.invoke(
+          EnableBlueprints,
+          { keys: ['org.dxos.blueprint.database'] },
+          { conversation },
+        );
+        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 conversation = yield* getConversationDxn;
+        const { enabled, rejected } = yield* Operation.invoke(
+          EnableBlueprints,
+          { keys: ['org.dxos.blueprint.research'] },
+          { conversation },
+        );
+        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 conversation = yield* getConversationDxn;
+        const { enabled, rejected } = yield* Operation.invoke(
+          EnableBlueprints,
+          { keys: ['org.dxos.blueprint.database', 'org.dxos.blueprint.markdown', 'org.dxos.blueprint.research'] },
+          { conversation },
+        );
+        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 conversation = yield* getConversationDxn;
+        const { enabled, rejected } = yield* Operation.invoke(
+          EnableBlueprints,
+          { keys: ['org.dxos.blueprint.nonexistent'] },
+          { conversation },
+        );
+        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 },
+  );
+
+  it.scoped(
+    'refresh-blueprints: agent syncs a mutated database blueprint from the registry',
+    Effect.fnUntraced(
+      function* (_) {
+        const registry = yield* Blueprint.RegistryService;
+        const canonical = registry.getByKey('org.dxos.blueprint.database');
+        expect(canonical).toBeDefined();
+
+        const stored = yield* Blueprint.upsert('org.dxos.blueprint.database');
+        const originalName = stored.name;
+        Obj.change(stored, (stored) => {
+          stored.name = '___TEST_MUTATED_BLUEPRINT_NAME___';
+        });
+        yield* Database.flush();
+        expect(stored.name).toBe('___TEST_MUTATED_BLUEPRINT_NAME___');
+
+        const session = yield* AiSessionService;
+        yield* Effect.promise(() => session.context.open());
+        yield* Effect.promise(() =>
+          session.context.bind({
+            blueprints: [Ref.make(BlueprintManagerDefinition.make())],
+          }),
+        );
+
+        yield* session
+          .createRequest({
+            system: trim`
+            You can call blueprint manager tools. When asked to refresh or sync blueprints from the registry,
+            call the refresh blueprints tool once and then stop.
+          `,
+            prompt: trim`
+            Refresh blueprints from the registry so database copies match the built-in definitions.
+          `,
+          })
+          .pipe(Effect.provide(session.makeToolExecutionServices()));
+
+        expect(stored.name).toBe(originalName);
+      },
+      provideTestLayers,
+      TestHelpers.provideTestContext,
+    ),
+    MemoizedAiService.isGenerationEnabled() ? 240_000 : 60_000,
+  );
+});

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

@@ -0,0 +1,50 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { Blueprint, Template } from '@dxos/blueprints';
+import { trim } from '@dxos/util';
+
+import { EnableBlueprints, QueryBlueprints, UpdateBlueprints } 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 [refresh-blueprints] to update blueprint objects stored in the database from the built-in registry when they have drifted.
+        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, UpdateBlueprints] }),
+  });
+
+const blueprint: AppCapabilities.BlueprintDefinition = {
+  key: BLUEPRINT_KEY,
+  make,
+};
+
+export default blueprint;

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

@@ -0,0 +1,58 @@
+//
+// 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],
+});
+
+export const UpdateBlueprints = Operation.make({
+  meta: {
+    key: 'org.dxos.function.blueprint-manager.refresh-blueprints',
+    name: 'Refresh blueprints',
+    description:
+      'Updates the blueprints saved to the database with the latest version from the registry. Sometimes blueprints in the database can become outdated. Use this function to pull in the latest versions.',
+  },
+  input: Schema.Struct({}),
+  output: Schema.Void,
+  services: [Blueprint.RegistryService, Database.Service],
+});

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,13 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/operation';
+
+export * from './definitions';
+
+export const BlueprintManagerHandlers = OperationHandlerSet.lazy(
+  () => import('./query-blueprints'),
+  () => import('./enable-blueprints'),
+  () => import('./update-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/functions/update-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 { UpdateBlueprints } from './definitions';
+
+export default UpdateBlueprints.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      const registry = yield* Blueprint.RegistryService;
+      yield* registry.updateBlueprints();
+    }),
+  ),
+);