@dxos/assistant-toolkit 0.9.1-main.c7dcc2e112 → 0.10.0

package/src/{functions/agent/blueprint-resolution.test.ts → operations/skill-resolution.test.ts}

@@ -7,20 +7,20 @@ import * as Duration from 'effect/Duration';
 import * as Effect from 'effect/Effect';
 
 import { AiContext } from '@dxos/assistant';
-import { Blueprint, Routine } from '@dxos/compute';
+import { Instructions, Skill } from '@dxos/compute';
 import { Database, Feed, Ref } from '@dxos/echo';
 import { TestHelpers } from '@dxos/effect/testing';
 import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
 import { Text } from '@dxos/schema';
 
-import { WebSearchBlueprint } from '../../blueprints';
+import { WebSearchSkill } from '../skills';
 
-// Regression coverage for the CRM-routine failure: blueprints live only in the registry
-// (referenced via `Ref.fromURI(Blueprint.registryURI(key))`), never forked into the space DB.
+// Regression coverage for the CRM-instructions failure: skills live only in the registry
+// (referenced via `Ref.fromURI(Skill.registryURI(key))`), never forked into the space DB.
 //
-// `AiContext.Binder.bind` persists each bound blueprint ref to the conversation feed. A later
+// `AiContext.Binder.bind` persists each bound skill ref to the conversation feed. A later
 // turn (or spawned process) re-reads that ref with an empty in-memory cache and must resolve it
-// on its own. If the routine's registry blueprint is bound by its registry DXN ref, resolution
+// on its own. If the instructions's registry skill is bound by its registry DXN ref, resolution
 // stays in the registry and succeeds. If it is re-wrapped with `Ref.make` first (minting an
 // EID ref to an object that only exists in the registry, never in the DB), the persisted ref
 // dangles — in production the DB query blocks for its full 30s timeout; with a fresh binder here
@@ -30,40 +30,40 @@ const TestLayer = AssistantTestLayer({
   types: [Text.Text],
 });
 
-const blueprintKey = 'org.dxos.blueprint.webSearch';
+const skillKey = 'org.dxos.skill.webSearch';
 
