@iqai/adk 0.2.4 → 0.3.0

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;
       }
     };
   }
@@ -7111,6 +7282,7 @@ var AuthLlmRequestProcessor = class extends BaseLlmRequestProcessor {
 var requestProcessor = new AuthLlmRequestProcessor();
 
 // src/flows/llm-flows/basic.ts
+init_logger();
 var BasicLlmRequestProcessor = class extends BaseLlmRequestProcessor {
   async *runAsync(invocationContext, llmRequest) {
     const agent = invocationContext.agent;
@@ -7126,7 +7298,21 @@ var BasicLlmRequestProcessor = class extends BaseLlmRequestProcessor {
       llmRequest.config = {};
     }
     if (agent.outputSchema) {
-      llmRequest.setOutputSchema(agent.outputSchema);
+      const hasTools = (await agent.canonicalTools?.(invocationContext))?.length > 0;
+      const hasTransfers = !!("subAgents" in agent && agent.subAgents && agent.subAgents.length > 0 && !(agent.disallowTransferToParent && agent.disallowTransferToPeers));
+      if (!hasTools && !hasTransfers) {
+        llmRequest.setOutputSchema(agent.outputSchema);
+      } else {
+        (() => {
+          try {
+            const logger = new Logger({ name: "BasicLlmRequestProcessor" });
+            logger.debug(
+              `Skipping request-level output schema for agent ${agent.name} because tools/transfers are present. Schema will be validated during response processing.`
+            );
+          } catch (e) {
+          }
+        })();
+      }
     }
     const runConfig = invocationContext.runConfig;
     if (!llmRequest.liveConnectConfig) {
@@ -8278,10 +8464,11 @@ var InstructionsLlmRequestProcessor = class extends BaseLlmRequestProcessor {
         });
         const { $schema, ...json } = raw || {};
         llmRequest.appendInstructions([
-          "You must respond with application/json that validates against this JSON Schema:",
-          "```json",
-          JSON.stringify(json, null, 2),
-          "```"
+          "You must respond with application/json that validates against this JSON Schema (do NOT wrap the output in markdown or code fences):",
+          JSON.stringify(json, null, 2)
+        ]);
+        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 {
       }
@@ -8578,6 +8765,7 @@ var requestProcessor7 = new NlPlanningRequestProcessor();
 var responseProcessor2 = new NlPlanningResponseProcessor();
 
 // src/flows/llm-flows/output-schema.ts
+import { jsonrepair } from "jsonrepair";
 init_logger();
 var OutputSchemaResponseProcessor = class extends BaseLlmResponseProcessor {
   logger = new Logger({ name: "OutputSchemaResponseProcessor" });
@@ -8599,7 +8787,8 @@ var OutputSchemaResponseProcessor = class extends BaseLlmResponseProcessor {
       return;
     }
     try {
-      const parsed = JSON.parse(textContent);
+      const candidate = this.stripCodeFences(textContent);
+      const parsed = this.tryParseJson(candidate, agent.name);
       const validated = agent.outputSchema.parse(parsed);
       textContent = JSON.stringify(validated, null, 2);
       llmResponse.content.parts = llmResponse.content.parts.map((part) => {
@@ -8647,6 +8836,38 @@ var OutputSchemaResponseProcessor = class extends BaseLlmResponseProcessor {
       yield errorEvent;
     }
   }
+  // Strip common code fences and surrounding explanatory text from LLM output.
+  stripCodeFences(raw) {
+    const fencePattern = /```(?:json)?\s*([\s\S]*?)```/i;
+    const fenceMatch = raw.match(fencePattern);
+    if (fenceMatch?.[1]) {
+      return fenceMatch[1].trim();
+    }
+    const lines = raw.split(/\r?\n/).map((l) => l.trim());
+    const startIdx = lines.findIndex(
+      (l) => l.startsWith("{") || l.startsWith("[")
+    );
+    if (startIdx >= 0) {
+      return lines.slice(startIdx).join("\n").trim();
+    }
+    return raw.trim();
+  }
+  // Try parsing JSON; if parse fails, attempt to repair using jsonrepair and parse again.
+  tryParseJson(candidate, agentName) {
+    try {
+      return JSON.parse(candidate);
+    } catch (err) {
+      this.logger.debug("Initial JSON.parse failed, attempting jsonrepair", {
+        agent: agentName
+      });
+      try {
+        const repaired = jsonrepair(candidate);
+        return JSON.parse(repaired);
+      } catch (repairErr) {
+        throw err;
+      }
+    }
+  }
 };
 var responseProcessor3 = new OutputSchemaResponseProcessor();
 
@@ -9069,19 +9290,17 @@ var LlmAgent = class _LlmAgent extends BaseAgent {
     }
     if (!this.disallowTransferToParent || !this.disallowTransferToPeers) {
       this.logger.warn(
-        `Invalid config for agent ${this.name}: output_schema cannot co-exist with agent transfer configurations. Setting disallow_transfer_to_parent=true, disallow_transfer_to_peers=true`
+        `Agent ${this.name}: outputSchema is set while transfer flags allow transfers. The output schema will be applied in response post-processing to preserve tool-calling and transfer behavior.`
       );
-      this.disallowTransferToParent = true;
-      this.disallowTransferToPeers = true;
     }
     if (this.subAgents && this.subAgents.length > 0) {
-      throw new Error(
-        `Invalid config for agent ${this.name}: if output_schema is set, sub_agents must be empty to disable agent transfer.`
+      this.logger.warn(
+        `Agent ${this.name}: outputSchema is set and subAgents are present. Agent transfers to sub-agents will remain enabled; the schema will be validated after transfers/tools complete.`
       );
     }
     if (this.tools && this.tools.length > 0) {
-      throw new Error(
-        `Invalid config for agent ${this.name}: if output_schema is set, tools must be empty`
+      this.logger.warn(
+        `Agent ${this.name}: outputSchema is set and tools are configured. Tools will be callable; the output schema will be applied during response post-processing.`
       );
     }
   }
@@ -9243,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;
     }
   }
 }
@@ -10432,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
    */
@@ -10493,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;
   }
@@ -10533,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;
   }
@@ -10584,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;
   }
   /**
@@ -10595,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;
   }
   /**
@@ -10650,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,
@@ -10723,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
@@ -10751,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({
@@ -10775,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,
@@ -10784,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,
@@ -10793,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,
@@ -10803,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,
@@ -10837,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");
         }
@@ -10855,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