@dxos/agent-runtime 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/agent-runtime",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Local agent process runtime (agent-service) and assistant-coupled test helpers.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -39,29 +39,29 @@
   ],
   "dependencies": {
     "effect": "4.0.0",
-    "@dxos/ai": "0.13.0",
-    "@dxos/compute": "0.13.0",
-    "@dxos/compute-runtime": "0.13.0",
-    "@dxos/echo": "0.13.0",
-    "@dxos/echo-client": "0.13.0",
-    "@dxos/effect": "0.13.0",
-    "@dxos/keys": "0.13.0",
-    "@dxos/link": "0.13.0",
-    "@dxos/log": "0.13.0",
-    "@dxos/mcp-client": "0.13.0",
-    "@dxos/schema": "0.13.0",
-    "@dxos/types": "0.13.0",
-    "@dxos/util": "0.13.0"
+    "@dxos/ai": "0.14.0",
+    "@dxos/compute": "0.14.0",
+    "@dxos/compute-runtime": "0.14.0",
+    "@dxos/echo": "0.14.0",
+    "@dxos/echo-client": "0.14.0",
+    "@dxos/effect": "0.14.0",
+    "@dxos/keys": "0.14.0",
+    "@dxos/link": "0.14.0",
+    "@dxos/log": "0.14.0",
+    "@dxos/mcp-client": "0.14.0",
+    "@dxos/schema": "0.14.0",
+    "@dxos/types": "0.14.0",
+    "@dxos/util": "0.14.0"
   },
   "devDependencies": {
     "@effect/vitest": "4.0.0",
     "vitest": "4.1.10",
-    "@dxos/assistant": "0.13.0",
-    "@dxos/errors": "0.13.0"
+    "@dxos/assistant": "0.14.0",
+    "@dxos/errors": "0.14.0"
   },
   "peerDependencies": {
     "effect": "4.0.0",
-    "@dxos/assistant": "^0.13.0"
+    "@dxos/assistant": "^0.14.0"
   },
   "publishConfig": {
     "access": "public"

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

@@ -22,6 +22,7 @@ import { LanguageModelFixture } from '@dxos/ai/testing';
 import { type HarnessControlRpcs, SessionLink } from '@dxos/assistant';
 import * as Chat from '@dxos/assistant/Chat';
 import { ProcessManager } from '@dxos/compute-runtime';
+import { OperationProcess } from '@dxos/compute-runtime';
 import * as ComputeAgentService from '@dxos/compute/AgentService';
 import * as Instructions from '@dxos/compute/Instructions';
 import * as Operation from '@dxos/compute/Operation';
@@ -213,9 +214,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;
           }),
         })),
     ),
