@dxos/assistant-toolkit 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/assistant-toolkit",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Assistant toolkit, definitions, and utilities.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -15,12 +15,12 @@
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "default": "./dist/lib/neutral/index.mjs"
+      "import": "./dist/lib/index.mjs"
     },
     "./testing": {
       "source": "./src/testing/index.ts",
       "types": "./dist/types/src/testing/index.d.ts",
-      "default": "./dist/lib/neutral/testing/index.mjs"
+      "import": "./dist/lib/testing.mjs"
     }
   },
   "files": [
@@ -33,42 +33,43 @@
     "@effect/platform": "0.96.2",
     "dfx": "^0.127.0",
     "exa-js": "^1.5.12",
-    "@dxos/ai": "0.10.0",
-    "@dxos/app-framework": "0.10.0",
-    "@dxos/assistant": "0.10.0",
-    "@dxos/client-protocol": "0.10.0",
-    "@dxos/echo": "0.10.0",
-    "@dxos/app-toolkit": "0.10.0",
-    "@dxos/compute": "0.10.0",
-    "@dxos/compute-runtime": "0.10.0",
-    "@dxos/edge-client": "0.10.0",
-    "@dxos/errors": "0.10.0",
-    "@dxos/echo-protocol": "0.10.0",
-    "@dxos/functions": "0.10.0",
-    "@dxos/effect": "0.10.0",
-    "@dxos/invariant": "0.10.0",
-    "@dxos/functions-runtime": "0.10.0",
-    "@dxos/react-ui": "0.10.0",
-    "@dxos/keys": "0.10.0",
-    "@dxos/react-ui-syntax-highlighter": "0.10.0",
-    "@dxos/schema": "0.10.0",
-    "@dxos/types": "0.10.0",
-    "@dxos/util": "0.10.0",
-    "@dxos/log": "0.10.0"
+    "@dxos/agent-runtime": "0.11.0",
+    "@dxos/ai": "0.11.0",
+    "@dxos/app-framework": "0.11.0",
+    "@dxos/app-toolkit": "0.11.0",
+    "@dxos/assistant": "0.11.0",
+    "@dxos/compute": "0.11.0",
+    "@dxos/compute-runtime": "0.11.0",
+    "@dxos/echo": "0.11.0",
+    "@dxos/echo-protocol": "0.11.0",
+    "@dxos/edge-client": "0.11.0",
+    "@dxos/effect": "0.11.0",
+    "@dxos/errors": "0.11.0",
+    "@dxos/invariant": "0.11.0",
+    "@dxos/keys": "0.11.0",
+    "@dxos/log": "0.11.0",
+    "@dxos/protocols": "0.11.0",
+    "@dxos/react-ui": "0.11.0",
+    "@dxos/react-ui-syntax-highlighter": "0.11.0",
+    "@dxos/schema": "0.11.0",
+    "@dxos/types": "0.11.0",
+    "@dxos/util": "0.11.0",
+    "@dxos/client-protocol": "0.11.0"
   },
   "devDependencies": {
     "effect": "3.21.4",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "@dxos/client-protocol": "0.10.0",
-    "@dxos/plugin-markdown": "0.10.0",
-    "@dxos/ui-theme": "0.10.0"
+    "@dxos/echo-client": "0.11.0",
+    "@dxos/plugin-markdown": "0.11.0",
+    "@dxos/ui-theme": "0.11.0",
+    "@dxos/client-protocol": "0.11.0"
   },
   "peerDependencies": {
     "effect": "3.21.4",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "@dxos/ui-theme": "0.10.0"
+    "@dxos/ui-theme": "^0.11.0"
   },
   "publishConfig": {
     "access": "public"

package/src/operations/run-instructions.test.ts

@@ -6,31 +6,37 @@ import { describe, expect, it } from '@effect/vitest';
 import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
+import { AssistantTestLayer } from '@dxos/agent-runtime/testing';
+import { ScriptedLanguageModel } from '@dxos/ai/testing';
 import { AiContext } from '@dxos/assistant';
 import { Instructions, Operation, OperationHandlerSet } from '@dxos/compute';
 import { Database, Feed, Filter, JsonSchema, Obj, Ref } from '@dxos/echo';
 import { TestHelpers } from '@dxos/effect/testing';
-import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
 import { EntityId } from '@dxos/keys';
 import { Text } from '@dxos/schema';
-import { Message } from '@dxos/types';
+import { Message, Outline } from '@dxos/types';
 
 import * as Chat from '../types/Chat';
-import * as Plan from '../types/Plan';
 import { RunInstructions } from './definitions';
 import defaultAgentPrompt from './run-instructions';
 
 EntityId.dangerouslyDisableRandomness();
 
-const operationHandlerSet = OperationHandlerSet.make(defaultAgentPrompt);
-
-const TestLayer = AssistantTestLayer({
-  operationHandlers: operationHandlerSet,
-  types: [Chat.Chat, Message.Message, AiContext.Binding, Text.Text, Plan.Plan],
-  aiServicePreset: 'edge-remote',
-});
+// The agent finishes by calling `completeJob`; scripting that call drives the whole operation
+// without a live model, so what is asserted is the operation's own behaviour rather than the
+// model's. A scripted turn replaces the memoized conversation this file used to replay.
+const layerWithResult = (success: unknown) =>
+  AssistantTestLayer({
+    operationHandlers: OperationHandlerSet.make(defaultAgentPrompt),
+    types: [Chat.Chat, Message.Message, AiContext.Binding, Text.Text, Outline.Outline],
+    aiService: ScriptedLanguageModel.scriptedAiService([
+      { parts: [ScriptedLanguageModel.toolCall('completeJob', { success })] },
+      // The loop asks again once the tool result is fed back; a text-only turn stops it.
+      { parts: [ScriptedLanguageModel.text('Done.')] },
+    ]),
+  });
 
-describe('Agent prompt', () => {
+describe('RunInstructions', () => {
   it.effect(
     'chat mode appends assistant messages to the chat queue',
     Effect.fnUntraced(
@@ -38,12 +44,7 @@ describe('Agent prompt', () => {
         const feed = yield* Database.add(Feed.make());
         const messageCountBefore = yield* countFeedMessages(feed);
 
-        const chat = yield* Database.add(
-          Chat.make({
-            feed: Ref.make(feed),
-          }),
-        );
-
+        const chat = yield* Database.add(Chat.make({ feed: Ref.make(feed) }));
         const instructions = yield* Database.add(
           Instructions.make({
             name: 'chat-mode-test',
@@ -52,7 +53,6 @@ describe('Agent prompt', () => {
             output: Schema.String,
           }),
         );
-
         yield* Database.flush();
 
         const result = yield* Operation.invoke(RunInstructions, {
@@ -62,34 +62,28 @@ describe('Agent prompt', () => {
         });
 
         const messageCountAfter = yield* countFeedMessages(feed);
-
         expect(messageCountAfter).toBeGreaterThan(messageCountBefore);
         expect(result).toBe('ack');
       },
-      Effect.provide(TestLayer),
+      Effect.provide(layerWithResult('ack')),
       TestHelpers.provideTestContext,
     ),
-    { timeout: 60_000 },
   );
 
   it.effect(
-    'generates an object conforming to the instructions output schema',
+    'returns an object conforming to the instructions output schema',
     Effect.fnUntraced(
       function* (_) {
-        const Person = Schema.Struct({
-          name: Schema.String,
-          age: Schema.Number,
-        });
+        const Person = Schema.Struct({ name: Schema.String, age: Schema.Number });
 
         const instructions = yield* Database.add(
           Instructions.make({
             name: 'output-schema-test',
-            text: 'Invent a fictional person and call completeJob with the success object describing them (name and age).',
+            text: 'Invent a fictional person and call completeJob with the success object describing them.',
             output: Person,
             skills: [],
           }),
         );
-
         yield* Database.flush();
 
         const result = yield* Operation.invoke(RunInstructions, {
@@ -97,17 +91,15 @@ describe('Agent prompt', () => {
           input: {},
         });
 
-        // The instructions persists its declared output as a JSON schema; decode it back and assert the
-        // agent-produced object satisfies that schema.
+        // The instructions persist their declared output as a JSON schema; decode it back and assert
+        // the returned object satisfies that schema.
         const outputSchema = JsonSchema.toEffectSchema(instructions.output);
         const decoded = Schema.decodeUnknownSync(outputSchema)(result);
-        expect(typeof decoded.name).toBe('string');
-        expect(typeof decoded.age).toBe('number');
+        expect(decoded).toEqual({ name: 'Ada Lovelace', age: 36 });
       },
-      Effect.provide(TestLayer),
+      Effect.provide(layerWithResult({ name: 'Ada Lovelace', age: 36 })),
       TestHelpers.provideTestContext,
     ),
-    { timeout: 60_000 },
   );
 });
 

package/src/operations/skill-resolution.test.ts

@@ -6,11 +6,11 @@ import { describe, it } from '@effect/vitest';
 import * as Duration from 'effect/Duration';
 import * as Effect from 'effect/Effect';
 
+import { AssistantTestLayer } from '@dxos/agent-runtime/testing';
 import { AiContext } from '@dxos/assistant';
 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 { WebSearchSkill } from '../skills';
@@ -111,6 +111,11 @@ describe('Skill binding resolution (registry refs)', () => {
         yield* Effect.promise(() => writer.open());
         yield* Effect.promise(() => writer.bind({ skills: [Ref.make(skill)], objects: [] }));
 
+        // Model a spawned process reading the feed cold: drop the in-memory feed handle so the
+        // reader re-decodes the binding freshly, without the writer's identity-preserved instance
+        // (whose ref still carries the in-memory skill target).
+        yield* Effect.promise(() => db.evictFeedHandle(feed));
+
         const reader = new AiContext.Binder({ feed, runtime });
         yield* Effect.promise(() => reader.open()).pipe(
           Effect.timeoutFail({

package/src/skills/agent/operations/definitions.ts

@@ -4,50 +4,33 @@
 
 import * as Schema from 'effect/Schema';
 
-import { AiService, OpaqueToolkit } from '@dxos/ai';
+import { AiService } from '@dxos/ai';
 import { Harness } from '@dxos/assistant';
-import { Operation, Trace, TriggerEvent } from '@dxos/compute';
-import { Database, Ref, Registry } from '@dxos/echo';
+import { Operation, TriggerEvent } from '@dxos/compute';
+import { AgentService } from '@dxos/compute/AgentService';
+import { Database, Ref } from '@dxos/echo';
 import { DXN } from '@dxos/keys';
 
-import { Agent } from '../../../types';
+import { Chat } from '../../../types';
 
-export const AgentWorker = Operation.make({
+export const Relay = Operation.make({
   meta: {
-    key: DXN.make('org.dxos.function.agent.worker'),
-    name: 'Agent Worker',
-    description: 'Agentic worker that drives the agent autonomously.',
-    icon: 'ph--brain--regular',
-  },
-  input: Schema.Struct({
-    agent: Schema.suspend(() => Ref.Ref(Agent.Agent)),
-    prompt: Schema.optional(Schema.String),
-    event: Schema.optional(TriggerEvent.TriggerEvent),
-  }),
-  output: Schema.Void,
-  services: [
-    AiService.AiService,
-    Database.Service,
-    Registry.Service,
-    Trace.TraceService,
-    OpaqueToolkit.OpaqueToolkitProvider,
-  ],
-});
-
-export const Qualifier = Operation.make({
-  meta: {
-    key: DXN.make('org.dxos.function.agent.qualifier'),
-    name: 'Agent Qualifier',
-    description:
-      'Qualifier that determines if the event is relevant to the agent. Puts the data into the input queue of the agent.',
+    key: DXN.make('org.dxos.function.agent.relay'),
+    name: 'Agent Relay',
+    description: 'Qualifies a subscription event with a cheap model and forwards it onto the durable agent session.',
     icon: 'ph--funnel--regular',
   },
   input: Schema.Struct({
-    agent: Schema.suspend(() => Ref.Ref(Agent.Agent)),
-    event: TriggerEvent.TriggerEvent,
+    /** The chat whose durable session receives the event (carries feed, instructions, and agent). */
+    chat: Schema.suspend(() => Ref.Ref(Chat.Chat)),
+    event: Schema.optional(TriggerEvent.TriggerEvent),
+    /** Synthetic wake prompt (e.g. a cron tick) delivered instead of an event payload. */
+    prompt: Schema.optional(Schema.String),
+    /** Skip the cheap-model relevance check (default: qualify when an event is present). */
+    qualify: Schema.optional(Schema.Boolean),
   }),
   output: Schema.Void,
-  services: [AiService.AiService, Database.Service],
+  services: [AiService.AiService, Database.Service, AgentService],
 });
 
 export const GetContext = Operation.make({
@@ -62,34 +45,7 @@ export const GetContext = Operation.make({
     id: Schema.String,
     name: Schema.String,
     instructions: Schema.String,
-    plan: Schema.String,
-    artifacts: Schema.Array(
-      Schema.Struct({
-        name: Schema.String,
-        type: Schema.optional(Schema.String),
-        dxn: Schema.optional(Schema.String),
-      }),
-    ),
+    checklist: Schema.String,
   }),
   services: [Harness.HarnessService, Database.Service],
 });
-
-export const AddArtifact = Operation.make({
-  meta: {
-    key: DXN.make('org.dxos.function.agent.addArtifact'),
-    name: 'Add artifact',
-    description: 'Adds a new artifact.',
-    icon: 'ph--plus--regular',
-  },
-  input: Schema.Struct({
-    name: Schema.String.annotations({
-      description: 'The name of the artifact to add.',
-    }),
-    artifact: Schema.String.annotations({
-      description:
-        'The id of the artifact to add, exactly as returned by the tool that created it. Do NOT guess or generate the id.',
-    }),
-  }),
-  output: Schema.Void,
-  services: [Harness.HarnessService, Database.Service],
-});

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

@@ -0,0 +1,81 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { AiContext } from '@dxos/assistant';
+import { Operation } from '@dxos/compute';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { invariant } from '@dxos/invariant';
+import { EntityId } from '@dxos/keys';
+import { Outline } from '@dxos/types';
+
+import { OperationTestLayer } from '../../../testing';
+import { Agent, Chat } from '../../../types';
+import AgentSkillDef from '../skill';
+import * as AgentSkillOperations from './definitions';
+
+EntityId.dangerouslyDisableRandomness();
+
+describe('GetContext', () => {
+  it.effect(
+    'reports the bound agent name and instructions',
+    Effect.fnUntraced(
+      function* (_) {
+        const { agent, conversation } = yield* setupBoundAgent();
+
+        const context = yield* Operation.invoke(AgentSkillOperations.GetContext, {}).pipe(Effect.provide(conversation));
+
+        expect(context.id).toBe(agent.id);
+        expect(context.name).toBe('Test Agent');
+        expect(context.instructions).toBe('A test agent for context.');
+        expect(context.checklist).toBe('No checklist found.');
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'formats the chat checklist once one exists',
+    Effect.fnUntraced(
+      function* (_) {
+        const { agent, conversation } = yield* setupBoundAgent();
+        const chat = yield* Agent.loadChat(agent);
+        invariant(chat, 'Agent chat not found.');
+        const { text } = yield* Chat.ensureOutlineText(chat);
+        Obj.update(text, (text) => {
+          text.content = Outline.upsertChecklistItems(text.content, [{ title: 'Buy eggs', done: false }]);
+        });
+        yield* Database.flush();
+
+        const context = yield* Operation.invoke(AgentSkillOperations.GetContext, {}).pipe(Effect.provide(conversation));
+
+        expect(context.checklist).toContain('Buy eggs');
+      },
+      Effect.provide(OperationTestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});
+
+// Creates an agent and binds it to its own chat feed so the harness-scoped operation resolves it.
+const setupBoundAgent = Effect.fnUntraced(function* () {
+  const agent = yield* Agent.makeInitialized(
+    { name: 'Test Agent', instructions: 'A test agent for context.' },
+    AgentSkillDef.make(),
+  );
+  yield* Database.flush();
+
+  const chat = yield* Agent.loadChat(agent);
+  const chatFeed = chat?.feed?.target;
+  invariant(chatFeed, 'Agent chat feed not found.');
+  const runtime = yield* Effect.runtime<Database.Service>();
+  const binder = new AiContext.Binder({ feed: chatFeed, runtime });
+  yield* Effect.promise(() => binder.bind({ objects: [Ref.make(agent)] }));
+
+  return { agent, conversation: Operation.withInvocationOptions({ conversation: Obj.getURI(chatFeed) }) };
+});

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

@@ -6,21 +6,13 @@ import * as Effect from 'effect/Effect';
 
 import { Harness } from '@dxos/assistant';
 import { Operation } from '@dxos/compute';
-import { Database, Filter, Obj } from '@dxos/echo';
+import { Filter } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
 
 import { HarnessContextError } from '../../../errors';
-import { Agent, Chat, Plan } from '../../../types';
+import { Agent, Chat } 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* () {
@@ -28,7 +20,7 @@ export default GetContext.pipe(
       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: [] };
+        return { id: '', name: '', instructions: 'No agent context.', checklist: 'No checklist found.' };
       }
       if (agents.length > 1) {
         return yield* Effect.fail(new HarnessContextError({ type: 'agent', count: agents.length }));
@@ -37,15 +29,9 @@ export default GetContext.pipe(
         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.
+      // Prefer the directly bound chat; fall back to the agent's companion chat 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);
+      const chat = directChat ?? (agents.length > 0 ? yield* Agent.loadChat(agents[0]) : undefined);
 
       if (agents.length === 0) {
         invariant(chat, 'Expected a bound chat when no agent is in context.');
@@ -53,8 +39,7 @@ export default GetContext.pipe(
           id: chat.id,
           name: chat.name ?? '',
           instructions: 'No agent context.',
-          plan: yield* formatPlan(chat),
-          artifacts: [],
+          checklist: yield* Chat.formatChecklist(chat),
         };
       }
 
@@ -63,23 +48,11 @@ export default GetContext.pipe(
       return {
         id: agent.id,
         name: agent.name,
-        instructions: yield* agent.instructions.pipe(Database.load).pipe(
-          Effect.map((_) => _.content),
+        instructions: yield* Agent.loadInstructions(agent).pipe(
+          Effect.map((_) => _.text),
           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,
-            };
-          }),
-        ),
+        checklist: yield* chat ? Chat.formatChecklist(chat) : Effect.succeed('No checklist found.'),
       };
     }) as any,
   ),

package/src/skills/agent/operations/index.ts

@@ -7,8 +7,6 @@ import { OperationHandlerSet } from '@dxos/compute';
 export * as AgentSkillOperations from './definitions';
 
 export const AgentSkillHandlers = OperationHandlerSet.lazy(
-  () => import('./add-artifact'),
-  () => import('./agent'),
   () => import('./get-context'),
-  () => import('./qualifier'),
+  () => import('./relay'),
 );

package/src/skills/agent/operations/relay.test.ts

@@ -0,0 +1,63 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import { expect } from 'vitest';
+
+import { AssistantTestLayer } from '@dxos/agent-runtime/testing';
+import { Instructions, Operation, OperationHandlerSet, Process } from '@dxos/compute';
+import { ProcessManager } from '@dxos/compute-runtime';
+import { Database, Feed, Obj, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { Text } from '@dxos/schema';
+
+import { Chat } from '../../../types';
+import { Relay } from './definitions';
+import relayHandler from './relay';
+
+const TestLayer = AssistantTestLayer({
+  operationHandlers: OperationHandlerSet.make(relayHandler),
+  types: [Chat.Chat, Instructions.Instructions, Text.Text, Feed.Feed],
+});
+
+// Control-plane only: the qualify:false path needs no LLM turn, so it runs ungated in CI.
+// Qualification itself (cheap-model relevance) is covered by the memoized agent-skill suite.
+describe('Agent relay (control plane)', () => {
+  it.scoped(
+    'forwards onto the durable session for the chat feed',
+    Effect.fnUntraced(
+      function* (_) {
+        const processManager = yield* ProcessManager.ProcessManagerService;
+
+        const instructions = yield* Database.add(Instructions.make({ text: 'Relay target.' }));
+        const feed = yield* Database.add(Feed.make());
+        const chat = yield* Database.add(
+          Chat.make({ name: 'Relay chat', feed: Ref.make(feed), instructions: Ref.make(instructions) }),
+        );
+        yield* Database.flush();
+
+        yield* Operation.invoke(Relay, {
+          chat: Ref.make(chat),
+          prompt: 'Wake up.',
+          qualify: false,
+        });
+
+        // Delivery lands on the durable process keyed by the chat feed (spawned on demand).
+        const target = Obj.getURI(feed);
+        const processes = yield* processManager.list({ target });
+        expect(processes.length).toBeGreaterThanOrEqual(1);
+
+        // Terminate before the turn runs — this test proves delivery, not the LLM turn.
+        for (const handle of processes) {
+          if (handle.status.state === Process.State.RUNNING) {
+            yield* handle.terminate();
+          }
+        }
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});