@iqai/adk 0.2.5 → 0.3.0

package/dist/index.js

@@ -30,98 +30,269 @@ var _chalk = require('chalk'); var _chalk2 = _interopRequireDefault(_chalk);
 function isDebugEnabled() {
   return process.env.NODE_ENV === "development" || process.env.ADK_DEBUG === "true";
 }
-var Logger;
+var LOG_LEVELS, Logger;
 var init_logger = __esm({
   "src/logger/index.ts"() {
+    LOG_LEVELS = {
+      debug: { icon: "\u{1F41B}", color: _chalk2.default.blue, method: console.log },
+      info: { icon: "\u2139\uFE0F", color: _chalk2.default.cyan, method: console.debug },
+      warn: { icon: "\u{1F6A7}", color: _chalk2.default.yellow, method: console.warn },
+      error: { icon: "\u274C", color: _chalk2.default.red, method: console.error }
+    };
     Logger = (_class = class {
       
       __init2() {this.isDebugEnabled = isDebugEnabled()}
       constructor({ name }) {;_class.prototype.__init2.call(this);
         this.name = name;
       }
-      colorize(message) {
-        return _chalk2.default.blue(message);
-      }
       debug(message, ...args) {
         if (this.isDebugEnabled) {
-          const time = (/* @__PURE__ */ new Date()).toLocaleTimeString();
-          console.log(
-            this.colorize(`[${time}] \u{1F41B} [${this.name}] ${message}`),
-            ...args
-          );
+          this.log("debug", message, ...args);
         }
       }
       info(message, ...args) {
-        const time = (/* @__PURE__ */ new Date()).toLocaleTimeString();
-        console.debug(
-          this.colorize(`[${time}] \u2139\uFE0F [${this.name}] ${message}`),
-          ...args
-        );
+        this.log("info", message, ...args);
       }
       warn(message, ...args) {
-        const time = (/* @__PURE__ */ new Date()).toLocaleTimeString();
-        console.warn(
-          this.colorize(`[${time}] \u{1F6A7} [${this.name}] ${message}`),
-          ...args
-        );
+        this.log("warn", message, ...args);
       }
       error(message, ...args) {
+        this.log("error", message, ...args);
+      }
+      log(level, message, ...args) {
+        const { icon, color, method } = LOG_LEVELS[level];
         const time = (/* @__PURE__ */ new Date()).toLocaleTimeString();
-        console.error(
-          this.colorize(`[${time}] \u274C [${this.name}] ${message}`),
-          ...args
+        const isProd = process.env.NODE_ENV === "production";
+        const forceBoxes = process.env.ADK_FORCE_BOXES === "true";
+        const { meta, otherArgs } = this.extractMeta(args);
+        const lines = this.formatArgs(otherArgs, level === "error");
+        if (meta.suggestion) lines.unshift(`\u2022 Suggestion: ${meta.suggestion}`);
+        if (meta.context && Object.keys(meta.context).length) {
+          const contextStr = Object.entries(meta.context).map(([k, v]) => `${k}=${this.stringify(v)}`).join("  ");
+          lines.unshift(`\u2022 Context: ${contextStr}`);
+        }
+        if (isProd && !forceBoxes) {
+          const header = `[${time}] ${icon} [${this.name}] ${message}`;
+          const output = lines.length ? [header, ...lines].join("\n") : header;
+          method(color(output));
+          return;
+        }
+        if (level === "warn" || level === "error") {
+          const box = this.formatBox({
+            title: `${icon} ${this.capitalize(level)} @ ${time} (${this.name})`,
+            description: message,
+            lines,
+            color
+          });
+          method(box);
+        } else {
+          const header = `[${time}] ${icon} [${this.name}] ${message}`;
+          const output = lines.length ? [header, ...lines].join("\n") : header;
+          method(color(output));
+        }
+      }
+      extractMeta(args) {
+        const meta = {};
+        const otherArgs = [];
+        let metaFound = false;
+        for (const arg of args) {
+          if (!arg) continue;
+          if (!metaFound && typeof arg === "object" && !(arg instanceof Error) && ("suggestion" in arg || "context" in arg)) {
+            meta.suggestion = arg.suggestion;
+            meta.context = arg.context;
+            metaFound = true;
+          } else {
+            otherArgs.push(arg);
+          }
+        }
+        return { meta, otherArgs };
+      }
+      formatArgs(args, includeStack = false) {
+        const lines = [];
+        const maxFrames = Number(process.env.ADK_ERROR_STACK_FRAMES || 8);
+        for (const arg of args) {
+          if (!arg) continue;
+          if (arg instanceof Error) {
+            lines.push(`\u2022 ${arg.name}: ${arg.message}`);
+            if (includeStack && arg.stack) {
+              const frames = this.parseStackFrames(arg.stack, maxFrames);
+              if (frames.length) {
+                lines.push("\u2022 Stack:", ...frames);
+              }
+            }
+          } else {
+            lines.push(`\u2022 ${this.stringify(arg)}`);
+          }
+        }
+        return lines;
+      }
+      parseStackFrames(stack, maxFrames) {
+        const frames = stack.split(/\n/).slice(1).map((f) => f.trim()).filter(Boolean).slice(0, maxFrames);
+        const result = frames.map((frame) => {
+          const cleaned = frame.replace(/^at\s+/, "").replace(process.cwd(), ".");
+          return `  \u21B3 ${cleaned}`;
+        });
+        const totalFrames = stack.split(/\n/).length - 1;
+        if (totalFrames > maxFrames) {
+          result.push(`  \u21B3 \u2026 ${totalFrames - maxFrames} more frames`);
+        }
+        return result;
+      }
+      stringify(value) {
+        if (typeof value === "string") return value;
+        if (typeof value === "number" || typeof value === "boolean")
+          return String(value);
+        if (value === null || value === void 0) return String(value);
+        try {
+          return JSON.stringify(value);
+        } catch (e2) {
+          return String(value);
+        }
+      }
+      capitalize(str) {
+        return str.charAt(0).toUpperCase() + str.slice(1);
+      }
+      formatBox(params) {
+        const {
+          title,
+          description,
+          lines = [],
+          width = 60,
+          maxWidthPct = 0.9,
+          color = _chalk2.default.yellow,
+          pad = 1,
+          borderChar = "\u2500"
+        } = params;
+        const isProd = process.env.NODE_ENV === "production";
+        const forceBoxes = process.env.ADK_FORCE_BOXES === "true";
+        if (isProd && !forceBoxes) {
+          return [`${title}: ${description}`, ...lines].join("\n");
+        }
+        const termWidth = process.stdout.columns || 80;
+        const maxWidth = Math.floor(termWidth * maxWidthPct);
+        const contentWidth = Math.max(
+          width,
+          title.length + 2,
+          description.length,
+          ...lines.map((l) => l.length)
         );
+        const innerWidth = Math.min(contentWidth + pad * 2, maxWidth - 2);
+        const horizontal = borderChar.repeat(innerWidth + 2);
+        const top = `\u250C${horizontal}\u2510`;
+        const separator = `\u251C${horizontal}\u2524`;
+        const bottom = `\u2514${horizontal}\u2518`;
+        const padLine = (text) => {
+          const maxContent = innerWidth - pad * 2;
+          const truncated = text.length > maxContent ? `${text.slice(0, maxContent - 1)}\u2026` : text;
+          const padded = " ".repeat(pad) + truncated;
+          return padded + " ".repeat(innerWidth - padded.length);
+        };
+        const content = [
+          top,
+          `\u2502 ${padLine(title)} \u2502`,
+          separator,
+          `\u2502 ${padLine(description)} \u2502`,
+          ...lines.map((line) => `\u2502 ${padLine(line)} \u2502`),
+          bottom
+        ];
+        return `
+${content.map((line) => color(line)).join("\n")}`;
       }
       /**
-       * Logs structured data in a visually appealing table format.
-       * Uses vertical layout for better readability and respects debug settings.
+       * Structured warning with code, suggestion, context.
        */
+      warnStructured(warning, opts = {}) {
+        const format = opts.format || process.env.ADK_WARN_FORMAT || "pretty";
+        const verbose = opts.verbose || process.env.ADK_AGENT_BUILDER_WARN === "verbose";
+        const timestamp = warning.timestamp || (/* @__PURE__ */ new Date()).toISOString();
+        const severity = warning.severity || "warn";
+        if (format === "json") {
+          this.warn(
+            JSON.stringify({
+              level: severity,
+              source: this.name,
+              timestamp,
+              ...warning
+            })
+          );
+          return;
+        }
+        const { icon } = LOG_LEVELS[severity] || LOG_LEVELS.warn;
+        const base = `${icon} ${warning.code} ${warning.message}`;
+        const parts = [base];
+        if (warning.suggestion) {
+          parts.push(`   \u2022 Suggestion: ${warning.suggestion}`);
+        }
+        if (verbose && warning.context && Object.keys(warning.context).length) {
+          const contextStr = Object.entries(warning.context).map(([k, v]) => `${k}=${this.stringify(v)}`).join("  ");
+          parts.push(`   \u2022 Context: ${contextStr}`);
+        }
+        if (format === "pretty") {
+          this.warn(parts.join("\n"));
+        } else {
+          const textParts = [`[${warning.code}] ${warning.message}`];
+          if (warning.suggestion) textParts.push(`  -> ${warning.suggestion}`);
+          if (verbose && warning.context && Object.keys(warning.context).length) {
+            const contextStr = Object.entries(warning.context).map(([k, v]) => `${k}=${this.stringify(v)}`).join("  ");
+            textParts.push(`   \u2022 Context: ${contextStr}`);
+          }
+          this.warn(textParts.join("\n"));
+        }
+      }
       debugStructured(title, data) {
         if (!this.isDebugEnabled) return;
-        const terminalWidth = process.stdout.columns || 60;
-        const width = Math.min(terminalWidth, 100);
-        const contentWidth = width - 4;
-        const topBorder = `\u250C${"\u2500".repeat(width - 2)}\u2510`;
-        const bottomBorder = `\u2514${"\u2500".repeat(width - 2)}\u2518`;
-        const middleBorder = `\u251C${"\u2500".repeat(width - 2)}\u2524`;
-        console.log(this.colorize(topBorder));
-        console.log(this.colorize(`\u2502 ${title.padEnd(contentWidth)} \u2502`));
-        console.log(this.colorize(middleBorder));
-        Object.entries(data).forEach(([key, value]) => {
-          const formattedKey = key.padEnd(20);
-          const formattedValue = String(value);
-          const availableValueSpace = contentWidth - 20 - 2;
-          const truncatedValue = formattedValue.length > availableValueSpace ? `${formattedValue.substring(0, availableValueSpace - 3)}...` : formattedValue;
-          const content = `${formattedKey}: ${truncatedValue}`;
-          const paddedContent = content.padEnd(contentWidth);
-          console.log(this.colorize(`\u2502 ${paddedContent} \u2502`));
+        const time = (/* @__PURE__ */ new Date()).toLocaleTimeString();
+        const lines = this.objectToLines(data);
+        const box = this.formatBox({
+          title: `\u{1F41B} Debug @ ${time} (${this.name})`,
+          description: title,
+          lines,
+          color: _chalk2.default.blue
         });
-        console.log(this.colorize(bottomBorder));
+        console.log(box);
       }
-      /**
-       * Logs array data in a compact, readable format.
-       */
       debugArray(title, items) {
         if (!this.isDebugEnabled) return;
-        const terminalWidth = process.stdout.columns || 78;
-        const width = Math.min(terminalWidth, 120);
-        const contentWidth = width - 4;
-        const topBorder = `\u250C${"\u2500".repeat(width - 2)}\u2510`;
-        const bottomBorder = `\u2514${"\u2500".repeat(width - 2)}\u2518`;
-        const middleBorder = `\u251C${"\u2500".repeat(width - 2)}\u2524`;
-        console.log(this.colorize(topBorder));
-        console.log(this.colorize(`\u2502 ${title.padEnd(contentWidth)} \u2502`));
-        console.log(this.colorize(middleBorder));
-        items.forEach((item, index) => {
-          const itemStr = Object.entries(item).map(([k, v]) => `${k}: ${v}`).join(" \u2022 ");
-          const indexPart = `[${index + 1}] `;
-          const availableSpace = contentWidth - indexPart.length;
-          const truncatedItem = itemStr.length > availableSpace ? `${itemStr.substring(0, availableSpace - 3)}...` : itemStr;
-          const content = `${indexPart}${truncatedItem}`;
-          const paddedContent = content.padEnd(contentWidth);
-          console.log(this.colorize(`\u2502 ${paddedContent} \u2502`));
+        const time = (/* @__PURE__ */ new Date()).toLocaleTimeString();
+        const lines = this.arrayToLines(items);
+        const box = this.formatBox({
+          title: `\u{1F41B} Debug List @ ${time} (${this.name})`,
+          description: title,
+          lines,
+          color: _chalk2.default.blue,
+          width: 78,
+          maxWidthPct: 0.95
+        });
+        console.log(box);
+      }
+      objectToLines(obj) {
+        const entries = Object.entries(obj || {});
+        if (!entries.length) return ["(empty)"];
+        const keyWidth = Math.min(
+          30,
+          Math.max(6, ...entries.map(([k]) => k.length))
+        );
+        return entries.slice(0, 200).map(([k, v]) => {
+          const value = this.stringify(v);
+          const truncated = value.length > 140 ? `${value.slice(0, 139)}\u2026` : value;
+          return `${k.padEnd(keyWidth)}: ${truncated}`;
         });
-        console.log(this.colorize(bottomBorder));
+      }
+      arrayToLines(items) {
+        if (!items.length) return ["(empty list)"];
+        const maxItems = 50;
+        const lines = items.slice(0, maxItems).map((obj, i) => {
+          const props = Object.entries(obj).map(([k, v]) => {
+            const value = this.stringify(v);
+            const truncated = value.length > 160 ? `${value.slice(0, 159)}\u2026` : value;
+            return `${k}=${truncated}`;
+          }).join("  \u2022  ");
+          return `[${i + 1}] ${props}`;
+        });
+        if (items.length > maxItems) {
+          lines.push(`\u2026 ${items.length - maxItems} more items omitted`);
+        }
+        return lines;
       }
     }, _class);
   }
@@ -4237,7 +4408,7 @@ var AgentTool = (_class15 = class extends BaseTool {
       let toolResult;
       try {
         toolResult = JSON.parse(mergedText);
-      } catch (e2) {
+      } catch (e3) {
         toolResult = mergedText;
       }
       if (this.outputKey && _optionalChain([context4, 'optionalAccess', _145 => _145.state])) {
@@ -4688,7 +4859,7 @@ var FileOperationsTool = class extends BaseTool {
         success: true,
         data: true
       };
-    } catch (e3) {
+    } catch (e4) {
       return {
         success: true,
         data: false
@@ -7256,7 +7427,7 @@ var CodeExecutionUtils = class _CodeExecutionUtils {
   static isBase64Encoded(str) {
     try {
       return btoa(atob(str)) === str;
-    } catch (e4) {
+    } catch (e5) {
       return false;
     }
   }
@@ -8299,7 +8470,7 @@ var InstructionsLlmRequestProcessor = class extends BaseLlmRequestProcessor {
         llmRequest.appendInstructions([
           'IMPORTANT: After any tool calls, function calls, or agent transfers have completed, produce ONE final assistant message whose entire content is ONLY the JSON object that conforms to the schema provided above. Do NOT include any explanatory text, markdown, or additional messages. Do NOT wrap the JSON in code fences (for example, do NOT use ```json or ```). If you cannot produce valid JSON that matches the schema, return a JSON object with an "error" field describing the problem.'
         ]);
-      } catch (e5) {
+      } catch (e6) {
       }
     }
     for await (const _ of []) {
@@ -9291,37 +9462,29 @@ async function* mergeAgentRun(agentRuns) {
   if (agentRuns.length === 0) {
     return;
   }
-  const promises = agentRuns.map(async (generator, index) => {
-    try {
-      const result = await generator.next();
-      return { index, result };
-    } catch (error) {
-      return { index, result: { done: true, value: void 0 }, error };
+  const nextFor = (gen, index) => gen.next().then((result) => ({ index, result })).catch((error) => ({
+    index,
+    result: { done: true, value: void 0 },
+    error
+  }));
+  const entries = agentRuns.map((gen, i) => ({ index: i, promise: nextFor(gen, i) }));
+  const activePromises = () => entries.filter((e) => !!e).map((e) => e.promise);
+  while (true) {
+    const currentActivePromises = activePromises();
+    if (currentActivePromises.length === 0) {
+      break;
     }
-  });
-  let pendingPromises = [...promises];
-  while (pendingPromises.length > 0) {
-    const { index, result, error } = await Promise.race(pendingPromises);
-    pendingPromises = pendingPromises.filter((_, i) => i !== index);
+    const { index, result, error } = await Promise.race(currentActivePromises);
     if (error) {
       console.error(`Error in parallel agent ${index}:`, error);
+      entries[index] = void 0;
       continue;
     }
     if (!result.done) {
       yield result.value;
-      const nextPromise = (async () => {
-        try {
-          const nextResult = await agentRuns[index].next();
-          return { index, result: nextResult };
-        } catch (nextError) {
-          return {
-            index,
-            result: { done: true, value: void 0 },
-            error: nextError
-          };
-        }
-      })();
-      pendingPromises.push(nextPromise);
+      entries[index] = { index, promise: nextFor(agentRuns[index], index) };
+    } else {
+      entries[index] = void 0;
     }
   }
 }
@@ -10480,12 +10643,24 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
   // If provided, reuse directly
   __init57() {this.definitionLocked = false}
   // Lock further definition mutation after withAgent
-  __init58() {this.warnedMethods = /* @__PURE__ */ new Set()}
-  __init59() {this.logger = new Logger({ name: "AgentBuilder" })}
+  __init58() {this.logger = new Logger({ name: "AgentBuilder" })}
+  /**
+   * Warn (once per method) if the definition has been locked by withAgent().
+   */
+  warnIfLocked(method) {
+    if (!this.definitionLocked) return;
+    this.logger.warn(
+      `AgentBuilder: ${method}() ignored because builder is locked by withAgent()`,
+      {
+        suggestion: "Configure model/tools/etc. before calling withAgent(), or avoid withAgent() if you intend to mutate afterwards.",
+        context: { method, agentName: this.config.name }
+      }
+    );
+  }
   /**
    * Private constructor - use static create() method
    */
-  constructor(name) {;_class33.prototype.__init56.call(this);_class33.prototype.__init57.call(this);_class33.prototype.__init58.call(this);_class33.prototype.__init59.call(this);
+  constructor(name) {;_class33.prototype.__init56.call(this);_class33.prototype.__init57.call(this);_class33.prototype.__init58.call(this);
     this.config = { name };
   }
   /**
@@ -10541,6 +10716,16 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
   }
   withOutputSchema(schema) {
     this.warnIfLocked("withOutputSchema");
+    if (this.agentType === "sequential" || this.agentType === "parallel") {
+      const msg = "Output schemas cannot be applied to sequential or parallel agents. Define output schemas on each sub-agent instead.";
+      this.logger.error(msg, {
+        suggestion: "Apply outputSchema to each sub-agent individually.",
+        context: {
+          agentType: this.agentType
+        }
+      });
+      throw new Error(msg);
+    }
     this.config.outputSchema = schema;
     return this;
   }
@@ -10581,6 +10766,16 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
    */
   withOutputKey(outputKey) {
     this.warnIfLocked("withOutputKey");
+    if (this.agentType === "sequential" || this.agentType === "parallel") {
+      this.logger.warn(
+        "AgentBuilder: outputKey ignored for sequential/parallel aggregator",
+        {
+          suggestion: "Set outputKey on each sub-agent instead.",
+          context: { attemptedOutputKey: outputKey, agentType: this.agentType }
+        }
+      );
+      return this;
+    }
     this.config.outputKey = outputKey;
     return this;
   }
@@ -10632,9 +10827,37 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
    * @returns This builder instance for chaining
    */
   asSequential(subAgents) {
-    this.warnIfLocked("asSequential");
+    if (this.definitionLocked) {
+      this.logger.warn(
+        "AgentBuilder: asSequential() ignored; builder locked by withAgent()",
+        {
+          suggestion: "Call asSequential() before withAgent().",
+          context: { agentName: this.config.name }
+        }
+      );
+      return this;
+    }
     this.agentType = "sequential";
     this.config.subAgents = subAgents;
+    if (this.config.outputKey) {
+      this.logger.warn(
+        "AgentBuilder: outputKey ignored for sequential agent aggregator; removed",
+        {
+          suggestion: "Assign outputKey on individual sub-agents if needed.",
+          context: { previousValue: this.config.outputKey }
+        }
+      );
+      this.config.outputKey = void 0;
+    }
+    if (this.config.outputSchema) {
+      this.logger.warn(
+        "AgentBuilder: outputSchema cannot be applied to sequential aggregator; removed",
+        {
+          suggestion: "Apply schemas to sub-agents individually."
+        }
+      );
+      this.config.outputSchema = void 0;
+    }
     return this;
   }
   /**
@@ -10643,9 +10866,37 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
    * @returns This builder instance for chaining
    */
   asParallel(subAgents) {
-    this.warnIfLocked("asParallel");
+    if (this.definitionLocked) {
+      this.logger.warn(
+        "AgentBuilder: asParallel() ignored; builder locked by withAgent()",
+        {
+          suggestion: "Call asParallel() before withAgent().",
+          context: { agentName: this.config.name }
+        }
+      );
+      return this;
+    }
     this.agentType = "parallel";
     this.config.subAgents = subAgents;
+    if (this.config.outputKey) {
+      this.logger.warn(
+        "AgentBuilder: outputKey ignored for parallel agent aggregator; removed",
+        {
+          suggestion: "Assign outputKey on individual sub-agents if needed.",
+          context: { previousValue: this.config.outputKey }
+        }
+      );
+      this.config.outputKey = void 0;
+    }
+    if (this.config.outputSchema) {
+      this.logger.warn(
+        "AgentBuilder: outputSchema cannot be applied to parallel aggregator; removed",
+        {
+          suggestion: "Apply schemas to sub-agents individually."
+        }
+      );
+      this.config.outputSchema = void 0;
+    }
     return this;
   }
   /**
@@ -10698,9 +10949,11 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
    */
   withSession(session) {
     if (!this.sessionService) {
-      throw new Error(
-        "Session service must be configured before using withSession(). Call withSessionService() first, or use withQuickSession() for in-memory sessions."
-      );
+      const msg = "Session service must be configured before using withSession(). Call withSessionService() first, or use withQuickSession() for in-memory sessions.";
+      this.logger.error(msg, {
+        suggestion: "Invoke withSessionService() prior to withSession()."
+      });
+      throw new Error(msg);
     }
     this.sessionOptions = {
       ...this.sessionOptions,
@@ -10771,7 +11024,12 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
       const baseRunner = new Runner(runnerConfig);
       runner = this.createEnhancedRunner(baseRunner, session);
     }
-    return { agent, runner, session };
+    return {
+      agent,
+      runner,
+      session,
+      sessionService: this.sessionService
+    };
   }
   /**
    * Type-safe build method for agents with output schemas
@@ -10799,7 +11057,11 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
     switch (this.agentType) {
       case "llm": {
         if (!this.config.model) {
-          throw new Error("Model is required for LLM agent");
+          const msg = "Model is required for LLM agent";
+          this.logger.error(msg, {
+            suggestion: "Call withModel() before build()."
+          });
+          throw new Error(msg);
         }
         const model = this.config.model;
         return new LlmAgent({
@@ -10823,7 +11085,11 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
       }
       case "sequential":
         if (!this.config.subAgents || !Array.isArray(this.config.subAgents) || this.config.subAgents.length === 0) {
-          throw new Error("Sub-agents required for sequential agent");
+          const msg = "Sub-agents required for sequential agent";
+          this.logger.error(msg, {
+            suggestion: "Provide at least one sub-agent."
+          });
+          throw new Error(msg);
         }
         return new SequentialAgent({
           name: this.config.name,
@@ -10832,7 +11098,11 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
         });
       case "parallel":
         if (!this.config.subAgents || !Array.isArray(this.config.subAgents) || this.config.subAgents.length === 0) {
-          throw new Error("Sub-agents required for parallel agent");
+          const msg = "Sub-agents required for parallel agent";
+          this.logger.error(msg, {
+            suggestion: "Provide at least one sub-agent."
+          });
+          throw new Error(msg);
         }
         return new ParallelAgent({
           name: this.config.name,
@@ -10841,7 +11111,11 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
         });
       case "loop":
         if (!this.config.subAgents || !Array.isArray(this.config.subAgents) || this.config.subAgents.length === 0) {
-          throw new Error("Sub-agents required for loop agent");
+          const msg = "Sub-agents required for loop agent";
+          this.logger.error(msg, {
+            suggestion: "Provide at least one sub-agent."
+          });
+          throw new Error(msg);
         }
         return new LoopAgent({
           name: this.config.name,
@@ -10851,7 +11125,11 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
         });
       case "langgraph":
         if (!this.config.nodes || !Array.isArray(this.config.nodes) || this.config.nodes.length === 0 || !this.config.rootNode || typeof this.config.rootNode !== "string") {
-          throw new Error("Nodes and root node required for LangGraph agent");
+          const msg = "Nodes and root node required for LangGraph agent";
+          this.logger.error(msg, {
+            suggestion: "Provide nodes[] and a valid rootNode string."
+          });
+          throw new Error(msg);
         }
         return new LangGraphAgent({
           name: this.config.name,
@@ -10885,12 +11163,17 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
   createEnhancedRunner(baseRunner, session) {
     const sessionOptions = this.sessionOptions;
     const outputSchema = this.config.outputSchema;
+    const agentType = this.agentType;
+    const isMulti = agentType === "parallel" || agentType === "sequential";
+    const subAgentNames = _optionalChain([this, 'access', _287 => _287.config, 'access', _288 => _288.subAgents, 'optionalAccess', _289 => _289.map, 'call', _290 => _290((a) => a.name)]) || [];
     return {
       __outputSchema: outputSchema,
       async ask(message) {
         const newMessage = typeof message === "string" ? { parts: [{ text: message }] } : typeof message === "object" && "contents" in message ? { parts: message.contents[message.contents.length - 1].parts } : message;
-        let response = "";
-        if (!_optionalChain([sessionOptions, 'optionalAccess', _287 => _287.userId])) {
+        let combinedResponse = "";
+        const perAgentBuffers = {};
+        const authors = /* @__PURE__ */ new Set();
+        if (!_optionalChain([sessionOptions, 'optionalAccess', _291 => _291.userId])) {
           throw new Error("Session configuration is required");
         }
         for await (const event of baseRunner.runAsync({
@@ -10898,50 +11181,50 @@ var AgentBuilder = (_class33 = class _AgentBuilder {
           sessionId: session.id,
           newMessage
         })) {
-          if (_optionalChain([event, 'access', _288 => _288.content, 'optionalAccess', _289 => _289.parts]) && Array.isArray(event.content.parts)) {
+          if (_optionalChain([event, 'access', _292 => _292.content, 'optionalAccess', _293 => _293.parts]) && Array.isArray(event.content.parts)) {
             const content = event.content.parts.map(
               (part) => (part && typeof part === "object" && "text" in part ? part.text : "") || ""
             ).join("");
             if (content) {
-              response += content;
+              combinedResponse += content;
+              const author = event.author || "";
+              if (author && author !== "user") {
+                authors.add(author);
+                perAgentBuffers[author] = (perAgentBuffers[author] || "") + content;
+              }
             }
           }
         }
+        if (isMulti) {
+          return subAgentNames.map((name) => ({
+            agent: name,
+            response: (perAgentBuffers[name] || "").trim()
+          }));
+        }
         if (outputSchema) {
           try {
-            const parsed = JSON.parse(response);
+            const parsed = JSON.parse(combinedResponse);
             return outputSchema.parse(parsed);
           } catch (parseError) {
             try {
-              return outputSchema.parse(response);
+              return outputSchema.parse(combinedResponse);
             } catch (validationError) {
-              return response.trim();
+              throw new Error(
+                `Failed to parse and validate LLM output against the schema.
+							JSON parse error: ${parseError instanceof Error ? parseError.message : String(parseError)}
+							Zod validation error: ${validationError instanceof Error ? validationError.message : String(validationError)}
+							Raw output: "${combinedResponse}"`
+              );
             }
           }
         }
-        return response.trim();
+        return combinedResponse.trim();
       },
       runAsync(params) {
         return baseRunner.runAsync(params);
       }
     };
   }
-  /**
-   * Warn (once per method) if the definition has been locked by withAgent().
-   */
-  warnIfLocked(method) {
-    if (!this.definitionLocked) return;
-    if (this.warnedMethods.has(method)) return;
-    this.warnedMethods.add(method);
-    if (process.env.NODE_ENV !== "production") {
-      const msg = `AgentBuilder: attempted to call ${method} after withAgent(); ignoring. (Wrap the agent first OR configure before withAgent).`;
-      if (this.logger && typeof this.logger.warn === "function") {
-        this.logger.warn(msg);
-      } else {
-        console.warn(msg);
-      }
-    }
-  }
 }, _class33);
 
 // src/memory/index.ts
@@ -11006,7 +11289,7 @@ var VertexAiSessionService = class extends BaseSessionService {
         path: `operations/${operationId}`,
         request_dict: {}
       });
-      if (_optionalChain([lroResponse, 'optionalAccess', _290 => _290.done])) {
+      if (_optionalChain([lroResponse, 'optionalAccess', _294 => _294.done])) {
         break;
       }
       await new Promise((resolve) => setTimeout(resolve, 1e3));
@@ -11278,9 +11561,9 @@ var VertexAiSessionService = class extends BaseSessionService {
 var _kysely = require('kysely');
 var DatabaseSessionService = (_class34 = class extends BaseSessionService {
   
-  __init60() {this.initialized = false}
+  __init59() {this.initialized = false}
   constructor(config) {
-    super();_class34.prototype.__init60.call(this);;
+    super();_class34.prototype.__init59.call(this);;
     this.db = config.db;
     if (!config.skipTableCreation) {
       this.initializeDatabase().catch((error) => {
@@ -11355,7 +11638,7 @@ var DatabaseSessionService = (_class34 = class extends BaseSessionService {
     if (!jsonString) return defaultValue;
     try {
       return JSON.parse(jsonString);
-    } catch (e6) {
+    } catch (e7) {
       return defaultValue;
     }
   }
@@ -11377,12 +11660,12 @@ var DatabaseSessionService = (_class34 = class extends BaseSessionService {
   }
   async createSession(appName, userId, state, sessionId) {
     await this.ensureInitialized();
-    const id = _optionalChain([sessionId, 'optionalAccess', _291 => _291.trim, 'call', _292 => _292()]) || this.generateSessionId();
+    const id = _optionalChain([sessionId, 'optionalAccess', _295 => _295.trim, 'call', _296 => _296()]) || this.generateSessionId();
     return await this.db.transaction().execute(async (trx) => {
       const appState = await trx.selectFrom("app_states").selectAll().where("app_name", "=", appName).executeTakeFirst();
       const userState = await trx.selectFrom("user_states").selectAll().where("app_name", "=", appName).where("user_id", "=", userId).executeTakeFirst();
-      let currentAppState = this.parseJsonSafely(_optionalChain([appState, 'optionalAccess', _293 => _293.state]), {});
-      let currentUserState = this.parseJsonSafely(_optionalChain([userState, 'optionalAccess', _294 => _294.state]), {});
+      let currentAppState = this.parseJsonSafely(_optionalChain([appState, 'optionalAccess', _297 => _297.state]), {});
+      let currentUserState = this.parseJsonSafely(_optionalChain([userState, 'optionalAccess', _298 => _298.state]), {});
       if (!appState) {
         await trx.insertInto("app_states").values({
           app_name: appName,
@@ -11441,21 +11724,21 @@ var DatabaseSessionService = (_class34 = class extends BaseSessionService {
         return void 0;
       }
       let eventQuery = trx.selectFrom("events").selectAll().where("session_id", "=", sessionId).orderBy("timestamp", "desc");
-      if (_optionalChain([config, 'optionalAccess', _295 => _295.afterTimestamp])) {
+      if (_optionalChain([config, 'optionalAccess', _299 => _299.afterTimestamp])) {
         eventQuery = eventQuery.where(
           "timestamp",
           ">=",
           new Date(config.afterTimestamp * 1e3)
         );
       }
-      if (_optionalChain([config, 'optionalAccess', _296 => _296.numRecentEvents])) {
+      if (_optionalChain([config, 'optionalAccess', _300 => _300.numRecentEvents])) {
         eventQuery = eventQuery.limit(config.numRecentEvents);
       }
       const storageEvents = await eventQuery.execute();
       const appState = await trx.selectFrom("app_states").selectAll().where("app_name", "=", appName).executeTakeFirst();
       const userState = await trx.selectFrom("user_states").selectAll().where("app_name", "=", appName).where("user_id", "=", userId).executeTakeFirst();
-      const currentAppState = this.parseJsonSafely(_optionalChain([appState, 'optionalAccess', _297 => _297.state]), {});
-      const currentUserState = this.parseJsonSafely(_optionalChain([userState, 'optionalAccess', _298 => _298.state]), {});
+      const currentAppState = this.parseJsonSafely(_optionalChain([appState, 'optionalAccess', _301 => _301.state]), {});
+      const currentUserState = this.parseJsonSafely(_optionalChain([userState, 'optionalAccess', _302 => _302.state]), {});
       const sessionState = this.parseJsonSafely(storageSession.state, {});
       const mergedState = this.mergeState(
         currentAppState,
@@ -11513,13 +11796,13 @@ var DatabaseSessionService = (_class34 = class extends BaseSessionService {
       }
       const appState = await trx.selectFrom("app_states").selectAll().where("app_name", "=", session.appName).executeTakeFirst();
       const userState = await trx.selectFrom("user_states").selectAll().where("app_name", "=", session.appName).where("user_id", "=", session.userId).executeTakeFirst();
-      let currentAppState = this.parseJsonSafely(_optionalChain([appState, 'optionalAccess', _299 => _299.state]), {});
-      let currentUserState = this.parseJsonSafely(_optionalChain([userState, 'optionalAccess', _300 => _300.state]), {});
+      let currentAppState = this.parseJsonSafely(_optionalChain([appState, 'optionalAccess', _303 => _303.state]), {});
+      let currentUserState = this.parseJsonSafely(_optionalChain([userState, 'optionalAccess', _304 => _304.state]), {});
       let sessionState = this.parseJsonSafely(storageSession.state, {});
       let appStateDelta = {};
       let userStateDelta = {};
       let sessionStateDelta = {};
-      if (_optionalChain([event, 'access', _301 => _301.actions, 'optionalAccess', _302 => _302.stateDelta])) {
+      if (_optionalChain([event, 'access', _305 => _305.actions, 'optionalAccess', _306 => _306.stateDelta])) {
         const deltas = this.extractStateDelta(event.actions.stateDelta);
         appStateDelta = deltas.appStateDelta;
         userStateDelta = deltas.userStateDelta;
@@ -11665,7 +11948,7 @@ var DatabaseSessionService = (_class34 = class extends BaseSessionService {
    * Overrides the base class method to work with plain object state.
    */
   updateSessionState(session, event) {
-    if (!_optionalChain([event, 'access', _303 => _303.actions, 'optionalAccess', _304 => _304.stateDelta])) {
+    if (!_optionalChain([event, 'access', _307 => _307.actions, 'optionalAccess', _308 => _308.stateDelta])) {
       return;
     }
     for (const [key, value] of Object.entries(event.actions.stateDelta)) {
@@ -11835,7 +12118,7 @@ var GcsArtifactService = class {
       };
       return part;
     } catch (error) {
-      if (_optionalChain([error, 'optionalAccess', _305 => _305.code]) === 404) {
+      if (_optionalChain([error, 'optionalAccess', _309 => _309.code]) === 404) {
         return null;
       }
       throw error;
@@ -12086,13 +12369,13 @@ var VertexAiEvalFacade = class _VertexAiEvalFacade {
     };
   }
   _getText(content) {
-    if (_optionalChain([content, 'optionalAccess', _306 => _306.parts])) {
+    if (_optionalChain([content, 'optionalAccess', _310 => _310.parts])) {
       return content.parts.map((p) => p.text || "").filter((text) => text.length > 0).join("\n");
     }
     return "";
   }
   _getScore(evalResult) {
-    if (_optionalChain([evalResult, 'optionalAccess', _307 => _307.summaryMetrics, 'optionalAccess', _308 => _308[0], 'optionalAccess', _309 => _309.meanScore]) !== void 0 && typeof evalResult.summaryMetrics[0].meanScore === "number" && !Number.isNaN(evalResult.summaryMetrics[0].meanScore)) {
+    if (_optionalChain([evalResult, 'optionalAccess', _311 => _311.summaryMetrics, 'optionalAccess', _312 => _312[0], 'optionalAccess', _313 => _313.meanScore]) !== void 0 && typeof evalResult.summaryMetrics[0].meanScore === "number" && !Number.isNaN(evalResult.summaryMetrics[0].meanScore)) {
       return evalResult.summaryMetrics[0].meanScore;
     }
     return void 0;
@@ -12242,7 +12525,7 @@ var ResponseEvaluator = class extends Evaluator {
     return fmeasure;
   }
   extractText(content) {
-    if (_optionalChain([content, 'optionalAccess', _310 => _310.parts])) {
+    if (_optionalChain([content, 'optionalAccess', _314 => _314.parts])) {
       return content.parts.map((p) => p.text || "").filter((text) => text.length > 0).join(" ");
     }
     return "";
@@ -12275,7 +12558,7 @@ var TrajectoryEvaluator = class extends Evaluator {
     for (let i = 0; i < actualInvocations.length; i++) {
       const actual = actualInvocations[i];
       const expected = expectedInvocations[i];
-      if (!_optionalChain([actual, 'access', _311 => _311.intermediateData, 'optionalAccess', _312 => _312.toolUses]) || !_optionalChain([expected, 'access', _313 => _313.intermediateData, 'optionalAccess', _314 => _314.toolUses])) {
+      if (!_optionalChain([actual, 'access', _315 => _315.intermediateData, 'optionalAccess', _316 => _316.toolUses]) || !_optionalChain([expected, 'access', _317 => _317.intermediateData, 'optionalAccess', _318 => _318.toolUses])) {
         perInvocationResults.push({
           actualInvocation: actual,
           expectedInvocation: expected,
@@ -12363,7 +12646,7 @@ var SafetyEvaluatorV1 = class extends Evaluator {
 
 // src/evaluation/llm-as-judge-utils.ts
 function getTextFromContent(content) {
-  if (_optionalChain([content, 'optionalAccess', _315 => _315.parts])) {
+  if (_optionalChain([content, 'optionalAccess', _319 => _319.parts])) {
     return content.parts.map((part) => part.text).filter(Boolean).join("\n");
   }
   return "";
@@ -12375,9 +12658,9 @@ function getEvalStatus(score, threshold) {
 // src/evaluation/llm-as-judge.ts
 var LlmAsJudge = class {
   async sampleJudge(prompt, numSamples, critiqueParser, judgeModelOptions) {
-    const modelName = _optionalChain([judgeModelOptions, 'optionalAccess', _316 => _316.judgeModel]) || "gemini-2.5-flash";
+    const modelName = _optionalChain([judgeModelOptions, 'optionalAccess', _320 => _320.judgeModel]) || "gemini-2.5-flash";
     const model = LLMRegistry.getModelOrCreate(modelName);
-    const config = _optionalChain([judgeModelOptions, 'optionalAccess', _317 => _317.judgeModelConfig]) || {};
+    const config = _optionalChain([judgeModelOptions, 'optionalAccess', _321 => _321.judgeModelConfig]) || {};
     const samples = [];
     for (let i = 0; i < numSamples; i++) {
       try {
@@ -12443,7 +12726,7 @@ function parseCritique(response) {
   const labelMatchIsResponseValid = response.match(
     /"is_the_agent_response_valid":\s*\[*[\n\s]*"*([^"^\]^\s]*)"*[\n\s]*\]*\s*[,\n\}]/
   );
-  if (_optionalChain([labelMatchIsResponseValid, 'optionalAccess', _318 => _318[1]])) {
+  if (_optionalChain([labelMatchIsResponseValid, 'optionalAccess', _322 => _322[1]])) {
     const label = labelMatchIsResponseValid[1].toLowerCase();
     return label === "valid" ? "valid" /* VALID */ : "invalid" /* INVALID */;
   }
@@ -12488,7 +12771,7 @@ var FinalResponseMatchV2Evaluator = class extends Evaluator {
         "{prompt}",
         prompt
       ).replace("{response}", response).replace("{golden_response}", goldenResponse);
-      const numSamples = _nullishCoalesce(_optionalChain([this, 'access', _319 => _319.metric, 'access', _320 => _320.judgeModelOptions, 'optionalAccess', _321 => _321.numSamples]), () => ( DEFAULT_NUM_SAMPLES));
+      const numSamples = _nullishCoalesce(_optionalChain([this, 'access', _323 => _323.metric, 'access', _324 => _324.judgeModelOptions, 'optionalAccess', _325 => _325.numSamples]), () => ( DEFAULT_NUM_SAMPLES));
       const labels = await this.llmAsJudge.sampleJudge(
         formattedPrompt,
         numSamples,
@@ -12515,8 +12798,8 @@ var FinalResponseMatchV2Evaluator = class extends Evaluator {
 };
 
 // src/evaluation/metric-evaluator-registry.ts
-var MetricEvaluatorRegistry = (_class35 = class {constructor() { _class35.prototype.__init61.call(this); }
-  __init61() {this.registry = /* @__PURE__ */ new Map()}
+var MetricEvaluatorRegistry = (_class35 = class {constructor() { _class35.prototype.__init60.call(this); }
+  __init60() {this.registry = /* @__PURE__ */ new Map()}
   getEvaluator(evalMetric) {
     const entry = this.registry.get(evalMetric.metricName);
     if (!entry) {
@@ -12528,7 +12811,7 @@ var MetricEvaluatorRegistry = (_class35 = class {constructor() { _class35.protot
     const metricName = metricInfo.metricName;
     if (this.registry.has(metricName)) {
       console.info(
-        `Updating Evaluator class for ${metricName} from ${_optionalChain([this, 'access', _322 => _322.registry, 'access', _323 => _323.get, 'call', _324 => _324(metricName), 'optionalAccess', _325 => _325.evaluator, 'access', _326 => _326.name])} to ${evaluator.name}`
+        `Updating Evaluator class for ${metricName} from ${_optionalChain([this, 'access', _326 => _326.registry, 'access', _327 => _327.get, 'call', _328 => _328(metricName), 'optionalAccess', _329 => _329.evaluator, 'access', _330 => _330.name])} to ${evaluator.name}`
       );
     }
     this.registry.set(metricName, {
@@ -12642,10 +12925,10 @@ var LocalEvalService = class extends BaseEvalService {
       for (const evalMetric of evaluateConfig.evalMetrics) {
         const evaluator = DEFAULT_METRIC_EVALUATOR_REGISTRY.getEvaluator(evalMetric);
         const actual = results.filter(
-          (r) => !_optionalChain([r, 'access', _327 => _327.invocationId, 'optionalAccess', _328 => _328.includes, 'call', _329 => _329("expected")])
+          (r) => !_optionalChain([r, 'access', _331 => _331.invocationId, 'optionalAccess', _332 => _332.includes, 'call', _333 => _333("expected")])
         );
         const expected = results.filter(
-          (r) => _optionalChain([r, 'access', _330 => _330.invocationId, 'optionalAccess', _331 => _331.includes, 'call', _332 => _332("expected")])
+          (r) => _optionalChain([r, 'access', _334 => _334.invocationId, 'optionalAccess', _335 => _335.includes, 'call', _336 => _336("expected")])
         );
         const result = await evaluator.evaluateInvocations(actual, expected);
         evalResult.evalCaseResults.push({
@@ -13037,13 +13320,13 @@ ${failures.join(
     console.log("\n\n");
   }
   static _convertContentToText(content) {
-    if (_optionalChain([content, 'optionalAccess', _333 => _333.parts])) {
+    if (_optionalChain([content, 'optionalAccess', _337 => _337.parts])) {
       return content.parts.map((p) => p.text || "").filter((text) => text.length > 0).join("\n");
     }
     return "";
   }
   static _convertToolCallsToText(intermediateData) {
-    if (_optionalChain([intermediateData, 'optionalAccess', _334 => _334.toolUses])) {
+    if (_optionalChain([intermediateData, 'optionalAccess', _338 => _338.toolUses])) {
       return intermediateData.toolUses.map((t) => JSON.stringify(t)).join("\n");
     }
     return "";
@@ -13098,7 +13381,7 @@ ${failures.join(
     for (const [metricName, evalMetricResultsWithInvocations] of Object.entries(
       evalMetricResults
     )) {
-      const threshold = _optionalChain([evalMetricResultsWithInvocations, 'access', _335 => _335[0], 'optionalAccess', _336 => _336.evalMetricResult, 'access', _337 => _337.threshold]) || 0;
+      const threshold = _optionalChain([evalMetricResultsWithInvocations, 'access', _339 => _339[0], 'optionalAccess', _340 => _340.evalMetricResult, 'access', _341 => _341.threshold]) || 0;
       const scores = evalMetricResultsWithInvocations.map((m) => m.evalMetricResult.score).filter((s) => s !== void 0);
       let overallScore;
       let overallEvalStatus;
@@ -13187,7 +13470,7 @@ var RougeEvaluator = class extends Evaluator {
   }
 };
 function getTextFromContent2(content) {
-  if (_optionalChain([content, 'optionalAccess', _338 => _338.parts])) {
+  if (_optionalChain([content, 'optionalAccess', _342 => _342.parts])) {
     return content.parts.map((part) => part.text).filter(Boolean).join("\n");
   }
   return "";