-describe('Blueprint binding resolution (registry refs)', () => {
+describe('Skill binding resolution (registry refs)', () => {
   it.effect(
-    'a registry blueprint bound by its registry ref survives a feed round-trip',
+    'a registry skill bound by its registry ref survives a feed round-trip',
     Effect.fnUntraced(
       function* ({ expect }) {
         const { db } = yield* Database.Service;
 
-        // Register the web-search blueprint in the db registry (the resolver's registry),
-        // the same way `plugin-automation/RegistrySync` does in production.
-        db.registry.add([WebSearchBlueprint.make()]);
+        // Register the web-search skill in the db registry (the resolver's registry),
+        // the same way `plugin-instructions/RegistrySync` does in production.
+        db.registry.add([WebSearchSkill.make()]);
 
-        // Create a routine referencing the blueprint purely by registry URI. Once added to the
-        // DB its blueprint ref is a resolver-backed registry ref — exactly the ref `prompt.ts`
+        // Create a instructions referencing the skill purely by registry URI. Once added to the
+        // DB its skill ref is a resolver-backed registry ref — exactly the ref `prompt.ts`
         // binds.
-        const routine = yield* Database.add(
-          Routine.make({
+        const instructions = yield* Database.add(
+          Instructions.make({
             name: 'resolution-test',
-            instructions: 'noop',
-            blueprints: [Ref.fromURI(Blueprint.registryURI(blueprintKey))],
+            text: 'noop',
+            skills: [Ref.fromURI(Skill.registryURI(skillKey))],
           }),
         );
         yield* Database.flush();
-        const registryRef = routine.blueprints[0];
+        const registryRef = instructions.skills[0];
 
         const feed = yield* Database.add(Feed.make());
         yield* Database.flush();
-        const runtime = yield* Effect.runtime<Feed.FeedService>();
+        const runtime = yield* Effect.runtime<Database.Service>();
 
-        // Bind the routine's own registry ref (the fix) and persist it to the feed.
+        // Bind the instructions's own registry ref (the fix) and persist it to the feed.
         const writer = new AiContext.Binder({ feed, runtime });
         yield* Effect.promise(() => writer.open());
-        yield* Effect.promise(() => writer.bind({ blueprints: [registryRef], objects: [] }));
+        yield* Effect.promise(() => writer.bind({ skills: [registryRef], objects: [] }));
 
         // A fresh binder on the same feed models the next agent turn / spawned process: no
         // in-memory cache, so the persisted binding ref must resolve on its own.
@@ -71,12 +71,12 @@ describe('Blueprint binding resolution (registry refs)', () => {
         yield* Effect.promise(() => reader.open()).pipe(
           Effect.timeoutFail({
             duration: Duration.seconds(3),
-            onTimeout: () => new Error('TIMED OUT resolving bound blueprint on feed re-read'),
+            onTimeout: () => new Error('TIMED OUT resolving bound skill on feed re-read'),
           }),
         );
 
-        const resolved = reader.getBlueprints();
-        expect(resolved.map((bp) => Blueprint.getKey(bp))).toContain(blueprintKey);
+        const resolved = reader.getSkills();
+        expect(resolved.map((bp) => Skill.getKey(bp))).toContain(skillKey);
       },
       Effect.provide(TestLayer),
       TestHelpers.provideTestContext,
@@ -85,43 +85,43 @@ describe('Blueprint binding resolution (registry refs)', () => {
   );
 
   it.effect(
-    'a registry blueprint re-wrapped with Ref.make (EID ref) dangles on feed re-read',
+    'a registry skill re-wrapped with Ref.make (EID ref) dangles on feed re-read',
     Effect.fnUntraced(
       function* ({ expect }) {
         const { db } = yield* Database.Service;
-        db.registry.add([WebSearchBlueprint.make()]);
+        db.registry.add([WebSearchSkill.make()]);
 
-        const routine = yield* Database.add(
-          Routine.make({
+        const instructions = yield* Database.add(
+          Instructions.make({
             name: 'resolution-test',
-            instructions: 'noop',
-            blueprints: [Ref.fromURI(Blueprint.registryURI(blueprintKey))],
+            text: 'noop',
+            skills: [Ref.fromURI(Skill.registryURI(skillKey))],
           }),
         );
         yield* Database.flush();
-        const blueprint = yield* Database.load(routine.blueprints[0]);
+        const skill = yield* Database.load(instructions.skills[0]);
 
         const feed = yield* Database.add(Feed.make());
         yield* Database.flush();
-        const runtime = yield* Effect.runtime<Feed.FeedService>();
+        const runtime = yield* Effect.runtime<Database.Service>();
 
-        // The pre-fix behaviour: re-wrap the resolved blueprint with `Ref.make`, minting an
-        // EID ref that addresses a blueprint which only exists in the registry.
+        // The pre-fix behaviour: re-wrap the resolved skill with `Ref.make`, minting an
+        // EID ref that addresses a skill which only exists in the registry.
         const writer = new AiContext.Binder({ feed, runtime });
         yield* Effect.promise(() => writer.open());
-        yield* Effect.promise(() => writer.bind({ blueprints: [Ref.make(blueprint)], objects: [] }));
+        yield* Effect.promise(() => writer.bind({ skills: [Ref.make(skill)], objects: [] }));
 
         const reader = new AiContext.Binder({ feed, runtime });
         yield* Effect.promise(() => reader.open()).pipe(
           Effect.timeoutFail({
             duration: Duration.seconds(3),
-            onTimeout: () => new Error('TIMED OUT resolving bound blueprint on feed re-read'),
+            onTimeout: () => new Error('TIMED OUT resolving bound skill on feed re-read'),
           }),
         );
 
         // The EID ref cannot be recovered from the registry, so the fresh binder resolves nothing.
-        const resolved = reader.getBlueprints();
-        expect(resolved.map((bp) => Blueprint.getKey(bp))).not.toContain(blueprintKey);
+        const resolved = reader.getSkills();
+        expect(resolved.map((bp) => Skill.getKey(bp))).not.toContain(skillKey);
       },
       Effect.provide(TestLayer),
       TestHelpers.provideTestContext,

package/src/skills/AGENTS.md

@@ -0,0 +1,13 @@
+# Skill Structure
+
+```ts
+// <skill>/index.ts — thin re-export
+export { default as XSkill } from './skill';
+export { XSkillHandlers, XSkillOperations } from './operations';
+```
+
+```ts
+// <skill>/operations/index.ts — single source of both aggregates
+export * as XSkillOperations from './definitions';
+export const XHandlers = OperationHandlerSet.lazy(...);
+```

package/src/skills/agent/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { default as AgentSkill } from './skill';
+export { AgentSkillHandlers, AgentSkillOperations } from './operations';

package/src/{blueprints → skills}/agent/operations/agent.ts

@@ -8,7 +8,7 @@ import * as Layer from 'effect/Layer';
 import { AiService } from '@dxos/ai';
 import { AiSession, ToolExecutionServices } from '@dxos/assistant';
 import { Operation } from '@dxos/compute';
-import { Database, Feed, Obj } from '@dxos/echo';
+import { Database, Obj } from '@dxos/echo';
 import { EffectEx } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
 import { ContentBlock } from '@dxos/types';
@@ -31,7 +31,7 @@ export default AgentWorker.pipe(
         Effect.catchTag('EntityNotFoundError', () => Effect.die(new Error('Unable to load agent chat feed object.'))),
       );
       invariant(chatFeed, 'Agent chat feed not found.');
-      const runtime = yield* Effect.runtime<Feed.FeedService>();
+      const runtime = yield* Effect.runtime<Database.Service>();
       const session = yield* EffectEx.acquireReleaseResource(() => new AiSession.Session({ feed: chatFeed, runtime }));
 
       const agentsInContext = session.context.getObjects().filter(Obj.instanceOf(Agent.Agent));
@@ -57,7 +57,7 @@ export default AgentWorker.pipe(
         })
         .pipe(
           Effect.provide(
-            Layer.mergeAll(AiService.model('ai.claude.model.claude-opus-4-6'), ToolExecutionServices).pipe(
+            Layer.mergeAll(AiService.model('com.anthropic.model.claude-opus-4-8.default'), ToolExecutionServices).pipe(
               Layer.provideMerge(Operation.withInvocationOptions({ conversation: Obj.getURI(chatFeed) })),
             ),
           ),

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

@@ -5,9 +5,9 @@
 import * as Schema from 'effect/Schema';
 
 import { AiService, OpaqueToolkit } from '@dxos/ai';
-import { AiContext } from '@dxos/assistant';
-import { Trace, TriggerEvent, Operation } from '@dxos/compute';
-import { Database, Feed, Ref, Registry } from '@dxos/echo';
+import { Harness } from '@dxos/assistant';
+import { Operation, Trace, TriggerEvent } from '@dxos/compute';
+import { Database, Ref, Registry } from '@dxos/echo';
 import { DXN } from '@dxos/keys';
 
 import { Agent } from '../../../types';
@@ -28,7 +28,6 @@ export const AgentWorker = Operation.make({
   services: [
     AiService.AiService,
     Database.Service,
-    Feed.FeedService,
     Registry.Service,
     Trace.TraceService,
     OpaqueToolkit.OpaqueToolkitProvider,
@@ -48,7 +47,7 @@ export const Qualifier = Operation.make({
     event: TriggerEvent.TriggerEvent,
   }),
   output: Schema.Void,
-  services: [AiService.AiService, Database.Service, Feed.FeedService],
+  services: [AiService.AiService, Database.Service],
 });
 
 export const GetContext = Operation.make({
@@ -72,7 +71,7 @@ export const GetContext = Operation.make({
       }),
     ),
   }),
-  services: [AiContext.Service, Database.Service],
+  services: [Harness.HarnessService, Database.Service],
 });
 
 export const AddArtifact = Operation.make({
@@ -92,5 +91,5 @@ export const AddArtifact = Operation.make({
     }),
   }),
   output: Schema.Void,
-  services: [AiContext.Service, Database.Service],
+  services: [Harness.HarnessService, Database.Service],
 });

package/src/skills/agent/operations/get-context.ts

@@ -0,0 +1,87 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Harness } from '@dxos/assistant';
+import { Operation } from '@dxos/compute';
+import { Database, Filter, Obj } from '@dxos/echo';
+import { invariant } from '@dxos/invariant';
+
+import { HarnessContextError } from '../../../errors';
+import { Agent, Chat, Plan } from '../../../types';
+import { GetContext } from './definitions';
+
+const formatPlan = (chat: Chat.Chat) =>
+  chat.plan
+    ? chat.plan.pipe(Database.load).pipe(
+        Effect.map(Plan.formatPlan),
+        Effect.catchTag('EntityNotFoundError', () => Effect.succeed('No plan found.')),
+      )
+    : Effect.succeed('No plan found.');
+
+export default GetContext.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      const agents = yield* Harness.queryContext(Filter.type(Agent.Agent));
+      const chats = yield* Harness.queryContext(Filter.type(Chat.Chat));
+
+      if (agents.length === 0 && chats.length === 0) {
+        return { id: '', name: '', instructions: 'No agent context.', plan: 'No plan found.', artifacts: [] };
+      }
+      if (agents.length > 1) {
+        return yield* Effect.fail(new HarnessContextError({ type: 'agent', count: agents.length }));
+      }
+      if (chats.length > 1) {
+        return yield* Effect.fail(new HarnessContextError({ type: 'chat', count: chats.length }));
+      }
+
+      // Prefer the directly bound chat; fall back to the agent's own chat ref when no chat is bound.
+      const directChat = chats.length === 1 ? chats[0] : undefined;
+      const chat =
+        directChat ??
+        (agents.length > 0 && agents[0].chat
+          ? yield* agents[0].chat
+              .pipe(Database.load)
+              .pipe(Effect.catchTag('EntityNotFoundError', () => Effect.succeed(undefined)))
+          : undefined);
+
+      if (agents.length === 0) {
+        invariant(chat, 'Expected a bound chat when no agent is in context.');
+        return {
+          id: chat.id,
+          name: chat.name ?? '',
+          instructions: 'No agent context.',
+          plan: yield* formatPlan(chat),
+          artifacts: [],
+        };
+      }
+
+      const agent = agents[0];
+
+      return {
+        id: agent.id,
+        name: agent.name,
+        instructions: yield* agent.instructions.pipe(Database.load).pipe(
+          Effect.map((_) => _.content),
+          Effect.catchTag('EntityNotFoundError', () => Effect.succeed('No instructions found.')),
+        ),
+        plan: yield* chat ? formatPlan(chat) : Effect.succeed('No plan found.'),
+        artifacts: yield* Effect.forEach(agent.artifacts, (artifact) =>
+          Effect.gen(function* () {
+            return {
+              name: artifact.name,
+              type: yield* Database.load(artifact.data).pipe(
+                Effect.map(Obj.getTypename),
+                Effect.catchTag('EntityNotFoundError', () => Effect.succeed('Artifact not found.')),
+              ),
+              dxn: artifact.data.uri,
+            };
+          }),
+        ),
+      };
+    }) as any,
+  ),
+  Operation.opaqueHandler,
+);

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

@@ -4,9 +4,9 @@
 
 import { OperationHandlerSet } from '@dxos/compute';
 
-export * as AgentBlueprintOperations from './definitions';
+export * as AgentSkillOperations from './definitions';
 
-export const AgentBlueprintHandlers = OperationHandlerSet.lazy(
+export const AgentSkillHandlers = OperationHandlerSet.lazy(
   () => import('./add-artifact'),
   () => import('./agent'),
   () => import('./get-context'),

package/src/{blueprints → skills}/agent/operations/qualifier.ts

@@ -13,7 +13,7 @@ import { Database, Feed, Obj, Ref } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
 import { trim } from '@dxos/util';
 
-import { Plan, Agent } from '../../../types';
+import { Agent, Plan } from '../../../types';
 import { Qualifier } from './definitions';
 
 const handler: Operation.WithHandler<typeof Qualifier> = Qualifier.pipe(
@@ -29,7 +29,13 @@ const handler: Operation.WithHandler<typeof Qualifier> = Qualifier.pipe(
           throw new Error('Agent has no queue.');
         }
 
-        const plan = yield* Database.load(agent.plan);
+        const chat = yield* Database.load(agent.chat);
+        const planText = chat.plan
+          ? yield* Database.load(chat.plan).pipe(
+              Effect.map(Plan.formatPlan),
+              Effect.catchTag('EntityNotFoundError', () => Effect.succeed('No plan found.')),
+            )
+          : 'No plan found.';
         const instructions = yield* Database.load(agent.instructions);
 
         const { value } = yield* Effect.scoped(
@@ -49,7 +55,7 @@ const handler: Operation.WithHandler<typeof Qualifier> = Qualifier.pipe(
                     ${instructions.content}
                     </instructions>
                     <plan>
-                      ${Plan.formatPlan(plan)}
+                      ${planText}
                     </plan>
                   </agent>
                 `,
@@ -84,7 +90,7 @@ const handler: Operation.WithHandler<typeof Qualifier> = Qualifier.pipe(
           }
         }
       },
-      Effect.provide(AiService.model('ai.claude.model.claude-sonnet-4-5')),
+      Effect.provide(AiService.model('com.anthropic.model.claude-sonnet-4-6.default')),
     ),
   ),
 );