@dxos/agent-runtime 0.0.0 → 0.11.0

package/src/agent-service/AgentService.test.ts

@@ -16,15 +16,16 @@ import { expect } from 'vitest';
 
 import { MemoizedAiService } from '@dxos/ai/testing';
 import { PartialBlock, SessionLink } from '@dxos/assistant';
-import { Operation, OperationHandlerSet, Process, ServiceResolver, Skill, Trace } from '@dxos/compute';
+import { Instructions, Operation, OperationHandlerSet, Process, ServiceResolver, Skill, Trace } from '@dxos/compute';
 import { ProcessManager } from '@dxos/compute-runtime';
 import { getSession, hydrate } from '@dxos/compute/AgentService';
-import { Annotation, Feed, Filter, Obj, Ref } from '@dxos/echo';
+import { Annotation, Database, Feed, Filter, Obj, Ref } from '@dxos/echo';
 import { TestHelpers } from '@dxos/effect/testing';
 import { DXN, EntityId } from '@dxos/keys';
+import { Text } from '@dxos/schema';
 import { Message, Organization } from '@dxos/types';
 
-import { AssistantTestLayer } from '../testing';
+import { AssistantTestLayer, runMemoizedTests } from '../testing';
 import * as ResearchService from '../testing/ResearchService';
 import { AGENT_PROCESS_KEY } from './agent-process';
 import * as AgentService from './AgentService';
