@langwatch/scenario 0.2.9 → 0.2.11

package/dist/index.mjs

@@ -17,11 +17,11 @@ import {
   getBatchRunId,
   getProjectConfig,
   scenarioProjectConfigSchema
-} from "./chunk-7H6OGEQ5.mjs";
+} from "./chunk-7HLDX5EL.mjs";
 import {
   Logger,
-  env
-} from "./chunk-YPJZSK4J.mjs";
+  getEnv
+} from "./chunk-OL4RFXV4.mjs";
 import {
   __export
 } from "./chunk-7P6ASYW6.mjs";
@@ -163,88 +163,109 @@ function buildFinishTestTool(criteria) {
     })
   });
 }
-var judgeAgent = (cfg) => {
-  return {
-    role: "Judge" /* JUDGE */,
-    criteria: cfg.criteria,
-    call: async (input) => {
-      var _a;
-      const systemPrompt = cfg.systemPrompt ?? buildSystemPrompt(cfg.criteria, input.scenarioConfig.description);
-      const messages = [
-        { role: "system", content: systemPrompt },
-        ...input.messages
-      ];
-      const isLastMessage = input.scenarioState.currentTurn === input.scenarioConfig.maxTurns;
-      const projectConfig = await getProjectConfig();
-      const mergedConfig = mergeAndValidateConfig(cfg, projectConfig);
-      if (!mergedConfig.model) {
-        throw new Error("Model is required for the judge agent");
-      }
-      const tools = {
-        continue_test: buildContinueTestTool(),
-        finish_test: buildFinishTestTool(cfg.criteria)
-      };
-      const enforceJudgement = input.judgmentRequest;
-      const hasCriteria = cfg.criteria.length && cfg.criteria.length > 0;
-      if (enforceJudgement && !hasCriteria) {
-        return {
-          success: false,
-          messages: [],
-          reasoning: "JudgeAgent: No criteria was provided to be judged against",
-          metCriteria: [],
-          unmetCriteria: []
-        };
-      }
-      const toolChoice = (isLastMessage || enforceJudgement) && hasCriteria ? { type: "tool", toolName: "finish_test" } : "required";
-      const completion = await generateText({
-        model: mergedConfig.model,
-        messages,
-        temperature: mergedConfig.temperature ?? 0,
-        maxTokens: mergedConfig.maxTokens,
-        tools,
-        toolChoice
-      });
-      let args;
-      if ((_a = completion.toolCalls) == null ? void 0 : _a.length) {
-        const toolCall = completion.toolCalls[0];
-        switch (toolCall.toolName) {
-          case "finish_test": {
-            args = toolCall.args;
-            const verdict = args.verdict || "inconclusive";
-            const reasoning = args.reasoning || "No reasoning provided";
-            const criteria = args.criteria || {};
-            const criteriaValues = Object.values(criteria);
-            const metCriteria = cfg.criteria.filter((_, i) => criteriaValues[i] === "true");
-            const unmetCriteria = cfg.criteria.filter((_, i) => criteriaValues[i] !== "true");
-            return {
-              success: verdict === "success",
-              messages: input.messages,
-              reasoning,
-              metCriteria,
-              unmetCriteria
-            };
-          }
-          case "continue_test":
-            return [];
-          default:
-            return {
-              success: false,
-              messages: input.messages,
-              reasoning: `JudgeAgent: Unknown tool call: ${toolCall.toolName}`,
-              metCriteria: [],
-              unmetCriteria: cfg.criteria
-            };
-        }
-      }
+var JudgeAgent = class extends JudgeAgentAdapter {
+  constructor(cfg) {
+    super();
+    this.cfg = cfg;
+    this.criteria = cfg.criteria;
+    this.role = "Judge" /* JUDGE */;
+  }
+  logger = new Logger("JudgeAgent");
+  role = "Judge" /* JUDGE */;
+  criteria;
+  async call(input) {
+    var _a;
+    const cfg = this.cfg;
+    const systemPrompt = cfg.systemPrompt ?? buildSystemPrompt(cfg.criteria, input.scenarioConfig.description);
+    const messages = [
+      { role: "system", content: systemPrompt },
+      ...input.messages
+    ];
+    const isLastMessage = input.scenarioState.currentTurn === input.scenarioConfig.maxTurns;
+    const projectConfig = await getProjectConfig();
+    const mergedConfig = mergeAndValidateConfig(cfg, projectConfig);
+    if (!mergedConfig.model) {
+      throw new Error("Model is required for the judge agent");
+    }
+    const tools = {
+      continue_test: buildContinueTestTool(),
+      finish_test: buildFinishTestTool(cfg.criteria)
+    };
+    const enforceJudgement = input.judgmentRequest;
+    const hasCriteria = cfg.criteria.length && cfg.criteria.length > 0;
+    if (enforceJudgement && !hasCriteria) {
       return {
         success: false,
-        messages: input.messages,
-        reasoning: `JudgeAgent: No tool call found in LLM output`,
+        messages: [],
+        reasoning: "JudgeAgent: No criteria was provided to be judged against",
         metCriteria: [],
-        unmetCriteria: cfg.criteria
+        unmetCriteria: []
       };
     }
-  };
+    const toolChoice = (isLastMessage || enforceJudgement) && hasCriteria ? { type: "tool", toolName: "finish_test" } : "required";
+    const completion = await this.generateText({
+      model: mergedConfig.model,
+      messages,
+      temperature: mergedConfig.temperature ?? 0,
+      maxTokens: mergedConfig.maxTokens,
+      tools,
+      toolChoice
+    });
+    let args;
+    if ((_a = completion.toolCalls) == null ? void 0 : _a.length) {
+      const toolCall = completion.toolCalls[0];
+      switch (toolCall.toolName) {
+        case "finish_test": {
+          args = toolCall.args;
+          const verdict = args.verdict || "inconclusive";
+          const reasoning = args.reasoning || "No reasoning provided";
+          const criteria = args.criteria || {};
+          const criteriaValues = Object.values(criteria);
+          const metCriteria = cfg.criteria.filter(
+            (_, i) => criteriaValues[i] === "true"
+          );
+          const unmetCriteria = cfg.criteria.filter(
+            (_, i) => criteriaValues[i] !== "true"
+          );
+          return {
+            success: verdict === "success",
+            messages: input.messages,
+            reasoning,
+            metCriteria,
+            unmetCriteria
+          };
+        }
+        case "continue_test":
+          return [];
+        default:
+          return {
+            success: false,
+            messages: input.messages,
+            reasoning: `JudgeAgent: Unknown tool call: ${toolCall.toolName}`,
+            metCriteria: [],
+            unmetCriteria: cfg.criteria
+          };
+      }
+    }
+    return {
+      success: false,
+      messages: input.messages,
+      reasoning: `JudgeAgent: No tool call found in LLM output`,
+      metCriteria: [],
+      unmetCriteria: cfg.criteria
+    };
+  }
+  async generateText(input) {
+    try {
+      return await generateText(input);
+    } catch (error) {
+      this.logger.error("Error generating text", { error });
+      throw error;
+    }
+  }
+};
+var judgeAgent = (cfg) => {
+  return new JudgeAgent(cfg);
 };
 
 // src/agents/user-simulator-agent.ts
@@ -269,52 +290,75 @@ ${description}
 </rules>
 `.trim();
 }
-var userSimulatorAgent = (config) => {
-  return {
-    role: "User" /* USER */,
-    call: async (input) => {
-      const systemPrompt = (config == null ? void 0 : config.systemPrompt) ?? buildSystemPrompt2(input.scenarioConfig.description);
-      const messages = [
-        { role: "system", content: systemPrompt },
-        { role: "assistant", content: "Hello, how can I help you today" },
-        ...input.messages
-      ];
-      const projectConfig = await getProjectConfig();
-      const mergedConfig = mergeAndValidateConfig(config ?? {}, projectConfig);
-      if (!mergedConfig.model) {
-        throw new Error("Model is required for the user simulator agent");
-      }
-      const reversedMessages = messageRoleReversal(messages);
-      const completion = await generateText2({
-        model: mergedConfig.model,
-        messages: reversedMessages,
-        temperature: mergedConfig.temperature ?? DEFAULT_TEMPERATURE,
-        maxTokens: mergedConfig.maxTokens
-      });
-      const messageContent = completion.text;
-      if (!messageContent) {
-        throw new Error("No response content from LLM");
-      }
-      return { role: "user", content: messageContent };
+var UserSimulatorAgent = class extends UserSimulatorAgentAdapter {
+  constructor(cfg) {
+    super();
+    this.cfg = cfg;
+  }
+  logger = new Logger(this.constructor.name);
+  call = async (input) => {
+    const config = this.cfg;
+    const systemPrompt = (config == null ? void 0 : config.systemPrompt) ?? buildSystemPrompt2(input.scenarioConfig.description);
+    const messages = [
+      { role: "system", content: systemPrompt },
+      { role: "assistant", content: "Hello, how can I help you today" },
+      ...input.messages
+    ];
+    const projectConfig = await getProjectConfig();
+    const mergedConfig = mergeAndValidateConfig(config ?? {}, projectConfig);
+    if (!mergedConfig.model) {
+      throw new Error("Model is required for the user simulator agent");
+    }
+    const reversedMessages = messageRoleReversal(messages);
+    const completion = await this.generateText({
+      model: mergedConfig.model,
+      messages: reversedMessages,
+      temperature: mergedConfig.temperature ?? DEFAULT_TEMPERATURE,
+      maxTokens: mergedConfig.maxTokens
+    });
+    const messageContent = completion.text;
+    if (!messageContent) {
+      throw new Error("No response content from LLM");
     }
+    return { role: "user", content: messageContent };
   };
+  async generateText(input) {
+    try {
+      return await generateText2(input);
+    } catch (error) {
+      this.logger.error("Error generating text", { error });
+      throw error;
+    }
+  }
+};
+var userSimulatorAgent = (config) => {
+  return new UserSimulatorAgent(config);
 };
 
 // src/execution/index.ts
 var execution_exports = {};
 __export(execution_exports, {
   ScenarioExecution: () => ScenarioExecution,
-  ScenarioExecutionState: () => ScenarioExecutionState
+  ScenarioExecutionState: () => ScenarioExecutionState,
+  StateChangeEventType: () => StateChangeEventType
 });
 
 // src/execution/scenario-execution.ts
-import { Subject } from "rxjs";
+import { filter, Subject as Subject2 } from "rxjs";
 
 // src/execution/scenario-execution-state.ts
+import { Subject } from "rxjs";
+var StateChangeEventType = /* @__PURE__ */ ((StateChangeEventType2) => {
+  StateChangeEventType2["MESSAGE_ADDED"] = "MESSAGE_ADDED";
+  return StateChangeEventType2;
+})(StateChangeEventType || {});
 var ScenarioExecutionState = class {
   _messages = [];
   _currentTurn = 0;
   _threadId = "";
+  /** Event stream for message additions */
+  eventSubject = new Subject();
+  events$ = this.eventSubject.asObservable();
   description;
   config;
   constructor(config) {
@@ -342,7 +386,9 @@ var ScenarioExecutionState = class {
    * @param message - The message to add.
    */
   addMessage(message2) {
-    this._messages.push({ ...message2, id: generateMessageId() });
+    const messageWithId = { ...message2, id: generateMessageId() };
+    this._messages.push(messageWithId);
+    this.eventSubject.next({ type: "MESSAGE_ADDED" /* MESSAGE_ADDED */ });
   }
   lastMessage() {
     if (this._messages.length === 0) {
@@ -354,7 +400,9 @@ var ScenarioExecutionState = class {
     if (this._messages.length === 0) {
       throw new Error("No messages in history");
     }
-    const lastMessage = this._messages.findLast((message2) => message2.role === "user");
+    const lastMessage = this._messages.findLast(
+      (message2) => message2.role === "user"
+    );
     if (!lastMessage) {
       throw new Error("No user message in history");
     }
@@ -364,7 +412,9 @@ var ScenarioExecutionState = class {
     if (this._messages.length === 0) {
       throw new Error("No messages in history");
     }
-    const lastMessage = this._messages.findLast((message2) => message2.role === "assistant");
+    const lastMessage = this._messages.findLast(
+      (message2) => message2.role === "assistant"
+    );
     if (!lastMessage) {
       throw new Error("No agent message in history");
     }
@@ -374,9 +424,11 @@ var ScenarioExecutionState = class {
     if (this._messages.length === 0) {
       throw new Error("No messages in history");
     }
-    const lastMessage = this._messages.findLast((message2) => message2.role === "tool" && message2.content.find(
-      (part) => part.type === "tool-result" && part.toolName === toolName
-    ));
+    const lastMessage = this._messages.findLast(
+      (message2) => message2.role === "tool" && message2.content.find(
+        (part) => part.type === "tool-result" && part.toolName === toolName
+      )
+    );
     return lastMessage;
   }
   hasToolCall(toolName) {
@@ -388,7 +440,7 @@ var ScenarioExecutionState = class {
   }
 };
 
-// src/utils/message-conversion.ts
+// src/utils/convert-core-messages-to-agui-messages.ts
 function convertCoreMessagesToAguiMessages(coreMessages) {
   const aguiMessages = [];
   for (const msg of coreMessages) {
@@ -457,30 +509,53 @@ function convertCoreMessagesToAguiMessages(coreMessages) {
   }
   return aguiMessages;
 }
-var message_conversion_default = convertCoreMessagesToAguiMessages;
+var convert_core_messages_to_agui_messages_default = convertCoreMessagesToAguiMessages;
 
 // src/execution/scenario-execution.ts
 var ScenarioExecution = class {
+  /** The current state of the scenario execution */
   state;
-  eventSubject = new Subject();
+  /** Logger for debugging and monitoring */
   logger = new Logger("scenario.execution.ScenarioExecution");
+  /** Finalized configuration with all defaults applied */
   config;
+  /** Array of all agents participating in the scenario */
   agents = [];
+  /** Roles that still need to act in the current turn (USER, AGENT, JUDGE) */
   pendingRolesOnTurn = [];
+  /** Agents that still need to act in the current turn */
   pendingAgentsOnTurn = /* @__PURE__ */ new Set();
+  /**
+   * Message queues for each agent. When an agent sends a message, it gets
+   * broadcast to all other agents' pending message queues. When an agent
+   * is called, it receives these pending messages as part of its input.
+   *
+   * Key: agent index, Value: array of pending messages for that agent
+   */
   pendingMessages = /* @__PURE__ */ new Map();
+  /** Intermediate result set by agents that make final decisions */
   partialResult = null;
+  /** Accumulated execution time for each agent (for performance tracking) */
   agentTimes = /* @__PURE__ */ new Map();
+  /** Timestamp when execution started (for total time calculation) */
   totalStartTime = 0;
+  /** Event stream for monitoring scenario progress */
+  eventSubject = new Subject2();
   /**
    * An observable stream of events that occur during the scenario execution.
    * Subscribe to this to monitor the progress of the scenario in real-time.
+   *
+   * Events include:
+   * - RUN_STARTED: When scenario execution begins
+   * - MESSAGE_SNAPSHOT: After each message is added to the conversation
+   * - RUN_FINISHED: When scenario execution completes (success/failure/error)
    */
   events$ = this.eventSubject.asObservable();
   /**
    * Creates a new ScenarioExecution instance.
-   * @param config The scenario configuration.
-   * @param script The script steps to execute.
+   *
+   * @param config - The scenario configuration containing agents, settings, and metadata
+   * @param script - The ordered sequence of script steps that define the test flow
    */
   constructor(config, script) {
     this.config = {
@@ -498,13 +573,18 @@ var ScenarioExecution = class {
     this.reset();
   }
   /**
-   * The history of messages in the conversation.
+   * Gets the complete conversation history as an array of messages.
+   *
+   * @returns Array of CoreMessage objects representing the full conversation
    */
   get messages() {
     return this.state.messages;
   }
   /**
-   * The unique identifier for the conversation thread.
+   * Gets the unique identifier for the conversation thread.
+   * This ID is used to maintain conversation context across multiple runs.
+   *
+   * @returns The thread identifier string
    */
   get threadId() {
     return this.state.threadId;
@@ -517,21 +597,43 @@ var ScenarioExecution = class {
   }
   /**
    * Executes the entire scenario from start to finish.
-   * This will run through the script and any automatic proceeding logic until a
-   * final result (success, failure, or error) is determined.
-   * @returns A promise that resolves with the final result of the scenario.
+   *
+   * This method runs through all script steps sequentially until a final result
+   * (success, failure, or error) is determined. Each script step can trigger one or
+   * more agent interactions depending on the step type:
+   * - `user()` and `agent()` steps typically trigger one agent interaction each
+   * - `proceed()` steps can trigger multiple agent interactions across multiple turns
+   * - `judge()` steps trigger the judge agent to evaluate the conversation
+   * - `succeed()` and `fail()` steps immediately end the scenario
+   *
+   * The execution will stop early if:
+   * - A script step returns a ScenarioResult
+   * - The maximum number of turns is reached
+   * - An error occurs during execution
+   *
+   * @returns A promise that resolves with the final result of the scenario
+   * @throws Error if an unhandled exception occurs during execution
+   *
+   * @example
+   * ```typescript
+   * const execution = new ScenarioExecution(config, script);
+   * const result = await execution.execute();
+   * console.log(`Scenario ${result.success ? 'passed' : 'failed'}`);
+   * ```
    */
   async execute() {
     this.reset();
     const scenarioRunId = generateScenarioRunId();
     this.emitRunStarted({ scenarioRunId });
+    const subscription = this.state.events$.pipe(
+      filter((event) => event.type === "MESSAGE_ADDED" /* MESSAGE_ADDED */)
+    ).subscribe(() => {
+      this.emitMessageSnapshot({ scenarioRunId });
+    });
     try {
-      for (const scriptStep of this.config.script) {
-        this.logger.debug(`[${this.config.id}] Executing script step`, {
-          scriptStep
-        });
-        const result = await scriptStep(this.state, this);
-        this.emitMessageSnapshot({ scenarioRunId });
+      for (let i = 0; i < this.config.script.length; i++) {
+        const scriptStep = this.config.script[i];
+        const result = await this.executeScriptStep(scriptStep, i);
         if (result && typeof result === "object" && "success" in result) {
           this.emitRunFinished({
             scenarioRunId,
@@ -551,27 +653,58 @@ var ScenarioExecution = class {
         ].join("\n")
       );
     } catch (error) {
+      const errorInfo = extractErrorInfo(error);
       const errorResult = {
         success: false,
         messages: this.state.messages,
-        reasoning: `Scenario failed with error: ${error instanceof Error ? error.message : String(error)}`,
+        reasoning: `Scenario failed with error: ${errorInfo.message}`,
         metCriteria: [],
         unmetCriteria: [],
-        error: error instanceof Error ? error.message : String(error)
+        error: JSON.stringify(errorInfo)
       };
       this.emitRunFinished({
         scenarioRunId,
         status: "ERROR" /* ERROR */,
         result: errorResult
       });
-      return errorResult;
+      throw error;
+    } finally {
+      subscription.unsubscribe();
     }
   }
   /**
-   * Executes a single step in the scenario.
-   * A step usually corresponds to a single agent's turn. This method is useful
-   * for manually controlling the scenario's progress.
-   * @returns A promise that resolves with the new messages added during the step, or a final scenario result if the step concludes the scenario.
+   * Executes a single agent interaction in the scenario.
+   *
+   * This method is for manual step-by-step execution of the scenario, where each call
+   * represents one agent taking their turn. This is different from script steps (like
+   * `user()`, `agent()`, `proceed()`, etc.) which are functions in the scenario script.
+   *
+   * Each call to this method will:
+   * - Progress to the next turn if needed
+   * - Find the next agent that should act
+   * - Execute that agent's response
+   * - Return either new messages or a final scenario result
+   *
+   * Note: This method is primarily for debugging or custom execution flows. Most users
+   * will use `execute()` to run the entire scenario automatically.
+   *
+   * @returns A promise that resolves with either:
+   *   - Array of new messages added during the agent interaction, or
+   *   - A final ScenarioResult if the interaction concludes the scenario
+   * @throws Error if no result is returned from the step
+   *
+   * @example
+   * ```typescript
+   * const execution = new ScenarioExecution(config, script);
+   *
+   * // Execute one agent interaction at a time
+   * const messages = await execution.step();
+   * if (Array.isArray(messages)) {
+   *   console.log('New messages:', messages);
+   * } else {
+   *   console.log('Scenario finished:', messages.success);
+   * }
+   * ```
    */
   async step() {
     const result = await this._step();
@@ -595,6 +728,34 @@ var ScenarioExecution = class {
     this.removePendingAgent(nextAgent);
     return await this.callAgent(idx, currentRole);
   }
+  /**
+   * Calls a specific agent to generate a response or make a decision.
+   *
+   * This method is the core of agent interaction. It prepares the agent's input
+   * by combining the conversation history with any pending messages that have been
+   * broadcast to this agent, then calls the agent and processes its response.
+   *
+   * The agent input includes:
+   * - Full conversation history (this.state.messages)
+   * - New messages that have been broadcast to this agent (this.pendingMessages.get(idx))
+   * - The role the agent is being asked to play
+   * - Whether this is a judgment request (for judge agents)
+   * - Current scenario state and configuration
+   *
+   * After the agent responds:
+   * - Performance timing is recorded
+   * - Pending messages for this agent are cleared (they've been processed)
+   * - If the agent returns a ScenarioResult, it's returned immediately
+   * - Otherwise, the agent's messages are added to the conversation and broadcast
+   *
+   * @param idx - The index of the agent in the agents array
+   * @param role - The role the agent is being asked to play (USER, AGENT, or JUDGE)
+   * @param judgmentRequest - Whether this is a judgment request (for judge agents)
+   * @returns A promise that resolves with either:
+   *   - Array of messages if the agent generated a response, or
+   *   - ScenarioResult if the agent made a final decision
+   * @throws Error if the agent call fails
+   */
   async callAgent(idx, role, judgmentRequest = false) {
     const agent2 = this.agents[idx];
     const startTime = Date.now();
@@ -607,29 +768,55 @@ var ScenarioExecution = class {
       scenarioState: this.state,
       scenarioConfig: this.config
     };
-    const agentResponse = await agent2.call(agentInput);
-    const endTime = Date.now();
-    this.addAgentTime(idx, endTime - startTime);
-    this.pendingMessages.delete(idx);
-    if (agentResponse && typeof agentResponse === "object" && "success" in agentResponse) {
-      return agentResponse;
-    }
-    const currentAgentTime = this.agentTimes.get(idx) ?? 0;
-    this.agentTimes.set(idx, currentAgentTime + (Date.now() - startTime));
-    const messages = convertAgentReturnTypesToMessages(
-      agentResponse,
-      role === "User" /* USER */ ? "user" : "assistant"
-    );
-    for (const message2 of messages) {
-      this.state.addMessage(message2);
-      this.broadcastMessage(message2, idx);
+    try {
+      const agentResponse = await agent2.call(agentInput);
+      const endTime = Date.now();
+      this.addAgentTime(idx, endTime - startTime);
+      this.pendingMessages.delete(idx);
+      if (agentResponse && typeof agentResponse === "object" && "success" in agentResponse) {
+        return agentResponse;
+      }
+      const currentAgentTime = this.agentTimes.get(idx) ?? 0;
+      this.agentTimes.set(idx, currentAgentTime + (Date.now() - startTime));
+      const messages = convertAgentReturnTypesToMessages(
+        agentResponse,
+        role === "User" /* USER */ ? "user" : "assistant"
+      );
+      for (const message2 of messages) {
+        this.state.addMessage(message2);
+        this.broadcastMessage(message2, idx);
+      }
+      return messages;
+    } catch (error) {
+      this.logger.error(
+        `[${this.config.id}] Error calling agent ${agent2.constructor.name}`,
+        {
+          error: error instanceof Error ? error.message : String(error),
+          agent: agent2.constructor.name,
+          agentInput
+        }
+      );
+      throw error;
     }
-    return messages;
   }
   /**
    * Adds a message to the conversation history.
-   * This is part of the `ScenarioExecutionLike` interface used by script steps.
-   * @param message The message to add.
+   *
+   * This method is part of the ScenarioExecutionLike interface used by script steps.
+   * It automatically routes the message to the appropriate agent based on the message role:
+   * - "user" messages are routed to USER role agents
+   * - "assistant" messages are routed to AGENT role agents
+   * - Other message types are added directly to the conversation
+   *
+   * @param message - The CoreMessage to add to the conversation
+   *
+   * @example
+   * ```typescript
+   * await execution.message({
+   *   role: "user",
+   *   content: "Hello, how are you?"
+   * });
+   * ```
    */
   async message(message2) {
     if (message2.role === "user") {
@@ -642,42 +829,134 @@ var ScenarioExecution = class {
     }
   }
   /**
-   * Executes a user turn.
-   * If content is provided, it's used as the user's message.
-   * If not, the user simulator agent is called to generate a message.
-   * This is part of the `ScenarioExecutionLike` interface used by script steps.
-   * @param content The optional content of the user's message.
+   * Executes a user turn in the conversation.
+   *
+   * If content is provided, it's used directly as the user's message. If not provided,
+   * the user simulator agent is called to generate an appropriate response based on
+   * the current conversation context.
+   *
+   * This method is part of the ScenarioExecutionLike interface used by script steps.
+   *
+   * @param content - Optional content for the user's message. Can be a string or CoreMessage.
+   *                 If not provided, the user simulator agent will generate the content.
+   *
+   * @example
+   * ```typescript
+   * // Use provided content
+   * await execution.user("What's the weather like?");
+   *
+   * // Let user simulator generate content
+   * await execution.user();
+   *
+   * // Use a CoreMessage object
+   * await execution.user({
+   *   role: "user",
+   *   content: "Tell me a joke"
+   * });
+   * ```
    */
   async user(content) {
     await this.scriptCallAgent("User" /* USER */, content);
   }
   /**
-   * Executes an agent turn.
-   * If content is provided, it's used as the agent's message.
-   * If not, the agent under test is called to generate a response.
-   * This is part of the `ScenarioExecutionLike` interface used by script steps.
-   * @param content The optional content of the agent's message.
+   * Executes an agent turn in the conversation.
+   *
+   * If content is provided, it's used directly as the agent's response. If not provided,
+   * the agent under test is called to generate a response based on the current conversation
+   * context and any pending messages.
+   *
+   * This method is part of the ScenarioExecutionLike interface used by script steps.
+   *
+   * @param content - Optional content for the agent's response. Can be a string or CoreMessage.
+   *                 If not provided, the agent under test will generate the response.
+   *
+   * @example
+   * ```typescript
+   * // Let agent generate response
+   * await execution.agent();
+   *
+   * // Use provided content
+   * await execution.agent("The weather is sunny today!");
+   *
+   * // Use a CoreMessage object
+   * await execution.agent({
+   *   role: "assistant",
+   *   content: "I'm here to help you with weather information."
+   * });
+   * ```
    */
   async agent(content) {
     await this.scriptCallAgent("Agent" /* AGENT */, content);
   }
   /**
    * Invokes the judge agent to evaluate the current state of the conversation.
-   * This is part of the `ScenarioExecutionLike` interface used by script steps.
-   * @param content Optional message to pass to the judge.
-   * @returns A promise that resolves with the scenario result if the judge makes a final decision, otherwise null.
+   *
+   * The judge agent analyzes the conversation history and determines whether the
+   * scenario criteria have been met. This can result in either:
+   * - A final scenario result (success/failure) if the judge makes a decision
+   * - Null if the judge needs more information or conversation to continue
+   *
+   * This method is part of the ScenarioExecutionLike interface used by script steps.
+   *
+   * @param content - Optional message to pass to the judge agent for additional context
+   * @returns A promise that resolves with:
+   *   - ScenarioResult if the judge makes a final decision, or
+   *   - Null if the conversation should continue
+   *
+   * @example
+   * ```typescript
+   * // Let judge evaluate current state
+   * const result = await execution.judge();
+   * if (result) {
+   *   console.log(`Judge decided: ${result.success ? 'pass' : 'fail'}`);
+   * }
+   *
+   * // Provide additional context to judge
+   * const result = await execution.judge("Please consider the user's satisfaction level");
+   * ```
    */
   async judge(content) {
     return await this.scriptCallAgent("Judge" /* JUDGE */, content, true);
   }
   /**
    * Lets the scenario proceed automatically for a specified number of turns.
-   * This simulates the natural flow of conversation between agents.
-   * This is part of the `ScenarioExecutionLike` interface used by script steps.
-   * @param turns The number of turns to proceed. If undefined, runs until a conclusion or max turns is reached.
-   * @param onTurn A callback executed at the end of each turn.
-   * @param onStep A callback executed after each agent interaction.
-   * @returns A promise that resolves with the scenario result if a conclusion is reached.
+   *
+   * This method is a script step that simulates natural conversation flow by allowing
+   * agents to interact automatically without explicit script steps. It can trigger
+   * multiple agent interactions across multiple turns, making it useful for testing
+   * scenarios where you want to see how agents behave in extended conversations.
+   *
+   * Unlike other script steps that typically trigger one agent interaction each,
+   * this step can trigger many agent interactions depending on the number of turns
+   * and the agents' behavior.
+   *
+   * The method will continue until:
+   * - The specified number of turns is reached
+   * - A final scenario result is determined
+   * - The maximum turns limit is reached
+   *
+   * @param turns - The number of turns to proceed. If undefined, runs until a conclusion
+   *               or max turns is reached
+   * @param onTurn - Optional callback executed at the end of each turn. Receives the
+   *                current execution state
+   * @param onStep - Optional callback executed after each agent interaction. Receives
+   *                the current execution state
+   * @returns A promise that resolves with:
+   *   - ScenarioResult if a conclusion is reached during the proceeding, or
+   *   - Null if the specified turns complete without conclusion
+   *
+   * @example
+   * ```typescript
+   * // Proceed for 5 turns
+   * const result = await execution.proceed(5);
+   *
+   * // Proceed until conclusion with callbacks
+   * const result = await execution.proceed(
+   *   undefined,
+   *   (state) => console.log(`Turn ${state.currentTurn} completed`),
+   *   (state) => console.log(`Agent interaction completed, ${state.messages.length} messages`)
+   * );
+   * ```
    */
   async proceed(turns, onTurn, onStep) {
     let initialTurn = this.state.currentTurn;
@@ -695,9 +974,26 @@ var ScenarioExecution = class {
   }
   /**
    * Immediately ends the scenario with a success verdict.
-   * This is part of the `ScenarioExecutionLike` interface used by script steps.
-   * @param reasoning An optional explanation for the success.
-   * @returns A promise that resolves with the final successful scenario result.
+   *
+   * This method forces the scenario to end successfully, regardless of the current
+   * conversation state. It's useful for scenarios where you want to explicitly
+   * mark success based on specific conditions or external factors.
+   *
+   * This method is part of the ScenarioExecutionLike interface used by script steps.
+   *
+   * @param reasoning - Optional explanation for why the scenario is being marked as successful
+   * @returns A promise that resolves with the final successful scenario result
+   *
+   * @example
+   * ```typescript
+   * // Mark success with default reasoning
+   * const result = await execution.succeed();
+   *
+   * // Mark success with custom reasoning
+   * const result = await execution.succeed(
+   *   "User successfully completed the onboarding flow"
+   * );
+   * ```
    */
   async succeed(reasoning) {
     return {
@@ -710,9 +1006,26 @@ var ScenarioExecution = class {
   }
   /**
    * Immediately ends the scenario with a failure verdict.
-   * This is part of the `ScenarioExecutionLike` interface used by script steps.
-   * @param reasoning An optional explanation for the failure.
-   * @returns A promise that resolves with the final failed scenario result.
+   *
+   * This method forces the scenario to end with failure, regardless of the current
+   * conversation state. It's useful for scenarios where you want to explicitly
+   * mark failure based on specific conditions or external factors.
+   *
+   * This method is part of the ScenarioExecutionLike interface used by script steps.
+   *
+   * @param reasoning - Optional explanation for why the scenario is being marked as failed
+   * @returns A promise that resolves with the final failed scenario result
+   *
+   * @example
+   * ```typescript
+   * // Mark failure with default reasoning
+   * const result = await execution.fail();
+   *
+   * // Mark failure with custom reasoning
+   * const result = await execution.fail(
+   *   "Agent failed to provide accurate weather information"
+   * );
+   * ```
    */
   async fail(reasoning) {
     return {
@@ -723,16 +1036,95 @@ var ScenarioExecution = class {
       unmetCriteria: []
     };
   }
+  /**
+   * Adds execution time for a specific agent to the performance tracking.
+   *
+   * This method is used internally to track how long each agent takes to respond,
+   * which is included in the final scenario result for performance analysis.
+   * The accumulated time for each agent is used to calculate total agent response
+   * times in the scenario result.
+   *
+   * @param agentIdx - The index of the agent in the agents array
+   * @param time - The execution time in milliseconds to add to the agent's total
+   *
+   * @example
+   * ```typescript
+   * // This is typically called internally by the execution engine
+   * execution.addAgentTime(0, 1500); // Agent at index 0 took 1.5 seconds
+   * ```
+   */
   addAgentTime(agentIdx, time) {
     const currentTime = this.agentTimes.get(agentIdx) || 0;
     this.agentTimes.set(agentIdx, currentTime + time);
   }
+  /**
+   * Checks if a partial result has been set for the scenario.
+   *
+   * This method is used internally to determine if a scenario has already reached
+   * a conclusion (success or failure) but hasn't been finalized yet. Partial results
+   * are typically set by agents that make final decisions (like judge agents) and
+   * are later finalized with the complete message history.
+   *
+   * @returns True if a partial result exists, false otherwise
+   *
+   * @example
+   * ```typescript
+   * // This is typically used internally by the execution engine
+   * if (execution.hasResult()) {
+   *   console.log('Scenario has reached a conclusion');
+   * }
+   * ```
+   */
   hasResult() {
     return this.partialResult !== null;
   }
+  /**
+   * Sets a partial result for the scenario.
+   *
+   * This method is used internally to store intermediate results that may be
+   * finalized later with the complete message history. Partial results are typically
+   * created by agents that make final decisions (like judge agents) and contain
+   * the success/failure status, reasoning, and criteria evaluation, but not the
+   * complete message history.
+   *
+   * @param result - The partial result without the messages field. Should include
+   *                success status, reasoning, and criteria evaluation.
+   *
+   * @example
+   * ```typescript
+   * // This is typically called internally by agents that make final decisions
+   * execution.setResult({
+   *   success: true,
+   *   reasoning: "Agent provided accurate weather information",
+   *   metCriteria: ["Provides accurate weather data"],
+   *   unmetCriteria: []
+   * });
+   * ```
+   */
   setResult(result) {
     this.partialResult = result;
   }
+  /**
+   * Internal method to handle script step calls to agents.
+   *
+   * This method is the core logic for executing script steps that involve agent
+   * interactions. It handles finding the appropriate agent for the given role,
+   * managing turn progression, and executing the agent's response.
+   *
+   * The method will:
+   * - Find the next available agent for the specified role
+   * - Progress to a new turn if no agent is available
+   * - Execute the agent with the provided content or let it generate content
+   * - Handle judgment requests for judge agents
+   * - Return a final result if the agent makes a decision
+   *
+   * @param role - The role of the agent to call (USER, AGENT, or JUDGE)
+   * @param content - Optional content to use instead of letting the agent generate it
+   * @param judgmentRequest - Whether this is a judgment request (for judge agents)
+   * @returns A promise that resolves with a ScenarioResult if the agent makes a final
+   *          decision, or null if the conversation should continue
+   * @throws Error if no agent is found for the specified role
+   */
   async scriptCallAgent(role, content, judgmentRequest = false) {
     this.consumeUntilRole(role);
     let index = -1;
@@ -784,6 +1176,21 @@ var ScenarioExecution = class {
     }
     return null;
   }
+  /**
+   * Resets the scenario execution to its initial state.
+   *
+   * This method is called at the beginning of each execution to ensure a clean
+   * state. It creates a new execution state, initializes agents, sets up the
+   * first turn, and clears any pending messages or partial results.
+   *
+   * The reset process:
+   * - Creates a new ScenarioExecutionState with the current config
+   * - Sets up the thread ID (generates new one if not provided)
+   * - Initializes all agents
+   * - Starts the first turn
+   * - Records the start time for performance tracking
+   * - Clears any pending messages
+   */
   reset() {
     this.state = new ScenarioExecutionState(this.config);
     this.state.threadId = this.config.threadId || generateThreadId();
@@ -801,6 +1208,16 @@ var ScenarioExecution = class {
     }
     return { idx: -1, agent: null };
   }
+  /**
+   * Starts a new turn in the scenario execution.
+   *
+   * This method is called when transitioning to a new turn. It resets the pending
+   * agents and roles for the turn, allowing all agents to participate again in
+   * the new turn. The turn counter is incremented to track the current turn number.
+   *
+   * A turn represents a cycle where agents can take actions. Each turn can involve
+   * multiple agent interactions as agents respond to each other's messages.
+   */
   newTurn() {
     this.pendingAgentsOnTurn = new Set(this.agents);
     this.pendingRolesOnTurn = [
@@ -843,6 +1260,23 @@ var ScenarioExecution = class {
       this.pendingRolesOnTurn.pop();
     }
   }
+  /**
+   * Creates a failure result when the maximum number of turns is reached.
+   *
+   * This method is called when the scenario execution reaches the maximum number
+   * of turns without reaching a conclusion. It creates a failure result with
+   * appropriate reasoning and includes performance metrics.
+   *
+   * The result includes:
+   * - All messages from the conversation
+   * - Failure reasoning explaining the turn limit was reached
+   * - Empty met criteria (since no conclusion was reached)
+   * - All judge criteria as unmet (since no evaluation was completed)
+   * - Total execution time and agent response times
+   *
+   * @param errorMessage - Optional custom error message to use instead of the default
+   * @returns A ScenarioResult indicating failure due to reaching max turns
+   */
   reachedMaxTurns(errorMessage) {
     var _a;
     const agentRoleAgentsIdx = this.agents.map((agent2, i) => ({ agent: agent2, idx: i })).filter(({ agent: agent2 }) => agent2.role === "Agent" /* AGENT */).map(({ idx }) => idx);
@@ -903,7 +1337,7 @@ var ScenarioExecution = class {
     this.emitEvent({
       ...this.makeBaseEvent({ scenarioRunId }),
       type: "SCENARIO_MESSAGE_SNAPSHOT" /* MESSAGE_SNAPSHOT */,
-      messages: message_conversion_default(this.state.messages)
+      messages: convert_core_messages_to_agui_messages_default(this.state.messages)
       // Add any other required fields from MessagesSnapshotEventSchema
     });
   }
@@ -934,8 +1368,31 @@ var ScenarioExecution = class {
   /**
    * Distributes a message to all other agents in the scenario.
    *
-   * @param message - The message to broadcast.
-   * @param fromAgentIdx - The index of the agent that sent the message, to avoid echoing.
+   * This method implements the message broadcasting system that allows agents to
+   * "hear" messages from other agents. When an agent sends a message, it needs to
+   * be distributed to all other agents so they can respond appropriately.
+   *
+   * The broadcasting process:
+   * 1. Iterates through all agents in the scenario
+   * 2. Skips the agent that sent the message (to avoid echo)
+   * 3. Adds the message to each agent's pending message queue
+   * 4. Agents will receive these messages when they're called next
+   *
+   * This creates a realistic conversation environment where agents can see
+   * the full conversation history and respond contextually.
+   *
+   * @param message - The message to broadcast to all other agents
+   * @param fromAgentIdx - The index of the agent that sent the message (to avoid echoing back to sender)
+   *
+   * @example
+   * ```typescript
+   * // When agent 0 sends a message, it gets broadcast to agents 1 and 2
+   * execution.broadcastMessage(
+   *   { role: "user", content: "Hello" },
+   *   0 // fromAgentIdx
+   * );
+   * // Now agents 1 and 2 have this message in their pendingMessages queue
+   * ```
    */
   broadcastMessage(message2, fromAgentIdx) {
     for (let idx = 0; idx < this.agents.length; idx++) {
@@ -946,6 +1403,58 @@ var ScenarioExecution = class {
       this.pendingMessages.get(idx).push(message2);
     }
   }
+  /**
+   * Executes a single script step with proper error handling and logging.
+   *
+   * This method is responsible for executing each script step function with
+   * comprehensive error handling and logging. It provides the execution context
+   * to the script step and handles any errors that occur during execution.
+   *
+   * The method:
+   * - Logs the start of script step execution
+   * - Calls the script step function with the current state and execution context
+   * - Logs the completion of the script step
+   * - Handles and logs any errors that occur
+   * - Re-throws errors to maintain the original error context
+   *
+   * @param scriptStep - The script step function to execute (user, agent, judge, etc.)
+   * @param stepIndex - The index of the script step for logging and debugging context
+   * @returns The result of the script step execution (void, ScenarioResult, or null)
+   * @throws Error if the script step throws an error (preserves original error)
+   */
+  async executeScriptStep(scriptStep, stepIndex) {
+    const functionString = scriptStep.toString();
+    try {
+      this.logger.debug(
+        `[${this.config.id}] Executing script step ${stepIndex + 1}`,
+        {
+          stepIndex,
+          function: functionString
+        }
+      );
+      const result = await scriptStep(this.state, this);
+      this.logger.debug(
+        `[${this.config.id}] Script step ${stepIndex + 1} completed`,
+        {
+          stepIndex,
+          hasResult: result !== null && result !== void 0,
+          resultType: typeof result
+        }
+      );
+      return result;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error(
+        `[${this.config.id}] Script step ${stepIndex + 1} failed`,
+        {
+          stepIndex,
+          error: errorMessage,
+          function: functionString
+        }
+      );
+      throw error;
+    }
+  }
 };
 function convertAgentReturnTypesToMessages(response, role) {
   if (typeof response === "string")
@@ -954,6 +1463,19 @@ function convertAgentReturnTypesToMessages(response, role) {
   if (typeof response === "object" && "role" in response) return [response];
   return [];
 }
+function extractErrorInfo(error) {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      stack: error.stack
+    };
+  }
+  return {
+    name: typeof error,
+    message: String(error)
+  };
+}
 
 // src/runner/index.ts
 var runner_exports = {};
@@ -1024,9 +1546,10 @@ async function run(cfg) {
   let eventBus = null;
   let subscription = null;
   try {
+    const envConfig = getEnv();
     eventBus = new EventBus({
-      endpoint: env.LANGWATCH_ENDPOINT,
-      apiKey: env.LANGWATCH_API_KEY
+      endpoint: envConfig.LANGWATCH_ENDPOINT,
+      apiKey: envConfig.LANGWATCH_API_KEY
     });
     eventBus.listen();
     subscription = eventBus.subscribeTo(execution.events$);
@@ -1107,6 +1630,7 @@ export {
   JudgeAgentAdapter,
   ScenarioExecution,
   ScenarioExecutionState,
+  StateChangeEventType,
   UserSimulatorAgentAdapter,
   agent,
   allAgentRoles,