llmist 0.5.1 → 0.6.1

package/dist/index.cjs

@@ -345,12 +345,16 @@ var init_registry = __esm({
 });
 
 // src/core/constants.ts
-var GADGET_START_PREFIX, GADGET_END_PREFIX;
+var GADGET_START_PREFIX, GADGET_END_PREFIX, DEFAULT_GADGET_OUTPUT_LIMIT, DEFAULT_GADGET_OUTPUT_LIMIT_PERCENT, CHARS_PER_TOKEN, FALLBACK_CONTEXT_WINDOW;
 var init_constants = __esm({
   "src/core/constants.ts"() {
     "use strict";
     GADGET_START_PREFIX = "!!!GADGET_START:";
     GADGET_END_PREFIX = "!!!GADGET_END";
+    DEFAULT_GADGET_OUTPUT_LIMIT = true;
+    DEFAULT_GADGET_OUTPUT_LIMIT_PERCENT = 15;
+    CHARS_PER_TOKEN = 4;
+    FALLBACK_CONTEXT_WINDOW = 128e3;
   }
 });
 
@@ -384,7 +388,7 @@ var init_prompt_config = __esm({
       criticalUsage: "INVOKE gadgets using the markers - do not describe what you want to do.",
       formatDescriptionYaml: "Parameters in YAML format (one per line)",
       formatDescriptionJson: "Parameters in JSON format (valid JSON object)",
-      formatDescriptionToml: "Parameters in TOML format (key = value pairs, use triple-quotes for multiline)",
+      formatDescriptionToml: "Parameters in TOML format (key = value pairs, use heredoc for multiline: key = <<<EOF ... EOF)",
       rules: () => [
         "Output ONLY plain text with the exact markers - never use function/tool calling",
         "You can invoke multiple gadgets in a single response",
@@ -565,10 +569,11 @@ ${this.endPrefix}
 ${this.startPrefix}analyze
 type: economic_analysis
 matter: "Polish Economy"
-question: |
-  Analyze the following:
-  - Polish arms exports 2025
-  - Economic implications
+question: <<<EOF
+Analyze the following:
+- Polish arms exports 2025
+- Economic implications
+EOF
 ${this.endPrefix}`,
           json: `${this.startPrefix}translate
 {"from": "English", "to": "Polish", "content": "Paris is the capital of France: a beautiful city."}
@@ -584,11 +589,11 @@ ${this.endPrefix}
 ${this.startPrefix}analyze
 type = "economic_analysis"
 matter = "Polish Economy"
-question = """
+question = <<<EOF
 Analyze the following:
 - Polish arms exports 2025
 - Economic implications
-"""
+EOF
 ${this.endPrefix}`,
           auto: `${this.startPrefix}translate
 {"from": "English", "to": "Polish", "content": "Paris is the capital of France: a beautiful city."}
@@ -605,37 +610,38 @@ ${multipleExamples[parameterFormat]}`);
         if (parameterFormat === "yaml") {
           parts.push(`
 
-YAML MULTILINE SYNTAX:
-For string values with special characters (colons, dashes, quotes) or multiple lines,
-use the pipe (|) syntax. ALL content lines MUST be indented with 2 spaces:
+YAML HEREDOC SYNTAX:
+For string values with multiple lines, use heredoc syntax (<<<DELIMITER...DELIMITER):
+
+filePath: "README.md"
+content: <<<EOF
+# Project Title
 
-CORRECT - all lines indented:
-question: |
-  Which option do you prefer?
-  - Option A: fast processing
-  - Option B: thorough analysis
-  Please choose one.
+This content can contain:
+- Markdown lists
+- Special characters: # : -
+- Multiple paragraphs
+EOF
 
-WRONG - inconsistent indentation breaks YAML:
-question: |
-  Which option do you prefer?
-  - Option A: fast
-Please choose one.    <-- ERROR: not indented, breaks out of the block`);
+The delimiter (EOF) can be any identifier. The closing delimiter must be on its own line.
+No indentation is required for the content.`);
         } else if (parameterFormat === "toml") {
           parts.push(`
 
-TOML MULTILINE SYNTAX:
-For string values with multiple lines or special characters, use triple-quotes ("""):
+TOML HEREDOC SYNTAX:
+For string values with multiple lines, use heredoc syntax (<<<DELIMITER...DELIMITER):
 
 filePath = "README.md"
-content = """
+content = <<<EOF
 # Project Title
 
 This content can contain:
 - Markdown lists
 - Special characters: # : -
 - Multiple paragraphs
-"""`);
+EOF
+
+The delimiter (EOF) can be any identifier. The closing delimiter must be on its own line.`);
         }
         return parts.join("");
       }
@@ -714,18 +720,28 @@ function parseLogLevel(value) {
   }
   return LEVEL_NAME_TO_ID[normalized];
 }
+function parseEnvBoolean(value) {
+  if (!value) return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true" || normalized === "1") return true;
+  if (normalized === "false" || normalized === "0") return false;
+  return void 0;
+}
 function createLogger(options = {}) {
   const envMinLevel = parseLogLevel(process.env.LLMIST_LOG_LEVEL);
   const envLogFile = process.env.LLMIST_LOG_FILE?.trim() ?? "";
+  const envLogReset = parseEnvBoolean(process.env.LLMIST_LOG_RESET);
   const minLevel = options.minLevel ?? envMinLevel ?? 4;
   const defaultType = options.type ?? "pretty";
   const name = options.name ?? "llmist";
+  const logReset = options.logReset ?? envLogReset ?? false;
   let logFileStream;
   let finalType = defaultType;
   if (envLogFile) {
     try {
       (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(envLogFile), { recursive: true });
-      logFileStream = (0, import_node_fs.createWriteStream)(envLogFile, { flags: "a" });
+      const flags = logReset ? "w" : "a";
+      logFileStream = (0, import_node_fs.createWriteStream)(envLogFile, { flags });
       finalType = "hidden";
     } catch (error) {
       console.error("Failed to initialize LLMIST_LOG_FILE output:", error);
@@ -768,6 +784,532 @@ var init_logger = __esm({
   }
 });
 
+// src/gadgets/schema-to-json.ts
+function schemaToJSONSchema(schema, options) {
+  const jsonSchema = z2.toJSONSchema(schema, options ?? { target: "draft-7" });
+  const mismatches = detectDescriptionMismatch(schema, jsonSchema);
+  if (mismatches.length > 0) {
+    defaultLogger.warn(
+      `Zod instance mismatch detected: ${mismatches.length} description(s) lost. For best results, use: import { z } from "llmist"`
+    );
+    return mergeDescriptions(schema, jsonSchema);
+  }
+  return jsonSchema;
+}
+function detectDescriptionMismatch(schema, jsonSchema) {
+  const mismatches = [];
+  function checkSchema(zodSchema, json, path) {
+    if (!zodSchema || typeof zodSchema !== "object") return;
+    const def = zodSchema._def;
+    const jsonObj = json;
+    if (def?.description && !jsonObj?.description) {
+      mismatches.push(path || "root");
+    }
+    if (def?.typeName === "ZodObject" && def?.shape) {
+      const shape = typeof def.shape === "function" ? def.shape() : def.shape;
+      for (const [key, fieldSchema] of Object.entries(shape)) {
+        const properties = jsonObj?.properties;
+        const jsonProp = properties?.[key];
+        checkSchema(fieldSchema, jsonProp, path ? `${path}.${key}` : key);
+      }
+    }
+    if (def?.typeName === "ZodArray" && def?.type) {
+      checkSchema(def.type, jsonObj?.items, path ? `${path}[]` : "[]");
+    }
+    if ((def?.typeName === "ZodOptional" || def?.typeName === "ZodNullable") && def?.innerType) {
+      checkSchema(def.innerType, json, path);
+    }
+    if (def?.typeName === "ZodDefault" && def?.innerType) {
+      checkSchema(def.innerType, json, path);
+    }
+  }
+  checkSchema(schema, jsonSchema, "");
+  return mismatches;
+}
+function mergeDescriptions(schema, jsonSchema) {
+  function merge(zodSchema, json) {
+    if (!json || typeof json !== "object") return json;
+    const def = zodSchema._def;
+    const jsonObj = json;
+    const merged = { ...jsonObj };
+    if (def?.description && !jsonObj.description) {
+      merged.description = def.description;
+    }
+    if (def?.typeName === "ZodObject" && def?.shape && jsonObj.properties) {
+      const shape = typeof def.shape === "function" ? def.shape() : def.shape;
+      const properties = jsonObj.properties;
+      merged.properties = { ...properties };
+      for (const [key, fieldSchema] of Object.entries(shape)) {
+        if (properties[key]) {
+          merged.properties[key] = merge(fieldSchema, properties[key]);
+        }
+      }
+    }
+    if (def?.typeName === "ZodArray" && def?.type && jsonObj.items) {
+      merged.items = merge(def.type, jsonObj.items);
+    }
+    if ((def?.typeName === "ZodOptional" || def?.typeName === "ZodNullable") && def?.innerType) {
+      return merge(def.innerType, json);
+    }
+    if (def?.typeName === "ZodDefault" && def?.innerType) {
+      return merge(def.innerType, json);
+    }
+    return merged;
+  }
+  return merge(schema, jsonSchema);
+}
+var z2;
+var init_schema_to_json = __esm({
+  "src/gadgets/schema-to-json.ts"() {
+    "use strict";
+    z2 = __toESM(require("zod"), 1);
+    init_logger();
+  }
+});
+
+// src/gadgets/gadget.ts
+function findSafeDelimiter(content) {
+  const lines = content.split("\n");
+  for (const delimiter of HEREDOC_DELIMITERS) {
+    const regex = new RegExp(`^${delimiter}\\s*$`);
+    const isUsed = lines.some((line) => regex.test(line));
+    if (!isUsed) {
+      return delimiter;
+    }
+  }
+  let counter = 1;
+  while (counter < 1e3) {
+    const delimiter = `HEREDOC_${counter}`;
+    const regex = new RegExp(`^${delimiter}\\s*$`);
+    const isUsed = lines.some((line) => regex.test(line));
+    if (!isUsed) {
+      return delimiter;
+    }
+    counter++;
+  }
+  return "HEREDOC_FALLBACK";
+}
+function formatYamlValue(value, indent = "") {
+  if (typeof value === "string") {
+    const lines = value.split("\n");
+    if (lines.length === 1 && !value.includes(":") && !value.startsWith("-")) {
+      return value;
+    }
+    const delimiter = findSafeDelimiter(value);
+    return `<<<${delimiter}
+${value}
+${delimiter}`;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (value === null || value === void 0) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    const items = value.map((item) => `${indent}- ${formatYamlValue(item, indent + "  ")}`);
+    return "\n" + items.join("\n");
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return "{}";
+    const lines = entries.map(([k, v]) => {
+      const formattedValue = formatYamlValue(v, indent + "  ");
+      if (formattedValue.startsWith("\n") || formattedValue.startsWith("|")) {
+        return `${indent}${k}: ${formattedValue}`;
+      }
+      return `${indent}${k}: ${formattedValue}`;
+    });
+    return "\n" + lines.join("\n");
+  }
+  return yaml.dump(value).trimEnd();
+}
+function formatParamsAsYaml(params) {
+  const lines = [];
+  for (const [key, value] of Object.entries(params)) {
+    const formattedValue = formatYamlValue(value, "");
+    if (formattedValue.startsWith("\n")) {
+      lines.push(`${key}:${formattedValue}`);
+    } else {
+      lines.push(`${key}: ${formattedValue}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatTomlValue(value) {
+  if (typeof value === "string") {
+    if (value.includes("\n")) {
+      const delimiter = findSafeDelimiter(value);
+      return `<<<${delimiter}
+${value}
+${delimiter}`;
+    }
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (value === null || value === void 0) {
+    return '""';
+  }
+  if (Array.isArray(value)) {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return JSON.stringify(value);
+}
+function formatParamsAsToml(params) {
+  const lines = [];
+  for (const [key, value] of Object.entries(params)) {
+    lines.push(`${key} = ${formatTomlValue(value)}`);
+  }
+  return lines.join("\n");
+}
+var yaml, HEREDOC_DELIMITERS, BaseGadget;
+var init_gadget = __esm({
+  "src/gadgets/gadget.ts"() {
+    "use strict";
+    yaml = __toESM(require("js-yaml"), 1);
+    init_schema_to_json();
+    init_schema_validator();
+    HEREDOC_DELIMITERS = ["EOF", "END", "DOC", "CONTENT", "TEXT", "HEREDOC", "DATA", "BLOCK"];
+    BaseGadget = class {
+      /**
+       * The name of the gadget. Used for identification when LLM calls it.
+       * If not provided, defaults to the class name.
+       */
+      name;
+      /**
+       * Optional Zod schema describing the expected input payload. When provided,
+       * it will be validated before execution and transformed into a JSON Schema
+       * representation that is surfaced to the LLM as part of the instructions.
+       */
+      parameterSchema;
+      /**
+       * Optional timeout in milliseconds for gadget execution.
+       * If execution exceeds this timeout, a TimeoutException will be thrown.
+       * If not set, the global defaultGadgetTimeoutMs from runtime options will be used.
+       * Set to 0 or undefined to disable timeout for this gadget.
+       */
+      timeoutMs;
+      /**
+       * Optional usage examples to help LLMs understand proper invocation.
+       * Examples are rendered in getInstruction() alongside the schema.
+       *
+       * Note: Uses broader `unknown` type to allow typed examples from subclasses
+       * while maintaining runtime compatibility.
+       */
+      examples;
+      /**
+       * Auto-generated instruction text for the LLM.
+       * Combines name, description, and parameter schema into a formatted instruction.
+       * @deprecated Use getInstruction(format) instead for format-specific schemas
+       */
+      get instruction() {
+        return this.getInstruction("yaml");
+      }
+      /**
+       * Generate instruction text for the LLM with format-specific schema.
+       * Combines name, description, and parameter schema into a formatted instruction.
+       *
+       * @param format - Format for the schema representation ('json' | 'yaml' | 'toml' | 'auto')
+       * @returns Formatted instruction string
+       */
+      getInstruction(format = "json") {
+        const parts = [];
+        parts.push(this.description);
+        if (this.parameterSchema) {
+          const gadgetName = this.name ?? this.constructor.name;
+          validateGadgetSchema(this.parameterSchema, gadgetName);
+          const jsonSchema = schemaToJSONSchema(this.parameterSchema, {
+            target: "draft-7"
+          });
+          if (format === "json" || format === "auto") {
+            parts.push("\n\nInput Schema (JSON):");
+            parts.push(JSON.stringify(jsonSchema, null, 2));
+          } else if (format === "toml") {
+            parts.push("\n\nInput Schema (TOML):");
+            parts.push(JSON.stringify(jsonSchema, null, 2));
+          } else {
+            const yamlSchema = yaml.dump(jsonSchema).trimEnd();
+            parts.push("\n\nInput Schema (YAML):");
+            parts.push(yamlSchema);
+          }
+        }
+        if (this.examples && this.examples.length > 0) {
+          parts.push("\n\nExamples:");
+          this.examples.forEach((example, index) => {
+            if (index > 0) {
+              parts.push("");
+            }
+            if (example.comment) {
+              parts.push(`# ${example.comment}`);
+            }
+            parts.push("Input:");
+            if (format === "json" || format === "auto") {
+              parts.push(JSON.stringify(example.params, null, 2));
+            } else if (format === "toml") {
+              parts.push(formatParamsAsToml(example.params));
+            } else {
+              parts.push(formatParamsAsYaml(example.params));
+            }
+            if (example.output !== void 0) {
+              parts.push("Output:");
+              parts.push(example.output);
+            }
+          });
+        }
+        return parts.join("\n");
+      }
+    };
+  }
+});
+
+// src/gadgets/create-gadget.ts
+function createGadget(config) {
+  class DynamicGadget extends BaseGadget {
+    name = config.name;
+    description = config.description;
+    parameterSchema = config.schema;
+    timeoutMs = config.timeoutMs;
+    examples = config.examples;
+    execute(params) {
+      return config.execute(params);
+    }
+  }
+  return new DynamicGadget();
+}
+var init_create_gadget = __esm({
+  "src/gadgets/create-gadget.ts"() {
+    "use strict";
+    init_gadget();
+  }
+});
+
+// src/gadgets/output-viewer.ts
+function applyPattern(lines, pattern) {
+  const regex = new RegExp(pattern.regex);
+  if (!pattern.include) {
+    return lines.filter((line) => !regex.test(line));
+  }
+  const matchIndices = /* @__PURE__ */ new Set();
+  for (let i = 0; i < lines.length; i++) {
+    if (regex.test(lines[i])) {
+      const start = Math.max(0, i - pattern.before);
+      const end = Math.min(lines.length - 1, i + pattern.after);
+      for (let j = start; j <= end; j++) {
+        matchIndices.add(j);
+      }
+    }
+  }
+  return lines.filter((_, index) => matchIndices.has(index));
+}
+function applyPatterns(lines, patterns) {
+  let result = lines;
+  for (const pattern of patterns) {
+    result = applyPattern(result, pattern);
+  }
+  return result;
+}
+function applyLineLimit(lines, limit) {
+  const trimmed = limit.trim();
+  if (trimmed.endsWith("-") && !trimmed.startsWith("-")) {
+    const n = parseInt(trimmed.slice(0, -1), 10);
+    if (!isNaN(n) && n > 0) {
+      return lines.slice(0, n);
+    }
+  }
+  if (trimmed.startsWith("-") && !trimmed.includes("-", 1)) {
+    const n = parseInt(trimmed, 10);
+    if (!isNaN(n) && n < 0) {
+      return lines.slice(n);
+    }
+  }
+  const rangeMatch = trimmed.match(/^(\d+)-(\d+)$/);
+  if (rangeMatch) {
+    const start = parseInt(rangeMatch[1], 10);
+    const end = parseInt(rangeMatch[2], 10);
+    if (!isNaN(start) && !isNaN(end) && start > 0 && end >= start) {
+      return lines.slice(start - 1, end);
+    }
+  }
+  return lines;
+}
+function createGadgetOutputViewer(store) {
+  return createGadget({
+    name: "GadgetOutputViewer",
+    description: "View stored output from gadgets that returned too much data. Use patterns to filter lines (like grep) and limit to control output size. Patterns are applied first in order, then the limit is applied to the result.",
+    schema: import_zod.z.object({
+      id: import_zod.z.string().describe("ID of the stored output (from the truncation message)"),
+      patterns: import_zod.z.array(patternSchema).optional().describe(
+        "Filter patterns applied in order (like piping through grep). Each pattern can include or exclude lines with optional before/after context."
+      ),
+      limit: import_zod.z.string().optional().describe(
+        "Line range to return after filtering. Formats: '100-' (first 100), '-25' (last 25), '50-100' (lines 50-100)"
+      )
+    }),
+    examples: [
+      {
+        comment: "View first 50 lines of stored output",
+        params: { id: "Search_abc12345", limit: "50-" }
+      },
+      {
+        comment: "Filter for error lines with context",
+        params: {
+          id: "Search_abc12345",
+          patterns: [{ regex: "error|Error|ERROR", include: true, before: 2, after: 5 }]
+        }
+      },
+      {
+        comment: "Exclude blank lines, then show first 100",
+        params: {
+          id: "Search_abc12345",
+          patterns: [{ regex: "^\\s*$", include: false, before: 0, after: 0 }],
+          limit: "100-"
+        }
+      },
+      {
+        comment: "Chain filters: find TODOs, exclude tests, limit to 50 lines",
+        params: {
+          id: "Search_abc12345",
+          patterns: [
+            { regex: "TODO", include: true, before: 1, after: 1 },
+            { regex: "test|spec", include: false, before: 0, after: 0 }
+          ],
+          limit: "50-"
+        }
+      }
+    ],
+    execute: ({ id, patterns, limit }) => {
+      const stored = store.get(id);
+      if (!stored) {
+        return `Error: No stored output with id "${id}". Available IDs: ${store.getIds().join(", ") || "(none)"}`;
+      }
+      let lines = stored.content.split("\n");
+      if (patterns && patterns.length > 0) {
+        lines = applyPatterns(
+          lines,
+          patterns.map((p) => ({
+            regex: p.regex,
+            include: p.include ?? true,
+            before: p.before ?? 0,
+            after: p.after ?? 0
+          }))
+        );
+      }
+      if (limit) {
+        lines = applyLineLimit(lines, limit);
+      }
+      const totalLines = stored.lineCount;
+      const returnedLines = lines.length;
+      if (returnedLines === 0) {
+        return `No lines matched the filters. Original output had ${totalLines} lines.`;
+      }
+      const header = returnedLines < totalLines ? `[Showing ${returnedLines} of ${totalLines} lines]
+` : `[Showing all ${totalLines} lines]
+`;
+      return header + lines.join("\n");
+    }
+  });
+}
+var import_zod, patternSchema;
+var init_output_viewer = __esm({
+  "src/gadgets/output-viewer.ts"() {
+    "use strict";
+    import_zod = require("zod");
+    init_create_gadget();
+    patternSchema = import_zod.z.object({
+      regex: import_zod.z.string().describe("Regular expression to match"),
+      include: import_zod.z.boolean().default(true).describe("true = keep matching lines, false = exclude matching lines"),
+      before: import_zod.z.number().int().min(0).default(0).describe("Context lines before each match (like grep -B)"),
+      after: import_zod.z.number().int().min(0).default(0).describe("Context lines after each match (like grep -A)")
+    });
+  }
+});
+
+// src/agent/gadget-output-store.ts
+var import_node_crypto, GadgetOutputStore;
+var init_gadget_output_store = __esm({
+  "src/agent/gadget-output-store.ts"() {
+    "use strict";
+    import_node_crypto = require("crypto");
+    GadgetOutputStore = class {
+      outputs = /* @__PURE__ */ new Map();
+      /**
+       * Store a gadget output and return its ID.
+       *
+       * @param gadgetName - Name of the gadget that produced the output
+       * @param content - Full output content to store
+       * @returns Generated ID for retrieving the output later
+       */
+      store(gadgetName, content) {
+        const id = this.generateId(gadgetName);
+        const encoder = new TextEncoder();
+        const stored = {
+          id,
+          gadgetName,
+          content,
+          byteSize: encoder.encode(content).length,
+          lineCount: content.split("\n").length,
+          timestamp: /* @__PURE__ */ new Date()
+        };
+        this.outputs.set(id, stored);
+        return id;
+      }
+      /**
+       * Retrieve a stored output by ID.
+       *
+       * @param id - The output ID (e.g., "Search_d34db33f")
+       * @returns The stored output or undefined if not found
+       */
+      get(id) {
+        return this.outputs.get(id);
+      }
+      /**
+       * Check if an output exists.
+       *
+       * @param id - The output ID to check
+       * @returns True if the output exists
+       */
+      has(id) {
+        return this.outputs.has(id);
+      }
+      /**
+       * Get all stored output IDs.
+       *
+       * @returns Array of output IDs
+       */
+      getIds() {
+        return Array.from(this.outputs.keys());
+      }
+      /**
+       * Get the number of stored outputs.
+       */
+      get size() {
+        return this.outputs.size;
+      }
+      /**
+       * Clear all stored outputs.
+       * Called when the agent run completes.
+       */
+      clear() {
+        this.outputs.clear();
+      }
+      /**
+       * Generate a unique ID for a stored output.
+       * Format: {GadgetName}_{8 hex chars}
+       */
+      generateId(gadgetName) {
+        const hex = (0, import_node_crypto.randomBytes)(4).toString("hex");
+        return `${gadgetName}_${hex}`;
+      }
+    };
+  }
+});
+
 // src/agent/agent-internal-key.ts
 function isValidAgentKey(key) {
   return key === AGENT_INTERNAL_KEY;
@@ -1305,6 +1847,25 @@ function preprocessYaml(yamlStr) {
   let i = 0;
   while (i < lines.length) {
     const line = lines[i];
+    const heredocMatch = line.match(/^(\s*)([\w-]+):\s*<<<([A-Za-z_][A-Za-z0-9_]*)\s*$/);
+    if (heredocMatch) {
+      const [, indent, key, delimiter] = heredocMatch;
+      const bodyLines = [];
+      i++;
+      const closingRegex = new RegExp(`^${delimiter}\\s*$`);
+      while (i < lines.length && !closingRegex.test(lines[i])) {
+        bodyLines.push(lines[i]);
+        i++;
+      }
+      if (i < lines.length) {
+        i++;
+      }
+      result.push(`${indent}${key}: |`);
+      for (const bodyLine of bodyLines) {
+        result.push(`${indent}  ${bodyLine}`);
+      }
+      continue;
+    }
     const match = line.match(/^(\s*)([\w-]+):\s+(.+)$/);
     if (match) {
       const [, indent, key, value] = match;
@@ -1396,11 +1957,53 @@ function preprocessYaml(yamlStr) {
   }
   return result.join("\n");
 }
-var yaml, import_js_toml, globalInvocationCounter, StreamParser;
+function preprocessTomlHeredoc(tomlStr) {
+  const lines = tomlStr.split("\n");
+  const result = [];
+  let i = 0;
+  const heredocStartRegex = /^(\s*)([\w-]+)\s*=\s*<<<([A-Za-z_][A-Za-z0-9_]*)\s*$/;
+  while (i < lines.length) {
+    const line = lines[i];
+    const match = line.match(heredocStartRegex);
+    if (match) {
+      const [, indent, key, delimiter] = match;
+      const bodyLines = [];
+      i++;
+      const closingRegex = new RegExp(`^${delimiter}\\s*$`);
+      let foundClosing = false;
+      while (i < lines.length) {
+        const bodyLine = lines[i];
+        if (closingRegex.test(bodyLine)) {
+          foundClosing = true;
+          i++;
+          break;
+        }
+        bodyLines.push(bodyLine);
+        i++;
+      }
+      if (bodyLines.length === 0) {
+        result.push(`${indent}${key} = """"""`);
+      } else {
+        result.push(`${indent}${key} = """`);
+        for (let j = 0; j < bodyLines.length - 1; j++) {
+          result.push(bodyLines[j]);
+        }
+        result.push(`${bodyLines[bodyLines.length - 1]}"""`);
+      }
+      if (!foundClosing) {
+      }
+      continue;
+    }
+    result.push(line);
+    i++;
+  }
+  return result.join("\n");
+}
+var yaml2, import_js_toml, globalInvocationCounter, StreamParser;
 var init_parser = __esm({
   "src/gadgets/parser.ts"() {
     "use strict";
-    yaml = __toESM(require("js-yaml"), 1);
+    yaml2 = __toESM(require("js-yaml"), 1);
     import_js_toml = require("js-toml");
     init_constants();
     globalInvocationCounter = 0;
@@ -1447,14 +2050,14 @@ var init_parser = __esm({
         }
         if (this.parameterFormat === "yaml") {
           try {
-            return { parameters: yaml.load(preprocessYaml(raw)) };
+            return { parameters: yaml2.load(preprocessYaml(raw)) };
           } catch (error) {
             return { parseError: error instanceof Error ? error.message : "Failed to parse YAML" };
           }
         }
         if (this.parameterFormat === "toml") {
           try {
-            return { parameters: (0, import_js_toml.load)(raw) };
+            return { parameters: (0, import_js_toml.load)(preprocessTomlHeredoc(raw)) };
           } catch (error) {
             return { parseError: error instanceof Error ? error.message : "Failed to parse TOML" };
           }
@@ -1463,10 +2066,10 @@ var init_parser = __esm({
           return { parameters: JSON.parse(raw) };
         } catch {
           try {
-            return { parameters: (0, import_js_toml.load)(raw) };
+            return { parameters: (0, import_js_toml.load)(preprocessTomlHeredoc(raw)) };
           } catch {
             try {
-              return { parameters: yaml.load(preprocessYaml(raw)) };
+              return { parameters: yaml2.load(preprocessYaml(raw)) };
             } catch (error) {
               return {
                 parseError: error instanceof Error ? error.message : "Failed to parse as JSON, TOML, or YAML"
@@ -1988,9 +2591,12 @@ var Agent;
 var init_agent = __esm({
   "src/agent/agent.ts"() {
     "use strict";
+    init_constants();
     init_messages();
     init_model_shortcuts();
+    init_output_viewer();
     init_logger();
+    init_gadget_output_store();
     init_agent_internal_key();
     init_conversation_manager();
     init_event_handlers();
@@ -2015,6 +2621,10 @@ var init_agent = __esm({
       defaultGadgetTimeoutMs;
       defaultMaxTokens;
       userPromptProvided;
+      // Gadget output limiting
+      outputStore;
+      outputLimitEnabled;
+      outputLimitCharLimit;
       /**
        * Creates a new Agent instance.
        * @internal This constructor is private. Use LLMist.createAgent() or AgentBuilder instead.
@@ -2030,7 +2640,6 @@ var init_agent = __esm({
         this.maxIterations = options.maxIterations ?? 10;
         this.temperature = options.temperature;
         this.logger = options.logger ?? createLogger({ name: "llmist:agent" });
-        this.hooks = options.hooks ?? {};
         this.registry = options.registry;
         this.parameterFormat = options.parameterFormat ?? "json";
         this.gadgetStartPrefix = options.gadgetStartPrefix;
@@ -2041,6 +2650,16 @@ var init_agent = __esm({
         this.shouldContinueAfterError = options.shouldContinueAfterError;
         this.defaultGadgetTimeoutMs = options.defaultGadgetTimeoutMs;
         this.defaultMaxTokens = this.resolveMaxTokensFromCatalog(options.model);
+        this.outputLimitEnabled = options.gadgetOutputLimit ?? DEFAULT_GADGET_OUTPUT_LIMIT;
+        this.outputStore = new GadgetOutputStore();
+        const limitPercent = options.gadgetOutputLimitPercent ?? DEFAULT_GADGET_OUTPUT_LIMIT_PERCENT;
+        const limits = this.client.modelRegistry.getModelLimits(this.model);
+        const contextWindow = limits?.contextWindow ?? FALLBACK_CONTEXT_WINDOW;
+        this.outputLimitCharLimit = Math.floor(contextWindow * (limitPercent / 100) * CHARS_PER_TOKEN);
+        if (this.outputLimitEnabled) {
+          this.registry.register("GadgetOutputViewer", createGadgetOutputViewer(this.outputStore));
+        }
+        this.hooks = this.mergeOutputLimiterHook(options.hooks);
         const baseBuilder = new LLMMessageBuilder(options.promptConfig);
         if (options.systemPrompt) {
           baseBuilder.addSystem(options.systemPrompt);
@@ -2345,6 +2964,43 @@ var init_agent = __esm({
         }
         return this.client.modelRegistry.getModelLimits(unprefixedModelId)?.maxOutputTokens;
       }
+      /**
+       * Merge the output limiter interceptor into user-provided hooks.
+       * The limiter runs first, then chains to any user interceptor.
+       */
+      mergeOutputLimiterHook(userHooks) {
+        if (!this.outputLimitEnabled) {
+          return userHooks ?? {};
+        }
+        const limiterInterceptor = (result, ctx) => {
+          if (ctx.gadgetName === "GadgetOutputViewer") {
+            return result;
+          }
+          if (result.length > this.outputLimitCharLimit) {
+            const id = this.outputStore.store(ctx.gadgetName, result);
+            const lines = result.split("\n").length;
+            const bytes = new TextEncoder().encode(result).length;
+            this.logger.info("Gadget output exceeded limit, stored for browsing", {
+              gadgetName: ctx.gadgetName,
+              outputId: id,
+              bytes,
+              lines,
+              charLimit: this.outputLimitCharLimit
+            });
+            return `[Gadget "${ctx.gadgetName}" returned too much data: ${bytes.toLocaleString()} bytes, ${lines.toLocaleString()} lines. Use GadgetOutputViewer with id "${id}" to read it]`;
+          }
+          return result;
+        };
+        const userInterceptor = userHooks?.interceptors?.interceptGadgetResult;
+        const chainedInterceptor = userInterceptor ? (result, ctx) => userInterceptor(limiterInterceptor(result, ctx), ctx) : limiterInterceptor;
+        return {
+          ...userHooks,
+          interceptors: {
+            ...userHooks?.interceptors,
+            interceptGadgetResult: chainedInterceptor
+          }
+        };
+      }
       /**
        * Run agent with named event handlers (syntactic sugar).
        *
@@ -4086,6 +4742,8 @@ var init_builder = __esm({
       stopOnGadgetError;
       shouldContinueAfterError;
       defaultGadgetTimeoutMs;
+      gadgetOutputLimit;
+      gadgetOutputLimitPercent;
       constructor(client) {
         this.client = client;
       }
@@ -4418,6 +5076,45 @@ var init_builder = __esm({
         this.defaultGadgetTimeoutMs = timeoutMs;
         return this;
       }
+      /**
+       * Enable or disable gadget output limiting.
+       *
+       * When enabled, gadget outputs exceeding the configured limit are stored
+       * and can be browsed using the GadgetOutputViewer gadget.
+       *
+       * @param enabled - Whether to enable output limiting (default: true)
+       * @returns This builder for chaining
+       *
+       * @example
+       * ```typescript
+       * .withGadgetOutputLimit(false) // Disable output limiting
+       * ```
+       */
+      withGadgetOutputLimit(enabled) {
+        this.gadgetOutputLimit = enabled;
+        return this;
+      }
+      /**
+       * Set the maximum gadget output as a percentage of the model's context window.
+       *
+       * Outputs exceeding this limit are stored for later browsing with GadgetOutputViewer.
+       *
+       * @param percent - Percentage of context window (1-100, default: 15)
+       * @returns This builder for chaining
+       * @throws {Error} If percent is not between 1 and 100
+       *
+       * @example
+       * ```typescript
+       * .withGadgetOutputLimitPercent(25) // 25% of context window
+       * ```
+       */
+      withGadgetOutputLimitPercent(percent) {
+        if (percent < 1 || percent > 100) {
+          throw new Error("Output limit percent must be between 1 and 100");
+        }
+        this.gadgetOutputLimitPercent = percent;
+        return this;
+      }
       /**
        * Build and create the agent with the given user prompt.
        * Returns the Agent instance ready to run.
@@ -4462,7 +5159,9 @@ var init_builder = __esm({
           textOnlyHandler: this.textOnlyHandler,
           stopOnGadgetError: this.stopOnGadgetError,
           shouldContinueAfterError: this.shouldContinueAfterError,
-          defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs
+          defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
+          gadgetOutputLimit: this.gadgetOutputLimit,
+          gadgetOutputLimitPercent: this.gadgetOutputLimitPercent
         };
         return new Agent(AGENT_INTERNAL_KEY, options);
       }
@@ -4561,7 +5260,9 @@ var init_builder = __esm({
           textOnlyHandler: this.textOnlyHandler,
           stopOnGadgetError: this.stopOnGadgetError,
           shouldContinueAfterError: this.shouldContinueAfterError,
-          defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs
+          defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
+          gadgetOutputLimit: this.gadgetOutputLimit,
+          gadgetOutputLimitPercent: this.gadgetOutputLimitPercent
         };
         return new Agent(AGENT_INTERNAL_KEY, options);
       }
@@ -4580,6 +5281,7 @@ __export(index_exports, {
   DEFAULT_PROMPTS: () => DEFAULT_PROMPTS,
   Gadget: () => Gadget,
   GadgetExecutor: () => GadgetExecutor,
+  GadgetOutputStore: () => GadgetOutputStore,
   GadgetRegistry: () => GadgetRegistry,
   GeminiGenerativeProvider: () => GeminiGenerativeProvider,
   HookPresets: () => HookPresets,
@@ -4600,6 +5302,7 @@ __export(index_exports, {
   complete: () => complete,
   createAnthropicProviderFromEnv: () => createAnthropicProviderFromEnv,
   createGadget: () => createGadget,
+  createGadgetOutputViewer: () => createGadgetOutputViewer,
   createGeminiProviderFromEnv: () => createGeminiProviderFromEnv,
   createLogger: () => createLogger,
   createMockAdapter: () => createMockAdapter,
@@ -4621,10 +5324,10 @@ __export(index_exports, {
   stream: () => stream,
   validateAndApplyDefaults: () => validateAndApplyDefaults,
   validateGadgetParams: () => validateGadgetParams,
-  z: () => import_zod.z
+  z: () => import_zod2.z
 });
 module.exports = __toCommonJS(index_exports);
-var import_zod = require("zod");
+var import_zod2 = require("zod");
 init_builder();
 init_event_handlers();
 
@@ -5356,6 +6059,7 @@ var HookPresets = class _HookPresets {
 // src/agent/index.ts
 init_conversation_manager();
 init_stream_processor();
+init_gadget_output_store();
 
 // src/index.ts
 init_client();
@@ -5365,278 +6069,16 @@ init_model_shortcuts();
 init_options();
 init_prompt_config();
 init_quick_methods();
-
-// src/gadgets/gadget.ts
-var yaml2 = __toESM(require("js-yaml"), 1);
-
-// src/gadgets/schema-to-json.ts
-var z2 = __toESM(require("zod"), 1);
-init_logger();
-function schemaToJSONSchema(schema, options) {
-  const jsonSchema = z2.toJSONSchema(schema, options ?? { target: "draft-7" });
-  const mismatches = detectDescriptionMismatch(schema, jsonSchema);
-  if (mismatches.length > 0) {
-    defaultLogger.warn(
-      `Zod instance mismatch detected: ${mismatches.length} description(s) lost. For best results, use: import { z } from "llmist"`
-    );
-    return mergeDescriptions(schema, jsonSchema);
-  }
-  return jsonSchema;
-}
-function detectDescriptionMismatch(schema, jsonSchema) {
-  const mismatches = [];
-  function checkSchema(zodSchema, json, path) {
-    if (!zodSchema || typeof zodSchema !== "object") return;
-    const def = zodSchema._def;
-    const jsonObj = json;
-    if (def?.description && !jsonObj?.description) {
-      mismatches.push(path || "root");
-    }
-    if (def?.typeName === "ZodObject" && def?.shape) {
-      const shape = typeof def.shape === "function" ? def.shape() : def.shape;
-      for (const [key, fieldSchema] of Object.entries(shape)) {
-        const properties = jsonObj?.properties;
-        const jsonProp = properties?.[key];
-        checkSchema(fieldSchema, jsonProp, path ? `${path}.${key}` : key);
-      }
-    }
-    if (def?.typeName === "ZodArray" && def?.type) {
-      checkSchema(def.type, jsonObj?.items, path ? `${path}[]` : "[]");
-    }
-    if ((def?.typeName === "ZodOptional" || def?.typeName === "ZodNullable") && def?.innerType) {
-      checkSchema(def.innerType, json, path);
-    }
-    if (def?.typeName === "ZodDefault" && def?.innerType) {
-      checkSchema(def.innerType, json, path);
-    }
-  }
-  checkSchema(schema, jsonSchema, "");
-  return mismatches;
-}
-function mergeDescriptions(schema, jsonSchema) {
-  function merge(zodSchema, json) {
-    if (!json || typeof json !== "object") return json;
-    const def = zodSchema._def;
-    const jsonObj = json;
-    const merged = { ...jsonObj };
-    if (def?.description && !jsonObj.description) {
-      merged.description = def.description;
-    }
-    if (def?.typeName === "ZodObject" && def?.shape && jsonObj.properties) {
-      const shape = typeof def.shape === "function" ? def.shape() : def.shape;
-      const properties = jsonObj.properties;
-      merged.properties = { ...properties };
-      for (const [key, fieldSchema] of Object.entries(shape)) {
-        if (properties[key]) {
-          merged.properties[key] = merge(fieldSchema, properties[key]);
-        }
-      }
-    }
-    if (def?.typeName === "ZodArray" && def?.type && jsonObj.items) {
-      merged.items = merge(def.type, jsonObj.items);
-    }
-    if ((def?.typeName === "ZodOptional" || def?.typeName === "ZodNullable") && def?.innerType) {
-      return merge(def.innerType, json);
-    }
-    if (def?.typeName === "ZodDefault" && def?.innerType) {
-      return merge(def.innerType, json);
-    }
-    return merged;
-  }
-  return merge(schema, jsonSchema);
-}
-
-// src/gadgets/gadget.ts
-init_schema_validator();
-function formatYamlValue(value, indent = "") {
-  if (typeof value === "string") {
-    const lines = value.split("\n");
-    if (lines.length === 1 && !value.includes(":") && !value.startsWith("-")) {
-      return value;
-    }
-    const indentedLines = lines.map((line) => `${indent}  ${line}`).join("\n");
-    return `|
-${indentedLines}`;
-  }
-  if (typeof value === "number" || typeof value === "boolean") {
-    return String(value);
-  }
-  if (value === null || value === void 0) {
-    return "null";
-  }
-  if (Array.isArray(value)) {
-    if (value.length === 0) return "[]";
-    const items = value.map((item) => `${indent}- ${formatYamlValue(item, indent + "  ")}`);
-    return "\n" + items.join("\n");
-  }
-  if (typeof value === "object") {
-    const entries = Object.entries(value);
-    if (entries.length === 0) return "{}";
-    const lines = entries.map(([k, v]) => {
-      const formattedValue = formatYamlValue(v, indent + "  ");
-      if (formattedValue.startsWith("\n") || formattedValue.startsWith("|")) {
-        return `${indent}${k}: ${formattedValue}`;
-      }
-      return `${indent}${k}: ${formattedValue}`;
-    });
-    return "\n" + lines.join("\n");
-  }
-  return yaml2.dump(value).trimEnd();
-}
-function formatParamsAsYaml(params) {
-  const lines = [];
-  for (const [key, value] of Object.entries(params)) {
-    const formattedValue = formatYamlValue(value, "");
-    if (formattedValue.startsWith("\n")) {
-      lines.push(`${key}:${formattedValue}`);
-    } else {
-      lines.push(`${key}: ${formattedValue}`);
-    }
-  }
-  return lines.join("\n");
-}
-function formatTomlValue(value) {
-  if (typeof value === "string") {
-    if (value.includes("\n")) {
-      return `"""
-${value}
-"""`;
-    }
-    return JSON.stringify(value);
-  }
-  if (typeof value === "number" || typeof value === "boolean") {
-    return String(value);
-  }
-  if (value === null || value === void 0) {
-    return '""';
-  }
-  if (Array.isArray(value)) {
-    return JSON.stringify(value);
-  }
-  if (typeof value === "object") {
-    return JSON.stringify(value);
-  }
-  return JSON.stringify(value);
-}
-function formatParamsAsToml(params) {
-  const lines = [];
-  for (const [key, value] of Object.entries(params)) {
-    lines.push(`${key} = ${formatTomlValue(value)}`);
-  }
-  return lines.join("\n");
-}
-var BaseGadget = class {
-  /**
-   * The name of the gadget. Used for identification when LLM calls it.
-   * If not provided, defaults to the class name.
-   */
-  name;
-  /**
-   * Optional Zod schema describing the expected input payload. When provided,
-   * it will be validated before execution and transformed into a JSON Schema
-   * representation that is surfaced to the LLM as part of the instructions.
-   */
-  parameterSchema;
-  /**
-   * Optional timeout in milliseconds for gadget execution.
-   * If execution exceeds this timeout, a TimeoutException will be thrown.
-   * If not set, the global defaultGadgetTimeoutMs from runtime options will be used.
-   * Set to 0 or undefined to disable timeout for this gadget.
-   */
-  timeoutMs;
-  /**
-   * Optional usage examples to help LLMs understand proper invocation.
-   * Examples are rendered in getInstruction() alongside the schema.
-   *
-   * Note: Uses broader `unknown` type to allow typed examples from subclasses
-   * while maintaining runtime compatibility.
-   */
-  examples;
-  /**
-   * Auto-generated instruction text for the LLM.
-   * Combines name, description, and parameter schema into a formatted instruction.
-   * @deprecated Use getInstruction(format) instead for format-specific schemas
-   */
-  get instruction() {
-    return this.getInstruction("yaml");
-  }
-  /**
-   * Generate instruction text for the LLM with format-specific schema.
-   * Combines name, description, and parameter schema into a formatted instruction.
-   *
-   * @param format - Format for the schema representation ('json' | 'yaml' | 'toml' | 'auto')
-   * @returns Formatted instruction string
-   */
-  getInstruction(format = "json") {
-    const parts = [];
-    parts.push(this.description);
-    if (this.parameterSchema) {
-      const gadgetName = this.name ?? this.constructor.name;
-      validateGadgetSchema(this.parameterSchema, gadgetName);
-      const jsonSchema = schemaToJSONSchema(this.parameterSchema, {
-        target: "draft-7"
-      });
-      if (format === "json" || format === "auto") {
-        parts.push("\n\nInput Schema (JSON):");
-        parts.push(JSON.stringify(jsonSchema, null, 2));
-      } else if (format === "toml") {
-        parts.push("\n\nInput Schema (TOML):");
-        parts.push(JSON.stringify(jsonSchema, null, 2));
-      } else {
-        const yamlSchema = yaml2.dump(jsonSchema).trimEnd();
-        parts.push("\n\nInput Schema (YAML):");
-        parts.push(yamlSchema);
-      }
-    }
-    if (this.examples && this.examples.length > 0) {
-      parts.push("\n\nExamples:");
-      this.examples.forEach((example, index) => {
-        if (index > 0) {
-          parts.push("");
-        }
-        if (example.comment) {
-          parts.push(`# ${example.comment}`);
-        }
-        parts.push("Input:");
-        if (format === "json" || format === "auto") {
-          parts.push(JSON.stringify(example.params, null, 2));
-        } else if (format === "toml") {
-          parts.push(formatParamsAsToml(example.params));
-        } else {
-          parts.push(formatParamsAsYaml(example.params));
-        }
-        if (example.output !== void 0) {
-          parts.push("Output:");
-          parts.push(example.output);
-        }
-      });
-    }
-    return parts.join("\n");
-  }
-};
-
-// src/gadgets/create-gadget.ts
-function createGadget(config) {
-  class DynamicGadget extends BaseGadget {
-    name = config.name;
-    description = config.description;
-    parameterSchema = config.schema;
-    timeoutMs = config.timeoutMs;
-    examples = config.examples;
-    execute(params) {
-      return config.execute(params);
-    }
-  }
-  return new DynamicGadget();
-}
-
-// src/index.ts
+init_create_gadget();
+init_output_viewer();
 init_exceptions();
 init_executor();
+init_gadget();
 init_parser();
 init_registry();
 
 // src/gadgets/typed-gadget.ts
+init_gadget();
 function Gadget(config) {
   class GadgetBase extends BaseGadget {
     description = config.description;
@@ -6356,6 +6798,9 @@ function createMockClient(options) {
     defaultProvider: "mock"
   });
 }
+
+// src/testing/mock-gadget.ts
+init_gadget();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgentBuilder,
@@ -6366,6 +6811,7 @@ function createMockClient(options) {
   DEFAULT_PROMPTS,
   Gadget,
   GadgetExecutor,
+  GadgetOutputStore,
   GadgetRegistry,
   GeminiGenerativeProvider,
   HookPresets,
@@ -6386,6 +6832,7 @@ function createMockClient(options) {
   complete,
   createAnthropicProviderFromEnv,
   createGadget,
+  createGadgetOutputViewer,
   createGeminiProviderFromEnv,
   createLogger,
   createMockAdapter,