@dxos/assistant-toolkit 0.10.0 → 0.11.1

package/src/supervisor/delegation-strategy.ts

@@ -6,14 +6,15 @@ import * as Cause from 'effect/Cause';
 import * as Effect from 'effect/Effect';
 import * as Exit from 'effect/Exit';
 
+import { type Delegation, type DelegationStrategy } from '@dxos/agent-runtime';
 import { AiContext } from '@dxos/assistant';
 import { Instructions } from '@dxos/compute';
 import { ProcessManager } from '@dxos/compute-runtime';
-import { Database, Feed, Filter, Obj, Ref } from '@dxos/echo';
+import { Database, Feed, Filter, Obj, Query, Ref } from '@dxos/echo';
 import { EffectEx } from '@dxos/effect';
-import { type Delegation, type DelegationStrategy } from '@dxos/functions-runtime';
+import { EID, EntityId } from '@dxos/keys';
 import { log } from '@dxos/log';
-import { Message } from '@dxos/types';
+import { Message, Outline, Task } from '@dxos/types';
 import { trim } from '@dxos/util';
 
 import { RunInstructions } from '../operations';
@@ -39,26 +40,29 @@ const findChatForFeed = (feed: Feed.Feed): Effect.Effect<Chat.Chat | undefined,
   });
 
 /**
- * Resolves the agent whose chat is backed by the given conversation feed, if any. Plain (agentless)
- * chats yield `undefined`, so artifact folding is skipped for them.
+ * Resolves the agent whose chat is backed by the given conversation feed, if any.
+ * Plain (agentless) chats yield `undefined`.
  */
 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;
