@dxos/assistant-toolkit 0.8.4-main.fcc0d83b33 → 0.8.4-staging.60fe92afc8

package/src/functions/agent/blueprint-resolution.test.ts

@@ -0,0 +1,131 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+
+import { AiContext } from '@dxos/assistant';
+import { Blueprint, Routine } 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';
+
+// 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.
+//
+// `AiContext.Binder.bind` persists each bound blueprint 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
+// 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
+// it simply resolves to nothing.
+
+const TestLayer = AssistantTestLayer({
+  types: [Text.Text],
+});
+
+const blueprintKey = 'org.dxos.blueprint.webSearch';
+
+describe('Blueprint binding resolution (registry refs)', () => {
+  it.effect(
+    'a registry blueprint 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()]);
+
+        // 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`
+        // binds.
+        const routine = yield* Database.add(
+          Routine.make({
+            name: 'resolution-test',
+            instructions: 'noop',
+            blueprints: [Ref.fromURI(Blueprint.registryURI(blueprintKey))],
+          }),
+        );
+        yield* Database.flush();
+        const registryRef = routine.blueprints[0];
+
+        const feed = yield* Database.add(Feed.make());
+        yield* Database.flush();
+        const runtime = yield* Effect.runtime<Feed.FeedService>();
+
+        // Bind the routine'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: [] }));
+
+        // 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.
+        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'),
+          }),
+        );
+
+        const resolved = reader.getBlueprints();
+        expect(resolved.map((bp) => Blueprint.getKey(bp))).toContain(blueprintKey);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 20_000 },
+  );
+
+  it.effect(
+    'a registry blueprint 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()]);
+
+        const routine = yield* Database.add(
+          Routine.make({
+            name: 'resolution-test',
+            instructions: 'noop',
+            blueprints: [Ref.fromURI(Blueprint.registryURI(blueprintKey))],
+          }),
+        );
+        yield* Database.flush();
+        const blueprint = yield* Database.load(routine.blueprints[0]);
+
+        const feed = yield* Database.add(Feed.make());
+        yield* Database.flush();
+        const runtime = yield* Effect.runtime<Feed.FeedService>();
+
+        // 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.
+        const writer = new AiContext.Binder({ feed, runtime });
+        yield* Effect.promise(() => writer.open());
+        yield* Effect.promise(() => writer.bind({ blueprints: [Ref.make(blueprint)], 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'),
+          }),
+        );
+
+        // 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);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 20_000 },
+  );
+});

package/src/functions/agent/definitions.ts

@@ -5,18 +5,20 @@
 import * as Schema from 'effect/Schema';
 
 import { AiService, OpaqueToolkit, ModelName } from '@dxos/ai';
-import { Routine } from '@dxos/compute';
-import { Trace } from '@dxos/compute';
-import { Operation, OperationRegistry } from '@dxos/compute';
-import { Database, Feed, Ref } from '@dxos/echo';
+import { Routine, Trace, Operation } from '@dxos/compute';
+import { Database, Feed, Ref, Registry } from '@dxos/echo';
+import { DXN } from '@dxos/keys';
+import { Text } from '@dxos/schema';
 
 import * as Chat from '../../types/Chat';
 
