@dxos/assistant-toolkit 0.10.0 → 0.11.1

package/src/skills/planning/operations/update-tasks.ts

@@ -6,44 +6,36 @@ import * as Effect from 'effect/Effect';
 
 import { Operation } from '@dxos/compute';
 import { Obj } from '@dxos/echo';
+import { Outline } from '@dxos/types';
 import { trim } from '@dxos/util';
 
-import { Chat, Plan } from '../../../types';
+import { Chat } from '../../../types';
 import { UpdateTasks } from './definitions';
 
 /**
- * Updates the planning document (Chat.plan) with the given tasks.
+ * Upserts checklist items into the conversation's working outline (markdown `- [ ]` lines,
+ * matched by title). The outline is the cheap, fluid form of work — durable Task objects are
+ * created by promotion/delegation, not here.
  */
 export default UpdateTasks.pipe(
   Operation.withHandler(
-    Effect.fnUntraced(function* ({ tasks: newTasks }) {
+    Effect.fnUntraced(function* ({ tasks }) {
       const chat = yield* Chat.getFromContext;
-      // TODO(burdon): How to specify requirements/preconditions before calling?
-      // TODO(burdon): How to report non-technical error?
-      const plan = yield* Chat.ensurePlan(chat);
+      const { text } = yield* Chat.ensureOutlineText(chat);
 
-      Obj.update(plan, (plan) => {
-        for (const task of newTasks) {
-          const existingTask = plan.tasks.find((t) => t.id === task.id);
-          if (existingTask) {
-            existingTask.title = task.title;
-            existingTask.status = task.status;
-          } else {
-            plan.tasks.push({
-              id: task.id,
-              title: task.title,
-              status: task.status,
-            });
-          }
-        }
+      Obj.update(text, (text) => {
+        text.content = Outline.upsertChecklistItems(
+          text.content,
+          tasks.map(({ title, status }) => ({ title, done: status === 'done' })),
+        );
       });
 
       return trim`
-        You must update the task status to 'in-progress' when you start and 'done' when complete.
-        Current plan updated:
-        <plan>
-          ${Plan.formatPlan(plan)}
-        </plan>
+        You must update a task to 'done' when complete, and keep exactly one task in progress.
+        Current checklist:
+        <checklist>
+          ${text.content}
+        </checklist>
       `;
     }),
   ),

package/src/skills/project/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { default as ProjectSkill } from './skill';
+export { ProjectHandlers, ProjectOperations } from './operations';

package/src/skills/project/operations/artifact-add.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Collection, Database, Obj, Ref } from '@dxos/echo';
+import { EID } from '@dxos/keys';
+
+import { ArtifactAdd } from './definitions';
+
+/** Compare refs by entity id when possible — space-qualified and local URIs may name the same object. */
+const refKey = (ref: Ref.Ref<Obj.Unknown>): string => {
+  const eid = EID.tryParse(ref.uri);
+  return (eid && EID.getEntityId(eid)) ?? ref.uri;
+};
+
+const handler: Operation.WithHandler<typeof ArtifactAdd> = ArtifactAdd.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ project: projectRef, object: objectRef }) {
+      const project = yield* Database.load(projectRef);
+
+      // Projects normally own an artifacts collection from creation; materialize one for those that don't.
+      let collection: Collection.Collection;
+      if (project.artifacts) {
+        collection = yield* Database.load(project.artifacts);
+      } else {
+        collection = yield* Database.add(Collection.make());
+        Obj.setParent(collection, project);
+        Obj.update(project, (project) => {
+          project.artifacts = Ref.make(collection);
+        });
+      }
+
+      if (!collection.objects.some((ref) => refKey(ref) === refKey(objectRef))) {
+        Obj.update(collection, (collection) => {
+          collection.objects.push(objectRef);
+        });
+      }
+
+      yield* Database.flush();
+    }),
+  ),
+);
+
+export default handler;

