@dxos/agent-runtime 0.0.0

package/src/agent-service/AgentService.ts

@@ -0,0 +1,239 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { AiContext } from '@dxos/assistant';
+import { McpServer, Process, Skill } from '@dxos/compute';
+import { ProcessManager } from '@dxos/compute-runtime';
+import {
+  AgentService,
+  type GetSessionOptions,
+  type Service,
+  type Session,
+  getSession,
+} from '@dxos/compute/AgentService';
+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 { AGENT_PROCESS_KEY, AgentProcess } from './agent-process';
+import { type DelegationStrategy } from './delegation-strategy';
+
+/** The RPC control surface declared by {@link AgentProcess}, recovered from the executable type. */
+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>;
+
+const isTerminalProcess = (state: Process.State): boolean =>
+  state === Process.State.SUCCEEDED || state === Process.State.FAILED || state === Process.State.TERMINATED;
+
+export interface CreateSessionOptions {
+  readonly skills?: Skill.Skill[];
+  readonly context?: Ref.Ref<Obj.Unknown>[];
+  readonly model?: DXN.DXN;
+  readonly provider?: DXN.DXN;
+  readonly systemPrompt?: string;
+}
+
+export const createSession: (
+  opts?: CreateSessionOptions,
+) => Effect.Effect<Session, Skill.NotFoundError, Database.Service | Registry.Service | AgentService> = Effect.fn(
+  'createSession',
+)(function* (opts) {
+  const skills = yield* Effect.forEach(opts?.skills ?? [], (skill) =>
+    Skill.upsert(Skill.getKey(skill)).pipe(Effect.map(Ref.make)),
+  );
+
+  const feed = yield* Database.add(Feed.make());
+  const runtime = yield* Effect.runtime<Database.Service>();
+  const binder = yield* EffectEx.acquireReleaseResource(() => new AiContext.Binder({ feed, runtime }));
+
+  yield* Effect.promise(() =>
+    binder.bind({
+      skills,
+      objects: opts?.context ?? [],
+    }),
+  );
+
+  return yield* getSession(feed, { model: opts?.model, provider: opts?.provider });
+}, Effect.scoped);
+
+export interface AgentServiceOptions {
+  systemPrompt?: string;
+  /**
+   * Default model used by sessions that don't specify one explicitly.
+   */
+  model?: DXN.DXN;
+
+  /**
+   * Default provider used to resolve the model for sessions that don't specify one explicitly.
+   */
+  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.
+   *
+   * @default false
+   */
+  enableToolBackgrounding?: boolean;
+
+  /**
+   * When provided, sessions act as supervisors: the agent delegates outstanding work to sub-agent
+   * child processes and folds their results back into the conversation. Absent — a plain agent.
+   */
+  delegationStrategy?: DelegationStrategy;
+}
+
+export const layer = (opts?: AgentServiceOptions): Layer.Layer<AgentService, never, ProcessManager.Service> =>
+  Layer.effect(
+    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).
+      const sessionCache = new Map<
+        string,
+        { model: DXN.DXN | undefined; provider: DXN.DXN | undefined; handle: AgentHandle; session: Session }
+      >();
+
+      const makeExecutable = (model?: DXN.DXN, provider?: DXN.DXN) =>
+        AgentProcess({
+          systemPrompt: opts?.systemPrompt,
+          model: model ?? opts?.model,
+          provider: provider ?? opts?.provider,
+          getMcpServers: opts?.getMcpServers,
+          enableToolBackgrounding: opts?.enableToolBackgrounding,
+          delegationStrategy: opts?.delegationStrategy,
+        });
+
+      const hydrateAgents = Effect.fnUntraced(function* () {
+        // Handles cached before shutdown are suspended and no longer registered with the manager.
+        sessionCache.clear();
+
+        const executable = makeExecutable();
+        const agents = yield* processManager.list({ key: AGENT_PROCESS_KEY });
+        log('agent hydrate', { count: agents.length });
+        for (const agent of agents) {
+          yield* agent
+            .hydrate(executable)
+            .pipe(
+              Effect.catchAllCause((cause) =>
+                Effect.sync(() => log.warn('agent hydrate skipped', { pid: agent.pid, cause: Cause.pretty(cause) })),
+              ),
+            );
+        }
+      });
+
+      const service: Service = {
+        getSession: (feed: Feed.Feed, options?: GetSessionOptions) =>
+          Effect.gen(function* () {
+            const model = options?.model ?? opts?.model;
+            const provider = options?.provider ?? opts?.provider;
+            const cached = sessionCache.get(feed.id);
+            if (cached) {
+              if (
+                cached.model === model &&
+                cached.provider === provider &&
+                !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
+                // 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.
+                yield* cached.handle.terminate();
+              }
+              sessionCache.delete(feed.id);
+            }
+
+            const target = Obj.getURI(feed);
+            const parsedEchoUri = EID.tryParse(target);
+            const spaceId = parsedEchoUri ? EID.getSpaceId(parsedEchoUri) : undefined;
+            const executable = makeExecutable(model, provider);
+
+            // Reuse a still-running process for this feed only when there was no cached session
+            // (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 handle: AgentHandle;
+            if (activeProcess) {
+              yield* activeProcess.hydrate(executable);
+              handle = activeProcess;
+            } else {
+              handle = yield* processManager.spawn(executable, {
+                name: 'Agent',
+                target,
+                // Stamp the host marker so the harness control surface is discoverable by annotation
+                // lookup (set once at spawn, immutable — the identity plane).
+                annotations: Annotation.buildDictionary((dictionary) => {
+                  Annotation.setDictionary(dictionary, Process.HarnessHostAnnotation, true);
+                }),
+                environment: {
+                  ...(spaceId !== undefined ? { space: spaceId } : {}),
+                  conversation: target,
+                },
+                traceMeta: {
+                  conversation: Ref.make(feed),
+                },
+              });
+            }
+
+            const releaseSession = () => {
+              sessionCache.delete(feed.id);
+            };
+            const session = makeSession(handle, feed, releaseSession);
+            sessionCache.set(feed.id, { model, provider, handle, session });
+            return session;
+          }),
+        hydrate: hydrateAgents,
+      };
+
+      return service;
+    }),
+  );
+
+const makeSession = (process: AgentHandle, feed: Feed.Feed, releaseSession: () => void): Session => ({
+  feed,
+  getContext: () =>
+    Effect.gen(function* () {
+      const runtime = yield* Effect.runtime<Database.Service>();
+      const binder = yield* EffectEx.acquireReleaseResource(() => new AiContext.Binder({ feed, runtime }));
+      return binder.getObjects().map((object) => Ref.make(object));
+    }).pipe(Effect.scoped),
+  addContext: (context: Ref.Ref<Obj.Unknown>[]) =>
+    Effect.gen(function* () {
+      const runtime = yield* Effect.runtime<Database.Service>();
+      const binder = yield* EffectEx.acquireReleaseResource(() => new AiContext.Binder({ feed, runtime }));
+      yield* Effect.promise(() =>
+        binder.bind({
+          skills: [],
+          objects: context,
+        }),
+      );
+    }).pipe(Effect.scoped),
+  submitPrompt: (prompt: string) => 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(),
+  terminate: () => process.terminate().pipe(Effect.tap(() => Effect.sync(releaseSession))),
+  subscribeEphemeral: () => process.subscribeEphemeral(),
+});