+// TODO(dmaretskyi): Rename to RunRoutine.
 export const AgentPrompt = Operation.make({
   meta: {
-    key: 'org.dxos.function.prompt',
-    name: 'Agent',
+    key: DXN.make('org.dxos.function.prompt'),
+    name: 'Run Routine',
     description: 'Agentic worker that executes a provided prompt using blueprints and tools.',
+    icon: 'ph--brain--regular',
   },
   input: Schema.Struct({
     prompt: Ref.Ref(Routine.Routine),
@@ -27,10 +29,10 @@ export const AgentPrompt = Operation.make({
     chat: Schema.optional(Ref.Ref(Chat.Chat)),
 
     /**
-     * @default @anthropic/claude-opus-4-6
+     * @default ai.claude.model.claude-opus-4-6
      */
-
     model: Schema.optional(ModelName),
+
     /**
      * Input object or data.
      * References get auto-resolved.
@@ -42,12 +44,15 @@ export const AgentPrompt = Operation.make({
     }),
   }),
   output: Schema.Any,
+  // ECHO types that the handler loads via Database.load(). Declaring them here ensures the
+  // runtime registers their schema before remote invocation (e.g. via the EDGE function service).
+  types: [Routine.Routine, Text.Text, Feed.Feed, Chat.Chat],
   services: [
     AiService.AiService,
     Database.Service,
     Feed.FeedService,
     OpaqueToolkit.OpaqueToolkitProvider,
-    OperationRegistry.Service,
+    Registry.Service,
     Trace.TraceService,
   ],
 });

package/src/functions/agent/prompt.conversations.json

@@ -1 +1 @@
-{"conversations":[{"parameters":{"model":"@anthropic/claude-opus-4-6","stream":true,"tools":[{"name":"completeJob","inputSchema":{"type":"object","required":[],"properties":{"success":{"$id":"/schemas/any","title":"any"},"failure":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Short message describing the error."},"description":{"type":"string","description":"Optional longer message describing in detail what went wrong"}},"additionalProperties":false}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"system","content":"You are an agent running in the non-interactive mode.\nThe user is unable to see what you are doing, and cannot answer any questions.\nDo not ask questions.\nComplete the task before you, and at the end call [completeJob] with the output.\nIf you are unable to complete the task, call [completeJob] with the failure reason.\nIf no output is required, call [completeJob] with an empty object: {}\nDo not stop until you call [completeJob].","options":{}},{"role":"user","content":"Reply with a single word: ack.\n<input>{}</input>","options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01BJnJPY3oMFLFRKBzfm18k4","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 me to reply with a single word: \"ack\".","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{"anthropic":{"type":"thinking","signature":"EvABClkIDRgCKkDoETBa+lesagv7ixB9LGrYHpBYfS/DCnRnegAetRGGWDl0kkFyqVQI7oDc+ZWbyk9tB+4ePqoqNXQXwE3240/HMg9jbGF1ZGUtb3B1cy00LTY4ABIMZ4jEaKNKFseHE6SGGgxDCMKKPXa0JrDQ52ciMG+cUvHgNQwSWMWlYEBfsVvvwZnDif1WmjybXm26QJIGtpnF/4kQQkk8Re1W0OPoYCpFYVSQgk56gj+oWRLRn8FgcWrdoxhpuw6BVArd0/EEeXi78h9AJPLa7BN30HyfNmAOQ5LiuW8fznNPRzCv1yHLrjw4IE+GGAE="}}},{"type":"reasoning-end","id":"0","metadata":{}},{"type":"tool-params-start","id":"toolu_01N1FCMswXa62WFdsMrbu4Kv","name":"completeJob","providerExecuted":false,"metadata":{}},{"type":"tool-params-delta","id":"toolu_01N1FCMswXa62WFdsMrbu4Kv","delta":"","metadata":{}},{"type":"tool-params-delta","id":"toolu_01N1FCMswXa62WFdsMrbu4Kv","delta":"{\"success\": ","metadata":{}},{"type":"tool-params-delta","id":"toolu_01N1FCMswXa62WFdsMrbu4Kv","delta":"\"ack\"}","metadata":{}},{"type":"tool-params-end","id":"toolu_01N1FCMswXa62WFdsMrbu4Kv","metadata":{}},{"type":"finish","reason":"tool-calls","usage":{"inputTokens":757,"outputTokens":85,"totalTokens":842},"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":757,"output_tokens":60,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"@anthropic/claude-opus-4-6","stream":true,"tools":[{"name":"completeJob","inputSchema":{"type":"object","required":[],"properties":{"success":{"$id":"/schemas/any","title":"any"},"failure":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Short message describing the error."},"description":{"type":"string","description":"Optional longer message describing in detail what went wrong"}},"additionalProperties":false}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"system","content":"You are an agent running in the non-interactive mode.\nThe user is unable to see what you are doing, and cannot answer any questions.\nDo not ask questions.\nComplete the task before you, and at the end call [completeJob] with the output.\nIf you are unable to complete the task, call [completeJob] with the failure reason.\nIf no output is required, call [completeJob] with an empty object: {}\nDo not stop until you call [completeJob].","options":{}},{"role":"user","content":"Reply with a single word: ack.\n<input>{}</input>","options":{}},{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to reply with a single word: \"ack\".","options":{}},{"type":"tool-call","id":"toolu_01N1FCMswXa62WFdsMrbu4Kv","name":"completeJob","params":{"success":"ack"},"providerExecuted":false,"options":{}}],"options":{}},{"role":"tool","content":[{"type":"tool-result","id":"toolu_01N1FCMswXa62WFdsMrbu4Kv","name":"completeJob","isFailure":false,"result":{},"providerExecuted":false,"options":{}}],"options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01XmKNsc4F8Re8N5UEDdxcjp","modelId":"claude-opus-4-6","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":824,"outputTokens":2,"totalTokens":826},"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":824,"output_tokens":2,"server_tool_use":null,"service_tier":"standard"}}}}]}]}
+{"conversations":[{"parameters":{"model":"ai.claude.model.claude-opus-4-6","stream":true,"tools":[{"name":"completeJob","inputSchema":{"type":"object","required":[],"properties":{"success":{"$id":"/schemas/any","title":"any"},"failure":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Short message describing the error."},"description":{"type":"string","description":"Optional longer message describing in detail what went wrong"}},"additionalProperties":false}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"system","content":"You are an agent running in the non-interactive mode.\nThe user is unable to see what you are doing, and cannot answer any questions.\nDo not ask questions.\nComplete the task before you, and at the end call [completeJob] with the output.\nIf you are unable to complete the task, call [completeJob] with the failure reason.\nIf no output is required, call [completeJob] with an empty object: {}\nDo not stop until you call [completeJob].","options":{}},{"role":"user","content":"Reply with a single word: ack.\n<input>{}</input>","options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01JstbpndWJDAhVwAppVJz2H","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 me to reply with a single word: \"ack\".","metadata":{}},{"type":"reasoning-delta","id":"0","delta":"","metadata":{"anthropic":{"type":"thinking","signature":"EvsBCmMIDhgCKkDoETBa+lesagv7ixB9LGrYHpBYfS/DCnRnegAetRGGWDl0kkFyqVQI7oDc+ZWbyk9tB+4ePqoqNXQXwE3240/HMg9jbGF1ZGUtb3B1cy00LTY4AEIIdGhpbmtpbmcSDFVIZlew/AFp1rmNoxoMPw+kyp+9hoNL5WyHIjDdm7hZK7hOH93slrwJoeXIuYMlv70L5mOQbDviNfFQyGfbuluo3tzWampRVGtohCgqRtiIkY7cWA700K9SVqH4mMfq1sjQ7yYuCRMv2lT7PrbCp3IRJmncUU6avNwBVX6E/hMO7ml/pORVNgsnB8Tn6FrYKqMFENAYAQ=="}}},{"type":"reasoning-end","id":"0","metadata":{}},{"type":"tool-params-start","id":"toolu_01KDviPNKjzY2nh9cGmo4oKm","name":"completeJob","providerExecuted":false,"metadata":{}},{"type":"tool-params-delta","id":"toolu_01KDviPNKjzY2nh9cGmo4oKm","delta":"","metadata":{}},{"type":"tool-params-delta","id":"toolu_01KDviPNKjzY2nh9cGmo4oKm","delta":"{\"success\"","metadata":{}},{"type":"tool-params-delta","id":"toolu_01KDviPNKjzY2nh9cGmo4oKm","delta":": ","metadata":{}},{"type":"tool-params-delta","id":"toolu_01KDviPNKjzY2nh9cGmo4oKm","delta":"\"ack\"}","metadata":{}},{"type":"tool-params-end","id":"toolu_01KDviPNKjzY2nh9cGmo4oKm","metadata":{}},{"type":"finish","reason":"tool-calls","usage":{"inputTokens":757,"outputTokens":85,"totalTokens":842},"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":757,"output_tokens":60,"server_tool_use":null,"service_tier":"standard"}}}}]},{"parameters":{"model":"ai.claude.model.claude-opus-4-6","stream":true,"tools":[{"name":"completeJob","inputSchema":{"type":"object","required":[],"properties":{"success":{"$id":"/schemas/any","title":"any"},"failure":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Short message describing the error."},"description":{"type":"string","description":"Optional longer message describing in detail what went wrong"}},"additionalProperties":false}},"additionalProperties":false}}]},"prompt":{"content":[{"role":"system","content":"You are an agent running in the non-interactive mode.\nThe user is unable to see what you are doing, and cannot answer any questions.\nDo not ask questions.\nComplete the task before you, and at the end call [completeJob] with the output.\nIf you are unable to complete the task, call [completeJob] with the failure reason.\nIf no output is required, call [completeJob] with an empty object: {}\nDo not stop until you call [completeJob].","options":{}},{"role":"user","content":"Reply with a single word: ack.\n<input>{}</input>","options":{}},{"role":"assistant","content":[{"type":"reasoning","text":"The user wants me to reply with a single word: \"ack\".","options":{}},{"type":"tool-call","id":"toolu_01KDviPNKjzY2nh9cGmo4oKm","name":"completeJob","params":{"success":"ack"},"providerExecuted":false,"options":{}}],"options":{}},{"role":"tool","content":[{"type":"tool-result","id":"toolu_01KDviPNKjzY2nh9cGmo4oKm","name":"completeJob","isFailure":false,"result":{},"providerExecuted":false,"options":{}}],"options":{"anthropic":{"cacheControl":{"ttl":"5m","type":"ephemeral"}}}}]},"response":[{"type":"response-metadata","id":"msg_01Pz14sZtxk8PRuR9CKbe7Fy","modelId":"claude-opus-4-6","timestamp":"1970-01-01T00:00:00.000Z","metadata":{}},{"type":"finish","reason":"stop","usage":{"inputTokens":824,"outputTokens":2,"totalTokens":826},"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":824,"output_tokens":2,"server_tool_use":null,"service_tier":"standard"}}}}]}]}

package/src/functions/agent/prompt.test.ts

@@ -5,15 +5,12 @@
 import { describe, expect, it } from '@effect/vitest';
 import * as Effect from 'effect/Effect';
 
-import { ContextBinding } from '@dxos/assistant';
-import { Routine } from '@dxos/compute';
-import { QueueService } from '@dxos/compute';
-import { Operation } from '@dxos/compute';
-import { OperationHandlerSet } from '@dxos/compute';
-import { Database, Feed, Obj, Ref } from '@dxos/echo';
+import { AiContext } from '@dxos/assistant';
+import { Routine, Operation, OperationHandlerSet } from '@dxos/compute';
+import { Database, Feed, Filter, Obj, Ref } from '@dxos/echo';
 import { TestHelpers } from '@dxos/effect/testing';
 import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
-import { ObjectId } from '@dxos/keys';
+import { EntityId } from '@dxos/keys';
 import { Text } from '@dxos/schema';
 import { Message } from '@dxos/types';
 
@@ -21,19 +18,19 @@ import * as Chat from '../../types/Chat';
 import { AgentPrompt } from './definitions';
 import defaultAgentPrompt from './prompt';
 
-ObjectId.dangerouslyDisableRandomness();
+EntityId.dangerouslyDisableRandomness();
 
 const operationHandlerSet = OperationHandlerSet.make(defaultAgentPrompt);
 
 const TestLayer = AssistantTestLayer({
   operationHandlers: operationHandlerSet,
-  types: [Chat.Chat, Message.Message, ContextBinding, Text.Text],
+  types: [Chat.Chat, Message.Message, AiContext.Binding, Text.Text],
   aiServicePreset: 'edge-remote',
 });
 
-const countQueueMessages = (queue: { queryObjects: () => Promise<Obj.Unknown[]> }) =>
-  Effect.promise(async () => {
-    const items = await queue.queryObjects();
+const countFeedMessages = (feed: Feed.Feed) =>
+  Effect.gen(function* () {
+    const items = yield* Feed.runQuery(feed, Filter.everything());
     return items.filter(Obj.instanceOf(Message.Message)).length;
   });
 
@@ -43,9 +40,7 @@ describe('Agent prompt', () => {
     Effect.fnUntraced(
       function* (_) {
         const feed = yield* Database.add(Feed.make());
-        const queueDxn = Feed.getQueueDxn(feed)!;
-        const queue = yield* QueueService.getQueue<Message.Message | ContextBinding>(queueDxn);
-        const messageCountBefore = yield* countQueueMessages(queue);
+        const messageCountBefore = yield* countFeedMessages(feed);
 
         const chat = yield* Database.add(
           Chat.make({
@@ -70,7 +65,7 @@ describe('Agent prompt', () => {
           chat: Ref.make(chat),
         });
 
-        const messageCountAfter = yield* countQueueMessages(queue);
+        const messageCountAfter = yield* countFeedMessages(feed);
 
         expect(messageCountAfter).toBeGreaterThan(messageCountBefore);
         expect(result).toBe('ack');

package/src/functions/agent/prompt.ts

@@ -4,10 +4,8 @@
 
 import * as Tool from '@effect/ai/Tool';
 import * as Toolkit from '@effect/ai/Toolkit';
-import * as Array from 'effect/Array';
 import * as Deferred from 'effect/Deferred';
 import * as Effect from 'effect/Effect';
-import * as Function from 'effect/Function';
 import * as Layer from 'effect/Layer';
 import * as Option from 'effect/Option';
 import * as Schema from 'effect/Schema';
@@ -19,11 +17,9 @@ import {
   makeToolExecutionService,
   makeToolResolverFromOperations,
 } from '@dxos/assistant';
-import { Template } from '@dxos/compute';
-import { Trace } from '@dxos/compute';
-import { Operation } from '@dxos/compute';
+import { Template, Trace, Operation } from '@dxos/compute';
 import { Database, Feed, Obj, Ref } from '@dxos/echo';
-import { acquireReleaseResource } from '@dxos/effect';
+import { EffectEx } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
 import { trim } from '@dxos/util';
@@ -32,7 +28,7 @@ import { PromptError } from '../../errors';
 import * as Chat from '../../types/Chat';
 import { AgentPrompt } from './definitions';
 
-const DEFAULT_MODEL: ModelName = '@anthropic/claude-opus-4-6';
+const DEFAULT_MODEL: ModelName = 'ai.claude.model.claude-opus-4-6';
 
 export default AgentPrompt.pipe(
   Operation.withHandler(
@@ -50,21 +46,25 @@ export default AgentPrompt.pipe(
 
         log.info('starting agent', { prompt: prompt.id, input });
 
-        const blueprints = yield* Function.pipe(
-          prompt.blueprints,
-          Effect.forEach(Database.loadOption),
-          Effect.map(Array.filter(Option.isSome)),
-          Effect.map(Array.map((option) => option.value)),
+        // Bind the routine's own refs, dropping any that no longer resolve. The refs must be
+        // bound as-is (not re-wrapped via `Ref.make`) to preserve their registry DXN: bindings
+        // are persisted to the conversation feed, and registry-only blueprints have no space-DB
+        // identity, so an EID ref would not resolve when the binding is re-read.
+        const blueprintRefs = yield* Effect.filter(prompt.blueprints, (ref) =>
+          Database.load(ref).pipe(
+            Effect.as(true),
+            Effect.catchTag('EntityNotFoundError', () => Effect.succeed(false)),
+          ),
         );
 
-        const objects = yield* Function.pipe(
-          prompt.context,
-          Effect.forEach(Database.loadOption),
-          Effect.map(Array.filter(Option.isSome)),
-          Effect.map(Array.map((option) => option.value)),
+        const objectRefs = yield* Effect.filter(prompt.context, (ref) =>
+          Database.load(ref).pipe(
+            Effect.as(true),
+            Effect.catchTag('EntityNotFoundError', () => Effect.succeed(false)),
+          ),
         );
 
-        const promptInstructions = yield* Database.load(prompt.instructions.source);
+        const promptInstructions = yield* Database.load(prompt.instructions);
         let promptText = Template.process(promptInstructions.content, input);
 
         if (input !== undefined) {
@@ -81,7 +81,7 @@ export default AgentPrompt.pipe(
           Do not stop until you call [completeJob].
         `;
         if (data.systemInstructions) {
-          systemText += `\n\n${data.systemInstructions}`;
+          systemText += `\n${data.systemInstructions}`;
         }
 
         const modelLayer = AiService.model(data.model ?? DEFAULT_MODEL);
@@ -102,12 +102,12 @@ export default AgentPrompt.pipe(
         });
 
         const runtime = yield* Effect.runtime<Feed.FeedService>();
-        const session = yield* acquireReleaseResource(() => new AiSession({ feed, runtime }));
+        const session = yield* EffectEx.acquireReleaseResource(() => new AiSession.Session({ feed, runtime }));
 
         yield* Effect.promise(() =>
           session.context.bind({
-            blueprints: blueprints.map((blueprint) => Ref.make(blueprint)),
-            objects: objects.map((object) => Ref.make(object as Obj.Unknown)),
+            blueprints: blueprintRefs,
+            objects: objectRefs,
           }),
         );
 
@@ -151,8 +151,11 @@ export default AgentPrompt.pipe(
           ),
         );
       },
+      Effect.tapBoth({
+        onSuccess: () => Database.flush(),
+        onFailure: () => Database.flush(),
+      }),
       Effect.scoped,
-      Effect.provide(Trace.writerLayerNoop),
     ),
   ),
   Operation.opaqueHandler,
@@ -212,7 +215,7 @@ const ToolExecutionService = ({ feed }: ToolExecutionServiceOptions) =>
             log('invoking operation', { operationDef, input });
             const result = yield* operationInvoker
               .invoke(operationDef, input, {
-                conversation: Obj.getDXN(feed).toString(),
+                conversation: Obj.getURI(feed),
               })
               .pipe(Effect.orDie);
             log('result', { result });

package/src/index.ts

@@ -5,6 +5,7 @@
 export * from './blueprints';
 export * from './crud';
 export * from './functions';
+export * from './supervisor';
 export * from './sync';
 export * from './toolkits';
 export * from './types';

package/src/supervisor/delegation-strategy.ts

@@ -0,0 +1,188 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+
+import { AiContext } from '@dxos/assistant';
+import { Routine } from '@dxos/compute';
+import { ProcessManager } from '@dxos/compute-runtime';
+import { Database, Feed, Filter, Obj, Ref } from '@dxos/echo';
+import { EffectEx } from '@dxos/effect';
+import { type Delegation, type DelegationStrategy } from '@dxos/functions-runtime';
+import { log } from '@dxos/log';
+import { Message } from '@dxos/types';
+import { trim } from '@dxos/util';
+
+import { DelegationBlueprint } from '../blueprints';
+import { AgentPrompt } from '../functions';
+import { Agent } from '../types';
+
+/**
+ * Resolves the agent whose chat is backed by the given conversation feed, if any. Plain (agentless)
+ * chats yield `undefined`, so the strategy is a no-op for them.
+ */
+const findAgentForFeed = (feed: Feed.Feed): Effect.Effect<Agent.Agent | undefined, never, Database.Service> =>
+  Effect.gen(function* () {
+    const agents = yield* Database.query(Filter.type(Agent.Agent)).run;
+    for (const agent of agents) {
+      if (!agent.chat) {
+        continue;
+      }
+      const matches = yield* Effect.gen(function* () {
+        const chat = yield* Database.load(agent.chat!);
+        const chatFeed = yield* Database.load(chat.feed);
+        return chatFeed.id === feed.id;
+      }).pipe(Effect.orElseSucceed(() => false));
+      if (matches) {
+        return agent;
+      }
+    }
+    return undefined;
+  });
+
+/**
+ * Renders a sub-agent result for inclusion in a notification message.
+ */
+const formatResult = (value: unknown): string => (typeof value === 'string' ? value : JSON.stringify(value));
+
+/**
+ * Extracts artifact ids a sub-agent reported in its result (see the synthesized routine
+ * instructions). Tolerates the result being a string, or an object with `artifactIds`/`artifactId`.
+ */
+const extractArtifactIds = (value: unknown): string[] => {
+  if (typeof value !== 'object' || value === null) {
+    return [];
+  }
+
+  const record = value as { artifactIds?: unknown; artifactId?: unknown };
+  const ids = Array.isArray(record.artifactIds)
+    ? record.artifactIds
+    : typeof record.artifactId === 'string'
+      ? [record.artifactId]
+      : [];
+  return ids.filter((id): id is string => typeof id === 'string');
+};
+
+/**
+ * Supervisor behaviour for the conversational agent: after each turn, every in-progress plan task
+ * not already delegated is run by a sub-agent (a synthesized minimal `Routine` executed via
+ * `AgentPrompt`); on completion the task status is updated and a templated message is posted back to
+ * the conversation.
+ */
+export const makeDelegationStrategy = (): DelegationStrategy => ({
+  reconcile: (feed, activeIds) =>
+    Effect.gen(function* () {
+      const agent = yield* findAgentForFeed(feed);
+      if (!agent) {
+        return [];
+      }
+      const plan = yield* Database.load(agent.plan).pipe(Effect.orElseSucceed(() => undefined));
+      if (!plan) {
+        return [];
+      }
+
+      // Only delegated tasks are spawned as sub-agents — a task created via ordinary planning
+      // (`update-tasks`) stays in the plan but is not double-delegated.
+      const pending = plan.tasks.filter(
+        (task) => task.delegated === true && task.status === 'in-progress' && !activeIds.has(task.id),
+      );
+      if (pending.length === 0) {
+        return [];
+      }
+
+      // Sub-agents inherit the supervisor's bound blueprints (so they have the same tools/
+      // capabilities), minus the delegation blueprint itself — otherwise a sub-agent could
+      // recursively delegate. Resolved from the conversation's AiContext bindings.
+      const inheritedBlueprints = yield* Effect.gen(function* () {
+        const runtime = yield* Effect.runtime<Feed.FeedService>();
+        const binder = yield* EffectEx.acquireReleaseResource(() => new AiContext.Binder({ feed, runtime }));
+        return binder.getBlueprints().filter((blueprint) => Obj.getMeta(blueprint).key !== DelegationBlueprint.key);
+      }).pipe(Effect.scoped);
+      const blueprints = inheritedBlueprints.map((blueprint) => Ref.make(blueprint));
+
+      const delegations: Delegation[] = [];
+      for (const task of pending) {
+        // Synthesize a minimal routine whose goal is the task; the sub-agent runs it via AgentPrompt
+        // with the inherited blueprints bound.
+        const routine = yield* Database.add(
+          Routine.make({
+            name: task.title,
+            instructions: trim`
+              Complete the following task and report the result concisely.
+
+              If you create any documents or artifacts, call completeJob with a JSON object of the
+              form { "summary": string, "artifactIds": string[] }, where artifactIds are the exact
+              ids returned by the tools that created them. Otherwise return a short summary string.
+
+              Task: ${task.title}
+            `,
+            blueprints,
+          }),
+        );
+
+        delegations.push({
+          id: task.id,
+          spawn: Effect.gen(function* () {
+            const invoker = yield* ProcessManager.ProcessOperationInvoker.Service;
+            const fiber = yield* invoker.invokeFiber(AgentPrompt, { prompt: Ref.make(routine), input: {} });
+            return fiber.pid;
+          }),
+        });
+      }
+      return delegations;
+    }),
+
+  onComplete: (feed, id, exit) =>
+    Effect.gen(function* () {
+      const agent = yield* findAgentForFeed(feed);
+      const plan = agent ? yield* Database.load(agent.plan).pipe(Effect.orElseSucceed(() => undefined)) : undefined;
+
+      let title = id;
+      if (plan) {
+        Obj.update(plan, (plan) => {
+          const task = plan.tasks.find((task) => task.id === id);
+          if (task) {
+            task.status = Exit.isSuccess(exit) ? 'done' : 'failed';
+            title = task.title;
+          }
+        });
+      }
+
+      // Fold any artifacts the sub-agent produced into the supervisor agent's context, so follow-up
+      // turns can reference them. The sub-agent runs in its own session but in the same space, so
+      // the artifacts resolve by id. Keep the stored refs to embed as inline reference blocks below.
+      const artifactRefs: Ref.Ref<Obj.Unknown>[] = [];
+      if (agent && Exit.isSuccess(exit)) {
+        for (const artifactId of extractArtifactIds(exit.value)) {
+          const ref = yield* Agent.addArtifact(agent, { name: title, id: artifactId }).pipe(
+            Effect.orElseSucceed(() => undefined),
+          );
+          if (ref) {
+            artifactRefs.push(ref);
+          }
+        }
+      }
+
+      // Surface the actual failure cause (not just "failed") so delegation errors are debuggable.
+      const failureCause = Exit.isFailure(exit) ? Cause.pretty(exit.cause) : undefined;
+      if (failureCause) {
+        log.warn('sub-agent failed', { taskId: id, title, cause: failureCause });
+      }
+
+      const text = Exit.isSuccess(exit)
+        ? `The sub-agent completed "${title}".${artifactRefs.length === 0 ? ` ${formatResult(exit.value)}` : ''}`
+        : `The sub-agent failed to complete "${title}": ${failureCause ?? 'unknown error'}`;
+
+      // Embed each produced artifact as a `reference` block — the chat renders these as a dx-anchor
+      // tag with an inline object preview, rather than a raw `echo://` URI in the text.
+      const blocks = [
+        { _tag: 'text' as const, text },
+        ...artifactRefs.map((reference) => ({ _tag: 'reference' as const, reference })),
+      ];
+
+      yield* Feed.append(feed, [Message.make({ sender: 'assistant', blocks })]);
+    }),
+});

package/src/supervisor/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './delegation-strategy';

package/src/sync/sync.ts

@@ -4,9 +4,9 @@
 
 import * as Effect from 'effect/Effect';
 
-import { Filter, Obj, Query, Ref } from '@dxos/echo';
-import { Database } from '@dxos/echo';
+import { Database, Filter, Obj, Query, Ref } from '@dxos/echo';
 import { failedInvariant } from '@dxos/invariant';
+import { EID } from '@dxos/keys';
 import { log } from '@dxos/log';
 
 /**
@@ -39,22 +39,23 @@ export const syncObjects: (
         if (!ref.target) {
           continue;
         }
-        if (Obj.getDXN(ref.target).isLocalObjectId()) {
+        const targetUri = EID.tryParse(Obj.getURI(ref.target));
+        if (targetUri && EID.isLocal(targetUri)) {
           // obj not persisted to db.
           const [target] = yield* syncObjects([ref.target], { foreignKeyId });
           (obj as any)[key] = Ref.make(target);
         }
       }
 
-      const schema = Obj.getSchema(obj) ?? failedInvariant('No schema.');
+      const type = Obj.getType(obj) ?? failedInvariant('No type.');
       const foreignId = Obj.getKeys(obj, foreignKeyId)[0]?.id ?? failedInvariant('No foreign key.');
-      const [existing] = yield* Database.runQuery(
-        Query.select(Filter.foreignKeys(schema, [{ source: foreignKeyId, id: foreignId }])),
-      );
+      const [existing] = yield* Database.query(
+        Query.select(Filter.foreignKeys(type, [{ source: foreignKeyId, id: foreignId }])),
+      ).run;
       log('sync object', {
         type: Obj.getTypename(obj),
         foreignId,
-        existing: existing ? Obj.getDXN(existing) : undefined,
+        existing: existing ? Obj.getURI(existing) : undefined,
       });
       if (!existing) {
         yield* Database.add(obj);