llmist 17.2.1 → 17.5.0

package/dist/index.js

@@ -1,29 +1,87 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-};
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+import {
+  AbortException,
+  AbstractGadget,
+  BudgetPricingUnavailableError,
+  CHARS_PER_TOKEN,
+  DEFAULT_GADGET_OUTPUT_LIMIT,
+  DEFAULT_GADGET_OUTPUT_LIMIT_PERCENT,
+  DEFAULT_HINTS,
+  DEFAULT_MCP_COMMAND_ALLOWLIST,
+  DEFAULT_PROMPTS,
+  FALLBACK_CONTEXT_WINDOW,
+  GADGET_ARG_PREFIX,
+  GADGET_END_PREFIX,
+  GADGET_START_PREFIX,
+  HumanInputRequiredException,
+  JsonSchemaConversionError,
+  LLMMessageBuilder,
+  McpClient,
+  McpConnectError,
+  McpError,
+  McpLifecycle,
+  McpToolCallError,
+  McpUntrustedCommandError,
+  TaskCompletionSignal,
+  TimeoutException,
+  __esm,
+  __export,
+  __require,
+  __toCommonJS,
+  assertCommandAllowed,
+  audioFromBase64,
+  audioFromBuffer,
+  createGadget,
+  createLogger,
+  createMediaOutput,
+  defaultLogger,
+  detectAudioMimeType,
+  detectImageMimeType,
+  extractMessageText,
+  gadgetError,
+  gadgetSuccess,
+  getErrorMessage,
+  imageFromBase64,
+  imageFromBuffer,
+  imageFromUrl,
+  init_allowlist,
+  init_client,
+  init_constants,
+  init_create_gadget,
+  init_errors,
+  init_exceptions,
+  init_gadget,
+  init_helpers,
+  init_input_content,
+  init_json_schema_to_zod,
+  init_lifecycle,
+  init_logger,
+  init_messages,
+  init_prompt_config,
+  init_schema_to_json,
+  init_schema_validator,
+  init_tool_adapter,
+  isAudioPart,
+  isDataUrl,
+  isImagePart,
+  isTextPart,
+  jsonSchemaToZod,
+  mcpToolToGadget,
+  normalizeMessageContent,
+  parseDataUrl,
+  resolveHintTemplate,
+  resolvePromptTemplate,
+  resolveRulesTemplate,
+  resultWithAudio,
+  resultWithFile,
+  resultWithImage,
+  resultWithImages,
+  resultWithMedia,
+  schemaToJSONSchema,
+  text,
+  toBase64,
+  validateGadgetSchema,
+  withErrorHandling
+} from "./chunk-HM7PUGPA.js";
 
 // src/core/execution-tree-aggregator.ts
 var ExecutionTreeAggregator;
@@ -803,679 +861,6 @@ var init_execution_tree = __esm({
   }
 });
 