package/src/agent-service/README.md

@@ -0,0 +1,91 @@
+# 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.
+
+## Layering
+
+The supervisor behaviour is split across three layers so `@dxos/functions-runtime` stays agnostic of
+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>"]
+  end
+
+  subgraph fr["@dxos/functions-runtime · agent-service"]
+    AS["AgentService.layer({ delegationStrategy? })"]
+    AP["AgentProcess<br/>onAlarm (turn) · onChildEvent (wake)<br/>DelegationsKey: pid → id"]
+    SS["DelegationStrategy <i>(type-only seam)</i><br/>reconcile() / onComplete()"]
+    AS --> AP
+    AP -. "calls" .-> SS
+    AP --> POI
+  end
+
+  subgraph tk["@dxos/assistant-toolkit"]
+    IMPL["makeDelegationStrategy()<br/>reconcile: delegated plan tasks → Routine + AgentPrompt<br/>onComplete: update Task · addArtifact · post message"]
+  end
+
+  subgraph pa["plugin-automation"]
+    CAP["AgentDelegationStrategy capability"]
+  end
+
+  IMPL -. "implements" .-> SS
+  CAP -. "provides impl to" .-> AS
+  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`.
+- **`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,
+  contributed by `plugin-automation` and injected through `AgentService.layer`.
+
+## 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
+`pid → id` map so a child that exits after the supervisor hibernates can still be correlated.
+
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant AP as AgentProcess (supervisor)
+  participant ST as DelegationStrategy
+  participant POI as ProcessOperationInvoker
+  participant CH as Sub-agent (child process)
+
+  U->>AP: submitInput(prompt)
+  AP->>AP: onAlarm → run AiSession turn (tools may record delegated plan tasks)
+  AP->>ST: reconcile(feed, activeIds)
+  ST-->>AP: Delegation[] { id, spawn }
+  loop per delegation
+    AP->>POI: invokeFiber(op, input)
+    POI->>CH: linked child (non-blocking)
+    POI-->>AP: pid
+    AP->>AP: DelegationsKey.set(pid → id)
+  end
+  Note over AP: turn settles via runUntilSettled — supervisor stays IDLE/HYBERNATING and accepts more input
+
+  CH-->>AP: exit (wake only — no payload)
+  AP->>AP: onChildEvent: match pid → id, drop from DelegationsKey
+  AP->>POI: attachFiber(pid) + await
+  POI-->>AP: Exit of output value
+  AP->>ST: onComplete(feed, id, exit)
+  ST->>U: update Task status + post message (reference blocks → dx-anchor)
+```
+
+## Key types
+
+| Symbol | Where | Role |
+| --- | --- | --- |
+| `AgentService` / `layer` | `AgentService.ts` | Per-feed 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. |
+| `makeDelegationStrategy()` | `@dxos/assistant-toolkit` | Concrete agent/plan-aware strategy. |

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

@@ -0,0 +1,206 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as KeyValueStore from '@effect/platform/KeyValueStore';
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { Process } from '@dxos/compute';
+import { storageServiceLayer } from '@dxos/compute-runtime';
+import { ContentBlock } from '@dxos/types';
+
+import { AlarmManager, computeAlarmDelay, isAgentWorkPending } from './agent-process';
+
+const NOW = new Date('2026-06-04T12:00:00.000Z').getTime();
+
+/** Builds a fresh in-memory storage service for a single test. */
+const makeStorage = Effect.gen(function* () {
+  const kvStore = yield* KeyValueStore.KeyValueStore;
+  return storageServiceLayer(kvStore, 'agent/');
+}).pipe(Effect.provide(KeyValueStore.layerMemory));
+
+/** AlarmManager with a captured `setAlarm` and a fixed clock for deterministic assertions. */
+const makeManager = Effect.fnUntraced(function* (now: number = NOW) {
+  const storageService = yield* makeStorage;
+  const alarmCalls: Array<number | undefined> = [];
+  const alarmManager = new AlarmManager({
+    storageService,
+    setAlarm: (timeout) => alarmCalls.push(timeout),
+    now: () => now,
+  });
+  return { alarmManager, alarmCalls, storageService };
+});
+
+describe('computeAlarmDelay', () => {
+  it('wakes immediately when there is pending work', ({ expect }) => {
+    expect(computeAlarmDelay({ hasPendingWork: true, wakeAt: NOW + 10_000, now: NOW })).toBe(0);
+    expect(computeAlarmDelay({ hasPendingWork: true, wakeAt: null, now: NOW })).toBe(0);
+  });
+
+  it('schedules a future self-wake when idle', ({ expect }) => {
+    expect(computeAlarmDelay({ hasPendingWork: false, wakeAt: NOW + 10_000, now: NOW })).toBe(10_000);
+  });
+
+  it('wakes immediately when a self-wake is already due', ({ expect }) => {
+    expect(computeAlarmDelay({ hasPendingWork: false, wakeAt: NOW - 10_000, now: NOW })).toBe(0);
+  });
+
+  it('schedules nothing when idle and no self-wake is set', ({ expect }) => {
+    expect(computeAlarmDelay({ hasPendingWork: false, wakeAt: null, now: NOW })).toBe(null);
+  });
+});
+
+describe('AlarmManager', () => {
+  it.effect(
+    'tracks and persists the next self-wake, syncing with setAlarm',
+    Effect.fnUntraced(function* ({ expect }) {
+      const { alarmManager, alarmCalls, storageService } = yield* makeManager();
+
+      yield* alarmManager.load();
+      expect(alarmManager.wakeAt).toBe(null);
+
+      yield* alarmManager.setWakeAt(NOW + 60_000);
+      expect(alarmManager.wakeAt).toBe(NOW + 60_000);
+
+      // Reconcile schedules the underlying process alarm for the self-wake delay.
+      alarmManager.reconcile(false);
+      expect(alarmCalls).toEqual([60_000]);
+
+      // A new manager backed by the same storage recovers the persisted alarm.
+      const recovered = new AlarmManager({ storageService, setAlarm: () => {}, now: () => NOW });
+      yield* recovered.load();
+      expect(recovered.wakeAt).toBe(NOW + 60_000);
+    }),
+  );
+
+  it.effect(
+    'reconcile prefers pending work over a future self-wake',
+    Effect.fnUntraced(function* ({ expect }) {
+      const { alarmManager, alarmCalls } = yield* makeManager();
+      yield* alarmManager.setWakeAt(NOW + 60_000);
+
+      alarmManager.reconcile(true);
+      expect(alarmCalls).toEqual([0]);
+    }),
+  );
+
+  it.effect(
+    'reconcile schedules nothing when idle without a self-wake',
+    Effect.fnUntraced(function* ({ expect }) {
+      const { alarmManager, alarmCalls } = yield* makeManager();
+      yield* alarmManager.load();
+
+      alarmManager.reconcile(false);
+      expect(alarmCalls).toEqual([]);
+    }),
+  );
+
+  it.effect(
+    'takeFiredAlarm clears and returns a due alarm, persisting the cleared state',
+    Effect.fnUntraced(function* ({ expect }) {
+      const { alarmManager, storageService } = yield* makeManager();
+      yield* alarmManager.setWakeAt(NOW - 1_000);
+
+      const fired = yield* alarmManager.takeFiredAlarm();
+      expect(fired).toEqual({ firedAt: NOW - 1_000, message: null });
+      expect(alarmManager.wakeAt).toBe(null);
+
+      const recovered = new AlarmManager({ storageService, setAlarm: () => {}, now: () => NOW });
+      yield* recovered.load();
+      expect(recovered.wakeAt).toBe(null);
+    }),
+  );
+
+  it.effect(
+    'takeFiredAlarm leaves a future alarm untouched',
+    Effect.fnUntraced(function* ({ expect }) {
+      const { alarmManager } = yield* makeManager();
+      yield* alarmManager.setWakeAt(NOW + 60_000);
+
+      const fired = yield* alarmManager.takeFiredAlarm();
+      expect(fired).toBe(null);
+      expect(alarmManager.wakeAt).toBe(NOW + 60_000);
+    }),
+  );
+
+  it.effect(
+    'persists and restores the reminder message alongside the self-wake',
+    Effect.fnUntraced(function* ({ expect }) {
+      const { alarmManager, storageService } = yield* makeManager();
+      yield* alarmManager.setWakeAt(NOW - 1_000, 'check the build');
+      expect(alarmManager.message).toBe('check the build');
+
+      // A new manager backed by the same storage recovers both the timestamp and the message.
+      const recovered = new AlarmManager({ storageService, setAlarm: () => {}, now: () => NOW });
+      yield* recovered.load();
+      expect(recovered.wakeAt).toBe(NOW - 1_000);
+      expect(recovered.message).toBe('check the build');
+
+      const fired = yield* recovered.takeFiredAlarm();
+      expect(fired).toEqual({ firedAt: NOW - 1_000, message: 'check the build' });
+      expect(recovered.message).toBe(null);
+    }),
+  );
+});
+
+// The completion decision (`maybeComplete` → `ctx.succeed()`) is exercised at two levels: the
+// `isAgentWorkPending` suite below covers the predicate the process consults (queue / alarm /
+// delegations / pending tool results), and `AgentService.test.ts` covers the process reaching a
+// terminal state and respawning for a follow-up turn end-to-end.
+
+describe('isAgentWorkPending', () => {
+  const makeSnapshot = (overrides: Partial<Parameters<typeof isAgentWorkPending>[0]> = {}) => {
+    const storageService = Effect.runSync(makeStorage);
+    const alarmManager = new AlarmManager({ storageService, setAlarm: () => {} });
+    return {
+      inputQueue: [],
+      alarmManager,
+      delegations: [],
+      toolCallManager: {
+        hasPendingToolResults: () => false,
+      },
+      ...overrides,
+    } satisfies Parameters<typeof isAgentWorkPending>[0];
+  };
+
+  it('is idle when nothing is pending', ({ expect }) => {
+    expect(isAgentWorkPending(makeSnapshot())).toBe(false);
+  });
+
+  it('is pending when the input queue has work', ({ expect }) => {
+    expect(
+      isAgentWorkPending(
+        makeSnapshot({
+          inputQueue: [{ _tag: 'prompt', content: [ContentBlock.Text.make({ text: 'hello' })] }],
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it('is pending when a self-wake alarm is scheduled', ({ expect }) => {
+    const snapshot = makeSnapshot();
+    Effect.runSync(snapshot.alarmManager.setWakeAt(NOW + 60_000));
+    expect(isAgentWorkPending(snapshot)).toBe(true);
+  });
+
+  it('is pending when subprocess delegations are in flight', ({ expect }) => {
+    expect(
+      isAgentWorkPending(
+        makeSnapshot({
+          delegations: [{ pid: Process.ID.make('child-1'), id: 'task-1' }],
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it('is pending when tool results have not been delivered', ({ expect }) => {
+    expect(
+      isAgentWorkPending(
+        makeSnapshot({
+          toolCallManager: { hasPendingToolResults: () => true },
+        }),
+      ),
+    ).toBe(true);
+  });
+});