@dxos/assistant 0.8.3 → 0.8.4-main.f9ba587

package/src/session/session.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Option, Schema } from 'effect';
+import { Array, Option, pipe, Schema } from 'effect';
 
 import {
   AgentStatusReport,
@@ -19,6 +19,8 @@ import {
   ToolResult,
   createTool,
   type ExecutableTool,
+  type ToolId,
+  type ToolResolver,
 } from '@dxos/ai';
 import { type ArtifactDefinition } from '@dxos/artifact';
 import { Event, synchronized } from '@dxos/async';
@@ -58,14 +60,12 @@ export type ArtifactDiffResolver = (artifacts: { id: ObjectId; lastVersion: Obje
 >;
 
 export type SessionRunOptions = {
-  client: AiServiceClient;
-
   artifacts: ArtifactDefinition[];
 
   /**
    * Non-artifact specific tools.
    */
-  tools: ExecutableTool[];
+  tools: ToolId[];
 
   history: Message[];
 
@@ -82,6 +82,14 @@ export type SessionRunOptions = {
    */
   requiredArtifactIds?: string[];
 
+  client: AiServiceClient;
+  toolResolver: ToolResolver;
+
+  /**
+   * Executable tools that do not go through the tool resolver.
+   */
+  executableTools?: ExecutableTool[];
+
   /**
    * @see ArtifactDiffResolver
    */
@@ -129,6 +137,9 @@ export class AISession {
    */
   public readonly update = this._parser.update;
 
+  /**
+   * Unparsed events from the underlying generation stream.
+   */
   public readonly streamEvent = this._parser.streamEvent;
 
   /**
@@ -138,9 +149,19 @@ export class AISession {
 
   /**
    * Agent self-reporting its status.
+   * Triggered by the model.
    */
   public readonly statusReport = new Event<AgentStatus>();
 
+  /**
+   * Emits when the session is done.
+   */
+  public readonly done = new Event<void>();
+
+  /**
+   * Emits when the tool reports its status.
+   * Triggered by the tool execution function.
+   */
   public readonly toolStatusReport = new Event<{ message: Message; status: AgentStatus }>();
 
   constructor(private readonly _options: AiSessionOptions) {
@@ -155,6 +176,11 @@ export class AISession {
     });
   }
 
+  /**
+   * Runs the AI model loop interacting with tools and artifacts.
+   * @param options - The session options.
+   * @returns The messages generated by the session, including the user's prompt.
+   */
   @synchronized
   async run(options: SessionRunOptions): Promise<Message[]> {
     const systemTools: ExecutableTool[] = [];
@@ -190,13 +216,17 @@ export class AISession {
     try {
       let more = false;
       do {
-        const tools: ExecutableTool[] = [
-          ...systemTools,
-          ...options.tools,
-          ...options.artifacts
-            .filter((artifact) => requiredArtifactIds.has(artifact.id))
-            .flatMap((artifact) => artifact.tools),
-        ];
+        const tools: ExecutableTool[] = pipe(
+          [
+            ...systemTools,
+            ...(await Promise.all(options.tools.map((toolId) => options.toolResolver.resolve(toolId)))),
+            ...(options.executableTools ?? []),
+            ...options.artifacts
+              .filter((artifact) => requiredArtifactIds.has(artifact.id))
+              .flatMap((artifact) => artifact.tools),
+          ],
+          Array.dedupeWith((a, b) => a.id === b.id),
+        );
 
         log('request', {
           pending: this._pending.length,
@@ -213,7 +243,7 @@ export class AISession {
           systemPrompt:
             options.systemPrompt ??
             createBaseInstructions({
-              availableArtifacts: Array.from(requiredArtifactIds),
+              availableArtifacts: [...requiredArtifactIds],
               operationModel: this._options.operationModel,
             }),
         });
@@ -258,6 +288,7 @@ export class AISession {
       }
     } finally {
       this._stream = undefined;
+      this.done.emit();
     }
 
     if (error) {
@@ -274,7 +305,7 @@ export class AISession {
     const parser = structuredOutputParser(schema);
     const result = await this.run({
       ...options,
-      tools: [...options.tools, parser.tool],
+      executableTools: [...(options.executableTools ?? []), parser.tool],
     });
     return parser.getResult(result);
   }
@@ -290,7 +321,7 @@ export class AISession {
       const versions = gatherObjectVersions(history);
 
       const artifactDiff = await artifactDiffResolver(
-        Array.from(versions.entries()).map(([id, version]) => ({ id, lastVersion: version })),
+        [...versions.entries()].map(([id, version]) => ({ id, lastVersion: version })),
       );
 
       log.info('vision', {
@@ -409,14 +440,11 @@ export class AISession {
           session.userMessage.on((ev) => this.userMessage.emit(ev));
 
           const messages = await session.run({
-            client: options.client,
             artifacts: options.artifacts,
             tools: options.tools,
             history: options.history,
             extensions: options.extensions,
-            generationOptions: options.generationOptions,
             requiredArtifactIds: step.requiredArtifactIds.slice(),
-            artifactDiffResolver: options.artifactDiffResolver,
             prompt: `
               You are an agent that executes the subtask in a plan.
               
@@ -439,6 +467,11 @@ export class AISession {
               Previous step results:
               ${JSON.stringify(stepResults.at(-1))}.
             `,
+
+            generationOptions: options.generationOptions,
+            client: options.client,
+            toolResolver: options.toolResolver,
+            artifactDiffResolver: options.artifactDiffResolver,
           });
           const result = messages.at(-1);
           stepResults.push(result);
@@ -541,7 +574,7 @@ const createArtifactUpdateBlock = (
     disposition: 'artifact-update',
     text: `
       The following artifacts have been updated since the last message:
-      ${Array.from(artifactDiff.entries())
+      ${[...artifactDiff.entries()]
         .map(([id, { diff }]) => `<changed-artifact id="${id}">${diff ? `\n${diff}` : ''}</changed-artifact>`)
         .join('\n')}
     `,