package/src/skills/project/operations/artifact-list.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+import { Database, Obj } from '@dxos/echo';
+
+import { ArtifactList } from './definitions';
+
+const handler: Operation.WithHandler<typeof ArtifactList> = ArtifactList.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ project: projectRef }) {
+      const project = yield* Database.load(projectRef);
+      if (!project.artifacts) {
+        return { artifacts: [] };
+      }
+
+      const collection = yield* Database.load(project.artifacts);
+      const artifacts = yield* Effect.forEach(collection.objects, (ref) =>
+        Database.load(ref).pipe(
+          Effect.map((object) => ({
+            dxn: Obj.getURI(object),
+            typename: Obj.getTypename(object),
+            label: Obj.getLabel(object),
+          })),
+          // A broken ref yields a placeholder row rather than failing the whole listing; other
+          // load failures (transport, decoding) still propagate.
+          Effect.catchTag('EntityNotFoundError', () =>
+            Effect.succeed({ dxn: ref.uri, typename: undefined, label: undefined }),
+          ),
+        ),
+      );
+
+      return { artifacts };
+    }),
+  ),
+);
+
+export default handler;

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

@@ -0,0 +1,63 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Operation, Project } from '@dxos/compute';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { DXN } from '@dxos/keys';
+import { trim } from '@dxos/util';
+
+export const ArtifactAdd = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.function.project.artifactAdd'),
+    name: 'Add project artifact',
+    icon: 'ph--stack-plus--regular',
+    description: trim`
+      Files an object into a project's artifacts collection.
+      Use this after creating an object (document, outline, sheet, contact, …) while working in a
+      project's context, so the project owns it and it appears in the project's artifacts list.
+      Adding the same object twice is a no-op.
+    `,
+  },
+  input: Schema.Struct({
+    project: Ref.Ref(Project.Project).annotations({
+      description: 'The project to file into (its reference is in the chat context).',
+    }),
+    object: Ref.Ref(Obj.Unknown).annotations({
+      description: 'The object to file as an artifact.',
+    }),
+  }),
+  output: Schema.Void,
+  services: [Database.Service],
+});
+
+/** One artifact row: enough to identify and load the object, without inlining its content. */
+export const ArtifactInfo = Schema.Struct({
+  dxn: Schema.String,
+  typename: Schema.optional(Schema.String),
+  label: Schema.optional(Schema.String),
+});
+
+export const ArtifactList = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.function.project.artifactList'),
+    name: 'List project artifacts',
+    icon: 'ph--stack--regular',
+    description: trim`
+      Lists the objects in a project's artifacts collection (DXN, type, and label per artifact).
+      Use this to find what the project already holds before searching the whole space; load an
+      artifact's content with the load tool when needed.
+    `,
+  },
+  input: Schema.Struct({
+    project: Ref.Ref(Project.Project).annotations({
+      description: 'The project whose artifacts to list (its reference is in the chat context).',
+    }),
+  }),
+  output: Schema.Struct({
+    artifacts: Schema.Array(ArtifactInfo),
+  }),
+  services: [Database.Service],
+});

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

@@ -0,0 +1,12 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export * as ProjectOperations from './definitions';
+
+export const ProjectHandlers = OperationHandlerSet.lazy(
+  () => import('./artifact-add'),
+  () => import('./artifact-list'),
+);

package/src/skills/project/skill.test.ts

