@dxos/assistant 0.8.4-main.b97322e → 0.8.4-main.bc2380dfbc

package/src/functions/services.ts

@@ -2,72 +2,149 @@
 // Copyright 2025 DXOS.org
 //
 
-import { AiTool } from '@effect/ai';
-import { Context, Effect, Layer, Match, Predicate, Record, Schema } from 'effect';
+import * as Tool from '@effect/ai/Tool';
+import type * as Toolkit from '@effect/ai/Toolkit';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Option from 'effect/Option';
+import * as Record from 'effect/Record';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
 
 import { AiToolNotFoundError, ToolExecutionService, ToolResolverService } from '@dxos/ai';
+import { OpaqueToolkit } from '@dxos/ai';
+import { Operation, OperationRegistry } from '@dxos/compute';
 import { todo } from '@dxos/debug';
-import { FunctionError, type FunctionContext, type FunctionDefinition, type Services } from '@dxos/functions';
+import { Ref } from '@dxos/echo';
 import { invariant } from '@dxos/invariant';
 
-export const makeToolResolverFromFunctions = (
-  functions: FunctionDefinition<any, any>[],
-): Layer.Layer<ToolResolverService> => {
-  return Layer.succeed(ToolResolverService, {
-    resolve: Effect.fn('resolveTool')(function* (id) {
-      const fn = functions.find((f) => f.name === id);
-      if (!fn) {
-        return yield* Effect.fail(new AiToolNotFoundError(id));
-      }
-
-      return projectFunctionToTool(fn);
+import { RefFromLLM } from '../util';
+
+export const makeToolResolverFromOperations = <R = never>({
+  toolkit: extraToolkit = OpaqueToolkit.empty,
+}: { toolkit?: OpaqueToolkit.OpaqueToolkit<never, never, R> } = {}): Layer.Layer<
+  ToolResolverService,
+  never,
+  OpaqueToolkit.OpaqueToolkitProvider | OperationRegistry.Service | R
+> => {
+  return Layer.effect(
+    ToolResolverService,
+    Effect.gen(function* () {
+      const toolkitProvider = yield* OpaqueToolkit.OpaqueToolkitProvider;
+      const operationRegistry = yield* OperationRegistry.Service;
+      return {
+        resolve: (id): Effect.Effect<Tool.Any, AiToolNotFoundError> =>
+          Effect.gen(function* () {
+            const toolkit = OpaqueToolkit.merge(extraToolkit, toolkitProvider.getToolkit());
+
+            const tool = toolkit.toolkit.tools[id];
+            if (tool) {
+              return tool;
+            }
+
+            return yield* operationRegistry.resolve(id).pipe(
+              Effect.flatMap(
+                Option.match({
+                  onSome: (_) => Effect.succeed(projectFunctionToTool(_)),
+                  onNone: () => Effect.fail(new AiToolNotFoundError(id)),
+                }),
+              ),
+            );
+          }),
+      } satisfies Context.Tag.Service<ToolResolverService>;
     }),
-  });
+  );
 };
 
-export const makeToolExecutionServiceFromFunctions = (
-  functions: FunctionDefinition<any, any>[],
-): Layer.Layer<ToolExecutionService> => {
-  return Layer.succeed(ToolExecutionService, {
-    handlersFor: (toolkit) => {
-      const makeHandler = (tool: AiTool.Any): ((params: unknown) => Effect.Effect<unknown, any, any>) => {
-        return Effect.fn('toolFunctionHandler')(function* (input: any) {
-          const { functionName } = Context.get(FunctionToolAnnotation)(tool.annotations as any);
-          const fnDef = functions.find((f) => f.name === functionName);
-          if (!fnDef) {
-            return yield* Effect.fail(new AiToolNotFoundError(tool.name));
-          }
-
-          return yield* invokeFunction(fnDef, input).pipe(Effect.catchAllDefect((defect) => Effect.fail(defect)));
-        });
+export const makeToolExecutionService = <E, R>(opts: {
+  invoke: (tool: Tool.Any, input: unknown) => Effect.Effect<unknown>;
+}): Layer.Layer<ToolExecutionService, never, OpaqueToolkit.OpaqueToolkitProvider> =>
+  Layer.effect(
+    ToolExecutionService,
+    Effect.gen(function* () {
+      const toolkitProvider = yield* OpaqueToolkit.OpaqueToolkitProvider;
+      const toolkit = toolkitProvider.getToolkit();
+
+      const toolkitHandler = yield* toolkit.toolkit.pipe(Effect.provide(toolkit.layer));
+      invariant(isHandlerLike(toolkitHandler));
+
+      return {
+        handlersFor: (toolkit) => {
+          const makeHandler = (tool: Tool.Any): ((params: unknown) => Effect.Effect<unknown, any, any>) => {
+            return Effect.fn(`toolFunctionHandler ${tool.name}`)(function* (input: any) {
+              if (toolkitHandler.tools[tool.name]) {
+                if (Tool.isProviderDefined(tool)) {
+                  throw new Error('Attempted to call a provider-defined tool');
+                }
+
+                // TODO(wittjosiah): Everything is `never` here.
+                const { result } = yield* (toolkitHandler.handle as any)(tool.name, input);
+                return result;
+              }
+
+              return yield* opts.invoke(tool, input).pipe(Effect.catchAllDefect((defect) => Effect.fail(defect)));
+            });
+          };
+
+          return toolkit.of(
+            Record.map(toolkit.tools, (tool, _name) => (Tool.isUserDefined(tool) ? makeHandler(tool) : null)) as any,
+          ) as any;
+        },
       };
+    }),
+  );
 
-      return toolkit.of(Record.map(toolkit.tools, (tool, name) => makeHandler(tool)) as any) as any;
-    },
-  });
+export const makeToolExecutionServiceFromOperationInvoker = (): Layer.Layer<
+  ToolExecutionService,
+  never,
+  Operation.Service | OpaqueToolkit.OpaqueToolkitProvider
+> => {
+  return Layer.unwrapEffect(
+    Effect.gen(function* () {
+      const operationInvoker = yield* Operation.Service;
+
+      return makeToolExecutionService({
+        invoke: (tool, input) =>
+          Effect.gen(function* () {
+            const operationDef = getOperationFromTool(tool).pipe(Option.getOrThrow);
+
+            return yield* operationInvoker.invoke(operationDef, input).pipe(Effect.orDie);
+          }),
+      });
+    }),
+  );
 };
 
-/**
- * Tools that are projected from functions have this annotation.
- */
-class FunctionToolAnnotation extends Context.Tag('@dxos/assisatnt/FunctionToolAnnotation')<
+export const ToolExecutionServices = Layer.mergeAll(
+  makeToolResolverFromOperations(),
+  makeToolExecutionServiceFromOperationInvoker(),
+);
+
+class FunctionToolAnnotation extends Context.Tag('@dxos/assistant/FunctionToolAnnotation')<
   FunctionToolAnnotation,
-  {
-    functionName: string;
-  }
+  { definition: Operation.Definition.Any }
 >() {}
 
-const toolCache = new WeakMap<FunctionDefinition<any, any>, AiTool.Any>();
-const projectFunctionToTool = (fn: FunctionDefinition<any, any>): AiTool.Any => {
+export const getOperationFromTool = (tool: Tool.Any): Option.Option<Operation.Definition.Any> => {
+  return Context.getOption(FunctionToolAnnotation)(tool.annotations).pipe(Option.map(({ definition }) => definition));
+};
+
+const toolCache = new WeakMap<Operation.Definition.Any, Tool.Any>();
+
+/**
+ * Projects an `Operation.Definition` into an `AiTool`.
+ */
+const projectFunctionToTool = (fn: Operation.Definition.Any): Tool.Any => {
   if (toolCache.has(fn)) {
     return toolCache.get(fn)!;
   }
-  const tool = AiTool.make(makeToolName(fn.name), {
-    description: fn.description,
-    parameters: createStructFieldsFromSchema(fn.inputSchema),
-    // TODO(dmaretskyi): Include output schema.
-    failure: Schema.Any, // TODO(dmaretskyi): Better type for the failure?
-  }).annotate(FunctionToolAnnotation, { functionName: fn.name });
+
+  const tool = Tool.make(makeToolName(fn.meta.name ?? fn.meta.key), {
+    description: fn.meta.description,
+    parameters: createStructFieldsFromSchema(fn.input),
+    failure: Schema.Any,
+  }).annotate(FunctionToolAnnotation, { definition: fn });
   toolCache.set(fn, tool);
   return tool;
 };
@@ -76,64 +153,62 @@ const projectFunctionToTool = (fn: FunctionDefinition<any, any>): AiTool.Any =>
  * @returns Tool name produced from function name by escaping invalid characters.
  */
 const makeToolName = (name: string) => {
-  const toolName = name.replace(/[^a-zA-Z0-9]/g, '');
-  invariant(toolName.match(/^[a-zA-Z_][a-zA-Z0-9-_]*$/));
+  const toolName = name.toLowerCase().replace(/[^a-zA-Z0-9]/g, '-');
+  invariant(toolName.match(/^[a-z_][a-z0-9-_]*$/));
   return toolName;
 };
 
 // TODO(dmaretskyi): Factor out.
 const createStructFieldsFromSchema = (schema: Schema.Schema<any, any>): Record<string, Schema.Schema<any, any>> => {
-  return Match.value(schema.ast).pipe(
-    Match.when(Predicate.isTagged('TypeLiteral'), (ast) => {
-      return Object.fromEntries(ast.propertySignatures.map((prop) => [prop.name, Schema.make(prop.type)]));
-    }),
-    Match.orElseAbsurd,
-  );
+  switch (schema.ast._tag) {
+    case 'TypeLiteral':
+      return Object.fromEntries(
+        schema.ast.propertySignatures.map((prop) => [prop.name, Schema.make(mapSchemaTypeForLLM(prop.type))]),
+      );
+    case 'VoidKeyword':
+      return {};
+    default:
+      return todo(`Unsupported schema AST: ${schema.ast._tag}`);
+  }
 };
 
-// TODO(dmaretskyi): Factor out.
-const invokeFunction = (fnDef: FunctionDefinition<any, any>, input: any): Effect.Effect<unknown, never, Services> =>
-  Effect.gen(function* () {
-    // Assert input matches schema
-    const assertInput = fnDef.inputSchema.pipe(Schema.asserts);
-    (assertInput as any)(input);
-
-    const context: FunctionContext = {
-      getService: () => todo(),
-      getSpace: async (_spaceId: any) => {
-        throw new Error('Not available. Use the database service instead.');
-      },
-      space: undefined,
-      get ai(): never {
-        throw new Error('Not available. Use the ai service instead.');
-      },
-    };
-
-    // TODO(dmaretskyi): This should be delegated to a function invoker service.
-    const data = yield* Effect.gen(function* () {
-      const result = fnDef.handler({ context, data: input });
-      if (Effect.isEffect(result)) {
-        return yield* (result as Effect.Effect<unknown, unknown, Services>).pipe(Effect.orDie);
-      } else if (
-        typeof result === 'object' &&
-        result !== null &&
-        'then' in result &&
-        typeof result.then === 'function'
-      ) {
-        return yield* Effect.promise(() => result);
-      } else {
-        return result;
-      }
-    }).pipe(
-      Effect.orDie,
-      Effect.catchAllDefect((defect) =>
-        Effect.die(new FunctionError('Error running function', { context: { name: fnDef.name }, cause: defect })),
+/**
+ * Picks an LLM-friendly schema type for the given schema AST.
+ * The picked schema type decodes to the original schema type.
+ */
+const mapSchemaTypeForLLM = (ast: SchemaAST.AST): SchemaAST.AST => {
+  if (Ref.isRefType(ast)) {
+    const description = ast.annotations.description
+      ? ast.annotations.description + '\n' + RefFromLLM.ast.annotations.description
+      : (RefFromLLM.ast.annotations.description as string);
+    return RefFromLLM.annotations({ description }).ast;
+  } else if (SchemaAST.isTupleType(ast)) {
+    return new SchemaAST.TupleType(
+      ast.elements.map((t) => new SchemaAST.OptionalType(mapSchemaTypeForLLM(t.type), t.isOptional, t.annotations)),
+      ast.rest.map((t) => new SchemaAST.Type(mapSchemaTypeForLLM(t.type), t.annotations)),
+      ast.isReadonly,
+      ast.annotations,
+    );
+  } else if (SchemaAST.isTypeLiteral(ast)) {
+    return new SchemaAST.TypeLiteral(
+      ast.propertySignatures.map(
+        (p) =>
+          new SchemaAST.PropertySignature(
+            p.name,
+            mapSchemaTypeForLLM(p.type),
+            p.isOptional,
+            p.isReadonly,
+            p.annotations,
+          ),
       ),
+      ast.indexSignatures,
+      ast.annotations,
     );
+  }
 
-    // Assert output matches schema
-    const assertOutput = fnDef.outputSchema?.pipe(Schema.asserts);
-    (assertOutput as any)(data);
+  return ast;
+};
 
-    return data;
-  }).pipe(Effect.withSpan('invokeFunction', { attributes: { name: fnDef.name } }));
+const isHandlerLike = (value: unknown): value is Toolkit.WithHandler<Record<string, Tool.Any>> => {
+  return typeof (value as any).tools === 'object' && typeof (value as any).handle === 'function';
+};

package/src/index.ts

@@ -2,11 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './context';
-export * from './conversation';
-export * from './extraction';
 export * from './functions';
-export * from './research';
+export * from './request';
 export * from './session';
 export * from './templates';
-export * from './types';
+export * from './util';

package/src/request/AiRequest.ts

@@ -0,0 +1,348 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import type * as AiError from '@effect/ai/AiError';
+import * as LanguageModel from '@effect/ai/LanguageModel';
+import * as Array from 'effect/Array';
+import * as Chunk from 'effect/Chunk';
+import * as Effect from 'effect/Effect';
+import { pipe } from 'effect/Function';
+import * as Option from 'effect/Option';
+import * as Stream from 'effect/Stream';
+
+import {
+  AiParser,
+  AiPreprocessor,
+  AiSummarizer,
+  type AiToolNotFoundError,
+  callTool,
+  type OpaqueToolkit,
+  type PromptPreprocessingError,
+  type ToolExecutionService,
+  type ToolResolverService,
+  withoutToolCallParising,
+} from '@dxos/ai';
+import { type Blueprint, Trace, Operation, OperationRegistry } from '@dxos/compute';
+import { Database, Obj } from '@dxos/echo';
+import { log } from '@dxos/log';
+import { ContentBlock, Message } from '@dxos/types';
+
+import { type AiAssistantError, CompleteBlock, PartialBlock } from '../util';
+import { formatSystemPrompt, formatUserPrompt } from './format';
+import { GenerationObserver } from './observer';
+
+export type RunError = AiError.AiError | PromptPreprocessingError | AiToolNotFoundError | AiAssistantError;
+
+export type RunRequirements =
+  | LanguageModel.LanguageModel
+  | ToolExecutionService
+  | ToolResolverService
+  | Database.Service
+  | Operation.Service
+  | OperationRegistry.Service
+  | Trace.TraceService;
+
+export type Options = {
+  /**
+   * Summarize before executing the prompt if the existing history exceeds this threshold.
+   */
+  summarizationThreshold?: number;
+
+  // TODO(dmaretskyi): Plan to phase out in favor of TracingService and the return type being a stream.
+  observer?: GenerationObserver;
+  /**
+   * Callback for when a message is received from the user, model, or tool.
+   * This is useful for streaming the output to a queue.
+   */
+  onOutput?: (message: Message.Message) => Effect.Effect<void, never, never>;
+};
+
+export type RunProps<R = never> = {
+  prompt: string | ContentBlock.Any[];
+  // TODO(wittjosiah): Rename to systemPrompt.
+  system?: string;
+  history?: Message.Message[];
+  objects?: Obj.Unknown[];
+  blueprints?: readonly Blueprint.Blueprint[];
+  toolkit?: OpaqueToolkit.OpaqueToolkit<R>;
+};
+
+export type BeginProps = {
+  prompt: string | ContentBlock.Any[];
+  system?: string;
+  history?: Message.Message[];
+  objects?: Obj.Unknown[];
+  blueprints?: readonly Blueprint.Blueprint[];
+};
+
+export type TurnProps<R = never> = {
+  system: string;
+  toolkit?: OpaqueToolkit.OpaqueToolkit<R>;
+};
+
+export type TurnResult = {
+  messages: Message.Message[];
+  done: boolean;
+};
+
+/**
+ * Contains message history, tools, current context.
+ * Current context means the state of the app, time of day, and other contextual information.
+ * It makes requests to the model, its a state machine.
+ * It keeps track of the current goal.
+ * It manages the context window.
+ * Tracks the success criteria of reaching the goal, exposing metrics (stretch).
+ * Could be run locally in the app or remotely.
+ * Could be personal or shared.
+ */
+export class Request {
+  /** Prevents concurrent execution of session. */
+  private readonly _semaphore = Effect.runSync(Effect.makeSemaphore(1));
+
+  private readonly _observer: GenerationObserver;
+  private readonly _onOutput: (message: Message.Message) => Effect.Effect<void, never, never>;
+
+  /** Message history from queue. */
+  // TODO(burdon): Evolve into supporting a git-like graph of messages.
+  private _history: Message.Message[] = [];
+
+  /** Pending messages for this session (incl. the current prompt). */
+  private _pending: Message.Message[] = [];
+
+  private _started = 0;
+  private _ended = 0;
+  private _toolCalls = 0;
+
+  constructor(private readonly _options: Options = {}) {
+    this._observer = _options.observer ?? GenerationObserver.noop();
+    this._onOutput = _options.onOutput ?? (() => Effect.void);
+  }
+
+  get duration(): number {
+    return this._ended - this._started;
+  }
+
+  get toolCalls(): number {
+    return this._toolCalls;
+  }
+
+  get pending(): readonly Message.Message[] {
+    return this._pending;
+  }
+
+  private _submitMessage = (message: Message.Message): Effect.Effect<Message.Message, never, Trace.TraceService> =>
+    Effect.gen(this, function* () {
+      this._pending.push(message);
+      yield* this._observer.onMessage(message);
+      for (const block of message.blocks) {
+        log('write complete block', {
+          messageId: message.id,
+          role: message.sender.role!,
+          block: JSON.stringify(block),
+        });
+        yield* Trace.write(CompleteBlock, {
+          messageId: message.id,
+          role: message.sender.role!,
+          block,
+        });
+      }
+      yield* this._onOutput(message);
+      return message;
+    });
+
+  getToolCalls = () =>
+    pipe(
+      [...this._history, ...this._pending],
+      Array.reverse,
+      Array.takeWhile((_) => _.sender.role === 'assistant'),
+      Array.flatMap((_) => _.blocks.filter(ContentBlock.is('toolCall')).map((block) => ({ block, message: _ }))),
+      Array.filter((_) => !_.block.providerExecuted),
+      Array.reverse,
+    );
+
+  /**
+   * Initialize a session: set up history, perform summarization if needed, and submit the user prompt.
+   * Must be called before `runTurn()`.
+   */
+  begin = ({
+    prompt,
+    system,
+    history = [],
+    blueprints = [],
+    objects = [],
+  }: BeginProps): Effect.Effect<void, RunError, RunRequirements> =>
+    Effect.gen(this, function* () {
+      this._started = Date.now();
+      this._history = [...history];
+      this._pending = [];
+
+      const systemPrompt = yield* formatSystemPrompt({ system, blueprints, objects }).pipe(Effect.orDie);
+
+      if (this._options.summarizationThreshold !== undefined) {
+        const tokenCount = yield* AiPreprocessor.estimateTokens(
+          yield* AiPreprocessor.preprocessPrompt([...this._history], {
+            system: systemPrompt,
+          }),
+        );
+        if (tokenCount > this._options.summarizationThreshold) {
+          const summary = yield* AiSummarizer.summarize([...this._history]);
+          yield* this._submitMessage(summary);
+        }
+      }
+
+      yield* this._submitMessage(yield* formatUserPrompt({ prompt, history }));
+    }).pipe(Effect.withSpan('AiRequest.begin'));
+
+  /**
+   * Execute a single turn: one LLM generation followed by tool execution.
+   * The toolkit and system prompt can be updated between turns to reflect context changes (e.g. dynamically enabled blueprints).
+   */
+  runAgentTurn = <const R = never>({
+    system,
+    toolkit: opaqueToolkit,
+  }: TurnProps<R>): Effect.Effect<TurnResult, RunError, RunRequirements | R> =>
+    Effect.gen(this, function* () {
+      log.info('request', {
+        system: { snippet: createSnippet(system), length: system.length },
+        pending: this._pending.length,
+        history: this._history.length,
+      });
+
+      const prompt = yield* AiPreprocessor.preprocessPrompt([...this._history, ...this._pending], {
+        system,
+        cacheControl: 'ephemeral',
+      });
+
+      const toolkit = opaqueToolkit ? yield* opaqueToolkit.handlers : undefined;
+
+      const observer = this._observer;
+      let currentMessageId: Obj.ID | null = null;
+
+      const messages = yield* LanguageModel.streamText({
+        prompt,
+        toolkit,
+        disableToolCallResolution: true,
+      }).pipe(
+        withoutToolCallParising,
+        AiParser.parseResponse({
+          emitPartial: true,
+          onBegin: () => observer.onBegin(),
+          onBlock: (block) => observer.onBlock(block),
+          onPart: (part) => observer.onPart(part as any),
+          onEnd: (summary) => observer.onEnd(summary),
+        }),
+        Stream.mapEffect(
+          (block) =>
+            Effect.gen(this, function* () {
+              if (block.pending) {
+                currentMessageId ??= Obj.ID.random();
+                log('emit ephemeral message', { id: currentMessageId, type: block._tag });
+                yield* Trace.write(PartialBlock, {
+                  messageId: currentMessageId,
+                  role: 'assistant',
+                  block,
+                });
+                return Option.none();
+              } else {
+                currentMessageId ??= Obj.ID.random();
+                const id = currentMessageId;
+                currentMessageId = null;
+                log('emit complete message', { id, type: block._tag });
+                const message = Obj.make(Message.Message, {
+                  id,
+                  created: new Date().toISOString(),
+                  sender: { role: 'assistant' },
+                  blocks: [block],
+                });
+                return Option.some(yield* this._submitMessage(message));
+              }
+            }),
+          { concurrency: 1, unordered: false },
+        ),
+        Stream.filterMap((_) => _),
+        Stream.runCollect,
+        Effect.map(Chunk.toArray),
+      );
+      log.info('messages', { messages });
+
+      const toolCalls = this.getToolCalls();
+
+      if (toolCalls.length === 0) {
+        this._ended = Date.now();
+        return { messages, done: true };
+      } else if (!toolkit) {
+        throw new Error('No toolkit provided');
+      }
+
+      return { messages, done: false };
+    }).pipe(Effect.withSpan('AiRequest.runAgentTurn'));
+
+  runTools = <const R = never>({
+    toolkit: opaqueToolkit,
+  }: {
+    toolkit?: OpaqueToolkit.OpaqueToolkit<R>;
+  }): Effect.Effect<void, RunError, RunRequirements | R> =>
+    Effect.gen(this, function* () {
+      const toolkit = opaqueToolkit ? yield* opaqueToolkit.handlers : undefined;
+      const toolCalls = this.getToolCalls();
+      const toolResults = yield* Effect.forEach(toolCalls, ({ block, message }) => {
+        if (!toolkit) {
+          throw new Error('No toolkit provided');
+        }
+        return callTool(toolkit, block);
+      });
+
+      yield* this._submitMessage(
+        Obj.make(Message.Message, {
+          created: new Date().toISOString(),
+          sender: { role: 'tool' },
+          blocks: toolResults,
+        }),
+      );
+
+      this._toolCalls += toolResults.length;
+    }).pipe(Effect.withSpan('AiRequest.runTools'));
+
+  /**
+   * Run a full conversation turn loop. Equivalent to calling `begin()` then `runTurn()` in a loop.
+   */
+  run = <const R = never>({
+    prompt,
+    system: systemTemplate,
+    history = [],
+    objects = [],
+    blueprints = [],
+    toolkit,
+  }: RunProps<R>): Effect.Effect<Message.Message[], RunError, RunRequirements | R> =>
+    Effect.gen(this, function* () {
+      yield* this.begin({ prompt, system: systemTemplate, history, objects, blueprints });
+
+      const system = yield* formatSystemPrompt({ system: systemTemplate, blueprints, objects }).pipe(Effect.orDie);
+
+      do {
+        const { done } = yield* this.runAgentTurn({ system, toolkit });
+        if (done) {
+          break;
+        }
+        yield* this.runTools({ toolkit });
+      } while (true);
+
+      log('done', { pending: this._pending.length, duration: this.duration, tools: this._toolCalls });
+      return this._pending;
+    }).pipe(this._semaphore.withPermits(1), Effect.withSpan('AiRequest.run'));
+}
+
+const createSnippet = (text: string, len = 32) =>
+  text.length <= len * 2 ? text : [text.slice(0, len), '...', text.slice(-len)].join('');
+
+// TODO(dmaretskyi): Extract as a general util.
+const logDump = (message: string, data: unknown) => {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { writeFileSync } = require('node:fs');
+  const path = `/tmp/log-data-${Date.now()}.json`;
+  writeFileSync(path, JSON.stringify(data, null, 2));
+  log.info(message, { path });
+};