-      }
+    const chat = yield* findChatForFeed(feed);
+    return chat ? yield* Agent.loadForChat(chat) : undefined;
+  });
+
+/**
+ * Normalizes an LLM-reported artifact reference (bare entity id or full ECHO URI) to a
+ * fully-qualified ref in the current space. Not resolved here — it resolves lazily when read.
+ */
+const resolveArtifactRef = (id: string): Effect.Effect<Ref.Ref<Obj.Unknown>, Error, Database.Service> =>
+  Effect.gen(function* () {
+    const parsed = EID.tryParse(id);
+    const candidate = (parsed ? EID.getEntityId(parsed) : undefined) ?? id;
+    if (!EntityId.isValid(candidate)) {
+      // Malformed LLM-reported id: fail so the caller's `orElseSucceed` drops it.
+      return yield* Effect.fail(new Error(`Invalid artifact id: ${id}`));
     }
-    return undefined;
+    const { db } = yield* Database.Service;
+    return db.makeRef<Obj.Unknown>(EID.make({ spaceId: db.spaceId, entityId: candidate }));
   });
 
 /**
@@ -85,10 +89,42 @@ const extractArtifactIds = (value: unknown): 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
- * `RunInstructions`); on completion the task status is updated and a templated message is posted back to
- * the conversation.
+ * The durable agent tasks awaiting a sub-agent for this conversation: in-progress children of the
+ * working outline's task set whose assignee is an agent. Ordinary checklist items (markdown) are
+ * never spawned — delegation happens only through the promotion the delegate-task tool performs.
+ */
+const findPendingTasks = (
+  chat: Chat.Chat,
+  activeIds: ReadonlySet<string>,
+): Effect.Effect<Task.Task[], never, Database.Service> =>
+  Effect.gen(function* () {
+    const outlineRef = Chat.peekOutlineRef(chat);
+    const outline = outlineRef
+      ? yield* Database.load(outlineRef).pipe(Effect.orElseSucceed(() => undefined))
+      : undefined;
+    const taskSet = outline?.taskSet
+      ? yield* Database.load(outline.taskSet).pipe(Effect.orElseSucceed(() => undefined))
+      : undefined;
+    if (!taskSet) {
+      return [];
+    }
+    const children = yield* Database.query(Query.select(Filter.id(taskSet.id)).children()).run.pipe(
+      Effect.orElseSucceed(() => []),
+    );
+    return children.filter(
+      (child): child is Task.Task =>
+        Obj.instanceOf(Task.Task, child) &&
+        child.assignee?.role === 'assistant' &&
+        child.status === 'in-progress' &&
+        !activeIds.has(child.id),
+    );
+  });
+
+/**
+ * Supervisor behaviour for the conversational agent: after each turn, every in-progress agent
+ * task not already running is run by a sub-agent (a synthesized minimal `Routine` executed via
+ * `RunInstructions`); on completion the task status is updated, the checklist line is checked
+ * off, and a templated message is posted back to the conversation.
  */
 export const makeDelegationStrategy = (): DelegationStrategy => ({
   reconcile: (feed, activeIds) =>
@@ -97,16 +133,8 @@ export const makeDelegationStrategy = (): DelegationStrategy => ({
       if (!chat) {
         return [];
       }
-      const plan = chat.plan ? yield* Database.load(chat.plan).pipe(Effect.orElseSucceed(() => undefined)) : 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),
-      );
+      const pending = yield* findPendingTasks(chat, activeIds);
       if (pending.length === 0) {
         return [];
       }
@@ -145,18 +173,13 @@ export const makeDelegationStrategy = (): DelegationStrategy => ({
           id: task.id,
           spawn: Effect.gen(function* () {
             const invoker = yield* ProcessManager.ProcessOperationInvoker.Service;
+            // The task ↔ process mapping lives runtime-side (the supervisor's activeIds keyed by
+            // task id) — nothing is stamped on the durable task.
             const fiber = yield* invoker.invokeFiber(RunInstructions, {
               instructions: Ref.make(instructions),
               input: {},
             });
-            const pid = fiber.pid;
-            Obj.update(plan, (plan) => {
-              const taskRecord = plan.tasks.find((taskRecord) => taskRecord.id === task.id);
-              if (taskRecord) {
-                taskRecord.agentPid = pid;
-              }
-            });
-            return pid;
+            return fiber.pid;
           }),
         });
       }
@@ -166,30 +189,43 @@ export const makeDelegationStrategy = (): DelegationStrategy => ({
   onComplete: (feed, id, exit) =>
     Effect.gen(function* () {
       const chat = yield* findChatForFeed(feed);
-      const agent = yield* findAgentForFeed(feed);
-      const plan =
-        chat?.plan != null ? yield* Database.load(chat.plan).pipe(Effect.orElseSucceed(() => undefined)) : undefined;
+      // Reuse the chat just resolved rather than re-scanning every chat for the same feed.
+      const agent = chat ? yield* Agent.loadForChat(chat) : undefined;
 
+      // Resolve the durable task by its id and record the outcome; on success the checklist line
+      // is checked off so the markdown mirror follows the durable state.
       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;
-          }
+      const tasks = yield* Database.query(Query.select(Filter.id(id))).run.pipe(Effect.orElseSucceed(() => []));
+      const task = tasks.find((candidate): candidate is Task.Task => Obj.instanceOf(Task.Task, candidate));
+      if (task) {
+        Obj.update(task, (task) => {
+          task.status = Exit.isSuccess(exit) ? 'done' : 'failed';
         });
+        title = task.title;
+
+        if (chat && Exit.isSuccess(exit)) {
+          const outlineRef = Chat.peekOutlineRef(chat);
+          const outline = outlineRef
+            ? yield* Database.load(outlineRef).pipe(Effect.orElseSucceed(() => undefined))
+            : undefined;
+          const text = outline
+            ? yield* Database.load(outline.content).pipe(Effect.orElseSucceed(() => undefined))
+            : undefined;
+          if (text) {
+            Obj.update(text, (text) => {
+              text.content = Outline.upsertChecklistItems(text.content, [{ title: task.title, done: true }]);
+            });
+          }
+        }
       }
 
-      // 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.
+      // Surface any artifacts the sub-agent produced as inline reference blocks in the notification
+      // message, so follow-up turns can reference them (durable filing belongs to the project's
+      // collection — the agent stores no artifacts).
       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),
-          );
+          const ref = yield* resolveArtifactRef(artifactId).pipe(Effect.orElseSucceed(() => undefined));
           if (ref) {
             artifactRefs.push(ref);
           }

package/src/sync/sync.test.ts

@@ -0,0 +1,95 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { AssistantTestLayer } from '@dxos/agent-runtime/testing';
+import { Database, Filter, Obj, Query } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { EntityId } from '@dxos/keys';
+import { Text } from '@dxos/schema';
+
+import { syncObjects } from './sync';
+
+EntityId.dangerouslyDisableRandomness();
+
+const TestLayer = AssistantTestLayer({ types: [Text.Text], disableLlmMemoization: true });
+
+const SOURCE = 'test.source';
+
+/** Detached object carrying the foreign key `syncObjects` matches on. */
+const makeIncoming = (id: string, content: string) => {
+  const obj = Obj.make(Text.Text, { content });
+  Obj.update(obj, (obj) => {
+    Obj.getMeta(obj).keys.push({ source: SOURCE, id });
+  });
+  return obj;
+};
+
+describe('syncObjects', () => {
+  it.effect(
+    'adds an object with no foreign-key match',
+    Effect.fnUntraced(
+      function* (_) {
+        const [synced] = yield* syncObjects([makeIncoming('a', 'first')], { foreignKeyId: SOURCE });
+        yield* Database.flush();
+
+        const all = yield* Database.query(Filter.type(Text.Text)).run;
+        expect(all).toHaveLength(1);
+        expect(all[0].id).toBe(synced.id);
+        expect(Obj.getKeys(synced, SOURCE)).toEqual([{ source: SOURCE, id: 'a' }]);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'updates the matching object in place rather than adding a second',
+    Effect.fnUntraced(
+      function* (_) {
+        const [first] = yield* syncObjects([makeIncoming('a', 'first')], { foreignKeyId: SOURCE });
+        yield* Database.flush();
+
+        const [second] = yield* syncObjects([makeIncoming('a', 'updated')], { foreignKeyId: SOURCE });
+        yield* Database.flush();
+
+        expect(second.id).toBe(first.id);
+
+        // Queried rather than read off the returned `Obj.Unknown`, which would need a cast.
+        const all = yield* Database.query(Query.select(Filter.type(Text.Text))).run;
+        expect(all).toHaveLength(1);
+        expect(all[0].content).toBe('updated');
+
+        // The foreign key survives the copy: it is read off a detached object, so it reaches the
+        // persisted object only because assignment copies nested records by value.
+        expect(Obj.getKeys(second, SOURCE)).toEqual([{ source: SOURCE, id: 'a' }]);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'replaces keys from the same source, leaving other sources intact',
+    Effect.fnUntraced(
+      function* (_) {
+        const [existing] = yield* syncObjects([makeIncoming('a', 'first')], { foreignKeyId: SOURCE });
+        Obj.update(existing, (existing) => {
+          Obj.getMeta(existing).keys.push({ source: 'other', id: 'keep-me' });
+        });
+        yield* Database.flush();
+
+        yield* syncObjects([makeIncoming('a', 'updated')], { foreignKeyId: SOURCE });
+        yield* Database.flush();
+
+        expect(Obj.getKeys(existing, SOURCE)).toEqual([{ source: SOURCE, id: 'a' }]);
+        expect(Obj.getKeys(existing, 'other')).toEqual([{ source: 'other', id: 'keep-me' }]);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/sync/sync.ts

@@ -84,6 +84,7 @@ const copyObjectData = (existing: Obj.Unknown, newObj: Obj.Unknown) => {
       ) {
         continue;
       }
+
       (existing as any)[key] = (newObj as any)[key];
     }
 
@@ -92,16 +93,17 @@ const copyObjectData = (existing: Obj.Unknown, newObj: Obj.Unknown) => {
       if (typeof key !== 'string' || key === 'id') {
         continue;
       }
+
       if (!(key in newObj)) {
         delete (existing as any)[key];
       }
     }
 
-    // Update foreign keys.
+    // Update foreign keys. The push copies by value, so `existing` does not share mutable state
+    // with `newObj`.
     for (const foreignKey of Obj.getMeta(newObj).keys) {
       Obj.deleteKeys(existing, foreignKey.source);
-      // TODO(dmaretskyi): Doesn't work: `Obj.getMeta(existing).keys.push(foreignKey);`
-      Obj.getMeta(existing).keys.push({ ...foreignKey });
+      Obj.getMeta(existing).keys.push(foreignKey);
     }
   });
 };

package/src/testing/index.ts

@@ -3,4 +3,5 @@
 //
 
 export * from '../skills/testing';
+export * from './operations';
 export * from './plugins';

package/src/testing/operations.ts

@@ -0,0 +1,65 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { AssistantTestLayerWithTriggers } from '@dxos/agent-runtime/testing';
+import { AiContext } from '@dxos/assistant';
+import { SpaceProperties } from '@dxos/client-protocol';
+import { Instructions, OperationHandlerSet, Routine, Skill, Trigger } from '@dxos/compute';
+import { Collection, Feed, Tag } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { Employer, Organization, Outline, Person, Task, TaskSet } from '@dxos/types';
+
+import { AgentHandlers } from '../operations';
+import { AgentWizardHandlers } from '../skills/agent-wizard/operations';
+import { AgentSkillHandlers } from '../skills/agent/operations';
+import { AlarmHandlers } from '../skills/alarm/operations';
+import { DatabaseHandlers } from '../skills/database/operations';
+import { DelegationHandlers } from '../skills/delegation/operations';
+import { MemoryHandlers } from '../skills/memory/operations';
+import { PlanningHandlers } from '../skills/planning/operations';
+import { SkillManagerHandlers } from '../skills/skill-manager/operations';
+import { Agent, Chat } from '../types';
+import { Memory } from '../types/Memory';
+
+/**
+ * Shared layer for operation tests: every handler in the package plus the types those handlers
+ * touch, with no language model. Defined once so a `.test.ts` per handler does not restate it —
+ * handler sets are lazy, so registering all of them costs nothing until one is invoked.
+ */
+export const OperationTestLayer = AssistantTestLayerWithTriggers({
+  operationHandlers: OperationHandlerSet.merge(
+    AgentHandlers,
+    AgentSkillHandlers,
+    AgentWizardHandlers,
+    AlarmHandlers,
+    DatabaseHandlers,
+    DelegationHandlers,
+    MemoryHandlers,
+    PlanningHandlers,
+    SkillManagerHandlers,
+  ),
+  types: [
+    Agent.Agent,
+    AiContext.Binding,
+    Chat.Chat,
+    Chat.CompanionTo,
+    Collection.Collection,
+    Employer.Employer,
+    Feed.Feed,
+    Instructions.Instructions,
+    Memory,
+    Organization.Organization,
+    Person.Person,
+    Outline.Outline,
+    Routine.Routine,
+    Task.Task,
+    TaskSet.TaskSet,
+    Skill.Skill,
+    SpaceProperties,
+    Tag.Tag,
+    Text.Text,
+    Trigger.Trigger,
+  ],
+  disableLlmMemoization: true,
+});

package/src/types/Agent.test.ts

@@ -5,86 +5,56 @@
 import { describe, it } from '@effect/vitest';
 import * as Effect from 'effect/Effect';
 
-import { Skill } from '@dxos/compute';
-import { Database, Feed, Obj } from '@dxos/echo';
+import { AssistantTestLayer } from '@dxos/agent-runtime/testing';
+import { Instructions, Skill } from '@dxos/compute';
+import { Database, Feed, Obj, Type } 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 { Outline } from '@dxos/types';
 
-import { Agent, Chat, Plan } from '../types';
+import { Agent, Chat } from '../types';
 
 EntityId.dangerouslyDisableRandomness();
 
 const TestLayer = AssistantTestLayer({
-  types: [Agent.Agent, Plan.Plan, Chat.Chat, Chat.CompanionTo, Skill.Skill, Feed.Feed, Text.Text],
+  types: [
+    Agent.Agent,
+    Outline.Outline,
+    Chat.Chat,
+    Chat.CompanionTo,
+    Skill.Skill,
+    Feed.Feed,
+    Text.Text,
+    Instructions.Instructions,
+  ],
   disableLlmMemoization: true,
 });
 
-const makeAgent = Effect.fnUntraced(function* () {
-  return yield* Agent.makeInitialized(
-    { name: 'Test', instructions: '' },
-    Skill.make({ key: 'org.dxos.test.skill', name: 'Test' }),
-  );
-});
-
-describe('Agent.addArtifact', () => {
-  // The id forms a tool may hand back: a bare entity id, or a fully-qualified ECHO URI. LLMs commonly
-  // strip a returned URI down to the bare id, so both must resolve.
-  it.scoped(
-    'adds a freshly-created object by bare entity id',
-    Effect.fnUntraced(
-      function* ({ expect }) {
-        const agent = yield* makeAgent();
-        const doc = yield* Database.add(Text.make({ content: 'hello' }));
-
-        yield* Agent.addArtifact(agent, { name: 'Doc', id: doc.id });
-
-        expect(agent.artifacts).toHaveLength(1);
-        expect(agent.artifacts[0]!.name).toBe('Doc');
-        const loaded = yield* Database.load(agent.artifacts[0]!.data);
-        expect(loaded.id).toBe(doc.id);
-      },
-      Effect.provide(TestLayer),
-      TestHelpers.provideTestContext,
-    ),
-  );
-
+describe('Agent (0.2.0)', () => {
   it.scoped(
-    'adds an object by fully-qualified ECHO URI',
+    'makeInitialized creates the identity/preset shape',
     Effect.fnUntraced(
       function* ({ expect }) {
-        const agent = yield* makeAgent();
-        const doc = yield* Database.add(Text.make({ content: 'world' }));
-
-        yield* Agent.addArtifact(agent, { name: 'Doc', id: Obj.getURI(doc) });
-
-        expect(agent.artifacts).toHaveLength(1);
-        const loaded = yield* Database.load(agent.artifacts[0]!.data);
-        expect(loaded.id).toBe(doc.id);
-      },
-      Effect.provide(TestLayer),
-      TestHelpers.provideTestContext,
-    ),
-  );
-
-  // Best-effort: the reference is stored without resolving (the artifact may be created by a separate
-  // invocation and not yet visible); resolution happens lazily when the artifact is later read.
-  it.scoped(
-    'stores a reference without resolving it (resolves lazily)',
-    Effect.fnUntraced(
-      function* ({ expect }) {
-        const agent = yield* makeAgent();
-        const doc = yield* Database.add(Text.make({ content: 'later' }));
-        const bareId = doc.id;
-
-        // Add by bare id; the helper must not require the artifact to be resolvable at add time.
-        yield* Agent.addArtifact(agent, { name: 'Doc', id: bareId });
-        expect(agent.artifacts).toHaveLength(1);
-
-        // The stored ref still resolves to the object.
-        const loaded = yield* Database.load(agent.artifacts[0]!.data);
-        expect(loaded.id).toBe(doc.id);
+        const agent = yield* Agent.makeInitialized(
+          { name: 'Test', instructions: 'Do the thing.' },
+          Skill.make({ key: 'org.dxos.test.skill', name: 'Test' }),
+        );
+        yield* Database.flush();
+
+        expect(Type.getVersion(Agent.Agent)).toBe('0.2.0');
+        const { text, instructions } = yield* Agent.loadInstructions(agent);
+        expect(text).toBe('Do the thing.');
+        expect(Obj.getParent(instructions)).toBe(agent);
+
+        // The relation carries the linkage in both directions; the agent owns no conversation state.
+        const chat = yield* Agent.loadChat(agent);
+        expect(chat).toBeDefined();
+        expect(chat?.instructions?.uri).toBe(agent.instructions.uri);
+
+        // Compare by id: the two query paths may resolve distinct proxy instances.
+        const linkedAgent = chat ? yield* Agent.loadForChat(chat) : undefined;
+        expect(linkedAgent?.id).toBe(agent.id);
       },
       Effect.provide(TestLayer),
       TestHelpers.provideTestContext,