llmist 17.3.0 → 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";
@@ -2432,126 +1767,6 @@ var init_media_store = __esm({
   }
 });
 
-// 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(" ")}
-`);
-        }
-      }
-    } : 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();
-  }
-});
-
 // src/agent/agent-internal-key.ts
 function isValidAgentKey(key) {
   return key === AGENT_INTERNAL_KEY;
@@ -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) {
@@ -3994,666 +3219,83 @@ var init_llm_call_lifecycle = __esm({
       resolveCachingConfig() {
         if (this.caching !== void 0) return this.caching;
         return { enabled: true };
-      }
-      /**
-       * Calculate cost and complete LLM call in execution tree.
-       * Also records usage to rate limit tracker for proactive throttling.
-       */
-      completeLLMCallInTree(nodeId, result) {
-        const inputTokens = result.usage?.inputTokens ?? 0;
-        const outputTokens = result.usage?.outputTokens ?? 0;
-        if (this.rateLimitTracker) {
-          this.rateLimitTracker.recordUsage(inputTokens, outputTokens);
-        }
-        const llmCost = this.client.modelRegistry?.estimateCost?.(
-          this.model,
-          inputTokens,
-          outputTokens,
-          result.usage?.cachedInputTokens ?? 0,
-          result.usage?.cacheCreationInputTokens ?? 0,
-          result.usage?.reasoningTokens ?? 0
-        )?.totalCost;
-        this.tree.completeLLMCall(nodeId, {
-          response: result.rawResponse,
-          usage: result.usage,
-          finishReason: result.finishReason,
-          cost: llmCost,
-          thinkingContent: result.thinkingContent
-        });
-      }
-      /**
-       * Process afterLLMCall controller and return modified final message.
-       *
-       * Skips controller invocation for interrupted calls (`finishReason === "interrupted"`)
-       * 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();
-       *   }
-       * }
-       * ```
+      }
+      /**
+       * Calculate cost and complete LLM call in execution tree.
+       * Also records usage to rate limit tracker for proactive throttling.
        */
-      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 }
-            );
-          }
+      completeLLMCallInTree(nodeId, result) {
+        const inputTokens = result.usage?.inputTokens ?? 0;
+        const outputTokens = result.usage?.outputTokens ?? 0;
+        if (this.rateLimitTracker) {
+          this.rateLimitTracker.recordUsage(inputTokens, outputTokens);
         }
-        return controller;
+        const llmCost = this.client.modelRegistry?.estimateCost?.(
+          this.model,
+          inputTokens,
+          outputTokens,
+          result.usage?.cachedInputTokens ?? 0,
+          result.usage?.cacheCreationInputTokens ?? 0,
+          result.usage?.reasoningTokens ?? 0
+        )?.totalCost;
+        this.tree.completeLLMCall(nodeId, {
+          response: result.rawResponse,
+          usage: result.usage,
+          finishReason: result.finishReason,
+          cost: llmCost,
+          thinkingContent: result.thinkingContent
+        });
       }
       /**
-       * Generate instruction text for the LLM.
-       * Combines name, description, and parameter schema into a formatted instruction.
+       * Process afterLLMCall controller and return modified final message.
        *
-       * @param optionsOrArgPrefix - Optional custom prefixes for examples, or just argPrefix string for backwards compatibility
-       * @returns Formatted instruction string
+       * Skips controller invocation for interrupted calls (`finishReason === "interrupted"`)
+       * 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.
        */
-      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;
 }
