@dxos/agent-runtime 0.13.0 → 0.14.0

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

@@ -0,0 +1,135 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import { expect } from 'vitest';
+
+import { HarnessControl } 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 { Annotation, Database, Feed, Obj, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { Message } from '@dxos/types';
+
+import { AssistantTestLayer, waitForMessage } from '../testing/index.ts';
+import { AGENT_PROCESS_KEY, AgentInput, type AgentProcessDefinition, makeInputMessage } from './agent-process.ts';
+
+const ECHO_PROCESS_KEY = 'com.example.process.echo';
+
+/** Answers each prompt with its own text, so a test can tell which process ran the chat. */
+const EchoProcess: AgentProcessDefinition = Operation.makeDurable({
+  key: ECHO_PROCESS_KEY,
+  input: AgentInput,
+  output: Schema.Void,
+  types: [Chat.Chat, Feed.Feed, Message.Message],
+  services: [Database.Service],
+  rpcs: HarnessControl,
+}).pipe(
+  Operation.withDurableHandler((ctx) =>
+    Effect.gen(function* () {
+      const chatDxn = Option.getOrThrow(Annotation.getDictionary(ctx.params.annotations, Process.TargetAnnotation));
+      const chat = yield* Database.resolve(chatDxn, Chat.Chat).pipe(Effect.orDie);
+      const feed = yield* Database.load(chat.feed).pipe(Effect.orDie);
+      const reply = (text: string) =>
+        Feed.append(feed, [
+          Message.make({ sender: { role: 'assistant' }, blocks: [{ _tag: 'text', text: `echo: ${text}` }] }),
+        ]);
+      return {
+        rpcHandlers: yield* HarnessControl.toHandlers({
+          setAlarm: () => Effect.void,
+          enqueueMessage: () => Effect.void,
+        }),
+        onInput: (input) => reply(Message.extractText(makeInputMessage(input))),
+      };
+    }),
+  ),
+);
+
+const TestLayer = AssistantTestLayer({
+  types: [Feed.Feed],
+  agent: { processes: () => [EchoProcess] },
+});
+
+const makeChat = Effect.fnUntraced(function* (process?: string) {
+  const feed = yield* Database.add(Feed.make());
+  return yield* Database.add(Chat.make({ feed: Ref.make(feed), ...(process ? { session: { process } } : {}) }));
+});
+
+const runningKeys = Effect.gen(function* () {
+  const manager = yield* Process.ManagerService;
+  const processes = yield* manager.handles();
+  return processes.map((process) => process.key);
+});
+
+describe('AgentService process selection', () => {
+  it.effect(
+    'runs a chat on the process its session names',
+    Effect.fnUntraced(
+      function* (_) {
+        const chat = yield* makeChat(ECHO_PROCESS_KEY);
+        const session = yield* AgentService.getSession(chat);
+        yield* session.submitPrompt('hello');
+        const reply = yield* waitForMessage(session.feed, (message) => message.sender.role === 'assistant', {
+          timeout: 5_000,
+        });
+        expect(Message.extractText(reply)).toBe('echo: hello');
+        expect(yield* runningKeys).toEqual([ECHO_PROCESS_KEY]);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    "runs a chat that names no process, or one nothing contributed, on the assistant's",
+    Effect.fnUntraced(
+      function* (_) {
+        yield* AgentService.getSession(yield* makeChat());
+        yield* AgentService.getSession(yield* makeChat('com.example.process.uninstalled'));
+        expect(yield* runningKeys).toEqual([AGENT_PROCESS_KEY, AGENT_PROCESS_KEY]);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'moves a chat to the process its session names when that changes',
+    Effect.fnUntraced(
+      function* (_) {
+        const chat = yield* makeChat();
+        yield* AgentService.getSession(chat);
+        Obj.update(chat, (chat) => {
+          chat.session = { ...chat.session, process: ECHO_PROCESS_KEY };
+        });
+        yield* AgentService.getSession(chat);
+        const manager = yield* Process.ManagerService;
+        const live = (yield* manager.handles()).filter((process) => process.status.state !== Process.State.TERMINATED);
+        expect(live.map((process) => process.key)).toEqual([ECHO_PROCESS_KEY]);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'refuses to run a contributed process on edge',
+    Effect.fnUntraced(
+      function* (_) {
+        const chat = yield* makeChat(ECHO_PROCESS_KEY);
+        const exit = yield* AgentService.getSession(chat, { location: 'edge' }).pipe(Effect.exit);
+        expect(Exit.isFailure(exit)).toBe(true);
+        expect(yield* runningKeys).toEqual([]);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

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

@@ -11,8 +11,11 @@ import { expect } from 'vitest';
 
 import { ScriptedLanguageModel } from '@dxos/ai/testing';
 import { Alarm, SessionStore, isConsumed, isQueued } from '@dxos/assistant';
+import { ProcessManager } from '@dxos/compute-runtime';
+import * as ComputeAgentService from '@dxos/compute/AgentService';
 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 { type Database, Feed, Filter, Obj } from '@dxos/echo';
 import * as RuntimeProvider from '@dxos/effect/RuntimeProvider';
@@ -21,6 +24,7 @@ import { DXN, EntityId } from '@dxos/keys';
 import { Message } from '@dxos/types';
 
 import { AssistantTestLayer } from '../testing/index.ts';
+import { AGENT_PROCESS_KEY } from './agent-process.ts';
 import * as AgentService from './AgentService.ts';
 
 const { text, toolCall, scriptedAiService } = ScriptedLanguageModel;
@@ -139,6 +143,41 @@ const readFeed = (feed: Feed.Feed) =>
     return { items, messages, ...pending };
   });
 
+describe('AgentProcess residency (scripted)', () => {
+  it.effect(
+    'a resident process stays idle after its turn and takes the next prompt itself',
+    Effect.fnUntraced(
+      function* (_) {
+        const processManager = yield* ProcessManager.ProcessManagerService;
+        const session = yield* AgentService.createSession();
+        const target = Obj.getURI(session.chat);
+
+        yield* session.submitPrompt('first');
+        yield* session.waitForCompletion();
+        const [handle] = yield* processManager.list({ target, key: AGENT_PROCESS_KEY });
+        expect(handle.status.state).toBe(Process.State.IDLE);
+
+        // The same session, the same process: no respawn (and no history replay) for a follow-up.
+        const followUp = yield* ComputeAgentService.getSession(session.chat);
+        yield* followUp.submitPrompt('second');
+        yield* followUp.waitForCompletion();
+        const processes = yield* processManager.list({ target, key: AGENT_PROCESS_KEY });
+        expect(processes.map((process) => String(process.pid))).toEqual([String(handle.pid)]);
+        expect(new Set(promptTexts((yield* readFeed(session.feed)).messages))).toEqual(new Set(['first', 'second']));
+      },
+      Effect.provide(
+        AssistantTestLayer({
+          types: [Alarm.Alarm],
+          agent: { resident: true },
+          aiService: scriptedAiService(Array.from({ length: 4 }, () => ({ parts: [text('Acknowledged.')] }))),
+        }),
+      ),
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 30_000 },
+  );
+});
+
 describe('AgentProcess input queue (scripted)', () => {
   it.effect(
     'a submitted prompt is queued on the feed, then acked by the turn that consumes it',

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

@@ -7,7 +7,13 @@ import { describe, it } from 'vitest';
 import * as Process from '@dxos/compute/Process';
 import { type ContentBlock } from '@dxos/types';
 
-import { type ToolResultEvent, dropReportedToolResults, toolResultPrompt, wakeUpPrompt } from './agent-process.ts';
+import {
+  type ToolResultEvent,
+  dropReportedToolResults,
+  isToolResultHandled,
+  toolResultPrompt,
+  wakeUpPrompt,
+} from './agent-process.ts';
 
 // Recovering a tool result across a reload was, until now, exercised only when a race inside
 // `AgentService.test.ts`'s `recovers queued tool results after reload` happened to land on it, and no
@@ -55,6 +61,22 @@ describe('dropReportedToolResults', () => {
   });
 });
 
+// A tool child that can no longer be reattached is answered with an error unless its result is already
+// accounted for; otherwise the call would stay pending and the agent could never complete.
+describe('isToolResultHandled', () => {
+  it('is handled when the result is queued for the next turn', ({ expect }) => {
+    expect(isToolResultHandled([toolResult('1')], Process.ID.make('1'), () => false)).toBe(true);
+  });
+
+  it('is handled when the result already reached the agent', ({ expect }) => {
+    expect(isToolResultHandled([], Process.ID.make('1'), (pid) => pid === Process.ID.make('1'))).toBe(true);
+  });
+
+  it('is not handled when the result was neither queued nor reported', ({ expect }) => {
+    expect(isToolResultHandled([toolResult('2')], Process.ID.make('1'), () => false)).toBe(false);
+  });
+});
+
 describe('toolResultPrompt', () => {
   it('redelivers a recovered tool result as a synthetic <result> block', ({ expect }) => {
     const [block] = toolResultPrompt(toolResult('9', 'listed on the NASDAQ'));

package/src/agent-service/skill-hooks.test.ts

@@ -0,0 +1,182 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { beforeEach, describe, expect, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { ScriptedLanguageModel } from '@dxos/ai/testing';
+import { ProcessManager } 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 * as Skill from '@dxos/compute/Skill';
+import { Feed, Obj, Ref } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { DXN, EntityId } from '@dxos/keys';
+import { Message } from '@dxos/types';
+
+import { AssistantTestLayer } from '../testing/index.ts';
+import { AGENT_PROCESS_KEY } from './agent-process.ts';
+import * as AgentService from './AgentService.ts';
+
+EntityId.dangerouslyDisableRandomness();
+
+const InlineHook = Operation.make({
+  meta: { key: DXN.make('com.example.operation.inlineHook'), name: 'Inline hook' },
+  input: Schema.Struct({}),
+  output: Schema.Void,
+});
+
+const BackgroundHook = Operation.make({
+  meta: { key: DXN.make('com.example.operation.backgroundHook'), name: 'Background hook' },
+  input: Schema.Struct({}),
+  output: Schema.Void,
+});
+
+const QuickHook = Operation.make({
+  meta: { key: DXN.make('com.example.operation.quickHook'), name: 'Quick hook' },
+  input: Schema.Struct({}),
+  output: Schema.Void,
+});
+
+const FailingHook = Operation.make({
+  meta: { key: DXN.make('com.example.operation.failingHook'), name: 'Failing hook' },
+  input: Schema.Struct({}),
+  output: Schema.Void,
+});
+
+/** Hook invocations in the order they started and finished, and the gate the background hook holds on. */
+type HookLog = { events: string[]; release: () => void; released: Promise<void> };
+
+const makeHookLog = (): HookLog => {
+  let release = () => {};
+  const released = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  return { events: [], release, released };
+};
+
+let hookLog = makeHookLog();
+
+const handlers = OperationHandlerSet.make(
+  InlineHook.pipe(Operation.withHandler(() => Effect.sync(() => void hookLog.events.push('inline')))),
+  BackgroundHook.pipe(
+    Operation.withHandler(() =>
+      Effect.gen(function* () {
+        hookLog.events.push('background:start');
+        yield* Effect.promise(() => hookLog.released);
+        hookLog.events.push('background:end');
+      }),
+    ),
+  ),
+  FailingHook.pipe(Operation.withHandler(() => Effect.die(new Error('hook failed')))),
+  QuickHook.pipe(Operation.withHandler(() => Effect.sync(() => void hookLog.events.push('quick')))),
+);
+
+const hook = (operation: Operation.Definition.Any, async: boolean): Skill.Hook => ({
+  spec: { _tag: 'end-request' },
+  async,
+  function: Ref.make(Operation.serialize(operation)),
+});
+
+const HookSkill = Skill.make({
+  key: 'com.example.skill.hooks',
+  name: 'Hooks',
+  hooks: [hook(InlineHook, false), hook(BackgroundHook, true)],
+});
+
+const FailingHookSkill = Skill.make({
+  key: 'com.example.skill.failingHooks',
+  name: 'Failing hooks',
+  hooks: [hook(FailingHook, true)],
+});
+
+// Finishes at once, so its exit can race the agent registering it.
+const QuickHookSkill = Skill.make({
+  key: 'com.example.skill.quickHooks',
+  name: 'Quick hooks',
+  hooks: [hook(QuickHook, true)],
+});
+
+const TestLayer = AssistantTestLayer({
+  operationHandlers: handlers,
+  types: [Skill.Skill, Feed.Feed, Message.Message],
+  skills: [HookSkill, FailingHookSkill, QuickHookSkill],
+  aiService: ScriptedLanguageModel.scriptedAiService(() => ({ parts: [ScriptedLanguageModel.text('Done.')] })),
+});
+
+/** The agent process serving the session's chat. */
+const agentProcess = Effect.fnUntraced(function* (session: { chat: Obj.Unknown }) {
+  const processManager = yield* ProcessManager.ProcessManagerService;
+  const [handle] = yield* processManager.list({ target: Obj.getURI(session.chat), key: AGENT_PROCESS_KEY });
+  return handle;
+});
+
+describe('end-request skill hooks', () => {
+  beforeEach(() => {
+    hookLog = makeHookLog();
+  });
+
+  it.effect(
+    'a background hook does not hold up the request, and the process awaits it before finishing',
+    Effect.fnUntraced(
+      function* (_) {
+        const session = yield* AgentService.createSession({ skills: [HookSkill] });
+        yield* session.submitPrompt('Hello.');
+        yield* session.waitForCompletion();
+
+        // The request settled while the background hook is still blocked; the inline hook ran first.
+        expect(hookLog.events).toEqual(['inline', 'background:start']);
+        const handle = yield* agentProcess(session);
+        expect(handle.status.state).not.toBe(Process.State.SUCCEEDED);
+
+        hookLog.release();
+        yield* Effect.promise(async () => {
+          await expect.poll(() => handle.status.state, { timeout: 5_000 }).toBe(Process.State.SUCCEEDED);
+        });
+        expect(hookLog.events).toEqual(['inline', 'background:start', 'background:end']);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'a background hook that finishes at once still lets the process finish',
+    Effect.fnUntraced(
+      function* (_) {
+        const session = yield* AgentService.createSession({ skills: [QuickHookSkill] });
+        yield* session.submitPrompt('Hello.');
+        yield* session.waitForCompletion();
+
+        const handle = yield* agentProcess(session);
+        yield* Effect.promise(async () => {
+          await expect.poll(() => handle.status.state, { timeout: 5_000 }).toBe(Process.State.SUCCEEDED);
+        });
+        expect(hookLog.events).toEqual(['quick']);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+
+  it.effect(
+    'a failing background hook still lets the process finish',
+    Effect.fnUntraced(
+      function* (_) {
+        const session = yield* AgentService.createSession({ skills: [FailingHookSkill] });
+        yield* session.submitPrompt('Hello.');
+        yield* session.waitForCompletion();
+
+        const handle = yield* agentProcess(session);
+        yield* Effect.promise(async () => {
+          await expect.poll(() => handle.status.state, { timeout: 5_000 }).toBe(Process.State.SUCCEEDED);
+        });
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+  );
+});

package/src/testing/assistant-test-layer.ts

@@ -18,6 +18,7 @@ import * as Chat from '@dxos/assistant/Chat';
 import {
   FeedTraceSink,
   ProcessManager,
+  ProcessOperationInvoker,
   RemoteProcessManager,
   RemoteTraceMonitor,
   TriggerDispatcher,
@@ -101,7 +102,7 @@ export type AssistantTestServices =
   | Operation.Service
   | ProcessManager.Service
   | RemoteProcessManager.Service
-  | ProcessManager.ProcessOperationInvoker.Service
+  | ProcessOperationInvoker.Service
   | Process.ManagerService
   | AtomRegistry.AtomRegistry
   | OperationHandlerSet.OperationHandlerProvider
@@ -139,7 +140,7 @@ export const AssistantTestLayer = (
   return Layer.empty.pipe(
     // Captures must sit above the layers they read (a provideMerge chain feeds upward).
     Layer.provideMerge(captureAgentService(agentServiceHolder)),
-    Layer.provideMerge(ProcessManager.ProcessOperationInvoker.layer),
+    Layer.provideMerge(ProcessOperationInvoker.layer),
     Layer.provideMerge(AgentServiceRuntime.layer(agentOptions)),
     Layer.provideMerge(UnifiedProcessManager.layer),
     // A local test stack has no EDGE, so both the manager's remote half and `location: 'edge'` see