@@ -85,7 +86,7 @@ const ResearchSkill = Skill.make({
 });
 
 const assistantTestLayerOptions = {
-  types: [Organization.Organization, Feed.Feed, Skill.Skill],
+  types: [Organization.Organization, Feed.Feed, Skill.Skill, Instructions.Instructions, Text.Text],
   tracing: 'pretty' as const,
   aiServicePreset: 'edge-remote' as const,
   operationHandlers: [handlers],
@@ -144,16 +145,16 @@ const DelegationTestLayer = AssistantTestLayer({
   agent: { delegationStrategy: StubDelegationStrategy },
 });
 
-describe('Agent Service', () => {
+describe.skipIf(!runMemoizedTests())('Agent Service', () => {
   it.effect(
     'can answer a question',
     Effect.fnUntraced(
       function* (_) {
-        const agent = yield* AgentService.createSession();
-        yield* agent.submitPrompt('What is the capital of France?');
-        yield* agent.waitForCompletion();
+        const session = yield* AgentService.createSession();
+        yield* session.submitPrompt('What is the capital of France?');
+        yield* session.waitForCompletion();
 
-        const messages = yield* Feed.query(agent.feed, Filter.type(Message.Message)).run;
+        const messages = yield* Feed.query(session.feed, Filter.type(Message.Message)).run;
         const text = messages.map(Message.extractText).join('\n');
         expect(text.toLocaleLowerCase()).toContain('paris');
       },
@@ -167,15 +168,13 @@ describe('Agent Service', () => {
     'tool call',
     Effect.fnUntraced(
       function* (_) {
-        const agent = yield* AgentService.createSession({
-          skills: [ResearchSkill],
-        });
-        yield* agent.submitPrompt(`Research ${JSON.stringify(ResearchService.getTestData().organizations[0])}`);
+        const session = yield* AgentService.createSession({ skills: [ResearchSkill] });
+        yield* session.submitPrompt(`Research ${JSON.stringify(ResearchService.getTestData().organizations[0])}`);
 
         const researchService = yield* ServiceResolver.resolve(ResearchService.ResearchService, {});
         yield* researchService.waitForTaskToAppear();
         yield* researchService.completeOneTask();
-        yield* agent.waitForCompletion();
+        yield* session.waitForCompletion();
       },
       Effect.provide(TestLayer()),
       TestHelpers.provideTestContext,
@@ -187,14 +186,12 @@ describe('Agent Service', () => {
     'can be stopped while waiting for a tool call',
     Effect.fnUntraced(
       function* (_) {
-        let agent = yield* AgentService.createSession({
-          skills: [ResearchSkill],
-        });
-        yield* agent.submitPrompt(`Research ${JSON.stringify(ResearchService.getTestData().organizations[0])}`);
+        let session = yield* AgentService.createSession({ skills: [ResearchSkill] });
+        yield* session.submitPrompt(`Research ${JSON.stringify(ResearchService.getTestData().organizations[0])}`);
         const researchService = yield* ServiceResolver.resolve(ResearchService.ResearchService, {});
         yield* researchService.waitForTaskToAppear();
 
-        yield* agent.terminate();
+        yield* session.terminate();
         expect(researchService.getTasks().map((task) => task.state)).toEqual(['interrupted']);
       },
       Effect.provide(TestLayer()),
@@ -206,10 +203,8 @@ describe('Agent Service', () => {
     'restart during tool call',
     Effect.fnUntraced(
       function* (_) {
-        let agent = yield* AgentService.createSession({
-          skills: [ResearchSkill],
-        });
-        yield* agent.submitPrompt(`Research ${JSON.stringify(ResearchService.getTestData().organizations[0])}`);
+        let session = yield* AgentService.createSession({ skills: [ResearchSkill] });
+        yield* session.submitPrompt(`Research ${JSON.stringify(ResearchService.getTestData().organizations[0])}`);
 
         const researchService = yield* ServiceResolver.resolve(ResearchService.ResearchService, {});
         yield* researchService.waitForTaskToAppear();
@@ -224,8 +219,8 @@ describe('Agent Service', () => {
         yield* researchService.waitForTaskToAppear();
         yield* researchService.completeAllTasks();
 
-        agent = yield* getSession(agent.feed);
-        yield* agent.waitForCompletion();
+        session = yield* getSession(session.feed);
+        yield* session.waitForCompletion();
       },
       Effect.provide(TestLayer()),
       TestHelpers.provideTestContext,
@@ -237,10 +232,8 @@ describe('Agent Service', () => {
     'recovers queued tool results after reload',
     Effect.fnUntraced(
       function* (_) {
-        let agent = yield* AgentService.createSession({
-          skills: [ResearchSkill],
-        });
-        yield* agent.submitPrompt(`Research ${JSON.stringify(ResearchService.getTestData().organizations[0])}`);
+        let session = yield* AgentService.createSession({ skills: [ResearchSkill] });
+        yield* session.submitPrompt(`Research ${JSON.stringify(ResearchService.getTestData().organizations[0])}`);
 
         const researchService = yield* ServiceResolver.resolve(ResearchService.ResearchService, {});
         yield* researchService.waitForTaskToAppear();
@@ -255,10 +248,10 @@ describe('Agent Service', () => {
         yield* researchService.waitForTaskToAppear();
         yield* researchService.completeAllTasks();
 
-        agent = yield* getSession(agent.feed);
-        yield* agent.waitForCompletion();
+        session = yield* getSession(session.feed);
+        yield* session.waitForCompletion();
 
-        const messages = yield* Feed.query(agent.feed, Filter.type(Message.Message)).run;
+        const messages = yield* Feed.query(session.feed, Filter.type(Message.Message)).run;
         const text = messages.map(Message.extractText).join('\n');
         expect(text.toLocaleLowerCase()).toContain('cyberdyne');
       },
@@ -272,9 +265,9 @@ describe('Agent Service', () => {
     'rehydrates an idle session and replays conversation history',
     Effect.fnUntraced(
       function* (_) {
-        let agent = yield* AgentService.createSession();
-        yield* agent.submitPrompt('What is the capital of France? Reply with just the city name.');
-        yield* agent.waitForCompletion();
+        let session = yield* AgentService.createSession();
+        yield* session.submitPrompt('What is the capital of France? Reply with just the city name.');
+        yield* session.waitForCompletion();
 
         // Simulate app teardown + reboot while the session sits idle (nothing in-flight).
         const processManager = yield* ProcessManager.ProcessManagerService;
@@ -284,11 +277,11 @@ describe('Agent Service', () => {
 
         // The rehydrated agent is bound to the same feed, so a follow-up that only makes sense
         // with prior context resolves against the pre-restart turn.
-        agent = yield* getSession(agent.feed);
-        yield* agent.submitPrompt('What country did I just ask you about? Reply with just the country name.');
-        yield* agent.waitForCompletion();
+        session = yield* getSession(session.feed);
+        yield* session.submitPrompt('What country did I just ask you about? Reply with just the country name.');
+        yield* session.waitForCompletion();
 
-        const messages = yield* Feed.query(agent.feed, Filter.type(Message.Message)).run;
+        const messages = yield* Feed.query(session.feed, Filter.type(Message.Message)).run;
         const text = messages.map(Message.extractText).join('\n');
         expect(text.toLocaleLowerCase()).toContain('paris');
         expect(text.toLocaleLowerCase()).toContain('france');
@@ -319,9 +312,7 @@ describe('Agent Service', () => {
     'runs AI agent with background tools via process manager',
     Effect.fnUntraced(
       function* (_) {
-        const agent = yield* AgentService.createSession({
-          skills: [ResearchSkill],
-        });
+        const session = yield* AgentService.createSession({ skills: [ResearchSkill] });
 
         const researchService = yield* ServiceResolver.resolve(ResearchService.ResearchService, {});
         const taskDrainer = yield* Effect.gen(function* () {
@@ -330,7 +321,7 @@ describe('Agent Service', () => {
         }).pipe(Effect.forever, Effect.fork);
 
         let ephemeralEventCount = 0;
-        const ephemeralFiber = yield* agent.subscribeEphemeral().pipe(
+        const ephemeralFiber = yield* session.subscribeEphemeral().pipe(
           Stream.runForEach((msg) =>
             Effect.gen(function* () {
               for (const event of msg.events) {
@@ -344,11 +335,11 @@ describe('Agent Service', () => {
         );
 
         for (const org of ResearchService.getTestData().organizations) {
-          yield* agent.submitPrompt(JSON.stringify(org));
+          yield* session.submitPrompt(JSON.stringify(org));
         }
-        yield* agent.submitPrompt('When all research is complete, print 1-sentence summary for each organization.');
+        yield* session.submitPrompt('When all research is complete, print 1-sentence summary for each organization.');
         // TODO(dmaretskyi): wait until settles and only now start draining
-        yield* agent.waitForCompletion();
+        yield* session.waitForCompletion();
 
         yield* Fiber.interrupt(taskDrainer);
         yield* Fiber.interrupt(ephemeralFiber);
@@ -361,6 +352,10 @@ describe('Agent Service', () => {
     { timeout: MemoizedAiService.isGenerationEnabled() ? 120_000 : undefined },
   );
 
+  // Superseded by the ungated scripted-model port in `delegation-scripted.test.ts` (and the
+  // real-strategy test in `assistant-toolkit/src/supervisor/delegation-strategy.test.ts`); kept
+  // in place until this file's memoized fixtures are next regenerated, since removing it would
+  // shift the shared deterministic ID stream the later fixtures depend on.
   describe('delegation (stub)', () => {
     it.scoped(
       'delegates work to a sub-agent and folds the result back on completion',
@@ -369,10 +364,10 @@ describe('Agent Service', () => {
           delegationHarness.pending = [{ id: 'task-1', input: 'forty-two' }];
           delegationHarness.completed = [];
 
-          const agent = yield* AgentService.createSession();
-          yield* agent.submitPrompt('What is the capital of France?');
+          const session = yield* AgentService.createSession();
+          yield* session.submitPrompt('What is the capital of France?');
           // Settles on the turn's reply; the delegated child runs in the background (not awaited here).
-          yield* agent.waitForCompletion();
+          yield* session.waitForCompletion();
 
           // The post-turn reconcile spawned a linked child; its exit drives onChildEvent → onComplete.
           yield* Effect.promise(async () => {
@@ -450,11 +445,11 @@ describe('Agent Service', () => {
       function* (_) {
         const processManager = yield* ProcessManager.ProcessManagerService;
 
-        const agent = yield* AgentService.createSession();
-        const target = Obj.getURI(agent.feed);
+        const session = yield* AgentService.createSession();
+        const target = Obj.getURI(session.feed);
 
-        yield* agent.submitPrompt('What is the capital of France? Reply with just the city name.');
-        yield* agent.waitForCompletion();
+        yield* session.submitPrompt('What is the capital of France? Reply with just the city name.');
+        yield* session.waitForCompletion();
 
         // With no queued work, alarms, delegations, or undelivered tool results, the process calls
         // `ctx.succeed()` (see `maybeComplete` / `isAgentWorkPending`) and reaches a terminal state
@@ -467,14 +462,14 @@ describe('Agent Service', () => {
 
         // A follow-up turn does not reuse the succeeded process: `getSession` skips terminal handles
         // and spawns a fresh one, which replays conversation history from the feed.
-        const followUp = yield* getSession(agent.feed);
+        const followUp = yield* getSession(session.feed);
         yield* followUp.submitPrompt('What country did I just ask you about? Reply with just the country name.');
         yield* followUp.waitForCompletion();
 
         const processes = yield* processManager.list({ target, key: AGENT_PROCESS_KEY });
         expect(processes.some((process) => String(process.pid) !== firstPid)).toBe(true);
 
-        const messages = yield* Feed.query(agent.feed, Filter.type(Message.Message)).run;
+        const messages = yield* Feed.query(session.feed, Filter.type(Message.Message)).run;
         const text = messages.map(Message.extractText).join('\n');
         expect(text.toLocaleLowerCase()).toContain('france');
       },
@@ -492,9 +487,9 @@ describe('Agent Service', () => {
       function* (_) {
         const processManager = yield* ProcessManager.ProcessManagerService;
 
-        // createSession spawns the agent process (no LLM turn yet) bound to a stamped host marker.
-        const agent = yield* AgentService.createSession();
-        const target = Obj.getURI(agent.feed);
+        // Spawns the agent process (no LLM turn yet) bound to a stamped host marker.
+        const session = yield* AgentService.createSession();
+        const target = Obj.getURI(session.feed);
         const [handle] = yield* processManager.list({ target, key: AGENT_PROCESS_KEY });
 
         // The spawn stamped the harness-host annotation so the process is discoverable as the owner.
@@ -521,3 +516,65 @@ describe('Agent Service', () => {
     ),
   );
 });
+
+// Control-plane coverage (no LLM turn), so it runs ungated in CI unlike the replay suite above.
+describe('Agent Service (control plane)', () => {
+  // Exercises the instruction-aware reuse identity on both paths — the session cache and the
+  // remount (rediscovered process) path.
+  it.scoped(
+    'session reuse tracks the steering-instructions ref',
+    Effect.fnUntraced(
+      function* (_) {
+        const processManager = yield* ProcessManager.ProcessManagerService;
+
+        const instructionsA = yield* Database.add(Instructions.make({ text: 'Steering A.' }));
+        const instructionsB = yield* Database.add(Instructions.make({ text: 'Steering B.' }));
+        const feed = yield* Database.add(Feed.make());
+        yield* Database.flush();
+        const target = Obj.getURI(feed);
+
+        const isActive = (state: Process.State) =>
+          state !== Process.State.SUCCEEDED && state !== Process.State.FAILED && state !== Process.State.TERMINATED;
+        const activePids = Effect.gen(function* () {
+          const processes = yield* processManager.list({ target, key: AGENT_PROCESS_KEY });
+          return processes.filter((process) => isActive(process.status.state));
+        });
+
+        // Spawn with A: the ref URI is stamped as a spawn annotation.
+        const sessionA = yield* getSession(feed, { instructions: Ref.make(instructionsA) });
+        const [handleA] = yield* activePids;
+        const pidA = String(handleA.pid);
+        expect(
+          Option.getOrNull(Annotation.getDictionary(handleA.params.annotations, Process.InstructionsAnnotation)),
+        ).toBe(Ref.make(instructionsA).uri);
+
+        // Unchanged ref: the cached session (and process) is reused.
+        const sessionAgain = yield* getSession(feed, { instructions: Ref.make(instructionsA) });
+        expect(sessionAgain).toBe(sessionA);
+        expect((yield* activePids).map((handle) => String(handle.pid))).toEqual([pidA]);
+
+        // Repointed ref: the process is torn down and respawned with the new annotation.
+        yield* getSession(feed, { instructions: Ref.make(instructionsB) });
+        const [handleB] = yield* activePids;
+        expect(String(handleB.pid)).not.toBe(pidA);
+        expect(
+          Option.getOrNull(Annotation.getDictionary(handleB.params.annotations, Process.InstructionsAnnotation)),
+        ).toBe(Ref.make(instructionsB).uri);
+
+        // Remount path (cache cleared by hydrate): present-to-absent also respawns, since the
+        // rediscovered process's spawn annotation no longer matches the request.
+        yield* hydrate();
+        yield* getSession(feed);
+        const [handleNone] = yield* activePids;
+        expect(String(handleNone.pid)).not.toBe(String(handleB.pid));
+        expect(
+          Option.getOrNull(Annotation.getDictionary(handleNone.params.annotations, Process.InstructionsAnnotation)),
+        ).toBeNull();
+
+        yield* handleNone.terminate();
+      },
+      Effect.provide(TestLayer()),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/agent-service/AgentService.ts

@@ -7,6 +7,7 @@
 import * as Cause from 'effect/Cause';
 import * as Effect from 'effect/Effect';
 import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
 
 import { AiContext } from '@dxos/assistant';
 import { McpServer, Process, Skill } from '@dxos/compute';
@@ -22,6 +23,7 @@ import { Annotation, Database, Feed, Obj, Ref, Registry } from '@dxos/echo';
 import { EffectEx } from '@dxos/effect';
 import { DXN, EID } from '@dxos/keys';
 import { log } from '@dxos/log';
+import type { ContentBlock } from '@dxos/types';
 
 import { AGENT_PROCESS_KEY, AgentProcess } from './agent-process';
 import { type DelegationStrategy } from './delegation-strategy';
@@ -30,11 +32,12 @@ import { type DelegationStrategy } from './delegation-strategy';
 type AgentRpcs = ReturnType<typeof AgentProcess> extends Process.Process<any, any, any, infer Rpcs> ? Rpcs : never;
 
 /** Live handle to a spawned {@link AgentProcess}, carrying its `HarnessControl` RPC surface. */
-type AgentHandle = ProcessManager.Handle<string, void, AgentRpcs>;
+type AgentHandle = ProcessManager.Handle<string | ContentBlock.Any[], void, AgentRpcs>;
 
 const isTerminalProcess = (state: Process.State): boolean =>
   state === Process.State.SUCCEEDED || state === Process.State.FAILED || state === Process.State.TERMINATED;
 
+// TODO(burdon): Agent identity?
 export interface CreateSessionOptions {
   readonly skills?: Skill.Skill[];
   readonly context?: Ref.Ref<Obj.Unknown>[];
@@ -68,6 +71,7 @@ export const createSession: (
 
 export interface AgentServiceOptions {
   systemPrompt?: string;
+
   /**
    * Default model used by sessions that don't specify one explicitly.
    */
@@ -78,11 +82,6 @@ export interface AgentServiceOptions {
    */
   provider?: DXN.DXN;
 
-  /**
-   * Provider for space-level MCP server configs.
-   */
-  getMcpServers?: () => McpServer.McpServer[];
-
   /**
    * If true, long-running tool calls are moved to the background and the agent is notified
    * asynchronously when they complete. Currently unstable — disabled by default.
@@ -96,6 +95,11 @@ export interface AgentServiceOptions {
    * child processes and folds their results back into the conversation. Absent — a plain agent.
    */
   delegationStrategy?: DelegationStrategy;
+
+  /**
+   * Provider for space-level MCP server configs.
+   */
+  getMcpServers?: () => McpServer.McpServer[];
 }
 
 export const layer = (opts?: AgentServiceOptions): Layer.Layer<AgentService, never, ProcessManager.Service> =>
@@ -103,12 +107,18 @@ export const layer = (opts?: AgentServiceOptions): Layer.Layer<AgentService, nev
     AgentService,
     Effect.gen(function* () {
       const processManager = yield* ProcessManager.Service;
-      // The agent's model is bound to its process at spawn time, so the cache tracks the model
-      // each session was created with. Requesting a different model for the same feed tears down
-      // the old process and spawns a fresh one (see below).
+      // The agent's model and steering instructions are bound to its process at spawn time, so the
+      // cache tracks what each session was created with. Requesting a different model or a repointed
+      // instructions ref for the same feed tears down the old process and spawns a fresh one (see below).
       const sessionCache = new Map<
         string,
-        { model: DXN.DXN | undefined; provider: DXN.DXN | undefined; handle: AgentHandle; session: Session }
+        {
+          model: DXN.DXN | undefined;
+          provider: DXN.DXN | undefined;
+          instructions: string | undefined;
+          handle: AgentHandle;
+          session: Session;
+        }
       >();
 
       const makeExecutable = (model?: DXN.DXN, provider?: DXN.DXN) =>
@@ -144,20 +154,24 @@ export const layer = (opts?: AgentServiceOptions): Layer.Layer<AgentService, nev
           Effect.gen(function* () {
             const model = options?.model ?? opts?.model;
             const provider = options?.provider ?? opts?.provider;
+            const instructions = options?.instructions?.uri;
             const cached = sessionCache.get(feed.id);
             if (cached) {
               if (
                 cached.model === model &&
                 cached.provider === provider &&
+                cached.instructions === instructions &&
                 !isTerminalProcess(cached.handle.status.state)
               ) {
                 return cached.session;
               }
 
               if (!isTerminalProcess(cached.handle.status.state)) {
-                // Model or provider changed (e.g. the user toggled online/offline): terminate the
+                // Model, provider, or steering instructions changed (e.g. the user toggled
+                // online/offline, or the chat's instructions ref was repointed): terminate the
                 // existing process so the conversation continues on a fresh process bound to the new
-                // model. Conversation history is preserved via the feed, which the new process replays.
+                // configuration. Conversation history is preserved via the feed, which the new
+                // process replays.
                 yield* cached.handle.terminate();
               }
               sessionCache.delete(feed.id);
@@ -172,7 +186,19 @@ export const layer = (opts?: AgentServiceOptions): Layer.Layer<AgentService, nev
             // (e.g. after the UI remounted). After a model change we always spawn a fresh process,
             // since the process key does not encode the model.
             const processes = yield* processManager.list({ target, key: executable.key });
-            const activeProcess = processes.find((process) => !isTerminalProcess(process.status.state));
+            let activeProcess = processes.find((process) => !isTerminalProcess(process.status.state));
+
+            // Spawn annotations are immutable, so a running process found via the remount path may
+            // carry stale instructions; terminate it and respawn with the requested ref.
+            if (activeProcess) {
+              const processInstructions = Option.getOrUndefined(
+                Annotation.getDictionary(activeProcess.params.annotations, Process.InstructionsAnnotation),
+              );
+              if (processInstructions !== instructions) {
+                yield* activeProcess.terminate();
+                activeProcess = undefined;
+              }
+            }
 
             let handle: AgentHandle;
             if (activeProcess) {
@@ -186,6 +212,9 @@ export const layer = (opts?: AgentServiceOptions): Layer.Layer<AgentService, nev
                 // lookup (set once at spawn, immutable — the identity plane).
                 annotations: Annotation.buildDictionary((dictionary) => {
                   Annotation.setDictionary(dictionary, Process.HarnessHostAnnotation, true);
+                  if (options?.instructions) {
+                    Annotation.setDictionary(dictionary, Process.InstructionsAnnotation, options.instructions.uri);
+                  }
                 }),
                 environment: {
                   ...(spaceId !== undefined ? { space: spaceId } : {}),
@@ -201,7 +230,7 @@ export const layer = (opts?: AgentServiceOptions): Layer.Layer<AgentService, nev
               sessionCache.delete(feed.id);
             };
             const session = makeSession(handle, feed, releaseSession);
-            sessionCache.set(feed.id, { model, provider, handle, session });
+            sessionCache.set(feed.id, { model, provider, instructions, handle, session });
             return session;
           }),
         hydrate: hydrateAgents,
@@ -230,7 +259,7 @@ const makeSession = (process: AgentHandle, feed: Feed.Feed, releaseSession: () =
         }),
       );
     }).pipe(Effect.scoped),
-  submitPrompt: (prompt: string) => process.submitInput(prompt),
+  submitPrompt: (prompt: string | ContentBlock.Any[]) => process.submitInput(prompt),
   // Settle when the turn's reply is complete; do NOT block on background sub-agents
   // (a supervisor delegates work that runs after the turn and reports back out of band).
   waitForCompletion: () => process.runUntilSettled(),

package/src/agent-service/README.md

@@ -1,9 +1,9 @@
 # Agent Service
 
-`AgentService` spawns and caches a process-backed **agent** per conversation feed. The agent is a
-long-lived `AgentProcess` that handles user turns; when a `DelegationStrategy` is injected it also
-acts as a **supervisor** that delegates work to linked child processes and folds their results back
-into the conversation.
+`AgentService` spawns and caches a process-backed **agent** per conversation feed. 
+The agent is a long-lived `AgentProcess` that handles user turns; 
+when a `DelegationStrategy` is injected it also acts as a **supervisor** that delegates work 
+to linked child processes and folds their results back into the conversation.
 
 ## Layering
 

package/src/agent-service/agent-process.ts

@@ -25,7 +25,7 @@ import {
   makeToolExecutionService,
   makeToolResolverFromOperations,
 } from '@dxos/assistant';
-import { Credential, McpServer, Operation, Trace } from '@dxos/compute';
+import { Credential, Instructions, McpServer, Operation, Trace } from '@dxos/compute';
 import { Process } from '@dxos/compute';
 import { ProcessManager } from '@dxos/compute-runtime';
 import * as StorageService from '@dxos/compute/StorageService';
@@ -39,23 +39,23 @@ import { trim } from '@dxos/util';
 import { type DelegationStrategy } from './delegation-strategy';
 
 interface AgentProcessOptions {
+  // TODO(burdon): Instructions?
   systemPrompt?: string;
+
+  /** Model identifier. */
   model?: DXN.DXN;
-  // The catalog's shared model ids are served by several providers, so resolution needs the provider
-  // alongside the id; without it a local model id cannot be claimed by any resolver.
-  provider?: DXN.DXN;
 
   /**
-   * Provider for space-level MCP server configs, called on each turn.
+   * The catalog's shared model ids are served by several providers, so resolution needs the provider
+   * alongside the id; without it a local model id cannot be claimed by any resolver.
    */
-  getMcpServers?: () => McpServer.McpServer[];
+  provider?: DXN.DXN;
 
   /**
    * If true, long-running tool calls are moved to the background after `backgroundThreshold`
    * and the agent is notified asynchronously when they complete.
    *
    * Currently unstable — disabled by default.
-   *
    * @default false
    */
   enableToolBackgrounding?: boolean;
@@ -66,6 +66,11 @@ interface AgentProcessOptions {
    * (the default) the process behaves as a plain conversational agent.
    */
   delegationStrategy?: DelegationStrategy;
+
+  /**
+   * Provider for space-level MCP server configs, called on each turn.
+   */
+  getMcpServers?: () => McpServer.McpServer[];
 }
 
 export const AGENT_PROCESS_KEY = 'org.dxos.testing.process.agent';
@@ -78,7 +83,8 @@ export const AgentProcess = (options: AgentProcessOptions) =>
   Process.make(
     {
       key: AGENT_PROCESS_KEY,
-      input: Schema.String,
+      // String member keeps queue entries persisted before the block-array widening decodable.
+      input: Schema.Union(Schema.String, Schema.Array(ContentBlock.Any)),
       output: Schema.Void,
       services: [
         Database.Service,
@@ -102,8 +108,20 @@ export const AgentProcess = (options: AgentProcessOptions) =>
           return yield* Effect.die(new Error('Agent executable requires spawn options.target set to a queue DXN.'));
         }
         const feed = yield* Database.resolve(feedDxn, Feed.Feed).pipe(Effect.orDie);
+        // Steering instructions travel as a spawn annotation (the session is feed-centric and cannot
+        // reach its Chat); a broken ref degrades to an unsteered session rather than failing the process.
+        const instructionsDxn = Annotation.getDictionary(ctx.params.annotations, Process.InstructionsAnnotation).pipe(
+          Option.getOrUndefined,
+        );
+        const instructions = instructionsDxn
+          ? yield* Database.resolve(instructionsDxn, Instructions.Instructions).pipe(
+              Effect.orElseSucceed(() => undefined),
+            )
+          : undefined;
         const runtime = yield* Effect.runtime<Database.Service>();
-        const session = yield* EffectEx.acquireReleaseResource(() => new AiSession.Session({ feed, runtime }));
+        const session = yield* EffectEx.acquireReleaseResource(
+          () => new AiSession.Session({ feed, runtime, instructions: instructions ? [instructions] : [] }),
+        );
         let inputQueue: AgentEvent[] = [...(yield* AgentEventsCell.get)];
         const storageService = yield* StorageService.StorageService;
         const toolCallManager = new ToolCallManager(storageService);
@@ -195,9 +213,10 @@ export const AgentProcess = (options: AgentProcessOptions) =>
               alarmManager.reconcile(true);
             }),
           }),
-          onInput: Effect.fnUntraced(function* (prompt: string) {
-            log('agent onInput received', { promptLength: prompt.length, backlog: inputQueue.length });
-            inputQueue.push({ _tag: 'prompt', content: [ContentBlock.Text.make({ text: prompt })] });
+          onInput: Effect.fnUntraced(function* (prompt: string | readonly ContentBlock.Any[]) {
+            log('agent onInput received', { backlog: inputQueue.length });
+            const content = typeof prompt === 'string' ? [ContentBlock.Text.make({ text: prompt })] : [...prompt];
+            inputQueue.push({ _tag: 'prompt', content });
             log('agent onInput persisting queue', { depth: inputQueue.length });
             yield* AgentEventsCell.set(inputQueue);
             log('agent onInput persisted', { depth: inputQueue.length });