@od-oneapp/ai-platform 0.1.0

package/src/agents/experimental/index.ts

@@ -0,0 +1,1095 @@
+/**
+ * Experimental Agent Module
+ *
+ * AI SDK v6 Agent patterns with enhanced control:
+ * - prepareStep hook for dynamic model escalation and context trimming
+ * - toolChoice control (auto/required/none/specific)
+ * - InferAgentUIMessage for end-to-end type safety
+ * - Step-based execution with configurable stop conditions
+ *
+ * @module agents/experimental
+ */
+
+import { logWarn } from '@repo/shared/logs';
+
+import { generateText, tool } from '../../shared';
+import {
+  convertFromSDKUsage,
+  generateId,
+  resolveModelId as getModelId,
+  type TokenUsage,
+  type ModelRef,
+  type SDKToolChoice,
+  type SDKTextPart,
+  type SDKFilePart,
+  type SDKToolCallPart,
+  type SDKToolResultPart,
+  type SDKToolApprovalResponse,
+  type SDKModelMessage,
+  type SDKUserMessage,
+  type SDKSystemMessage,
+  type SDKAssistantMessage,
+  type SDKToolMessage,
+  type SDKLanguageModel,
+  type SDKToolSet,
+  type SDKFlexibleSchema,
+  type MessageRole,
+  type CoreMessageRole,
+  type StepFinishReason,
+  type AgentFinishReason,
+} from '../../shared';
+
+import type { z } from 'zod';
+
+// -----------------------------------------------------------------------------
+// Types (SDK-Aligned)
+// -----------------------------------------------------------------------------
+
+/**
+ * Model reference - LanguageModel instance from AI SDK.
+ * Re-exported from ai-types for convenience.
+ */
+export type { ModelRef };
+
+/**
+ * Tool choice options.
+ * Aligned with AI SDK v6's ToolChoice type.
+ * @see SDKToolChoice for the SDK's native type
+ */
+export type ToolChoice = SDKToolChoice<SDKToolSet>;
+
+/**
+ * Token usage tracking.
+ * Re-exported from ai-types for convenience.
+ * @see TokenUsage in ai-types.ts
+ */
+export type { TokenUsage };
+
+/**
+ * Text part - SDK-aligned type for text content in messages.
+ */
+export type TextPart = SDKTextPart;
+
+/**
+ * Tool call part - SDK-aligned type for tool invocations.
+ */
+export type ToolCallPart = SDKToolCallPart;
+
+/**
+ * Tool result part - SDK-aligned type for tool execution results.
+ */
+export type ToolResultPart = SDKToolResultPart;
+
+/**
+ * Message part types union.
+ * Directly uses AI SDK v6 part types for full compatibility.
+ */
+export type MessagePart =
+  | TextPart
+  | SDKFilePart
+  | ToolCallPart
+  | ToolResultPart
+  | SDKToolApprovalResponse;
+
+type JsonValue = string | number | boolean | null | { [key: string]: JsonValue } | JsonValue[];
+
+type AssistantPart = Exclude<MessagePart, SDKToolApprovalResponse>;
+
+/** Tool definition */
+export interface ToolDefinition<TInput = unknown, TOutput = unknown> {
+  readonly description: string;
+  readonly inputSchema: z.ZodSchema<TInput>;
+  readonly execute: (
+    input: TInput,
+    context: ToolExecutionContext,
+  ) => Promise<TOutput> | AsyncIterable<TOutput>;
+  readonly strict?: boolean;
+  readonly inputExamples?: Array<{ input: TInput }>;
+  readonly needsApproval?: boolean | ((input: TInput) => Promise<boolean>);
+}
+
+/** Tool execution context */
+export interface ToolExecutionContext {
+  readonly toolCallId: string;
+  readonly messages: AgentMessage[];
+  readonly abortSignal?: AbortSignal;
+  readonly context?: Record<string, unknown>;
+}
+
+/**
+ * Agent message (SDK-aligned).
+ * Uses SDK message part types for content and MessageRole type.
+ */
+export interface AgentMessage {
+  readonly id: string;
+  readonly role: MessageRole;
+  readonly content: string | MessagePart[];
+  readonly createdAt?: Date;
+}
+
+/**
+ * Step result from agent execution.
+ * Uses SDK-aligned StepFinishReason type.
+ */
+export interface AgentStepResult {
+  readonly stepNumber: number;
+  readonly message: AgentMessage;
+  readonly toolCalls?: Array<{
+    toolName: string;
+    toolCallId: string;
+    input: unknown;
+    output: ToolResultPart['output'];
+    duration?: number;
+  }>;
+  readonly usage?: TokenUsage;
+  readonly finishReason?: StepFinishReason;
+}
+
+/** Base agent configuration for experimental agent */
+export interface ExperimentalAgentBaseConfig<
+  TTools extends Record<string, ToolDefinition> = Record<string, ToolDefinition>,
+> {
+  /** Primary model for agent */
+  readonly model: ModelRef;
+  /** System prompt */
+  readonly system?: string;
+  /** Available tools */
+  readonly tools?: TTools;
+  /** Default tool choice behavior */
+  readonly toolChoice?: ToolChoice;
+  /** Maximum generation steps (default: 10) */
+  readonly maxSteps?: number;
+  /** Custom context passed to tools */
+  readonly context?: Record<string, unknown>;
+  /** Abort signal for cancellation */
+  readonly abortSignal?: AbortSignal;
+}
+
+/** PrepareStep hook input */
+export interface PrepareStepInput {
+  readonly stepNumber: number;
+  readonly messages: AgentMessage[];
+  readonly usage?: TokenUsage[];
+  readonly toolHistory?: Array<{ toolName: string; output: unknown }>;
+}
+
+/** PrepareStep hook output */
+export interface PrepareStepOutput {
+  /** Override model for this step */
+  readonly model?: ModelRef;
+  /** Trimmed/modified messages */
+  readonly messages?: AgentMessage[];
+  /** Override tool choice for this step */
+  readonly toolChoice?: ToolChoice;
+  /** Active tools (subset of available tools) */
+  readonly activeTools?: string[];
+  /** Additional system prompt */
+  readonly appendSystem?: string;
+}
+
+/** Agent with prepareStep hook */
+export interface ExperimentalAgentConfig<
+  TTools extends Record<string, ToolDefinition> = Record<string, ToolDefinition>,
+> extends ExperimentalAgentBaseConfig<TTools> {
+  /** Hook called before each generation step */
+  readonly prepareStep?: (
+    input: PrepareStepInput,
+  ) => Promise<PrepareStepOutput> | PrepareStepOutput;
+  /** Callback after each step completes */
+  readonly onStepComplete?: (result: AgentStepResult) => Promise<void> | void;
+  /** Callback when tool needs approval */
+  readonly onToolApproval?: (
+    toolName: string,
+    input: unknown,
+  ) => Promise<{ approved: boolean; reason?: string }>;
+}
+
+/**
+ * Agent execution result.
+ * Uses SDK-aligned AgentFinishReason type.
+ */
+export interface AgentResult {
+  readonly text: string;
+  readonly steps: AgentStepResult[];
+  readonly usage: TokenUsage;
+  readonly finishReason: AgentFinishReason;
+}
+
+// -----------------------------------------------------------------------------
+// Experimental Agent Class
+// -----------------------------------------------------------------------------
+
+/**
+ * Experimental Agent with enhanced control patterns.
+ *
+ * @example
+ * ```typescript
+ * const agent = new ExperimentalAgent({
+ *   model: openai('gpt-4o'),
+ *   system: 'You are a research assistant.',
+ *   tools: { search, analyze, summarize },
+ *   maxSteps: 15,
+ *
+ *   prepareStep: async ({ stepNumber, messages, usage }) => {
+ *     // Escalate to better model after step 5
+ *     if (stepNumber >= 5) {
+ *       return {
+ *         model: openai('gpt-4-turbo'),
+ *         messages: messages.slice(-10), // Trim history
+ *       };
+ *     }
+ *     return {};
+ *   },
+ * });
+ *
+ * const result = await agent.generate({ prompt: 'Research quantum computing' });
+ * ```
+ */
+export class ExperimentalAgent<
+  TTools extends Record<string, ToolDefinition> = Record<string, ToolDefinition>,
+> {
+  private readonly config: ExperimentalAgentConfig<TTools>;
+  private stepHistory: AgentStepResult[] = [];
+  private totalUsage: TokenUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+  private aborted = false;
+
+  constructor(config: ExperimentalAgentConfig<TTools>) {
+    this.config = {
+      maxSteps: 10,
+      toolChoice: 'auto',
+      ...config,
+    };
+  }
+
+  /** Get all executed steps */
+  get steps(): AgentStepResult[] {
+    return [...this.stepHistory];
+  }
+
+  /** Get total token usage */
+  get usage(): TokenUsage {
+    return { ...this.totalUsage };
+  }
+
+  /**
+   * Generate a response for the given prompt.
+   */
+  async generate(options: { prompt: string; messages?: AgentMessage[] }): Promise<AgentResult> {
+    this.stepHistory = [];
+    this.totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    this.aborted = false;
+
+    const { prompt, messages: initialMessages = [] } = options;
+
+    // Build initial messages
+    let messages: AgentMessage[] = [
+      ...initialMessages,
+      {
+        id: generateId(),
+        role: 'user',
+        content: prompt,
+        createdAt: new Date(),
+      },
+    ];
+
+    const maxSteps = this.config.maxSteps ?? 10;
+    let stepNumber = 0;
+    let finishReason: AgentResult['finishReason'] = 'stop';
+
+    // Main agent loop
+    while (stepNumber < maxSteps && !this.aborted) {
+      // Check abort signal
+      if (this.config.abortSignal?.aborted) {
+        this.aborted = true;
+        finishReason = 'abort';
+        break;
+      }
+
+      stepNumber++;
+
+      // Run prepareStep hook
+      let stepConfig: PrepareStepOutput = {};
+      if (this.config.prepareStep) {
+        stepConfig = await this.config.prepareStep({
+          stepNumber,
+          messages,
+          usage: this.stepHistory.map(s => s.usage).filter(Boolean) as TokenUsage[],
+          toolHistory: this.stepHistory.flatMap(s =>
+            (s.toolCalls ?? []).map(tc => ({ toolName: tc.toolName, output: tc.output })),
+          ),
+        });
+
+        // Apply message trimming if provided
+        const { messages: preparedMessages } = stepConfig;
+        if (preparedMessages) {
+          messages = preparedMessages;
+        }
+      }
+
+      // Determine active tools
+      const tools = this.getActiveTools(stepConfig.activeTools);
+      const toolChoice = stepConfig.toolChoice ?? this.config.toolChoice ?? 'auto';
+      const model = stepConfig.model ?? this.config.model;
+
+      // Execute step (simulated - in real implementation would call AI SDK)
+      const stepResult = await this.executeStep({
+        stepNumber,
+        messages,
+        tools,
+        toolChoice,
+        model,
+        appendSystem: stepConfig.appendSystem,
+      });
+
+      // Track step
+      this.stepHistory.push(stepResult);
+      this.updateUsage(stepResult.usage);
+
+      // Callback
+      if (this.config.onStepComplete) {
+        await this.config.onStepComplete(stepResult);
+      }
+
+      // Add assistant message to history
+      messages = [...messages, stepResult.message];
+
+      // Check if we should stop
+      if (stepResult.finishReason === 'stop') {
+        finishReason = 'stop';
+        break;
+      }
+
+      // Process tool calls
+      if (stepResult.toolCalls && stepResult.toolCalls.length > 0) {
+        for (const toolCall of stepResult.toolCalls) {
+          // Add tool result to messages
+          messages = [
+            ...messages,
+            {
+              id: generateId(),
+              role: 'tool',
+              content: [
+                {
+                  type: 'tool-result',
+                  toolCallId: toolCall.toolCallId,
+                  toolName: toolCall.toolName,
+                  output: toolCall.output,
+                },
+              ],
+            },
+          ];
+        }
+      }
+    }
+
+    // If we hit max steps
+    if (stepNumber >= maxSteps && finishReason !== 'abort') {
+      finishReason = 'max-steps';
+    }
+
+    // Extract final text from last assistant message
+    const lastStep = this.stepHistory[this.stepHistory.length - 1];
+    const text = this.extractText(lastStep?.message);
+
+    return {
+      text,
+      steps: this.stepHistory,
+      usage: this.totalUsage,
+      finishReason,
+    };
+  }
+
+  /**
+   * Stream a response (returns async generator).
+   */
+  async *stream(options: {
+    prompt: string;
+    messages?: AgentMessage[];
+  }): AsyncGenerator<{ type: 'step' | 'text' | 'tool-call' | 'done'; data: unknown }> {
+    // Similar to generate but yields intermediate results
+    this.stepHistory = [];
+    this.totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    this.aborted = false;
+
+    const { prompt, messages: initialMessages = [] } = options;
+
+    let messages: AgentMessage[] = [
+      ...initialMessages,
+      { id: generateId(), role: 'user', content: prompt, createdAt: new Date() },
+    ];
+
+    const maxSteps = this.config.maxSteps ?? 10;
+    let stepNumber = 0;
+
+    while (stepNumber < maxSteps && !this.aborted) {
+      if (this.config.abortSignal?.aborted) {
+        this.aborted = true;
+        break;
+      }
+
+      stepNumber++;
+
+      let stepConfig: PrepareStepOutput = {};
+      if (this.config.prepareStep) {
+        stepConfig = await this.config.prepareStep({
+          stepNumber,
+          messages,
+          usage: this.stepHistory.map(s => s.usage).filter(Boolean) as TokenUsage[],
+          toolHistory: this.stepHistory.flatMap(s =>
+            (s.toolCalls ?? []).map(tc => ({ toolName: tc.toolName, output: tc.output })),
+          ),
+        });
+        const { messages: preparedMessages } = stepConfig;
+        if (preparedMessages) {
+          messages = preparedMessages;
+        }
+      }
+
+      const tools = this.getActiveTools(stepConfig.activeTools);
+      const toolChoice = stepConfig.toolChoice ?? this.config.toolChoice ?? 'auto';
+      const model = stepConfig.model ?? this.config.model;
+
+      const stepResult = await this.executeStep({
+        stepNumber,
+        messages,
+        tools,
+        toolChoice,
+        model,
+        appendSystem: stepConfig.appendSystem,
+      });
+
+      this.stepHistory.push(stepResult);
+      this.updateUsage(stepResult.usage);
+
+      yield { type: 'step', data: stepResult };
+
+      if (stepResult.toolCalls) {
+        for (const tc of stepResult.toolCalls) {
+          yield { type: 'tool-call', data: tc };
+        }
+      }
+
+      const text = this.extractText(stepResult.message);
+      if (text) {
+        yield { type: 'text', data: text };
+      }
+
+      if (this.config.onStepComplete) {
+        await this.config.onStepComplete(stepResult);
+      }
+
+      messages = [...messages, stepResult.message];
+
+      if (stepResult.finishReason === 'stop') break;
+
+      if (stepResult.toolCalls?.length) {
+        for (const tc of stepResult.toolCalls) {
+          messages = [
+            ...messages,
+            {
+              id: generateId(),
+              role: 'tool',
+              content: [
+                {
+                  type: 'tool-result',
+                  toolCallId: tc.toolCallId,
+                  toolName: tc.toolName,
+                  output: tc.output,
+                },
+              ],
+            },
+          ];
+        }
+      }
+    }
+
+    yield {
+      type: 'done',
+      data: {
+        steps: this.stepHistory,
+        usage: this.totalUsage,
+        finishReason: this.aborted ? 'abort' : stepNumber >= maxSteps ? 'max-steps' : 'stop',
+      },
+    };
+  }
+
+  /**
+   * Abort the current execution.
+   */
+  abort(): void {
+    this.aborted = true;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private Methods
+  // ---------------------------------------------------------------------------
+
+  private getActiveTools(activeToolNames?: string[]): Record<string, ToolDefinition> {
+    if (!this.config.tools) return {};
+
+    if (!activeToolNames) {
+      return this.config.tools as Record<string, ToolDefinition>;
+    }
+
+    const result: Record<string, ToolDefinition> = {};
+    for (const name of activeToolNames) {
+      const tool = (this.config.tools as Record<string, ToolDefinition>)[name];
+      if (tool) {
+        result[name] = tool;
+      }
+    }
+    return result;
+  }
+
+  private async executeStep(options: {
+    stepNumber: number;
+    messages: AgentMessage[];
+    tools: Record<string, ToolDefinition>;
+    toolChoice: ToolChoice;
+    model: ModelRef;
+    appendSystem?: string;
+  }): Promise<AgentStepResult> {
+    const { stepNumber, messages, tools, toolChoice, model, appendSystem } = options;
+
+    // Validate model is a proper LanguageModel instance
+    // ModelRef allows string | { modelId: string } but we need LanguageModel
+    if (
+      typeof model === 'string' ||
+      (typeof model === 'object' &&
+        model !== null &&
+        'modelId' in model &&
+        !('doGenerate' in model))
+    ) {
+      throw new Error(
+        'Model must be a LanguageModel instance (e.g., from openai("gpt-4o")), not a plain string or object with modelId',
+      );
+    }
+    const languageModel = model as SDKLanguageModel;
+
+    // Convert AgentMessage[] to AI SDK format
+    const sdkMessages = this.convertMessagesToSDK(messages);
+
+    // Build system prompt
+    let systemPrompt = this.config.system;
+    if (appendSystem) {
+      systemPrompt = systemPrompt ? `${systemPrompt}\n\n${appendSystem}` : appendSystem;
+    }
+
+    // Convert tools to AI SDK format
+    const sdkTools = this.convertToolsToSDK(tools);
+
+    // Convert toolChoice to AI SDK format
+    const sdkToolChoice = this.convertToolChoiceToSDK(toolChoice);
+
+    // Call AI SDK generateText
+    const result = await generateText({
+      model: languageModel,
+      system: systemPrompt,
+      messages: sdkMessages,
+      tools: sdkTools,
+      toolChoice: sdkToolChoice,
+      abortSignal: this.config.abortSignal,
+    });
+
+    // Process tool calls
+    const toolCalls: AgentStepResult['toolCalls'] = [];
+
+    if (result.toolCalls && result.toolCalls.length > 0) {
+      for (const toolCall of result.toolCalls) {
+        const { toolName } = toolCall;
+        const tool = tools[toolName];
+
+        if (!tool) {
+          // Log warning for observability - tool name from model doesn't match registered tools
+          logWarn(`[ExperimentalAgent] Unknown tool "${toolName}" requested by model`);
+          continue;
+        }
+
+        const startTime = Date.now();
+
+        // Check approval if needed
+        let approved = true;
+        const input = toolCall.input ?? {};
+        let needsApprovalCheck = false;
+        if (tool.needsApproval) {
+          if (typeof tool.needsApproval === 'function') {
+            needsApprovalCheck = await tool.needsApproval(input);
+          } else {
+            needsApprovalCheck = tool.needsApproval;
+          }
+        }
+        if (needsApprovalCheck) {
+          if (!this.config.onToolApproval) {
+            // HITL approval required but no handler configured - reject tool execution
+            throw new Error(
+              `Tool "${toolName}" requires approval but no onToolApproval handler is configured. ` +
+                `Either provide an onToolApproval callback or set needsApproval: false for this tool.`,
+            );
+          }
+          const approvalResult = await this.config.onToolApproval(toolName, input);
+          const { approved: approvedResult } = approvalResult;
+          approved = approvedResult;
+        }
+
+        if (approved) {
+          const { toolCallId } = toolCall;
+
+          const toolResult = await this.executeToolCall(tool, input, {
+            toolCallId,
+            messages,
+            abortSignal: this.config.abortSignal,
+            context: this.config.context,
+          });
+          const output = this.toToolOutput(toolResult);
+
+          toolCalls.push({
+            toolName,
+            toolCallId,
+            input,
+            output,
+            duration: Date.now() - startTime,
+          });
+        } else {
+          // Add denied tool result to message history so model knows the call was rejected
+          const { toolCallId } = toolCall;
+          const output = this.toToolOutput('Tool call denied by approval handler');
+          toolCalls.push({
+            toolName,
+            toolCallId,
+            input,
+            output,
+            duration: Date.now() - startTime,
+          });
+        }
+      }
+    }
+
+    // Convert result to AgentMessage format
+    const message: AgentMessage = {
+      id: generateId(),
+      role: 'assistant',
+      content:
+        toolCalls.length > 0
+          ? toolCalls.map(tc => ({
+              type: 'tool-call' as const,
+              toolCallId: tc.toolCallId,
+              toolName: tc.toolName,
+              input: tc.input,
+            }))
+          : result.text,
+      createdAt: new Date(),
+    };
+
+    // Convert usage
+    const usage = result.usage
+      ? convertFromSDKUsage(result.usage)
+      : {
+          promptTokens: 0,
+          completionTokens: 0,
+          totalTokens: 0,
+        };
+
+    // Determine finish reason
+    let finishReason: AgentStepResult['finishReason'] = 'stop';
+    if (result.finishReason === 'tool-calls') {
+      finishReason = 'tool-calls';
+    } else if (result.finishReason === 'length') {
+      finishReason = 'length';
+    } else if (result.finishReason === 'content-filter') {
+      finishReason = 'content-filter';
+    }
+
+    return {
+      stepNumber,
+      message,
+      toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+      usage,
+      finishReason,
+    };
+  }
+
+  private async executeToolCall(
+    tool: ToolDefinition,
+    input: unknown,
+    context: ToolExecutionContext,
+  ): Promise<unknown> {
+    // Validate input against schema before execution
+    const parsedInput = tool.inputSchema.parse(input);
+    const result = tool.execute(parsedInput, context);
+
+    if (isAsyncIterable(result)) {
+      // Collect all yielded values - return all values for async iterables
+      const values: unknown[] = [];
+      for await (const value of result) {
+        values.push(value);
+      }
+      // Return single value if only one, otherwise return all values
+      return values.length === 1 ? values[0] : values;
+    }
+
+    return result;
+  }
+
+  private extractText(message?: AgentMessage): string {
+    if (!message) return '';
+    if (typeof message.content === 'string') return message.content;
+    const textParts = message.content.filter(
+      (p): p is { type: 'text'; text: string } => p.type === 'text',
+    );
+    return textParts.map(p => p.text).join('');
+  }
+
+  private updateUsage(usage?: TokenUsage): void {
+    if (!usage) return;
+    this.totalUsage = {
+      promptTokens: this.totalUsage.promptTokens + usage.promptTokens,
+      completionTokens: this.totalUsage.completionTokens + usage.completionTokens,
+      totalTokens: this.totalUsage.totalTokens + usage.totalTokens,
+    };
+  }
+
+  private isTextPart(part: MessagePart): part is TextPart {
+    return part.type === 'text';
+  }
+
+  private isFilePart(part: MessagePart): part is SDKFilePart {
+    return part.type === 'file';
+  }
+
+  private isAssistantPart(part: MessagePart): part is AssistantPart {
+    return part.type !== 'tool-approval-response';
+  }
+
+  private partsToText(parts: MessagePart[]): string {
+    return parts
+      .filter(part => this.isTextPart(part))
+      .map(part => part.text)
+      .join('\n');
+  }
+
+  private isJsonValue(value: unknown): value is JsonValue {
+    if (value === null) return true;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+      return true;
+    }
+    if (Array.isArray(value)) {
+      return value.every(item => this.isJsonValue(item));
+    }
+    if (typeof value === 'object') {
+      return Object.values(value).every(item => this.isJsonValue(item));
+    }
+    return false;
+  }
+
+  private convertMessagesToSDK(messages: AgentMessage[]): SDKModelMessage[] {
+    return messages.map<SDKModelMessage>(msg => {
+      if (msg.role === 'tool') {
+        if (typeof msg.content === 'string') {
+          const toolMessage: SDKToolMessage = {
+            role: 'tool',
+            content: [
+              {
+                type: 'tool-result',
+                toolCallId: 'unknown',
+                toolName: 'unknown',
+                output: this.toToolOutput(msg.content),
+              },
+            ],
+          };
+          return toolMessage;
+        }
+        const toolMessage: SDKToolMessage = {
+          role: 'tool',
+          content: this.normalizeToolContent(msg.content),
+        };
+        return toolMessage;
+      }
+
+      if (msg.role === 'system') {
+        const systemMessage: SDKSystemMessage = {
+          role: 'system',
+          content: typeof msg.content === 'string' ? msg.content : this.partsToText(msg.content),
+        };
+        return systemMessage;
+      }
+
+      if (msg.role === 'user') {
+        if (typeof msg.content === 'string') {
+          const userMessage: SDKUserMessage = { role: 'user', content: msg.content };
+          return userMessage;
+        }
+        const userParts = msg.content.filter(
+          part => this.isTextPart(part) || this.isFilePart(part),
+        );
+        if (userParts.length === msg.content.length) {
+          const userMessage: SDKUserMessage = { role: 'user', content: userParts };
+          return userMessage;
+        }
+        const userMessage: SDKUserMessage = {
+          role: 'user',
+          content: this.partsToText(msg.content),
+        };
+        return userMessage;
+      }
+
+      if (typeof msg.content === 'string') {
+        const assistantMessage: SDKAssistantMessage = {
+          role: 'assistant',
+          content: msg.content,
+        };
+        return assistantMessage;
+      }
+
+      const assistantParts = msg.content.filter(this.isAssistantPart).map(part => {
+        if (part.type === 'tool-call') {
+          return { ...part, input: part.input };
+        }
+        return part;
+      });
+
+      const assistantMessage: SDKAssistantMessage = {
+        role: 'assistant',
+        content: assistantParts.length > 0 ? assistantParts : '',
+      };
+      return assistantMessage;
+    });
+  }
+
+  private normalizeToolContent(
+    parts: MessagePart[],
+  ): Array<ToolResultPart | SDKToolApprovalResponse> {
+    const toolContent = parts.filter(
+      (part): part is ToolResultPart | SDKToolApprovalResponse =>
+        part.type === 'tool-result' || part.type === 'tool-approval-response',
+    );
+    if (toolContent.length === parts.length && toolContent.length > 0) {
+      return toolContent.map(part => {
+        if (part.type !== 'tool-result') {
+          return part;
+        }
+        return {
+          ...part,
+          output: this.toToolOutput(part.output),
+        };
+      });
+    }
+
+    const textValue = parts
+      .filter((part): part is TextPart => part.type === 'text')
+      .map(part => part.text)
+      .join('\n');
+    return [
+      {
+        type: 'tool-result',
+        toolCallId: 'unknown',
+        toolName: 'unknown',
+        output: this.toToolOutput(textValue || ''),
+      },
+    ];
+  }
+
+  private toToolOutput(value: unknown): ToolResultPart['output'] {
+    if (value && typeof value === 'object' && 'type' in value) {
+      const output = value as ToolResultPart['output'];
+      if (typeof output.type === 'string') {
+        return output;
+      }
+    }
+    if (value instanceof Error) {
+      return { type: 'error-text', value: value.message };
+    }
+    if (typeof value === 'string') {
+      return { type: 'text', value };
+    }
+    if (value === undefined) {
+      return { type: 'json', value: null };
+    }
+    if (this.isJsonValue(value)) {
+      return { type: 'json', value };
+    }
+    const serialized = JSON.stringify(value);
+    return { type: 'text', value: serialized ?? String(value) };
+  }
+
+  private convertToolsToSDK(tools: Record<string, ToolDefinition>): SDKToolSet {
+    const sdkTools: SDKToolSet = {};
+
+    for (const [name, toolDef] of Object.entries(tools)) {
+      // Create placeholder tools for SDK - actual execution happens manually
+      // with proper ToolExecutionContext after we get toolCallId from result
+      const inputSchema = toolDef.inputSchema as SDKFlexibleSchema;
+      sdkTools[name] = tool<unknown, { placeholder: boolean }>({
+        description: toolDef.description,
+        inputSchema,
+        execute: async (input, options) => {
+          // Placeholder - actual execution happens manually in executeStep
+          // This allows SDK to decide which tools to call, but we control execution
+          void input;
+          void options;
+          return { placeholder: true };
+        },
+      });
+    }
+
+    return sdkTools;
+  }
+
+  private convertToolChoiceToSDK(
+    toolChoice: ToolChoice,
+  ): 'auto' | 'required' | 'none' | { type: 'tool'; toolName: string } {
+    if (toolChoice === 'auto' || toolChoice === 'required' || toolChoice === 'none') {
+      return toolChoice;
+    }
+
+    if (typeof toolChoice === 'object' && toolChoice.type === 'tool') {
+      return { type: 'tool', toolName: toolChoice.toolName };
+    }
+
+    return 'auto';
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Type Inference Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Infer UI message type from agent definition.
+ *
+ * @example
+ * ```typescript
+ * const agent = new ExperimentalAgent({
+ *   model: openai('gpt-4o'),
+ *   tools: { search, analyze },
+ * });
+ *
+ * type MyUIMessage = InferAgentUIMessage<typeof agent>;
+ * // MyUIMessage includes tool call types for 'search' and 'analyze'
+ * ```
+ */
+export type InferAgentUIMessage<TAgent extends ExperimentalAgent<Record<string, ToolDefinition>>> =
+  TAgent extends ExperimentalAgent<infer TTools>
+    ? {
+        id: string;
+        role: CoreMessageRole;
+        content: string;
+        toolInvocations?: Array<{
+          toolCallId: string;
+          toolName: keyof TTools;
+          state: 'pending' | 'running' | 'completed' | 'failed';
+          input: unknown;
+          output?: unknown;
+        }>;
+      }
+    : never;
+
+/**
+ * Infer tool types from agent.
+ */
+export type InferAgentTools<TAgent extends ExperimentalAgent<Record<string, ToolDefinition>>> =
+  TAgent extends ExperimentalAgent<infer TTools> ? TTools : never;
+
+// -----------------------------------------------------------------------------
+// Factory Functions
+// -----------------------------------------------------------------------------
+
+/**
+ * Create an experimental agent with simplified configuration.
+ *
+ * @example
+ * ```typescript
+ * const agent = createExperimentalAgent({
+ *   model: openai('gpt-4o'),
+ *   system: 'You are helpful.',
+ *   tools: { search, analyze },
+ * });
+ * ```
+ */
+export function createExperimentalAgent<TTools extends Record<string, ToolDefinition>>(
+  config: ExperimentalAgentConfig<TTools>,
+): ExperimentalAgent<TTools> {
+  return new ExperimentalAgent(config);
+}
+
+/**
+ * Create a prepareStep hook for model escalation.
+ *
+ * @example
+ * ```typescript
+ * const prepareStep = createModelEscalation({
+ *   defaultModel: openai('gpt-4o-mini'),
+ *   escalateAfterStep: 5,
+ *   escalatedModel: openai('gpt-4o'),
+ *   trimMessagesTo: 10,
+ * });
+ * ```
+ */
+export function createModelEscalation(options: {
+  defaultModel: ModelRef;
+  escalateAfterStep: number;
+  escalatedModel: ModelRef;
+  trimMessagesTo?: number;
+}): (input: PrepareStepInput) => PrepareStepOutput {
+  const { defaultModel, escalateAfterStep, escalatedModel, trimMessagesTo } = options;
+
+  return ({ stepNumber, messages }) => {
+    const model = stepNumber >= escalateAfterStep ? escalatedModel : defaultModel;
+    const trimmedMessages = trimMessagesTo ? messages.slice(-trimMessagesTo) : messages;
+
+    return {
+      model,
+      messages: trimmedMessages,
+    };
+  };
+}
+
+/**
+ * Create a prepareStep hook for phased tool availability.
+ *
+ * @example
+ * ```typescript
+ * const prepareStep = createPhasedTools({
+ *   phases: [
+ *     { steps: [1, 2, 3], activeTools: ['search'], toolChoice: 'required' },
+ *     { steps: [4, 5, 6], activeTools: ['analyze'], toolChoice: 'required' },
+ *     { steps: [7, 8, 9, 10], activeTools: ['summarize', 'report'], toolChoice: 'auto' },
+ *   ],
+ * });
+ * ```
+ */
+export function createPhasedTools(options: {
+  phases: Array<{
+    steps: number[];
+    activeTools: string[];
+    toolChoice?: ToolChoice;
+  }>;
+}): (input: PrepareStepInput) => PrepareStepOutput {
+  return ({ stepNumber }) => {
+    for (const phase of options.phases) {
+      if (phase.steps.includes(stepNumber)) {
+        return {
+          activeTools: phase.activeTools,
+          toolChoice: phase.toolChoice,
+        };
+      }
+    }
+    return {};
+  };
+}
+
+// -----------------------------------------------------------------------------
+// Utilities
+// -----------------------------------------------------------------------------
+
+function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
+  return (
+    value != null && typeof (value as AsyncIterable<unknown>)[Symbol.asyncIterator] === 'function'
+  );
+}
+
+// -----------------------------------------------------------------------------
+// Re-exports
+// -----------------------------------------------------------------------------
+
+export { generateId, getModelId };
+export type { MessageRole, CoreMessageRole, StepFinishReason, AgentFinishReason };