@dxos/assistant-toolkit 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/{blueprints/database/blueprint.test.ts → skills/database/skill.test.ts}

@@ -5,7 +5,7 @@
 import { describe, expect, it } from '@effect/vitest';
 import * as Effect from 'effect/Effect';
 
-import { Blueprint, Operation } from '@dxos/compute';
+import { Operation, Skill } from '@dxos/compute';
 import { Database, Entity, Feed, Filter, Obj, Query, Ref, Relation, Scope, Tag, Type } from '@dxos/echo';
 import { TestHelpers } from '@dxos/effect/testing';
 import { AgentService } from '@dxos/functions-runtime';
@@ -14,21 +14,21 @@ import { EID, EntityId } from '@dxos/keys';
 import { Employer, Organization, Person } from '@dxos/types';
 import { trim } from '@dxos/util';
 
-import DatabaseBlueprint from './blueprint';
 import { DatabaseHandlers } from './operations';
 import { Query as DatabaseQueryOperation } from './operations/definitions';
+import DatabaseSkill from './skill';
 
 EntityId.dangerouslyDisableRandomness();
 
 const TestLayer = AssistantTestLayer({
   operationHandlers: DatabaseHandlers,
-  types: [Organization.Organization, Person.Person, Employer.Employer, Tag.Tag, Blueprint.Blueprint, Feed.Feed],
-  blueprints: [DatabaseBlueprint.make()],
+  types: [Organization.Organization, Person.Person, Employer.Employer, Tag.Tag, Skill.Skill, Feed.Feed],
+  skills: [DatabaseSkill.make()],
   tracing: 'pretty',
   aiServicePreset: 'edge-remote',
 });
 
