llmist 2.5.0 → 2.6.0

package/dist/index.js

@@ -2,10 +2,16 @@ import {
   Gadget,
   HookPresets,
   createHints,
+  createMedia,
   iterationProgressHint,
   parallelGadgetHint,
+  resultWithAudio,
+  resultWithFile,
+  resultWithImage,
+  resultWithImages,
+  resultWithMedia,
   z
-} from "./chunk-IHSZUAYN.js";
+} from "./chunk-4IHLIYW5.js";
 import {
   AbortError,
   AgentBuilder,
@@ -27,6 +33,7 @@ import {
   LLMMessageBuilder,
   LLMist,
   MODEL_ALIASES,
+  MediaStore,
   MockBuilder,
   MockManager,
   MockProviderAdapter,
@@ -81,7 +88,7 @@ import {
   toBase64,
   validateAndApplyDefaults,
   validateGadgetParams
-} from "./chunk-YHS2DYXP.js";
+} from "./chunk-364PEMVT.js";
 export {
   AbortError,
   AgentBuilder,
@@ -105,6 +112,7 @@ export {
   LLMMessageBuilder,
   LLMist,
   MODEL_ALIASES,
+  MediaStore,
   MockBuilder,
   MockManager,
   MockProviderAdapter,
@@ -126,6 +134,7 @@ export {
   createGeminiProviderFromEnv,
   createHints,
   createLogger,
+  createMedia,
   createMockAdapter,
   createMockClient,
   createMockStream,
@@ -156,6 +165,11 @@ export {
   resolveModel,
   resolvePromptTemplate,
   resolveRulesTemplate,
+  resultWithAudio,
+  resultWithFile,
+  resultWithImage,
+  resultWithImages,
+  resultWithMedia,
   runWithHandlers,
   stream,
   text,

package/dist/{mock-stream-ga4KIiwX.d.cts → mock-stream-Jgg5u6Uf.d.cts}

@@ -819,6 +819,81 @@ interface GadgetExample<TParams = Record<string, unknown>> {
     /** Optional description explaining what this example demonstrates */
     comment?: string;
 }
+/**
+ * Supported media types for gadget output.
+ * Extensible via union - add new types as needed.
+ */
+type MediaKind = "image" | "audio" | "video" | "file";
+/**
+ * Type-specific metadata for media outputs.
+ * Extensible via index signature for future media types.
+ */
+interface MediaMetadata {
+    /** Width in pixels (images, video) */
+    width?: number;
+    /** Height in pixels (images, video) */
+    height?: number;
+    /** Duration in milliseconds (audio, video) */
+    durationMs?: number;
+    /** Allow additional metadata for future extensions */
+    [key: string]: unknown;
+}
+/**
+ * Media output from a gadget execution.
+ * Supports images, audio, video, and arbitrary files.
+ *
+ * @example
+ * ```typescript
+ * // Image output
+ * const imageOutput: GadgetMediaOutput = {
+ *   kind: "image",
+ *   data: base64EncodedPng,
+ *   mimeType: "image/png",
+ *   description: "Screenshot of webpage",
+ *   metadata: { width: 1920, height: 1080 }
+ * };
+ * ```
+ */
+interface GadgetMediaOutput {
+    /** Type of media (discriminator for type-specific handling) */
+    kind: MediaKind;
+    /** Base64-encoded media data */
+    data: string;
+    /** Full MIME type (e.g., "image/png", "audio/mp3", "video/mp4") */
+    mimeType: string;
+    /** Human-readable description of the media */
+    description?: string;
+    /** Type-specific metadata */
+    metadata?: MediaMetadata;
+    /** Optional filename to use when saving (if not provided, auto-generated) */
+    fileName?: string;
+}
+/**
+ * Stored media item with metadata and file path.
+ *
+ * Created by MediaStore when a gadget returns media outputs.
+ * Contains the abstract ID, file path, and metadata for display.
+ */
+interface StoredMedia {
+    /** Unique ID for this media item (e.g., "media_a1b2c3") */
+    id: string;
+    /** Type of media */
+    kind: MediaKind;
+    /** Actual file path on disk (internal use) */
+    path: string;
+    /** MIME type */
+    mimeType: string;
+    /** File size in bytes */
+    sizeBytes: number;
+    /** Human-readable description */
+    description?: string;
+    /** Type-specific metadata */
+    metadata?: MediaMetadata;
+    /** Name of the gadget that created this media */
+    gadgetName: string;
+    /** When the media was stored */
+    createdAt: Date;
+}
 interface GadgetExecutionResult {
     gadgetName: string;
     invocationId: string;
@@ -829,6 +904,12 @@ interface GadgetExecutionResult {
     breaksLoop?: boolean;
     /** Cost of gadget execution in USD. Defaults to 0 if not provided by gadget. */
     cost?: number;
+    /** Media outputs from the gadget (images, audio, video, files) */
+    media?: GadgetMediaOutput[];
+    /** Abstract IDs for media outputs (e.g., ["media_a1b2c3"]) */
+    mediaIds?: string[];
+    /** Stored media with paths (for CLI display) */
+    storedMedia?: StoredMedia[];
 }
 /**
  * Result returned by gadget execute() method.
@@ -849,12 +930,41 @@ interface GadgetExecuteResult {
     /** Optional cost in USD (e.g., 0.001 for $0.001) */
     cost?: number;
 }
+/**
+ * Extended result type with media support.
+ * Use this when gadget returns images, audio, video, or files.
+ *
+ * @example
+ * ```typescript
+ * // Return with image
+ * execute: () => ({
+ *   result: "Screenshot captured",
+ *   media: [{
+ *     kind: "image",
+ *     data: base64EncodedPng,
+ *     mimeType: "image/png",
+ *     description: "Screenshot"
+ *   }],
+ *   cost: 0.001
+ * })
+ * ```
+ */
+interface GadgetExecuteResultWithMedia {
+    /** The execution result as a string */
+    result: string;
+    /** Media outputs (images, audio, video, files) */
+    media?: GadgetMediaOutput[];
+    /** Optional cost in USD (e.g., 0.001 for $0.001) */
+    cost?: number;
+}
 /**
  * Union type for backwards-compatible execute() return type.
- * Gadgets can return either a string (legacy, cost = 0) or
- * an object with result and optional cost.
+ * Gadgets can return:
+ * - string (legacy, cost = 0)
+ * - GadgetExecuteResult (result + optional cost)
+ * - GadgetExecuteResultWithMedia (result + optional media + optional cost)
  */
-type GadgetExecuteReturn = string | GadgetExecuteResult;
+type GadgetExecuteReturn = string | GadgetExecuteResult | GadgetExecuteResultWithMedia;
 interface ParsedGadgetCall {
     gadgetName: string;
     invocationId: string;
@@ -1350,7 +1460,7 @@ type ImageMimeType = "image/jpeg" | "image/png" | "image/gif" | "image/webp";
  * Supported audio MIME types for input.
  * Currently only Gemini supports audio input.
  */
-type AudioMimeType = "audio/mp3" | "audio/mpeg" | "audio/wav" | "audio/webm" | "audio/ogg";
+type AudioMimeType = "audio/mp3" | "audio/mpeg" | "audio/wav" | "audio/webm" | "audio/ogg" | "audio/flac";
 /**
  * Base interface for all content parts.
  */
@@ -1811,7 +1921,7 @@ declare class LLMMessageBuilder {
      * ```
      */
     addUserMultimodal(parts: ContentPart[]): this;
-    addGadgetCall(gadget: string, parameters: Record<string, unknown>, result: string): this;
+    addGadgetCall(gadget: string, parameters: Record<string, unknown>, result: string, media?: GadgetMediaOutput[], mediaIds?: string[]): this;
     /**
      * Format parameters as Block format with JSON Pointer paths.
      * Uses the configured argPrefix for consistency with system prompt.
@@ -2372,6 +2482,121 @@ declare class GadgetRegistry {
     clear(): void;
 }
 
+/**
+ * MediaStore: Session-scoped storage for gadget media outputs.
+ *
+ * This module provides an abstraction layer between gadgets and the filesystem.
+ * Instead of exposing raw file paths, it assigns unique IDs to stored media
+ * that can be shared with the LLM and user.
+ *
+ * @example
+ * ```typescript
+ * const store = new MediaStore();
+ *
+ * // Store an image, get back ID
+ * const stored = await store.store({
+ *   kind: "image",
+ *   data: base64EncodedPng,
+ *   mimeType: "image/png",
+ *   description: "Screenshot"
+ * }, "Screenshot");
+ *
+ * console.log(stored.id); // "media_a1b2c3"
+ * console.log(stored.path); // "/tmp/llmist-media-xxx/Screenshot_001.png"
+ *
+ * // Later: retrieve by ID
+ * const retrieved = store.get("media_a1b2c3");
+ * ```
+ */
+
+/**
+ * Session-scoped media storage with ID abstraction.
+ *
+ * Each MediaStore instance manages media for a single agent session.
+ * Media files are stored in a temporary directory and referenced by
+ * short, unique IDs rather than file paths.
+ */
+declare class MediaStore {
+    private readonly items;
+    private readonly outputDir;
+    private counter;
+    private initialized;
+    /**
+     * Create a new MediaStore.
+     *
+     * @param sessionId - Optional session ID for the output directory.
+     *                    If not provided, a random ID is generated.
+     */
+    constructor(sessionId?: string);
+    /**
+     * Get the output directory path.
+     */
+    getOutputDir(): string;
+    /**
+     * Ensure the output directory exists.
+     * @throws Error if directory creation fails
+     */
+    private ensureDir;
+    /**
+     * Generate a unique media ID.
+     * Format: "media_" + 6 random alphanumeric characters
+     */
+    private generateId;
+    /**
+     * Get file extension from MIME type.
+     */
+    private getExtension;
+    /**
+     * 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
+     */
+    store(media: GadgetMediaOutput, gadgetName: string): Promise<StoredMedia>;
+    /**
+     * 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: string): StoredMedia | undefined;
+    /**
+     * 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: string): string | undefined;
+    /**
+     * List all stored media, optionally filtered by kind.
+     *
+     * @param kind - Optional media kind to filter by
+     * @returns Array of stored media items
+     */
+    list(kind?: MediaKind): StoredMedia[];
+    /**
+     * Get the count of stored media items.
+     */
+    get size(): number;
+    /**
+     * Check if a media ID exists.
+     */
+    has(id: string): boolean;
+    /**
+     * Clear in-memory store without deleting files.
+     * Resets the counter but leaves files on disk.
+     */
+    clear(): void;
+    /**
+     * Delete all stored files and clear memory.
+     * Removes the entire session directory.
+     */
+    cleanup(): Promise<void>;
+}
+
 /**
  * Internal key for Agent instantiation.
  * This Symbol is used to ensure only AgentBuilder can create Agent instances.
@@ -3183,6 +3408,7 @@ declare class Agent {
     private readonly outputLimitEnabled;
     private readonly outputLimitCharLimit;
     private readonly compactionManager?;
+    private readonly mediaStore;
     private readonly signal?;
     /**
      * Creates a new Agent instance.
@@ -3208,6 +3434,34 @@ declare class Agent {
      * ```
      */
     getRegistry(): GadgetRegistry;
+    /**
+     * 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(): MediaStore;
     /**
      * Manually trigger context compaction.
      *
@@ -3981,8 +4235,9 @@ interface IConversationManager {
     addAssistantMessage(content: string): void;
     /**
      * Adds a gadget call and its result to the conversation.
+     * Optionally includes media outputs (images, audio, etc.) for multimodal results.
      */
-    addGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): void;
+    addGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string, media?: GadgetMediaOutput[], mediaIds?: string[]): void;
     /**
      * Gets the complete conversation history including base messages (system prompts, gadget instructions).
      */
@@ -4718,4 +4973,4 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
-export { type TrailingMessage as $, type AgentHooks as A, BaseGadget as B, type CompactionStrategy as C, type GadgetExecuteReturn as D, type ExecutionContext as E, type GadgetExample as F, GadgetRegistry as G, type HintTemplate as H, type IConversationManager as I, type GadgetExecutionResult as J, type ProviderAdapter as K, type LLMStream as L, MockProviderAdapter as M, type ModelDescriptor as N, type ModelSpec as O, type ParsedGadgetCall as P, type LLMGenerationOptions as Q, type ResolvedCompactionConfig as R, type StreamEvent as S, type TokenUsage as T, type ImageModelSpec as U, type ImageGenerationOptions as V, type ImageGenerationResult as W, type SpeechModelSpec as X, type SpeechGenerationOptions as Y, type SpeechGenerationResult as Z, type HistoryMessage as _, type LLMStreamChunk as a, type VisionAnalyzeOptions as a$, type TrailingMessageContext as a0, AgentBuilder as a1, type EventHandlers as a2, collectEvents as a3, collectText as a4, runWithHandlers as a5, type AfterGadgetExecutionAction as a6, type AfterGadgetExecutionControllerContext as a7, type AfterLLMCallAction as a8, type AfterLLMCallControllerContext as a9, type AudioMimeType as aA, type AudioSource as aB, type ContentPart as aC, type ImageBase64Source as aD, type ImageContentPart as aE, type ImageMimeType as aF, type ImageSource as aG, type ImageUrlSource as aH, type TextContentPart as aI, audioFromBase64 as aJ, audioFromBuffer as aK, detectAudioMimeType as aL, detectImageMimeType as aM, imageFromBase64 as aN, imageFromBuffer as aO, imageFromUrl as aP, isAudioPart as aQ, isDataUrl as aR, isImagePart as aS, isTextPart as aT, parseDataUrl as aU, text as aV, toBase64 as aW, type LLMRole as aX, extractText as aY, LLMMessageBuilder as aZ, normalizeContent as a_, type AfterLLMErrorAction as aa, type AgentOptions as ab, type BeforeGadgetExecutionAction as ac, type BeforeLLMCallAction as ad, type ChunkInterceptorContext as ae, type Controllers as af, type GadgetExecutionControllerContext as ag, type GadgetParameterInterceptorContext as ah, type GadgetResultInterceptorContext as ai, type Interceptors as aj, type LLMCallControllerContext as ak, type LLMErrorControllerContext as al, type MessageInterceptorContext as am, type ObserveChunkContext as an, type ObserveGadgetCompleteContext as ao, type ObserveGadgetStartContext as ap, type ObserveLLMCallContext as aq, type ObserveLLMCompleteContext as ar, type ObserveLLMErrorContext as as, type Observers as at, type MessageTurn as au, type ObserveCompactionContext as av, DEFAULT_COMPACTION_CONFIG as aw, DEFAULT_SUMMARIZATION_PROMPT as ax, type LLMistOptions as ay, type AudioContentPart as az, type LLMMessage as b, type VisionAnalyzeResult as b0, type CostEstimate as b1, type ModelFeatures as b2, type ModelLimits as b3, type ModelPricing as b4, type ProviderIdentifier as b5, ModelIdentifierParser as b6, type HintContext as b7, type PromptConfig as b8, type PromptContext as b9, type PromptTemplate as ba, DEFAULT_HINTS as bb, DEFAULT_PROMPTS as bc, resolveHintTemplate as bd, resolvePromptTemplate as be, resolveRulesTemplate as bf, type QuickOptions as bg, complete as bh, stream as bi, type GadgetClass as bj, type GadgetOrClass as bk, type CostReportingLLMist as bl, type GadgetExecuteResult as bm, type GadgetSkippedEvent as bn, type TextOnlyAction as bo, type TextOnlyContext as bp, type TextOnlyCustomHandler as bq, type TextOnlyGadgetConfig as br, type TextOnlyHandler as bs, type TextOnlyStrategy as bt, createMockAdapter as c, MockBuilder as d, createMockClient as e, MockManager as f, getMockManager as g, createMockStream as h, createTextMockStream as i, type MockAudioData as j, type MockImageData as k, type MockMatcher as l, mockLLM as m, type MockMatcherContext as n, type MockOptions as o, type MockRegistration as p, type MockResponse as q, type MockStats as r, ModelRegistry as s, type MessageContent as t, LLMist as u, type CompactionContext as v, type CompactionResult as w, type CompactionConfig as x, type CompactionEvent as y, type CompactionStats as z };
+export { type ImageGenerationResult as $, type AgentHooks as A, BaseGadget as B, type CompactionConfig as C, GadgetRegistry as D, MediaStore as E, type ExecutionContext as F, type GadgetMediaOutput as G, type HintTemplate as H, type IConversationManager as I, type GadgetExecuteReturn as J, type GadgetExample as K, type LLMMessage as L, MockProviderAdapter as M, type GadgetExecutionResult as N, type MediaKind as O, type ParsedGadgetCall as P, type MediaMetadata as Q, type ResolvedCompactionConfig as R, type StreamEvent as S, type TokenUsage as T, type GadgetExecuteResultWithMedia as U, type ProviderAdapter as V, type ModelDescriptor as W, type ModelSpec as X, type LLMGenerationOptions as Y, type ImageModelSpec as Z, type ImageGenerationOptions as _, type LLMStream as a, toBase64 as a$, type SpeechModelSpec as a0, type SpeechGenerationOptions as a1, type SpeechGenerationResult as a2, type HistoryMessage as a3, type TrailingMessage as a4, type TrailingMessageContext as a5, AgentBuilder as a6, type EventHandlers as a7, collectEvents as a8, collectText as a9, type Observers as aA, DEFAULT_COMPACTION_CONFIG as aB, DEFAULT_SUMMARIZATION_PROMPT as aC, type LLMistOptions as aD, type AudioContentPart as aE, type AudioMimeType as aF, type AudioSource as aG, type ContentPart as aH, type ImageBase64Source as aI, type ImageContentPart as aJ, type ImageMimeType as aK, type ImageSource as aL, type ImageUrlSource as aM, type TextContentPart as aN, audioFromBase64 as aO, audioFromBuffer as aP, detectAudioMimeType as aQ, detectImageMimeType as aR, imageFromBase64 as aS, imageFromBuffer as aT, imageFromUrl as aU, isAudioPart as aV, isDataUrl as aW, isImagePart as aX, isTextPart as aY, parseDataUrl as aZ, text as a_, runWithHandlers as aa, type AfterGadgetExecutionAction as ab, type AfterGadgetExecutionControllerContext as ac, type AfterLLMCallAction as ad, type AfterLLMCallControllerContext as ae, type AfterLLMErrorAction as af, type AgentOptions as ag, type BeforeGadgetExecutionAction as ah, type BeforeLLMCallAction as ai, type ChunkInterceptorContext as aj, type Controllers as ak, type GadgetExecutionControllerContext as al, type GadgetParameterInterceptorContext as am, type GadgetResultInterceptorContext as an, type Interceptors as ao, type LLMCallControllerContext as ap, type LLMErrorControllerContext as aq, type MessageInterceptorContext as ar, type MessageTurn as as, type ObserveChunkContext as at, type ObserveCompactionContext as au, type ObserveGadgetCompleteContext as av, type ObserveGadgetStartContext as aw, type ObserveLLMCallContext as ax, type ObserveLLMCompleteContext as ay, type ObserveLLMErrorContext as az, type LLMStreamChunk as b, type LLMRole as b0, extractText as b1, LLMMessageBuilder as b2, normalizeContent as b3, type CostEstimate as b4, type ModelFeatures as b5, type ModelLimits as b6, type ModelPricing as b7, type VisionAnalyzeOptions as b8, type VisionAnalyzeResult as b9, type ProviderIdentifier as ba, ModelIdentifierParser as bb, type HintContext as bc, type PromptConfig as bd, type PromptContext as be, type PromptTemplate as bf, DEFAULT_HINTS as bg, DEFAULT_PROMPTS as bh, resolveHintTemplate as bi, resolvePromptTemplate as bj, resolveRulesTemplate as bk, type QuickOptions as bl, complete as bm, stream as bn, type GadgetClass as bo, type GadgetOrClass as bp, type CostReportingLLMist as bq, type GadgetExecuteResult as br, type GadgetSkippedEvent as bs, type StoredMedia as bt, type TextOnlyAction as bu, type TextOnlyContext as bv, type TextOnlyCustomHandler as bw, type TextOnlyGadgetConfig as bx, type TextOnlyHandler as by, type TextOnlyStrategy as bz, createMockAdapter as c, MockBuilder as d, createMockClient as e, MockManager as f, getMockManager as g, createMockStream as h, createTextMockStream as i, type MockAudioData as j, type MockImageData as k, type MockMatcher as l, mockLLM as m, type MockMatcherContext as n, type MockOptions as o, type MockRegistration as p, type MockResponse as q, type MockStats as r, ModelRegistry as s, LLMist as t, type CompactionEvent as u, type CompactionStats as v, type CompactionStrategy as w, type CompactionContext as x, type CompactionResult as y, type MessageContent as z };