dxos-blueprints
Guide for creating and integrating Blueprints in DXOS. Use when adding blueprints to plugins, wiring operations as tools, structuring blueprint definitions, or testing with AssistantTestLayer.
SKILL.mddataset/repos/dxos§dxos/.cursor/skills/blueprints/SKILL.md
GitHubDXOS Blueprints
Blueprints define AI toolkits for a domain (e.g. markdown, kanban). They combine operation definitions (for tool schemas) with operation handlers (for runtime execution). See the operations skill (.cursor/skills/operations/SKILL.md) for defining operations.
Blueprint definition
A blueprint has three parts:
| Field | Type | Purpose |
|---|---|---|
key |
string |
Globally unique key (reverse-domain style). |
operations |
OperationHandlerSet.OperationHandlerSet |
Handler set for runtime invocation. |
make |
() => Blueprint.Blueprint |
Factory that creates the Blueprint instance with tools. |
Example (see packages/plugins/plugin-markdown/src/blueprints/markdown-blueprint.ts):
import { type AppCapabilities } from '@dxos/app-toolkit';
import { Blueprint, Template } from '@dxos/blueprints';
import { trim } from '@dxos/util';
import { MarkdownHandlers, Create, Open, Update } from './functions';
const BLUEPRINT_KEY = 'org.dxos.blueprint.markdown';
const make = () =>
Blueprint.make({
key: BLUEPRINT_KEY,
name: 'Markdown',
tools: Blueprint.toolDefinitions({ operations: [Create, Open, Update] }),
instructions: Template.make({
source: trim`
You can create, read and update markdown documents.
When asked to edit or update documents return updates as a set of compact diff string pairs.
`,
}),
});
const blueprint: AppCapabilities.BlueprintDefinition = {
key: BLUEPRINT_KEY,
operations: MarkdownHandlers,
make,
};
export default blueprint;
- Definitions (
Create,Open,Update) go toBlueprint.toolDefinitions({ operations })— they provide schemas for the AI. - Handlers (
MarkdownHandlers) go to the blueprint'soperationsfield — they are invoked at runtime.
File structure
Blueprints live inside plugins. Structure:
plugin-my-domain/
├── src/
│ ├── blueprints/
│ │ ├── index.ts # Re-exports blueprint
│ │ ├── my-blueprint.ts # Blueprint definition (key, operations, make)
│ │ └── functions/ # Operations (definitions + handlers)
│ │ ├── definitions.ts
│ │ ├── create.ts
│ │ ├── open.ts
│ │ ├── update.ts
│ │ └── index.ts
│ └── capabilities/
│ └── blueprint-definition/
│ ├── index.ts # Lazy export
│ └── blueprint-definition.ts # Contributes to AppCapabilities.BlueprintDefinition
Where blueprints are registered (Composer)
- Capability module — contributes the blueprint to the app:
// capabilities/blueprint-definition/blueprint-definition.ts
import * as Effect from 'effect/Effect';
import { Capability } from '@dxos/app-framework';
import { AppCapabilities } from '@dxos/app-toolkit';
import { MarkdownBlueprint } from '../../blueprints';
const blueprintDefinition = Capability.makeModule<
[],
Capability.Capability<typeof AppCapabilities.BlueprintDefinition>[]
>(() => Effect.succeed([Capability.contributes(AppCapabilities.BlueprintDefinition, MarkdownBlueprint)]));
export default blueprintDefinition;
- Plugin — registers the capability module:
// MarkdownPlugin.tsx
import { BlueprintDefinition } from './capabilities';
export const MarkdownPlugin = Plugin.define(meta).pipe(
AppPlugin.addBlueprintDefinitionModule({ activate: BlueprintDefinition }),
// ...other modules
Plugin.make,
);
- Composer — plugin must be in the app's plugin list (
packages/apps/composer-app/src/plugin-defs.tsx). If the plugin is imported there, its blueprints are available.
Testing with AssistantTestLayer
Use AssistantTestLayer from @dxos/assistant/testing to test operations and AI flows that use blueprints.
import { AssistantTestLayer } from '@dxos/assistant/testing';
import { Blueprint } from '@dxos/blueprints';
import MarkdownBlueprint from '../markdown-blueprint';
const TestLayer = AssistantTestLayer({
operationHandlers: MarkdownBlueprint.operations,
types: [SpaceProperties, Collection.Collection, Blueprint.Blueprint, Markdown.Document, HasSubject.HasSubject],
tracing: 'pretty',
});
operationHandlers— the blueprint'soperations(handler set). Required forFunctionInvocationService.invokeFunctionto resolve handlers.types— ECHO types the test needs (e.g.Markdown.Document,Blueprint.Blueprint).blueprints— optional; use when the test binds blueprints viaAiContextService.bindContext({ blueprints: [...] })and you need the registry to know about them.
To invoke an operation directly:
import { FunctionInvocationService } from '@dxos/functions';
import { Create } from './definitions';
const result =
yield *
FunctionInvocationService.invokeFunction(Create, {
name: 'My Doc',
content: 'Hello world.',
});