@dxos/assistant 0.8.4-main.f9ba587 → 0.8.4-main.fd6878d

package/src/session/session.ts

@@ -2,581 +2,278 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Array, Option, pipe, Schema } from 'effect';
+import { type AiError, AiLanguageModel, type AiResponse, type AiTool, AiToolkit } from '@effect/ai';
+import { Chunk, type Context, Effect, Function, Option, Queue, type Schema, Stream } from 'effect';
 
 import {
-  AgentStatusReport,
-  isToolUse,
-  runTools,
-  type AgentStatus,
-  structuredOutputParser,
-  type AiServiceClient,
-  type GenerationStream,
-  type GenerateRequest,
-  Message,
-  type MessageContentBlock,
-  MixedStreamParser,
-  ToolResult,
-  createTool,
-  type ExecutableTool,
-  type ToolId,
-  type ToolResolver,
+  type AiInputPreprocessingError,
+  AiParser,
+  AiPreprocessor,
+  type AiToolNotFoundError,
+  type ConsolePrinter,
+  ToolExecutionService,
+  ToolResolverService,
+  callTools,
+  getToolCalls,
 } from '@dxos/ai';
-import { type ArtifactDefinition } from '@dxos/artifact';
-import { Event, synchronized } from '@dxos/async';
+import { type Blueprint } from '@dxos/blueprints';
+import { todo } from '@dxos/debug';
 import { Obj } from '@dxos/echo';
-import { ObjectVersion } from '@dxos/echo-db';
-import { create, type ObjectId } from '@dxos/echo-schema';
-import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
+import { type ContentBlock, DataType } from '@dxos/schema';
+import { isNotFalsy } from '@dxos/util';
 
-import { VersionPin } from './version-pin';
+import { type AiAssistantError } from '../errors';
 
-/**
- * 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.
- */
+import { formatSystemPrompt, formatUserPrompt } from './format';
+
+export type AiSessionOptions = {};
 
 /**
- * Resolves artifact ids to their versions.
- * Used to give the model a sense of the changes to the artifacts made by users during the conversation.
- * The artifacts versions are pinned in the history, and whenever the artifact changes in-between assistant's steps,
- * a diff is inserted into the conversation.
+ * Live observer of the generation process.
  */
