@dxos/assistant 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

package/src/service/AgentService.test.ts

@@ -0,0 +1,169 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom';
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { Blueprint } from '@dxos/blueprints';
+
+import { Feed } from '@dxos/echo';
+import { TestHelpers } from '@dxos/effect/testing';
+import { Process } from '@dxos/functions-runtime';
+import { Organization } from '@dxos/types';
+import { trim } from '@dxos/util';
+import { Operation, OperationHandlerSet } from '@dxos/operation';
+
+import { AssistantTestLayer } from '../testing';
+import { log } from '@dxos/log';
+import * as AgentService from './AgentService';
+import { ObjectId } from '@dxos/keys';
+import * as Stream from 'effect/Stream';
+import { Trace } from '@dxos/functions';
+import { PartialBlock } from '../tracing';
+import { expect } from 'vitest';
+
+ObjectId.dangerouslyDisableRandomness();
+
+//
+// Test data.
+//
+
+const TEST_DATA = {
+  organizations: [
+    Organization.make({
+      name: 'Cyberdyne Systems',
+      website: 'https://cyberdyne.com',
+    }),
+    Organization.make({
+      name: 'Acme Robotics',
+      website: 'https://acmerobotics.example',
+    }),
+    Organization.make({
+      name: 'Globex Research',
+      website: 'https://globex.example',
+    }),
+  ],
+  research: {
+    'https://cyberdyne.com': `
+      Cyberdyne Systems is a company that builds AI agents.
+      They are based in San Francisco, California.
+      They were founded in 1984.
+      They are a public company.
+      They are listed on the NASDAQ under the symbol CYBR.
+      They are a member of the S&P 500 index.
+    `,
+    'https://acmerobotics.example': `
+      Acme Robotics designs industrial automation and collaborative robots.
+      They are headquartered in Austin, Texas.
+      They were founded in 2010.
+      They serve manufacturing and logistics customers worldwide.
+    `,
+    'https://globex.example': `
+      Globex Research runs applied R&D labs focused on materials science and energy storage.
+      They are based in Cambridge, Massachusetts.
+      They partner with universities and government grants programs.
+      Their flagship product line is solid-state battery prototypes for EVs.
+    `,
+  } as Record<string, string>,
+};
+
+const Research = Operation.make({
+  meta: {
+    key: 'org.dxos.function.research',
+    name: 'Research',
+    description: 'Research an organization',
+  },
+  input: Schema.Struct({
+    website: Schema.String.annotations({ description: 'The website of the organization to research' }),
+  }),
+  output: Schema.String,
+});
+
+const handlers = OperationHandlerSet.make(
+  Research.pipe(
+    Operation.withHandler(
+      Effect.fnUntraced(function* ({ website }) {
+        log.info('begin research', { website });
+        yield* Effect.sleep(
+          15_000 * (TEST_DATA.organizations.findIndex((organization) => organization.website === website) + 1),
+        );
+        log.info('end research', { website });
+        return TEST_DATA.research[website];
+      }),
+    ),
+  ),
+);
+
+const ResearchBlueprint = Blueprint.make({
+  key: 'org.dxos.blueprint.research',
+  name: 'Research',
+  tools: Blueprint.toolDefinitions({ operations: [Research] }),
+});
+
+//
+// Test layer: AI services + toolkit.
+//
+
+const SYSTEM_PROMPT = trim`
+  You are reacting to a continuous stream of organizations.
+  Research each organization.
+  Research takes a while to complete.
+  Do not block on the research since there might be more organizations to research, and we want research to happen in parallel.
+  Do not wait longer then 3 seconds to keep the conversation open for new events or user queries.
+  Do internal reasoning, but only show the answers to the user.
+`;
+
+const TestLayer = AssistantTestLayer({
+  types: [Organization.Organization, Feed.Feed, Blueprint.Blueprint],
+  tracing: 'console',
+  aiServicePreset: 'edge-remote',
+  operationHandlers: [handlers],
+  blueprints: [ResearchBlueprint],
+  systemPrompt: SYSTEM_PROMPT,
+});
+
+describe('Agent Executable', () => {
+  // TODO(dmaretskyi): Figure out how to make it not sleep for 45 seconds.
+  it.scoped.skip(
+    'runs AI agent with background tools via process manager',
+    Effect.fnUntraced(
+      function* (_) {
+        const registry = yield* Registry.AtomRegistry;
+        const monitor = yield* Process.ProcessMonitorService;
+        registry.subscribe(monitor.processTreeAtom, (tree) => {
+          console.log(`\n----- Process tree -----\n${Process.prettyProcessTree(tree)}\n-----------------\n`);
+        });
+
+        const agent = yield* AgentService.createSession({
+          blueprints: [ResearchBlueprint],
+        });
+
+        let ephemeralEventCount = 0;
+        yield* agent.subscribeEphemeral().pipe(
+          Stream.runForEach((msg) =>
+            Effect.gen(function* () {
+              for (const event of msg.events) {
+                if (Trace.isOfType(PartialBlock, event)) {
+                  ephemeralEventCount++;
+                }
+              }
+            }),
+          ),
+          Effect.fork,
+        );
+
+        for (const org of TEST_DATA.organizations) {
+          yield* agent.submitPrompt(JSON.stringify(org));
+        }
+        yield* agent.submitPrompt('When all research is complete, print 1-sentence summary for each organization.');
+        yield* agent.waitForCompletion();
+        expect(ephemeralEventCount).toBeGreaterThan(0);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    { timeout: 120_000 },
+  );
+});

package/src/service/AgentService.ts

@@ -0,0 +1,171 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import { Database, Feed, Obj } from '@dxos/echo';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Stream from 'effect/Stream';
+
+import { Blueprint } from '@dxos/blueprints';
+import { ProcessManager } from '@dxos/functions-runtime';
+import { failedInvariant } from '@dxos/invariant';
+import { AgentProcess } from './agent-process';
+
+import { Ref } from '@dxos/echo';
+import { QueueService, type Trace } from '@dxos/functions';
+import { type Message } from '@dxos/types';
+
+import { acquireReleaseResource } from '@dxos/effect';
+import { AiContextBinder, ContextBinding } from '../conversation';
+
+export interface Service {
+  /**
+   * Gets or creates a session for a feed.
+   */
+  getSession: (feed: Feed.Feed) => Effect.Effect<Session>;
+}
+
+export class AgentService extends Context.Tag('@dxos/assistant/AgentService')<AgentService, Service>() {}
+
+/**
+ * Handle to an agent session.
+ */
+export interface Session {
+  /**
+   * The feed that the session is associated with.
+   */
+  readonly feed: Feed.Feed;
+  /**
+   * Submits a prompt to the agent.
+   */
+  submitPrompt: (prompt: string) => Effect.Effect<void>;
+
+  /**
+   * Wait until agent has completed its work.
+   */
+  waitForCompletion: () => Effect.Effect<void>;
+
+  /**
+   * Subscribe to ephemeral trace events (e.g. streaming partial messages).
+   * Replays buffered events, then streams new ones until the process ends.
+   */
+  subscribeEphemeral: () => Stream.Stream<Trace.Message>;
+
+  /**
+   * Adds context objects to the agent.
+   */
+  addContext: (context: Ref.Ref<Obj.Unknown>[]) => Effect.Effect<void, never, QueueService>;
+
+  /**
+   * Gets the context objects from the agent.
+   */
+  getContext: () => Effect.Effect<Ref.Ref<Obj.Unknown>[], never, QueueService>;
+}
+
+/**
+ * Gets or creates a session for a feed.
+ */
+export const getSession = Effect.serviceFunctionEffect(AgentService, (service) => service.getSession);
+
+export interface CreateSessionOptions {
+  readonly blueprints?: Blueprint.Blueprint[];
+  readonly context?: Ref.Ref<Obj.Unknown>[];
+}
+
+export const createSession: (
+  opts?: CreateSessionOptions,
+) => Effect.Effect<
+  Session,
+  Blueprint.NotFoundError,
+  Database.Service | QueueService | Blueprint.RegistryService | AgentService
+> = Effect.fn('createSession')(function* (opts) {
+  const blueprints = yield* Effect.forEach(opts?.blueprints ?? [], (blueprint) =>
+    Blueprint.upsert(blueprint.key).pipe(Effect.map(Ref.make)),
+  );
+
+  const feed = yield* Database.add(Feed.make());
+  const queueDxn = Feed.getQueueDxn(feed) ?? failedInvariant();
+  const queue = yield* QueueService.getQueue<Message.Message | ContextBinding>(queueDxn);
+  const binder = yield* acquireReleaseResource(() => new AiContextBinder({ queue }));
+
+  yield* Effect.promise(() =>
+    binder.bind({
+      blueprints,
+      objects: opts?.context ?? [],
+    }),
+  );
+
+  return yield* getSession(feed);
+}, Effect.scoped);
+
+export const layer = (opts?: {
+  systemPrompt?: string;
+}): Layer.Layer<AgentService, never, ProcessManager.ProcessManagerService> =>
+  Layer.effect(
+    AgentService,
+    Effect.gen(function* () {
+      const processManager = yield* ProcessManager.ProcessManagerService;
+      const sessionCache = new Map<string, Session>();
+
+      return {
+        getSession: (feed: Feed.Feed) =>
+          Effect.gen(function* () {
+            const cached = sessionCache.get(feed.id);
+            if (cached) {
+              return cached;
+            }
+
+            const target = Obj.getDXN(feed).toString();
+            const executable = AgentProcess({ systemPrompt: opts?.systemPrompt });
+            const processes = yield* processManager.list({ target, key: executable.key });
+
+            let handle: ProcessManager.Handle<string, void>;
+            if (processes.length > 0) {
+              handle = processes[0];
+            } else {
+              handle = yield* processManager.spawn(executable, {
+                name: 'agent',
+                target,
+                traceMeta: {
+                  conversationId: feed.id,
+                },
+              });
+            }
+
+            const session = makeSession(handle, feed);
+            sessionCache.set(feed.id, session);
+            return session;
+          }),
+      };
+    }),
+  );
+
+const makeSession = (process: ProcessManager.Handle<string, void>, feed: Feed.Feed): Session => ({
+  feed,
+  submitPrompt: (prompt: string) => process.submitInput(prompt),
+  waitForCompletion: () => process.runToCompletion(),
+  subscribeEphemeral: () => process.subscribeEphemeral(),
+  addContext: (context: Ref.Ref<Obj.Unknown>[]) =>
+    Effect.gen(function* () {
+      const queueDxn = Feed.getQueueDxn(feed) ?? failedInvariant();
+      const queue = yield* QueueService.getQueue<Message.Message | ContextBinding>(queueDxn);
+      const binder = yield* acquireReleaseResource(() => new AiContextBinder({ queue }));
+      yield* Effect.promise(() =>
+        binder.bind({
+          blueprints: [],
+          objects: context,
+        }),
+      );
+    }).pipe(Effect.scoped),
+  getContext: () =>
+    Effect.gen(function* () {
+      const queueDxn = Feed.getQueueDxn(feed) ?? failedInvariant();
+      const queue = yield* QueueService.getQueue<Message.Message | ContextBinding>(queueDxn);
+      const binder = yield* acquireReleaseResource(() => new AiContextBinder({ queue }));
+      return binder.getObjects().map((object) => Ref.make(object));
+    }).pipe(Effect.scoped),
+});

package/src/service/agent-process.ts

@@ -0,0 +1,360 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { AiService, GenericToolkit, type ModelName } from '@dxos/ai';
+import { Database, DXN, Feed, Obj } from '@dxos/echo';
+import { QueueService, TracingService } from '@dxos/functions';
+import { Process, ProcessManager, StorageService } from '@dxos/functions-runtime';
+import { Operation, OperationRegistry } from '@dxos/operation';
+import { Message } from '@dxos/types';
+
+import { trim } from '@dxos/util';
+import * as Tool from '@effect/ai/Tool';
+import * as Toolkit from '@effect/ai/Toolkit';
+import * as Duration from 'effect/Duration';
+import * as Exit from 'effect/Exit';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import { AiConversation, type ContextBinding } from '../conversation';
+import {
+  functionInvocationServiceFromOperations,
+  getOperationFromTool,
+  makeToolExecutionService,
+  makeToolResolverFromOperations,
+} from '../functions';
+import { acquireReleaseResource } from '@dxos/effect';
+import { log } from '@dxos/log';
+import * as Match from 'effect/Match';
+import * as Cause from 'effect/Cause';
+
+interface AgentProcessOptions {
+  systemPrompt?: string;
+  model?: ModelName;
+}
+
+export const AGENT_PROCESS_KEY = 'org.dxos.testing.process.agent';
+
+/**
+ * Hosts a persistent, suspendible AiAgent that can process a number of prompts.
+ * The process target is a queue DXN string.
+ */
+export const AgentProcess = (options: AgentProcessOptions) =>
+  Process.make(
+    {
+      key: AGENT_PROCESS_KEY,
+      input: Schema.String,
+      output: Schema.Void,
+      services: [
+        Database.Service,
+        GenericToolkit.GenericToolkitProvider,
+        Operation.Service,
+        OperationRegistry.Service,
+        StorageService.StorageService,
+        QueueService,
+        ProcessManager.ProcessOperationInvoker.Service,
+        AiService.AiService,
+        // @deprecated Required by AiSessionRunRequirements for backward compat with tool handlers.
+        TracingService,
+      ],
+    },
+    (ctx) =>
+      Effect.gen(function* () {
+        const feedDxn = ctx.params.target;
+        if (feedDxn == null) {
+          return yield* Effect.die(new Error('Agent executable requires spawn options.target set to a queue DXN.'));
+        }
+        const feed = yield* Database.resolve(DXN.parse(feedDxn), Feed.Feed).pipe(Effect.orDie);
+        const queue = yield* QueueService.getQueue<Message.Message | ContextBinding>(Feed.getQueueDxn(feed)!);
+        const conversation = yield* acquireReleaseResource(() => new AiConversation({ queue }));
+        let inputQueue: AgentEvent[] = [...(yield* AgentEventsKey.get)];
+        const storageService = yield* StorageService.StorageService;
+        const toolCallManager = new ToolCallManager(storageService);
+        yield* toolCallManager.load();
+
+        return {
+          onInput: Effect.fnUntraced(function* (prompt: string) {
+            log('agent onInput received', { promptLength: prompt.length, backlog: inputQueue.length });
+            inputQueue.push({ _tag: 'prompt', content: prompt });
+            log('agent onInput persisting queue', { depth: inputQueue.length });
+            yield* AgentEventsKey.set(inputQueue);
+            log('agent onInput persisted', { depth: inputQueue.length });
+            ctx.setAlarm();
+            log('agent onInput alarm scheduled');
+          }),
+          onAlarm: Effect.fnUntraced(
+            function* () {
+              log('agent onAlarm fired', { pending: inputQueue.length });
+              const item = inputQueue.shift();
+              if (!item) {
+                log('agent onAlarm empty queue', {});
+                return;
+              }
+
+              if (item._tag === 'tool_result' && toolCallManager.isReported(item.pid)) {
+                log.info('skip tool result that was reported synchronously', { pid: item.pid });
+                // Ignore tool results that were reported synchronously.
+                return;
+              }
+
+              log('agent onAlarm handling', { tag: item._tag });
+
+              const prompt = Match.value(item).pipe(
+                Match.tag('prompt', (item) => item.content),
+                Match.tag('tool_result', (item) =>
+                  item.isError
+                    ? toolErrorResponse(item.pid, item.result as string)
+                    : toolResultResponse(item.pid, item.result),
+                ),
+                Match.exhaustive,
+              );
+
+              log('begin request', { prompt });
+              yield* conversation.createRequest({
+                prompt,
+                // TODO(dmaretskyi): Polling currently broken, agent relies on completion notifications being delivered.
+                // toolkit: AsynchronousExectionToolkit,
+                system: options.systemPrompt,
+              });
+              log('end request');
+              yield* AgentEventsKey.set(inputQueue);
+              if (inputQueue.length > 0) {
+                ctx.setAlarm();
+              }
+            },
+            Effect.orDie,
+            Effect.provide(
+              Layer.mergeAll(
+                makeToolResolverFromOperations(),
+                ToolExecutionService({
+                  toolCallManager,
+                  feed,
+                }),
+                functionInvocationServiceFromOperations,
+                AsynchronousExectionToolkitLayer,
+                AiService.model(options.model ?? '@anthropic/claude-opus-4-6'),
+              ).pipe(Layer.orDie),
+            ),
+          ),
+          onChildEvent: Effect.fnUntraced(function* (event) {
+            log.info('childEvent', { event });
+            if (event._tag === 'exited') {
+              if (!toolCallManager.isToolCall(event.pid)) {
+                log.verbose('childEvent ignored non-tool call', { pid: event.pid });
+                return;
+              }
+
+              const operationInvoker = yield* ProcessManager.ProcessOperationInvoker.Service;
+              const fiber = yield* operationInvoker.attachFiber(event.pid).pipe(Effect.orDie);
+              const result = yield* fiber.await.pipe(Effect.orDie).pipe(
+                Effect.map(
+                  Exit.match({
+                    onSuccess: (value): AgentEvent => ({
+                      _tag: 'tool_result',
+                      pid: event.pid,
+                      result: value,
+                      isError: false,
+                    }),
+                    onFailure: (cause): AgentEvent => ({
+                      _tag: 'tool_result',
+                      pid: event.pid,
+                      result: Cause.pretty(cause),
+                      isError: true,
+                    }),
+                  }),
+                ),
+              );
+              inputQueue.push(result);
+              log('agent onChildEvent persisted tool result', { depth: inputQueue.length, childPid: event.pid });
+              yield* AgentEventsKey.set(inputQueue);
+              ctx.setAlarm();
+              log('agent onChildEvent alarm scheduled', { depth: inputQueue.length });
+            }
+          }),
+        };
+      }),
+  );
+
+interface ToolExecutionServiceOptions {
+  /**
+   * Threshold after which the tool execution is placed in the background.
+   */
+  // TODO(dmaretskyi): Tool annotation to never run in background.
+  backgroundThreshold?: Duration.Duration;
+
+  toolCallManager: ToolCallManager;
+  feed: Feed.Feed;
+}
+
+const AgentEvent = Schema.Union(
+  Schema.TaggedStruct('prompt', {
+    content: Schema.String,
+  }),
+  Schema.TaggedStruct('tool_result', {
+    pid: Process.ID,
+    result: Schema.Unknown,
+    isError: Schema.Boolean,
+  }),
+);
+type AgentEvent = Schema.Schema.Type<typeof AgentEvent>;
+
+const AgentEventsKey = StorageService.key(
+  Schema.parseJson(Schema.Array(AgentEvent).pipe(Schema.mutable)),
+  'inputQueue',
+).pipe(StorageService.withDefault(() => []));
+
+const ToolCallState = Schema.Struct({
+  activeCalls: Schema.Array(
+    Schema.Struct({
+      pid: Process.ID,
+      // Whether the result was reported to the agent.
+      reported: Schema.Boolean,
+    }).pipe(Schema.mutable),
+  ).pipe(Schema.mutable),
+});
+interface ToolCallState extends Schema.Schema.Type<typeof ToolCallState> {}
+
+// Id's of processes who's results were already submitted to the agent.
+const ToolCallStateKey = StorageService.key(Schema.parseJson(ToolCallState.pipe(Schema.mutable)), 'toolCallState').pipe(
+  StorageService.withDefault(() => ({ activeCalls: [] })),
+);
+
+class ToolCallManager {
+  #storageService: StorageService.Service;
+  #state: ToolCallState = { activeCalls: [] };
+
+  constructor(storageService: StorageService.Service) {
+    this.#storageService = storageService;
+  }
+
+  load() {
+    return Effect.gen(this, function* () {
+      this.#state = yield* ToolCallStateKey.get;
+    }).pipe(Effect.provideService(StorageService.StorageService, this.#storageService));
+  }
+
+  beginCall(pid: Process.ID) {
+    return Effect.gen(this, function* () {
+      this.#state.activeCalls.push({ pid, reported: false });
+      yield* ToolCallStateKey.set(this.#state);
+    }).pipe(Effect.provideService(StorageService.StorageService, this.#storageService));
+  }
+
+  markAsReported(pid: Process.ID) {
+    return Effect.gen(this, function* () {
+      const call = this.#state.activeCalls.find((call) => call.pid === pid);
+      if (!call) {
+        return;
+      }
+      call.reported = true;
+      yield* ToolCallStateKey.set(this.#state);
+    }).pipe(Effect.provideService(StorageService.StorageService, this.#storageService));
+  }
+
+  isToolCall(pid: Process.ID): boolean {
+    return this.#state.activeCalls.some((call) => call.pid === pid);
+  }
+
+  isReported(pid: Process.ID) {
+    return this.#state.activeCalls.some((call) => call.pid === pid && call.reported);
+  }
+}
+
+const ToolExecutionService = ({
+  backgroundThreshold = Duration.seconds(1),
+  toolCallManager,
+  feed,
+}: ToolExecutionServiceOptions) =>
+  Layer.unwrapEffect(
+    Effect.gen(function* () {
+      const operationInvoker = yield* ProcessManager.ProcessOperationInvoker.Service;
+      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, {
+              environment: {
+                conversation: Obj.getDXN(feed).toString(),
+              },
+            });
+            toolCallManager.beginCall(fiber.pid);
+            log('invoked operation', { operationDef, input, fiber });
+
+            const result = yield* fiber.await.pipe(
+              Effect.tap(() => toolCallManager.markAsReported(fiber.pid)),
+              Effect.timeout(backgroundThreshold),
+              Effect.catchTag('TimeoutException', () => Effect.succeed(toolIsRunningInBackgroundResponse(fiber.pid))),
+            );
+            log('result', { result });
+            return result;
+          }),
+      });
+    }),
+  );
+
+class AsynchronousExectionToolkit extends Toolkit.make(
+  Tool.make('poll-tools', {
+    description: trim`
+      Poll tool calls running in the background.
+      Set wait to true to wait for the tool call to complete before returning.
+      Only set wait to true if you dont have other tasks to perform in parallel.
+      Set an appropriate timeout to avoid waiting forever.
+      You will also be notified about the job completion separatelly, so you do not always need to inspect the job if you dont need the result right now.
+    `,
+    parameters: {
+      ids: Schema.Array(Schema.String).annotations({
+        description: 'The IDs of the jobs to inspect.',
+      }),
+      wait: Schema.optional(Schema.Boolean).annotations({
+        description: 'Whether to wait for the job to complete before returning.',
+        default: false,
+      }),
+      timeout: Schema.optional(Schema.Number).annotations({
+        description:
+          'Maximum time to wait for the job to complete. If the job does not complete within the timeout, the current state is returned.',
+        default: 10_000,
+      }),
+    },
+  }),
+) {}
+
+// TODO(dmaretskyi): Currently broken: polling a completed process returns interruped error.
+const AsynchronousExectionToolkitLayer = AsynchronousExectionToolkit.toLayer(
+  Effect.gen(function* () {
+    const invoker = yield* ProcessManager.ProcessOperationInvoker.Service;
+    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('TimeoutException', () => Effect.succeed(`Process still running: ${pid}`)),
+            ),
+          );
+        }),
+    };
+  }),
+);
+
+/**
+ * Instructs model that the tool is running in the background.
+ */
+const toolIsRunningInBackgroundResponse = (pid: Process.ID) =>
+  `Tool is running in the background id=${pid}; wait for the completion notification to get the result.`;
+// `Tool is running in the background id=${pid}; use ${AsynchronousExectionToolkit.tools['poll-tools'].name} to get the result.`;
+
+const toolResultResponse = (pid: string, value: unknown) => `<result pid=${pid}>${JSON.stringify(value)}</result>`;
+
+const toolErrorResponse = (pid: string, cause: string) => `<error pid=${pid}>${cause}</error>`;