@iqai/adk 0.2.5 → 0.3.1

package/dist/index.mjs

@@ -30,98 +30,269 @@ import chalk from "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: chalk.blue, method: console.log },
+      info: { icon: "\u2139\uFE0F", color: chalk.cyan, method: console.debug },
+      warn: { icon: "\u{1F6A7}", color: chalk.yellow, method: console.warn },
+      error: { icon: "\u274C", color: chalk.red, method: console.error }
+    };
     Logger = class {
       name;
       isDebugEnabled = isDebugEnabled();
       constructor({ name }) {
         this.name = name;
       }
-      colorize(message) {
-        return chalk.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 {
+          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 = chalk.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: chalk.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: chalk.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}`;
+        });
+      }
+      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}`;
         });
-        console.log(this.colorize(bottomBorder));
+        if (items.length > maxItems) {
+          lines.push(`\u2026 ${items.length - maxItems} more items omitted`);
+        }
+        return lines;
       }
     };
   }
@@ -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,8 +10643,20 @@ var AgentBuilder = class _AgentBuilder {
   // If provided, reuse directly
   definitionLocked = false;
   // Lock further definition mutation after withAgent
-  warnedMethods = /* @__PURE__ */ new Set();
   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
    */
@@ -10541,6 +10716,16 @@ var AgentBuilder = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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,11 +11163,16 @@ var AgentBuilder = 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 = this.config.subAgents?.map((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 = "";
+        let combinedResponse = "";
+        const perAgentBuffers = {};
+        const authors = /* @__PURE__ */ new Set();
         if (!sessionOptions?.userId) {
           throw new Error("Session configuration is required");
         }
@@ -10903,45 +11186,45 @@ var AgentBuilder = class _AgentBuilder {
               (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);
-      }
-    }
-  }
 };
 
 // src/memory/index.ts