-describe('Database Blueprint', () => {
+describe('Database Skill', () => {
   //
   // Schema
   //
@@ -38,7 +38,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         yield* agent.submitPrompt('List all available schemas. Tell me what typenames are available.');
         yield* agent.waitForCompletion();
@@ -54,7 +54,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         yield* agent.submitPrompt(
           'Add a new schema called "Project" with typename "com.example.type.project" and fields: name (string), description (string), and status (string).',
@@ -81,7 +81,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         yield* agent.submitPrompt('Create a new organization called "Cyberdyne Systems".');
         yield* agent.waitForCompletion();
@@ -99,7 +99,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         yield* agent.submitPrompt(
           'Create a preson fullName="John Doe" with a reference to the organization "Cyberdyne Systems".',
@@ -122,7 +122,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Obsolete Corp' }));
         yield* agent.submitPrompt(`Delete the organization "Obsolete Corp".`);
@@ -140,7 +140,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Old Name Inc' }));
         yield* agent.submitPrompt(`Update the organization "Old Name Inc" and change its name to "New Name Corp".`);
@@ -162,7 +162,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         yield* Database.add(Obj.make(Organization.Organization, { name: 'Acme Corp' }));
         yield* Database.add(Obj.make(Organization.Organization, { name: 'Globex Industries' }));
@@ -180,7 +180,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         const org = yield* Database.add(
           Obj.make(Organization.Organization, { name: 'Detail Corp', description: 'A detailed organization.' }),
@@ -204,7 +204,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         yield* Database.add(Obj.make(Person.Person, { fullName: 'John Connor' }));
         yield* Database.add(Obj.make(Organization.Organization, { name: 'Cyberdyne Systems' }));
@@ -226,7 +226,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         const person = yield* Database.add(Obj.make(Person.Person, { fullName: 'Sarah Connor' }));
         const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Cyberdyne Systems' }));
@@ -257,7 +257,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Tagged Corp' }));
         const tag = yield* Database.add(Tag.make({ label: 'important' }));
@@ -279,7 +279,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Untagged Corp' }));
         const tag = yield* Database.add(Tag.make({ label: 'obsolete' }));
@@ -306,7 +306,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         yield* Database.add(Obj.make(Organization.Organization, { name: 'Context Corp' }));
         yield* agent.submitPrompt(`Add the organization "Context Corp" to the chat context.`);
@@ -325,7 +325,7 @@ describe('Database Blueprint', () => {
     Effect.fnUntraced(
       function* (_) {
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         const org = yield* Database.add(Obj.make(Organization.Organization, { name: 'Remove Context Corp' }));
         const { db } = yield* Database.Service;
@@ -359,7 +359,7 @@ describe('Database Blueprint', () => {
         yield* Database.flush();
 
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         yield* agent.submitPrompt(trim`
           A mock email was stored only on a feed (queue), not as a regular space document: organization "Lot Booking Co"
@@ -476,7 +476,7 @@ describe('Database Blueprint', () => {
         yield* Database.flush();
 
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         yield* agent.submitPrompt('Query for organizations in "inbox-1" feed.');
         yield* agent.waitForCompletion();
@@ -511,7 +511,7 @@ describe('Database Blueprint', () => {
         yield* Database.flush();
 
         const agent = yield* AgentService.createSession({
-          blueprints: [DatabaseBlueprint.make()],
+          skills: [DatabaseSkill.make()],
         });
         yield* agent.submitPrompt(
           `Call query tool with precisely ${JSON.stringify({

package/src/{blueprints/database/blueprint.ts → skills/database/skill.ts}

@@ -2,28 +2,28 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Blueprint } from '@dxos/compute';
+import { Skill } from '@dxos/compute';
 import { Ref } from '@dxos/echo';
 import { Text } from '@dxos/schema';
 import { trim } from '@dxos/util';
 
 import {
-  Query,
+  ContextAdd,
+  ContextRemove,
   Load,
   ObjectCreate,
-  ObjectUpdate,
   ObjectDelete,
-  SchemaAdd,
-  SchemaList,
-  ContextAdd,
-  ContextRemove,
+  ObjectUpdate,
+  Query,
   RelationCreate,
   RelationDelete,
+  SchemaAdd,
+  SchemaList,
   TagAdd,
   TagRemove,
 } from './operations/definitions';
 
-const BLUEPRINT_KEY = 'org.dxos.blueprint.database';
+const SKILL_KEY = 'org.dxos.skill.database';
 
 const instructions = trim`
   You can query, create, update, and delete objects in ECHO.
@@ -31,15 +31,15 @@ const instructions = trim`
 `;
 
 const make = () =>
-  Blueprint.make({
-    key: BLUEPRINT_KEY,
+  Skill.make({
+    key: SKILL_KEY,
     name: 'Database',
     description: 'Query and manipulate objects in the ECHO database.',
     agentCanEnable: true,
     instructions: {
       source: Ref.make(Text.make({ content: instructions })),
     },
-    tools: Blueprint.toolDefinitions({
+    tools: Skill.toolDefinitions({
       operations: [
         ContextAdd,
         ContextRemove,
@@ -58,9 +58,9 @@ const make = () =>
     }),
   });
 
-const blueprint: Blueprint.Definition = {
-  key: BLUEPRINT_KEY,
+const skill: Skill.Definition = {
+  key: SKILL_KEY,
   make,
 };
 
-export default blueprint;
+export default skill;

package/src/{blueprints → skills}/delegation/index.ts

@@ -2,5 +2,5 @@
 // Copyright 2026 DXOS.org
 //
 
-export { default as DelegationBlueprint } from './blueprint';
+export { default as DelegationSkill } from './skill';
 export { DelegationHandlers, DelegationOperations } from './operations';

package/src/skills/delegation/operations/delegate-task.test.ts

@@ -0,0 +1,122 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Operation, Skill } from '@dxos/compute';
+import { Database, Feed, Obj } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
+import { invariant } from '@dxos/invariant';
+import { EntityId } from '@dxos/keys';
+
+import { Agent, Chat, Plan } from '../../../types';
+import DelegationSkill from '../skill';
+import { DelegateTask } from './delegate-task';
+import { DelegationHandlers } from './index';
+
+EntityId.dangerouslyDisableRandomness();
+
+const TestLayer = AssistantTestLayer({
+  operationHandlers: DelegationHandlers,
+  types: [Agent.Agent, Plan.Plan, Chat.Chat, Chat.CompanionTo, Skill.Skill, Feed.Feed],
+  skills: [DelegationSkill.make()],
+  disableLlmMemoization: true,
+});
+
+const invokeDelegateTask = (input: { id?: Plan.TaskId; title?: string }, chatFeed: Feed.Feed) =>
+  Operation.invoke(DelegateTask, input).pipe(
+    Effect.provide(Operation.withInvocationOptions({ conversation: Obj.getURI(chatFeed) })),
+  );
+
+describe('DelegateTask', () => {
+  it.scoped(
+    'adds an in-progress task to the agent plan for delegated work',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        const agent = yield* Agent.makeInitialized(
+          { name: 'Supervisor', instructions: 'Test.' },
+          DelegationSkill.make(),
+        );
+        yield* Database.flush();
+
+        const chatFeed = agent.chat?.target?.feed?.target;
+        invariant(chatFeed, 'Agent chat feed not found.');
+
+        yield* invokeDelegateTask({ title: 'Research widgets' }, chatFeed);
+
+        const chat = yield* Database.load(agent.chat!);
+        const plan = yield* Database.load(chat.plan!);
+        expect(plan.tasks).toHaveLength(1);
+        expect(plan.tasks[0]).toMatchObject({
+          title: 'Research widgets',
+          status: 'in-progress',
+          delegated: true,
+        });
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.scoped(
+    'delegates an existing plan task by id without duplicating',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        const agent = yield* Agent.makeInitialized(
+          { name: 'Supervisor', instructions: 'Test.' },
+          DelegationSkill.make(),
+        );
+        const chat = yield* Database.load(agent.chat!);
+        const plan = yield* Chat.ensurePlan(chat);
+        const taskId = Plan.TaskId.make('1-ab');
+        Obj.update(plan, (plan) => {
+          plan.tasks.push({ id: taskId, title: 'Research widgets', status: 'todo' });
+        });
+        yield* Database.flush();
+
+        const chatFeed = agent.chat?.target?.feed?.target;
+        invariant(chatFeed, 'Agent chat feed not found.');
+
+        yield* invokeDelegateTask({ id: taskId }, chatFeed);
+
+        const updatedChat = yield* Database.load(agent.chat!);
+        const updated = yield* Database.load(updatedChat.plan!);
+        expect(updated.tasks).toHaveLength(1);
+        expect(updated.tasks[0]).toMatchObject({
+          id: taskId,
+          title: 'Research widgets',
+          status: 'in-progress',
+          delegated: true,
+        });
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.scoped(
+    'fails when both id and title are provided',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        const agent = yield* Agent.makeInitialized(
+          { name: 'Supervisor', instructions: 'Test.' },
+          DelegationSkill.make(),
+        );
+        yield* Database.flush();
+
+        const chatFeed = agent.chat?.target?.feed?.target;
+        invariant(chatFeed, 'Agent chat feed not found.');
+
+        const exit = yield* invokeDelegateTask({ id: Plan.TaskId.make('1-ab'), title: 'New task' }, chatFeed).pipe(
+          Effect.exit,
+        );
+        expect(exit._tag).toBe('Failure');
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/skills/delegation/operations/delegate-task.ts

@@ -0,0 +1,93 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { Harness } from '@dxos/assistant';
+import { Operation } from '@dxos/compute';
+import { Database, Obj } from '@dxos/echo';
+import { DXN } from '@dxos/keys';
+import { trim } from '@dxos/util';
+
+import { Chat, Plan } from '../../../types';
+
+export const DelegateTask = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.function.delegation.delegateTask'),
+    name: 'Delegate task',
+    description: trim`
+      Delegate a unit of work to a sub-agent.
+      Provide either \`id\` (an existing plan task from update-tasks) or \`title\` (to create a new task).
+      Marks the task in-progress and delegated so the supervisor spawns a background sub-agent.
+    `,
+    icon: 'ph--share-network--regular',
+  },
+  input: Schema.Struct({
+    id: Schema.optional(Plan.TaskId).annotations({
+      description: 'Id of an existing plan task to delegate (from update-tasks).',
+    }),
+    title: Schema.optional(Schema.String).annotations({
+      description: 'Title for a new task to create and delegate. Omit when delegating by id.',
+    }),
+  }),
+  output: Schema.Any,
+  services: [Harness.HarnessService, Database.Service],
+});
+
+/**
+ * Records delegated work as an in-progress task on the current session plan.
+ */
+export default DelegateTask.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ id, title }) {
+      const hasId = id !== undefined;
+      const hasTitle = title !== undefined && title.length > 0;
+      if (hasId === hasTitle) {
+        return yield* Effect.fail(
+          new Error('Provide exactly one of `id` (existing plan task) or `title` (new task to create).'),
+        );
+      }
+
+      const chat = yield* Chat.getFromContext;
+      const plan = yield* Chat.ensurePlan(chat);
+
+      if (hasId) {
+        const existing = plan.tasks.find((task) => task.id === id);
+        if (!existing) {
+          return yield* Effect.fail(new Error(`Plan task not found: ${id}`));
+        }
+        if (existing.status === 'done' || existing.status === 'failed') {
+          return yield* Effect.fail(
+            new Error(`Plan task "${id}" is already ${existing.status} and cannot be delegated.`),
+          );
+        }
+
+        Obj.update(plan, (plan) => {
+          const task = plan.tasks.find((task) => task.id === id);
+          if (task) {
+            task.delegated = true;
+            task.status = 'in-progress';
+          }
+        });
+      } else {
+        if (title === undefined) {
+          return yield* Effect.fail(
+            new Error('Provide exactly one of `id` (existing plan task) or `title` (new task to create).'),
+          );
+        }
+        Obj.update(plan, (plan) => {
+          Plan.addTasks(plan, [{ title, status: 'in-progress', delegated: true }]);
+        });
+      }
+
+      return trim`
+        Delegated work as an in-progress task. Current plan:
+        <plan>
+          ${Plan.formatPlan(plan)}
+        </plan>
+      `;
+    }),
+  ),
+);

package/src/skills/delegation/skill.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Skill } from '@dxos/compute';
+
+import { DelegateTask } from './operations/delegate-task';
+
+const SKILL_KEY = 'org.dxos.skill.delegation';
+
+const make = () =>
+  Skill.make({
+    key: SKILL_KEY,
+    name: 'Delegation',
+    description: 'Delegates work to sub-agents and tracks it as plan tasks.',
+    tools: Skill.toolDefinitions({ operations: [DelegateTask] }),
+  });
+
+const skill: Skill.Definition = {
+  key: SKILL_KEY,
+  make,
+};
+
+export default skill;

package/src/{blueprints → skills}/discord/index.ts

@@ -2,5 +2,5 @@
 // Copyright 2025 DXOS.org
 //
 
-export { default as DiscordBlueprint } from './blueprint';
+export { default as DiscordSkill } from './skill';
 export { DiscordHandlers, DiscordOperations } from './operations';

package/src/{blueprints → skills}/discord/operations/definitions.ts

@@ -4,7 +4,7 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Credential, Trace, Operation } from '@dxos/compute';
+import { Credential, Operation, Trace } from '@dxos/compute';
 import { DXN } from '@dxos/keys';
 
 // TODO(dmaretskyi): Extract.

package/src/{blueprints → skills}/discord/operations/fetch-messages.ts

@@ -17,7 +17,7 @@ import * as Function from 'effect/Function';
 import * as Layer from 'effect/Layer';
 import * as Option from 'effect/Option';
 
-import { Credential, Trace, Operation } from '@dxos/compute';
+import { Credential, Operation, Trace } from '@dxos/compute';
 import { Obj } from '@dxos/echo';
 import { log } from '@dxos/log';
 import { Message } from '@dxos/types';

package/src/{blueprints/discord/blueprint.ts → skills/discord/skill.ts}

@@ -2,14 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Blueprint } from '@dxos/compute';
+import { Skill } from '@dxos/compute';
 import { Ref } from '@dxos/echo';
 import { Text } from '@dxos/schema';
 import { trim } from '@dxos/util';
 
 import { FetchMessages } from './operations/definitions';
 
-const BLUEPRINT_KEY = 'org.dxos.blueprint.discord';
+const SKILL_KEY = 'org.dxos.skill.discord';
 
 /**
  * Agent prompt instructions for managing hierarchical task lists.
@@ -23,19 +23,19 @@ const instructions = trim`
 `;
 
 const make = () =>
-  Blueprint.make({
-    key: BLUEPRINT_KEY,
+  Skill.make({
+    key: SKILL_KEY,
     name: 'Discord',
     description: 'Discord integration.',
     instructions: {
       source: Ref.make(Text.make({ content: instructions })),
     },
-    tools: Blueprint.toolDefinitions({ operations: [FetchMessages] }),
+    tools: Skill.toolDefinitions({ operations: [FetchMessages] }),
   });
 
-const blueprint: Blueprint.Definition = {
-  key: BLUEPRINT_KEY,
+const skill: Skill.Definition = {
+  key: SKILL_KEY,
   make,
 };
 
-export default blueprint;
+export default skill;

package/src/{blueprints → skills}/index.ts

@@ -4,9 +4,11 @@
 
 export * from './agent';
 export * from './agent-wizard';
+export * from './alarm';
 export * from './automation';
-export * from './blueprint-manager';
+export * from './skill-manager';
 export * from './browser';
+export * from './connectors';
 export * from './database';
 export * from './delegation';
 export * from './discord';

package/src/{blueprints → skills}/linear/index.ts

@@ -2,5 +2,5 @@
 // Copyright 2025 DXOS.org
 //
 
-export { default as LinearBlueprint } from './blueprint';
+export { default as LinearSkill } from './skill';
 export { LinearHandlers, LinearOperations } from './operations';

package/src/{blueprints/linear/blueprint.ts → skills/linear/skill.ts}

@@ -2,14 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Blueprint } from '@dxos/compute';
+import { Skill } from '@dxos/compute';
 import { Ref } from '@dxos/echo';
 import { Text } from '@dxos/schema';
 import { trim } from '@dxos/util';
 
 import { SyncIssues } from './operations/definitions';
 
-const BLUEPRINT_KEY = 'org.dxos.blueprint.linear';
+const SKILL_KEY = 'org.dxos.skill.linear';
 
 /**
  * Agent prompt instructions for managing hierarchical task lists.
@@ -24,19 +24,19 @@ const instructions = trim`
 `;
 
 const make = () =>
-  Blueprint.make({
-    key: BLUEPRINT_KEY,
+  Skill.make({
+    key: SKILL_KEY,
     name: 'Linear',
     description: 'Syncs Linear workspaces.',
     instructions: {
       source: Ref.make(Text.make({ content: instructions })),
     },
-    tools: Blueprint.toolDefinitions({ operations: [SyncIssues] }),
+    tools: Skill.toolDefinitions({ operations: [SyncIssues] }),
   });
 
-const blueprint: Blueprint.Definition = {
-  key: BLUEPRINT_KEY,
+const skill: Skill.Definition = {
+  key: SKILL_KEY,
   make,
 };
 
-export default blueprint;
+export default skill;

package/src/{blueprints → skills}/memory/index.ts

@@ -2,5 +2,5 @@
 // Copyright 2026 DXOS.org
 //
 
-export { default as MemoryBlueprint } from './blueprint';
+export { default as MemorySkill } from './skill';
 export { MemoryHandlers, MemoryOperations } from './operations';