llmist 2.5.0 → 2.6.0

package/dist/index.cjs

@@ -192,7 +192,9 @@ var init_input_content = __esm({
       // WAV (RIFF)
       { bytes: [82, 73, 70, 70], mimeType: "audio/wav" },
       // WebM
-      { bytes: [26, 69, 223, 163], mimeType: "audio/webm" }
+      { bytes: [26, 69, 223, 163], mimeType: "audio/webm" },
+      // FLAC (fLaC)
+      { bytes: [102, 76, 97, 67], mimeType: "audio/flac" }
     ];
   }
 });
@@ -930,7 +932,7 @@ Produces: { "items": ["first", "second"] }`);
         this.messages.push({ role: "user", content: parts });
         return this;
       }
-      addGadgetCall(gadget, parameters, result) {
+      addGadgetCall(gadget, parameters, result, media, mediaIds) {
         const paramStr = this.formatBlockParameters(parameters, "");
         this.messages.push({
           role: "assistant",
@@ -938,10 +940,25 @@ Produces: { "items": ["first", "second"] }`);
 ${paramStr}
 ${this.endPrefix}`
         });
-        this.messages.push({
-          role: "user",
-          content: `Result: ${result}`
-        });
+        if (media && media.length > 0 && mediaIds && mediaIds.length > 0) {
+          const idRefs = media.map((m, i) => `[Media: ${mediaIds[i]} (${m.kind})]`).join("\n");
+          const textWithIds = `Result: ${result}
+${idRefs}`;
+          const parts = [text(textWithIds)];
+          for (const item of media) {
+            if (item.kind === "image") {
+              parts.push(imageFromBase64(item.data, item.mimeType));
+            } else if (item.kind === "audio") {
+              parts.push(audioFromBase64(item.data, item.mimeType));
+            }
+          }
+          this.messages.push({ role: "user", content: parts });
+        } else {
+          this.messages.push({
+            role: "user",
+            content: `Result: ${result}`
+          });
+        }
         return this;
       }
       /**
@@ -978,6 +995,210 @@ ${this.endPrefix}`
   }
 });
 