@@ -4775,15 +3417,15 @@ function createGadgetOutputViewer(store, maxOutputChars = DEFAULT_MAX_OUTPUT_CHA
   return createGadget({
     name: "GadgetOutputViewer",
     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: z3.object({
-      id: z3.string().describe("ID of the stored output (from the truncation message)"),
-      mode: z3.enum(["line", "character"]).default("line").describe(
+    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).'
       ),
-      patterns: z3.array(patternSchema).optional().describe(
+      patterns: z.array(patternSchema).optional().describe(
         'Line-mode filter patterns applied in order (like piping through grep). Not supported in mode "character".'
       ),
-      limit: z3.string().optional().describe(
+      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).`
       )
     }),
@@ -4923,11 +3565,11 @@ var init_output_viewer = __esm({
     DEFAULT_MAX_OUTPUT_CHARS = 76800;
     CHARACTER_HINT_WINDOW = 2e3;
     DENSE_LINE_THRESHOLD = 4e3;
-    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)")
+    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)")
     });
   }
 });
@@ -5461,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);
@@ -5473,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);
@@ -12910,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();
@@ -13224,6 +11866,7 @@ var init_builder = __esm({
       subagents;
       policies;
       skills;
+      mcp;
       constructor(client) {
         this.core = { client, initialMessages: [] };
         this.gadgets = { gadgets: [] };
@@ -13231,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) {
@@ -13277,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));
@@ -13538,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);
@@ -13597,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. */
@@ -14521,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,
@@ -14529,7 +13213,7 @@ function getHostExportsInternal() {
     createGadget,
     ExecutionTree,
     LLMist,
-    z: z5
+    z: z3
   };
 }
 var GadgetExecutor;
@@ -14538,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();
@@ -16669,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.
@@ -16740,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);
@@ -16999,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,
@@ -17198,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;
+          }
         }
       }
       /**
@@ -17389,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();
@@ -17502,7 +16211,7 @@ function createHints(config) {
 init_stream_processor();
 
 // src/index.ts
-init_client();
+init_client2();
 init_constants();
 
 // src/core/errors.ts
@@ -17567,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
@@ -17809,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
@@ -18138,6 +16929,7 @@ export {
   ConversationManager,
   DEFAULT_COMPACTION_CONFIG,
   DEFAULT_HINTS,
+  DEFAULT_MCP_COMMAND_ALLOWLIST,
   DEFAULT_PROMPTS,
   DEFAULT_RATE_LIMIT_CONFIG,
   DEFAULT_RETRY_CONFIG,
@@ -18157,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,
@@ -18176,6 +16975,7 @@ export {
   SummarizationStrategy,
   TaskCompletionSignal,
   TimeoutException,
+  assertCommandAllowed,
   audioFromBase64,
   audioFromBuffer,
   collectEvents,
@@ -18190,6 +16990,7 @@ export {
   createHuggingFaceProviderFromEnv,
   createLoadSkillGadget,
   createLogger,
+  createMcpServer,
   createMediaOutput,
   createOpenAIProviderFromEnv,
   createOpenRouterProviderFromEnv,
@@ -18212,7 +17013,9 @@ export {
   formatLLMError,
   formatLlmRequest,
   gadgetError,
+  gadgetResultToMcpContent,
   gadgetSuccess,
+  gadgetToMcpTool,
   getErrorMessage,
   getHostExports2 as getHostExports,
   getModelId,
@@ -18240,9 +17043,11 @@ export {
   isSubagentEvent,
   isTextPart,
   iterationProgressHint,
+  jsonSchemaToZod,
   listPresets,
   listSubagents,
   loadSkillsFromDirectory,
+  mcpToolToGadget,
   normalizeMessageContent,
   parallelGadgetHint,
   parseDataUrl,
@@ -18253,6 +17058,7 @@ export {
   parseSkillContent,
   parseSkillFile,
   randomDelay,
+  renderSkillForMcpPrompt,
   resetFileLoggingState,
   resolveConfig,
   resolveHintTemplate,
@@ -18270,9 +17076,11 @@ export {
   resultWithImage,
   resultWithImages,
   resultWithMedia,
+  runGadgetForMcp,
   runWithHandlers,
   scanResources,
   schemaToJSONSchema,
+  skillToMcpPrompt,
   stream,
   stripProviderPrefix,
   substituteArguments,
@@ -18288,6 +17096,6 @@ export {
   withErrorHandling,
   withRetry,
   withTimeout,
-  z6 as z
+  z4 as z
 };
 //# sourceMappingURL=index.js.map