llmist 17.3.0 → 17.5.0

package/dist/index.cjs

@@ -358,15 +358,15 @@ var init_execution_tree = __esm({
         const parentId = params.parentId ?? this.parentNodeId;
         const parent = parentId ? this.nodes.get(parentId) : null;
         const depth = parent ? parent.depth + 1 : this.baseDepth;
-        const path3 = parent ? [...parent.path] : [];
+        const path4 = parent ? [...parent.path] : [];
         const id = this.generateLLMCallId(params.iteration, parentId);
-        path3.push(id);
+        path4.push(id);
         const node = {
           id,
           type: "llm_call",
           parentId,
           depth,
-          path: path3,
+          path: path4,
           createdAt: Date.now(),
           completedAt: null,
           iteration: params.iteration,
@@ -477,15 +477,15 @@ var init_execution_tree = __esm({
         const parentId = params.parentId ?? this.getCurrentLLMCallId() ?? this.parentNodeId;
         const parent = parentId ? this.nodes.get(parentId) : null;
         const depth = parent ? parent.depth + 1 : this.baseDepth;
-        const path3 = parent ? [...parent.path] : [];
+        const path4 = parent ? [...parent.path] : [];
         const id = this.generateGadgetId(params.invocationId);
-        path3.push(id);
+        path4.push(id);
         const node = {
           id,
           type: "gadget",
           parentId,
           depth,
-          path: path3,
+          path: path4,
           createdAt: Date.now(),
           completedAt: null,
           invocationId: params.invocationId,
@@ -1424,8 +1424,8 @@ ${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}` : "";
+            const path4 = storedMedia?.[i]?.path;
+            const pathInfo = path4 ? ` \u2192 saved to: ${path4}` : "";
             return `[Media: ${mediaIds[i]} (${m.kind})${pathInfo}]`;
           }).join("\n");
           const textWithIds = `Result (${invocationId}): ${result}
@@ -3071,6 +3071,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) {
@@ -4088,29 +4098,29 @@ function schemaToJSONSchema(schema, options) {
 }
 function detectDescriptionMismatch(schema, jsonSchema) {
   const mismatches = [];
-  function checkSchema(zodSchema, json, path3) {
+  function checkSchema(zodSchema, json, path4) {
     if (!zodSchema || typeof zodSchema !== "object") return;
     const def = zodSchema._def;
     const jsonObj = json;
     if (def?.description && !jsonObj?.description) {
-      mismatches.push(path3 || "root");
+      mismatches.push(path4 || "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);
+        checkSchema(fieldSchema, jsonProp, path4 ? `${path4}.${key}` : key);
       }
     }
     if (def?.typeName === "ZodArray" && def?.type) {
-      checkSchema(def.type, jsonObj?.items, path3 ? `${path3}[]` : "[]");
+      checkSchema(def.type, jsonObj?.items, path4 ? `${path4}[]` : "[]");
     }
     if ((def?.typeName === "ZodOptional" || def?.typeName === "ZodNullable") && def?.innerType) {
-      checkSchema(def.innerType, json, path3);
+      checkSchema(def.innerType, json, path4);
     }
     if (def?.typeName === "ZodDefault" && def?.innerType) {
-      checkSchema(def.innerType, json, path3);
+      checkSchema(def.innerType, json, path4);
     }
   }
   checkSchema(schema, jsonSchema, "");
@@ -4203,7 +4213,7 @@ Example fixes:
     );
   }
 }
-function findUnknownTypes(schema, path3 = []) {
+function findUnknownTypes(schema, path4 = []) {
   const issues = [];
   if (!schema || typeof schema !== "object") {
     return issues;
@@ -4215,7 +4225,7 @@ function findUnknownTypes(schema, path3 = []) {
   }
   if (schema.properties) {
     for (const [propName, propSchema] of Object.entries(schema.properties)) {
-      const propPath = [...path3, propName];
+      const propPath = [...path4, propName];
       if (hasNoType(propSchema)) {
         issues.push(propPath.join(".") || propName);
       }
@@ -4223,7 +4233,7 @@ function findUnknownTypes(schema, path3 = []) {
     }
   }
   if (schema.items) {
-    const itemPath = [...path3, "[]"];
+    const itemPath = [...path4, "[]"];
     if (hasNoType(schema.items)) {
       issues.push(itemPath.join("."));
     }
@@ -4231,17 +4241,17 @@ function findUnknownTypes(schema, path3 = []) {
   }
   if (schema.anyOf) {
     schema.anyOf.forEach((subSchema, index) => {
-      issues.push(...findUnknownTypes(subSchema, [...path3, `anyOf[${index}]`]));
+      issues.push(...findUnknownTypes(subSchema, [...path4, `anyOf[${index}]`]));
     });
   }
   if (schema.oneOf) {
     schema.oneOf.forEach((subSchema, index) => {
-      issues.push(...findUnknownTypes(subSchema, [...path3, `oneOf[${index}]`]));
+      issues.push(...findUnknownTypes(subSchema, [...path4, `oneOf[${index}]`]));
     });
   }
   if (schema.allOf) {
     schema.allOf.forEach((subSchema, index) => {
-      issues.push(...findUnknownTypes(subSchema, [...path3, `allOf[${index}]`]));
+      issues.push(...findUnknownTypes(subSchema, [...path4, `allOf[${index}]`]));
     });
   }
   return issues;
@@ -13232,6 +13242,7 @@ var init_builder = __esm({
       subagents;
       policies;
       skills;
+      mcp;
       constructor(client) {
         this.core = { client, initialMessages: [] };
         this.gadgets = { gadgets: [] };
@@ -13239,6 +13250,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) {
@@ -13285,6 +13297,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));
@@ -13605,7 +13656,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. */
@@ -14251,8 +14303,8 @@ var init_error_formatter = __esm({
         const parts = [];
         parts.push(`Error: Invalid parameters for '${gadgetName}':`);
         for (const issue of zodError.issues) {
-          const path3 = issue.path.join(".") || "root";
-          parts.push(`  - ${path3}: ${issue.message}`);
+          const path4 = issue.path.join(".") || "root";
+          parts.push(`  - ${path4}: ${issue.message}`);
         }
         parts.push("");
         parts.push("Gadget Usage:");
@@ -16612,184 +16664,1081 @@ var init_stream_processor_factory = __esm({
   }
 });
 
-// src/agent/agent.ts
-var OVERFLOW_RECOVERY_MIN_HISTORY, Agent;
-var init_agent = __esm({
-  "src/agent/agent.ts"() {
+// src/mcp/errors.ts
+var McpError, McpUntrustedCommandError, McpConnectError, McpToolCallError, McpTimeoutError, JsonSchemaConversionError;
+var init_errors = __esm({
+  "src/mcp/errors.ts"() {
     "use strict";
-    init_execution_tree();
-    init_messages();
-    init_model_shortcuts();
-    init_rate_limit();
-    init_retry();
-    init_exceptions();
-    init_media_store();
-    init_logger();
-    init_agent_internal_key();
-    init_manager();
-    init_conversation_manager();
-    init_conversation_updater();
-    init_event_handlers();
-    init_llm_call_lifecycle();
-    init_output_limit_manager();
-    init_retry_orchestrator();
-    init_safe_observe();
-    init_stream_processor_factory();
-    init_tree_hook_bridge();
-    OVERFLOW_RECOVERY_MIN_HISTORY = 4;
-    Agent = class {
-      client;
-      model;
-      maxIterations;
-      budget;
-      temperature;
-      logger;
-      hooks;
-      conversation;
-      registry;
-      prefixConfig;
-      conversationUpdater;
-      defaultMaxTokens;
-      hasUserPrompt;
-      // Gadget output limiting
-      outputLimitManager;
-      // Context compaction
-      compactionManager;
-      // Media storage (for gadgets returning images, audio, etc.)
-      mediaStore;
-      // Cancellation
-      signal;
-      reasoning;
-      caching;
-      // Retry configuration (shared reference also passed to StreamProcessorFactory)
-      retryConfig;
-      // Rate limit tracker for proactive throttling
-      rateLimitTracker;
-      // Cross-iteration dependency tracking - allows gadgets to depend on results from prior iterations
-      completedInvocationIds = /* @__PURE__ */ new Set();
-      failedInvocationIds = /* @__PURE__ */ new Set();
-      // Queue for user messages injected during agent execution (REPL mid-session input)
-      pendingUserMessages = [];
-      // Execution Tree - first-class model for nested subagent support
-      tree;
-      parentNodeId;
-      // StreamProcessor factory - encapsulates all pass-through StreamProcessor config
-      streamProcessorFactory;
-      // LLM call lifecycle helper (encapsulates prepareLLMCall, completeLLMCall, notifyLLMError)
-      llmCallLifecycle;
-      /**
-       * Creates a new Agent instance.
-       * @internal This constructor is private. Use LLMist.createAgent() or AgentBuilder instead.
-       */
-      constructor(key, options) {
-        if (!isValidAgentKey(key)) {
-          throw new Error(
-            "Agent cannot be instantiated directly. Use LLMist.createAgent() or new AgentBuilder() instead."
+    McpError = class extends Error {
+      serverName;
+      constructor(message, serverName) {
+        super(message);
+        this.name = "McpError";
+        this.serverName = serverName;
+      }
+    };
+    McpUntrustedCommandError = class extends McpError {
+      command;
+      constructor(command, serverName) {
+        super(
+          `Refusing to spawn MCP stdio command "${command}" because its basename is not in the default allowlist. To opt in, set { trust: true } on the server spec (library), or trust = true in your TOML mcp.servers block, or pass --mcp-trust ${serverName ?? "<name>"} on the CLI. See https://llmist.dev/library/advanced/mcp-security/ for context (CVE-2026-30623).`,
+          serverName
+        );
+        this.name = "McpUntrustedCommandError";
+        this.command = command;
+      }
+    };
+    McpConnectError = class extends McpError {
+      cause;
+      constructor(message, opts) {
+        super(message, opts?.serverName);
+        this.name = "McpConnectError";
+        this.cause = opts?.cause;
+      }
+    };
+    McpToolCallError = class extends McpError {
+      toolName;
+      cause;
+      constructor(toolName, message, opts) {
+        super(message, opts?.serverName);
+        this.name = "McpToolCallError";
+        this.toolName = toolName;
+        this.cause = opts?.cause;
+      }
+    };
+    McpTimeoutError = class extends McpError {
+      operation;
+      timeoutMs;
+      constructor(operation, timeoutMs, serverName) {
+        super(
+          `MCP operation "${operation}" on server "${serverName ?? "<unknown>"}" timed out after ${timeoutMs}ms`,
+          serverName
+        );
+        this.name = "McpTimeoutError";
+        this.operation = operation;
+        this.timeoutMs = timeoutMs;
+      }
+    };
+    JsonSchemaConversionError = class extends Error {
+      schemaFragment;
+      reason;
+      constructor(reason, schemaFragment) {
+        super(`JSON Schema \u2192 Zod conversion failed: ${reason}`);
+        this.name = "JsonSchemaConversionError";
+        this.reason = reason;
+        this.schemaFragment = schemaFragment;
+      }
+    };
+  }
+});
+
+// src/mcp/allowlist.ts
+function assertCommandAllowed(command, trusted, customAllowlist) {
+  if (!command || typeof command !== "string") {
+    throw new McpUntrustedCommandError(String(command));
+  }
+  if (WHITESPACE_OR_META_RE.test(command)) {
+    throw new McpUntrustedCommandError(command);
+  }
+  if (trusted) return;
+  const allowlist = customAllowlist ?? DEFAULT_MCP_COMMAND_ALLOWLIST;
+  const base = import_node_path6.default.basename(command);
+  if (!allowlist.has(base)) {
+    throw new McpUntrustedCommandError(command);
+  }
+}
+var import_node_path6, DEFAULT_MCP_COMMAND_ALLOWLIST, WHITESPACE_OR_META_RE;
+var init_allowlist = __esm({
+  "src/mcp/allowlist.ts"() {
+    "use strict";
+    import_node_path6 = __toESM(require("path"), 1);
+    init_errors();
+    DEFAULT_MCP_COMMAND_ALLOWLIST = /* @__PURE__ */ new Set([
+      "npx",
+      "node",
+      "uvx",
+      "uv",
+      "python",
+      "python3",
+      "deno",
+      "bun"
+    ]);
+    WHITESPACE_OR_META_RE = /[\s;|&`$<>()'"\\]/;
+  }
+});
+
+// src/mcp/client.ts
+async function loadSdk() {
+  if (!cachedSdk) {
+    cachedSdk = (async () => {
+      const [client, stdio, http] = await Promise.all([
+        import("@modelcontextprotocol/sdk/client/index.js"),
+        import("@modelcontextprotocol/sdk/client/stdio.js"),
+        import("@modelcontextprotocol/sdk/client/streamableHttp.js")
+      ]);
+      return {
+        Client: client.Client,
+        StdioClientTransport: stdio.StdioClientTransport,
+        StreamableHTTPClientTransport: http.StreamableHTTPClientTransport
+      };
+    })();
+  }
+  return cachedSdk;
+}
+var cachedSdk, DEFAULT_CLIENT_INFO, McpClient;
+var init_client2 = __esm({
+  "src/mcp/client.ts"() {
+    "use strict";
+    init_allowlist();
+    init_errors();
+    cachedSdk = null;
+    DEFAULT_CLIENT_INFO = { name: "llmist", version: "0.0.0" };
+    McpClient = class {
+      constructor(spec, opts) {
+        this.spec = spec;
+        this.injectedTransport = opts?.transport;
+        this.clientInfo = opts?.clientInfo ?? DEFAULT_CLIENT_INFO;
+      }
+      sdkClient = null;
+      spawnedPid = null;
+      closed = false;
+      injectedTransport;
+      clientInfo;
+      get serverName() {
+        return this.spec.name;
+      }
+      get pid() {
+        return this.spawnedPid;
+      }
+      get serverCapabilities() {
+        if (!this.sdkClient) return null;
+        return this.sdkClient.getServerCapabilities() ?? null;
+      }
+      async connect() {
+        if (this.sdkClient) return;
+        let transport;
+        if (this.injectedTransport) {
+          transport = this.injectedTransport;
+        } else if (this.spec.transport === "stdio") {
+          assertCommandAllowed(this.spec.command, this.spec.trust === true);
+          const { StdioClientTransport } = await loadSdk();
+          const stdioTransport = new StdioClientTransport({
+            command: this.spec.command,
+            args: this.spec.args,
+            env: this.spec.env
+          });
+          transport = stdioTransport;
+          this.spawnedPid = null;
+        } else {
+          const { StreamableHTTPClientTransport } = await loadSdk();
+          let url;
+          try {
+            url = new URL(this.spec.url);
+          } catch (err) {
+            throw new McpConnectError(
+              `MCP server "${this.spec.name}" has an invalid URL: ${err.message}`,
+              { serverName: this.spec.name, cause: err }
+            );
+          }
+          transport = new StreamableHTTPClientTransport(url, {
+            requestInit: this.spec.headers ? { headers: this.spec.headers } : void 0
+          });
+        }
+        const { Client } = await loadSdk();
+        const client = new Client(this.clientInfo, { capabilities: {} });
+        try {
+          await this.withTimeout(() => client.connect(transport), "connect");
+        } catch (err) {
+          throw new McpConnectError(
+            `Failed to connect to MCP server "${this.spec.name}": ${err.message}`,
+            { serverName: this.spec.name, cause: err }
           );
         }
-        this.client = options.client;
-        this.model = resolveModel(options.model);
-        this.maxIterations = options.maxIterations ?? 10;
-        this.budget = options.budget;
-        this.temperature = options.temperature;
-        this.logger = options.logger ?? createLogger({ name: "llmist:agent" });
-        this.registry = options.registry;
-        this.prefixConfig = options.prefixConfig;
-        this.defaultMaxTokens = this.resolveMaxTokensFromCatalog(options.model);
-        const outputLimitConfig = {
-          enabled: options.outputLimitConfig?.enabled,
-          limitPercent: options.outputLimitConfig?.limitPercent
-        };
-        this.outputLimitManager = new OutputLimitManager(
-          this.client,
-          this.model,
-          outputLimitConfig,
-          this.registry,
-          this.logger
-        );
-        this.mediaStore = new MediaStore();
-        this.hooks = this.outputLimitManager.getHooks(options.hooks);
-        const baseBuilder = new LLMMessageBuilder(options.promptConfig);
-        if (options.systemPrompt) {
-          baseBuilder.addSystem(options.systemPrompt);
+        this.sdkClient = client;
+        const maybePid = transport.pid;
+        if (typeof maybePid === "number") {
+          this.spawnedPid = maybePid;
         }
-        baseBuilder.addGadgets(this.registry.getAll(), {
-          startPrefix: this.prefixConfig?.gadgetStartPrefix,
-          endPrefix: this.prefixConfig?.gadgetEndPrefix,
-          argPrefix: this.prefixConfig?.gadgetArgPrefix
-        });
-        const baseMessages = baseBuilder.build();
-        const initialMessages = (options.initialMessages ?? []).map((message) => ({
-          role: message.role,
-          content: message.content
+      }
+      async listTools() {
+        const client = this.requireClient();
+        const res = await this.withTimeout(() => client.listTools(), "tools/list");
+        return res.tools.map((t) => ({
+          name: t.name,
+          description: t.description,
+          inputSchema: t.inputSchema
         }));
-        this.conversation = new ConversationManager(baseMessages, initialMessages, {
-          startPrefix: this.prefixConfig?.gadgetStartPrefix,
-          endPrefix: this.prefixConfig?.gadgetEndPrefix,
-          argPrefix: this.prefixConfig?.gadgetArgPrefix
-        });
-        this.hasUserPrompt = !!options.userPrompt;
-        if (options.userPrompt) {
-          this.conversation.addUserMessage(options.userPrompt);
+      }
+      async callTool(name, args) {
+        const client = this.requireClient();
+        try {
+          const res = await this.withTimeout(
+            () => client.callTool({
+              name,
+              arguments: args ?? {}
+            }),
+            `tools/call ${name}`
+          );
+          return {
+            content: res.content ?? [],
+            isError: res.isError
+          };
+        } catch (err) {
+          throw new McpToolCallError(
+            name,
+            `MCP tool call "${name}" on server "${this.spec.name}" failed: ${err.message}`,
+            { serverName: this.spec.name, cause: err }
+          );
         }
-        this.conversationUpdater = new ConversationUpdater(
-          this.conversation,
-          options.textOnlyHandler ?? "terminate",
-          options.textWithGadgetsHandler,
-          this.logger
-        );
-        const compactionEnabled = options.compactionConfig?.enabled ?? true;
-        if (compactionEnabled) {
-          this.compactionManager = new CompactionManager(
-            this.client,
-            this.model,
-            options.compactionConfig,
-            this.logger
+      }
+      async listPrompts() {
+        const client = this.requireClient();
+        if (!client.listPrompts) {
+          return [];
+        }
+        const listPrompts = client.listPrompts.bind(client);
+        const res = await this.withTimeout(() => listPrompts(), "prompts/list");
+        return res.prompts.map((p) => ({
+          name: p.name,
+          description: p.description,
+          arguments: p.arguments
+        }));
+      }
+      async getPrompt(name, args) {
+        const client = this.requireClient();
+        if (!client.getPrompt) {
+          throw new McpToolCallError(name, "Server has no getPrompt method", {
+            serverName: this.spec.name
+          });
+        }
+        const getPrompt = client.getPrompt.bind(client);
+        try {
+          const res = await this.withTimeout(
+            () => getPrompt({ name, arguments: args ?? {} }),
+            `prompts/get ${name}`
+          );
+          return {
+            description: res.description,
+            messages: res.messages.map((m) => ({
+              role: m.role,
+              content: m.content
+            }))
+          };
+        } catch (err) {
+          throw new McpToolCallError(
+            name,
+            `MCP prompts/get "${name}" on server "${this.spec.name}" failed: ${err.message}`,
+            { serverName: this.spec.name, cause: err }
           );
         }
-        this.signal = options.signal;
-        this.reasoning = options.reasoning;
-        this.caching = options.caching;
-        this.retryConfig = options.sharedRetryConfig ?? resolveRetryConfig(options.retryConfig);
-        if (options.sharedRateLimitTracker) {
-          this.rateLimitTracker = options.sharedRateLimitTracker;
-        } else {
-          const rateLimitConfig = resolveRateLimitConfig(options.rateLimitConfig);
-          if (rateLimitConfig.enabled) {
-            this.rateLimitTracker = new RateLimitTracker(options.rateLimitConfig);
+      }
+      async close() {
+        if (this.closed) return;
+        this.closed = true;
+        if (this.sdkClient) {
+          try {
+            await this.sdkClient.close();
+          } catch {
           }
+          this.sdkClient = null;
         }
-        const treeConfig = options.treeConfig;
-        this.tree = treeConfig?.tree ?? new ExecutionTree();
-        this.parentNodeId = treeConfig?.parentNodeId ?? null;
-        this.streamProcessorFactory = new StreamProcessorFactory({
-          registry: this.registry,
-          prefixConfig: this.prefixConfig,
-          hooks: this.hooks,
-          logger: this.logger,
-          requestHumanInput: options.requestHumanInput,
-          defaultGadgetTimeoutMs: options.defaultGadgetTimeoutMs,
-          gadgetExecutionMode: options.gadgetExecutionMode ?? "parallel",
-          client: this.client,
-          mediaStore: this.mediaStore,
-          agentContextConfig: {
-            model: this.model,
-            temperature: this.temperature
-          },
-          subagentConfig: options.subagentConfig,
-          tree: this.tree,
-          baseDepth: treeConfig?.baseDepth ?? 0,
-          parentObservers: treeConfig?.parentObservers,
-          rateLimitTracker: this.rateLimitTracker,
-          retryConfig: this.retryConfig,
-          maxGadgetsPerResponse: options.maxGadgetsPerResponse ?? 0
+      }
+      requireClient() {
+        if (!this.sdkClient) {
+          throw new McpConnectError(
+            `MCP client for server "${this.spec.name}" is not connected. Call connect() first.`,
+            { serverName: this.spec.name }
+          );
+        }
+        return this.sdkClient;
+      }
+      async withTimeout(fn, operation) {
+        const timeoutMs = this.spec.timeoutMs;
+        if (timeoutMs === void 0 || timeoutMs <= 0) {
+          return fn();
+        }
+        return new Promise((resolve2, reject) => {
+          let settled = false;
+          const timeoutId = setTimeout(() => {
+            if (settled) return;
+            settled = true;
+            reject(new McpTimeoutError(operation, timeoutMs, this.spec.name));
+          }, timeoutMs);
+          fn().then((result) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timeoutId);
+            resolve2(result);
+          }).catch((err) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timeoutId);
+            reject(err);
+          });
         });
-        this.llmCallLifecycle = new LLMCallLifecycle({
-          client: this.client,
-          conversation: this.conversation,
-          tree: this.tree,
-          hooks: this.hooks,
-          logger: this.logger,
+      }
+    };
+  }
+});
+
+// src/mcp/lifecycle.ts
+var McpLifecycle;
+var init_lifecycle = __esm({
+  "src/mcp/lifecycle.ts"() {
+    "use strict";
+    init_logger();
+    McpLifecycle = class {
+      clients = [];
+      closing = null;
+      signalHandlersInstalled = false;
+      sigtermHandler = null;
+      sigintHandler = null;
+      get size() {
+        return this.clients.length;
+      }
+      register(client) {
+        this.clients.push(client);
+      }
+      /**
+       * Attach SIGTERM/SIGINT handlers that close every registered client when
+       * the parent process is asked to exit. Idempotent (double install is a
+       * no-op) and removable via `removeSignalHandlers()`.
+       */
+      installSignalHandlers() {
+        if (this.signalHandlersInstalled) return;
+        this.signalHandlersInstalled = true;
+        this.sigtermHandler = () => {
+          void this.closeAll();
+        };
+        this.sigintHandler = () => {
+          void this.closeAll();
+        };
+        process.on("SIGTERM", this.sigtermHandler);
+        process.on("SIGINT", this.sigintHandler);
+      }
+      removeSignalHandlers() {
+        if (!this.signalHandlersInstalled) return;
+        if (this.sigtermHandler) process.off("SIGTERM", this.sigtermHandler);
+        if (this.sigintHandler) process.off("SIGINT", this.sigintHandler);
+        this.sigtermHandler = null;
+        this.sigintHandler = null;
+        this.signalHandlersInstalled = false;
+      }
+      /**
+       * Close every registered client in parallel. Errors from individual close()
+       * calls are swallowed (logged via console.warn) — a teardown path must not
+       * throw because that would mask the original reason the agent is shutting
+       * down. Idempotent: concurrent calls all return the same in-flight promise.
+       */
+      async closeAll() {
+        if (this.closing) return this.closing;
+        const toClose = this.clients;
+        this.clients = [];
+        this.closing = (async () => {
+          const results = await Promise.allSettled(toClose.map((c) => c.close()));
+          for (const r of results) {
+            if (r.status === "rejected") {
+              defaultLogger.debug("MCP client close failed during teardown:", r.reason);
+            }
+          }
+        })();
+        try {
+          await this.closing;
+        } finally {
+          this.closing = null;
+          this.removeSignalHandlers();
+        }
+      }
+    };
+  }
+});
+
+// src/mcp/multi-server.ts
+function resolveToolNames(input) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const s of input) {
+    for (const t of s.tools) {
+      counts.set(t.name, (counts.get(t.name) ?? 0) + 1);
+    }
+  }
+  const collidingServers = /* @__PURE__ */ new Set();
+  for (const s of input) {
+    if (s.tools.some((t) => (counts.get(t.name) ?? 0) > 1)) {
+      collidingServers.add(s.server.name);
+    }
+  }
+  return input.map((s) => ({
+    ...s,
+    prefix: collidingServers.has(s.server.name) ? `${s.server.name}__` : void 0
+  }));
+}
+var init_multi_server = __esm({
+  "src/mcp/multi-server.ts"() {
+    "use strict";
+  }
+});
+
+// src/mcp/prompt-adapter.ts
+function mcpPromptToSkill(descriptor, client, opts) {
+  return new McpPromptSkill(descriptor, client, opts);
+}
+var McpPromptSkill;
+var init_prompt_adapter = __esm({
+  "src/mcp/prompt-adapter.ts"() {
+    "use strict";
+    McpPromptSkill = class {
+      name;
+      description;
+      metadata;
+      isUserInvocable = true;
+      isModelInvocable = true;
+      client;
+      mcpToolName;
+      constructor(descriptor, client, opts) {
+        const prefix = opts?.prefix ?? "";
+        this.name = prefix + descriptor.name;
+        this.description = descriptor.description ?? `MCP prompt "${descriptor.name}" from server "${client.serverName}"`;
+        this.metadata = {
+          name: this.name,
+          description: this.description,
+          ...descriptor.arguments ? { arguments: descriptor.arguments } : {}
+        };
+        this.client = client;
+        this.mcpToolName = descriptor.name;
+      }
+      /**
+       * Render the prompt by calling the MCP server's prompts/get with the
+       * supplied arguments and joining the resulting message text.
+       */
+      async getInstructions(args) {
+        const result = await this.client.getPrompt(this.mcpToolName, args ?? {});
+        const parts = [];
+        for (const m of result.messages) {
+          const c = m.content;
+          if (c.type === "text" && typeof c.text === "string") {
+            parts.push(c.text);
+          } else {
+            try {
+              parts.push(JSON.stringify(c));
+            } catch {
+              parts.push(String(c));
+            }
+          }
+        }
+        return parts.join("\n");
+      }
+    };
+  }
+});
+
+// src/gadgets/helpers.ts
+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);
+  return {
+    kind,
+    data: buffer.toString("base64"),
+    mimeType,
+    description: options?.description,
+    metadata: options?.metadata,
+    fileName: options?.fileName
+  };
+}
+function resultWithMedia(result, media, cost) {
+  if (media.length === 0) {
+    throw new Error("resultWithMedia: media array cannot be empty");
+  }
+  return {
+    result,
+    media,
+    cost
+  };
+}
+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."
+    );
+  }
+  return {
+    result,
+    media: [
+      {
+        kind: "image",
+        data: buffer.toString("base64"),
+        mimeType,
+        description: options?.description,
+        metadata: options?.metadata,
+        fileName: options?.fileName
+      }
+    ],
+    cost: options?.cost
+  };
+}
+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.`
+      );
+    }
+    return {
+      kind: "image",
+      data: buffer.toString("base64"),
+      mimeType,
+      description: img.description,
+      metadata: img.metadata,
+      fileName: img.fileName
+    };
+  });
+  return { result, media, cost };
+}
+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."
+    );
+  }
+  const metadata = options?.durationMs ? { durationMs: options.durationMs } : void 0;
+  return {
+    result,
+    media: [
+      {
+        kind: "audio",
+        data: buffer.toString("base64"),
+        mimeType,
+        description: options?.description,
+        metadata,
+        fileName: options?.fileName
+      }
+    ],
+    cost: options?.cost
+  };
+}
+function resultWithFile(result, fileData, mimeType, options) {
+  const buffer = fileData instanceof Buffer ? fileData : Buffer.from(fileData);
+  return {
+    result,
+    media: [
+      {
+        kind: "file",
+        data: buffer.toString("base64"),
+        mimeType,
+        description: options?.description,
+        fileName: options?.fileName
+      }
+    ],
+    cost: options?.cost
+  };
+}
+var init_helpers = __esm({
+  "src/gadgets/helpers.ts"() {
+    "use strict";
+    init_input_content();
+  }
+});
+
+// src/mcp/json-schema-to-zod.ts
+function jsonSchemaToZod(schema) {
+  if (!schema || typeof schema !== "object") {
+    return import_zod4.z.unknown();
+  }
+  if (schema.$ref) {
+    throw new JsonSchemaConversionError("$ref is not supported in MCP tool schemas", schema);
+  }
+  if (schema.allOf) {
+    throw new JsonSchemaConversionError(
+      "allOf is not supported (MCP tools should use a single composed schema)",
+      schema
+    );
+  }
+  const union = schema.oneOf ?? schema.anyOf;
+  if (union) {
+    if (!Array.isArray(union) || union.length < 2) {
+      throw new JsonSchemaConversionError("oneOf/anyOf must have at least two members", schema);
+    }
+    const branches = union.map((m) => jsonSchemaToZod(m));
+    return applyDecorators(import_zod4.z.union(branches), schema);
+  }
+  const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+  if (type === void 0 && schema.enum && Array.isArray(schema.enum)) {
+    return applyDecorators(buildEnum(schema.enum), schema);
+  }
+  if (type === void 0) {
+    return applyDecorators(import_zod4.z.unknown(), schema);
+  }
+  switch (type) {
+    case "string": {
+      let s;
+      if (schema.enum && Array.isArray(schema.enum)) {
+        s = buildEnum(schema.enum);
+      } else {
+        s = import_zod4.z.string();
+      }
+      return applyDecorators(s, schema);
+    }
+    case "number":
+      return applyDecorators(import_zod4.z.number(), schema);
+    case "integer":
+      return applyDecorators(import_zod4.z.number().int(), schema);
+    case "boolean":
+      return applyDecorators(import_zod4.z.boolean(), schema);
+    case "null":
+      return applyDecorators(import_zod4.z.null(), schema);
+    case "array": {
+      const items = schema.items;
+      if (Array.isArray(items)) {
+        throw new JsonSchemaConversionError("tuple-style items arrays are not supported", schema);
+      }
+      const inner = items ? jsonSchemaToZod(items) : import_zod4.z.unknown();
+      return applyDecorators(import_zod4.z.array(inner), schema);
+    }
+    case "object": {
+      const props = schema.properties ?? {};
+      const required = new Set(schema.required ?? []);
+      const keys = Object.keys(props);
+      if (keys.length === 0) {
+        return applyDecorators(import_zod4.z.record(import_zod4.z.string(), import_zod4.z.unknown()), schema);
+      }
+      const shape = {};
+      for (const key of keys) {
+        const inner = jsonSchemaToZod(props[key]);
+        shape[key] = required.has(key) ? inner : inner.optional();
+      }
+      return applyDecorators(import_zod4.z.object(shape), schema);
+    }
+    default:
+      throw new JsonSchemaConversionError(`unknown JSON Schema type "${type}"`, schema);
+  }
+}
+function buildEnum(values) {
+  if (values.every((v) => typeof v === "string")) {
+    const literals2 = values;
+    if (literals2.length === 0) {
+      throw new JsonSchemaConversionError("enum cannot be empty", values);
+    }
+    return import_zod4.z.enum(literals2);
+  }
+  const literals = values.map((v) => import_zod4.z.literal(v));
+  if (literals.length === 0) {
+    throw new JsonSchemaConversionError("enum cannot be empty", values);
+  }
+  if (literals.length === 1) {
+    return literals[0];
+  }
+  return import_zod4.z.union(literals);
+}
+function applyDecorators(base, schema) {
+  let s = base;
+  if (schema.nullable === true) {
+    s = s.nullable();
+  }
+  if (schema.description) {
+    s = s.describe(schema.description);
+  }
+  if (schema.default !== void 0) {
+    s = s.default(schema.default);
+  }
+  return s;
+}
+var import_zod4;
+var init_json_schema_to_zod = __esm({
+  "src/mcp/json-schema-to-zod.ts"() {
+    "use strict";
+    import_zod4 = require("zod");
+    init_errors();
+  }
+});
+
+// src/mcp/tool-adapter.ts
+function mcpToolToGadget(tool, client, opts) {
+  const gadgetName = (opts?.prefix ?? "") + tool.name;
+  const schema = buildSchema(tool.inputSchema);
+  const description = tool.description ?? `MCP tool "${tool.name}" from server "${client.serverName}"`;
+  return createGadget({
+    name: gadgetName,
+    description,
+    schema,
+    execute: async (params) => {
+      const result = await client.callTool(tool.name, params);
+      return mcpResultToGadgetReturn(result, tool.name);
+    }
+  });
+}
+function buildSchema(inputSchema) {
+  if (!inputSchema) {
+    return import_zod5.z.object({});
+  }
+  const converted = jsonSchemaToZod(inputSchema);
+  if (!(converted instanceof import_zod5.z.ZodObject) && !(converted instanceof import_zod5.z.ZodRecord)) {
+    return import_zod5.z.object({}).passthrough();
+  }
+  return converted;
+}
+function mcpResultToGadgetReturn(result, toolName) {
+  const blocks = result.content ?? [];
+  const textParts = [];
+  const media = [];
+  for (const block of blocks) {
+    const kind = block.type;
+    if (kind === "text" && typeof block.text === "string") {
+      textParts.push(block.text);
+    } else if (kind === "image") {
+      const b = block;
+      media.push({ kind: "image", data: b.data, mimeType: b.mimeType });
+    } else if (kind === "audio") {
+      const b = block;
+      media.push({ kind: "audio", data: b.data, mimeType: b.mimeType });
+    } else {
+      try {
+        textParts.push(JSON.stringify(block));
+      } catch {
+        textParts.push(String(block));
+      }
+    }
+  }
+  const text3 = textParts.join("\n");
+  if (result.isError) {
+    throw new Error(
+      text3 ? text3 : `MCP tool "${toolName}" returned an error result with no text content`
+    );
+  }
+  if (media.length === 0) {
+    return text3;
+  }
+  if (media.length === 1 && media[0].kind === "image") {
+    const img = media[0];
+    return resultWithImage(text3, Buffer.from(img.data, "base64"), {
+      mimeType: img.mimeType
+    });
+  }
+  return {
+    result: text3,
+    media: media.map((m) => ({
+      kind: m.kind,
+      data: m.data,
+      mimeType: m.mimeType
+    }))
+  };
+}
+var import_zod5;
+var init_tool_adapter = __esm({
+  "src/mcp/tool-adapter.ts"() {
+    "use strict";
+    import_zod5 = require("zod");
+    init_create_gadget();
+    init_helpers();
+    init_json_schema_to_zod();
+  }
+});
+
+// src/mcp/runtime.ts
+var runtime_exports = {};
+__export(runtime_exports, {
+  setupMcpServers: () => setupMcpServers
+});
+async function setupMcpServers(opts) {
+  const { specs, registry, conversation, prefixConfig, systemPrompt, logger: logger2, onPromptDiscovered } = opts;
+  const lifecycle = new McpLifecycle();
+  lifecycle.installSignalHandlers();
+  const connected = [];
+  await Promise.all(
+    specs.map(async (spec) => {
+      const client = new McpClient(spec);
+      try {
+        await client.connect();
+      } catch (err) {
+        logger2.warn(
+          `MCP server "${spec.name}" failed to connect \u2014 skipping. Reason: ${err.message}`
+        );
+        return;
+      }
+      lifecycle.register(client);
+      const caps = client.serverCapabilities;
+      const hasTools = caps?.tools !== void 0;
+      let tools = [];
+      if (hasTools) {
+        try {
+          tools = await client.listTools();
+        } catch (err) {
+          logger2.warn(
+            `MCP server "${spec.name}" listTools failed \u2014 skipping. Reason: ${err.message}`
+          );
+          return;
+        }
+      } else {
+        logger2.debug(
+          `MCP server "${spec.name}" did not advertise tools capability \u2014 skipping listTools.`
+        );
+      }
+      if (caps?.resources !== void 0) {
+        logger2.debug(
+          `MCP server "${spec.name}" advertises 'resources' capability \u2014 not yet implemented in llmist (deferred to v1.5).`
+        );
+      }
+      if (caps?.prompts !== void 0 && onPromptDiscovered) {
+        try {
+          const prompts = await client.listPrompts();
+          for (const p of prompts) {
+            onPromptDiscovered(mcpPromptToSkill(p, client));
+          }
+        } catch (err) {
+          logger2.debug(
+            `MCP server "${spec.name}" listPrompts failed \u2014 skipping prompts. Reason: ${err.message}`
+          );
+        }
+      }
+      connected.push({ client, serverToolList: { server: spec, tools } });
+    })
+  );
+  const resolved = resolveToolNames(connected.map((c) => c.serverToolList));
+  for (const r of resolved) {
+    const cs = connected.find((c) => c.serverToolList.server.name === r.server.name);
+    if (!cs) continue;
+    for (const tool of r.tools) {
+      const gadget = mcpToolToGadget(tool, cs.client, { prefix: r.prefix });
+      try {
+        registry.register(gadget.name ?? tool.name, gadget);
+      } catch (err) {
+        logger2.warn(
+          `MCP server "${r.server.name}" tool "${tool.name}" was not registered: ${err.message}`
+        );
+      }
+    }
+  }
+  const builder = new LLMMessageBuilder();
+  if (typeof systemPrompt === "string" && systemPrompt.length > 0) {
+    builder.addSystem(systemPrompt);
+  }
+  builder.addGadgets(registry.getAll(), {
+    startPrefix: prefixConfig?.gadgetStartPrefix,
+    endPrefix: prefixConfig?.gadgetEndPrefix,
+    argPrefix: prefixConfig?.gadgetArgPrefix
+  });
+  conversation.replaceBaseMessages(builder.build());
+  return lifecycle;
+}
+var init_runtime = __esm({
+  "src/mcp/runtime.ts"() {
+    "use strict";
+    init_messages();
+    init_client2();
+    init_lifecycle();
+    init_multi_server();
+    init_prompt_adapter();
+    init_tool_adapter();
+  }
+});
+
+// src/agent/agent.ts
+var OVERFLOW_RECOVERY_MIN_HISTORY, Agent;
+var init_agent = __esm({
+  "src/agent/agent.ts"() {
+    "use strict";
+    init_execution_tree();
+    init_messages();
+    init_model_shortcuts();
+    init_rate_limit();
+    init_retry();
+    init_exceptions();
+    init_media_store();
+    init_logger();
+    init_agent_internal_key();
+    init_manager();
+    init_conversation_manager();
+    init_conversation_updater();
+    init_event_handlers();
+    init_llm_call_lifecycle();
+    init_output_limit_manager();
+    init_retry_orchestrator();
+    init_safe_observe();
+    init_stream_processor_factory();
+    init_tree_hook_bridge();
+    OVERFLOW_RECOVERY_MIN_HISTORY = 4;
+    Agent = class {
+      client;
+      model;
+      maxIterations;
+      budget;
+      temperature;
+      logger;
+      hooks;
+      conversation;
+      registry;
+      prefixConfig;
+      conversationUpdater;
+      defaultMaxTokens;
+      hasUserPrompt;
+      // Gadget output limiting
+      outputLimitManager;
+      // Context compaction
+      compactionManager;
+      // Media storage (for gadgets returning images, audio, etc.)
+      mediaStore;
+      // Cancellation
+      signal;
+      reasoning;
+      caching;
+      // Retry configuration (shared reference also passed to StreamProcessorFactory)
+      retryConfig;
+      // Rate limit tracker for proactive throttling
+      rateLimitTracker;
+      // Cross-iteration dependency tracking - allows gadgets to depend on results from prior iterations
+      completedInvocationIds = /* @__PURE__ */ new Set();
+      failedInvocationIds = /* @__PURE__ */ new Set();
+      // Queue for user messages injected during agent execution (REPL mid-session input)
+      pendingUserMessages = [];
+      // Execution Tree - first-class model for nested subagent support
+      tree;
+      parentNodeId;
+      // StreamProcessor factory - encapsulates all pass-through StreamProcessor config
+      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.
+       */
+      constructor(key, options) {
+        if (!isValidAgentKey(key)) {
+          throw new Error(
+            "Agent cannot be instantiated directly. Use LLMist.createAgent() or new AgentBuilder() instead."
+          );
+        }
+        this.client = options.client;
+        this.model = resolveModel(options.model);
+        this.maxIterations = options.maxIterations ?? 10;
+        this.budget = options.budget;
+        this.temperature = options.temperature;
+        this.logger = options.logger ?? createLogger({ name: "llmist:agent" });
+        this.registry = options.registry;
+        this.prefixConfig = options.prefixConfig;
+        this.defaultMaxTokens = this.resolveMaxTokensFromCatalog(options.model);
+        const outputLimitConfig = {
+          enabled: options.outputLimitConfig?.enabled,
+          limitPercent: options.outputLimitConfig?.limitPercent
+        };
+        this.outputLimitManager = new OutputLimitManager(
+          this.client,
+          this.model,
+          outputLimitConfig,
+          this.registry,
+          this.logger
+        );
+        this.mediaStore = new MediaStore();
+        this.hooks = this.outputLimitManager.getHooks(options.hooks);
+        const baseBuilder = new LLMMessageBuilder(options.promptConfig);
+        if (options.systemPrompt) {
+          baseBuilder.addSystem(options.systemPrompt);
+        }
+        baseBuilder.addGadgets(this.registry.getAll(), {
+          startPrefix: this.prefixConfig?.gadgetStartPrefix,
+          endPrefix: this.prefixConfig?.gadgetEndPrefix,
+          argPrefix: this.prefixConfig?.gadgetArgPrefix
+        });
+        const baseMessages = baseBuilder.build();
+        const initialMessages = (options.initialMessages ?? []).map((message) => ({
+          role: message.role,
+          content: message.content
+        }));
+        this.conversation = new ConversationManager(baseMessages, initialMessages, {
+          startPrefix: this.prefixConfig?.gadgetStartPrefix,
+          endPrefix: this.prefixConfig?.gadgetEndPrefix,
+          argPrefix: this.prefixConfig?.gadgetArgPrefix
+        });
+        this.hasUserPrompt = !!options.userPrompt;
+        if (options.userPrompt) {
+          this.conversation.addUserMessage(options.userPrompt);
+        }
+        this.conversationUpdater = new ConversationUpdater(
+          this.conversation,
+          options.textOnlyHandler ?? "terminate",
+          options.textWithGadgetsHandler,
+          this.logger
+        );
+        const compactionEnabled = options.compactionConfig?.enabled ?? true;
+        if (compactionEnabled) {
+          this.compactionManager = new CompactionManager(
+            this.client,
+            this.model,
+            options.compactionConfig,
+            this.logger
+          );
+        }
+        this.signal = options.signal;
+        this.mcpSpecs = options.mcpSpecs ?? [];
+        this.reasoning = options.reasoning;
+        this.caching = options.caching;
+        this.retryConfig = options.sharedRetryConfig ?? resolveRetryConfig(options.retryConfig);
+        if (options.sharedRateLimitTracker) {
+          this.rateLimitTracker = options.sharedRateLimitTracker;
+        } else {
+          const rateLimitConfig = resolveRateLimitConfig(options.rateLimitConfig);
+          if (rateLimitConfig.enabled) {
+            this.rateLimitTracker = new RateLimitTracker(options.rateLimitConfig);
+          }
+        }
+        const treeConfig = options.treeConfig;
+        this.tree = treeConfig?.tree ?? new ExecutionTree();
+        this.parentNodeId = treeConfig?.parentNodeId ?? null;
+        this.streamProcessorFactory = new StreamProcessorFactory({
+          registry: this.registry,
+          prefixConfig: this.prefixConfig,
+          hooks: this.hooks,
+          logger: this.logger,
+          requestHumanInput: options.requestHumanInput,
+          defaultGadgetTimeoutMs: options.defaultGadgetTimeoutMs,
+          gadgetExecutionMode: options.gadgetExecutionMode ?? "parallel",
+          client: this.client,
+          mediaStore: this.mediaStore,
+          agentContextConfig: {
+            model: this.model,
+            temperature: this.temperature
+          },
+          subagentConfig: options.subagentConfig,
+          tree: this.tree,
+          baseDepth: treeConfig?.baseDepth ?? 0,
+          parentObservers: treeConfig?.parentObservers,
+          rateLimitTracker: this.rateLimitTracker,
+          retryConfig: this.retryConfig,
+          maxGadgetsPerResponse: options.maxGadgetsPerResponse ?? 0
+        });
+        this.llmCallLifecycle = new LLMCallLifecycle({
+          client: this.client,
+          conversation: this.conversation,
+          tree: this.tree,
+          hooks: this.hooks,
+          logger: this.logger,
           rateLimitTracker: this.rateLimitTracker,
           signal: this.signal,
           temperature: this.temperature,
@@ -17007,6 +17956,18 @@ var init_agent = __esm({
           );
         }
         const unsubscribeBridge = bridgeTreeToHooks(this.tree, this.hooks, this.logger);
+        if (this.mcpSpecs.length > 0) {
+          const { setupMcpServers: setupMcpServers2 } = await Promise.resolve().then(() => (init_runtime(), runtime_exports));
+          this.mcpLifecycle = await setupMcpServers2({
+            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,
@@ -17206,6 +18167,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;
+          }
         }
       }
       /**
@@ -17405,6 +18374,7 @@ __export(index_exports, {
   ConversationManager: () => ConversationManager,
   DEFAULT_COMPACTION_CONFIG: () => DEFAULT_COMPACTION_CONFIG,
   DEFAULT_HINTS: () => DEFAULT_HINTS,
+  DEFAULT_MCP_COMMAND_ALLOWLIST: () => DEFAULT_MCP_COMMAND_ALLOWLIST,
   DEFAULT_PROMPTS: () => DEFAULT_PROMPTS,
   DEFAULT_RATE_LIMIT_CONFIG: () => DEFAULT_RATE_LIMIT_CONFIG,
   DEFAULT_RETRY_CONFIG: () => DEFAULT_RETRY_CONFIG,
@@ -17424,10 +18394,17 @@ __export(index_exports, {
   HuggingFaceProvider: () => HuggingFaceProvider,
   HumanInputRequiredException: () => HumanInputRequiredException,
   HybridStrategy: () => HybridStrategy,
+  JsonSchemaConversionError: () => JsonSchemaConversionError,
   LLMMessageBuilder: () => LLMMessageBuilder,
   LLMist: () => LLMist,
   LOAD_SKILL_GADGET_NAME: () => LOAD_SKILL_GADGET_NAME,
   MODEL_ALIASES: () => MODEL_ALIASES,
+  McpClient: () => McpClient,
+  McpConnectError: () => McpConnectError,
+  McpError: () => McpError,
+  McpLifecycle: () => McpLifecycle,
+  McpToolCallError: () => McpToolCallError,
+  McpUntrustedCommandError: () => McpUntrustedCommandError,
   MediaStore: () => MediaStore,
   ModelIdentifierParser: () => ModelIdentifierParser,
   ModelRegistry: () => ModelRegistry,
@@ -17443,6 +18420,7 @@ __export(index_exports, {
   SummarizationStrategy: () => SummarizationStrategy,
   TaskCompletionSignal: () => TaskCompletionSignal,
   TimeoutException: () => TimeoutException,
+  assertCommandAllowed: () => assertCommandAllowed,
   audioFromBase64: () => audioFromBase64,
   audioFromBuffer: () => audioFromBuffer,
   collectEvents: () => collectEvents,
@@ -17457,6 +18435,7 @@ __export(index_exports, {
   createHuggingFaceProviderFromEnv: () => createHuggingFaceProviderFromEnv,
   createLoadSkillGadget: () => createLoadSkillGadget,
   createLogger: () => createLogger,
+  createMcpServer: () => createMcpServer,
   createMediaOutput: () => createMediaOutput,
   createOpenAIProviderFromEnv: () => createOpenAIProviderFromEnv,
   createOpenRouterProviderFromEnv: () => createOpenRouterProviderFromEnv,
@@ -17479,7 +18458,9 @@ __export(index_exports, {
   formatLLMError: () => formatLLMError,
   formatLlmRequest: () => formatLlmRequest,
   gadgetError: () => gadgetError,
+  gadgetResultToMcpContent: () => gadgetResultToMcpContent,
   gadgetSuccess: () => gadgetSuccess,
+  gadgetToMcpTool: () => gadgetToMcpTool,
   getErrorMessage: () => getErrorMessage,
   getHostExports: () => getHostExports2,
   getModelId: () => getModelId,
@@ -17507,9 +18488,11 @@ __export(index_exports, {
   isSubagentEvent: () => isSubagentEvent,
   isTextPart: () => isTextPart,
   iterationProgressHint: () => iterationProgressHint,
+  jsonSchemaToZod: () => jsonSchemaToZod,
   listPresets: () => listPresets,
   listSubagents: () => listSubagents,
   loadSkillsFromDirectory: () => loadSkillsFromDirectory,
+  mcpToolToGadget: () => mcpToolToGadget,
   normalizeMessageContent: () => normalizeMessageContent,
   parallelGadgetHint: () => parallelGadgetHint,
   parseDataUrl: () => parseDataUrl,
@@ -17520,6 +18503,7 @@ __export(index_exports, {
   parseSkillContent: () => parseSkillContent,
   parseSkillFile: () => parseSkillFile,
   randomDelay: () => randomDelay,
+  renderSkillForMcpPrompt: () => renderSkillForMcpPrompt,
   resetFileLoggingState: () => resetFileLoggingState,
   resolveConfig: () => resolveConfig,
   resolveHintTemplate: () => resolveHintTemplate,
@@ -17537,9 +18521,11 @@ __export(index_exports, {
   resultWithImage: () => resultWithImage,
   resultWithImages: () => resultWithImages,
   resultWithMedia: () => resultWithMedia,
+  runGadgetForMcp: () => runGadgetForMcp,
   runWithHandlers: () => runWithHandlers,
   scanResources: () => scanResources,
   schemaToJSONSchema: () => schemaToJSONSchema,
+  skillToMcpPrompt: () => skillToMcpPrompt,
   stream: () => stream,
   stripProviderPrefix: () => stripProviderPrefix,
   substituteArguments: () => substituteArguments,
@@ -17555,10 +18541,10 @@ __export(index_exports, {
   withErrorHandling: () => withErrorHandling,
   withRetry: () => withRetry,
   withTimeout: () => withTimeout,
-  z: () => import_zod4.z
+  z: () => import_zod6.z
 });
 module.exports = __toCommonJS(index_exports);
-var import_zod4 = require("zod");
+var import_zod6 = require("zod");
 init_agent();
 init_builder();
 init_event_handlers();
@@ -17741,140 +18727,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_client2();
+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");
+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;
   }
-  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.`
-      );
+  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
@@ -17983,38 +19083,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
@@ -18313,6 +19381,7 @@ function getHostExports2(ctx) {
   ConversationManager,
   DEFAULT_COMPACTION_CONFIG,
   DEFAULT_HINTS,
+  DEFAULT_MCP_COMMAND_ALLOWLIST,
   DEFAULT_PROMPTS,
   DEFAULT_RATE_LIMIT_CONFIG,
   DEFAULT_RETRY_CONFIG,
@@ -18332,10 +19401,17 @@ function getHostExports2(ctx) {
   HuggingFaceProvider,
   HumanInputRequiredException,
   HybridStrategy,
+  JsonSchemaConversionError,
   LLMMessageBuilder,
   LLMist,
   LOAD_SKILL_GADGET_NAME,
   MODEL_ALIASES,
+  McpClient,
+  McpConnectError,
+  McpError,
+  McpLifecycle,
+  McpToolCallError,
+  McpUntrustedCommandError,
   MediaStore,
   ModelIdentifierParser,
   ModelRegistry,
@@ -18351,6 +19427,7 @@ function getHostExports2(ctx) {
   SummarizationStrategy,
   TaskCompletionSignal,
   TimeoutException,
+  assertCommandAllowed,
   audioFromBase64,
   audioFromBuffer,
   collectEvents,
@@ -18365,6 +19442,7 @@ function getHostExports2(ctx) {
   createHuggingFaceProviderFromEnv,
   createLoadSkillGadget,
   createLogger,
+  createMcpServer,
   createMediaOutput,
   createOpenAIProviderFromEnv,
   createOpenRouterProviderFromEnv,
@@ -18387,7 +19465,9 @@ function getHostExports2(ctx) {
   formatLLMError,
   formatLlmRequest,
   gadgetError,
+  gadgetResultToMcpContent,
   gadgetSuccess,
+  gadgetToMcpTool,
   getErrorMessage,
   getHostExports,
   getModelId,
@@ -18415,9 +19495,11 @@ function getHostExports2(ctx) {
   isSubagentEvent,
   isTextPart,
   iterationProgressHint,
+  jsonSchemaToZod,
   listPresets,
   listSubagents,
   loadSkillsFromDirectory,
+  mcpToolToGadget,
   normalizeMessageContent,
   parallelGadgetHint,
   parseDataUrl,
@@ -18428,6 +19510,7 @@ function getHostExports2(ctx) {
   parseSkillContent,
   parseSkillFile,
   randomDelay,
+  renderSkillForMcpPrompt,
   resetFileLoggingState,
   resolveConfig,
   resolveHintTemplate,
@@ -18445,9 +19528,11 @@ function getHostExports2(ctx) {
   resultWithImage,
   resultWithImages,
   resultWithMedia,
+  runGadgetForMcp,
   runWithHandlers,
   scanResources,
   schemaToJSONSchema,
+  skillToMcpPrompt,
   stream,
   stripProviderPrefix,
   substituteArguments,