-export type ArtifactDiffResolver = (artifacts: { id: ObjectId; lastVersion: ObjectVersion }[]) => Promise<
-  Map<
-    ObjectId,
-    {
-      version: ObjectVersion;
-      diff?: string;
-    }
-  >
->;
-
-export type SessionRunOptions = {
-  artifacts: ArtifactDefinition[];
-
+export interface GenerationObserver {
   /**
-   * Non-artifact specific tools.
+   * Unparsed content block parts from the model.
    */
-  tools: ToolId[];
-
-  history: Message[];
-
-  prompt: string;
-
-  generationOptions?: Pick<GenerateRequest, 'model'>;
-
-  extensions?: ToolContextExtensions;
-
-  systemPrompt?: string;
+  onPart: (part: AiResponse.Part) => Effect.Effect<void>;
 
   /**
-   * Pre-require artifacts.
+   * Parsed content blocks from the model.
+   * NOTE: Use block.pending to determine if the block was completed.
+   * For each block this will be called 0..n times with a pending block and then once with the final state of the block.
+   *
+   * Example:
+   *  1. { pending: true, text: "Hello"}
+   *  2. { pending: true, text: "Hello, I am a"}
+   *  3. { pending: false, text: "Hello, I am a helpful assistant!"}
    */
-  requiredArtifactIds?: string[];
-
-  client: AiServiceClient;
-  toolResolver: ToolResolver;
+  onBlock: (block: ContentBlock.Any) => Effect.Effect<void>;
 
   /**
-   * Executable tools that do not go through the tool resolver.
+   * Complete messages fired during the session, both from the model and from the user.
+   * This message will contain all message blocks emitted through the `onBlock` callback.
    */
-  executableTools?: ExecutableTool[];
+  onMessage: (message: DataType.Message) => Effect.Effect<void>;
+}
 
-  /**
-   * @see ArtifactDiffResolver
-   */
-  artifactDiffResolver?: ArtifactDiffResolver;
-};
+export const GenerationObserver = Object.freeze({
+  make: ({
+    onPart = Function.constant(Effect.void),
+    onBlock = Function.constant(Effect.void),
+    onMessage = Function.constant(Effect.void),
+  }: Partial<GenerationObserver> = {}): GenerationObserver => ({
+    onPart,
+    onBlock,
+    onMessage,
+  }),
 
-type OperationModel = 'planning' | 'importing' | 'configured';
+  noop: () => GenerationObserver.make(),
 
-export type AiSessionOptions = {
   /**
-   * Determines the agent's handling of the artifacts definitions:
-   *
-   * - `planning`: The model will create a plan with required artifacts for each step.
-   * - `importing`: The model can query registry and only pull in the artifacts that are required to complete the task.
-   * - `configured`: The available artifacts are pre-selected and the model cannot select additional artifacts.
+   * Debug printer to be used in unit-tests and browser devtools.
    */
-  operationModel: OperationModel;
-};
-
-export class AISession {
-  /** SSE stream parser. */
-  private readonly _parser = new MixedStreamParser();
-
-  /** Pending messages (incl. the current user request). */
-  private _pending: Message[] = [];
-
-  /** Current streaming response. */
-  private _stream: GenerationStream | undefined;
+  fromPrinter: (printer: ConsolePrinter) =>
+    GenerationObserver.make({
+      onBlock: (block) =>
+        Effect.sync(() => {
+          if (block.pending) {
+            return; // Only prints full blocks (better for unit-tests and browser devtools).
+          }
+          printer.printContentBlock(block);
+        }),
+      onMessage: (message) =>
+        Effect.sync(() => {
+          if (message.sender.role === 'assistant') {
+            return; // Skip assistant messages since they are printed in the `onBlock` callback.
+          }
+          printer.printMessage(message);
+        }),
+    }),
+});
 
-  /** Prior history from queue. */
-  private _history: Message[] = [];
+export type SessionRunParams<Tools extends AiTool.Any> = {
+  prompt: string;
+  system?: string;
+  history?: DataType.Message[];
+  objects?: Obj.Any[]; // TODO(burdon): Meta only (typename and id -- write to binder).
+  blueprints?: Blueprint.Blueprint[];
+  toolkit?: AiToolkit.AiToolkit<Tools>;
+  observer?: GenerationObserver;
+};
 
-  /**
-   * New message.
-   */
-  public readonly message = this._parser.message;
+/**
+ * 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 AiSession {
+  /** Complete messages fired during the session, both from the model and from the user. */
+  public readonly messageQueue = Effect.runSync(Queue.unbounded<DataType.Message>());
 
-  /**
-   * Complete block added to Message.
-   */
-  public readonly block = this._parser.block;
+  // TODO(dmaretskyi): Remove the queues and convert everything to observer.
 
   /**
-   * Update partial block (while streaming).
+   * Blocks streaming from the model during the session.
+   * @deprecated Use `observer.onBlock` instead.
    */
-  public readonly update = this._parser.update;
+  public readonly blockQueue = Effect.runSync(Queue.unbounded<Option.Option<ContentBlock.Any>>());
 
-  /**
-   * Unparsed events from the underlying generation stream.
-   */
-  public readonly streamEvent = this._parser.streamEvent;
+  /** Unparsed events from the underlying generation stream. */
+  public readonly eventQueue = Effect.runSync(Queue.unbounded<AiResponse.Part>());
 
-  /**
-   * User prompt or tool result.
-   */
-  public readonly userMessage = new Event<Message>();
+  /** Prevents concurrent execution of session. */
+  private readonly _semaphore = Effect.runSync(Effect.makeSemaphore(1));
 
-  /**
-   * Agent self-reporting its status.
-   * Triggered by the model.
-   */
-  public readonly statusReport = new Event<AgentStatus>();
+  /** Pending messages (incl. the current user request). */
+  private _pending: DataType.Message[] = [];
 
-  /**
-   * Emits when the session is done.
-   */
-  public readonly done = new Event<void>();
+  /** Prior history from queue. */
+  private _history: DataType.Message[] = [];
 
-  /**
-   * 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) {
-    // Message complete.
-    this._parser.message.on((message) => {
-      this._pending.push(message);
-    });
-    this._parser.block.on((block) => {
-      if (block.type === 'text' && block.disposition === 'status') {
-        this.statusReport.emit(create(AgentStatusReport, { message: block.text }));
-      }
-    });
-  }
+  constructor(private readonly _options: AiSessionOptions = {}) {}
 
   /**
    * 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[] = [];
-    switch (this._options.operationModel) {
-      case 'planning':
-        systemTools.push(this._createQueryArtifactsTool(options.artifacts), this._createPlanningTool(options));
-        break;
-      case 'importing':
-        systemTools.push(
-          this._createQueryArtifactsTool(options.artifacts),
-          this._createRequireTool(options.artifacts, (artifactDefinitionIds) => {
-            for (const artifactDefinitionId of artifactDefinitionIds) {
-              requiredArtifactIds.add(artifactDefinitionId);
-            }
-          }),
-        );
-        break;
-      case 'configured':
-        // no system tools
-        break;
-      default:
-        throw new TypeError(`Invalid operation model: ${this._options.operationModel}`);
-    }
-
-    this._history = [...options.history];
-    this._pending = [await this._formatUserPrompt(options.artifactDiffResolver, options.prompt, options.history)];
-    this.userMessage.emit(this._pending.at(-1)!);
-    this._stream = undefined;
-
-    let error: Error | undefined;
-
-    const requiredArtifactIds = new Set<string>(options.requiredArtifactIds ?? []);
-    try {
-      let more = false;
+  // TODO(dmaretskyi): Toolkit context doesn't get added to the effect type.
+  run = <Tools extends AiTool.Any>(
+    params: SessionRunParams<Tools>,
+  ): Effect.Effect<
+    DataType.Message[],
+    AiAssistantError | AiInputPreprocessingError | AiToolNotFoundError | AiError.AiError,
+    AiLanguageModel.AiLanguageModel | ToolResolverService | ToolExecutionService | AiTool.ToHandler<Tools>
+  > =>
+    Effect.gen(this, function* () {
+      const observer = params.observer ?? GenerationObserver.noop();
+
+      // Create toolkit.
+      const toolkit: AiToolkit.ToHandler<Tools> = yield* createToolkit(params);
+
+      // Generate system prompt.
+      // TODO(budon): Dynamically resolve template variables.
+      const system = yield* formatSystemPrompt(params);
+      console.log(system);
+
+      // Generate user prompt.
+      const promptMessages = yield* formatUserPrompt(params);
+      yield* this.messageQueue.offer(promptMessages);
+      yield* observer.onMessage(promptMessages);
+
+      this._history = [...(params.history ?? [])];
+      this._pending = [promptMessages];
+
+      // Potential tool-use loop.
       do {
-        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', {
+        log.info('request', {
+          prompt: promptMessages,
+          system: { snippet: [system.slice(0, 32), '...', system.slice(-32)].join(''), length: system.length },
           pending: this._pending.length,
           history: this._history.length,
-          tools: tools.map((tool) => tool.name),
-        });
-
-        // Open request stream.
-        this._stream = await options.client.execStream({
-          ...(options.generationOptions ?? {}),
-          // TODO(burdon): Rename messages or separate history/message.
-          history: [...this._history, ...this._pending],
-          tools,
-          systemPrompt:
-            options.systemPrompt ??
-            createBaseInstructions({
-              availableArtifacts: [...requiredArtifactIds],
-              operationModel: this._options.operationModel,
-            }),
+          objects: params.objects?.length ?? 0,
+          blueprints: params.blueprints?.length ?? 0,
+          toolkit: Object.values(toolkit.tools).map((tool: AiTool.Any) => tool.name),
         });
 
-        // Wait until complete.
-        await this._parser.parse(this._stream);
-        await this._stream.complete();
-
-        // Add messages.
-        log('response', { pending: this._pending });
-
-        // Resolve tool use locally.
-        more = false;
-        const message = this._pending.at(-1);
-        invariant(message);
-        if (isToolUse(message)) {
-          log('tool request...');
-          const response = await runTools({
-            message: this._pending.at(-1)!,
-            tools,
-            extensions: options.extensions ?? {},
-            reportStatus: (status) => this._onToolStatusReport(message, status),
-          });
-
-          log('tool response', { response });
-          switch (response.type) {
-            case 'continue': {
-              this._pending = [...this._pending, response.message];
-              this.userMessage.emit(response.message);
-              more = true;
-              break;
-            }
-          }
-        }
-      } while (more);
-    } catch (err) {
-      log.catch(err);
-      if (err instanceof Error && err.message.includes('Overloaded')) {
-        error = new AIServiecOverloadedError('AI service overloaded', { cause: err } as any); // TODO(dmaretskyi): Schema errors cant have cause
-      } else {
-        error = new Error('AI service error', { cause: err });
-      }
-    } finally {
-      this._stream = undefined;
-      this.done.emit();
-    }
-
-    if (error) {
-      throw error;
-    }
-
-    return this._pending;
-  }
-
-  async runStructured<S extends Schema.Schema.AnyNoContext>(
-    schema: S,
-    options: SessionRunOptions,
-  ): Promise<Schema.Schema.Type<S>> {
-    const parser = structuredOutputParser(schema);
-    const result = await this.run({
-      ...options,
-      executableTools: [...(options.executableTools ?? []), parser.tool],
-    });
-    return parser.getResult(result);
-  }
-
-  private async _formatUserPrompt(
-    artifactDiffResolver: ArtifactDiffResolver | undefined,
-    prompt: string,
-    history: Message[],
-  ) {
-    const prelude: MessageContentBlock[] = [];
-
-    if (artifactDiffResolver) {
-      const versions = gatherObjectVersions(history);
-
-      const artifactDiff = await artifactDiffResolver(
-        [...versions.entries()].map(([id, version]) => ({ id, lastVersion: version })),
-      );
-
-      log.info('vision', {
-        artifactDiff,
-        versions,
-      });
-
-      for (const [id, { version }] of [...artifactDiff.entries()]) {
-        if (ObjectVersion.equals(version, versions.get(id)!)) {
-          artifactDiff.delete(id);
-          continue;
-        }
-
-        prelude.push(VersionPin.createBlock(VersionPin.make({ objectId: id, version })));
-      }
-      if (artifactDiff.size > 0) {
-        prelude.push(createArtifactUpdateBlock(artifactDiff));
-      }
-    }
-
-    return Obj.make(Message, {
-      role: 'user',
-      content: [...prelude, { type: 'text', text: prompt }],
-    });
-  }
+        // Generate the prompt and make request.
+        const prompt = yield* AiPreprocessor.preprocessAiInput([...this._history, ...this._pending]);
+        const blocks = yield* AiLanguageModel.streamText({
+          prompt,
+          system,
+          toolkit,
+          // TODO(burdon): Despite this flag, the model still calls tools.
+          //  Flag is only used in generateText (not streamText); patch and submit bug.
+          //  https://github.com/Effect-TS/effect/blob/main/packages/ai/ai/src/AiLanguageModel.ts#L401
+          disableToolCallResolution: true,
+        }).pipe(
+          AiParser.parseResponse({
+            onBlock: (block) =>
+              Effect.all([this.blockQueue.offer(Option.some(block)), observer.onBlock(block)], { discard: true }),
+            onPart: (part) => Effect.all([this.eventQueue.offer(part), observer.onPart(part)], { discard: true }),
+          }),
+          Stream.runCollect,
+          Effect.map(Chunk.toArray),
+        );
 
-  private _createQueryArtifactsTool(artifacts: ArtifactDefinition[]): ExecutableTool {
-    return createTool('system', {
-      name: 'query_artifact_definitions',
-      description: 'Query the available artifact definitions',
-      schema: Schema.Struct({}),
-      execute: async () => {
-        return ToolResult.Success({
-          artifactDefinitions: artifacts.map((artifact) => ({
-            id: artifact.id,
-            name: artifact.name,
-            description: artifact.description,
-          })),
+        // Signal to stream consumers that message blocks are complete.
+        // Allows for coordination between the block and message queues
+        //   to prevent the streaming blocks from being rendered twice when the message is produced.
+        // TODO(wittjosiah): The block queue should probably be drained at this point in the case that there is no consumer.
+        yield* this.blockQueue.offer(Option.none());
+
+        // Create response message.
+        const response = Obj.make(DataType.Message, {
+          created: new Date().toISOString(),
+          sender: { role: 'assistant' },
+          blocks,
         });
-      },
-    });
-  }
-
-  private _createRequireTool(
-    artifacts: ArtifactDefinition[],
-    onRequire: (artifactDefinitionIds: readonly string[]) => void,
-  ): ExecutableTool {
-    return createTool('system', {
-      name: 'require_artifact_definitions',
-      description:
-        'Require the use of specific artifact definitions. This will allow the model to interact with artifact definitions and use their tools.',
-      schema: Schema.Struct({
-        artifactDefinitionIds: Schema.Array(Schema.String).annotations({
-          description: 'The ids of the artifact definitions to require',
-          examples: [['artifact:dxos.org/example/Test']],
-        }),
-      }),
-      execute: async ({ artifactDefinitionIds }) => {
-        const missingArtifactDefinitionIds = artifactDefinitionIds.filter(
-          (artifactId) => !artifacts.some((artifact) => artifact.id === artifactId),
-        );
-        if (missingArtifactDefinitionIds.length > 0) {
-          return ToolResult.Error(
-            `One or more artifact definition ids are invalid: ${missingArtifactDefinitionIds.join(', ')}`,
-          );
+        this._pending.push(response);
+        yield* this.messageQueue.offer(response);
+        yield* observer.onMessage(response);
+
+        // Parse response for tool calls.
+        const toolCalls = getToolCalls(response);
+        if (toolCalls.length === 0) {
+          break;
         }
 
-        onRequire(artifactDefinitionIds);
-
-        return ToolResult.Success({});
-      },
-    });
-  }
-
-  private _createPlanningTool(options: SessionRunOptions): ExecutableTool {
-    return createTool('system', {
-      name: 'create_plan',
-      description:
-        'Create a plan. Make sure that each step is independent and can be executed solely on the data returned by the previous step. The steps only share the data that is specified in the plan.',
-      schema: Schema.Struct({
-        goal: Schema.String.annotations({ description: 'The goal that the plan will achieve.' }),
-        steps: Schema.Array(
-          Schema.Struct({
-            action: Schema.String.annotations({
-              description: 'Complete, detailed action to perform.',
-            }),
-            input: Schema.String.annotations({
-              description: 'The required input data for this step. First step must not require any data.',
-            }),
-            output: Schema.String.annotations({
-              description: 'The output data from this step. This is passed to the next step as input.',
-            }),
-            requiredArtifactIds: Schema.Array(Schema.String).annotations({
-              description: 'The ids of the artifacts required to perform this step.',
-              examples: [['artifact:dxos.org/example/Test']],
-            }),
-          }),
-        ).annotations({ description: 'Steps' }),
-      }),
-      execute: async ({ goal, steps }) => {
-        const missingArtifactIds = steps
-          .flatMap((step) => step.requiredArtifactIds)
-          .filter((artifactId) => !options.artifacts.some((artifact) => artifact.id === artifactId));
-        if (missingArtifactIds.length > 0) {
-          return ToolResult.Error(`One or more artifact ids are invalid: ${missingArtifactIds.join(', ')}`);
-        }
+        // TODO(burdon): Report errors to user; with proposed actions.
+        const toolResults = yield* callTools(toolkit, toolCalls);
+        const toolResultsMessage = Obj.make(DataType.Message, {
+          created: new Date().toISOString(),
+          sender: { role: 'user' },
+          blocks: toolResults,
+        });
 
-        const stepResults: any[] = [];
-        for (const step of steps) {
-          log('executing step', { action: step.action });
-          const session = new AISession({ operationModel: 'importing' });
-          session.message.on((ev) => this.message.emit(ev));
-          session.block.on((ev) => this.block.emit(ev));
-          session.update.on((ev) => this.update.emit(ev));
-          session.streamEvent.on((ev) => this.streamEvent.emit(ev));
-          session.userMessage.on((ev) => this.userMessage.emit(ev));
-
-          const messages = await session.run({
-            artifacts: options.artifacts,
-            tools: options.tools,
-            history: options.history,
-            extensions: options.extensions,
-            requiredArtifactIds: step.requiredArtifactIds.slice(),
-            prompt: `
-              You are an agent that executes the subtask in a plan.
-              
-              While you know the plan's goal only focus on your subtask
-              Use the data from the previous step to complete your task.
-              Return all of the data from "output" in your last message.
-              
-              Current step (that you need to complete):
-              ${JSON.stringify(
-                {
-                  goal,
-                  input: step.input,
-                  output: step.output,
-                  yourTask: step.action,
-                },
-                null,
-                2,
-              )}
-              
-              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);
-        }
+        this._pending.push(toolResultsMessage);
+        yield* this.messageQueue.offer(toolResultsMessage);
+        yield* observer.onMessage(toolResultsMessage);
+      } while (true);
 
-        return ToolResult.Success({ stepResults });
-      },
-    });
-  }
+      // Signals to stream consumers that the session has completed and no more messages are coming.
+      yield* Queue.shutdown(this.messageQueue);
+      yield* Queue.shutdown(this.blockQueue);
+      yield* Queue.shutdown(this.eventQueue);
 
-  private _onToolStatusReport(message: Message, status: AgentStatus): void {
-    this.toolStatusReport.emit({ message, status });
-  }
+      log('done', { pending: this._pending.length });
+      return this._pending;
+    }).pipe(this._semaphore.withPermits(1), Effect.withSpan('AiSession.run'));
 
-  abort(): void {
-    this._stream?.abort();
+  // TODO(burdon): Implement.
+  async runStructured<S extends Schema.Schema.AnyNoContext>(
+    _schema: S,
+    _options: SessionRunParams<AiTool.Any>,
+  ): Promise<Schema.Schema.Type<S>> {
+    return todo();
+    // const parser = structuredOutputParser(schema);
+    // const result = await this.run({
+    //   ...options,
+    //   executableTools: [...(options.executableTools ?? []), parser.tool],
+    // });
+    // return parser.getResult(result);
   }
 }
 
-// TODO(burdon): Use handlebars template with effect-schema input.
-const createBaseInstructions = ({
-  availableArtifacts,
-  operationModel,
-}: {
-  availableArtifacts: string[];
-  operationModel: OperationModel;
-}) => `
-  You are a friendly, advanced AI assistant capable of creating and managing artifacts from available data and tools. 
-  Your task is to process user commands and questions and decide how best to respond.
-  In some cases, you will need to create or reference data objects called artifacts.
-
-  Follow these guidelines carefully:
-
-  Decision-making:
-
-  - Analyze the structure and type of the content in the user's message.
-  
-  
-  ${
-    operationModel === 'planning'
-      ? `
-      - Can you complete the task using the available artifacts?
-      - If you can't complete the task using the available artifacts, query the list of available artifacts using the appropriate tool.
-      - Identify which artifacts are relevant to the user's request.
-        - Break down the user's request into a step-by-step plan that you will use to execute the user's request, the plan items should include artifacts which will be used to perform the actions.
-      `
-      : ''
-  }
-  ${
-    operationModel === 'importing'
-      ? `
-      - Can you complete the task using the available artifacts?
-      - If you can't complete the task using the available artifacts, query the list of available artifacts using the appropriate tool.
-      - Identify which artifacts are relevant to the user's request.
-    - Are the required artifacts already available?
-    - If not, select which artifact(s) will be the most relevant and require them using the require_artifacts tool.
-    - The require'd artifact tools will be available for use after require.
-  `
-      : ''
-  }
-  ${
-    operationModel === 'configured'
-      ? `
-    - Select the most relevant artifact(s) to complete the task.
-    - Call the appropriate tool to use the artifact(s).
-  `
-      : ''
-  }
-
-  ${availableArtifacts.length > 0 ? `Artifacts already in context: ${availableArtifacts.join('\n')}` : ''}
-`;
-
-export class AIServiecOverloadedError extends Schema.TaggedError<AIServiecOverloadedError>()(
-  'AIServiecOverloadedError',
-  {},
-) {}
-
-const gatherObjectVersions = (messages: Message[]): Map<ObjectId, ObjectVersion> => {
-  const artifactIds = new Map<ObjectId, ObjectVersion>();
-  for (const message of messages) {
-    for (const block of message.content) {
-      if (block.type === 'json' && block.disposition === VersionPin.DISPOSITION) {
-        const pin = VersionPin.pipe(Schema.decodeOption)(JSON.parse(block.json)).pipe(Option.getOrUndefined);
-        if (!pin) {
-          continue;
-        }
-        artifactIds.set(pin.objectId, pin.version);
-      }
-    }
-  }
-
-  return artifactIds;
-};
-
-const createArtifactUpdateBlock = (
-  artifactDiff: Map<ObjectId, { version: ObjectVersion; diff?: string }>,
-): MessageContentBlock => {
-  return {
-    type: 'text',
-    disposition: 'artifact-update',
-    text: `
-      The following artifacts have been updated since the last message:
-      ${[...artifactDiff.entries()]
-        .map(([id, { diff }]) => `<changed-artifact id="${id}">${diff ? `\n${diff}` : ''}</changed-artifact>`)
-        .join('\n')}
-    `,
-  };
-};
+/**
+ * Build a combined toolkit from the blueprint tools and the provided toolkit.
+ */
+const createToolkit = <Tools extends AiTool.Any>({
+  toolkit,
+  blueprints = [],
+}: Pick<SessionRunParams<Tools>, 'toolkit' | 'blueprints'>) =>
+  Effect.gen(function* () {
+    const blueprintToolkit = yield* ToolResolverService.resolveToolkit(blueprints.flatMap(({ tools }) => tools));
+    const blueprintToolkitHandler: Context.Context<AiTool.ToHandler<AiTool.Any>> = yield* blueprintToolkit.toContext(
+      ToolExecutionService.handlersFor(blueprintToolkit),
+    );
+
+    return yield* AiToolkit.merge(...[toolkit, blueprintToolkit].filter(isNotFalsy)).pipe(
+      Effect.provide(blueprintToolkitHandler),
+    ) as Effect.Effect<AiToolkit.ToHandler<any>, never, AiTool.ToHandler<Tools>>;
+  });