+// src/gadgets/media-store.ts
+function getLlmistTmpDir() {
+  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".llmist", "tmp");
+}
+var import_node_crypto, import_promises, import_node_os, import_node_path, MIME_TO_EXTENSION, MediaStore;
+var init_media_store = __esm({
+  "src/gadgets/media-store.ts"() {
+    "use strict";
+    import_node_crypto = require("crypto");
+    import_promises = require("fs/promises");
+    import_node_os = require("os");
+    import_node_path = require("path");
+    MIME_TO_EXTENSION = {
+      // Images
+      "image/png": ".png",
+      "image/jpeg": ".jpg",
+      "image/gif": ".gif",
+      "image/webp": ".webp",
+      "image/svg+xml": ".svg",
+      "image/bmp": ".bmp",
+      "image/tiff": ".tiff",
+      // Audio
+      "audio/mp3": ".mp3",
+      "audio/mpeg": ".mp3",
+      "audio/wav": ".wav",
+      "audio/webm": ".webm",
+      "audio/ogg": ".ogg",
+      "audio/flac": ".flac",
+      "audio/aac": ".aac",
+      // Video
+      "video/mp4": ".mp4",
+      "video/webm": ".webm",
+      "video/ogg": ".ogv",
+      "video/quicktime": ".mov",
+      "video/x-msvideo": ".avi",
+      // Documents
+      "application/pdf": ".pdf",
+      "application/json": ".json",
+      "text/plain": ".txt",
+      "text/html": ".html",
+      "text/css": ".css",
+      "text/javascript": ".js"
+    };
+    MediaStore = class {
+      items = /* @__PURE__ */ new Map();
+      outputDir;
+      counter = 0;
+      initialized = false;
+      /**
+       * Create a new MediaStore.
+       *
+       * @param sessionId - Optional session ID for the output directory.
+       *                    If not provided, a random ID is generated.
+       */
+      constructor(sessionId) {
+        const id = sessionId ?? (0, import_node_crypto.randomBytes)(8).toString("hex");
+        this.outputDir = (0, import_node_path.join)(getLlmistTmpDir(), `media-${id}`);
+      }
+      /**
+       * Get the output directory path.
+       */
+      getOutputDir() {
+        return this.outputDir;
+      }
+      /**
+       * Ensure the output directory exists.
+       * @throws Error if directory creation fails
+       */
+      async ensureDir() {
+        if (this.initialized) return;
+        try {
+          await (0, import_promises.mkdir)(this.outputDir, { recursive: true });
+          this.initialized = true;
+        } catch (error) {
+          throw new Error(
+            `MediaStore: Failed to create directory ${this.outputDir}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+      /**
+       * Generate a unique media ID.
+       * Format: "media_" + 6 random alphanumeric characters
+       */
+      generateId() {
+        const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+        let id = "media_";
+        const bytes = (0, import_node_crypto.randomBytes)(6);
+        for (let i = 0; i < 6; i++) {
+          id += chars[bytes[i] % chars.length];
+        }
+        return id;
+      }
+      /**
+       * Get file extension from MIME type.
+       */
+      getExtension(mimeType) {
+        return MIME_TO_EXTENSION[mimeType] ?? ".bin";
+      }
+      /**
+       * Store media and return stored metadata with ID.
+       *
+       * @param media - The media output from a gadget
+       * @param gadgetName - Name of the gadget that created this media
+       * @returns Stored media information including generated ID
+       * @throws Error if file write fails
+       */
+      async store(media, gadgetName) {
+        await this.ensureDir();
+        const id = this.generateId();
+        const ext = this.getExtension(media.mimeType);
+        const filename = media.fileName ?? `${gadgetName}_${String(++this.counter).padStart(3, "0")}${ext}`;
+        const filePath = (0, import_node_path.join)(this.outputDir, filename);
+        const buffer = Buffer.from(media.data, "base64");
+        try {
+          await (0, import_promises.writeFile)(filePath, buffer);
+        } catch (error) {
+          throw new Error(
+            `MediaStore: Failed to write media file ${filePath}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+        const stored = {
+          id,
+          kind: media.kind,
+          path: filePath,
+          mimeType: media.mimeType,
+          sizeBytes: buffer.length,
+          description: media.description,
+          metadata: media.metadata,
+          gadgetName,
+          createdAt: /* @__PURE__ */ new Date()
+        };
+        this.items.set(id, stored);
+        return stored;
+      }
+      /**
+       * Get stored media by ID.
+       *
+       * @param id - The media ID (e.g., "media_a1b2c3")
+       * @returns The stored media or undefined if not found
+       */
+      get(id) {
+        return this.items.get(id);
+      }
+      /**
+       * Get the actual file path for a media ID.
+       * Convenience method for gadgets that need the raw path.
+       *
+       * @param id - The media ID
+       * @returns The file path or undefined if not found
+       */
+      getPath(id) {
+        return this.items.get(id)?.path;
+      }
+      /**
+       * List all stored media, optionally filtered by kind.
+       *
+       * @param kind - Optional media kind to filter by
+       * @returns Array of stored media items
+       */
+      list(kind) {
+        const all = Array.from(this.items.values());
+        if (kind) {
+          return all.filter((item) => item.kind === kind);
+        }
+        return all;
+      }
+      /**
+       * Get the count of stored media items.
+       */
+      get size() {
+        return this.items.size;
+      }
+      /**
+       * Check if a media ID exists.
+       */
+      has(id) {
+        return this.items.has(id);
+      }
+      /**
+       * Clear in-memory store without deleting files.
+       * Resets the counter but leaves files on disk.
+       */
+      clear() {
+        this.items.clear();
+        this.counter = 0;
+      }
+      /**
+       * Delete all stored files and clear memory.
+       * Removes the entire session directory.
+       */
+      async cleanup() {
+        if (this.initialized) {
+          try {
+            await (0, import_promises.rm)(this.outputDir, { recursive: true, force: true });
+          } catch {
+          }
+          this.initialized = false;
+        }
+        this.clear();
+      }
+    };
+  }
+});
+
 // src/gadgets/exceptions.ts
 var BreakLoopException, HumanInputException, TimeoutException, AbortError;
 var init_exceptions = __esm({
@@ -1050,7 +1271,7 @@ function createLogger(options = {}) {
   let finalType = defaultType;
   if (envLogFile) {
     try {
-      (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(envLogFile), { recursive: true });
+      (0, import_node_fs.mkdirSync)((0, import_node_path2.dirname)(envLogFile), { recursive: true });
       const flags = logReset ? "w" : "a";
       logFileStream = (0, import_node_fs.createWriteStream)(envLogFile, { flags });
       finalType = "hidden";
@@ -1075,12 +1296,12 @@ function createLogger(options = {}) {
   }
   return logger;
 }
-var import_node_fs, import_node_path, import_tslog, LEVEL_NAME_TO_ID, defaultLogger;
+var import_node_fs, import_node_path2, import_tslog, LEVEL_NAME_TO_ID, defaultLogger;
 var init_logger = __esm({
   "src/logging/logger.ts"() {
     "use strict";
     import_node_fs = require("fs");
-    import_node_path = require("path");
+    import_node_path2 = require("path");
     import_tslog = require("tslog");
     LEVEL_NAME_TO_ID = {
       silly: 0,
@@ -1492,7 +1713,9 @@ var init_gadget = __esm({
               parts.push(`# ${example.comment}`);
             }
             parts.push(`${effectiveStartPrefix}${gadgetName}`);
-            parts.push(formatParamsAsBlock(example.params, "", effectiveArgPrefix));
+            parts.push(
+              formatParamsAsBlock(example.params, "", effectiveArgPrefix)
+            );
             parts.push(effectiveEndPrefix);
             if (example.output !== void 0) {
               parts.push("");
@@ -1694,6 +1917,18 @@ var init_output_viewer = __esm({
   }
 });
 
+// src/agent/agent-internal-key.ts
+function isValidAgentKey(key) {
+  return key === AGENT_INTERNAL_KEY;
+}
+var AGENT_INTERNAL_KEY;
+var init_agent_internal_key = __esm({
+  "src/agent/agent-internal-key.ts"() {
+    "use strict";
+    AGENT_INTERNAL_KEY = Symbol("AGENT_INTERNAL_KEY");
+  }
+});
+
 // src/agent/compaction/config.ts
 function resolveCompactionConfig(config = {}) {
   const trigger = config.triggerThresholdPercent ?? DEFAULT_COMPACTION_CONFIG.triggerThresholdPercent;
@@ -1941,9 +2176,9 @@ var init_hybrid = __esm({
 var init_strategies = __esm({
   "src/agent/compaction/strategies/index.ts"() {
     "use strict";
+    init_hybrid();
     init_sliding_window();
     init_summarization();
-    init_hybrid();
   }
 });
 
@@ -2105,98 +2340,6 @@ var init_manager = __esm({
   }
 });
 
-// src/agent/gadget-output-store.ts
-var import_node_crypto, GadgetOutputStore;
-var init_gadget_output_store = __esm({
-  "src/agent/gadget-output-store.ts"() {
-    "use strict";
-    import_node_crypto = require("crypto");
-    GadgetOutputStore = class {
-      outputs = /* @__PURE__ */ new Map();
-      /**
-       * Store a gadget output and return its ID.
-       *
-       * @param gadgetName - Name of the gadget that produced the output
-       * @param content - Full output content to store
-       * @returns Generated ID for retrieving the output later
-       */
-      store(gadgetName, content) {
-        const id = this.generateId(gadgetName);
-        const encoder = new TextEncoder();
-        const stored = {
-          id,
-          gadgetName,
-          content,
-          byteSize: encoder.encode(content).length,
-          lineCount: content.split("\n").length,
-          timestamp: /* @__PURE__ */ new Date()
-        };
-        this.outputs.set(id, stored);
-        return id;
-      }
-      /**
-       * Retrieve a stored output by ID.
-       *
-       * @param id - The output ID (e.g., "Search_d34db33f")
-       * @returns The stored output or undefined if not found
-       */
-      get(id) {
-        return this.outputs.get(id);
-      }
-      /**
-       * Check if an output exists.
-       *
-       * @param id - The output ID to check
-       * @returns True if the output exists
-       */
-      has(id) {
-        return this.outputs.has(id);
-      }
-      /**
-       * Get all stored output IDs.
-       *
-       * @returns Array of output IDs
-       */
-      getIds() {
-        return Array.from(this.outputs.keys());
-      }
-      /**
-       * Get the number of stored outputs.
-       */
-      get size() {
-        return this.outputs.size;
-      }
-      /**
-       * Clear all stored outputs.
-       * Called when the agent run completes.
-       */
-      clear() {
-        this.outputs.clear();
-      }
-      /**
-       * Generate a unique ID for a stored output.
-       * Format: {GadgetName}_{8 hex chars}
-       */
-      generateId(gadgetName) {
-        const hex = (0, import_node_crypto.randomBytes)(4).toString("hex");
-        return `${gadgetName}_${hex}`;
-      }
-    };
-  }
-});
-
-// src/agent/agent-internal-key.ts
-function isValidAgentKey(key) {
-  return key === AGENT_INTERNAL_KEY;
-}
-var AGENT_INTERNAL_KEY;
-var init_agent_internal_key = __esm({
-  "src/agent/agent-internal-key.ts"() {
-    "use strict";
-    AGENT_INTERNAL_KEY = Symbol("AGENT_INTERNAL_KEY");
-  }
-});
-
 // src/agent/conversation-manager.ts
 var ConversationManager;
 var init_conversation_manager = __esm({
@@ -2227,8 +2370,8 @@ var init_conversation_manager = __esm({
       addAssistantMessage(content) {
         this.historyBuilder.addAssistant(content);
       }
-      addGadgetCall(gadgetName, parameters, result) {
-        this.historyBuilder.addGadgetCall(gadgetName, parameters, result);
+      addGadgetCall(gadgetName, parameters, result, media, mediaIds) {
+        this.historyBuilder.addGadgetCall(gadgetName, parameters, result, media, mediaIds);
       }
       getMessages() {
         return [...this.baseMessages, ...this.initialMessages, ...this.historyBuilder.build()];
@@ -2342,6 +2485,86 @@ var init_event_handlers = __esm({
   }
 });
 
+// src/agent/gadget-output-store.ts
+var import_node_crypto2, GadgetOutputStore;
+var init_gadget_output_store = __esm({
+  "src/agent/gadget-output-store.ts"() {
+    "use strict";
+    import_node_crypto2 = require("crypto");
+    GadgetOutputStore = class {
+      outputs = /* @__PURE__ */ new Map();
+      /**
+       * Store a gadget output and return its ID.
+       *
+       * @param gadgetName - Name of the gadget that produced the output
+       * @param content - Full output content to store
+       * @returns Generated ID for retrieving the output later
+       */
+      store(gadgetName, content) {
+        const id = this.generateId(gadgetName);
+        const encoder = new TextEncoder();
+        const stored = {
+          id,
+          gadgetName,
+          content,
+          byteSize: encoder.encode(content).length,
+          lineCount: content.split("\n").length,
+          timestamp: /* @__PURE__ */ new Date()
+        };
+        this.outputs.set(id, stored);
+        return id;
+      }
+      /**
+       * Retrieve a stored output by ID.
+       *
+       * @param id - The output ID (e.g., "Search_d34db33f")
+       * @returns The stored output or undefined if not found
+       */
+      get(id) {
+        return this.outputs.get(id);
+      }
+      /**
+       * Check if an output exists.
+       *
+       * @param id - The output ID to check
+       * @returns True if the output exists
+       */
+      has(id) {
+        return this.outputs.has(id);
+      }
+      /**
+       * Get all stored output IDs.
+       *
+       * @returns Array of output IDs
+       */
+      getIds() {
+        return Array.from(this.outputs.keys());
+      }
+      /**
+       * Get the number of stored outputs.
+       */
+      get size() {
+        return this.outputs.size;
+      }
+      /**
+       * Clear all stored outputs.
+       * Called when the agent run completes.
+       */
+      clear() {
+        this.outputs.clear();
+      }
+      /**
+       * Generate a unique ID for a stored output.
+       * Format: {GadgetName}_{8 hex chars}
+       */
+      generateId(gadgetName) {
+        const hex = (0, import_node_crypto2.randomBytes)(4).toString("hex");
+        return `${gadgetName}_${hex}`;
+      }
+    };
+  }
+});
+
 // src/agent/hook-validators.ts
 function validateBeforeLLMCallAction(action) {
   if (!action || typeof action !== "object" || !("action" in action)) {
@@ -2652,8 +2875,7 @@ var init_schema_introspector = __esm({
             const values = def?.values;
             const value = values?.[0] ?? def?.value;
             if (typeof value === "string") return "string";
-            if (typeof value === "number" || typeof value === "bigint")
-              return "number";
+            if (typeof value === "number" || typeof value === "bigint") return "number";
             if (typeof value === "boolean") return "boolean";
             return "unknown";
           }
@@ -2925,7 +3147,13 @@ var init_cost_reporting_client = __esm({
             cacheCreationInputTokens = chunk.usage.cacheCreationInputTokens ?? 0;
           }
         }
-        this.reportCostFromUsage(model, inputTokens, outputTokens, cachedInputTokens, cacheCreationInputTokens);
+        this.reportCostFromUsage(
+          model,
+          inputTokens,
+          outputTokens,
+          cachedInputTokens,
+          cacheCreationInputTokens
+        );
         return result;
       }
       /**
@@ -2965,7 +3193,13 @@ var init_cost_reporting_client = __esm({
             }
           }
         } finally {
-          this.reportCostFromUsage(model, inputTokens, outputTokens, cachedInputTokens, cacheCreationInputTokens);
+          this.reportCostFromUsage(
+            model,
+            inputTokens,
+            outputTokens,
+            cachedInputTokens,
+            cacheCreationInputTokens
+          );
         }
       }
       /**
@@ -3003,7 +3237,13 @@ var init_cost_reporting_client = __esm({
             }
           } finally {
             if (inputTokens > 0 || outputTokens > 0) {
-              reportCostFromUsage(model, inputTokens, outputTokens, cachedInputTokens, cacheCreationInputTokens);
+              reportCostFromUsage(
+                model,
+                inputTokens,
+                outputTokens,
+                cachedInputTokens,
+                cacheCreationInputTokens
+              );
             }
           }
         }
@@ -3215,7 +3455,11 @@ 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, dependencies } = this.parseGadgetName(gadgetName);
+          const {
+            actualName: actualGadgetName,
+            invocationId,
+            dependencies
+          } = this.parseGadgetName(gadgetName);
           const contentStartIndex = metadataEndIndex + 1;
           let partEndIndex;
           let endMarkerLength = 0;
@@ -3263,7 +3507,11 @@ 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, dependencies } = 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);
@@ -3308,11 +3556,12 @@ var init_executor = __esm({
     init_exceptions();
     init_parser();
     GadgetExecutor = class {
-      constructor(registry, onHumanInputRequired, logger, defaultGadgetTimeoutMs, errorFormatterOptions, client) {
+      constructor(registry, onHumanInputRequired, logger, defaultGadgetTimeoutMs, errorFormatterOptions, client, mediaStore) {
         this.registry = registry;
         this.onHumanInputRequired = onHumanInputRequired;
         this.defaultGadgetTimeoutMs = defaultGadgetTimeoutMs;
         this.client = client;
+        this.mediaStore = mediaStore;
         this.logger = logger ?? createLogger({ name: "llmist:executor" });
         this.errorFormatter = new GadgetErrorFormatter(errorFormatterOptions);
         this.argPrefix = errorFormatterOptions?.argPrefix ?? GADGET_ARG_PREFIX;
@@ -3335,12 +3584,16 @@ var init_executor = __esm({
       }
       /**
        * Normalizes gadget execute result to consistent format.
-       * Handles both string returns (backwards compat) and object returns with cost.
+       * Handles string returns (backwards compat), object returns with cost,
+       * and object returns with media.
        */
       normalizeExecuteResult(raw) {
         if (typeof raw === "string") {
           return { result: raw, cost: 0 };
         }
+        if ("media" in raw && raw.media) {
+          return { result: raw.result, media: raw.media, cost: raw.cost ?? 0 };
+        }
         return { result: raw.result, cost: raw.cost ?? 0 };
       }
       // Execute a gadget call asynchronously
@@ -3467,8 +3720,21 @@ var init_executor = __esm({
           } else {
             rawResult = await Promise.resolve(gadget.execute(validatedParameters, ctx));
           }
-          const { result, cost: returnCost } = this.normalizeExecuteResult(rawResult);
+          const { result, media, cost: returnCost } = this.normalizeExecuteResult(rawResult);
           const totalCost = callbackCost + returnCost;
+          let mediaIds;
+          let storedMedia;
+          if (media && media.length > 0 && this.mediaStore) {
+            storedMedia = await Promise.all(
+              media.map((item) => this.mediaStore.store(item, call.gadgetName))
+            );
+            mediaIds = storedMedia.map((m) => m.id);
+            this.logger.debug("Stored media outputs", {
+              gadgetName: call.gadgetName,
+              mediaIds,
+              count: media.length
+            });
+          }
           const executionTimeMs = Date.now() - startTime;
           this.logger.info("Gadget executed successfully", {
             gadgetName: call.gadgetName,
@@ -3476,7 +3742,8 @@ var init_executor = __esm({
             executionTimeMs,
             cost: totalCost > 0 ? totalCost : void 0,
             callbackCost: callbackCost > 0 ? callbackCost : void 0,
-            returnCost: returnCost > 0 ? returnCost : void 0
+            returnCost: returnCost > 0 ? returnCost : void 0,
+            mediaCount: media?.length
           });
           this.logger.debug("Gadget result", {
             gadgetName: call.gadgetName,
@@ -3484,7 +3751,8 @@ var init_executor = __esm({
             parameters: validatedParameters,
             result,
             cost: totalCost,
-            executionTimeMs
+            executionTimeMs,
+            mediaIds
           });
           return {
             gadgetName: call.gadgetName,
@@ -3492,7 +3760,10 @@ var init_executor = __esm({
             parameters: validatedParameters,
             result,
             executionTimeMs,
-            cost: totalCost
+            cost: totalCost,
+            media,
+            mediaIds,
+            storedMedia
           };
         } catch (error) {
           if (error instanceof BreakLoopException) {
@@ -3670,7 +3941,8 @@ var init_stream_processor = __esm({
           this.logger.getSubLogger({ name: "executor" }),
           options.defaultGadgetTimeoutMs,
           { argPrefix: options.gadgetArgPrefix },
-          options.client
+          options.client,
+          options.mediaStore
         );
       }
       /**
@@ -4259,13 +4531,14 @@ var init_agent = __esm({
     init_constants();
     init_messages();
     init_model_shortcuts();
+    init_media_store();
     init_output_viewer();
     init_logger();
-    init_manager();
-    init_gadget_output_store();
     init_agent_internal_key();
+    init_manager();
     init_conversation_manager();
     init_event_handlers();
+    init_gadget_output_store();
     init_hook_validators();
     init_stream_processor();
     Agent = class {
@@ -4294,6 +4567,8 @@ var init_agent = __esm({
       outputLimitCharLimit;
       // Context compaction
       compactionManager;
+      // Media storage (for gadgets returning images, audio, etc.)
+      mediaStore;
       // Cancellation
       signal;
       /**
@@ -4324,6 +4599,7 @@ var init_agent = __esm({
         this.defaultMaxTokens = this.resolveMaxTokensFromCatalog(options.model);
         this.outputLimitEnabled = options.gadgetOutputLimit ?? DEFAULT_GADGET_OUTPUT_LIMIT;
         this.outputStore = new GadgetOutputStore();
+        this.mediaStore = new MediaStore();
         const limitPercent = options.gadgetOutputLimitPercent ?? DEFAULT_GADGET_OUTPUT_LIMIT_PERCENT;
         const limits = this.client.modelRegistry.getModelLimits(this.model);
         const contextWindow = limits?.contextWindow ?? FALLBACK_CONTEXT_WINDOW;
@@ -4389,6 +4665,36 @@ var init_agent = __esm({
       getRegistry() {
         return this.registry;
       }
+      /**
+       * Get the media store for this agent session.
+       *
+       * The media store holds all media outputs (images, audio, etc.) produced by gadgets
+       * during this agent's execution. Use this to:
+       * - Access stored media files by ID
+       * - List all stored media
+       * - Clean up temporary files after execution
+       *
+       * @returns The MediaStore instance for this agent
+       *
+       * @example
+       * ```typescript
+       * const agent = new AgentBuilder()
+       *   .withModel("sonnet")
+       *   .build();
+       *
+       * // After execution, access stored media
+       * const store = agent.getMediaStore();
+       * for (const media of store.list()) {
+       *   console.log(`${media.id}: ${media.path}`);
+       * }
+       *
+       * // Clean up when done
+       * await store.cleanup();
+       * ```
+       */
+      getMediaStore() {
+        return this.mediaStore;
+      }
       /**
        * Manually trigger context compaction.
        *
@@ -4564,7 +4870,8 @@ var init_agent = __esm({
               stopOnGadgetError: this.stopOnGadgetError,
               shouldContinueAfterError: this.shouldContinueAfterError,
               defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
-              client: this.client
+              client: this.client,
+              mediaStore: this.mediaStore
             });
             const result = await processor.process(stream2);
             for (const output of result.outputs) {
@@ -4626,7 +4933,9 @@ var init_agent = __esm({
             }
             if (result.didExecuteGadgets) {
               if (this.textWithGadgetsHandler) {
-                const textContent = result.outputs.filter((output) => output.type === "text").map((output) => output.content).join("");
+                const textContent = result.outputs.filter(
+                  (output) => output.type === "text"
+                ).map((output) => output.content).join("");
                 if (textContent.trim()) {
                   const { gadgetName, parameterMapping, resultMapping } = this.textWithGadgetsHandler;
                   this.conversation.addGadgetCall(
@@ -4642,7 +4951,9 @@ var init_agent = __esm({
                   this.conversation.addGadgetCall(
                     gadgetResult.gadgetName,
                     gadgetResult.parameters,
-                    gadgetResult.error ?? gadgetResult.result ?? ""
+                    gadgetResult.error ?? gadgetResult.result ?? "",
+                    gadgetResult.media,
+                    gadgetResult.mediaIds
                   );
                 }
               }
@@ -6857,14 +7168,7 @@ var OPENAI_TTS_VOICES, OPENAI_TTS_EXTENDED_VOICES, OPENAI_TTS_FORMATS, openaiSpe
 var init_openai_speech_models = __esm({
   "src/providers/openai-speech-models.ts"() {
     "use strict";
-    OPENAI_TTS_VOICES = [
-      "alloy",
-      "echo",
-      "fable",
-      "onyx",
-      "nova",
-      "shimmer"
-    ];
+    OPENAI_TTS_VOICES = ["alloy", "echo", "fable", "onyx", "nova", "shimmer"];
     OPENAI_TTS_EXTENDED_VOICES = [
       ...OPENAI_TTS_VOICES,
       "ash",
@@ -7562,9 +7866,7 @@ var init_image = __esm({
         return this.findImageAdapter(modelId) !== void 0;
       }
       findImageAdapter(modelId) {
-        return this.adapters.find(
-          (adapter) => adapter.supportsImageGeneration?.(modelId) ?? false
-        );
+        return this.adapters.find((adapter) => adapter.supportsImageGeneration?.(modelId) ?? false);
       }
     };
   }
@@ -7616,9 +7918,7 @@ var init_speech = __esm({
         return this.findSpeechAdapter(modelId) !== void 0;
       }
       findSpeechAdapter(modelId) {
-        return this.adapters.find(
-          (adapter) => adapter.supportsSpeechGeneration?.(modelId) ?? false
-        );
+        return this.adapters.find((adapter) => adapter.supportsSpeechGeneration?.(modelId) ?? false);
       }
     };
   }
@@ -7729,11 +8029,7 @@ var init_vision = __esm({
             if (!parsed) {
               throw new Error("Invalid data URL format");
             }
-            builder.addUserWithImage(
-              options.prompt,
-              parsed.data,
-              parsed.mimeType
-            );
+            builder.addUserWithImage(options.prompt, parsed.data, parsed.mimeType);
           } else {
             const buffer = Buffer.from(options.image, "base64");
             builder.addUserWithImage(options.prompt, buffer, options.mimeType);
@@ -9021,6 +9317,7 @@ __export(index_exports, {
   LLMMessageBuilder: () => LLMMessageBuilder,
   LLMist: () => LLMist,
   MODEL_ALIASES: () => MODEL_ALIASES,
+  MediaStore: () => MediaStore,
   MockBuilder: () => MockBuilder,
   MockManager: () => MockManager,
   MockProviderAdapter: () => MockProviderAdapter,
@@ -9042,6 +9339,7 @@ __export(index_exports, {
   createGeminiProviderFromEnv: () => createGeminiProviderFromEnv,
   createHints: () => createHints,
   createLogger: () => createLogger,
+  createMedia: () => createMedia,
   createMockAdapter: () => createMockAdapter,
   createMockClient: () => createMockClient,
   createMockStream: () => createMockStream,
@@ -9072,6 +9370,11 @@ __export(index_exports, {
   resolveModel: () => resolveModel,
   resolvePromptTemplate: () => resolvePromptTemplate,
   resolveRulesTemplate: () => resolveRulesTemplate,
+  resultWithAudio: () => resultWithAudio,
+  resultWithFile: () => resultWithFile,
+  resultWithImage: () => resultWithImage,
+  resultWithImages: () => resultWithImages,
+  resultWithMedia: () => resultWithMedia,
   runWithHandlers: () => runWithHandlers,
   stream: () => stream,
   text: () => text,
@@ -9625,9 +9928,7 @@ var HookPresets = class _HookPresets {
           console.log(
             `\u{1F5DC}\uFE0F  Compaction (${ctx.event.strategy}): ${ctx.event.tokensBefore} \u2192 ${ctx.event.tokensAfter} tokens (saved ${saved}, ${percent}%)`
           );
-          console.log(
-            `   Messages: ${ctx.event.messagesBefore} \u2192 ${ctx.event.messagesAfter}`
-          );
+          console.log(`   Messages: ${ctx.event.messagesBefore} \u2192 ${ctx.event.messagesAfter}`);
           if (ctx.stats.totalCompactions > 1) {
             console.log(
               `   Cumulative: ${ctx.stats.totalCompactions} compactions, ${ctx.stats.totalTokensSaved} tokens saved`
@@ -9862,16 +10163,15 @@ var HookPresets = class _HookPresets {
   }
 };
 
-// src/agent/index.ts
-init_conversation_manager();
-init_stream_processor();
-init_gadget_output_store();
-
 // src/agent/compaction/index.ts
 init_config();
-init_strategy();
-init_strategies();
 init_manager();
+init_strategies();
+init_strategy();
+
+// src/agent/index.ts
+init_conversation_manager();
+init_gadget_output_store();
 
 // src/agent/hints.ts
 init_prompt_config();
@@ -9895,11 +10195,7 @@ function iterationProgressHint(options) {
           maxIterations,
           remaining
         };
-        let hint = resolveHintTemplate(
-          template,
-          DEFAULT_HINTS.iterationProgressHint,
-          hintContext
-        );
+        let hint = resolveHintTemplate(template, DEFAULT_HINTS.iterationProgressHint, hintContext);
         if (showUrgency && progress >= 0.8) {
           hint += " \u26A0\uFE0F Running low on iterations - focus on completing the task.";
         }
@@ -9974,6 +10270,9 @@ function createHints(config) {
   return HookPresets.merge(...hooksToMerge);
 }
 
+// src/agent/index.ts
+init_stream_processor();
+
 // src/index.ts
 init_client();
 init_input_content();
@@ -9984,10 +10283,10 @@ init_options();
 init_prompt_config();
 init_quick_methods();
 init_create_gadget();
-init_output_viewer();
 init_exceptions();
 init_executor();
 init_gadget();
+init_output_viewer();
 init_parser();
 init_registry();
 
@@ -10012,6 +10311,119 @@ function Gadget(config) {
   return GadgetBase;
 }
 
+// src/gadgets/helpers.ts
+init_input_content();
+function createMedia(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
+  };
+}
+
+// src/index.ts
+init_media_store();
+
 // src/gadgets/validation.ts
 function validateAndApplyDefaults(schema, params) {
   const result = schema.safeParse(params);
@@ -10049,6 +10461,9 @@ init_discovery();
 init_gemini();
 init_openai();
 
+// src/testing/cli-helpers.ts
+var import_node_stream = require("stream");
+
 // src/testing/mock-manager.ts
 init_logger();
 var MockManager = class _MockManager {
@@ -10601,7 +11016,9 @@ var MockBuilder = class {
    */
   whenMessageContains(text3) {
     this.matchers.push(
-      (ctx) => ctx.messages.some((msg) => extractText(msg.content).toLowerCase().includes(text3.toLowerCase()))
+      (ctx) => ctx.messages.some(
+        (msg) => extractText(msg.content).toLowerCase().includes(text3.toLowerCase())
+      )
     );
     return this;
   }
@@ -11041,9 +11458,6 @@ function createMockClient(options) {
 
 // src/testing/mock-gadget.ts
 init_gadget();
-
-// src/testing/cli-helpers.ts
-var import_node_stream = require("stream");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AbortError,
@@ -11068,6 +11482,7 @@ var import_node_stream = require("stream");
   LLMMessageBuilder,
   LLMist,
   MODEL_ALIASES,
+  MediaStore,
   MockBuilder,
   MockManager,
   MockProviderAdapter,
@@ -11089,6 +11504,7 @@ var import_node_stream = require("stream");
   createGeminiProviderFromEnv,
   createHints,
   createLogger,
+  createMedia,
   createMockAdapter,
   createMockClient,
   createMockStream,
@@ -11119,6 +11535,11 @@ var import_node_stream = require("stream");
   resolveModel,
   resolvePromptTemplate,
   resolveRulesTemplate,
+  resultWithAudio,
+  resultWithFile,
+  resultWithImage,
+  resultWithImages,
+  resultWithMedia,
   runWithHandlers,
   stream,
   text,