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

package/src/testing/plugins.tsx

@@ -7,20 +7,15 @@ import React from 'react';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
 import { Surface } from '@dxos/app-framework/ui';
-import { Format, type Obj, Type } from '@dxos/echo';
+import { DXN, Format, type Obj, Type } from '@dxos/echo';
 import { Card } from '@dxos/react-ui';
 import { Syntax } from '@dxos/react-ui-syntax-highlighter';
 
 export const MapSchema = Schema.Struct({
   coordinates: Format.GeoPoint,
-}).pipe(
-  Type.object({
-    typename: 'com.example.type.map',
-    version: '0.1.0',
-  }),
-);
+}).pipe(Type.makeObject(DXN.make('com.example.type.map', '0.1.0')));
 
-export type MapSchema = Schema.Schema.Type<typeof MapSchema>;
+export type MapSchema = Type.InstanceType<typeof MapSchema>;
 
 // TODO(burdon): Move to ECHO def.
 export type ArtifactsContext = {
@@ -42,28 +37,28 @@ export const capabilities: Capability.Any[] = [
   Capability.contributes(
     Capabilities.ReactSurface,
     Surface.create({
-      id: 'plugin-image',
+      id: 'pluginImage',
       role: 'card--content',
       filter: (data: any): data is any => isImage(data.value),
       component: ({ data }) => (
-        <Card.Content>
+        <Card.Body>
           <img
             className='grow object-cover'
             src={`data:image/jpeg;base64,${data.value.source.data}`}
             alt={data.value.prompt ?? `Generated image [id=${data.value.id}]`}
           />
-        </Card.Content>
+        </Card.Body>
       ),
     }),
   ),
   Capability.contributes(
     Capabilities.ReactSurface,
     Surface.create({
-      id: 'plugin-default',
+      id: 'pluginDefault',
       role: 'card--content',
-      position: 'fallback',
+      position: 'last',
       component: ({ data }) => (
-        <Card.Content>
+        <Card.Body>
           <Syntax.Root data={data}>
             <Syntax.Content>
               <Syntax.Filter />
@@ -72,7 +67,7 @@ export const capabilities: Capability.Any[] = [
               </Syntax.Viewport>
             </Syntax.Content>
           </Syntax.Root>
-        </Card.Content>
+        </Card.Body>
       ),
     }),
   ),

package/src/toolkits/WebToolkit.ts

@@ -8,6 +8,8 @@ import * as Toolkit from '@effect/ai/Toolkit';
 import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
+import { proxyFetchLegacy } from '@dxos/edge-client/cors-proxy';
+
 // TODO(dmaretskyi): Testing only.
 export const WebToolkit = Toolkit.make(
   AnthropicTool.WebSearch_20250305({}).pipe(
@@ -27,7 +29,16 @@ export const WebToolkit = Toolkit.make(
 
 export const layer = WebToolkit.toLayer({
   WebFetch: Effect.fnUntraced(function* ({ url }) {
-    const response = yield* Effect.promise(() => fetch(url).then((response) => response.text()));
-    return response;
+    return yield* Effect.tryPromise({
+      try: async (): Promise<string> => {
+        const response = await proxyFetchLegacy(new URL(url));
+        if (!response.ok) {
+          const body = await response.text();
+          return `Fetch failed with status ${response.status}: ${body.slice(0, 256)}`;
+        }
+        return await response.text();
+      },
+      catch: (cause) => new Error(String(cause)),
+    }).pipe(Effect.catchAll((err) => Effect.succeed(err.message)));
   }),
 });

package/src/types/Agent.test.ts

@@ -0,0 +1,93 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Blueprint } from '@dxos/compute';
+import { Database, Feed, Obj } 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 { Agent, Chat, Plan } from '../types';
+
+EntityId.dangerouslyDisableRandomness();
+
+const TestLayer = AssistantTestLayer({
+  types: [Agent.Agent, Plan.Plan, Chat.Chat, Chat.CompanionTo, Blueprint.Blueprint, Feed.Feed, Text.Text],
+  disableLlmMemoization: true,
+});
+
+const makeAgent = Effect.fnUntraced(function* () {
+  return yield* Agent.makeInitialized(
+    { name: 'Test', instructions: '' },
+    Blueprint.make({ key: 'org.dxos.test.blueprint', 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,
+    ),
+  );
+
+  it.scoped(
+    'adds an object by fully-qualified ECHO URI',
+    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);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/types/Agent.ts

@@ -8,16 +8,15 @@ import * as Effect from 'effect/Effect';
 import * as Function from 'effect/Function';
 import * as Schema from 'effect/Schema';
 
-import { AiContextBinder, AiContextService } from '@dxos/assistant';
+import { AiContext } from '@dxos/assistant';
 import { type Blueprint } from '@dxos/compute';
-import { QueueService } from '@dxos/compute';
-import { Annotation, Database, Feed, Format, Obj, Ref, Relation, Type } from '@dxos/echo';
-import { Queue } from '@dxos/echo-db';
-import { type ObjectNotFoundError } from '@dxos/echo/Err';
-import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/internal';
-import { acquireReleaseResource } from '@dxos/effect';
+import { DXN, Annotation, Database, Feed, Format, Obj, Ref, Relation, Type } from '@dxos/echo';
+import { FormInputAnnotation } from '@dxos/echo/Annotation';
+import { type EntityNotFoundError } from '@dxos/echo/Err';
+import { EffectEx } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
-import { QueueAnnotation, Text } from '@dxos/schema';
+import { EID, type EntityId } from '@dxos/keys';
+import { Text } from '@dxos/schema';
 
 import * as Chat from './Chat';
 import * as Plan from './Plan';
@@ -64,52 +63,57 @@ export const Agent = Schema.Struct({
     }),
   ).pipe(FormInputAnnotation.set(false)),
 
-  /**
-   * Input feed for subscriptions.
-   */
-  // TODO(burdon): Rename to Feed?
-  // NOTE: Named `queue` to conform to subscribable schema (see QueueAnnotation).
-  queue: Schema.optional(Ref.Ref(Queue).pipe(FormInputAnnotation.set(false))),
-
   /**
    * References to objects with a canonical queue property.
    * Schema must have the QueueAnnotation.
    */
+  // Change to trigger.
   // TODO(dmaretskyi): Turn into an array of objects when form-data
   subscriptions: Schema.Array(Ref.Ref(Obj.Unknown)).pipe(FormInputAnnotation.set(false)),
 
+  /**
+   * Cron expression for a timer trigger that invokes the agent worker on a schedule.
+   * The timer trigger bypasses the qualifier and goes straight to the agent worker.
+   */
+  // Change to trigger.
+  cron: Schema.optional(Schema.String).annotations({
+    title: 'Cron',
+    description: 'Cron expression for a timer trigger that invokes the agent on a schedule.',
+  }),
+
+  /**
+   * Input feed for subscriptions.
+   * @deprecated Subscriptions will write directly to the agent.
+   */
+  feed: Schema.optional(Ref.Ref(Feed.Feed).pipe(FormInputAnnotation.set(false))),
+
   /**
    * Allow the agent to filter events.
    * Related events will be added to the input queue of the agent.
    * It is recommended to enable this.
+   * @deprecated
    */
   filterEvents: Schema.optional(Schema.Boolean).annotations({
     title: 'Filter events',
     description: 'Allow the agent to filter events.',
   }),
-
-  /**
-   * Cron expression for a timer trigger that invokes the agent worker on a schedule.
-   * The timer trigger bypasses the qualifier and goes straight to the agent worker.
-   */
-  cron: Schema.optional(Schema.String).annotations({
-    title: 'Cron',
-    description: 'Cron expression for a timer trigger that invokes the agent on a schedule.',
-  }),
 }).pipe(
-  Type.object({
-    typename: 'org.dxos.type.agent',
-    version: '0.1.0',
-  }),
-  LabelAnnotation.set(['name']),
-  QueueAnnotation.set(true),
-  Annotation.IconAnnotation.set({
-    icon: 'ph--drone--regular',
-    hue: 'sky',
-  }),
+  Annotation.LabelAnnotation.set(['name']),
+  Annotation.IconAnnotation.set({ icon: 'ph--drone--regular', hue: 'sky' }),
+  Type.makeObject(DXN.make('org.dxos.type.agent', '0.1.0')),
 );
 
-export interface Agent extends Schema.Schema.Type<typeof Agent> {}
+export type Agent = Type.InstanceType<typeof Agent>;
+
+export type MakeProps = Omit<
+  Obj.MakeProps<typeof Agent>,
+  'instructions' | 'plan' | 'artifacts' | 'subscriptions' | 'chat'
+> &
+  Partial<Pick<Obj.MakeProps<typeof Agent>, 'artifacts' | 'subscriptions'>> & {
+    instructions: string;
+    blueprints?: Ref.Ref<Blueprint.Blueprint>[];
+    contextObjects?: Ref.Ref<Obj.Any>[];
+  };
 
 /**
  * Creates a fully initialized Agent with chat, queue, and context bindings.
@@ -119,28 +123,25 @@ export interface Agent extends Schema.Schema.Type<typeof Agent> {}
  * @returns An Effect that yields the initialized Agent.
  */
 export const makeInitialized = (
-  props: Omit<Obj.MakeProps<typeof Agent>, 'instructions' | 'plan' | 'artifacts' | 'subscriptions' | 'chat'> &
-    Partial<Pick<Obj.MakeProps<typeof Agent>, 'artifacts' | 'subscriptions'>> & {
-      instructions: string;
-      blueprints?: Ref.Ref<Blueprint.Blueprint>[];
-      contextObjects?: Ref.Ref<Obj.Any>[];
-    },
+  props: MakeProps,
+  // TODO(burdon): Reconcile with props.blueprints.
   blueprint: Blueprint.Blueprint,
-): Effect.Effect<Agent, never, QueueService | Feed.FeedService | Database.Service> =>
+): Effect.Effect<Agent, never, Feed.FeedService | Database.Service> =>
   Effect.gen(function* () {
-    const agent = Obj.make(Agent, {
-      ...props,
-      instructions: Ref.make(Text.make(props.instructions)),
-      plan: Ref.make(Plan.makePlan({ tasks: [] })),
-      artifacts: props.artifacts ?? [],
-      subscriptions: props.subscriptions ?? [],
-      filterEvents: props.filterEvents ?? true,
-      enabled: props.enabled ?? true,
-    });
-    yield* Database.add(agent);
+    const agent = yield* Database.add(
+      Obj.make(Agent, {
+        ...props,
+        instructions: Ref.make(Text.make({ content: props.instructions })),
+        plan: Ref.make(Plan.makePlan({ tasks: [] })),
+        artifacts: props.artifacts ?? [],
+        subscriptions: props.subscriptions ?? [],
+        filterEvents: props.filterEvents ?? true,
+        enabled: props.enabled ?? true,
+      }),
+    );
     const feed = yield* Database.add(Feed.make());
     const runtime = yield* Effect.runtime<Feed.FeedService>();
-    const contextBinder = new AiContextBinder({ feed, runtime });
+    const contextBinder = new AiContext.Binder({ feed, runtime });
     // TODO(dmaretskyi): Blueprint registry.
     const agentBlueprint = yield* Database.add(Obj.clone(blueprint, { deep: true }));
     yield* Effect.promise(() =>
@@ -149,6 +150,7 @@ export const makeInitialized = (
         objects: [Ref.make(agent), ...(props.contextObjects ?? [])],
       }),
     );
+
     const chat = yield* Database.add(
       Chat.make({
         [Obj.Parent]: agent,
@@ -163,11 +165,10 @@ export const makeInitialized = (
       }),
     );
 
-    const inputQueue = yield* QueueService.createQueue();
-
+    const inputFeed = yield* Database.add(Feed.make());
     Obj.update(agent, (agent) => {
       agent.chat = Ref.make(chat);
-      agent.queue = Ref.fromDXN(inputQueue.dxn);
+      agent.feed = Ref.make(inputFeed);
     });
 
     return agent;
@@ -182,7 +183,7 @@ export const makeInitialized = (
  */
 export const resetChatHistory = (
   agent: Agent,
-): Effect.Effect<void, ObjectNotFoundError, Feed.FeedService | Database.Service> =>
+): Effect.Effect<void, EntityNotFoundError, Feed.FeedService | Database.Service> =>
   Effect.gen(function* () {
     invariant(agent.chat, 'Agent must have an existing chat to reset.');
 
@@ -191,9 +192,9 @@ export const resetChatHistory = (
       Effect.flatMap(Database.load),
     );
     const runtime = yield* Effect.runtime<Feed.FeedService>();
-    const existingContextBinder = yield* acquireReleaseResource(
+    const existingContextBinder = yield* EffectEx.acquireReleaseResource(
       () =>
-        new AiContextBinder({
+        new AiContext.Binder({
           feed: existingFeed,
           runtime,
         }),
@@ -202,7 +203,7 @@ export const resetChatHistory = (
     const objects = existingContextBinder.getObjects().map((object) => Ref.make(object));
 
     const feed = yield* Database.add(Feed.make());
-    const contextBinder = new AiContextBinder({ feed, runtime });
+    const contextBinder = new AiContext.Binder({ feed, runtime });
     yield* Effect.promise(() =>
       contextBinder.bind({
         blueprints,
@@ -228,8 +229,8 @@ export const resetChatHistory = (
     );
   }).pipe(Effect.scoped);
 
-export const getFromChatContext: Effect.Effect<Agent, Error, AiContextService> = Effect.gen(function* () {
-  const agents = yield* Function.pipe(AiContextService.findObjects(Agent));
+export const getFromChatContext: Effect.Effect<Agent, Error, AiContext.Service> = Effect.gen(function* () {
+  const agents = yield* Function.pipe(AiContext.Service.findObjects(Agent));
   if (agents.length !== 1) {
     return yield* Effect.fail(new Error(`There should be exactly one agent in context. Got: ${agents.length}`));
   }
@@ -237,3 +238,37 @@ export const getFromChatContext: Effect.Effect<Agent, Error, AiContextService> =
   const agent = agents[0];
   return agent;
 });
+
+/**
+ * Adds an object to the agent's artifacts (context), resolving it by id within the agent's space.
+ *
+ * Accepts whatever reference a tool returned — a bare entity id (e.g. `01J…`) or a full ECHO URI
+ * (`echo:/…`, `echo://…`). LLMs frequently strip a returned URI down to the bare id, which is not
+ * a resolvable URI on its own; resolving by entity id within the space tolerates both forms.
+ *
+ * Returns the fully-qualified {@link Ref.Ref} that was stored (also usable for an inline message
+ * reference block).
+ */
+export const addArtifact = (
+  agent: Agent,
+  { name, id }: { name: string; id: string },
+): Effect.Effect<Ref.Ref<Obj.Unknown>, Error, Database.Service> =>
+  Effect.gen(function* () {
+    // Untyped, LLM-provided reference: normalize to the entity id, falling back to the raw value
+    // (a bare id is already an entity id) — a genuine external-data boundary.
+    const parsed = EID.tryParse(id);
+    const entityId = ((parsed ? EID.getEntityId(parsed) : undefined) ?? id) as EntityId;
+
+    // Store a FULLY-QUALIFIED ref (`echo://<space>/<id>`), not a local `echo:/<id>` one: the artifact
+    // is created by a separate tool/process invocation, and a space-less local ref does not resolve
+    // when the agent is later read from a different db view (e.g. the UI). It is not resolved here —
+    // it resolves lazily when read, by which point the artifact is persisted.
+    const { db } = yield* Database.Service;
+    const ref = db.makeRef<Obj.Unknown>(EID.make({ spaceId: db.spaceId, entityId }));
+
+    Obj.update(agent, (agent) => {
+      agent.artifacts.push({ name, data: ref });
+    });
+    yield* Database.flush();
+    return ref;
+  });

package/src/types/Chat.ts

@@ -6,8 +6,8 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Annotation, Feed, Obj, Ref, Type } from '@dxos/echo';
-import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/internal';
+import { DXN, Annotation, Feed, Obj, Ref, Type } from '@dxos/echo';
+import { FormInputAnnotation, LabelAnnotation } from '@dxos/echo/Annotation';
 
 /**
  * AI chat.
@@ -17,47 +17,37 @@ export const Chat = Schema.Struct({
   feed: Ref.Ref(Feed.Feed).pipe(FormInputAnnotation.set(false)),
   view: Schema.String.pipe(Schema.optional),
 }).pipe(
-  Type.object({
-    typename: 'org.dxos.type.assistant.chat',
-    version: '0.1.0',
-  }),
   LabelAnnotation.set(['name']),
-  Annotation.IconAnnotation.set({
-    icon: 'ph--sparkle--regular',
-    hue: 'sky',
-  }),
+  Annotation.IconAnnotation.set({ icon: 'ph--sparkle--regular', hue: 'sky' }),
+  Type.makeObject(DXN.make('org.dxos.type.assistant.chat', '0.1.0')),
 );
 
-export interface Chat extends Schema.Schema.Type<typeof Chat> {}
-
+export type Chat = Type.InstanceType<typeof Chat>;
 export const make = (props: Obj.MakeProps<typeof Chat>) => Obj.make(Chat, props);
 
 /** @deprecated Use CompanionTo instead. */
 export const LegacyCompanionTo = Schema.Struct({
   id: Obj.ID,
 }).pipe(
-  Type.relation({
-    typename: 'org.dxos.relation.assistant.companion-to',
-    version: '0.1.0',
+  Type.makeRelation({
+    dxn: DXN.make('org.dxos.relation.assistant.companionTo', '0.1.0'),
     source: Chat,
     target: Obj.Unknown,
   }),
 );
 
-export interface LegacyCompanionTo extends Schema.Schema.Type<typeof LegacyCompanionTo> {}
-
+export type LegacyCompanionTo = Type.InstanceType<typeof LegacyCompanionTo>;
 /**
  * Relation between a Chat and companion objects (e.g., artifacts).
  */
 export const CompanionTo = Schema.Struct({
   id: Obj.ID,
 }).pipe(
-  Type.relation({
-    typename: 'org.dxos.relation.assistant.companionTo',
-    version: '0.1.0',
+  Type.makeRelation({
+    dxn: DXN.make('org.dxos.relation.assistant.companionTo', '0.1.0'),
     source: Chat,
     target: Obj.Unknown,
   }),
 );
 
-export interface CompanionTo extends Schema.Schema.Type<typeof CompanionTo> {}
+export type CompanionTo = Type.InstanceType<typeof CompanionTo>;

package/src/types/McpServer.ts

@@ -6,32 +6,26 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Annotation, Type } from '@dxos/echo';
-import { LabelAnnotation } from '@dxos/echo/internal';
+import { McpServer as McpServerSpec } from '@dxos/compute';
+import { DXN, Annotation, Type } from '@dxos/echo';
+import { LabelAnnotation } from '@dxos/echo/Annotation';
 
 /**
  * MCP server configuration stored as a space-level ECHO object.
  *
+ * Composes the canonical connection spec from `@dxos/compute` (`url`, `protocol`, `apiKey`)
+ * and adds instance-level fields (`name`, `enabled`) plus ECHO annotations.
+ *
  * NOTE: `apiKey` is stored in plaintext and replicated to all peers with access to the space.
  * A future iteration should move secrets to per-device credential storage or use envelope encryption.
  */
 export const McpServer = Schema.Struct({
-  name: Schema.String,
-  url: Schema.String,
-  protocol: Schema.Union(Schema.Literal('sse'), Schema.Literal('http')),
-  /** Stored in plaintext; replicated to all peers in the space. */
-  apiKey: Schema.optional(Schema.String),
+  ...McpServerSpec.McpServer.fields,
   enabled: Schema.optional(Schema.Boolean),
 }).pipe(
-  Type.object({
-    typename: 'org.dxos.type.assistant.mcpServer',
-    version: '0.1.0',
-  }),
   LabelAnnotation.set(['name']),
-  Annotation.IconAnnotation.set({
-    icon: 'ph--plugs-connected--regular',
-    hue: 'sky',
-  }),
+  Annotation.IconAnnotation.set({ icon: 'ph--plugs-connected--regular', hue: 'sky' }),
+  Type.makeObject(DXN.make('org.dxos.type.assistant.mcpServer', '0.1.0')),
 );
 
-export interface McpServer extends Schema.Schema.Type<typeof McpServer> {}
+export type McpServer = Type.InstanceType<typeof McpServer>;

package/src/types/Memory.ts

@@ -4,7 +4,7 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Annotation, Type } from '@dxos/echo';
+import { DXN, Annotation, Type } from '@dxos/echo';
 
 /**
  * Unit of knowledge generated by an agent.
@@ -13,12 +13,10 @@ export const Memory = Schema.Struct({
   title: Schema.String,
   content: Schema.String,
 }).pipe(
-  Type.object({ typename: 'org.dxos.type.memory', version: '0.1.0' }),
   Annotation.LabelAnnotation.set(['title']),
-  Annotation.IconAnnotation.set({
-    icon: 'ph--brain--regular',
-    hue: 'pink',
-  }),
+  Annotation.IconAnnotation.set({ icon: 'ph--brain--regular', hue: 'pink' }),
+  Annotation.HiddenAnnotation.set(true),
+  Type.makeObject(DXN.make('org.dxos.type.memory', '0.1.0')),
 );
 
-export interface Memory extends Schema.Schema.Type<typeof Memory> {}
+export type Memory = Type.InstanceType<typeof Memory>;

package/src/types/Plan.ts

@@ -6,7 +6,7 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Annotation, Obj, Ref, Type } from '@dxos/echo';
+import { DXN, Annotation, Obj, Ref, Type } from '@dxos/echo';
 
 import * as Chat from './Chat';
 
@@ -23,7 +23,14 @@ export const Task = Schema.Struct({
     description: 'Task title and description.',
   }),
 
-  status: Schema.Literal('todo', 'in-progress', 'done'),
+  status: Schema.Literal('todo', 'in-progress', 'done', 'failed'),
+
+  /**
+   * Whether this task was handed to a sub-agent via the delegation tool. Only delegated tasks are
+   * picked up by the supervisor's reconcile loop, so a task created via ordinary planning
+   * (`update-tasks`) is not double-spawned as a sub-agent.
+   */
+  delegated: Schema.optional(Schema.Boolean),
 
   /**
    * Parent task ID.
@@ -37,22 +44,15 @@ export const Task = Schema.Struct({
    */
   chat: Schema.optional(Ref.Ref(Chat.Chat)),
 });
-export interface Task extends Schema.Schema.Type<typeof Task> {}
 
+export type Task = Schema.Schema.Type<typeof Task>;
 /**
  * Hierarchical collection of tasks for humans and agents to track progress.
  */
 export const Plan = Schema.Struct({
   tasks: Schema.Array(Task),
-}).pipe(
-  Type.object({
-    typename: 'org.dxos.type.plan',
-    version: '0.1.0',
-  }),
-  Annotation.SystemTypeAnnotation.set(true),
-);
-export interface Plan extends Schema.Schema.Type<typeof Plan> {}
-
+}).pipe(Annotation.HiddenAnnotation.set(true), Type.makeObject(DXN.make('org.dxos.type.plan', '0.1.0')));
+export type Plan = Type.InstanceType<typeof Plan>;
 export const generateTaskId = (plan: Plan): TaskId => {
   const existingIds = plan.tasks
     .map((task) => {
@@ -76,7 +76,7 @@ export const generateTaskId = (plan: Plan): TaskId => {
  */
 export const addTasks = (
   plan: Obj.Mutable<Plan>,
-  tasks: (Pick<Task, 'title'> & Partial<Pick<Task, 'status' | 'parent' | 'chat'>>)[],
+  tasks: (Pick<Task, 'title'> & Partial<Pick<Task, 'status' | 'parent' | 'chat' | 'delegated'>>)[],
 ) => {
   for (const task of tasks) {
     const taskId = generateTaskId(plan);
@@ -86,10 +86,7 @@ export const addTasks = (
 };
 
 interface MakePlanProps {
-  tasks: {
-    title: string;
-    status?: 'todo' | 'in-progress' | 'done';
-  }[];
+  tasks: (Pick<Task, 'title'> & Partial<Pick<Task, 'status'>>)[];
 }
 
 export const makePlan = (props: MakePlanProps): Plan => {