@@ -597,7 +597,7 @@ describe('Agent Service', { tags: ['model-fixture'] }, () => {
         const target = Obj.getURI(session.chat);
         // `list` erases the RPC group to `any`, which Effect 4 resolves to an `unknown` requirement
         // on every call; naming the group restores it.
-        const handles: readonly Process.Handle<string | readonly ContentBlock.Any[], void, HarnessControlRpcs>[] =
+        const handles: readonly Process.Process<string | readonly ContentBlock.Any[], void, HarnessControlRpcs>[] =
           yield* processManager.list({
             target,
             key: AGENT_PROCESS_KEY,

package/src/agent-service/AgentService.ts

@@ -10,10 +10,9 @@ import * as Layer from 'effect/Layer';
 import * as Atom from 'effect/reactivity/Atom';
 import * as Semaphore from 'effect/Semaphore';
 
-import { AiContext } from '@dxos/assistant';
+import { AiContext, type HarnessControlRpcs } from '@dxos/assistant';
 import * as Chat from '@dxos/assistant/Chat';
 import * as AgentService from '@dxos/compute/AgentService';
-import * as Operation from '@dxos/compute/Operation';
 import * as Process from '@dxos/compute/Process';
 import * as Skill from '@dxos/compute/Skill';
 import { Annotation, Database, Feed, Obj, Ref, Registry } from '@dxos/echo';
@@ -22,24 +21,12 @@ import { DXN, EID, type SpaceId } from '@dxos/keys';
 import { log } from '@dxos/log';
 import type { ContentBlock } from '@dxos/types';
 
-import { AGENT_PROCESS_KEY, AgentProcess } from './agent-process.ts';
+import { AGENT_PROCESS_KEY, type AgentInput, AgentProcess, type AgentProcessDefinition } from './agent-process.ts';
 import { type DelegationStrategy } from './delegation-strategy.ts';
 import { type MakeTurnProducer } from './turn-producer.ts';
 
-/** The RPC control surface declared by {@link AgentProcess}, recovered from the executable type. */
-type AgentRpcs = ReturnType<typeof AgentProcess> extends Operation.Durable<any, any, any, infer Rpcs> ? Rpcs : never;
-
-/**
- * Live handle to a spawned {@link AgentProcess}, carrying its `HarnessControl` RPC surface.
- *
- * Derived from the definition rather than restated: `Process` exposes its input/output codecs, which
- * puts `_Input` in an invariant position, so a hand-written `ContentBlock.Any[]` no longer relates to
- * the `readonly` array the process's own schema yields.
- */
-type AgentHandle =
-  ReturnType<typeof AgentProcess> extends Operation.Durable<infer Input, infer Output, any, infer Rpcs>
-    ? Process.Handle<Input, Output, Rpcs>
-    : never;
+/** Live handle to a spawned agent process, carrying its `HarnessControl` RPC surface. */
+type AgentHandle = Process.Process<AgentInput, void, HarnessControlRpcs>;
 
 // TODO(burdon): Agent identity?
 export interface CreateSessionOptions {
@@ -111,6 +98,15 @@ export interface Options {
    * child processes and folds their results back into the conversation. Absent — a plain agent.
    */
   delegationStrategy?: DelegationStrategy;
+
+  /**
+   * Process definitions a chat can name in `chat.session.process` to run on instead of
+   * {@link AgentProcess}. Read per session, so a definition contributed after the layer was built
+   * is still found.
+   */
+  processes?: () => readonly AgentProcessDefinition[];
+  /** Keep each session's process resident between turns (see `AgentProcessOptions.resident`). */
+  resident?: boolean;
 }
 
 /**
@@ -159,6 +155,7 @@ export const layer = (opts?: Options): Layer.Layer<AgentService.AgentService, ne
           provider: DXN.DXN | undefined;
           instructions: string | undefined;
           location: AgentService.AgentLocation;
+          process: string;
           handle: AgentHandle;
           session: AgentService.Session;
         }
@@ -187,25 +184,52 @@ export const layer = (opts?: Options): Layer.Layer<AgentService.AgentService, ne
           provider: provider ?? opts?.provider,
           enableToolBackgrounding: opts?.enableToolBackgrounding,
           delegationStrategy: opts?.delegationStrategy,
+          resident: opts?.resident,
         });
 
+      /**
+       * The process a chat runs on: the one its session names, or ours. A name nothing contributed
+       * (its plugin was removed) falls back to ours rather than leaving the chat unable to run.
+       */
+      const executableFor = (chat: AgentService.Conversation, provider?: DXN.DXN): AgentProcessDefinition => {
+        const key = chat.session?.process;
+        if (key === undefined || key === AGENT_PROCESS_KEY) {
+          return makeExecutable(provider);
+        }
+        const definition = opts?.processes?.().find((candidate) => candidate.key === key);
+        if (!definition) {
+          log.warn('agent process not contributed; running the default', { key });
+          return makeExecutable(provider);
+        }
+        return definition;
+      };
+
       const hydrateAgents = Effect.fnUntraced(function* () {
         // Handles cached before shutdown are suspended and no longer registered with the manager.
         sessionCache.clear();
 
+        // Contributed processes run only locally (see `getSession`), so only ours is looked for on edge.
+        const contributed = (opts?.processes?.() ?? []).filter(({ key }) => key !== AGENT_PROCESS_KEY);
         const executable = makeExecutable();
         // Local, plus every space a session has already been opened on this run. A fresh client knows
         // no edge spaces yet and cannot enumerate them (one manager spans them all), but an edge agent
         // does not need the pre-warm: `getSession` reattaches to a process still running for its
         // chat, which is the path opening one takes.
         const agents = [
-          ...(yield* processManager.handles({ key: AGENT_PROCESS_KEY })),
+          ...(yield* processManager.handles({ key: AGENT_PROCESS_KEY })).map((agent) => ({ agent, executable })),
+          ...(yield* Effect.forEach(contributed, (definition) =>
+            processManager
+              .handles({ key: definition.key })
+              .pipe(Effect.map((agents) => agents.map((agent) => ({ agent, executable: definition })))),
+          )).flat(),
           ...(yield* Effect.forEach([...remoteSpaces], (space) =>
             processManager.handles({ key: AGENT_PROCESS_KEY, location: { kind: 'edge', space } }),
-          )).flat(),
+          ))
+            .flat()
+            .map((agent) => ({ agent, executable })),
         ];
         log('agent hydrate', { count: agents.length });
-        for (const agent of agents) {
+        for (const { agent, executable } of agents) {
           yield* agent
             .hydrate(executable)
             .pipe(
@@ -227,6 +251,13 @@ export const layer = (opts?: Options): Layer.Layer<AgentService.AgentService, ne
                 const model = chat.session?.model;
                 const instructions = chat.instructions?.uri;
                 const location: AgentService.AgentLocation = options?.location ?? 'local';
+                const executable = executableFor(chat, provider);
+                if (location === 'edge' && executable.key !== AGENT_PROCESS_KEY) {
+                  // EDGE spawns by key from its own registry, which holds no process a plugin contributed.
+                  return yield* Effect.die(
+                    new Error(`Agent process ${executable.key} runs only locally, but the chat asked for edge.`),
+                  );
+                }
                 const cached = sessionCache.get(chat.id);
                 if (cached) {
                   if (
@@ -234,13 +265,14 @@ export const layer = (opts?: Options): Layer.Layer<AgentService.AgentService, ne
                     cached.provider === provider &&
                     cached.instructions === instructions &&
                     cached.location === location &&
+                    cached.process === executable.key &&
                     !Process.isTerminal(cached.handle.status.state)
                   ) {
                     return cached.session;
                   }
 
                   if (!Process.isTerminal(cached.handle.status.state)) {
-                    // Model, provider, steering instructions or location changed (e.g. the user
+                    // Model, provider, steering instructions, location or process changed (e.g. the user
                     // toggled online/offline, or moved the chat to the cloud): terminate the
                     // existing process so the conversation continues on a fresh process bound to the new
                     // configuration. Conversation history is preserved via the feed, which the new
@@ -255,7 +287,6 @@ export const layer = (opts?: Options): Layer.Layer<AgentService.AgentService, ne
                 const parsedEchoUri = EID.tryParse(target);
                 const spaceId = parsedEchoUri ? EID.getSpaceId(parsedEchoUri) : undefined;
                 const processLocation = locationFor(options?.location, spaceId);
-                const executable = makeExecutable(provider);
 
                 // Reuse a still-running process for this feed only when there was no cached session
                 // (e.g. after the UI remounted). A process adopted this way re-reads the chat when it
@@ -330,7 +361,15 @@ export const layer = (opts?: Options): Layer.Layer<AgentService.AgentService, ne
                     Effect.provide(databaseContext),
                   );
                 const session = makeSession(handle, chat, feed, releaseSession, isFinished, resubmit);
-                sessionCache.set(chat.id, { model, provider, instructions, location, handle, session });
+                sessionCache.set(chat.id, {
+                  model,
+                  provider,
+                  instructions,
+                  location,
+                  process: executable.key,
+                  handle,
+                  session,
+                });
                 return session;
               }),
             ),
@@ -390,5 +429,5 @@ const makeSession = (
   // turn open, so anything it did afterwards would land after the reader's next prompt. The next
   // process to spawn on this feed discards what it inherits instead (see `onSpawn` in agent-process).
   terminate: () => process.terminate().pipe(Effect.tap(() => Effect.sync(releaseSession))),
-  subscribeEphemeral: () => process.subscribeEphemeral(),
+  subscribeEphemeral: (options) => process.subscribeEphemeral(options),
 });

package/src/agent-service/README.md

@@ -14,8 +14,8 @@ the agent/plan ECHO types (it cannot depend on `@dxos/assistant-toolkit`).
 
 ```mermaid
 flowchart TB
-  subgraph rt["@dxos/compute-runtime"]
-    POI["ProcessOperationInvoker<br/>invokeFiber() / attachFiber()<br/><i>(linked child)</i>"]
+  subgraph rt["@dxos/compute"]
+    POI["Process.ManagerService<br/>Process.spawn() / attach()<br/><i>(linked child)</i>"]
   end
 
   subgraph fr["@dxos/functions-runtime · agent-service"]
@@ -40,9 +40,9 @@ flowchart TB
   IMPL --> CAP
 ```
 
-- **`ProcessOperationInvoker`** (runtime primitive, no AI): `invokeFiber` spawns a linked,
-  non-blocking child and returns a fiber with `pid`; `attachFiber` + `fiber.await` reads the
-  finished child's `Exit`.
+- **`Process.ManagerService`** (runtime primitive, no AI): the process's own manager links every child
+  it spawns to the process. `Process.spawn` spawns an operation as such a child and returns its
+  `Process.Process`; `attach(pid)` + `Process.awaitOutput` reads the finished child's result.
 - **`DelegationStrategy`** (this dir, type-only): the pluggable policy `AgentProcess` calls —
   `reconcile` (what to delegate) and `onComplete` (how to fold a result back). Absent → plain chat.
 - **`makeDelegationStrategy()`** (assistant-toolkit): the concrete, agent/plan-aware implementation,
@@ -51,7 +51,7 @@ flowchart TB
 ## Delegation lifecycle
 
 The child's exit is only a **wake signal** — its output value is read separately via
-`attachFiber` + `fiber.await` (the `ChildEvent` does not carry the payload). `DelegationsKey` persists the
+`attach(pid)` + `Process.awaitOutput` (the `ChildEvent` does not carry the payload). `DelegationsKey` persists the
 `pid → id` map so a child that exits after the supervisor hibernates can still be correlated.
 
 ```mermaid
@@ -59,7 +59,7 @@ sequenceDiagram
   participant U as User
   participant AP as AgentProcess (supervisor)
   participant ST as DelegationStrategy
-  participant POI as ProcessOperationInvoker
+  participant POI as Process.ManagerService
   participant CH as Sub-agent (child process)
 
   U->>AP: submitInput(prompt)
@@ -67,7 +67,7 @@ sequenceDiagram
   AP->>ST: reconcile(chat, activeIds)
   ST-->>AP: Delegation[] { id, spawn }
   loop per delegation
-    AP->>POI: invokeFiber(op, input)
+    AP->>POI: Process.spawn(op, input)
     POI->>CH: linked child (non-blocking)
     POI-->>AP: pid
     AP->>AP: DelegationsKey.set(pid → id)
@@ -76,7 +76,7 @@ sequenceDiagram
 
   CH-->>AP: exit (wake only — no payload)
   AP->>AP: onChildEvent: match pid → id, drop from DelegationsKey
-  AP->>POI: attachFiber(pid) + await
+  AP->>POI: attach(pid) + Process.awaitOutput
   POI-->>AP: Exit of output value
   AP->>ST: onComplete(chat, id, exit)
   ST->>U: update Task status + post message (reference blocks → dx-anchor)
@@ -89,5 +89,5 @@ sequenceDiagram
 | `AgentService` / `layer` | `AgentService.ts` | Per-chat session cache (model-aware); wires `delegationStrategy` into `AgentProcess`. |
 | `AgentProcess` | `agent-process.ts` | Turn loop (`onAlarm`) + child-exit wake (`onChildEvent`); owns `DelegationsKey`. |
 | `DelegationStrategy`, `Delegation` | `delegation-strategy.ts` | Type-only seam: `reconcile` / `onComplete`; `Delegation = { id, spawn }`. |
-| `ProcessOperationInvoker.invokeFiber` / `attachFiber` | `@dxos/compute-runtime` | Linked-child spawn + result read. |
+| `Process.spawn` / `Process.Manager.attach` | `@dxos/compute` | Linked-child spawn + result read. |
 | `makeDelegationStrategy()` | `@dxos/assistant-toolkit` | Concrete agent/plan-aware strategy. |