-// src/core/constants.ts
-var GADGET_START_PREFIX, GADGET_END_PREFIX, GADGET_ARG_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";
-    GADGET_ARG_PREFIX = "!!!ARG:";
-    DEFAULT_GADGET_OUTPUT_LIMIT = true;
-    DEFAULT_GADGET_OUTPUT_LIMIT_PERCENT = 15;
-    CHARS_PER_TOKEN = 2;
-    FALLBACK_CONTEXT_WINDOW = 128e3;
-  }
-});
-
-// src/core/input-content.ts
-function isTextPart(part) {
-  return part.type === "text";
-}
-function isImagePart(part) {
-  return part.type === "image";
-}
-function isAudioPart(part) {
-  return part.type === "audio";
-}
-function text(content) {
-  return { type: "text", text: content };
-}
-function imageFromBase64(data, mediaType) {
-  return {
-    type: "image",
-    source: { type: "base64", mediaType, data }
-  };
-}
-function imageFromUrl(url) {
-  return {
-    type: "image",
-    source: { type: "url", url }
-  };
-}
-function detectImageMimeType(data) {
-  const bytes = data instanceof Buffer ? data : Buffer.from(data);
-  for (const { bytes: magic, mimeType } of IMAGE_MAGIC_BYTES) {
-    if (bytes.length >= magic.length) {
-      let matches = true;
-      for (let i = 0; i < magic.length; i++) {
-        if (bytes[i] !== magic[i]) {
-          matches = false;
-          break;
-        }
-      }
-      if (matches) {
-        if (mimeType === "image/webp") {
-          if (bytes.length >= 12) {
-            const webpMarker = bytes[8] === 87 && bytes[9] === 69 && bytes[10] === 66 && bytes[11] === 80;
-            if (!webpMarker) continue;
-          }
-        }
-        return mimeType;
-      }
-    }
-  }
-  return null;
-}
-function detectAudioMimeType(data) {
-  const bytes = data instanceof Buffer ? data : Buffer.from(data);
-  for (const { bytes: magic, mimeType } of AUDIO_MAGIC_BYTES) {
-    if (bytes.length >= magic.length) {
-      let matches = true;
-      for (let i = 0; i < magic.length; i++) {
-        if (bytes[i] !== magic[i]) {
-          matches = false;
-          break;
-        }
-      }
-      if (matches) {
-        if (mimeType === "audio/wav") {
-          if (bytes.length >= 12) {
-            const waveMarker = bytes[8] === 87 && bytes[9] === 65 && bytes[10] === 86 && bytes[11] === 69;
-            if (!waveMarker) continue;
-          }
-        }
-        return mimeType;
-      }
-    }
-  }
-  return null;
-}
-function toBase64(data) {
-  if (typeof data === "string") {
-    return data;
-  }
-  return Buffer.from(data).toString("base64");
-}
-function imageFromBuffer(buffer, mediaType) {
-  const detectedType = mediaType ?? detectImageMimeType(buffer);
-  if (!detectedType) {
-    throw new Error(
-      "Could not detect image MIME type. Please provide the mediaType parameter explicitly."
-    );
-  }
-  return {
-    type: "image",
-    source: {
-      type: "base64",
-      mediaType: detectedType,
-      data: toBase64(buffer)
-    }
-  };
-}
-function audioFromBase64(data, mediaType) {
-  return {
-    type: "audio",
-    source: { type: "base64", mediaType, data }
-  };
-}
-function audioFromBuffer(buffer, mediaType) {
-  const detectedType = mediaType ?? detectAudioMimeType(buffer);
-  if (!detectedType) {
-    throw new Error(
-      "Could not detect audio MIME type. Please provide the mediaType parameter explicitly."
-    );
-  }
-  return {
-    type: "audio",
-    source: {
-      type: "base64",
-      mediaType: detectedType,
-      data: toBase64(buffer)
-    }
-  };
-}
-function isDataUrl(input) {
-  return input.startsWith("data:");
-}
-function parseDataUrl(url) {
-  const match = url.match(/^data:([^;]+);base64,(.+)$/);
-  if (!match) return null;
-  return { mimeType: match[1], data: match[2] };
-}
-var IMAGE_MAGIC_BYTES, AUDIO_MAGIC_BYTES;
-var init_input_content = __esm({
-  "src/core/input-content.ts"() {
-    "use strict";
-    IMAGE_MAGIC_BYTES = [
-      { bytes: [255, 216, 255], mimeType: "image/jpeg" },
-      { bytes: [137, 80, 78, 71], mimeType: "image/png" },
-      { bytes: [71, 73, 70, 56], mimeType: "image/gif" },
-      // WebP starts with RIFF....WEBP
-      { bytes: [82, 73, 70, 70], mimeType: "image/webp" }
-    ];
-    AUDIO_MAGIC_BYTES = [
-      // MP3 frame sync
-      { bytes: [255, 251], mimeType: "audio/mp3" },
-      { bytes: [255, 250], mimeType: "audio/mp3" },
-      // ID3 tag (MP3)
-      { bytes: [73, 68, 51], mimeType: "audio/mp3" },
-      // OGG
-      { bytes: [79, 103, 103, 83], mimeType: "audio/ogg" },
-      // WAV (RIFF)
-      { bytes: [82, 73, 70, 70], mimeType: "audio/wav" },
-      // WebM
-      { bytes: [26, 69, 223, 163], mimeType: "audio/webm" },
-      // FLAC (fLaC)
-      { bytes: [102, 76, 97, 67], mimeType: "audio/flac" }
-    ];
-  }
-});
-
-// src/core/prompt-config.ts
-function resolvePromptTemplate(template, defaultValue, context) {
-  const resolved = template ?? defaultValue;
-  return typeof resolved === "function" ? resolved(context) : resolved;
-}
-function resolveRulesTemplate(rules, context) {
-  const resolved = rules ?? DEFAULT_PROMPTS.rules;
-  if (Array.isArray(resolved)) {
-    return resolved;
-  }
-  if (typeof resolved === "function") {
-    const result = resolved(context);
-    return Array.isArray(result) ? result : [result];
-  }
-  return [resolved];
-}
-function resolveHintTemplate(template, defaultValue, context) {
-  const resolved = template ?? defaultValue;
-  if (typeof resolved === "function") {
-    return resolved(context);
-  }
-  return resolved.replace(/\{iteration\}/g, String(context.iteration)).replace(/\{maxIterations\}/g, String(context.maxIterations)).replace(/\{remaining\}/g, String(context.remaining));
-}
-var DEFAULT_HINTS, DEFAULT_PROMPTS;
-var init_prompt_config = __esm({
-  "src/core/prompt-config.ts"() {
-    "use strict";
-    DEFAULT_HINTS = {
-      parallelGadgetsHint: "Tip: You can call multiple gadgets in a single response for efficiency.",
-      iterationProgressHint: "[Iteration {iteration}/{maxIterations}] Plan your actions accordingly."
-    };
-    DEFAULT_PROMPTS = {
-      mainInstruction: [
-        "\u26A0\uFE0F CRITICAL: RESPOND ONLY WITH GADGET INVOCATIONS",
-        "DO NOT use function calling or tool calling",
-        "You must output the exact text markers shown below in plain text.",
-        "EACH MARKER MUST START WITH A NEWLINE."
-      ].join("\n"),
-      criticalUsage: "INVOKE gadgets using the markers - do not describe what you want to do.",
-      formatDescription: (ctx) => `Parameters using ${ctx.argPrefix}name markers (value on next line(s), no escaping needed)`,
-      rules: () => [
-        "Output ONLY plain text with the exact markers - never use function/tool calling",
-        "You can invoke multiple gadgets in a single response",
-        "Gadgets without dependencies execute immediately (in parallel if multiple)",
-        "Use :invocation_id:dep1,dep2 syntax when a gadget needs results from prior gadgets",
-        "If any dependency fails, dependent gadgets are automatically skipped"
-      ],
-      customExamples: null
-    };
-  }
-});
-
-// src/core/messages.ts
-function normalizeMessageContent(content) {
-  if (typeof content === "string") {
-    return [{ type: "text", text: content }];
-  }
-  return content;
-}
-function extractMessageText(content) {
-  if (typeof content === "string") {
-    return content;
-  }
-  return content.filter((part) => part.type === "text").map((part) => part.text).join("");
-}
-var LLMMessageBuilder;
-var init_messages = __esm({
-  "src/core/messages.ts"() {
-    "use strict";
-    init_constants();
-    init_input_content();
-    init_prompt_config();
-    LLMMessageBuilder = class {
-      messages = [];
-      startPrefix = GADGET_START_PREFIX;
-      endPrefix = GADGET_END_PREFIX;
-      argPrefix = GADGET_ARG_PREFIX;
-      promptConfig;
-      constructor(promptConfig) {
-        this.promptConfig = promptConfig ?? {};
-      }
-      /**
-       * Set custom prefixes for gadget markers.
-       * Used to configure history builder to match system prompt markers.
-       */
-      withPrefixes(startPrefix, endPrefix, argPrefix) {
-        this.startPrefix = startPrefix;
-        this.endPrefix = endPrefix;
-        if (argPrefix) {
-          this.argPrefix = argPrefix;
-        }
-        return this;
-      }
-      addSystem(content, metadata) {
-        this.messages.push({ role: "system", content, metadata });
-        return this;
-      }
-      addGadgets(gadgets, options) {
-        if (options?.startPrefix) {
-          this.startPrefix = options.startPrefix;
-        }
-        if (options?.endPrefix) {
-          this.endPrefix = options.endPrefix;
-        }
-        if (options?.argPrefix) {
-          this.argPrefix = options.argPrefix;
-        }
-        const context = {
-          startPrefix: this.startPrefix,
-          endPrefix: this.endPrefix,
-          argPrefix: this.argPrefix,
-          gadgetCount: gadgets.length,
-          gadgetNames: gadgets.map((g) => g.name ?? g.constructor.name)
-        };
-        const parts = [];
-        const mainInstruction = resolvePromptTemplate(
-          this.promptConfig.mainInstruction,
-          DEFAULT_PROMPTS.mainInstruction,
-          context
-        );
-        parts.push(mainInstruction);
-        parts.push(this.buildGadgetsSection(gadgets));
-        parts.push(this.buildUsageSection(context));
-        this.messages.push({ role: "system", content: parts.join("") });
-        return this;
-      }
-      buildGadgetsSection(gadgets) {
-        const parts = [];
-        parts.push("\n\nAVAILABLE GADGETS");
-        parts.push("\n=================\n");
-        for (const gadget of gadgets) {
-          const gadgetName = gadget.name ?? gadget.constructor.name;
-          const instruction = gadget.getInstruction({
-            argPrefix: this.argPrefix,
-            startPrefix: this.startPrefix,
-            endPrefix: this.endPrefix
-          });
-          const schemaMarker = "\n\nInput Schema (BLOCK):";
-          const schemaIndex = instruction.indexOf(schemaMarker);
-          const description = (schemaIndex !== -1 ? instruction.substring(0, schemaIndex) : instruction).trim();
-          const schema = schemaIndex !== -1 ? instruction.substring(schemaIndex + schemaMarker.length).trim() : "";
-          parts.push(`
-GADGET: ${gadgetName}`);
-          parts.push(`
-${description}`);
-          if (schema) {
-            parts.push(`
-
-PARAMETERS (BLOCK):
-${schema}`);
-          }
-          parts.push("\n\n---");
-        }
-        return parts.join("");
-      }
-      buildUsageSection(context) {
-        const parts = [];
-        const formatDescription = resolvePromptTemplate(
-          this.promptConfig.formatDescription,
-          DEFAULT_PROMPTS.formatDescription,
-          context
-        );
-        parts.push("\n\nHOW TO INVOKE GADGETS");
-        parts.push("\n=====================\n");
-        const criticalUsage = resolvePromptTemplate(
-          this.promptConfig.criticalUsage,
-          DEFAULT_PROMPTS.criticalUsage,
-          context
-        );
-        parts.push(`
-CRITICAL: ${criticalUsage}
-`);
-        parts.push("\nFORMAT:");
-        parts.push(`
-  1. Start marker: ${this.startPrefix}gadget_name`);
-        parts.push(`
-     With ID: ${this.startPrefix}gadget_name:my_id`);
-        parts.push(`
-     With dependencies: ${this.startPrefix}gadget_name:my_id:dep1,dep2`);
-        parts.push(`
-  2. ${formatDescription}`);
-        parts.push(`
-  3. End marker: ${this.endPrefix}`);
-        parts.push(this.buildExamplesSection(context));
-        parts.push(this.buildRulesSection(context));
-        parts.push("\n");
-        return parts.join("");
-      }
-      buildExamplesSection(context) {
-        if (this.promptConfig.customExamples) {
-          return this.promptConfig.customExamples(context);
-        }
-        const parts = [];
-        const singleExample = `${this.startPrefix}translate
-${this.argPrefix}from
-English
-${this.argPrefix}to
-Polish
-${this.argPrefix}content
-Paris is the capital of France: a beautiful city.
-${this.endPrefix}`;
-        parts.push(`
-
-EXAMPLE (Single Gadget):
-
-${singleExample}`);
-        const multipleExample = `${this.startPrefix}translate
-${this.argPrefix}from
-English
-${this.argPrefix}to
-Polish
-${this.argPrefix}content
-Paris is the capital of France: a beautiful city.
-${this.endPrefix}
-${this.startPrefix}analyze
-${this.argPrefix}type
-economic_analysis
-${this.argPrefix}matter
-Polish Economy
-${this.argPrefix}question
-Analyze the following:
-- Polish arms exports 2025
-- Economic implications
-${this.endPrefix}`;
-        parts.push(`
-
-EXAMPLE (Multiple Gadgets):
-
-${multipleExample}`);
-        const dependencyExample = `${this.startPrefix}fetch_data:fetch_1
-${this.argPrefix}url
-https://api.example.com/users
-${this.endPrefix}
-${this.startPrefix}fetch_data:fetch_2
-${this.argPrefix}url
-https://api.example.com/orders
-${this.endPrefix}
-${this.startPrefix}merge_data:merge_1:fetch_1,fetch_2
-${this.argPrefix}format
-json
-${this.endPrefix}`;
-        parts.push(`
-
-EXAMPLE (With Dependencies):
-merge_1 waits for fetch_1 AND fetch_2 to complete.
-If either fails, merge_1 is automatically skipped.
-
-${dependencyExample}`);
-        parts.push(`
-
-BLOCK FORMAT SYNTAX:
-Block format uses ${this.argPrefix}name markers. Values are captured verbatim until the next marker.
-
-${this.argPrefix}filename
-calculator.ts
-${this.argPrefix}code
-class Calculator {
-  private history: string[] = [];
-
-  add(a: number, b: number): number {
-    const result = a + b;
-    this.history.push(\`\${a} + \${b} = \${result}\`);
-    return result;
-  }
-}
-
-BLOCK FORMAT RULES:
-- Each parameter starts with ${this.argPrefix}parameterName on its own line
-- The value starts on the NEXT line after the marker
-- Value ends when the next ${this.argPrefix} or ${this.endPrefix} appears
-- NO escaping needed - write values exactly as they should appear
-- Perfect for code, JSON, markdown, or any content with special characters
-
-NESTED OBJECTS (use / separator):
-${this.argPrefix}config/timeout
-30
-${this.argPrefix}config/retries
-3
-Produces: { "config": { "timeout": "30", "retries": "3" } }
-
-ARRAYS (use numeric indices):
-${this.argPrefix}items/0
-first
-${this.argPrefix}items/1
-second
-Produces: { "items": ["first", "second"] }`);
-        return parts.join("");
-      }
-      buildRulesSection(context) {
-        const parts = [];
-        parts.push("\n\nRULES:");
-        const rules = resolveRulesTemplate(this.promptConfig.rules, context);
-        for (const rule of rules) {
-          parts.push(`
-  - ${rule}`);
-        }
-        return parts.join("");
-      }
-      /**
-       * Add a user message.
-       * Content can be a string (text only) or an array of content parts (multimodal).
-       *
-       * @param content - Message content
-       * @param metadata - Optional metadata
-       *
-       * @example
-       * ```typescript
-       * // Text only
-       * builder.addUser("Hello!");
-       *
-       * // Multimodal
-       * builder.addUser([
-       *   text("What's in this image?"),
-       *   imageFromBuffer(imageData),
-       * ]);
-       * ```
-       */
-      addUser(content, metadata) {
-        this.messages.push({ role: "user", content, metadata });
-        return this;
-      }
-      addAssistant(content, metadata) {
-        this.messages.push({ role: "assistant", content, metadata });
-        return this;
-      }
-      /**
-       * Add a user message with an image attachment.
-       *
-       * @param textContent - Text prompt
-       * @param imageData - Image data (Buffer, Uint8Array, or base64 string)
-       * @param mimeType - Optional MIME type (auto-detected if not provided)
-       *
-       * @example
-       * ```typescript
-       * builder.addUserWithImage(
-       *   "What's in this image?",
-       *   await fs.readFile("photo.jpg"),
-       *   "image/jpeg"  // Optional - auto-detected
-       * );
-       * ```
-       */
-      addUserWithImage(textContent, imageData, mimeType) {
-        const imageBuffer = typeof imageData === "string" ? Buffer.from(imageData, "base64") : imageData;
-        const detectedMime = mimeType ?? detectImageMimeType(imageBuffer);
-        if (!detectedMime) {
-          throw new Error(
-            "Could not detect image MIME type. Please provide the mimeType parameter explicitly."
-          );
-        }
-        const content = [
-          text(textContent),
-          {
-            type: "image",
-            source: {
-              type: "base64",
-              mediaType: detectedMime,
-              data: toBase64(imageBuffer)
-            }
-          }
-        ];
-        this.messages.push({ role: "user", content });
-        return this;
-      }
-      /**
-       * Add a user message with an image URL (OpenAI only).
-       *
-       * @param textContent - Text prompt
-       * @param imageUrl - URL to the image
-       *
-       * @example
-       * ```typescript
-       * builder.addUserWithImageUrl(
-       *   "What's in this image?",
-       *   "https://example.com/image.jpg"
-       * );
-       * ```
-       */
-      addUserWithImageUrl(textContent, imageUrl) {
-        const content = [text(textContent), imageFromUrl(imageUrl)];
-        this.messages.push({ role: "user", content });
-        return this;
-      }
-      /**
-       * Add a user message with an audio attachment (Gemini only).
-       *
-       * @param textContent - Text prompt
-       * @param audioData - Audio data (Buffer, Uint8Array, or base64 string)
-       * @param mimeType - Optional MIME type (auto-detected if not provided)
-       *
-       * @example
-       * ```typescript
-       * builder.addUserWithAudio(
-       *   "Transcribe this audio",
-       *   await fs.readFile("recording.mp3"),
-       *   "audio/mp3"  // Optional - auto-detected
-       * );
-       * ```
-       */
-      addUserWithAudio(textContent, audioData, mimeType) {
-        const audioBuffer = typeof audioData === "string" ? Buffer.from(audioData, "base64") : audioData;
-        const content = [text(textContent), audioFromBuffer(audioBuffer, mimeType)];
-        this.messages.push({ role: "user", content });
-        return this;
-      }
-      /**
-       * Add a user message with multiple content parts.
-       * Provides full flexibility for complex multimodal messages.
-       *
-       * @param parts - Array of content parts
-       *
-       * @example
-       * ```typescript
-       * builder.addUserMultimodal([
-       *   text("Compare these images:"),
-       *   imageFromBuffer(image1),
-       *   imageFromBuffer(image2),
-       * ]);
-       * ```
-       */
-      addUserMultimodal(parts) {
-        this.messages.push({ role: "user", content: parts });
-        return this;
-      }
-      /**
-       * Record a gadget execution result in the message history.
-       * Creates an assistant message with the gadget invocation and a user message with the result.
-       *
-       * The invocationId is shown to the LLM so it can reference previous calls when building dependencies.
-       *
-       * @param gadget - Name of the gadget that was executed
-       * @param parameters - Parameters that were passed to the gadget
-       * @param result - Text result from the gadget execution
-       * @param invocationId - Invocation ID (shown to LLM so it can reference for dependencies)
-       * @param media - Optional media outputs from the gadget
-       * @param mediaIds - Optional IDs for the media outputs
-       * @param storedMedia - Optional stored media info including file paths
-       */
-      addGadgetCallResult(gadget, parameters, result, invocationId, media, mediaIds, storedMedia) {
-        const paramStr = this.formatBlockParameters(parameters, "");
-        this.messages.push({
-          role: "assistant",
-          content: `${this.startPrefix}${gadget}:${invocationId}
-${paramStr}
-${this.endPrefix}`
-        });
-        if (media && media.length > 0 && mediaIds && mediaIds.length > 0) {
-          const idRefs = media.map((m, i) => {
-            const path3 = storedMedia?.[i]?.path;
-            const pathInfo = path3 ? ` \u2192 saved to: ${path3}` : "";
-            return `[Media: ${mediaIds[i]} (${m.kind})${pathInfo}]`;
-          }).join("\n");
-          const textWithIds = `Result (${invocationId}): ${result}
-${idRefs}`;
-          const parts = [text(textWithIds)];
-          for (const item of media) {
-            if (item.kind === "image") {
-              parts.push(imageFromBase64(item.data, item.mimeType));
-            } else if (item.kind === "audio") {
-              parts.push(audioFromBase64(item.data, item.mimeType));
-            }
-          }
-          this.messages.push({ role: "user", content: parts });
-        } else {
-          this.messages.push({
-            role: "user",
-            content: `Result (${invocationId}): ${result}`
-          });
-        }
-        return this;
-      }
-      /**
-       * Format parameters as Block format with JSON Pointer paths.
-       * Uses the configured argPrefix for consistency with system prompt.
-       */
-      formatBlockParameters(params, prefix) {
-        const lines = [];
-        for (const [key, value] of Object.entries(params)) {
-          const fullPath = prefix ? `${prefix}/${key}` : key;
-          if (Array.isArray(value)) {
-            value.forEach((item, index) => {
-              const itemPath = `${fullPath}/${index}`;
-              if (typeof item === "object" && item !== null) {
-                lines.push(this.formatBlockParameters(item, itemPath));
-              } else {
-                lines.push(`${this.argPrefix}${itemPath}`);
-                lines.push(String(item));
-              }
-            });
-          } else if (typeof value === "object" && value !== null) {
-            lines.push(this.formatBlockParameters(value, fullPath));
-          } else {
-            lines.push(`${this.argPrefix}${fullPath}`);
-            lines.push(String(value));
-          }
-        }
-        return lines.join("\n");
-      }
-      build() {
-        return [...this.messages];
-      }
-    };
-  }
-});
-
 // src/core/model-shortcuts.ts
 function isKnownModelPattern(model) {
   const normalized = model.toLowerCase();
@@ -2178,56 +1563,6 @@ var init_retry = __esm({
   }
 });
 