@@ -0,0 +1,78 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Instructions, Project } from '@dxos/compute';
+import { Collection, Database, Obj, Ref } from '@dxos/echo';
+import { TestDatabaseLayer } from '@dxos/echo-client/testing';
+import { Text } from '@dxos/schema';
+
+import artifactAdd from './operations/artifact-add';
+import artifactList from './operations/artifact-list';
+
+const testLayer = () =>
+  TestDatabaseLayer({
+    types: [Project.Project, Instructions.Instructions, Collection.Collection, Text.Text],
+  });
+
+describe('project skill operations', () => {
+  it.effect('artifact-add files into the project collection; adding twice is a no-op', () =>
+    Effect.gen(function* () {
+      const collection = yield* Database.add(Collection.make());
+      const project = yield* Database.add(Project.make({ name: 'Voyage', artifacts: Ref.make(collection) }));
+      const doc = yield* Database.add(Text.make({ content: 'notes' }));
+      yield* Database.flush();
+
+      yield* artifactAdd.handler({ project: Ref.make(project), object: Ref.make(doc) });
+      expect(collection.objects).toHaveLength(1);
+
+      yield* artifactAdd.handler({ project: Ref.make(project), object: Ref.make(doc) });
+      expect(collection.objects).toHaveLength(1);
+    }).pipe(Effect.provide(testLayer())),
+  );
+
+  it.effect('artifact-add materializes a collection for a project without one', () =>
+    Effect.gen(function* () {
+      const project = yield* Database.add(Project.make({ name: 'Bare' }));
+      const doc = yield* Database.add(Text.make({ content: 'notes' }));
+      yield* Database.flush();
+
+      yield* artifactAdd.handler({ project: Ref.make(project), object: Ref.make(doc) });
+      const artifactsRef = project.artifacts;
+      expect(artifactsRef).toBeDefined();
+      if (!artifactsRef) {
+        throw new Error('unreachable');
+      }
+      const collection = yield* Database.load(artifactsRef);
+      expect(collection.objects).toHaveLength(1);
+    }).pipe(Effect.provide(testLayer())),
+  );
+
+  it.effect('artifact-list returns dxn, typename, and label per artifact', () =>
+    Effect.gen(function* () {
+      const doc = yield* Database.add(Text.make({ content: 'notes' }));
+      const collection = yield* Database.add(Collection.make({ objects: [Ref.make(doc)] }));
+      const project = yield* Database.add(Project.make({ name: 'Voyage', artifacts: Ref.make(collection) }));
+      yield* Database.flush();
+
+      const { artifacts } = yield* artifactList.handler({ project: Ref.make(project) });
+      expect(artifacts).toHaveLength(1);
+      expect(artifacts[0].dxn).toBe(Obj.getURI(doc));
+      expect(artifacts[0].typename).toBe('org.dxos.type.text');
+      expect(artifacts[0].label).toBe(Obj.getLabel(doc));
+    }).pipe(Effect.provide(testLayer())),
+  );
+
+  it.effect('artifact-list is empty for a project without a collection', () =>
+    Effect.gen(function* () {
+      const project = yield* Database.add(Project.make({ name: 'Bare' }));
+      yield* Database.flush();
+
+      const { artifacts } = yield* artifactList.handler({ project: Ref.make(project) });
+      expect(artifacts).toEqual([]);
+    }).pipe(Effect.provide(testLayer())),
+  );
+});

package/src/skills/project/skill.ts

@@ -0,0 +1,42 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Skill } from '@dxos/compute';
+import { Ref } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+import { ArtifactAdd, ArtifactList } from './operations/definitions';
+
+const SKILL_KEY = 'org.dxos.skill.project';
+
+const instructions = trim`
+  You are working in the context of a project (its reference is bound into this chat).
+  The project owns a collection of artifacts: the durable work products of this project.
+  When you create an object the user asked for (a document, outline, sheet, contact, …), file it
+  into the project's artifacts with the add-artifact tool so the project owns it.
+  When looking for the project's existing material, list its artifacts first rather than searching
+  the whole space.
+`;
+
+const make = () =>
+  Skill.make({
+    key: SKILL_KEY,
+    name: 'Project',
+    description: "Manage a project's artifacts: file created objects and find existing ones.",
+    agentCanEnable: true,
+    instructions: {
+      source: Ref.make(Text.make({ content: instructions })),
+    },
+    tools: Skill.toolDefinitions({
+      operations: [ArtifactAdd, ArtifactList],
+    }),
+  });
+
+const skill: Skill.Definition = {
+  key: SKILL_KEY,
+  make,
+};
+
+export default skill;

package/src/skills/skill-manager/operations/definitions.ts

