llmist 2.4.0 → 2.5.0

package/dist/cli.cjs

@@ -46,6 +46,137 @@ var init_constants = __esm({
   }
 });
 
+// src/core/input-content.ts
+function text(content) {
+  return { type: "text", text: content };
+}
+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 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" }
+    ];
+  }
+});
+
 // src/core/model-shortcuts.ts
 function isKnownModelPattern(model) {
   const normalized = model.toLowerCase();
@@ -375,7 +506,9 @@ var init_prompt_config = __esm({
       rules: () => [
         "Output ONLY plain text with the exact markers - never use function/tool calling",
         "You can invoke multiple gadgets in a single response",
-        "For dependent gadgets, invoke the first one and wait for the result"
+        "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
     };
@@ -383,11 +516,24 @@ var init_prompt_config = __esm({
 });
 
 // src/core/messages.ts
+function normalizeContent(content) {
+  if (typeof content === "string") {
+    return [{ type: "text", text: content }];
+  }
+  return content;
+}
+function extractText(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 = [];
@@ -489,6 +635,10 @@ CRITICAL: ${criticalUsage}
         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}`);
@@ -538,6 +688,25 @@ ${this.endPrefix}`;
 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:
@@ -588,6 +757,25 @@ Produces: { "items": ["first", "second"] }`);
         }
         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;
@@ -596,6 +784,104 @@ Produces: { "items": ["first", "second"] }`);
         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;
+      }
       addGadgetCall(gadget, parameters, result) {
         const paramStr = this.formatBlockParameters(parameters, "");
         this.messages.push({
@@ -1914,7 +2200,7 @@ var init_conversation_manager = __esm({
           if (msg.role === "user") {
             this.historyBuilder.addUser(msg.content);
           } else if (msg.role === "assistant") {
-            this.historyBuilder.addAssistant(msg.content);
+            this.historyBuilder.addAssistant(extractText(msg.content));
           }
         }
       }
@@ -1935,8 +2221,10 @@ async function runWithHandlers(agentGenerator, handlers) {
         if (handlers.onGadgetCall) {
           await handlers.onGadgetCall({
             gadgetName: event.call.gadgetName,
+            invocationId: event.call.invocationId,
             parameters: event.call.parameters,
-            parametersRaw: event.call.parametersRaw
+            parametersRaw: event.call.parametersRaw,
+            dependencies: event.call.dependencies
           });
         }
         break;
@@ -2783,15 +3071,37 @@ var init_parser = __esm({
         return segment.trim().length > 0 ? segment : void 0;
       }
       /**
-       * Parse gadget name, handling both old format (name:invocationId) and new format (just name).
-       * For new format, generates a unique invocation ID.
+       * Parse gadget name with optional invocation ID and dependencies.
+       *
+       * Supported formats:
+       * - `GadgetName` - Auto-generate ID, no dependencies
+       * - `GadgetName:my_id` - Explicit ID, no dependencies
+       * - `GadgetName:my_id:dep1,dep2` - Explicit ID with dependencies
+       *
+       * Dependencies must be comma-separated invocation IDs.
        */
       parseGadgetName(gadgetName) {
-        if (gadgetName.includes(":")) {
-          const parts = gadgetName.split(":");
-          return { actualName: parts[0], invocationId: parts[1] };
+        const parts = gadgetName.split(":");
+        if (parts.length === 1) {
+          return {
+            actualName: parts[0],
+            invocationId: `gadget_${++globalInvocationCounter}`,
+            dependencies: []
+          };
+        } else if (parts.length === 2) {
+          return {
+            actualName: parts[0],
+            invocationId: parts[1].trim(),
+            dependencies: []
+          };
+        } else {
+          const deps = parts[2].split(",").map((d) => d.trim()).filter((d) => d.length > 0);
+          return {
+            actualName: parts[0],
+            invocationId: parts[1].trim(),
+            dependencies: deps
+          };
         }
-        return { actualName: gadgetName, invocationId: `gadget_${++globalInvocationCounter}` };
       }
       /**
        * Extract the error message from a parse error.
@@ -2827,39 +3137,20 @@ var init_parser = __esm({
           const metadataEndIndex = this.buffer.indexOf("\n", metadataStartIndex);
           if (metadataEndIndex === -1) break;
           const gadgetName = this.buffer.substring(metadataStartIndex, metadataEndIndex).trim();
-          const { actualName: actualGadgetName, invocationId } = this.parseGadgetName(gadgetName);
+          const { actualName: actualGadgetName, invocationId, dependencies } = this.parseGadgetName(gadgetName);
           const contentStartIndex = metadataEndIndex + 1;
           let partEndIndex;
           let endMarkerLength = 0;
-          if (gadgetName.includes(":")) {
-            const oldEndMarker = `${this.endPrefix + actualGadgetName}:${invocationId}`;
-            partEndIndex = this.buffer.indexOf(oldEndMarker, contentStartIndex);
-            if (partEndIndex === -1) break;
-            endMarkerLength = oldEndMarker.length;
+          const nextStartPos = this.buffer.indexOf(this.startPrefix, contentStartIndex);
+          const endPos = this.buffer.indexOf(this.endPrefix, contentStartIndex);
+          if (nextStartPos !== -1 && (endPos === -1 || nextStartPos < endPos)) {
+            partEndIndex = nextStartPos;
+            endMarkerLength = 0;
+          } else if (endPos !== -1) {
+            partEndIndex = endPos;
+            endMarkerLength = this.endPrefix.length;
           } else {
-            const nextStartPos = this.buffer.indexOf(this.startPrefix, contentStartIndex);
-            let validEndPos = -1;
-            let searchPos = contentStartIndex;
-            while (true) {
-              const endPos = this.buffer.indexOf(this.endPrefix, searchPos);
-              if (endPos === -1) break;
-              const afterEnd = this.buffer.substring(endPos + this.endPrefix.length);
-              if (afterEnd.startsWith("\n") || afterEnd.startsWith("\r") || afterEnd.startsWith(this.startPrefix) || afterEnd.length === 0) {
-                validEndPos = endPos;
-                break;
-              } else {
-                searchPos = endPos + this.endPrefix.length;
-              }
-            }
-            if (nextStartPos !== -1 && (validEndPos === -1 || nextStartPos < validEndPos)) {
-              partEndIndex = nextStartPos;
-              endMarkerLength = 0;
-            } else if (validEndPos !== -1) {
-              partEndIndex = validEndPos;
-              endMarkerLength = this.endPrefix.length;
-            } else {
-              break;
-            }
+            break;
           }
           const parametersRaw = this.buffer.substring(contentStartIndex, partEndIndex).trim();
           const { parameters, parseError } = this.parseParameters(parametersRaw);
@@ -2870,7 +3161,8 @@ var init_parser = __esm({
               invocationId,
               parametersRaw,
               parameters,
-              parseError
+              parseError,
+              dependencies
             }
           };
           startIndex = partEndIndex + endMarkerLength;
@@ -2893,7 +3185,7 @@ var init_parser = __esm({
           const metadataEndIndex = this.buffer.indexOf("\n", metadataStartIndex);
           if (metadataEndIndex !== -1) {
             const gadgetName = this.buffer.substring(metadataStartIndex, metadataEndIndex).trim();
-            const { actualName: actualGadgetName, invocationId } = this.parseGadgetName(gadgetName);
+            const { actualName: actualGadgetName, invocationId, dependencies } = this.parseGadgetName(gadgetName);
             const contentStartIndex = metadataEndIndex + 1;
             const parametersRaw = this.buffer.substring(contentStartIndex).trim();
             const { parameters, parseError } = this.parseParameters(parametersRaw);
@@ -2904,7 +3196,8 @@ var init_parser = __esm({
                 invocationId,
                 parametersRaw,
                 parameters,
-                parseError
+                parseError,
+                dependencies
               }
             };
             return;
@@ -3274,6 +3567,13 @@ var init_stream_processor = __esm({
       accumulatedText = "";
       shouldStopExecution = false;
       observerFailureCount = 0;
+      // Dependency tracking for gadget execution DAG
+      /** Gadgets waiting for their dependencies to complete */
+      pendingGadgets = /* @__PURE__ */ new Map();
+      /** Completed gadget results, keyed by invocation ID */
+      completedResults = /* @__PURE__ */ new Map();
+      /** Invocation IDs of gadgets that have failed (error or skipped due to dependency) */
+      failedInvocations = /* @__PURE__ */ new Set();
       constructor(options) {
         this.iteration = options.iteration;
         this.registry = options.registry;
@@ -3374,6 +3674,16 @@ var init_stream_processor = __esm({
               }
             }
           }
+          const finalPendingEvents = await this.processPendingGadgets();
+          outputs.push(...finalPendingEvents);
+          if (finalPendingEvents.some((e) => e.type === "gadget_result")) {
+            didExecuteGadgets = true;
+          }
+          for (const evt of finalPendingEvents) {
+            if (evt.type === "gadget_result" && evt.result.breaksLoop) {
+              shouldBreakLoop = true;
+            }
+          }
         }
         let finalMessage = this.accumulatedText;
         if (this.hooks.interceptors?.interceptAssistantMessage) {
@@ -3425,7 +3735,11 @@ var init_stream_processor = __esm({
         return [{ type: "text", content }];
       }
       /**
-       * Process a gadget call through the full lifecycle.
+       * Process a gadget call through the full lifecycle, handling dependencies.
+       *
+       * Gadgets without dependencies (or with all dependencies satisfied) execute immediately.
+       * Gadgets with unsatisfied dependencies are queued for later execution.
+       * After each execution, pending gadgets are checked to see if they can now run.
        */
       async processGadgetCall(call) {
         if (this.shouldStopExecution) {
@@ -3436,6 +3750,53 @@ var init_stream_processor = __esm({
         }
         const events = [];
         events.push({ type: "gadget_call", call });
+        if (call.dependencies.length > 0) {
+          if (call.dependencies.includes(call.invocationId)) {
+            this.logger.warn("Gadget has self-referential dependency (depends on itself)", {
+              gadgetName: call.gadgetName,
+              invocationId: call.invocationId
+            });
+            this.failedInvocations.add(call.invocationId);
+            const skipEvent = {
+              type: "gadget_skipped",
+              gadgetName: call.gadgetName,
+              invocationId: call.invocationId,
+              parameters: call.parameters ?? {},
+              failedDependency: call.invocationId,
+              failedDependencyError: `Gadget "${call.invocationId}" cannot depend on itself (self-referential dependency)`
+            };
+            events.push(skipEvent);
+            return events;
+          }
+          const failedDep = call.dependencies.find((dep) => this.failedInvocations.has(dep));
+          if (failedDep) {
+            const skipEvents = await this.handleFailedDependency(call, failedDep);
+            events.push(...skipEvents);
+            return events;
+          }
+          const unsatisfied = call.dependencies.filter((dep) => !this.completedResults.has(dep));
+          if (unsatisfied.length > 0) {
+            this.logger.debug("Queueing gadget for later - waiting on dependencies", {
+              gadgetName: call.gadgetName,
+              invocationId: call.invocationId,
+              waitingOn: unsatisfied
+            });
+            this.pendingGadgets.set(call.invocationId, call);
+            return events;
+          }
+        }
+        const executeEvents = await this.executeGadgetWithHooks(call);
+        events.push(...executeEvents);
+        const triggeredEvents = await this.processPendingGadgets();
+        events.push(...triggeredEvents);
+        return events;
+      }
+      /**
+       * Execute a gadget through the full hook lifecycle.
+       * This is the core execution logic, extracted from processGadgetCall.
+       */
+      async executeGadgetWithHooks(call) {
+        const events = [];
         if (call.parseError) {
           this.logger.warn("Gadget has parse error", {
             gadgetName: call.gadgetName,
@@ -3566,6 +3927,10 @@ var init_stream_processor = __esm({
           });
         }
         await this.runObserversInParallel(completeObservers);
+        this.completedResults.set(result.invocationId, result);
+        if (result.error) {
+          this.failedInvocations.add(result.invocationId);
+        }
         events.push({ type: "gadget_result", result });
         if (result.error) {
           const errorType = this.determineErrorType(call, result);
@@ -3581,6 +3946,162 @@ var init_stream_processor = __esm({
         }
         return events;
       }
+      /**
+       * Handle a gadget that cannot execute because a dependency failed.
+       * Calls the onDependencySkipped controller to allow customization.
+       */
+      async handleFailedDependency(call, failedDep) {
+        const events = [];
+        const depResult = this.completedResults.get(failedDep);
+        const depError = depResult?.error ?? "Dependency failed";
+        let action = { action: "skip" };
+        if (this.hooks.controllers?.onDependencySkipped) {
+          const context = {
+            iteration: this.iteration,
+            gadgetName: call.gadgetName,
+            invocationId: call.invocationId,
+            parameters: call.parameters ?? {},
+            failedDependency: failedDep,
+            failedDependencyError: depError,
+            logger: this.logger
+          };
+          action = await this.hooks.controllers.onDependencySkipped(context);
+        }
+        if (action.action === "skip") {
+          this.failedInvocations.add(call.invocationId);
+          const skipEvent = {
+            type: "gadget_skipped",
+            gadgetName: call.gadgetName,
+            invocationId: call.invocationId,
+            parameters: call.parameters ?? {},
+            failedDependency: failedDep,
+            failedDependencyError: depError
+          };
+          events.push(skipEvent);
+          if (this.hooks.observers?.onGadgetSkipped) {
+            const observeContext = {
+              iteration: this.iteration,
+              gadgetName: call.gadgetName,
+              invocationId: call.invocationId,
+              parameters: call.parameters ?? {},
+              failedDependency: failedDep,
+              failedDependencyError: depError,
+              logger: this.logger
+            };
+            await this.safeObserve(() => this.hooks.observers.onGadgetSkipped(observeContext));
+          }
+          this.logger.info("Gadget skipped due to failed dependency", {
+            gadgetName: call.gadgetName,
+            invocationId: call.invocationId,
+            failedDependency: failedDep
+          });
+        } else if (action.action === "execute_anyway") {
+          this.logger.info("Executing gadget despite failed dependency (controller override)", {
+            gadgetName: call.gadgetName,
+            invocationId: call.invocationId,
+            failedDependency: failedDep
+          });
+          const executeEvents = await this.executeGadgetWithHooks(call);
+          events.push(...executeEvents);
+        } else if (action.action === "use_fallback") {
+          const fallbackResult = {
+            gadgetName: call.gadgetName,
+            invocationId: call.invocationId,
+            parameters: call.parameters ?? {},
+            result: action.fallbackResult,
+            executionTimeMs: 0
+          };
+          this.completedResults.set(call.invocationId, fallbackResult);
+          events.push({ type: "gadget_result", result: fallbackResult });
+          this.logger.info("Using fallback result for gadget with failed dependency", {
+            gadgetName: call.gadgetName,
+            invocationId: call.invocationId,
+            failedDependency: failedDep
+          });
+        }
+        return events;
+      }
+      /**
+       * Process pending gadgets whose dependencies are now satisfied.
+       * Executes ready gadgets in parallel and continues until no more can be triggered.
+       */
+      async processPendingGadgets() {
+        const events = [];
+        let progress = true;
+        while (progress && this.pendingGadgets.size > 0) {
+          progress = false;
+          const readyToExecute = [];
+          const readyToSkip = [];
+          for (const [invocationId, call] of this.pendingGadgets) {
+            const failedDep = call.dependencies.find((dep) => this.failedInvocations.has(dep));
+            if (failedDep) {
+              readyToSkip.push({ call, failedDep });
+              continue;
+            }
+            const allSatisfied = call.dependencies.every((dep) => this.completedResults.has(dep));
+            if (allSatisfied) {
+              readyToExecute.push(call);
+            }
+          }
+          for (const { call, failedDep } of readyToSkip) {
+            this.pendingGadgets.delete(call.invocationId);
+            const skipEvents = await this.handleFailedDependency(call, failedDep);
+            events.push(...skipEvents);
+            progress = true;
+          }
+          if (readyToExecute.length > 0) {
+            this.logger.debug("Executing ready gadgets in parallel", {
+              count: readyToExecute.length,
+              invocationIds: readyToExecute.map((c) => c.invocationId)
+            });
+            for (const call of readyToExecute) {
+              this.pendingGadgets.delete(call.invocationId);
+            }
+            const executePromises = readyToExecute.map((call) => this.executeGadgetWithHooks(call));
+            const results = await Promise.all(executePromises);
+            for (const executeEvents of results) {
+              events.push(...executeEvents);
+            }
+            progress = true;
+          }
+        }
+        if (this.pendingGadgets.size > 0) {
+          const pendingIds = new Set(this.pendingGadgets.keys());
+          for (const [invocationId, call] of this.pendingGadgets) {
+            const missingDeps = call.dependencies.filter((dep) => !this.completedResults.has(dep));
+            const circularDeps = missingDeps.filter((dep) => pendingIds.has(dep));
+            const trulyMissingDeps = missingDeps.filter((dep) => !pendingIds.has(dep));
+            let errorMessage;
+            let logLevel = "warn";
+            if (circularDeps.length > 0 && trulyMissingDeps.length > 0) {
+              errorMessage = `Dependencies unresolvable: circular=[${circularDeps.join(", ")}], missing=[${trulyMissingDeps.join(", ")}]`;
+              logLevel = "error";
+            } else if (circularDeps.length > 0) {
+              errorMessage = `Circular dependency detected: "${invocationId}" depends on "${circularDeps[0]}" which also depends on "${invocationId}" (directly or indirectly)`;
+            } else {
+              errorMessage = `Dependency "${missingDeps[0]}" was never executed - check that the invocation ID exists and is spelled correctly`;
+            }
+            this.logger[logLevel]("Gadget has unresolvable dependencies", {
+              gadgetName: call.gadgetName,
+              invocationId,
+              circularDependencies: circularDeps,
+              missingDependencies: trulyMissingDeps
+            });
+            this.failedInvocations.add(invocationId);
+            const skipEvent = {
+              type: "gadget_skipped",
+              gadgetName: call.gadgetName,
+              invocationId,
+              parameters: call.parameters ?? {},
+              failedDependency: missingDeps[0],
+              failedDependencyError: errorMessage
+            };
+            events.push(skipEvent);
+          }
+          this.pendingGadgets.clear();
+        }
+        return events;
+      }
       /**
        * Safely execute an observer, catching and logging any errors.
        * Observers are non-critical, so errors are logged but don't crash the system.
@@ -4018,9 +4539,9 @@ var init_agent = __esm({
                   if (msg.role === "user") {
                     this.conversation.addUserMessage(msg.content);
                   } else if (msg.role === "assistant") {
-                    this.conversation.addAssistantMessage(msg.content);
+                    this.conversation.addAssistantMessage(extractText(msg.content));
                   } else if (msg.role === "system") {
-                    this.conversation.addUserMessage(`[System] ${msg.content}`);
+                    this.conversation.addUserMessage(`[System] ${extractText(msg.content)}`);
                   }
                 }
               }
@@ -4599,6 +5120,7 @@ var init_anthropic = __esm({
   "src/providers/anthropic.ts"() {
     "use strict";
     import_sdk = __toESM(require("@anthropic-ai/sdk"), 1);
+    init_messages();
     init_anthropic_models();
     init_base_provider();
     init_constants2();
@@ -4637,7 +5159,7 @@ var init_anthropic = __esm({
         const systemMessages = messages.filter((message) => message.role === "system");
         const system = systemMessages.length > 0 ? systemMessages.map((m, index) => ({
           type: "text",
-          text: m.content,
+          text: extractText(m.content),
           // Add cache_control to the LAST system message block
           ...index === systemMessages.length - 1 ? { cache_control: { type: "ephemeral" } } : {}
         })) : void 0;
@@ -4650,14 +5172,10 @@ var init_anthropic = __esm({
         );
         const conversation = nonSystemMessages.map((message, index) => ({
           role: message.role,
-          content: [
-            {
-              type: "text",
-              text: message.content,
-              // Add cache_control to the LAST user message
-              ...message.role === "user" && index === lastUserIndex ? { cache_control: { type: "ephemeral" } } : {}
-            }
-          ]
+          content: this.convertToAnthropicContent(
+            message.content,
+            message.role === "user" && index === lastUserIndex
+          )
         }));
         const defaultMaxTokens = spec?.maxOutputTokens ?? ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS;
         const payload = {
@@ -4673,6 +5191,52 @@ var init_anthropic = __esm({
         };
         return payload;
       }
+      /**
+       * Convert llmist content to Anthropic's content block format.
+       * Handles text, images (base64 only), and applies cache_control.
+       */
+      convertToAnthropicContent(content, addCacheControl) {
+        const parts = normalizeContent(content);
+        return parts.map((part, index) => {
+          const isLastPart = index === parts.length - 1;
+          const cacheControl = addCacheControl && isLastPart ? { cache_control: { type: "ephemeral" } } : {};
+          if (part.type === "text") {
+            return {
+              type: "text",
+              text: part.text,
+              ...cacheControl
+            };
+          }
+          if (part.type === "image") {
+            return this.convertImagePart(part, cacheControl);
+          }
+          if (part.type === "audio") {
+            throw new Error(
+              "Anthropic does not support audio input. Use Google Gemini for audio processing."
+            );
+          }
+          throw new Error(`Unsupported content type: ${part.type}`);
+        });
+      }
+      /**
+       * Convert an image content part to Anthropic's image block format.
+       */
+      convertImagePart(part, cacheControl) {
+        if (part.source.type === "url") {
+          throw new Error(
+            "Anthropic does not support image URLs. Please provide base64-encoded image data instead."
+          );
+        }
+        return {
+          type: "image",
+          source: {
+            type: "base64",
+            media_type: part.source.mediaType,
+            data: part.source.data
+          },
+          ...cacheControl
+        };
+      }
       async executeStreamRequest(payload, signal) {
         const client = this.client;
         const stream2 = await client.messages.create(payload, signal ? { signal } : void 0);
@@ -4755,17 +5319,12 @@ var init_anthropic = __esm({
       async countTokens(messages, descriptor, _spec) {
         const client = this.client;
         const systemMessages = messages.filter((message) => message.role === "system");
-        const system = systemMessages.length > 0 ? systemMessages.map((m) => m.content).join("\n\n") : void 0;
+        const system = systemMessages.length > 0 ? systemMessages.map((m) => extractText(m.content)).join("\n\n") : void 0;
         const conversation = messages.filter(
           (message) => message.role !== "system"
         ).map((message) => ({
           role: message.role,
-          content: [
-            {
-              type: "text",
-              text: message.content
-            }
-          ]
+          content: this.convertToAnthropicContent(message.content, false)
         }));
         try {
           const response = await client.messages.countTokens({
@@ -4779,8 +5338,19 @@ var init_anthropic = __esm({
             `Token counting failed for ${descriptor.name}, using fallback estimation:`,
             error
           );
-          const totalChars = messages.reduce((sum, msg) => sum + (msg.content?.length ?? 0), 0);
-          return Math.ceil(totalChars / FALLBACK_CHARS_PER_TOKEN);
+          let totalChars = 0;
+          let imageCount = 0;
+          for (const msg of messages) {
+            const parts = normalizeContent(msg.content);
+            for (const part of parts) {
+              if (part.type === "text") {
+                totalChars += part.text.length;
+              } else if (part.type === "image") {
+                imageCount++;
+              }
+            }
+          }
+          return Math.ceil(totalChars / FALLBACK_CHARS_PER_TOKEN) + imageCount * 1e3;
         }
       }
     };
@@ -5309,6 +5879,7 @@ var init_gemini = __esm({
   "src/providers/gemini.ts"() {
     "use strict";
     import_genai = require("@google/genai");
+    init_messages();
     init_base_provider();
     init_constants2();
     init_gemini_image_models();
@@ -5478,7 +6049,7 @@ var init_gemini = __esm({
         };
         return {
           model: descriptor.name,
-          contents: this.convertContentsForNewSDK(contents),
+          contents,
           config
         };
       }
@@ -5513,18 +6084,25 @@ var init_gemini = __esm({
           if (message.role === "system") {
             expandedMessages.push({
               role: "user",
-              content: message.content
+              content: extractText(message.content)
             });
             expandedMessages.push({
               role: "assistant",
               content: "Understood."
             });
           } else {
-            expandedMessages.push(message);
+            expandedMessages.push({
+              role: message.role,
+              content: message.content
+            });
           }
         }
         return this.mergeConsecutiveMessages(expandedMessages);
       }
+      /**
+       * Merge consecutive messages with the same role (required by Gemini).
+       * Handles multimodal content by converting to Gemini's part format.
+       */
       mergeConsecutiveMessages(messages) {
         if (messages.length === 0) {
           return [];
@@ -5533,15 +6111,16 @@ var init_gemini = __esm({
         let currentGroup = null;
         for (const message of messages) {
           const geminiRole = GEMINI_ROLE_MAP[message.role];
+          const geminiParts = this.convertToGeminiParts(message.content);
           if (currentGroup && currentGroup.role === geminiRole) {
-            currentGroup.parts.push({ text: message.content });
+            currentGroup.parts.push(...geminiParts);
           } else {
             if (currentGroup) {
               result.push(currentGroup);
             }
             currentGroup = {
               role: geminiRole,
-              parts: [{ text: message.content }]
+              parts: geminiParts
             };
           }
         }
@@ -5550,11 +6129,39 @@ var init_gemini = __esm({
         }
         return result;
       }
-      convertContentsForNewSDK(contents) {
-        return contents.map((content) => ({
-          role: content.role,
-          parts: content.parts.map((part) => ({ text: part.text }))
-        }));
+      /**
+       * Convert llmist content to Gemini's part format.
+       * Handles text, images, and audio (Gemini supports all three).
+       */
+      convertToGeminiParts(content) {
+        const parts = normalizeContent(content);
+        return parts.map((part) => {
+          if (part.type === "text") {
+            return { text: part.text };
+          }
+          if (part.type === "image") {
+            if (part.source.type === "url") {
+              throw new Error(
+                "Gemini does not support image URLs directly. Please provide base64-encoded image data."
+              );
+            }
+            return {
+              inlineData: {
+                mimeType: part.source.mediaType,
+                data: part.source.data
+              }
+            };
+          }
+          if (part.type === "audio") {
+            return {
+              inlineData: {
+                mimeType: part.source.mediaType,
+                data: part.source.data
+              }
+            };
+          }
+          throw new Error(`Unsupported content type: ${part.type}`);
+        });
       }
       buildGenerationConfig(options) {
         const config = {};
@@ -5575,9 +6182,9 @@ var init_gemini = __esm({
       async *wrapStream(iterable) {
         const stream2 = iterable;
         for await (const chunk of stream2) {
-          const text = this.extractText(chunk);
-          if (text) {
-            yield { text, rawEvent: chunk };
+          const text3 = this.extractText(chunk);
+          if (text3) {
+            yield { text: text3, rawEvent: chunk };
           }
           const finishReason = this.extractFinishReason(chunk);
           const usage = this.extractUsage(chunk);
@@ -5638,7 +6245,7 @@ var init_gemini = __esm({
         try {
           const response = await client.models.countTokens({
             model: descriptor.name,
-            contents: this.convertContentsForNewSDK(contents)
+            contents
             // Note: systemInstruction not used - it's not supported by countTokens()
             // and would cause a 2100% token counting error
           });
@@ -5648,8 +6255,19 @@ var init_gemini = __esm({
             `Token counting failed for ${descriptor.name}, using fallback estimation:`,
             error
           );
-          const totalChars = messages.reduce((sum, msg) => sum + (msg.content?.length ?? 0), 0);
-          return Math.ceil(totalChars / FALLBACK_CHARS_PER_TOKEN);
+          let totalChars = 0;
+          let mediaCount = 0;
+          for (const msg of messages) {
+            const parts = normalizeContent(msg.content);
+            for (const part of parts) {
+              if (part.type === "text") {
+                totalChars += part.text.length;
+              } else if (part.type === "image" || part.type === "audio") {
+                mediaCount++;
+              }
+            }
+          }
+          return Math.ceil(totalChars / FALLBACK_CHARS_PER_TOKEN) + mediaCount * 258;
         }
       }
     };
@@ -6292,6 +6910,7 @@ var init_openai = __esm({
     "use strict";
     import_openai = __toESM(require("openai"), 1);
     import_tiktoken = require("tiktoken");
+    init_messages();
     init_base_provider();
     init_constants2();
     init_openai_image_models();
@@ -6399,11 +7018,7 @@ var init_openai = __esm({
         const sanitizedExtra = sanitizeExtra(extra, shouldIncludeTemperature);
         return {
           model: descriptor.name,
-          messages: messages.map((message) => ({
-            role: ROLE_MAP[message.role],
-            content: message.content,
-            name: message.name
-          })),
+          messages: messages.map((message) => this.convertToOpenAIMessage(message)),
           // Only set max_completion_tokens if explicitly provided
           // Otherwise let the API use "as much as fits" in the context window
           ...maxTokens !== void 0 ? { max_completion_tokens: maxTokens } : {},
@@ -6415,6 +7030,77 @@ var init_openai = __esm({
           ...shouldIncludeTemperature ? { temperature } : {}
         };
       }
+      /**
+       * Convert an LLMMessage to OpenAI's ChatCompletionMessageParam.
+       * Handles role-specific content type requirements:
+       * - system/assistant: string content only
+       * - user: string or multimodal array content
+       */
+      convertToOpenAIMessage(message) {
+        const role = ROLE_MAP[message.role];
+        if (role === "user") {
+          const content = this.convertToOpenAIContent(message.content);
+          return {
+            role: "user",
+            content,
+            ...message.name ? { name: message.name } : {}
+          };
+        }
+        const textContent = typeof message.content === "string" ? message.content : extractText(message.content);
+        if (role === "system") {
+          return {
+            role: "system",
+            content: textContent,
+            ...message.name ? { name: message.name } : {}
+          };
+        }
+        return {
+          role: "assistant",
+          content: textContent,
+          ...message.name ? { name: message.name } : {}
+        };
+      }
+      /**
+       * Convert llmist content to OpenAI's content format.
+       * Optimizes by returning string for text-only content, array for multimodal.
+       */
+      convertToOpenAIContent(content) {
+        if (typeof content === "string") {
+          return content;
+        }
+        return content.map((part) => {
+          if (part.type === "text") {
+            return { type: "text", text: part.text };
+          }
+          if (part.type === "image") {
+            return this.convertImagePart(part);
+          }
+          if (part.type === "audio") {
+            throw new Error(
+              "OpenAI chat completions do not support audio input. Use Whisper for transcription or Gemini for audio understanding."
+            );
+          }
+          throw new Error(`Unsupported content type: ${part.type}`);
+        });
+      }
+      /**
+       * Convert an image content part to OpenAI's image_url format.
+       * Supports both URLs and base64 data URLs.
+       */
+      convertImagePart(part) {
+        if (part.source.type === "url") {
+          return {
+            type: "image_url",
+            image_url: { url: part.source.url }
+          };
+        }
+        return {
+          type: "image_url",
+          image_url: {
+            url: `data:${part.source.mediaType};base64,${part.source.data}`
+          }
+        };
+      }
       async executeStreamRequest(payload, signal) {
         const client = this.client;
         const stream2 = await client.chat.completions.create(payload, signal ? { signal } : void 0);
@@ -6423,9 +7109,9 @@ var init_openai = __esm({
       async *wrapStream(iterable) {
         const stream2 = iterable;
         for await (const chunk of stream2) {
-          const text = chunk.choices.map((choice) => choice.delta?.content ?? "").join("");
-          if (text) {
-            yield { text, rawEvent: chunk };
+          const text3 = chunk.choices.map((choice) => choice.delta?.content ?? "").join("");
+          if (text3) {
+            yield { text: text3, rawEvent: chunk };
           }
           const finishReason = chunk.choices.find((choice) => choice.finish_reason)?.finish_reason;
           const usage = chunk.usage ? {
@@ -6473,17 +7159,26 @@ var init_openai = __esm({
           }
           try {
             let tokenCount = 0;
+            let imageCount = 0;
             for (const message of messages) {
               tokenCount += OPENAI_MESSAGE_OVERHEAD_TOKENS;
               const roleText = ROLE_MAP[message.role];
               tokenCount += encoding.encode(roleText).length;
-              tokenCount += encoding.encode(message.content ?? "").length;
+              const textContent = extractText(message.content);
+              tokenCount += encoding.encode(textContent).length;
+              const parts = normalizeContent(message.content);
+              for (const part of parts) {
+                if (part.type === "image") {
+                  imageCount++;
+                }
+              }
               if (message.name) {
                 tokenCount += encoding.encode(message.name).length;
                 tokenCount += OPENAI_NAME_FIELD_OVERHEAD_TOKENS;
               }
             }
             tokenCount += OPENAI_REPLY_PRIMING_TOKENS;
+            tokenCount += imageCount * 765;
             return tokenCount;
           } finally {
             encoding.free();
@@ -6493,8 +7188,19 @@ var init_openai = __esm({
             `Token counting failed for ${descriptor.name}, using fallback estimation:`,
             error
           );
-          const totalChars = messages.reduce((sum, msg) => sum + (msg.content?.length ?? 0), 0);
-          return Math.ceil(totalChars / FALLBACK_CHARS_PER_TOKEN);
+          let totalChars = 0;
+          let imageCount = 0;
+          for (const msg of messages) {
+            const parts = normalizeContent(msg.content);
+            for (const part of parts) {
+              if (part.type === "text") {
+                totalChars += part.text.length;
+              } else if (part.type === "image") {
+                imageCount++;
+              }
+            }
+          }
+          return Math.ceil(totalChars / FALLBACK_CHARS_PER_TOKEN) + imageCount * 765;
         }
       }
     };
@@ -6917,6 +7623,138 @@ var init_text = __esm({
   }
 });
 
+// src/core/namespaces/vision.ts
+var VisionNamespace;
+var init_vision = __esm({
+  "src/core/namespaces/vision.ts"() {
+    "use strict";
+    init_input_content();
+    init_messages();
+    VisionNamespace = class {
+      constructor(client) {
+        this.client = client;
+      }
+      /**
+       * Build a message builder with the image content attached.
+       * Handles URLs, data URLs, base64 strings, and binary buffers.
+       */
+      buildImageMessage(options) {
+        const builder = new LLMMessageBuilder();
+        if (options.systemPrompt) {
+          builder.addSystem(options.systemPrompt);
+        }
+        if (typeof options.image === "string") {
+          if (options.image.startsWith("http://") || options.image.startsWith("https://")) {
+            builder.addUserWithImageUrl(options.prompt, options.image);
+          } else if (isDataUrl(options.image)) {
+            const parsed = parseDataUrl(options.image);
+            if (!parsed) {
+              throw new Error("Invalid data URL format");
+            }
+            builder.addUserWithImage(
+              options.prompt,
+              parsed.data,
+              parsed.mimeType
+            );
+          } else {
+            const buffer = Buffer.from(options.image, "base64");
+            builder.addUserWithImage(options.prompt, buffer, options.mimeType);
+          }
+        } else {
+          builder.addUserWithImage(options.prompt, options.image, options.mimeType);
+        }
+        return builder;
+      }
+      /**
+       * Stream the response and collect text and usage information.
+       */
+      async streamAndCollect(options, builder) {
+        let response = "";
+        let finalUsage;
+        for await (const chunk of this.client.stream({
+          model: options.model,
+          messages: builder.build(),
+          maxTokens: options.maxTokens,
+          temperature: options.temperature
+        })) {
+          response += chunk.text;
+          if (chunk.usage) {
+            finalUsage = {
+              inputTokens: chunk.usage.inputTokens,
+              outputTokens: chunk.usage.outputTokens,
+              totalTokens: chunk.usage.totalTokens
+            };
+          }
+        }
+        return { text: response.trim(), usage: finalUsage };
+      }
+      /**
+       * Analyze an image with a vision-capable model.
+       * Returns the analysis as a string.
+       *
+       * @param options - Vision analysis options
+       * @returns Promise resolving to the analysis text
+       * @throws Error if the image format is unsupported or model doesn't support vision
+       *
+       * @example
+       * ```typescript
+       * // From file
+       * const result = await llmist.vision.analyze({
+       *   model: "gpt-4o",
+       *   image: await fs.readFile("photo.jpg"),
+       *   prompt: "What's in this image?",
+       * });
+       *
+       * // From URL (OpenAI only)
+       * const result = await llmist.vision.analyze({
+       *   model: "gpt-4o",
+       *   image: "https://example.com/image.jpg",
+       *   prompt: "Describe this image",
+       * });
+       * ```
+       */
+      async analyze(options) {
+        const builder = this.buildImageMessage(options);
+        const { text: text3 } = await this.streamAndCollect(options, builder);
+        return text3;
+      }
+      /**
+       * Analyze an image and return detailed result with usage info.
+       *
+       * @param options - Vision analysis options
+       * @returns Promise resolving to the analysis result with usage info
+       */
+      async analyzeWithUsage(options) {
+        const builder = this.buildImageMessage(options);
+        const { text: text3, usage } = await this.streamAndCollect(options, builder);
+        return {
+          text: text3,
+          model: options.model,
+          usage
+        };
+      }
+      /**
+       * Check if a model supports vision/image input.
+       *
+       * @param modelId - Model ID to check
+       * @returns True if the model supports vision
+       */
+      supportsModel(modelId) {
+        const spec = this.client.modelRegistry.getModelSpec(modelId);
+        return spec?.features?.vision === true;
+      }
+      /**
+       * List all models that support vision.
+       *
+       * @returns Array of model IDs that support vision
+       */
+      listModels() {
+        return this.client.modelRegistry.listModels().filter((spec) => spec.features?.vision === true).map((spec) => spec.modelId);
+      }
+    };
+  }
+});
+
 // src/core/options.ts
 var ModelIdentifierParser;
 var init_options = __esm({
@@ -6961,6 +7799,7 @@ var init_client = __esm({
     init_image();
     init_speech();
     init_text();
+    init_vision();
     init_options();
     init_quick_methods();
     LLMist = class _LLMist {
@@ -6972,6 +7811,7 @@ var init_client = __esm({
       text;
       image;
       speech;
+      vision;
       constructor(...args) {
         let adapters = [];
         let defaultProvider;
@@ -7022,6 +7862,7 @@ var init_client = __esm({
         this.text = new TextNamespace(this);
         this.image = new ImageNamespace(this.adapters, this.defaultProvider);
         this.speech = new SpeechNamespace(this.adapters, this.defaultProvider);
+        this.vision = new VisionNamespace(this);
       }
       stream(options) {
         const descriptor = this.parser.parse(options.model);
@@ -7206,6 +8047,7 @@ var init_builder = __esm({
   "src/agent/builder.ts"() {
     "use strict";
     init_constants();
+    init_input_content();
     init_model_shortcuts();
     init_registry();
     init_agent();
@@ -7853,13 +8695,17 @@ ${endPrefix}`
        * }
        * ```
        */
-      ask(userPrompt) {
+      /**
+       * Build AgentOptions with the given user prompt.
+       * Centralizes options construction for ask(), askWithImage(), and askWithContent().
+       */
+      buildAgentOptions(userPrompt) {
         if (!this.client) {
           const { LLMist: LLMistClass } = (init_client(), __toCommonJS(client_exports));
           this.client = new LLMistClass();
         }
         const registry = GadgetRegistry.from(this.gadgets);
-        const options = {
+        return {
           client: this.client,
           model: this.model ?? "openai:gpt-5-nano",
           systemPrompt: this.systemPrompt,
@@ -7885,6 +8731,83 @@ ${endPrefix}`
           compactionConfig: this.compactionConfig,
           signal: this.signal
         };
+      }
+      ask(userPrompt) {
+        const options = this.buildAgentOptions(userPrompt);
+        return new Agent(AGENT_INTERNAL_KEY, options);
+      }
+      /**
+       * Build and create the agent with a multimodal user prompt (text + image).
+       * Returns the Agent instance ready to run.
+       *
+       * @param textPrompt - Text prompt describing what to do with the image
+       * @param imageData - Image data (Buffer, Uint8Array, or base64 string)
+       * @param mimeType - Optional MIME type (auto-detected if not provided)
+       * @returns Configured Agent instance
+       *
+       * @example
+       * ```typescript
+       * const agent = LLMist.createAgent()
+       *   .withModel("gpt-4o")
+       *   .withSystem("You analyze images")
+       *   .askWithImage(
+       *     "What's in this image?",
+       *     await fs.readFile("photo.jpg")
+       *   );
+       *
+       * for await (const event of agent.run()) {
+       *   // handle events
+       * }
+       * ```
+       */
+      askWithImage(textPrompt, 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 userContent = [
+          text(textPrompt),
+          {
+            type: "image",
+            source: {
+              type: "base64",
+              mediaType: detectedMime,
+              data: toBase64(imageBuffer)
+            }
+          }
+        ];
+        const options = this.buildAgentOptions(userContent);
+        return new Agent(AGENT_INTERNAL_KEY, options);
+      }
+      /**
+       * Build and return an Agent configured with multimodal content.
+       * More flexible than askWithImage - accepts any combination of content parts.
+       *
+       * @param content - Array of content parts (text, images, audio)
+       * @returns A configured Agent ready for execution
+       *
+       * @example
+       * ```typescript
+       * import { text, imageFromBuffer, audioFromBuffer } from "llmist";
+       *
+       * const agent = LLMist.createAgent()
+       *   .withModel("gemini:gemini-2.5-flash")
+       *   .askWithContent([
+       *     text("Describe this image and transcribe the audio:"),
+       *     imageFromBuffer(imageData),
+       *     audioFromBuffer(audioData),
+       *   ]);
+       *
+       * for await (const event of agent.run()) {
+       *   // handle events
+       * }
+       * ```
+       */
+      askWithContent(content) {
+        const options = this.buildAgentOptions(content);
         return new Agent(AGENT_INTERNAL_KEY, options);
       }
       /**
@@ -8004,7 +8927,8 @@ var COMMANDS = {
   models: "models",
   gadget: "gadget",
   image: "image",
-  speech: "speech"
+  speech: "speech",
+  vision: "vision"
 };
 var LOG_LEVELS = ["silly", "trace", "debug", "info", "warn", "error", "fatal"];
 var DEFAULT_MODEL = "openai:gpt-5-nano";
@@ -8026,6 +8950,9 @@ var OPTION_FLAGS = {
   dockerRo: "--docker-ro",
   noDocker: "--no-docker",
   dockerDev: "--docker-dev",
+  // Multimodal input options
+  inputImage: "--image <path>",
+  inputAudio: "--audio <path>",
   // Image generation options
   imageSize: "--size <size>",
   imageQuality: "--quality <quality>",
@@ -8051,6 +8978,9 @@ var OPTION_DESCRIPTIONS = {
   noBuiltins: "Disable built-in gadgets (AskUser, TellUser).",
   noBuiltinInteraction: "Disable interactive gadgets (AskUser) while keeping TellUser.",
   quiet: "Suppress all output except content (text and TellUser messages).",
+  // Multimodal input descriptions
+  inputImage: "Image file to include with the prompt (vision models).",
+  inputAudio: "Audio file to include with the prompt (Gemini only).",
   docker: "Run agent in a Docker sandbox container for security isolation.",
   dockerRo: "Run in Docker with current directory mounted read-only.",
   noDocker: "Disable Docker sandboxing (override config).",
@@ -8074,7 +9004,7 @@ var import_commander2 = require("commander");
 // package.json
 var package_default = {
   name: "llmist",
-  version: "2.4.0",
+  version: "2.5.0",
   description: "TypeScript LLM client with streaming tool execution. Tools fire mid-stream. Built-in function calling works with any model\u2014no structured outputs or native tool support required.",
   type: "module",
   main: "dist/index.cjs",
@@ -8196,7 +9126,7 @@ var package_default = {
 };
 
 // src/cli/agent-command.ts
-var import_promises3 = require("readline/promises");
+var import_promises4 = require("readline/promises");
 var import_chalk5 = __toESM(require("chalk"), 1);
 init_builder();
 
@@ -8214,6 +9144,7 @@ function isAbortError(error) {
 }
 
 // src/cli/agent-command.ts
+init_input_content();
 init_registry();
 init_constants2();
 
@@ -8538,15 +9469,84 @@ var finish = createGadget({
 });
 var builtinGadgets = [askUser, tellUser, finish];
 
+// src/cli/file-utils.ts
+var import_promises2 = require("fs/promises");
+var import_node_path3 = require("path");
+init_input_content();
+var DEFAULT_MAX_FILE_SIZE = 50 * 1024 * 1024;
+function formatFileSize(bytes) {
+  if (bytes < 1024) return `${bytes} bytes`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}
+async function checkFileSize(absolutePath, filePath, maxSize) {
+  const stats = await (0, import_promises2.stat)(absolutePath);
+  if (stats.size > maxSize) {
+    throw new Error(
+      `File "${filePath}" is too large (${formatFileSize(stats.size)}). Maximum allowed size is ${formatFileSize(maxSize)}. Consider compressing the file or using a smaller version.`
+    );
+  }
+}
+async function readImageFile(filePath, options = {}) {
+  const absolutePath = (0, import_node_path3.resolve)(filePath);
+  const maxFileSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+  let buffer;
+  try {
+    await checkFileSize(absolutePath, filePath, maxFileSize);
+    buffer = await (0, import_promises2.readFile)(absolutePath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to read image file "${filePath}": ${message}`);
+  }
+  const mimeType = detectImageMimeType(buffer);
+  if (!mimeType) {
+    throw new Error(
+      `File "${filePath}" is not a supported image format. Supported formats: JPEG, PNG, GIF, WebP`
+    );
+  }
+  return imageFromBuffer(buffer, mimeType);
+}
+async function readAudioFile(filePath, options = {}) {
+  const absolutePath = (0, import_node_path3.resolve)(filePath);
+  const maxFileSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+  let buffer;
+  try {
+    await checkFileSize(absolutePath, filePath, maxFileSize);
+    buffer = await (0, import_promises2.readFile)(absolutePath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to read audio file "${filePath}": ${message}`);
+  }
+  const mimeType = detectAudioMimeType(buffer);
+  if (!mimeType) {
+    throw new Error(
+      `File "${filePath}" is not a supported audio format. Supported formats: MP3, WAV, OGG, WebM`
+    );
+  }
+  return audioFromBuffer(buffer, mimeType);
+}
+async function readFileBuffer(filePath, options = {}) {
+  const absolutePath = (0, import_node_path3.resolve)(filePath);
+  const maxFileSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+  try {
+    await checkFileSize(absolutePath, filePath, maxFileSize);
+    return await (0, import_promises2.readFile)(absolutePath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to read file "${filePath}": ${message}`);
+  }
+}
+
 // src/cli/gadgets.ts
 var import_node_fs7 = __toESM(require("fs"), 1);
-var import_node_path6 = __toESM(require("path"), 1);
+var import_node_path7 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 init_gadget();
 
 // src/cli/builtins/filesystem/list-directory.ts
 var import_node_fs4 = __toESM(require("fs"), 1);
-var import_node_path4 = __toESM(require("path"), 1);
+var import_node_path5 = __toESM(require("path"), 1);
 var import_zod4 = require("zod");
 
 // src/index.ts
@@ -8570,6 +9570,7 @@ init_prompt_config();
 
 // src/index.ts
 init_client();
+init_input_content();
 init_messages();
 init_model_registry();
 init_model_shortcuts();
@@ -8600,6 +9601,10 @@ init_logger();
 // src/testing/mock-stream.ts
 init_constants();
 
+// src/testing/mock-builder.ts
+init_input_content();
+init_messages();
+
 // src/testing/mock-client.ts
 init_client();
 
@@ -8611,7 +9616,7 @@ var import_node_stream = require("stream");
 
 // src/cli/builtins/filesystem/utils.ts
 var import_node_fs3 = __toESM(require("fs"), 1);
-var import_node_path3 = __toESM(require("path"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
 var PathSandboxException = class extends Error {
   constructor(inputPath, reason) {
     super(`Path access denied: ${inputPath}. ${reason}`);
@@ -8620,7 +9625,7 @@ var PathSandboxException = class extends Error {
 };
 function validatePathIsWithinCwd(inputPath) {
   const cwd = process.cwd();
-  const resolvedPath = import_node_path3.default.resolve(cwd, inputPath);
+  const resolvedPath = import_node_path4.default.resolve(cwd, inputPath);
   let finalPath;
   try {
     finalPath = import_node_fs3.default.realpathSync(resolvedPath);
@@ -8632,7 +9637,7 @@ function validatePathIsWithinCwd(inputPath) {
       throw error;
     }
   }
-  const cwdWithSep = cwd + import_node_path3.default.sep;
+  const cwdWithSep = cwd + import_node_path4.default.sep;
   if (!finalPath.startsWith(cwdWithSep) && finalPath !== cwd) {
     throw new PathSandboxException(inputPath, "Path is outside the current working directory");
   }
@@ -8645,8 +9650,8 @@ function listFiles(dirPath, basePath = dirPath, maxDepth = 1, currentDepth = 1)
   try {
     const items = import_node_fs4.default.readdirSync(dirPath);
     for (const item of items) {
-      const fullPath = import_node_path4.default.join(dirPath, item);
-      const relativePath = import_node_path4.default.relative(basePath, fullPath);
+      const fullPath = import_node_path5.default.join(dirPath, item);
+      const relativePath = import_node_path5.default.relative(basePath, fullPath);
       try {
         const stats = import_node_fs4.default.lstatSync(fullPath);
         let type;
@@ -8761,7 +9766,7 @@ ${formattedList}`;
 // src/cli/builtins/filesystem/read-file.ts
 var import_node_fs5 = __toESM(require("fs"), 1);
 var import_zod5 = require("zod");
-var readFile = createGadget({
+var readFile2 = createGadget({
   name: "ReadFile",
   description: "Read the entire content of a file and return it as text. The file path must be within the current working directory or its subdirectories.",
   schema: import_zod5.z.object({
@@ -8790,7 +9795,7 @@ ${content}`;
 
 // src/cli/builtins/filesystem/write-file.ts
 var import_node_fs6 = __toESM(require("fs"), 1);
-var import_node_path5 = __toESM(require("path"), 1);
+var import_node_path6 = __toESM(require("path"), 1);
 var import_zod6 = require("zod");
 var writeFile = createGadget({
   name: "WriteFile",
@@ -8825,7 +9830,7 @@ console.log(\`Server running on http://localhost:\${port}\`);`
   ],
   execute: ({ filePath, content }) => {
     const validatedPath = validatePathIsWithinCwd(filePath);
-    const parentDir = import_node_path5.default.dirname(validatedPath);
+    const parentDir = import_node_path6.default.dirname(validatedPath);
     let createdDir = false;
     if (!import_node_fs6.default.existsSync(parentDir)) {
       validatePathIsWithinCwd(parentDir);
@@ -8834,7 +9839,7 @@ console.log(\`Server running on http://localhost:\${port}\`);`
     }
     import_node_fs6.default.writeFileSync(validatedPath, content, "utf-8");
     const bytesWritten = Buffer.byteLength(content, "utf-8");
-    const dirNote = createdDir ? ` (created directory: ${import_node_path5.default.dirname(filePath)})` : "";
+    const dirNote = createdDir ? ` (created directory: ${import_node_path6.default.dirname(filePath)})` : "";
     return `path=${filePath}
 
 Wrote ${bytesWritten} bytes${dirNote}`;
@@ -9032,7 +10037,7 @@ error: ${message}`;
 // src/cli/builtins/index.ts
 var builtinGadgetRegistry = {
   ListDirectory: listDirectory,
-  ReadFile: readFile,
+  ReadFile: readFile2,
   WriteFile: writeFile,
   EditFile: editFile,
   RunCommand: runCommand
@@ -9069,10 +10074,10 @@ function expandHomePath(input) {
   if (!home) {
     return input;
   }
-  return import_node_path6.default.join(home, input.slice(1));
+  return import_node_path7.default.join(home, input.slice(1));
 }
 function isFileLikeSpecifier(specifier) {
-  return PATH_PREFIXES.some((prefix) => specifier.startsWith(prefix)) || specifier.includes(import_node_path6.default.sep);
+  return PATH_PREFIXES.some((prefix) => specifier.startsWith(prefix)) || specifier.includes(import_node_path7.default.sep);
 }
 function tryResolveBuiltin(specifier) {
   if (specifier.startsWith(BUILTIN_PREFIX)) {
@@ -9095,7 +10100,7 @@ function resolveGadgetSpecifier(specifier, cwd) {
     return specifier;
   }
   const expanded = expandHomePath(specifier);
-  const resolvedPath = import_node_path6.default.resolve(cwd, expanded);
+  const resolvedPath = import_node_path7.default.resolve(cwd, expanded);
   if (!import_node_fs7.default.existsSync(resolvedPath)) {
     throw new Error(`Gadget module not found at ${resolvedPath}`);
   }
@@ -9167,13 +10172,14 @@ async function loadGadgets(specifiers, cwd, importer = (specifier) => import(spe
 }
 
 // src/cli/llm-logging.ts
-var import_promises2 = require("fs/promises");
+var import_promises3 = require("fs/promises");
 var import_node_os = require("os");
-var import_node_path7 = require("path");
-var DEFAULT_LLM_LOG_DIR = (0, import_node_path7.join)((0, import_node_os.homedir)(), ".llmist", "logs");
+var import_node_path8 = require("path");
+init_messages();
+var DEFAULT_LLM_LOG_DIR = (0, import_node_path8.join)((0, import_node_os.homedir)(), ".llmist", "logs");
 function resolveLogDir(option, subdir) {
   if (option === true) {
-    return (0, import_node_path7.join)(DEFAULT_LLM_LOG_DIR, subdir);
+    return (0, import_node_path8.join)(DEFAULT_LLM_LOG_DIR, subdir);
   }
   if (typeof option === "string") {
     return option;
@@ -9184,14 +10190,14 @@ function formatLlmRequest(messages) {
   const lines = [];
   for (const msg of messages) {
     lines.push(`=== ${msg.role.toUpperCase()} ===`);
-    lines.push(msg.content ?? "");
+    lines.push(msg.content ? extractText(msg.content) : "");
     lines.push("");
   }
   return lines.join("\n");
 }
 async function writeLogFile(dir, filename, content) {
-  await (0, import_promises2.mkdir)(dir, { recursive: true });
-  await (0, import_promises2.writeFile)((0, import_node_path7.join)(dir, filename), content, "utf-8");
+  await (0, import_promises3.mkdir)(dir, { recursive: true });
+  await (0, import_promises3.writeFile)((0, import_node_path8.join)(dir, filename), content, "utf-8");
 }
 function formatSessionTimestamp(date = /* @__PURE__ */ new Date()) {
   const pad = (n) => n.toString().padStart(2, "0");
@@ -9205,9 +10211,9 @@ function formatSessionTimestamp(date = /* @__PURE__ */ new Date()) {
 }
 async function createSessionDir(baseDir) {
   const timestamp = formatSessionTimestamp();
-  const sessionDir = (0, import_node_path7.join)(baseDir, timestamp);
+  const sessionDir = (0, import_node_path8.join)(baseDir, timestamp);
   try {
-    await (0, import_promises2.mkdir)(sessionDir, { recursive: true });
+    await (0, import_promises3.mkdir)(sessionDir, { recursive: true });
     return sessionDir;
   } catch (error) {
     console.warn(`[llmist] Failed to create log session directory: ${sessionDir}`, error);
@@ -9258,9 +10264,9 @@ function ensureMarkedConfigured() {
     markedConfigured = true;
   }
 }
-function renderMarkdown(text) {
+function renderMarkdown(text3) {
   ensureMarkedConfigured();
-  let rendered = import_marked.marked.parse(text);
+  let rendered = import_marked.marked.parse(text3);
   rendered = rendered.replace(/\*\*(.+?)\*\*/g, (_, content) => import_chalk3.default.bold(content)).replace(/(?<!\*)\*(\S[^*]*)\*(?!\*)/g, (_, content) => import_chalk3.default.italic(content));
   return rendered.trimEnd();
 }
@@ -9274,8 +10280,8 @@ function createRainbowSeparator() {
   }
   return result;
 }
-function renderMarkdownWithSeparators(text) {
-  const rendered = renderMarkdown(text);
+function renderMarkdownWithSeparators(text3) {
+  const rendered = renderMarkdown(text3);
   const separator = createRainbowSeparator();
   return `
 ${separator}
@@ -9443,12 +10449,12 @@ var StreamPrinter = class {
    *
    * @param text - Text to write
    */
-  write(text) {
-    if (!text) {
+  write(text3) {
+    if (!text3) {
       return;
     }
-    this.target.write(text);
-    this.endedWithNewline = text.endsWith("\n");
+    this.target.write(text3);
+    this.endedWithNewline = text3.endsWith("\n");
   }
   /**
    * Ensures output ends with a newline by writing one if needed.
@@ -9927,7 +10933,7 @@ function addCompleteOptions(cmd, defaults) {
     OPTION_DESCRIPTIONS.maxTokens,
     createNumericParser({ label: "Max tokens", integer: true, min: 1 }),
     defaults?.["max-tokens"]
-  ).option(OPTION_FLAGS.quiet, OPTION_DESCRIPTIONS.quiet, defaults?.quiet).option(OPTION_FLAGS.logLlmRequests, OPTION_DESCRIPTIONS.logLlmRequests, defaults?.["log-llm-requests"]);
+  ).option(OPTION_FLAGS.quiet, OPTION_DESCRIPTIONS.quiet, defaults?.quiet).option(OPTION_FLAGS.logLlmRequests, OPTION_DESCRIPTIONS.logLlmRequests, defaults?.["log-llm-requests"]).option(OPTION_FLAGS.inputImage, OPTION_DESCRIPTIONS.inputImage).option(OPTION_FLAGS.inputAudio, OPTION_DESCRIPTIONS.inputAudio);
 }
 function addAgentOptions(cmd, defaults) {
   const gadgetAccumulator = (value, previous = []) => [
@@ -9951,7 +10957,7 @@ function addAgentOptions(cmd, defaults) {
     OPTION_FLAGS.noBuiltinInteraction,
     OPTION_DESCRIPTIONS.noBuiltinInteraction,
     defaults?.["builtin-interaction"] !== false
-  ).option(OPTION_FLAGS.quiet, OPTION_DESCRIPTIONS.quiet, defaults?.quiet).option(OPTION_FLAGS.logLlmRequests, OPTION_DESCRIPTIONS.logLlmRequests, defaults?.["log-llm-requests"]).option(OPTION_FLAGS.docker, OPTION_DESCRIPTIONS.docker).option(OPTION_FLAGS.dockerRo, OPTION_DESCRIPTIONS.dockerRo).option(OPTION_FLAGS.noDocker, OPTION_DESCRIPTIONS.noDocker).option(OPTION_FLAGS.dockerDev, OPTION_DESCRIPTIONS.dockerDev);
+  ).option(OPTION_FLAGS.quiet, OPTION_DESCRIPTIONS.quiet, defaults?.quiet).option(OPTION_FLAGS.logLlmRequests, OPTION_DESCRIPTIONS.logLlmRequests, defaults?.["log-llm-requests"]).option(OPTION_FLAGS.inputImage, OPTION_DESCRIPTIONS.inputImage).option(OPTION_FLAGS.inputAudio, OPTION_DESCRIPTIONS.inputAudio).option(OPTION_FLAGS.docker, OPTION_DESCRIPTIONS.docker).option(OPTION_FLAGS.dockerRo, OPTION_DESCRIPTIONS.dockerRo).option(OPTION_FLAGS.noDocker, OPTION_DESCRIPTIONS.noDocker).option(OPTION_FLAGS.dockerDev, OPTION_DESCRIPTIONS.dockerDev);
 }
 function configToCompleteOptions(config) {
   const result = {};
@@ -10018,7 +11024,7 @@ var DEV_SOURCE_MOUNT_TARGET = "/llmist-src";
 // src/cli/config.ts
 var import_node_fs8 = require("fs");
 var import_node_os2 = require("os");
-var import_node_path8 = require("path");
+var import_node_path9 = require("path");
 var import_js_toml = require("js-toml");
 
 // src/cli/templates.ts
@@ -10179,7 +11185,7 @@ var CUSTOM_CONFIG_KEYS = /* @__PURE__ */ new Set([
   "description"
 ]);
 function getConfigPath() {
-  return (0, import_node_path8.join)((0, import_node_os2.homedir)(), ".llmist", "cli.toml");
+  return (0, import_node_path9.join)((0, import_node_os2.homedir)(), ".llmist", "cli.toml");
 }
 var ConfigError = class extends Error {
   constructor(message, path5) {
@@ -11026,8 +12032,8 @@ function computeDockerfileHash(dockerfile) {
 // src/cli/docker/image-manager.ts
 var import_node_fs9 = require("fs");
 var import_node_os3 = require("os");
-var import_node_path9 = require("path");
-var CACHE_DIR = (0, import_node_path9.join)((0, import_node_os3.homedir)(), ".llmist", "docker-cache");
+var import_node_path10 = require("path");
+var CACHE_DIR = (0, import_node_path10.join)((0, import_node_os3.homedir)(), ".llmist", "docker-cache");
 var HASH_FILE = "image-hash.json";
 function ensureCacheDir() {
   if (!(0, import_node_fs9.existsSync)(CACHE_DIR)) {
@@ -11035,7 +12041,7 @@ function ensureCacheDir() {
   }
 }
 function getCachedHash(imageName) {
-  const hashPath = (0, import_node_path9.join)(CACHE_DIR, HASH_FILE);
+  const hashPath = (0, import_node_path10.join)(CACHE_DIR, HASH_FILE);
   if (!(0, import_node_fs9.existsSync)(hashPath)) {
     return void 0;
   }
@@ -11049,7 +12055,7 @@ function getCachedHash(imageName) {
 }
 function setCachedHash(imageName, hash) {
   ensureCacheDir();
-  const hashPath = (0, import_node_path9.join)(CACHE_DIR, HASH_FILE);
+  const hashPath = (0, import_node_path10.join)(CACHE_DIR, HASH_FILE);
   let cache = {};
   if ((0, import_node_fs9.existsSync)(hashPath)) {
     try {
@@ -11075,7 +12081,7 @@ var DockerBuildError = class extends Error {
 };
 async function buildImage(imageName, dockerfile) {
   ensureCacheDir();
-  const dockerfilePath = (0, import_node_path9.join)(CACHE_DIR, "Dockerfile");
+  const dockerfilePath = (0, import_node_path10.join)(CACHE_DIR, "Dockerfile");
   (0, import_node_fs9.writeFileSync)(dockerfilePath, dockerfile);
   const proc = Bun.spawn(
     ["docker", "build", "-t", imageName, "-f", dockerfilePath, CACHE_DIR],
@@ -11110,7 +12116,7 @@ async function ensureImage(imageName = DEFAULT_IMAGE_NAME, dockerfile) {
 
 // src/cli/docker/docker-wrapper.ts
 var import_node_fs10 = require("fs");
-var import_node_path10 = require("path");
+var import_node_path11 = require("path");
 var import_node_os4 = require("os");
 var DockerUnavailableError = class extends Error {
   constructor() {
@@ -11156,9 +12162,9 @@ function autoDetectDevSource() {
   if (!scriptPath || !scriptPath.endsWith("src/cli.ts")) {
     return void 0;
   }
-  const srcDir = (0, import_node_path10.dirname)(scriptPath);
-  const projectDir = (0, import_node_path10.dirname)(srcDir);
-  const packageJsonPath = (0, import_node_path10.join)(projectDir, "package.json");
+  const srcDir = (0, import_node_path11.dirname)(scriptPath);
+  const projectDir = (0, import_node_path11.dirname)(srcDir);
+  const packageJsonPath = (0, import_node_path11.join)(projectDir, "package.json");
   if (!(0, import_node_fs10.existsSync)(packageJsonPath)) {
     return void 0;
   }
@@ -11307,7 +12313,7 @@ function createHumanInputHandler(env, progress, keyboard) {
       keyboard.cleanupEsc();
       keyboard.cleanupEsc = null;
     }
-    const rl = (0, import_promises3.createInterface)({ input: env.stdin, output: env.stdout });
+    const rl = (0, import_promises4.createInterface)({ input: env.stdin, output: env.stdout });
     try {
       const questionLine = question.trim() ? `
 ${renderMarkdownWithSeparators(question.trim())}` : "";
@@ -11665,8 +12671,8 @@ Denied: ${result.reason ?? "by user"}`
   builder.withTextOnlyHandler("acknowledge");
   builder.withTextWithGadgetsHandler({
     gadgetName: "TellUser",
-    parameterMapping: (text) => ({ message: text, done: false, type: "info" }),
-    resultMapping: (text) => `\u2139\uFE0F  ${text}`
+    parameterMapping: (text3) => ({ message: text3, done: false, type: "info" }),
+    resultMapping: (text3) => `\u2139\uFE0F  ${text3}`
   });
   builder.withTrailingMessage(
     (ctx) => [
@@ -11675,7 +12681,19 @@ Denied: ${result.reason ?? "by user"}`
       "Maximize efficiency by batching independent operations in a single response."
     ].join(" ")
   );
-  const agent = builder.ask(prompt);
+  let agent;
+  if (options.image || options.audio) {
+    const parts = [text(prompt)];
+    if (options.image) {
+      parts.push(await readImageFile(options.image));
+    }
+    if (options.audio) {
+      parts.push(await readAudioFile(options.audio));
+    }
+    agent = builder.askWithContent(parts);
+  } else {
+    agent = builder.ask(prompt);
+  }
   let textBuffer = "";
   const flushTextBuffer = () => {
     if (textBuffer) {
@@ -11750,6 +12768,7 @@ function registerAgentCommand(program, env, config) {
 }
 
 // src/cli/complete-command.ts
+init_input_content();
 init_messages();
 init_model_shortcuts();
 init_constants2();
@@ -11761,7 +12780,18 @@ async function executeComplete(promptArg, options, env) {
   if (options.system) {
     builder.addSystem(options.system);
   }
-  builder.addUser(prompt);
+  if (options.image || options.audio) {
+    const parts = [text(prompt)];
+    if (options.image) {
+      parts.push(await readImageFile(options.image));
+    }
+    if (options.audio) {
+      parts.push(await readAudioFile(options.audio));
+    }
+    builder.addUserMultimodal(parts);
+  } else {
+    builder.addUser(prompt);
+  }
   const messages = builder.build();
   const llmLogsBaseDir = resolveLogDir(options.logLlmRequests, "requests");
   let llmSessionDir;
@@ -11836,7 +12866,7 @@ init_schema_to_json();
 init_schema_validator();
 
 // src/cli/gadget-prompts.ts
-var import_promises4 = require("readline/promises");
+var import_promises5 = require("readline/promises");
 var import_chalk6 = __toESM(require("chalk"), 1);
 init_schema_to_json();
 async function promptForParameters(schema, ctx) {
@@ -11847,7 +12877,7 @@ async function promptForParameters(schema, ctx) {
   if (!jsonSchema.properties || Object.keys(jsonSchema.properties).length === 0) {
     return {};
   }
-  const rl = (0, import_promises4.createInterface)({ input: ctx.stdin, output: ctx.stdout });
+  const rl = (0, import_promises5.createInterface)({ input: ctx.stdin, output: ctx.stdout });
   const params = {};
   try {
     for (const [key, prop] of Object.entries(jsonSchema.properties)) {
@@ -12709,7 +13739,7 @@ var import_node_fs12 = require("fs");
 var DEFAULT_SPEECH_MODEL = "tts-1";
 var DEFAULT_VOICE = "nova";
 async function executeSpeech(textArg, options, env) {
-  const text = await resolvePrompt(textArg, env);
+  const text3 = await resolvePrompt(textArg, env);
   const client = env.createClient();
   const model = options.model;
   const voice = options.voice ?? DEFAULT_VOICE;
@@ -12721,7 +13751,7 @@ async function executeSpeech(textArg, options, env) {
   }
   const result = await client.speech.generate({
     model,
-    input: text,
+    input: text3,
     voice,
     responseFormat: options.format,
     speed
@@ -12754,7 +13784,43 @@ function registerSpeechCommand(program, env, config) {
     OPTION_DESCRIPTIONS.model,
     config?.model ?? DEFAULT_SPEECH_MODEL
   ).option(OPTION_FLAGS.voice, OPTION_DESCRIPTIONS.voice, config?.voice ?? DEFAULT_VOICE).option(OPTION_FLAGS.speechFormat, OPTION_DESCRIPTIONS.speechFormat, config?.format).option(OPTION_FLAGS.speechSpeed, OPTION_DESCRIPTIONS.speechSpeed, config?.speed?.toString()).option(OPTION_FLAGS.speechOutput, OPTION_DESCRIPTIONS.speechOutput, config?.output).option(OPTION_FLAGS.quiet, OPTION_DESCRIPTIONS.quiet, config?.quiet ?? false).action(
-    (text, options) => executeAction(() => executeSpeech(text, options, env), env)
+    (text3, options) => executeAction(() => executeSpeech(text3, options, env), env)
+  );
+}
+
+// src/cli/vision-command.ts
+init_model_shortcuts();
+async function executeVision(imagePath, options, env) {
+  const client = env.createClient();
+  const model = resolveModel(options.model);
+  const imageBuffer = await readFileBuffer(imagePath);
+  const prompt = options.prompt ?? "Describe this image in detail.";
+  const stderrTTY = env.stderr.isTTY === true;
+  if (!options.quiet && stderrTTY) {
+    env.stderr.write(`${SUMMARY_PREFIX} Analyzing image with ${model}...
+`);
+  }
+  const result = await client.vision.analyze({
+    model,
+    image: imageBuffer,
+    prompt,
+    maxTokens: options.maxTokens
+  });
+  env.stdout.write(result);
+  env.stdout.write("\n");
+}
+function registerVisionCommand(program, env) {
+  program.command(COMMANDS.vision ?? "vision").description("Analyze an image using vision-capable models").argument("<image>", "Path to image file to analyze").option(
+    OPTION_FLAGS.model,
+    OPTION_DESCRIPTIONS.model,
+    "gpt-4o"
+    // Default to a vision-capable model
+  ).option("-p, --prompt <prompt>", "Analysis prompt describing what to extract or describe").option(
+    OPTION_FLAGS.maxTokens,
+    OPTION_DESCRIPTIONS.maxTokens,
+    createNumericParser({ label: "Max tokens", integer: true, min: 1 })
+  ).option(OPTION_FLAGS.quiet, OPTION_DESCRIPTIONS.quiet).action(
+    (imagePath, options) => executeAction(() => executeVision(imagePath, options, env), env)
   );
 }
 
@@ -12803,7 +13869,7 @@ function createLoggerFactory(config) {
 }
 function createPromptFunction(stdin, stdout) {
   return (question) => {
-    return new Promise((resolve2) => {
+    return new Promise((resolve3) => {
       const rl = import_node_readline.default.createInterface({
         input: stdin,
         output: stdout
@@ -12818,7 +13884,7 @@ function createPromptFunction(stdin, stdout) {
 `);
       rl.question(import_chalk9.default.green.bold("You: "), (answer) => {
         rl.close();
-        resolve2(answer);
+        resolve3(answer);
       });
     });
   };
@@ -12911,6 +13977,7 @@ function createProgram(env, config) {
   registerAgentCommand(program, env, config?.agent);
   registerImageCommand(program, env, config?.image);
   registerSpeechCommand(program, env, config?.speech);
+  registerVisionCommand(program, env);
   registerModelsCommand(program, env);
   registerGadgetCommand(program, env);
   if (config) {