-// src/gadgets/exceptions.ts
-var TaskCompletionSignal, HumanInputRequiredException, TimeoutException, AbortException, BudgetPricingUnavailableError;
-var init_exceptions = __esm({
-  "src/gadgets/exceptions.ts"() {
-    "use strict";
-    TaskCompletionSignal = class extends Error {
-      constructor(message) {
-        super(message ?? "Agent loop terminated by gadget");
-        this.name = "TaskCompletionSignal";
-      }
-    };
-    HumanInputRequiredException = class extends Error {
-      question;
-      constructor(question) {
-        super(`Human input required: ${question}`);
-        this.name = "HumanInputRequiredException";
-        this.question = question;
-      }
-    };
-    TimeoutException = class extends Error {
-      timeoutMs;
-      gadgetName;
-      constructor(gadgetName, timeoutMs) {
-        super(`Gadget '${gadgetName}' execution exceeded timeout of ${timeoutMs}ms`);
-        this.name = "TimeoutException";
-        this.gadgetName = gadgetName;
-        this.timeoutMs = timeoutMs;
-      }
-    };
-    AbortException = class extends Error {
-      constructor(message) {
-        super(message || "Gadget execution was aborted");
-        this.name = "AbortException";
-      }
-    };
-    BudgetPricingUnavailableError = class extends Error {
-      model;
-      budget;
-      constructor(model, budget) {
-        super(
-          `Budget of $${budget.toFixed(2)} was set but model "${model}" has no valid pricing information in the model registry. Either register pricing for this model via client.modelRegistry.registerModel() or remove the budget constraint.`
-        );
-        this.name = "BudgetPricingUnavailableError";
-        this.model = model;
-        this.budget = budget;
-      }
-    };
-  }
-});
-
 // src/gadgets/media-store.ts
 import { randomBytes } from "crypto";
 import { mkdir, rm, writeFile } from "fs/promises";
