@dxos/agent-runtime 0.13.0 → 0.14.0

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

@@ -20,6 +20,7 @@ import {
   AiContext,
   Alarm,
   HarnessControl,
+  type HarnessControlRpcs,
   type PendingState,
   SessionStore,
   SkillHooks,
@@ -28,10 +29,11 @@ import {
   makeToolResolverFromOperations,
 } from '@dxos/assistant';
 import * as Chat from '@dxos/assistant/Chat';
-import { ProcessManager } from '@dxos/compute-runtime';
+import { OperationProcess } from '@dxos/compute-runtime';
 import * as Credential from '@dxos/compute/Credential';
 import * as McpServer from '@dxos/compute/McpServer';
 import * as Operation from '@dxos/compute/Operation';
+import * as OperationHandlerSet from '@dxos/compute/OperationHandlerSet';
 import * as Process from '@dxos/compute/Process';
 import * as Skill from '@dxos/compute/Skill';
 import * as StorageService from '@dxos/compute/StorageService';
@@ -61,6 +63,14 @@ export interface AgentProcessOptions {
   /** Model used when the chat the process is bound to has not selected one. */
   defaultModel?: DXN.DXN;
 
+  /**
+   * Stay resident (IDLE) once the work is done rather than succeeding, so the next prompt lands on this
+   * process instead of a new one. For a host where a spawn is expensive — on EDGE it is a fresh Durable
+   * Object that opens the space and loads the toolkit before the turn can start.
+   * @default false
+   */
+  resident?: boolean;
+
   /**
    * 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.
@@ -120,6 +130,13 @@ export const makeInputMessage = (input: AgentInput): Message.Message => {
   return Message.make({ sender: { role: 'user', ...sender }, blocks, properties });
 };
 
+/**
+ * A process that can run a chat in place of {@link AgentProcess}: it takes the same input and serves
+ * the same `HarnessControl` RPCs, so a session drives it without knowing which one it is. Its
+ * requirements are its own; the host resolves them when it spawns the process.
+ */
+export type AgentProcessDefinition = Operation.Durable<AgentInput, void, any, HarnessControlRpcs>;
+
 /**
  * How long to wait before re-reading a queue that contradicts a write this process just made, and
  * how many times. A hosted runtime serves the read from an eventually-consistent index, and the lag
@@ -159,44 +176,44 @@ const MAX_UNSEEN_WRITE_WAKES = 20;
  * The process target is a queue DXN string.
  */
 export const AgentProcess = (options: AgentProcessOptions) =>
-  Operation.makeDurable(
-    {
-      key: AGENT_PROCESS_KEY,
-      input: AgentInput,
-      output: Schema.Void,
-      // The conversation's own data model. `SessionStore` reads the queue with a TYPED query
-      // (`Filter.type(Message)`/`Filter.type(Alarm)`), so without these registered every read comes
-      // back empty on a host that did not happen to register them itself: the prompt appends fine and
-      // the agent then finds nothing to do. `Chat`/`Feed` are resolved by DXN at startup.
-      // `AiContext.Binding` and `Skill` belong here for the same reason the rest do: the host
-      // registers exactly these with the process's database, and a typed query for a type it does
-      // not know matches nothing. Without them a hosted agent reads its own skill bindings back
-      // empty and runs every turn with an EMPTY TOOLKIT — the model can only answer in prose.
-      // `McpServer` and `AccessToken` are read each turn to connect the space's MCP servers.
-      types: [
-        Chat.Chat,
-        Feed.Feed,
-        Message.Message,
-        Alarm.Alarm,
-        AiContext.Binding,
-        Skill.Skill,
-        McpServer.McpServer,
-        AccessToken.AccessToken,
-      ],
-      services: [
-        Database.Service,
-        OpaqueToolkit.OpaqueToolkitProvider,
-        Operation.Service,
-        Registry.Service,
-        StorageService.StorageService,
-        ProcessManager.ProcessOperationInvoker.Service,
-        AiService.AiService,
-        // Needed in the fiber's context — `Header.byokLayer`'s per-request callback reads it.
-        Credential.CredentialsService,
-      ],
-      rpcs: HarnessControl,
-    },
-    (ctx) =>
+  Operation.makeDurable({
+    key: AGENT_PROCESS_KEY,
+    input: AgentInput,
+    output: Schema.Void,
+    // The conversation's own data model. `SessionStore` reads the queue with a TYPED query
+    // (`Filter.type(Message)`/`Filter.type(Alarm)`), so without these registered every read comes
+    // back empty on a host that did not happen to register them itself: the prompt appends fine and
+    // the agent then finds nothing to do. `Chat`/`Feed` are resolved by DXN at startup.
+    // `AiContext.Binding` and `Skill` belong here for the same reason the rest do: the host
+    // registers exactly these with the process's database, and a typed query for a type it does
+    // not know matches nothing. Without them a hosted agent reads its own skill bindings back
+    // empty and runs every turn with an EMPTY TOOLKIT — the model can only answer in prose.
+    // `McpServer` and `AccessToken` are read each turn to connect the space's MCP servers.
+    types: [
+      Chat.Chat,
+      Feed.Feed,
+      Message.Message,
+      Alarm.Alarm,
+      AiContext.Binding,
+      Skill.Skill,
+      McpServer.McpServer,
+      AccessToken.AccessToken,
+    ],
+    services: [
+      Database.Service,
+      OpaqueToolkit.OpaqueToolkitProvider,
+      Operation.Service,
+      Registry.Service,
+      StorageService.StorageService,
+      Process.ManagerService,
+      OperationHandlerSet.OperationHandlerProvider,
+      AiService.AiService,
+      // Needed in the fiber's context — `Header.byokLayer`'s per-request callback reads it.
+      Credential.CredentialsService,
+    ],
+    rpcs: HarnessControl,
+  }).pipe(
+    Operation.withDurableHandler((ctx) =>
       Effect.gen(function* () {
         const chatDxn = Annotation.getDictionary(ctx.params.annotations, Process.TargetAnnotation).pipe(
           Option.getOrUndefined,
@@ -282,6 +299,12 @@ export const AgentProcess = (options: AgentProcessOptions) =>
         // conversational agent.
         const strategy = Option.fromNullishOr(options.delegationStrategy);
         let delegations: Delegation[] = [...(yield* DelegationsCell.get)];
+        // Background end-request hooks still running as children; persisted so a rehydrated process
+        // still waits for them, and so it knows the request they belong to has already ended.
+        let asyncHooks: Process.ID[] = [...(yield* AsyncHooksCell.get)];
+        // Exits of children this process did not recognise yet: child events run concurrently with
+        // the handler, so a background hook can exit before its pid is registered below.
+        const untrackedExits = new Set<Process.ID>();
 
         // The chat's own selection wins: the process is bound to the chat, so the model it runs on is
         // recovered from the chat on rehydration like the instructions are.
@@ -290,7 +313,9 @@ export const AgentProcess = (options: AgentProcessOptions) =>
           provider: options.provider,
         });
 
-        const operationInvoker = yield* ProcessManager.ProcessOperationInvoker.Service;
+        const childServices = yield* Effect.context<
+          Process.ManagerService | OperationHandlerSet.OperationHandlerProvider
+        >();
 
         // Fire end-request hooks declared by the bound skills (e.g. the planning plan-reminder).
         // Each hook runs as a child operation with `conversation` set, so it resolves the full
@@ -300,20 +325,26 @@ export const AgentProcess = (options: AgentProcessOptions) =>
           yield* SkillHooks.runHooks({
             skills: session.getSkills(),
             phase: 'end-request',
-            invoke: (operation, input) =>
+            invoke: (operation, input, hook) =>
               Effect.gen(function* () {
-                const fiber = yield* operationInvoker.invokeFiber(operation, input, {
+                const handle = yield* Process.spawn(OperationProcess.make(operation), input, {
                   environment: { conversation: Obj.getURI(feed) },
                   traceMeta: { conversation: Ref.make(feed) },
                 });
-                // `fiber.await` yields an Exit; surface a child failure into the Effect channel so
-                // the outer `Effect.orDie` (and the hook runner's `catchAllCause`) handle it instead
-                // of the failure being silently discarded.
-                const exit = yield* fiber.await;
-                if (Exit.isFailure(exit)) {
-                  return yield* Effect.failCause(exit.cause);
+                if (hook.async) {
+                  if (untrackedExits.delete(handle.pid)) {
+                    return;
+                  }
+                  // Not awaited, so the request settles now; the child is linked, so its exit wakes
+                  // `onChildEvent`, which completes the process once every background hook is done.
+                  asyncHooks.push(handle.pid);
+                  yield* AsyncHooksCell.set(asyncHooks);
+                  return;
                 }
-              }).pipe(Effect.asVoid, Effect.orDie),
+                // A child failure surfaces in the Effect channel, so the outer `Effect.orDie` (and the
+                // hook runner's `catchAllCause`) handle it instead of it being silently discarded.
+                yield* Process.awaitOutput(handle);
+              }).pipe(Effect.provide(childServices), Effect.asVoid, Effect.orDie),
           });
         });
 
@@ -325,6 +356,11 @@ export const AgentProcess = (options: AgentProcessOptions) =>
         // handle, leaving the reader with no reply and no error.
         let turnRan = false;
 
+        // Whether this request's end-request hooks have fired; reset by every turn, so a request
+        // continued by a hook gets its own hooks when it ends. A rehydrated process with background
+        // hooks still running has already fired them.
+        let endHooksFired = asyncHooks.length > 0;
+
         // Queue entries this incarnation wrote but has not yet read back. A hosted process's queue
         // read is served by the space INDEX, which is eventually consistent: the agent appends a
         // prompt and, milliseconds later, its own read returns empty — the index catches up a beat
@@ -368,7 +404,7 @@ export const AgentProcess = (options: AgentProcessOptions) =>
               return;
             }
 
-            if (!turnRan) {
+            if (!turnRan && !endHooksFired) {
               // Idle, not done: stay resident so the prompt this process was spawned for can still
               // land. Ahead of the hooks below, which are end-of-REQUEST hooks — there has been no
               // request to end. Nothing is scheduled; the next `onInput` arms the alarm.
@@ -376,14 +412,29 @@ export const AgentProcess = (options: AgentProcessOptions) =>
               return;
             }
 
-            // The hook may enqueue work (e.g. a plan continuation reminder) via HarnessService Tier B,
-            // which appends to the feed queue; re-check before succeeding so the turn is not dropped.
-            yield* runEndRequestHooks;
-            const after = yield* sessionStore.loadPending(feed);
-            if (pendingWork(after)) {
-              log('agent work enqueued by end-request hook, continuing');
-              yield* reconcileAlarmWith(after);
-              yield* reportSleeping(after);
+            if (!endHooksFired) {
+              endHooksFired = true;
+              // The hook may enqueue work (e.g. a plan continuation reminder) via HarnessService Tier B,
+              // which appends to the feed queue; re-check before succeeding so the turn is not dropped.
+              yield* runEndRequestHooks;
+              const after = yield* sessionStore.loadPending(feed);
+              if (pendingWork(after)) {
+                log('agent work enqueued by end-request hook, continuing');
+                yield* reconcileAlarmWith(after);
+                yield* reportSleeping(after);
+                return;
+              }
+            }
+
+            if (asyncHooks.length > 0) {
+              // Resident rather than done: the linked children keep the process HYBERNATING, which
+              // `runUntilSettled` treats as settled, so the reader is not held up by them.
+              log('awaiting background end-request hooks', { count: asyncHooks.length });
+              return;
+            }
+
+            if (options.resident) {
+              log('agent work complete, staying resident');
               return;
             }
 
@@ -443,9 +494,13 @@ export const AgentProcess = (options: AgentProcessOptions) =>
               markWork('agent.wake');
 
               // Earliest point the agent can report to a reader who is already waiting: draining the
-              // queue below reads the feed, which is itself part of the wait. An empty wake emits it
-              // too, but that path returns in milliseconds and the turn settling clears the line.
-              yield* Trace.emitRequestPhase('preparing');
+              // queue below reads the feed, which is itself part of the wait. Only for a wake with known
+              // work — the re-check after every turn finds none, and on a hosted agent that read takes
+              // long enough for the line to read as another request starting after the reply.
+              const announced = toolResults.length > 0 || unseenWriteIds.size > 0;
+              if (announced) {
+                yield* Trace.emitRequestPhase('preparing');
+              }
 
               for (const pid of dropReportedToolResults(toolResults, (pid) => toolCallManager.isReported(pid))) {
                 log.info('skip tool result that was reported synchronously', { pid });
@@ -555,6 +610,10 @@ export const AgentProcess = (options: AgentProcessOptions) =>
                 }
               }
 
+              if (!announced) {
+                yield* Trace.emitRequestPhase('preparing');
+              }
+
               // The MCP servers are read concurrently with the writes below: neither depends on the
               // other, and each is a round trip to the database that the turn would otherwise wait on in series.
               const [mcpServers] = yield* Effect.all(
@@ -604,6 +663,7 @@ export const AgentProcess = (options: AgentProcessOptions) =>
                 );
               log('end request');
               turnRan = true;
+              endHooksFired = false;
               yield* ToolResultsCell.set(toolResults);
 
               // Ack only now: the turn is what the queue entry was for, so a process that dies before
@@ -651,6 +711,18 @@ export const AgentProcess = (options: AgentProcessOptions) =>
           ),
           onChildEvent: Effect.fnUntraced(function* (event) {
             log('childEvent', { event });
+            if (event._tag === 'exited' && asyncHooks.includes(event.pid)) {
+              asyncHooks = asyncHooks.filter((pid) => pid !== event.pid);
+              yield* AsyncHooksCell.set(asyncHooks);
+              const manager = yield* Process.ManagerService;
+              const exit = yield* manager.attach(event.pid).pipe(Effect.flatMap(Process.awaitOutput), Effect.exit);
+              // A failed background hook is reported and dropped, like a failed inline hook.
+              if (Exit.isFailure(exit)) {
+                log.warn('background end-request hook failed', { pid: event.pid });
+              }
+              yield* maybeComplete;
+              return;
+            }
             if (event._tag === 'exited') {
               // A delegated sub-agent finished: read its result and hand it to the strategy (which
               // updates the work item and notifies the user). Unlike tool results, this does not
@@ -659,9 +731,9 @@ export const AgentProcess = (options: AgentProcessOptions) =>
               if (delegation) {
                 delegations = delegations.filter((other) => other.pid !== event.pid);
                 yield* DelegationsCell.set(delegations);
-                const operationInvoker = yield* ProcessManager.ProcessOperationInvoker.Service;
-                const fiber = yield* operationInvoker.attachFiber(event.pid).pipe(Effect.orDie);
-                const exit = yield* fiber.await;
+                const manager = yield* Process.ManagerService;
+                const child = yield* manager.attach(event.pid);
+                const exit = yield* Process.awaitOutput(child).pipe(Effect.exit);
                 // Written beside `DelegationSpawned`, and for the same reason: the return is only
                 // observable here. The child's own trace ends with its operation and says nothing
                 // about reporting back, so this is what pairs an exit with the task it answers.
@@ -692,23 +764,24 @@ export const AgentProcess = (options: AgentProcessOptions) =>
                 log('delegated work completed', { pid: event.pid, id: delegation.id, success: Exit.isSuccess(exit) });
                 yield* maybeComplete;
               } else if (toolCallManager.isToolCall(event.pid)) {
-                const operationInvoker = yield* ProcessManager.ProcessOperationInvoker.Service;
-                const attachExit = yield* operationInvoker.attachFiber(event.pid).pipe(Effect.exit);
-                if (Exit.isFailure(attachExit)) {
-                  // Completed tool children are not rehydrated on reload; the result is in the tool
-                  // result queue or was delivered synchronously before the interrupted turn.
-                  if (
-                    toolCallManager.isToolCall(event.pid) ||
-                    toolResults.some((item) => item.pid === event.pid) ||
-                    toolCallManager.isReported(event.pid)
-                  ) {
-                    log.verbose('childEvent skipped (process gone, result already handled)', { pid: event.pid });
-                    return;
-                  }
-                  return yield* Effect.failCause(attachExit.cause).pipe(Effect.orDie);
+                const manager = yield* Process.ManagerService;
+                const attachExit = yield* manager.attach(event.pid).pipe(Effect.exit);
+                if (
+                  Exit.isFailure(attachExit) &&
+                  isToolResultHandled(toolResults, event.pid, (pid) => toolCallManager.isReported(pid))
+                ) {
+                  // Completed tool children are not rehydrated on reload; this result is already queued or
+                  // was delivered before the interrupted turn.
+                  log.verbose('childEvent skipped (process gone, result already handled)', { pid: event.pid });
+                  return;
                 }
-                const fiber = attachExit.value;
-                const result = yield* fiber.await.pipe(Effect.orDie).pipe(
+                const result = yield* (
+                  Exit.isFailure(attachExit)
+                    ? // Unreported and unreachable: answered as an error so the call does not stay pending forever.
+                      Effect.failCause(attachExit.cause)
+                    : Process.awaitOutput(attachExit.value)
+                ).pipe(
+                  Effect.exit,
                   Effect.map(
                     Exit.match({
                       onSuccess: (value): ToolResultEvent => ({
@@ -733,11 +806,13 @@ export const AgentProcess = (options: AgentProcessOptions) =>
                 log('agent onChildEvent alarm scheduled', { depth: toolResults.length });
               } else {
                 log.verbose('childEvent ignored non-tool call and not a delegation', { pid: event.pid });
+                untrackedExits.add(event.pid);
               }
             }
           }),
         };
       }),
+    ),
   );
 
 interface ToolExecutionServiceOptions {
@@ -784,6 +859,12 @@ const DelegationsCell = StorageService.cell(
   'delegations',
 ).pipe(StorageService.withDefault(() => []));
 
+/** Pids of background ({@link Skill.Hook.async}) end-request hooks the process is waiting on. */
+const AsyncHooksCell = StorageService.cell(
+  Schema.fromJsonString(Schema.Array(Process.ID).pipe(Schema.mutable)),
+  'asyncHooks',
+).pipe(StorageService.withDefault(() => []));
+
 /**
  * Ids of queue entries this process has ACKED, held until the ack is visible in the feed read.
  *
@@ -922,6 +1003,16 @@ export const isAgentWorkPending = ({
   delegations.length > 0 ||
   toolCallManager.hasPendingToolResults();
 
+/**
+ * Whether a tool call's result is already accounted for — queued for the next turn or delivered to the
+ * agent — so a finished child that can no longer be reattached needs no answer of its own.
+ */
+export const isToolResultHandled = (
+  queue: readonly ToolResultEvent[],
+  pid: Process.ID,
+  isReported: (pid: Process.ID) => boolean,
+): boolean => queue.some((item) => item.pid === pid) || isReported(pid);
+
 /**
  * Discards tool results at the head of the queue whose values already reached the agent.
  *
@@ -1016,13 +1107,15 @@ const ToolExecutionService = ({
 }: ToolExecutionServiceOptions) =>
   Layer.unwrap(
     Effect.gen(function* () {
-      const operationInvoker = yield* ProcessManager.ProcessOperationInvoker.Service;
+      const childServices = yield* Effect.context<
+        Process.ManagerService | OperationHandlerSet.OperationHandlerProvider
+      >();
       return makeToolExecutionService({
         invoke: (tool, input) =>
           Effect.gen(function* () {
             const operationDef = getOperationFromTool(tool).pipe(Option.getOrThrow);
             log('invoking operation', { operationDef, input });
-            const fiber = yield* operationInvoker.invokeFiber(operationDef, input, {
+            const handle = yield* Process.spawn(OperationProcess.make(operationDef), input, {
               environment: {
                 conversation: Obj.getURI(feed),
               },
@@ -1031,23 +1124,26 @@ const ToolExecutionService = ({
               },
             });
             markWork('tool.spawned');
-            yield* toolCallManager.beginCall(fiber.pid);
+            yield* toolCallManager.beginCall(handle.pid);
             markWork('tool.call-recorded');
-            log('invoked operation', { operationDef, input, fiber });
+            log('invoked operation', { operationDef, input, pid: handle.pid });
 
-            const awaitWithReport = fiber.await.pipe(Effect.tap(() => toolCallManager.markAsReported(fiber.pid)));
+            const awaitWithReport = Process.awaitOutput(handle).pipe(
+              Effect.exit,
+              Effect.tap(() => toolCallManager.markAsReported(handle.pid)),
+            );
             const result = enableBackgrounding
               ? yield* awaitWithReport.pipe(
                   Effect.timeout(backgroundThreshold),
                   Effect.catchTag('TimeoutError', () =>
-                    Effect.succeed(Exit.succeed(toolIsRunningInBackgroundResponse(fiber.pid))),
+                    Effect.succeed(Exit.succeed(toolIsRunningInBackgroundResponse(handle.pid))),
                   ),
                 )
               : yield* awaitWithReport;
             markWork('tool.settled');
             log('result', { result });
             return yield* result;
-          }),
+          }).pipe(Effect.provide(childServices)),
       });
     }),
   );
@@ -1081,23 +1177,28 @@ class AsynchronousExectionToolkit extends Toolkit.make(
 // TODO(dmaretskyi): Currently broken: polling a completed process returns interruped error.
 const AsynchronousExectionToolkitLayer = AsynchronousExectionToolkit.toLayer(
   Effect.gen(function* () {
-    const invoker = yield* ProcessManager.ProcessOperationInvoker.Service;
+    const manager = yield* Process.ManagerService;
     return {
       'poll-tools': ({ ids, wait, timeout = 10_000 }) =>
         Effect.gen(function* () {
           return yield* Effect.forEach(ids, (pid) =>
-            invoker.attachFiber<unknown>(Process.ID.make(pid)).pipe(
-              Effect.flatMap((_) => _.await),
-              Effect.timeout(Duration.millis(timeout)),
-              Effect.flatMap(
-                Exit.match({
-                  onSuccess: (value) => Effect.succeed(toolResultResponse(pid, value)),
-                  onFailure: (cause) => Effect.succeed(toolErrorResponse(pid, Cause.pretty(cause))),
-                }),
-              ),
-              Effect.catchTag('ProcessNotFoundError', () => Effect.succeed(`Process not found: ${pid}`)),
-              Effect.catchTag('TimeoutError', () => Effect.succeed(`Process still running: ${pid}`)),
-            ),
+            Effect.gen(function* () {
+              const attached = yield* manager.attach<unknown, unknown>(Process.ID.make(pid)).pipe(Effect.exit);
+              if (Exit.isFailure(attached)) {
+                return `Process not found: ${pid}`;
+              }
+              return yield* Process.awaitOutput(attached.value).pipe(
+                Effect.exit,
+                Effect.timeout(Duration.millis(timeout)),
+                Effect.map(
+                  Exit.match({
+                    onSuccess: (value) => toolResultResponse(pid, value),
+                    onFailure: (cause) => toolErrorResponse(pid, Cause.pretty(cause)),
+                  }),
+                ),
+                Effect.catchTag('TimeoutError', () => Effect.succeed(`Process still running: ${pid}`)),
+              );
+            }),
           );
         }),
     };

package/src/agent-service/delegation-scripted.test.ts

@@ -9,9 +9,10 @@ import * as Schema from 'effect/Schema';
 import { expect } from 'vitest';
 
 import { ScriptedLanguageModel } from '@dxos/ai/testing';
-import { ProcessManager } from '@dxos/compute-runtime';
+import { OperationProcess } from '@dxos/compute-runtime';
 import * as Operation from '@dxos/compute/Operation';
 import * as OperationHandlerSet from '@dxos/compute/OperationHandlerSet';
+import * as Process from '@dxos/compute/Process';
 import { TestHelpers } from '@dxos/effect/testing';
 import { DXN, EntityId } from '@dxos/keys';
 
@@ -70,9 +71,8 @@ const StubDelegationStrategy: DelegationStrategy = {
         .map((work) => ({
           id: work.id,
           spawn: Effect.gen(function* () {
-            const invoker = yield* ProcessManager.ProcessOperationInvoker.Service;
-            const fiber = yield* invoker.invokeFiber(DelegatedWork, work.input);
-            return fiber.pid;
+            const handle = yield* Process.spawn(OperationProcess.make(DelegatedWork), work.input);
+            return handle.pid;
           }),
         })),
     ),

package/src/agent-service/delegation-strategy.ts

@@ -7,13 +7,13 @@ import type * as Effect from 'effect/Effect';
 import type * as Exit from 'effect/Exit';
 
 import type * as Chat from '@dxos/assistant/Chat';
-import { type ProcessManager } from '@dxos/compute-runtime';
+import type * as OperationHandlerSet from '@dxos/compute/OperationHandlerSet';
 import type * as Process from '@dxos/compute/Process';
 import { type Database } from '@dxos/echo';
 
 /**
  * A unit of work the supervisor delegates to a linked child process. `spawn` is an existential over
- * the child operation's input/output types: the strategy constructs it (e.g. via `invokeFiber`)
+ * the child operation's input/output types: the strategy constructs it (e.g. via `Process.spawn`)
  * so {@link AgentProcess} can remain agnostic to the operation type and just track the returned pid.
  */
 export interface Delegation {
@@ -24,9 +24,14 @@ export interface Delegation {
 
   /**
    * Spawns the child for this delegation and returns its process id. Must be linked (non-blocking)
-   * so the child's exit wakes the supervisor's `onChildEvent` — i.e. `ProcessOperationInvoker.invokeFiber`.
+   * so the child's exit wakes the supervisor's `onChildEvent` — i.e. spawned through the supervisor's own
+   * {@link Process.ManagerService}, which links its children by default.
    */
-  readonly spawn: Effect.Effect<Process.ID, never, ProcessManager.ProcessOperationInvoker.Service>;
+  readonly spawn: Effect.Effect<
+    Process.ID,
+    never,
+    Process.ManagerService | OperationHandlerSet.OperationHandlerProvider
+  >;
 }
 
 /**

package/src/agent-service/index.ts

@@ -9,6 +9,7 @@ export {
   AGENT_PROCESS_KEY,
   AgentInput,
   AgentProcess,
+  type AgentProcessDefinition,
   type AgentProcessOptions,
   makeInputMessage,
 } from './agent-process.ts';