@@ -26,7 +26,7 @@ export const EnableSkills = Operation.make({
     key: DXN.make('org.dxos.function.skillManager.enableSkills'),
     name: 'Enable skills',
     description:
-      'Enables skills in the current conversation by their keys. Only skills with agentCanEnable=true can be enabled. Always call [query-skills] first to discover available skill keys.',
+      'Enables skills in the current conversation by their keys. Only skills with agentCanEnable=true can be enabled. The available keys are already listed in the system prompt, so call this directly rather than querying first.',
     icon: 'ph--plugs-connected--regular',
   },
   input: Schema.Struct({

package/src/skills/skill-manager/skill.test.ts

@@ -7,12 +7,12 @@ import * as Context from 'effect/Context';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
 
+import { AssistantTestLayer } from '@dxos/agent-runtime/testing';
 import { AiContext, Harness } from '@dxos/assistant';
 import { Operation, Skill } from '@dxos/compute';
 import { Database, Feed, Obj } from '@dxos/echo';
 import { EffectEx } from '@dxos/effect';
 import { TestHelpers } from '@dxos/effect/testing';
-import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
 import { EntityId, type URI } from '@dxos/keys';
 
 import { DatabaseSkill, DiscordSkill, MemorySkill } from '../index';

package/src/skills/skill-manager/skill.ts

@@ -17,10 +17,10 @@ const make = () =>
     description: 'Query and enable skills in the current conversation.',
     instructions: Template.make({
       source: trim`
-        You can query available skills and enable them in the current conversation.
-        Use [query-skills] to refresh the list of available skills.
-        Use [enable-skills] to enable skills by their keys. Always call [query-skills] first.
-        Only skills with agentCanEnable=true can be enabled by the agent.
+        The list below is the current set of available skills — it is rendered fresh into this prompt,
+        so do NOT call [query-skills] to obtain it. Call [enable-skills] directly with the keys you
+        need; only skills marked [agent-can-enable] can be enabled by the agent.
+        Reach for [query-skills] only to re-read the list after something has changed it.
 
         <available_skills>
         {{#each skills}}
@@ -28,7 +28,9 @@ const make = () =>
         {{/each}}
         </available_skills>
 
-        NOTE: You must enable the skill to use it, only then the tools from that skill will appear.
+        NOTE: A skill's tools only appear once it is enabled. Skills already enabled in this
+        conversation expose their tools to you directly — do not re-enable a skill whose tools you
+        can already see.
       `,
       inputs: [
         {

package/src/skills/websearch/skill.test.ts

@@ -5,9 +5,9 @@
 import { describe, it } from '@effect/vitest';
 import * as Effect from 'effect/Effect';
 
+import { AgentService } from '@dxos/agent-runtime';
+import { AssistantTestLayer } from '@dxos/agent-runtime/testing';
 import { TestHelpers } from '@dxos/effect/testing';
-import { AgentService } from '@dxos/functions-runtime';
-import { AssistantTestLayer } from '@dxos/functions-runtime/testing';
 
 import { WebSearchHandlers } from './operations';
 import WebSearchSkill from './skill';

package/src/supervisor/delegation-strategy.test.ts

@@ -0,0 +1,129 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { AssistantTestLayer, collectEphemeral, messageTextIncludes, waitForMessage } from '@dxos/agent-runtime/testing';
+import { ScriptedLanguageModel } from '@dxos/ai/testing';
+import { AiContext } from '@dxos/assistant';
+import { getSession } from '@dxos/compute/AgentService';
+import { Database, Filter, Obj, Query } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { invariant } from '@dxos/invariant';
+import { EntityId } from '@dxos/keys';
+import { Text } from '@dxos/schema';
+import { Message, Outline, Task, TaskSet } from '@dxos/types';
+
+import { AgentHandlers } from '../operations';
+import { DelegationHandlers, DelegationSkill } from '../skills';
+import { Agent, Chat } from '../types';
+import { makeDelegationStrategy } from './delegation-strategy';
+
+const { text, toolCall, promptIncludes, scriptedAiService } = ScriptedLanguageModel;
+
+EntityId.dangerouslyDisableRandomness();
+
+const TASK_TITLE = 'Compute 10 factorial';
+
+// Two cooperating sessions share one scripted service: the sub-agent's `RunInstructions` system
+// prompt is the discriminator (only sub-agents run in "non-interactive mode"); the supervisor is
+// the fallback route. Each route consumes its own cursor, so supervisor turns are unaffected by
+// when the sub-agent runs.
+const TestLayer = AssistantTestLayer({
+  agent: { delegationStrategy: makeDelegationStrategy() },
+  aiService: scriptedAiService([
+    {
+      name: 'sub-agent',
+      match: promptIncludes('non-interactive mode'),
+      turns: [{ parts: [toolCall('completeJob', { success: '3628800' })] }, { parts: [text('Done.')] }],
+    },
+    {
+      name: 'supervisor',
+      match: () => true,
+      turns: [
+        // Immediate reply + delegation in one turn: the user sees the reply while the work runs.
+        {
+          parts: [text('On it — delegating.'), toolCall('delegate-task', { title: TASK_TITLE })],
+        },
+        {
+          parts: [text('Delegated. I will report back when it completes.')],
+        },
+      ],
+    },
+  ]),
+  operationHandlers: [DelegationHandlers, AgentHandlers],
+  skills: [DelegationSkill.make()],
+  types: [
+    Agent.Agent,
+    Outline.Outline,
+    Task.Task,
+    TaskSet.TaskSet,
+    Chat.Chat,
+    Chat.CompanionTo,
+    AiContext.Binding,
+    Text.Text,
+    Message.Message,
+  ],
+});
+
+describe('makeDelegationStrategy', () => {
+  it.scoped(
+    'replies immediately, delegates to a sub-agent, and folds the result back',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        const agent = yield* Agent.makeInitialized(
+          {
+            name: 'Supervisor',
+            instructions: 'You delegate units of work to sub-agents using the available tools.',
+          },
+          DelegationSkill.make(),
+        );
+        yield* Database.flush();
+
+        const chat = yield* Agent.loadChat(agent);
+        invariant(chat, 'Agent chat not found.');
+        const feed = yield* Database.load(chat.feed);
+
+        const session = yield* getSession(feed);
+        const ephemeral = yield* collectEphemeral(session);
+
+        yield* session.submitPrompt('Delegate a task to a sub-agent to compute 10 factorial.');
+        // Settles on the turn's reply; the delegated child runs in the background.
+        yield* session.waitForCompletion();
+
+        // The immediate reply streamed before the sub-agent produced anything.
+        const streamedText = ephemeral
+          .partialBlocks()
+          .map(({ block }) => (block._tag === 'text' ? block.text : ''))
+          .join('');
+        expect(streamedText).toContain('On it');
+
+        // DelegateTask promoted the work to a durable agent task under the outline's task set.
+        const outlineAfterTurn = chat.outline ? yield* Database.load(chat.outline) : undefined;
+        invariant(outlineAfterTurn, 'Outline not created.');
+        const taskSet = outlineAfterTurn.taskSet ? yield* Database.load(outlineAfterTurn.taskSet) : undefined;
+        invariant(taskSet, 'Task set not created.');
+        const children = yield* Database.query(Query.select(Filter.id(taskSet.id)).children()).run;
+        const tasks = children.filter((child): child is Task.Task => Obj.instanceOf(Task.Task, child));
+        expect(tasks).toHaveLength(1);
+        expect(tasks[0]).toMatchObject({ title: TASK_TITLE, assignee: { role: 'assistant' } });
+
+        // The post-turn reconcile spawned the sub-agent; its exit drives onComplete, which posts
+        // the fold-back message to the conversation feed out of band.
+        const notification = yield* waitForMessage(feed, messageTextIncludes('The sub-agent completed'));
+        expect(Message.extractText(notification)).toContain(TASK_TITLE);
+        expect(Message.extractText(notification)).toContain('3628800');
+
+        // ...marked the durable task done and checked off the checklist line.
+        expect(tasks[0].status).toEqual('done');
+        const outlineText = yield* Database.load(outlineAfterTurn.content);
+        expect(Outline.parseChecklist(outlineText.content)).toEqual([{ title: TASK_TITLE, done: true }]);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 30_000 },
+  );
+});