@@ -2404,151 +1739,31 @@ var init_media_store = __esm({
        * Check if a media ID exists.
        */
       has(id) {
-        return this.items.has(id);
-      }
-      /**
-       * Clear in-memory store without deleting files.
-       * Resets the counter but leaves files on disk.
-       */
-      clear() {
-        this.items.clear();
-        this.counter = 0;
-      }
-      /**
-       * Delete all stored files and clear memory.
-       * Removes the entire session directory.
-       */
-      async cleanup() {
-        if (this.initialized) {
-          try {
-            await rm(this.outputDir, { recursive: true, force: true });
-          } catch {
-          }
-          this.initialized = false;
-        }
-        this.clear();
-      }
-    };
-  }
-});
-
-// src/logging/logger.ts
-import { createWriteStream, mkdirSync } from "fs";
-import { dirname } from "path";
-import { Logger } from "tslog";
-function parseLogLevel(value) {
-  if (!value) {
-    return void 0;
-  }
-  const normalized = value.trim().toLowerCase();
-  if (normalized === "") {
-    return void 0;
-  }
-  const numericLevel = Number(normalized);
-  if (Number.isFinite(numericLevel)) {
-    return Math.max(0, Math.min(6, Math.floor(numericLevel)));
-  }
-  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 stripAnsi(str) {
-  return str.replace(/\x1b\[[0-9;]*m/g, "");
-}
-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;
-  const envLogTee = parseEnvBoolean(process.env.LLMIST_LOG_TEE);
-  const teeToConsole = options.teeToConsole ?? envLogTee ?? false;
-  if (envLogFile && (!logFileInitialized || sharedLogFilePath !== envLogFile)) {
-    try {
-      if (sharedLogFileStream) {
-        sharedLogFileStream.end();
-        sharedLogFileStream = void 0;
-      }
-      mkdirSync(dirname(envLogFile), { recursive: true });
-      const flags = logReset ? "w" : "a";
-      sharedLogFileStream = createWriteStream(envLogFile, { flags });
-      sharedLogFilePath = envLogFile;
-      logFileInitialized = true;
-      writeErrorCount = 0;
-      writeErrorReported = false;
-      sharedLogFileStream.on("error", (error) => {
-        writeErrorCount++;
-        if (!writeErrorReported) {
-          console.error(`[llmist] Log file write error: ${error.message}`);
-          writeErrorReported = true;
-        }
-        if (writeErrorCount >= MAX_WRITE_ERRORS_BEFORE_DISABLE) {
-          console.error(
-            `[llmist] Too many log file errors (${writeErrorCount}), disabling file logging`
-          );
-          sharedLogFileStream?.end();
-          sharedLogFileStream = void 0;
-        }
-      });
-    } catch (error) {
-      console.error("Failed to initialize LLMIST_LOG_FILE output:", error);
-    }
-  }
-  const useFileLogging = Boolean(sharedLogFileStream);
-  const logger2 = new Logger({
-    name,
-    minLevel,
-    type: useFileLogging ? "pretty" : defaultType,
-    // Hide log position for file logging and non-pretty types
-    hideLogPositionForProduction: useFileLogging || defaultType !== "pretty",
-    prettyLogTemplate: LOG_TEMPLATE,
-    // Use overwrite to redirect tslog's formatted output to file instead of console
-    overwrite: useFileLogging ? {
-      transportFormatted: (logMetaMarkup, logArgs, _logErrors) => {
-        const args = logArgs.map(
-          (arg) => typeof arg === "string" ? arg : JSON.stringify(arg)
-        );
-        if (sharedLogFileStream) {
-          const meta = stripAnsi(logMetaMarkup);
-          const fileArgs = args.map((a) => stripAnsi(a));
-          sharedLogFileStream.write(`${meta}${fileArgs.join(" ")}
-`);
-        }
-        if (teeToConsole) {
-          process.stdout.write(`${logMetaMarkup}${args.join(" ")}
-`);
+        return this.items.has(id);
+      }
+      /**
+       * Clear in-memory store without deleting files.
+       * Resets the counter but leaves files on disk.
+       */
+      clear() {
+        this.items.clear();
+        this.counter = 0;
+      }
+      /**
+       * Delete all stored files and clear memory.
+       * Removes the entire session directory.
+       */
+      async cleanup() {
+        if (this.initialized) {
+          try {
+            await rm(this.outputDir, { recursive: true, force: true });
+          } catch {
+          }
+          this.initialized = false;
         }
+        this.clear();
       }
-    } : void 0
-  });
-  return logger2;
-}
-var LEVEL_NAME_TO_ID, sharedLogFilePath, sharedLogFileStream, logFileInitialized, writeErrorCount, writeErrorReported, MAX_WRITE_ERRORS_BEFORE_DISABLE, LOG_TEMPLATE, defaultLogger;
-var init_logger = __esm({
-  "src/logging/logger.ts"() {
-    "use strict";
-    LEVEL_NAME_TO_ID = {
-      silly: 0,
-      trace: 1,
-      debug: 2,
-      info: 3,
-      warn: 4,
-      error: 5,
-      fatal: 6
     };
-    logFileInitialized = false;
-    writeErrorCount = 0;
-    writeErrorReported = false;
-    MAX_WRITE_ERRORS_BEFORE_DISABLE = 5;
-    LOG_TEMPLATE = "{{yyyy}}-{{mm}}-{{dd}} {{hh}}:{{MM}}:{{ss}}:{{ms}}	{{logLevelName}}	[{{name}}]	";
-    defaultLogger = createLogger();
   }
 });
 
@@ -3066,6 +2281,16 @@ var init_conversation_manager = __esm({
       getBaseMessages() {
         return [...this.baseMessages, ...this.initialMessages];
       }
+      /**
+       * Replace the base (system + gadget catalog) messages.
+       *
+       * Used when async setup (e.g. MCP server connect-and-list) discovers
+       * additional gadgets after the agent was constructed. Conversation history
+       * is preserved; only the leading system block is swapped.
+       */
+      replaceBaseMessages(newBase) {
+        this.baseMessages = newBase;
+      }
       replaceHistory(newHistory) {
         this.historyBuilder = new LLMMessageBuilder();
         if (this.startPrefix && this.endPrefix) {
@@ -4028,632 +3253,52 @@ var init_llm_call_lifecycle = __esm({
        * to preserve the original Agent behavior: the `afterLLMCall` controller was never
        * invoked for interrupted calls in the pre-extraction code. Skipping it here prevents
        * side effects (e.g., `append_messages` mutating conversation state) during cleanup
-       * of an already-exited run loop.
-       */
-      async processAfterLLMCallController(iteration, llmOptions, result, gadgetCallCount) {
-        let finalMessage = result.finalMessage;
-        if (!this.hooks.controllers?.afterLLMCall || result.finishReason === "interrupted") {
-          return finalMessage;
-        }
-        const context = {
-          iteration,
-          maxIterations: this.maxIterations,
-          budget: this.budget,
-          totalCost: this.tree.getTotalCost(),
-          options: llmOptions,
-          finishReason: result.finishReason,
-          usage: result.usage,
-          finalMessage: result.finalMessage,
-          gadgetCallCount,
-          logger: this.logger
-        };
-        const action = await this.hooks.controllers.afterLLMCall(context);
-        validateAfterLLMCallAction(action);
-        if (action.action === "modify_and_continue" || action.action === "append_and_modify") {
-          finalMessage = action.modifiedMessage;
-        }
-        if (action.action === "append_messages" || action.action === "append_and_modify") {
-          for (const msg of action.messages) {
-            if (msg.role === "user") {
-              this.conversation.addUserMessage(msg.content);
-            } else if (msg.role === "assistant") {
-              this.conversation.addAssistantMessage(extractMessageText(msg.content));
-            } else if (msg.role === "system") {
-              this.conversation.addUserMessage(`[System] ${extractMessageText(msg.content)}`);
-            }
-          }
-        }
-        return finalMessage;
-      }
-    };
-  }
-});
-
-// src/gadgets/schema-to-json.ts
-import * as z from "zod";
-function schemaToJSONSchema(schema, options) {
-  const jsonSchema = z.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, path3) {
-    if (!zodSchema || typeof zodSchema !== "object") return;
-    const def = zodSchema._def;
-    const jsonObj = json;
-    if (def?.description && !jsonObj?.description) {
-      mismatches.push(path3 || "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, path3 ? `${path3}.${key}` : key);
-      }
-    }
-    if (def?.typeName === "ZodArray" && def?.type) {
-      checkSchema(def.type, jsonObj?.items, path3 ? `${path3}[]` : "[]");
-    }
-    if ((def?.typeName === "ZodOptional" || def?.typeName === "ZodNullable") && def?.innerType) {
-      checkSchema(def.innerType, json, path3);
-    }
-    if (def?.typeName === "ZodDefault" && def?.innerType) {
-      checkSchema(def.innerType, json, path3);
-    }
-  }
-  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 init_schema_to_json = __esm({
-  "src/gadgets/schema-to-json.ts"() {
-    "use strict";
-    init_logger();
-  }
-});
-
-// src/gadgets/schema-validator.ts
-import * as z2 from "zod";
-function validateGadgetSchema(schema, gadgetName) {
-  let jsonSchema;
-  try {
-    jsonSchema = z2.toJSONSchema(schema, { target: "draft-7" });
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `Gadget "${gadgetName}" has a schema that cannot be serialized to JSON Schema.
-This usually happens with unsupported patterns like:
-- z.record() - use z.object({}).passthrough() instead
-- Complex transforms or custom refinements
-- Circular references
-
-Original error: ${errorMessage}
-
-Only use schema patterns that Zod v4's native toJSONSchema() supports.`
-    );
-  }
-  const issues = findUnknownTypes(jsonSchema);
-  if (issues.length > 0) {
-    const fieldList = issues.join(", ");
-    throw new Error(
-      `Gadget "${gadgetName}" uses z.unknown() which produces incomplete schemas.
-Problematic fields: ${fieldList}
-
-z.unknown() doesn't generate type information in JSON Schema, making it unclear
-to the LLM what data structure to provide.
-
-Suggestions:
-- Use z.object({}).passthrough() for flexible objects
-- Use z.record(z.string()) for key-value objects with string values
-- Define specific structure if possible
-
-Example fixes:
-  // \u274C Bad
-  content: z.unknown()
-
-  // \u2705 Good
-  content: z.object({}).passthrough()   // for flexible objects
-  content: z.record(z.string())         // for key-value objects
-  content: z.array(z.string())          // for arrays of strings
-`
-    );
-  }
-}
-function findUnknownTypes(schema, path3 = []) {
-  const issues = [];
-  if (!schema || typeof schema !== "object") {
-    return issues;
-  }
-  if (schema.definitions) {
-    for (const defSchema of Object.values(schema.definitions)) {
-      issues.push(...findUnknownTypes(defSchema, []));
-    }
-  }
-  if (schema.properties) {
-    for (const [propName, propSchema] of Object.entries(schema.properties)) {
-      const propPath = [...path3, propName];
-      if (hasNoType(propSchema)) {
-        issues.push(propPath.join(".") || propName);
-      }
-      issues.push(...findUnknownTypes(propSchema, propPath));
-    }
-  }
-  if (schema.items) {
-    const itemPath = [...path3, "[]"];
-    if (hasNoType(schema.items)) {
-      issues.push(itemPath.join("."));
-    }
-    issues.push(...findUnknownTypes(schema.items, itemPath));
-  }
-  if (schema.anyOf) {
-    schema.anyOf.forEach((subSchema, index) => {
-      issues.push(...findUnknownTypes(subSchema, [...path3, `anyOf[${index}]`]));
-    });
-  }
-  if (schema.oneOf) {
-    schema.oneOf.forEach((subSchema, index) => {
-      issues.push(...findUnknownTypes(subSchema, [...path3, `oneOf[${index}]`]));
-    });
-  }
-  if (schema.allOf) {
-    schema.allOf.forEach((subSchema, index) => {
-      issues.push(...findUnknownTypes(subSchema, [...path3, `allOf[${index}]`]));
-    });
-  }
-  return issues;
-}
-function hasNoType(prop) {
-  if (!prop || typeof prop !== "object") {
-    return false;
-  }
-  const hasType = prop.type !== void 0;
-  const hasRef = prop.$ref !== void 0;
-  const hasUnion = prop.anyOf !== void 0 || prop.oneOf !== void 0 || prop.allOf !== void 0;
-  if (hasType || hasRef || hasUnion) {
-    return false;
-  }
-  const keys = Object.keys(prop);
-  const metadataKeys = ["description", "title", "default", "examples"];
-  const hasOnlyMetadata = keys.every((key) => metadataKeys.includes(key));
-  return hasOnlyMetadata || keys.length === 0;
-}
-var init_schema_validator = __esm({
-  "src/gadgets/schema-validator.ts"() {
-    "use strict";
-  }
-});
-
-// src/gadgets/gadget.ts
-function formatParamsForBlockExample(params, prefix = "", argPrefix = GADGET_ARG_PREFIX) {
-  const lines = [];
-  for (const [key, value] of Object.entries(params)) {
-    const fullPath = prefix ? `${prefix}/${key}` : key;
-    if (Array.isArray(value)) {
-      value.forEach((item, index) => {
-        const itemPath = `${fullPath}/${index}`;
-        if (typeof item === "object" && item !== null) {
-          lines.push(
-            formatParamsForBlockExample(item, itemPath, argPrefix)
-          );
-        } else {
-          lines.push(`${argPrefix}${itemPath}`);
-          lines.push(String(item));
-        }
-      });
-    } else if (typeof value === "object" && value !== null) {
-      lines.push(
-        formatParamsForBlockExample(value, fullPath, argPrefix)
-      );
-    } else {
-      lines.push(`${argPrefix}${fullPath}`);
-      lines.push(String(value));
-    }
-  }
-  return lines.join("\n");
-}
-function formatParamLine(key, propObj, isRequired, indent = "") {
-  const type = propObj.type;
-  const description = propObj.description;
-  const enumValues = propObj.enum;
-  let line = `${indent}- ${key}`;
-  if (type === "array") {
-    const items = propObj.items;
-    const itemType = items?.type || "any";
-    line += ` (array of ${itemType})`;
-  } else if (type === "object" && propObj.properties) {
-    line += " (object)";
-  } else {
-    line += ` (${type})`;
-  }
-  if (isRequired && indent !== "") {
-    line += " [required]";
-  }
-  if (description) {
-    line += `: ${description}`;
-  }
-  if (enumValues) {
-    line += ` - one of: ${enumValues.map((v) => `"${v}"`).join(", ")}`;
-  }
-  return line;
-}
-function formatSchemaAsPlainText(schema, indent = "", atRoot = true) {
-  const lines = [];
-  const properties = schema.properties || {};
-  const required = schema.required || [];
-  if (atRoot && indent === "") {
-    const requiredProps = [];
-    const optionalProps = [];
-    for (const [key, prop] of Object.entries(properties)) {
-      if (required.includes(key)) {
-        requiredProps.push([key, prop]);
-      } else {
-        optionalProps.push([key, prop]);
-      }
-    }
-    const reqCount = requiredProps.length;
-    const optCount = optionalProps.length;
-    if (reqCount > 0 || optCount > 0) {
-      const parts = [];
-      if (reqCount > 0) parts.push(`${reqCount} required`);
-      if (optCount > 0) parts.push(`${optCount} optional`);
-      lines.push(parts.join(", "));
-      lines.push("");
-    }
-    if (reqCount > 0) {
-      lines.push("REQUIRED Parameters:");
-      for (const [key, prop] of requiredProps) {
-        lines.push(formatParamLine(key, prop, true, ""));
-        const propObj = prop;
-        if (propObj.type === "object" && propObj.properties) {
-          lines.push(formatSchemaAsPlainText(propObj, "  ", false));
-        }
-      }
-    }
-    if (optCount > 0) {
-      if (reqCount > 0) lines.push("");
-      lines.push("OPTIONAL Parameters:");
-      for (const [key, prop] of optionalProps) {
-        lines.push(formatParamLine(key, prop, false, ""));
-        const propObj = prop;
-        if (propObj.type === "object" && propObj.properties) {
-          lines.push(formatSchemaAsPlainText(propObj, "  ", false));
-        }
-      }
-    }
-    return lines.join("\n");
-  }
-  for (const [key, prop] of Object.entries(properties)) {
-    const isRequired = required.includes(key);
-    lines.push(formatParamLine(key, prop, isRequired, indent));
-    const propObj = prop;
-    if (propObj.type === "object" && propObj.properties) {
-      lines.push(formatSchemaAsPlainText(propObj, indent + "  ", false));
-    }
-  }
-  return lines.join("\n");
-}
-var AbstractGadget;
-var init_gadget = __esm({
-  "src/gadgets/gadget.ts"() {
-    "use strict";
-    init_constants();
-    init_exceptions();
-    init_schema_to_json();
-    init_schema_validator();
-    AbstractGadget = 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;
-      /**
-       * Maximum number of concurrent executions allowed for this gadget.
-       * Use this to prevent race conditions in gadgets that modify shared state.
-       *
-       * - `1` = Sequential execution (only one instance runs at a time)
-       * - `0` or `undefined` = Unlimited concurrency (default)
-       * - `N > 1` = At most N concurrent executions
-       *
-       * This property sets a safety floor: external configuration (SubagentConfig)
-       * can only make concurrency MORE restrictive, never less. For example, if
-       * a gadget declares `maxConcurrent: 1`, external config cannot override it
-       * to allow parallel execution.
-       *
-       * @example
-       * ```typescript
-       * // File writer that must run sequentially to avoid race conditions
-       * class WriteFile extends Gadget({
-       *   description: 'Writes content to a file',
-       *   schema: z.object({ path: z.string(), content: z.string() }),
-       *   maxConcurrent: 1, // Sequential - prevents race conditions
-       * }) {
-       *   execute(params: this['params']) { ... }
-       * }
-       * ```
-       */
-      maxConcurrent;
-      /**
-       * If true, this gadget must execute alone — no other gadgets in the same
-       * LLM response can run in parallel. When an exclusive gadget arrives and
-       * other gadgets are already in-flight, it is deferred until they complete.
-       *
-       * Use for gadgets that terminate the agent loop (e.g., Finish), where
-       * sibling tool results must be visible to the LLM before the loop ends.
-       *
-       * This is a safety floor: external config cannot weaken it.
-       */
-      exclusive;
-      /**
-       * Throws an AbortException if the execution has been aborted.
-       *
-       * Call this at key checkpoints in long-running gadgets to allow early exit
-       * when the gadget has been cancelled (e.g., due to timeout). This enables
-       * resource cleanup and prevents unnecessary work after cancellation.
-       *
-       * @param ctx - The execution context containing the abort signal
-       * @throws AbortException if ctx.signal.aborted is true
-       *
-       * @example
-       * ```typescript
-       * class DataProcessor extends Gadget({
-       *   description: 'Processes data in multiple steps',
-       *   schema: z.object({ items: z.array(z.string()) }),
-       * }) {
-       *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
-       *     const results: string[] = [];
-       *
-       *     for (const item of params.items) {
-       *       // Check before each expensive operation
-       *       this.throwIfAborted(ctx);
-       *
-       *       results.push(await this.processItem(item));
-       *     }
-       *
-       *     return results.join(', ');
-       *   }
-       * }
-       * ```
-       */
-      throwIfAborted(ctx) {
-        if (ctx?.signal?.aborted) {
-          throw new AbortException();
-        }
-      }
-      /**
-       * Register a cleanup function to run when execution is aborted (timeout or cancellation).
-       * The cleanup function is called immediately if the signal is already aborted.
-       * Errors thrown by the cleanup function are silently ignored.
-       *
-       * Use this to clean up resources like browser instances, database connections,
-       * or child processes when the gadget is cancelled due to timeout.
-       *
-       * @param ctx - The execution context containing the abort signal
-       * @param cleanup - Function to run on abort (can be sync or async)
-       *
-       * @example
-       * ```typescript
-       * class BrowserGadget extends Gadget({
-       *   description: 'Fetches web page content',
-       *   schema: z.object({ url: z.string() }),
-       * }) {
-       *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
-       *     const browser = await chromium.launch();
-       *     this.onAbort(ctx, () => browser.close());
-       *
-       *     const page = await browser.newPage();
-       *     this.onAbort(ctx, () => page.close());
-       *
-       *     await page.goto(params.url);
-       *     const content = await page.content();
-       *
-       *     await browser.close();
-       *     return content;
-       *   }
-       * }
-       * ```
-       */
-      onAbort(ctx, cleanup) {
-        if (!ctx?.signal) return;
-        const safeCleanup = () => {
-          try {
-            const result = cleanup();
-            if (result && typeof result === "object" && "catch" in result) {
-              result.catch(() => {
-              });
-            }
-          } catch {
-          }
-        };
-        if (ctx.signal.aborted) {
-          safeCleanup();
-          return;
-        }
-        ctx.signal.addEventListener("abort", safeCleanup, { once: true });
-      }
-      /**
-       * Create an AbortController linked to the execution context's signal.
-       * When the parent signal aborts, the returned controller also aborts with the same reason.
-       *
-       * Useful for passing abort signals to child operations like fetch() while still
-       * being able to abort them independently if needed.
-       *
-       * @param ctx - The execution context containing the parent abort signal
-       * @returns A new AbortController linked to the parent signal
-       *
-       * @example
-       * ```typescript
-       * class FetchGadget extends Gadget({
-       *   description: 'Fetches data from URL',
-       *   schema: z.object({ url: z.string() }),
-       * }) {
-       *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
-       *     const controller = this.createLinkedAbortController(ctx);
-       *
-       *     // fetch() will automatically abort when parent times out
-       *     const response = await fetch(params.url, { signal: controller.signal });
-       *     return response.text();
-       *   }
-       * }
-       * ```
-       */
-      createLinkedAbortController(ctx) {
-        const controller = new AbortController();
-        if (ctx?.signal) {
-          if (ctx.signal.aborted) {
-            controller.abort(ctx.signal.reason);
-          } else {
-            ctx.signal.addEventListener(
-              "abort",
-              () => {
-                controller.abort(ctx.signal.reason);
-              },
-              { once: true }
-            );
-          }
-        }
-        return controller;
-      }
-      /**
-       * Generate instruction text for the LLM.
-       * Combines name, description, and parameter schema into a formatted instruction.
-       *
-       * @param optionsOrArgPrefix - Optional custom prefixes for examples, or just argPrefix string for backwards compatibility
-       * @returns Formatted instruction string
+       * of an already-exited run loop.
        */
-      getInstruction(optionsOrArgPrefix) {
-        const options = typeof optionsOrArgPrefix === "string" ? { argPrefix: optionsOrArgPrefix } : optionsOrArgPrefix;
-        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"
-          });
-          parts.push("\n\nParameters:");
-          parts.push(formatSchemaAsPlainText(jsonSchema));
-        }
-        if (this.examples && this.examples.length > 0) {
-          parts.push("\n\nExamples:");
-          const effectiveArgPrefix = options?.argPrefix ?? GADGET_ARG_PREFIX;
-          const effectiveStartPrefix = options?.startPrefix ?? GADGET_START_PREFIX;
-          const effectiveEndPrefix = options?.endPrefix ?? GADGET_END_PREFIX;
-          const gadgetName = this.name || this.constructor.name;
-          this.examples.forEach((example, index) => {
-            if (index > 0) {
-              parts.push("");
-              parts.push("---");
-              parts.push("");
-            }
-            if (example.comment) {
-              parts.push(`# ${example.comment}`);
-            }
-            parts.push(`${effectiveStartPrefix}${gadgetName}`);
-            parts.push(
-              formatParamsForBlockExample(
-                example.params,
-                "",
-                effectiveArgPrefix
-              )
-            );
-            parts.push(effectiveEndPrefix);
-            if (example.output !== void 0) {
-              parts.push("");
-              parts.push("Expected Output:");
-              parts.push(example.output);
+      async processAfterLLMCallController(iteration, llmOptions, result, gadgetCallCount) {
+        let finalMessage = result.finalMessage;
+        if (!this.hooks.controllers?.afterLLMCall || result.finishReason === "interrupted") {
+          return finalMessage;
+        }
+        const context = {
+          iteration,
+          maxIterations: this.maxIterations,
+          budget: this.budget,
+          totalCost: this.tree.getTotalCost(),
+          options: llmOptions,
+          finishReason: result.finishReason,
+          usage: result.usage,
+          finalMessage: result.finalMessage,
+          gadgetCallCount,
+          logger: this.logger
+        };
+        const action = await this.hooks.controllers.afterLLMCall(context);
+        validateAfterLLMCallAction(action);
+        if (action.action === "modify_and_continue" || action.action === "append_and_modify") {
+          finalMessage = action.modifiedMessage;
+        }
+        if (action.action === "append_messages" || action.action === "append_and_modify") {
+          for (const msg of action.messages) {
+            if (msg.role === "user") {
+              this.conversation.addUserMessage(msg.content);
+            } else if (msg.role === "assistant") {
+              this.conversation.addAssistantMessage(extractMessageText(msg.content));
+            } else if (msg.role === "system") {
+              this.conversation.addUserMessage(`[System] ${extractMessageText(msg.content)}`);
             }
-          });
+          }
         }
-        return parts.join("\n");
+        return finalMessage;
       }
     };
   }
 });
 
-// src/gadgets/create-gadget.ts
-function createGadget(config) {
-  class DynamicGadget extends AbstractGadget {
-    name = config.name;
-    description = config.description;
-    parameterSchema = config.schema;
-    timeoutMs = config.timeoutMs;
-    examples = config.examples;
-    maxConcurrent = config.maxConcurrent;
-    execute(params, ctx) {
-      return config.execute(params, ctx);
-    }
-  }
-  return new DynamicGadget();
-}
-var init_create_gadget = __esm({
-  "src/gadgets/create-gadget.ts"() {
-    "use strict";
-    init_gadget();
-  }
-});
-
 // src/gadgets/output-viewer.ts
-import { z as z3 } from "zod";
+import { z } from "zod";
+function pluralize(count, singular, plural = `${singular}s`) {
+  return count === 1 ? singular : plural;
+}
 function applyPattern(lines, pattern) {
   const regex = new RegExp(pattern.regex);
   if (!pattern.include) {
@@ -4678,80 +3323,169 @@ function applyPatterns(lines, patterns) {
   }
   return result;
 }
-function applyLineLimit(lines, limit) {
+function parseLimitWindow(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 (!Number.isNaN(n) && n > 0) {
+      return { kind: "first", count: n };
     }
   }
   if (trimmed.startsWith("-") && !trimmed.includes("-", 1)) {
     const n = parseInt(trimmed, 10);
-    if (!isNaN(n) && n < 0) {
-      return lines.slice(n);
+    if (!Number.isNaN(n) && n < 0) {
+      return { kind: "last", count: Math.abs(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);
+    if (!Number.isNaN(start) && !Number.isNaN(end) && start > 0 && end >= start) {
+      return { kind: "range", start, end };
+    }
+  }
+  return null;
+}
+function applyLineLimit(lines, limit) {
+  const window = parseLimitWindow(limit);
+  if (!window) return lines;
+  switch (window.kind) {
+    case "first":
+      return lines.slice(0, window.count);
+    case "last":
+      return lines.slice(-window.count);
+    case "range":
+      return lines.slice(window.start - 1, window.end);
+  }
+}
+function applyCharacterLimit(content, limit, maxOutputChars) {
+  const total = content.length;
+  if (total === 0) {
+    return { text: "", start: 0, end: 0, total: 0, truncatedBySize: false, hasMoreAfter: false };
+  }
+  let startIndex = 0;
+  let endExclusive = total;
+  const window = limit ? parseLimitWindow(limit) : null;
+  if (window) {
+    switch (window.kind) {
+      case "first":
+        endExclusive = Math.min(window.count, total);
+        break;
+      case "last":
+        startIndex = Math.max(0, total - window.count);
+        break;
+      case "range":
+        startIndex = Math.min(window.start - 1, total);
+        endExclusive = Math.min(window.end, total);
+        break;
+    }
+  }
+  let text3 = content.slice(startIndex, endExclusive);
+  let truncatedBySize = false;
+  if (text3.length > maxOutputChars) {
+    text3 = window?.kind === "last" ? text3.slice(-maxOutputChars) : text3.slice(0, maxOutputChars);
+    if (window?.kind === "last") {
+      startIndex = endExclusive - text3.length;
     }
+    truncatedBySize = true;
   }
-  return lines;
+  return {
+    text: text3,
+    start: text3.length === 0 ? 0 : startIndex + 1,
+    end: text3.length === 0 ? 0 : startIndex + text3.length,
+    total,
+    truncatedBySize,
+    hasMoreAfter: startIndex + text3.length < total
+  };
+}
+function buildCharacterRangeHint(start, total) {
+  if (total <= 0 || start > total) return null;
+  const end = Math.min(total, start + CHARACTER_HINT_WINDOW - 1);
+  return `${start}-${end}`;
+}
+function buildCharacterModeSuggestion(stored, opts = {}) {
+  const hint = buildCharacterRangeHint(opts.start ?? 1, stored.charCount);
+  const action = opts.removePatterns ? "Remove patterns and then try" : "Try";
+  const lineLabel = pluralize(stored.lineCount, "line");
+  return `This output is dense (${stored.lineCount.toLocaleString()} ${lineLabel}; longest line ${stored.maxLineLength.toLocaleString()} chars). ${action} mode: "character"` + (hint ? `, limit: "${hint}"` : "") + ".";
+}
+function shouldSuggestCharacterMode(stored, maxOutputChars = DEFAULT_MAX_OUTPUT_CHARS) {
+  return stored.lineCount <= 3 && (stored.maxLineLength > maxOutputChars || stored.maxLineLength >= DENSE_LINE_THRESHOLD);
 }
 function createGadgetOutputViewer(store, maxOutputChars = DEFAULT_MAX_OUTPUT_CHARS) {
   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: z3.object({
-      id: z3.string().describe("ID of the stored output (from the truncation message)"),
-      patterns: z3.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."
+    description: 'View stored output from gadgets that returned too much data. Use mode "line" for grep-like filtering and mode "character" for raw chunked browsing when the output is dense or effectively single-line. Patterns work only in line mode.',
+    schema: z.object({
+      id: z.string().describe("ID of the stored output (from the truncation message)"),
+      mode: z.enum(["line", "character"]).default("line").describe(
+        'Browse by "line" (supports patterns) or by "character" (raw windows for dense output).'
       ),
-      limit: z3.string().optional().describe(
-        "Line range to return after filtering. Formats: '100-' (first 100), '-25' (last 25), '50-100' (lines 50-100)"
+      patterns: z.array(patternSchema).optional().describe(
+        'Line-mode filter patterns applied in order (like piping through grep). Not supported in mode "character".'
+      ),
+      limit: z.string().optional().describe(
+        `Pagination window. In mode "line" it is a line range; in mode "character" it is a character range. Formats: "100-" (first 100), "-25" (last 25), "50-100" (inclusive range).`
       )
     }),
     examples: [
       {
         comment: "View first 50 lines of stored output",
-        params: { id: "Search_abc12345", limit: "50-" }
+        params: { id: "Search_abc12345", mode: "line", limit: "50-" }
       },
       {
         comment: "Filter for error lines with context",
         params: {
           id: "Search_abc12345",
+          mode: "line",
           patterns: [{ regex: "error|Error|ERROR", include: true, before: 2, after: 5 }]
         }
       },
       {
-        comment: "Exclude blank lines, then show first 100",
+        comment: "Exclude blank lines, then show first 100 lines",
         params: {
           id: "Search_abc12345",
+          mode: "line",
           patterns: [{ regex: "^\\s*$", include: false, before: 0, after: 0 }],
           limit: "100-"
         }
       },
       {
-        comment: "Chain filters: find TODOs, exclude tests, limit to 50 lines",
+        comment: "Browse the raw output by character window when line mode is too dense",
         params: {
           id: "Search_abc12345",
-          patterns: [
-            { regex: "TODO", include: true, before: 1, after: 1 },
-            { regex: "test|spec", include: false, before: 0, after: 0 }
-          ],
-          limit: "50-"
+          mode: "character",
+          limit: "1-2000"
         }
       }
     ],
-    execute: ({ id, patterns, limit }) => {
+    execute: ({ id, mode, patterns, limit }) => {
       const stored = store.get(id);
       if (!stored) {
         return `Error: No stored output with id "${id}". Available IDs: ${store.getIds().join(", ") || "(none)"}`;
       }
+      const suggestCharacterMode = shouldSuggestCharacterMode(stored, maxOutputChars);
+      if (mode === "character") {
+        if (patterns && patterns.length > 0) {
+          return 'Error: patterns are only supported in mode "line". Remove patterns or switch back to mode: "line".';
+        }
+        const window = applyCharacterLimit(stored.content, limit, maxOutputChars);
+        if (window.total === 0) {
+          return "[Mode: character | Output is empty]";
+        }
+        const header2 = [
+          `[Mode: character | Showing chars ${window.start.toLocaleString()}-${window.end.toLocaleString()} of ${window.total.toLocaleString()}${window.truncatedBySize ? " (truncated due to viewer size limit)" : ""}]`
+        ];
+        if (window.hasMoreAfter) {
+          const nextRange = buildCharacterRangeHint(window.end + 1, window.total);
+          if (nextRange) {
+            header2.push(`[Next chunk: mode: "character", limit: "${nextRange}"]`);
+          }
+        }
+        return `${header2.join("\n")}
+${window.text}`;
+      }
       let lines = stored.content.split("\n");
       if (patterns && patterns.length > 0) {
         lines = applyPatterns(
@@ -4767,54 +3501,76 @@ function createGadgetOutputViewer(store, maxOutputChars = DEFAULT_MAX_OUTPUT_CHA
       if (limit) {
         lines = applyLineLimit(lines, limit);
       }
-      let output = lines.join("\n");
       const totalLines = stored.lineCount;
+      const totalLineLabel = pluralize(totalLines, "line");
       const returnedLines = lines.length;
       if (returnedLines === 0) {
-        return `No lines matched the filters. Original output had ${totalLines} lines.`;
+        const base = `No lines matched the filters. Original output had ${totalLines.toLocaleString()} lines.`;
+        if (!suggestCharacterMode) return base;
+        return `${base} ${buildCharacterModeSuggestion(stored, {
+          removePatterns: Boolean(patterns && patterns.length > 0)
+        })}`;
       }
+      let output = lines.join("\n");
       let truncatedBySize = false;
       let linesIncluded = returnedLines;
+      let clippedFirstLine = false;
       if (output.length > maxOutputChars) {
         truncatedBySize = true;
         let truncatedOutput = "";
         linesIncluded = 0;
         for (const line of lines) {
-          if (truncatedOutput.length + line.length + 1 > maxOutputChars) break;
-          truncatedOutput += line + "\n";
+          const addition = linesIncluded === 0 ? line : `
+${line}`;
+          if (truncatedOutput.length + addition.length > maxOutputChars) break;
+          truncatedOutput += addition;
           linesIncluded++;
         }
+        if (linesIncluded === 0) {
+          clippedFirstLine = true;
+          linesIncluded = 1;
+          truncatedOutput = lines[0].slice(0, maxOutputChars);
+        }
         output = truncatedOutput;
       }
       let header;
-      if (truncatedBySize) {
+      if (clippedFirstLine) {
+        header = `[Mode: line | Showing 1 partial line of ${totalLines.toLocaleString()} ${totalLineLabel} (the selected line exceeds the viewer size limit)]
+`;
+      } else if (truncatedBySize) {
         const remainingLines = returnedLines - linesIncluded;
-        header = `[Showing ${linesIncluded} of ${totalLines} lines (truncated due to size limit)]
-[... ${remainingLines.toLocaleString()} more lines. Use limit parameter to paginate, e.g., limit: "${linesIncluded + 1}-${linesIncluded + 200}"]
+        header = `[Mode: line | Showing ${linesIncluded.toLocaleString()} of ${totalLines.toLocaleString()} ${totalLineLabel} (truncated due to size limit)]
+[... ${remainingLines.toLocaleString()} more ${pluralize(remainingLines, "line")}. Use limit parameter to paginate, e.g., limit: "${linesIncluded + 1}-${linesIncluded + 200}"]
 `;
       } else if (returnedLines < totalLines) {
-        header = `[Showing ${returnedLines} of ${totalLines} lines]
+        header = `[Mode: line | Showing ${returnedLines.toLocaleString()} of ${totalLines.toLocaleString()} ${totalLineLabel}]
 `;
       } else {
-        header = `[Showing all ${totalLines} lines]
+        header = `[Mode: line | Showing all ${totalLines.toLocaleString()} ${totalLineLabel}]
 `;
       }
-      return header + output;
+      const footer = suggestCharacterMode || clippedFirstLine ? `
+[Tip: ${buildCharacterModeSuggestion(stored, {
+        removePatterns: Boolean(patterns && patterns.length > 0)
+      })}]` : "";
+      return header + output + footer;
     }
   });
 }
-var patternSchema, DEFAULT_MAX_OUTPUT_CHARS;
+var DEFAULT_MAX_OUTPUT_CHARS, CHARACTER_HINT_WINDOW, DENSE_LINE_THRESHOLD, patternSchema;
 var init_output_viewer = __esm({
   "src/gadgets/output-viewer.ts"() {
     "use strict";
     init_create_gadget();
-    patternSchema = z3.object({
-      regex: z3.string().describe("Regular expression to match"),
-      include: z3.boolean().default(true).describe("true = keep matching lines, false = exclude matching lines"),
-      before: z3.number().int().min(0).default(0).describe("Context lines before each match (like grep -B)"),
-      after: z3.number().int().min(0).default(0).describe("Context lines after each match (like grep -A)")
-    });
     DEFAULT_MAX_OUTPUT_CHARS = 76800;
+    CHARACTER_HINT_WINDOW = 2e3;
+    DENSE_LINE_THRESHOLD = 4e3;
+    patternSchema = z.object({
+      regex: z.string().describe("Regular expression to match"),
+      include: z.boolean().default(true).describe("true = keep matching lines, false = exclude matching lines"),
+      before: z.number().int().min(0).default(0).describe("Context lines before each match (like grep -B)"),
+      after: z.number().int().min(0).default(0).describe("Context lines after each match (like grep -A)")
+    });
   }
 });
 
@@ -4836,12 +3592,15 @@ var init_gadget_output_store = __esm({
       store(gadgetName, content) {
         const id = this.generateId(gadgetName);
         const encoder = new TextEncoder();
+        const lines = content.split("\n");
         const stored = {
           id,
           gadgetName,
           content,
+          charCount: content.length,
           byteSize: encoder.encode(content).length,
-          lineCount: content.split("\n").length,
+          lineCount: lines.length,
+          maxLineLength: lines.reduce((max, line) => Math.max(max, line.length), 0),
           timestamp: /* @__PURE__ */ new Date()
         };
         this.outputs.set(id, stored);
@@ -4945,16 +3704,20 @@ var init_output_limit_manager = __esm({
           }
           if (result.length > this.charLimit) {
             const id = this.outputStore.store(ctx.gadgetName, result);
-            const lines = result.split("\n").length;
-            const bytes = new TextEncoder().encode(result).length;
+            const stored = this.outputStore.get(id);
+            const lines = stored?.lineCount ?? result.split("\n").length;
+            const bytes = stored?.byteSize ?? new TextEncoder().encode(result).length;
+            const denseSuggestion = stored && shouldSuggestCharacterMode(stored, this.charLimit) ? ` ${buildCharacterModeSuggestion(stored)}` : "";
             this.logger.info("Gadget output exceeded limit, stored for browsing", {
               gadgetName: ctx.gadgetName,
               outputId: id,
               bytes,
               lines,
+              charCount: stored?.charCount,
+              maxLineLength: stored?.maxLineLength,
               charLimit: this.charLimit
             });
-            return `[Gadget "${ctx.gadgetName}" returned too much data: ${bytes.toLocaleString()} bytes, ${lines.toLocaleString()} lines. Use GadgetOutputViewer with id "${id}" to read it]`;
+            return `[Gadget "${ctx.gadgetName}" returned too much data: ${bytes.toLocaleString()} bytes, ${lines.toLocaleString()} lines. Use GadgetOutputViewer with id "${id}" to read it.]` + denseSuggestion;
           }
           return result;
         };
@@ -5340,7 +4103,7 @@ var init_activation = __esm({
 });
 
 // src/skills/load-skill-gadget.ts
-import { z as z4 } from "zod";
+import { z as z2 } from "zod";
 function createLoadSkillGadget(registry) {
   const summaries = registry.getMetadataSummaries();
   const skillNames = registry.getModelInvocable().map((s) => s.name);
@@ -5352,9 +4115,9 @@ function createLoadSkillGadget(registry) {
   return createGadget({
     name: LOAD_SKILL_GADGET_NAME,
     description,
-    schema: z4.object({
-      skill: z4.enum(skillNames).describe("Name of the skill to load"),
-      arguments: z4.string().optional().describe("Arguments for the skill (e.g., a filename, issue number, or search query)")
+    schema: z2.object({
+      skill: z2.enum(skillNames).describe("Name of the skill to load"),
+      arguments: z2.string().optional().describe("Arguments for the skill (e.g., a filename, issue number, or search query)")
     }),
     execute: async ({ skill: skillName, arguments: args }) => {
       const skill = registry.get(skillName);
@@ -12789,7 +11552,7 @@ __export(client_exports, {
   LLMist: () => LLMist
 });
 var LLMist;
-var init_client = __esm({
+var init_client2 = __esm({
   "src/core/client.ts"() {
     "use strict";
     init_builder();
@@ -13103,6 +11866,7 @@ var init_builder = __esm({
       subagents;
       policies;
       skills;
+      mcp;
       constructor(client) {
         this.core = { client, initialMessages: [] };
         this.gadgets = { gadgets: [] };
@@ -13110,6 +11874,7 @@ var init_builder = __esm({
         this.subagents = {};
         this.policies = {};
         this.skills = { preActivated: [], skillDirs: [] };
+        this.mcp = { servers: [] };
       }
       /** Set the model to use. Supports aliases like "sonnet", "flash". */
       withModel(model) {
@@ -13156,6 +11921,45 @@ var init_builder = __esm({
         this.gadgets.gadgets.push(...gadgets);
         return this;
       }
+      /**
+       * Attach a Model Context Protocol (MCP) server.
+       *
+       * The agent connects to the server lazily at the start of `run()`,
+       * discovers its tools, and registers them as native gadgets so the LLM
+       * can call them through the standard streaming block format.
+       *
+       * Calling this multiple times accumulates servers. Tools across servers
+       * are merged into a single registry; in plan 1, conflicting tool names
+       * raise a registration warning. Plan 2 introduces deterministic
+       * `<server>__<tool>` prefixing for collisions.
+       *
+       * STDIO commands are gated by an allowlist (see allowlist.ts) — pass
+       * `trust: true` on the spec to opt in for non-allowlisted binaries.
+       *
+       * Zero-overhead invariant: if you never call this method, the MCP
+       * runtime module is never loaded. Agents without MCP pay nothing.
+       *
+       * @example
+       * ```typescript
+       * const agent = LLMist.createAgent()
+       *   .withModel("sonnet")
+       *   .withMcpServer({
+       *     name: "filesystem",
+       *     transport: "stdio",
+       *     command: "npx",
+       *     args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+       *   })
+       *   .ask("list files in /tmp");
+       * ```
+       */
+      withMcpServer(spec) {
+        this.mcp.servers.push(spec);
+        return this;
+      }
+      /** Inspect the configured MCP server specs. Useful for tests. */
+      getMcpServerSpecs() {
+        return this.mcp.servers;
+      }
       /** Add conversation history messages. */
       withHistory(messages) {
         this.core.initialMessages.push(...normalizeHistory(messages));
@@ -13417,7 +12221,7 @@ ${resolved}`);
       }
       buildAgentOptions(userPrompt) {
         if (!this.core.client) {
-          const { LLMist: LLMistClass } = (init_client(), __toCommonJS(client_exports));
+          const { LLMist: LLMistClass } = (init_client2(), __toCommonJS(client_exports));
           this.core.client = new LLMistClass();
         }
         const registry = GadgetRegistry.from(this.gadgets.gadgets);
@@ -13476,7 +12280,8 @@ ${preActivatedBlock}` : preActivatedBlock;
             parentObservers: this.subagents.parentObservers
           },
           sharedRateLimitTracker: this.subagents.sharedRateLimitTracker,
-          sharedRetryConfig: this.retry.sharedRetryConfig
+          sharedRetryConfig: this.retry.sharedRetryConfig,
+          mcpSpecs: this.mcp.servers.length > 0 ? [...this.mcp.servers] : void 0
         };
       }
       /** Create agent and start with a user prompt. */
@@ -14400,7 +13205,7 @@ var init_typed_gadget = __esm({
 
 // src/gadgets/executor.ts
 import equal from "fast-deep-equal";
-import { z as z5 } from "zod";
+import { z as z3 } from "zod";
 function getHostExportsInternal() {
   return {
     AgentBuilder,
@@ -14408,7 +13213,7 @@ function getHostExportsInternal() {
     createGadget,
     ExecutionTree,
     LLMist,
-    z: z5
+    z: z3
   };
 }
 var GadgetExecutor;
@@ -14417,7 +13222,7 @@ var init_executor = __esm({
     "use strict";
     init_builder();
     init_hook_utils();
-    init_client();
+    init_client2();
     init_constants();
     init_execution_tree();
     init_logger();
@@ -16548,6 +15353,10 @@ var init_agent = __esm({
       streamProcessorFactory;
       // LLM call lifecycle helper (encapsulates prepareLLMCall, completeLLMCall, notifyLLMError)
       llmCallLifecycle;
+      // MCP integration — populated only when mcpSpecs were provided.
+      mcpSpecs;
+      mcpLifecycle = null;
+      mcpDiscoveredPrompts = [];
       /**
        * Creates a new Agent instance.
        * @internal This constructor is private. Use LLMist.createAgent() or AgentBuilder instead.
@@ -16619,6 +15428,7 @@ var init_agent = __esm({
           );
         }
         this.signal = options.signal;
+        this.mcpSpecs = options.mcpSpecs ?? [];
         this.reasoning = options.reasoning;
         this.caching = options.caching;
         this.retryConfig = options.sharedRetryConfig ?? resolveRetryConfig(options.retryConfig);
@@ -16878,6 +15688,18 @@ var init_agent = __esm({
           );
         }
         const unsubscribeBridge = bridgeTreeToHooks(this.tree, this.hooks, this.logger);
+        if (this.mcpSpecs.length > 0) {
+          const { setupMcpServers } = await import("./runtime-GKQ6QIQP.js");
+          this.mcpLifecycle = await setupMcpServers({
+            specs: this.mcpSpecs,
+            registry: this.registry,
+            conversation: this.conversation,
+            prefixConfig: this.prefixConfig,
+            systemPrompt: this.conversation.getBaseMessages()[0]?.role === "system" ? this.conversation.getBaseMessages()[0].content : void 0,
+            logger: this.logger,
+            onPromptDiscovered: (skill) => this.mcpDiscoveredPrompts.push(skill)
+          });
+        }
         let currentIteration = 0;
         this.logger.info("Starting agent loop", {
           model: this.model,
@@ -17077,6 +15899,14 @@ var init_agent = __esm({
             }
           }
           unsubscribeBridge();
+          if (this.mcpLifecycle) {
+            try {
+              await this.mcpLifecycle.closeAll();
+            } catch (err) {
+              this.logger.debug("MCP lifecycle teardown error (suppressed):", err);
+            }
+            this.mcpLifecycle = null;
+          }
         }
       }
       /**
@@ -17268,7 +16098,7 @@ init_builder();
 init_event_handlers();
 init_file_logging();
 init_hook_presets();
-import { z as z6 } from "zod";
+import { z as z4 } from "zod";
 
 // src/agent/compaction/index.ts
 init_config();
@@ -17381,7 +16211,7 @@ function createHints(config) {
 init_stream_processor();
 
 // src/index.ts
-init_client();
+init_client2();
 init_constants();
 
 // src/core/errors.ts
@@ -17446,140 +16276,254 @@ init_create_gadget();
 init_exceptions();
 init_executor();
 init_gadget();
+init_helpers();
+init_output_viewer();
+init_parser2();
+init_registry();
+init_typed_gadget();
 
-// src/gadgets/helpers.ts
-init_input_content();
-function gadgetSuccess(data = {}) {
-  return JSON.stringify({ success: true, ...data });
-}
-function gadgetError(message, details) {
-  return JSON.stringify({ error: message, ...details });
-}
-function getErrorMessage(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-function withErrorHandling(execute) {
-  return async (params, ctx) => {
-    try {
-      return await execute(params, ctx);
-    } catch (error) {
-      return gadgetError(getErrorMessage(error));
-    }
-  };
-}
-function createMediaOutput(kind, data, mimeType, options) {
-  const buffer = data instanceof Buffer ? data : Buffer.from(data);
+// src/mcp/index.ts
+init_allowlist();
+init_client();
+init_errors();
+
+// src/mcp/gadget-exporter.ts
+init_schema_to_json();
+
+// src/gadgets/validation.ts
+function validateAndApplyDefaults(schema, params) {
+  const result = schema.safeParse(params);
+  if (result.success) {
+    return {
+      success: true,
+      data: result.data
+    };
+  }
+  const issues = result.error.issues.map((issue) => ({
+    path: issue.path.join(".") || "root",
+    message: issue.message
+  }));
+  const formattedError = `Invalid parameters: ${issues.map((i) => `${i.path}: ${i.message}`).join("; ")}`;
   return {
-    kind,
-    data: buffer.toString("base64"),
-    mimeType,
-    description: options?.description,
-    metadata: options?.metadata,
-    fileName: options?.fileName
+    success: false,
+    error: formattedError,
+    issues
   };
 }
-function resultWithMedia(result, media, cost) {
-  if (media.length === 0) {
-    throw new Error("resultWithMedia: media array cannot be empty");
+function validateGadgetParams(gadget, params) {
+  if (!gadget.parameterSchema) {
+    return {
+      success: true,
+      data: params
+    };
   }
-  return {
-    result,
-    media,
-    cost
-  };
+  return validateAndApplyDefaults(gadget.parameterSchema, params);
 }
-function resultWithImage(result, imageData, options) {
-  const buffer = imageData instanceof Buffer ? imageData : Buffer.from(imageData);
-  const mimeType = options?.mimeType ?? detectImageMimeType(buffer);
-  if (!mimeType) {
-    throw new Error(
-      "Could not detect image MIME type. Please provide mimeType explicitly in options."
-    );
+
+// src/mcp/gadget-exporter.ts
+function gadgetToMcpTool(gadget) {
+  const description = gadget.description && gadget.description.length > 0 ? gadget.description : `Native llmist gadget "${gadget.name ?? "unnamed"}"`;
+  let inputSchema;
+  if (gadget.parameterSchema) {
+    inputSchema = schemaToJSONSchema(gadget.parameterSchema);
+  } else {
+    inputSchema = { type: "object", properties: {} };
   }
   return {
-    result,
-    media: [
-      {
-        kind: "image",
-        data: buffer.toString("base64"),
-        mimeType,
-        description: options?.description,
-        metadata: options?.metadata,
-        fileName: options?.fileName
-      }
-    ],
-    cost: options?.cost
+    name: gadget.name ?? "unnamed-gadget",
+    description,
+    inputSchema
   };
 }
-function resultWithImages(result, images, cost) {
-  if (images.length === 0) {
-    throw new Error("resultWithImages: images array cannot be empty");
-  }
-  const media = images.map((img, index) => {
-    const buffer = img.data instanceof Buffer ? img.data : Buffer.from(img.data);
-    const mimeType = img.mimeType ?? detectImageMimeType(buffer);
-    if (!mimeType) {
-      throw new Error(
-        `Could not detect MIME type for image at index ${index}. Please provide mimeType explicitly.`
-      );
+function gadgetResultToMcpContent(ret) {
+  if (typeof ret === "string") {
+    return [{ type: "text", text: ret }];
+  }
+  if (ret && typeof ret === "object" && "result" in ret) {
+    const r = ret;
+    const blocks = [];
+    if (typeof r.result === "string") {
+      blocks.push({ type: "text", text: r.result });
+    } else {
+      blocks.push({ type: "text", text: JSON.stringify(r.result) });
+    }
+    if (r.media) {
+      for (const m of r.media) {
+        if (m.kind === "image" || m.kind === "audio") {
+          blocks.push({
+            type: m.kind,
+            data: m.data,
+            mimeType: m.mimeType
+          });
+        }
+      }
+    }
+    return blocks;
+  }
+  return [{ type: "text", text: JSON.stringify(ret) }];
+}
+async function runGadgetForMcp(gadget, rawParams) {
+  if (gadget.parameterSchema) {
+    const validation = validateAndApplyDefaults(
+      gadget.parameterSchema,
+      rawParams ?? {}
+    );
+    if (!validation.success) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Invalid arguments for gadget "${gadget.name}": ${validation.error}`
+          }
+        ]
+      };
     }
+    rawParams = validation.data;
+  }
+  try {
+    const result = await gadget.execute(rawParams);
     return {
-      kind: "image",
-      data: buffer.toString("base64"),
-      mimeType,
-      description: img.description,
-      metadata: img.metadata,
-      fileName: img.fileName
+      content: gadgetResultToMcpContent(result)
     };
-  });
-  return { result, media, cost };
+  } catch (err) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: "text",
+          text: `Gadget "${gadget.name}" failed: ${err.message}`
+        }
+      ]
+    };
+  }
 }
-function resultWithAudio(result, audioData, options) {
-  const buffer = audioData instanceof Buffer ? audioData : Buffer.from(audioData);
-  const mimeType = options?.mimeType ?? detectAudioMimeType(buffer);
-  if (!mimeType) {
-    throw new Error(
-      "Could not detect audio MIME type. Please provide mimeType explicitly in options."
-    );
+
+// src/mcp/index.ts
+init_json_schema_to_zod();
+init_lifecycle();
+
+// src/mcp/skill-exporter.ts
+function skillToMcpPrompt(skill) {
+  const description = skill.description && skill.description.length > 0 ? skill.description : `Native llmist skill "${skill.name}"`;
+  const args = [];
+  if (skill.metadata.argumentHint) {
+    args.push({
+      name: "arguments",
+      description: skill.metadata.argumentHint,
+      required: false
+    });
   }
-  const metadata = options?.durationMs ? { durationMs: options.durationMs } : void 0;
   return {
-    result,
-    media: [
+    name: skill.name,
+    description,
+    ...args.length > 0 ? { arguments: args } : {}
+  };
+}
+async function renderSkillForMcpPrompt(skill, args) {
+  const argString = typeof args.arguments === "string" ? args.arguments : Object.values(args).filter((v) => typeof v === "string").join(" ");
+  const activation = await skill.activate({
+    arguments: argString || void 0
+  });
+  return {
+    description: skill.description,
+    messages: [
       {
-        kind: "audio",
-        data: buffer.toString("base64"),
-        mimeType,
-        description: options?.description,
-        metadata,
-        fileName: options?.fileName
+        role: "user",
+        content: { type: "text", text: activation.resolvedInstructions }
       }
-    ],
-    cost: options?.cost
+    ]
   };
 }
-function resultWithFile(result, fileData, mimeType, options) {
-  const buffer = fileData instanceof Buffer ? fileData : Buffer.from(fileData);
+
+// src/mcp/server.ts
+var DEFAULT_SERVER_INFO = { name: "llmist", version: "0.0.0" };
+function createMcpServer(opts) {
+  const { gadgets, skills } = opts;
+  const hasTools = gadgets.getAll().length > 0;
+  const hasPrompts = !!skills && skills.size > 0;
+  const capabilities = {};
+  if (hasTools) capabilities.tools = {};
+  if (hasPrompts) capabilities.prompts = {};
+  let sdkServer = null;
+  let running = false;
+  async function ensureServer() {
+    if (sdkServer) return sdkServer;
+    const [serverMod, typesMod] = await Promise.all([
+      import("@modelcontextprotocol/sdk/server/index.js"),
+      import("@modelcontextprotocol/sdk/types.js")
+    ]);
+    const ServerClass = serverMod.Server;
+    const server = new ServerClass(opts.serverInfo ?? DEFAULT_SERVER_INFO, {
+      capabilities
+    });
+    if (hasTools) {
+      server.setRequestHandler(typesMod.ListToolsRequestSchema, async () => ({
+        tools: gadgets.getAll().map(gadgetToMcpTool)
+      }));
+      server.setRequestHandler(
+        typesMod.CallToolRequestSchema,
+        async (req) => {
+          const gadget = gadgets.get(req.params.name);
+          if (!gadget) {
+            return {
+              isError: true,
+              content: [
+                {
+                  type: "text",
+                  text: `Unknown tool "${req.params.name}". Call tools/list first.`
+                }
+              ]
+            };
+          }
+          return runGadgetForMcp(gadget, req.params.arguments ?? {});
+        }
+      );
+    }
+    if (hasPrompts && skills) {
+      server.setRequestHandler(typesMod.ListPromptsRequestSchema, async () => ({
+        prompts: Array.from(skills.getAll()).map(skillToMcpPrompt)
+      }));
+      server.setRequestHandler(
+        typesMod.GetPromptRequestSchema,
+        async (req) => {
+          const skill = skills.get(req.params.name);
+          if (!skill) {
+            throw new Error(`Unknown prompt "${req.params.name}"`);
+          }
+          const result = await renderSkillForMcpPrompt(skill, req.params.arguments ?? {});
+          return result;
+        }
+      );
+    }
+    sdkServer = server;
+    return server;
+  }
   return {
-    result,
-    media: [
-      {
-        kind: "file",
-        data: buffer.toString("base64"),
-        mimeType,
-        description: options?.description,
-        fileName: options?.fileName
+    get running() {
+      return running;
+    },
+    async connect(transport) {
+      const server = await ensureServer();
+      await server.connect(transport);
+      running = true;
+    },
+    async stop() {
+      if (!sdkServer) return;
+      try {
+        await sdkServer.close();
+      } catch {
       }
-    ],
-    cost: options?.cost
+      sdkServer = null;
+      running = false;
+    }
   };
 }
 
+// src/mcp/index.ts
+init_tool_adapter();
+
 // src/index.ts
-init_output_viewer();
-init_parser2();
-init_registry();
-init_typed_gadget();
 init_constants2();
 
 // src/utils/config-resolver.ts
@@ -17688,38 +16632,6 @@ function hasHostExports(ctx) {
 init_media_store();
 init_schema_to_json();
 init_schema_validator();
-
-// src/gadgets/validation.ts
-function validateAndApplyDefaults(schema, params) {
-  const result = schema.safeParse(params);
-  if (result.success) {
-    return {
-      success: true,
-      data: result.data
-    };
-  }
-  const issues = result.error.issues.map((issue) => ({
-    path: issue.path.join(".") || "root",
-    message: issue.message
-  }));
-  const formattedError = `Invalid parameters: ${issues.map((i) => `${i.path}: ${i.message}`).join("; ")}`;
-  return {
-    success: false,
-    error: formattedError,
-    issues
-  };
-}
-function validateGadgetParams(gadget, params) {
-  if (!gadget.parameterSchema) {
-    return {
-      success: true,
-      data: params
-    };
-  }
-  return validateAndApplyDefaults(gadget.parameterSchema, params);
-}
-
-// src/index.ts
 init_logger();
 
 // src/package/manifest.ts
@@ -18017,6 +16929,7 @@ export {
   ConversationManager,
   DEFAULT_COMPACTION_CONFIG,
   DEFAULT_HINTS,
+  DEFAULT_MCP_COMMAND_ALLOWLIST,
   DEFAULT_PROMPTS,
   DEFAULT_RATE_LIMIT_CONFIG,
   DEFAULT_RETRY_CONFIG,
@@ -18036,10 +16949,17 @@ export {
   HuggingFaceProvider,
   HumanInputRequiredException,
   HybridStrategy,
+  JsonSchemaConversionError,
   LLMMessageBuilder,
   LLMist,
   LOAD_SKILL_GADGET_NAME,
   MODEL_ALIASES,
+  McpClient,
+  McpConnectError,
+  McpError,
+  McpLifecycle,
+  McpToolCallError,
+  McpUntrustedCommandError,
   MediaStore,
   ModelIdentifierParser,
   ModelRegistry,
@@ -18055,6 +16975,7 @@ export {
   SummarizationStrategy,
   TaskCompletionSignal,
   TimeoutException,
+  assertCommandAllowed,
   audioFromBase64,
   audioFromBuffer,
   collectEvents,
@@ -18069,6 +16990,7 @@ export {
   createHuggingFaceProviderFromEnv,
   createLoadSkillGadget,
   createLogger,
+  createMcpServer,
   createMediaOutput,
   createOpenAIProviderFromEnv,
   createOpenRouterProviderFromEnv,
@@ -18091,7 +17013,9 @@ export {
   formatLLMError,
   formatLlmRequest,
   gadgetError,
+  gadgetResultToMcpContent,
   gadgetSuccess,
+  gadgetToMcpTool,
   getErrorMessage,
   getHostExports2 as getHostExports,
   getModelId,
@@ -18119,9 +17043,11 @@ export {
   isSubagentEvent,
   isTextPart,
   iterationProgressHint,
+  jsonSchemaToZod,
   listPresets,
   listSubagents,
   loadSkillsFromDirectory,
+  mcpToolToGadget,
   normalizeMessageContent,
   parallelGadgetHint,
   parseDataUrl,
@@ -18132,6 +17058,7 @@ export {
   parseSkillContent,
   parseSkillFile,
   randomDelay,
+  renderSkillForMcpPrompt,
   resetFileLoggingState,
   resolveConfig,
   resolveHintTemplate,
@@ -18149,9 +17076,11 @@ export {
   resultWithImage,
   resultWithImages,
   resultWithMedia,
+  runGadgetForMcp,
   runWithHandlers,
   scanResources,
   schemaToJSONSchema,
+  skillToMcpPrompt,
   stream,
   stripProviderPrefix,
   substituteArguments,
@@ -18167,6 +17096,6 @@ export {
   withErrorHandling,
   withRetry,
   withTimeout,
-  z6 as z
+  z4 as z
 };
 //# sourceMappingURL=index.js.map