llmist 2.5.0 → 2.6.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ZodType, ZodTypeAny } from 'zod';
 export { z } from 'zod';
-import { A as AgentHooks, s as ModelRegistry, I as IConversationManager, b as LLMMessage, t as MessageContent, S as StreamEvent, T as TokenUsage, G as GadgetRegistry, u as LLMist, a as LLMStreamChunk, C as CompactionStrategy, R as ResolvedCompactionConfig, v as CompactionContext, w as CompactionResult, x as CompactionConfig, y as CompactionEvent, z as CompactionStats, H as HintTemplate, E as ExecutionContext, D as GadgetExecuteReturn, F as GadgetExample, B as BaseGadget, P as ParsedGadgetCall, J as GadgetExecutionResult, K as ProviderAdapter, N as ModelDescriptor, O as ModelSpec, Q as LLMGenerationOptions, L as LLMStream, U as ImageModelSpec, V as ImageGenerationOptions, W as ImageGenerationResult, X as SpeechModelSpec, Y as SpeechGenerationOptions, Z as SpeechGenerationResult } from './mock-stream-ga4KIiwX.js';
-export { a6 as AfterGadgetExecutionAction, a7 as AfterGadgetExecutionControllerContext, a8 as AfterLLMCallAction, a9 as AfterLLMCallControllerContext, aa as AfterLLMErrorAction, a1 as AgentBuilder, ab as AgentOptions, az as AudioContentPart, aA as AudioMimeType, aB as AudioSource, ac as BeforeGadgetExecutionAction, ad as BeforeLLMCallAction, ae as ChunkInterceptorContext, aC as ContentPart, af as Controllers, b1 as CostEstimate, bl as CostReportingLLMist, aw as DEFAULT_COMPACTION_CONFIG, bb as DEFAULT_HINTS, bc as DEFAULT_PROMPTS, ax as DEFAULT_SUMMARIZATION_PROMPT, a2 as EventHandlers, bj as GadgetClass, bm as GadgetExecuteResult, ag as GadgetExecutionControllerContext, bk as GadgetOrClass, ah as GadgetParameterInterceptorContext, ai as GadgetResultInterceptorContext, bn as GadgetSkippedEvent, b7 as HintContext, _ as HistoryMessage, aD as ImageBase64Source, aE as ImageContentPart, aF as ImageMimeType, aG as ImageSource, aH as ImageUrlSource, aj as Interceptors, ak as LLMCallControllerContext, al as LLMErrorControllerContext, aZ as LLMMessageBuilder, aX as LLMRole, ay as LLMistOptions, am as MessageInterceptorContext, au as MessageTurn, d as MockBuilder, f as MockManager, l as MockMatcher, n as MockMatcherContext, o as MockOptions, M as MockProviderAdapter, p as MockRegistration, q as MockResponse, r as MockStats, b2 as ModelFeatures, b6 as ModelIdentifierParser, b3 as ModelLimits, b4 as ModelPricing, an as ObserveChunkContext, av as ObserveCompactionContext, ao as ObserveGadgetCompleteContext, ap as ObserveGadgetStartContext, aq as ObserveLLMCallContext, ar as ObserveLLMCompleteContext, as as ObserveLLMErrorContext, at as Observers, b8 as PromptConfig, b9 as PromptContext, ba as PromptTemplate, b5 as ProviderIdentifier, bg as QuickOptions, aI as TextContentPart, bo as TextOnlyAction, bp as TextOnlyContext, bq as TextOnlyCustomHandler, br as TextOnlyGadgetConfig, bs as TextOnlyHandler, bt as TextOnlyStrategy, $ as TrailingMessage, a0 as TrailingMessageContext, a$ as VisionAnalyzeOptions, b0 as VisionAnalyzeResult, aJ as audioFromBase64, aK as audioFromBuffer, a3 as collectEvents, a4 as collectText, bh as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, aL as detectAudioMimeType, aM as detectImageMimeType, aY as extractText, g as getMockManager, aN as imageFromBase64, aO as imageFromBuffer, aP as imageFromUrl, aQ as isAudioPart, aR as isDataUrl, aS as isImagePart, aT as isTextPart, m as mockLLM, a_ as normalizeContent, aU as parseDataUrl, bd as resolveHintTemplate, be as resolvePromptTemplate, bf as resolveRulesTemplate, a5 as runWithHandlers, bi as stream, aV as text, aW as toBase64 } from './mock-stream-ga4KIiwX.js';
+import { A as AgentHooks, s as ModelRegistry, t as LLMist, C as CompactionConfig, I as IConversationManager, u as CompactionEvent, L as LLMMessage, v as CompactionStats, w as CompactionStrategy, R as ResolvedCompactionConfig, x as CompactionContext, y as CompactionResult, z as MessageContent, G as GadgetMediaOutput, H as HintTemplate, S as StreamEvent, T as TokenUsage, D as GadgetRegistry, E as MediaStore, b as LLMStreamChunk, F as ExecutionContext, J as GadgetExecuteReturn, K as GadgetExample, B as BaseGadget, P as ParsedGadgetCall, N as GadgetExecutionResult, O as MediaKind, Q as MediaMetadata, U as GadgetExecuteResultWithMedia, V as ProviderAdapter, W as ModelDescriptor, X as ModelSpec, Y as LLMGenerationOptions, a as LLMStream, Z as ImageModelSpec, _ as ImageGenerationOptions, $ as ImageGenerationResult, a0 as SpeechModelSpec, a1 as SpeechGenerationOptions, a2 as SpeechGenerationResult } from './mock-stream-Jgg5u6Uf.js';
+export { ab as AfterGadgetExecutionAction, ac as AfterGadgetExecutionControllerContext, ad as AfterLLMCallAction, ae as AfterLLMCallControllerContext, af as AfterLLMErrorAction, a6 as AgentBuilder, ag as AgentOptions, aE as AudioContentPart, aF as AudioMimeType, aG as AudioSource, ah as BeforeGadgetExecutionAction, ai as BeforeLLMCallAction, aj as ChunkInterceptorContext, aH as ContentPart, ak as Controllers, b4 as CostEstimate, bq as CostReportingLLMist, aB as DEFAULT_COMPACTION_CONFIG, bg as DEFAULT_HINTS, bh as DEFAULT_PROMPTS, aC as DEFAULT_SUMMARIZATION_PROMPT, a7 as EventHandlers, bo as GadgetClass, br as GadgetExecuteResult, al as GadgetExecutionControllerContext, bp as GadgetOrClass, am as GadgetParameterInterceptorContext, an as GadgetResultInterceptorContext, bs as GadgetSkippedEvent, bc as HintContext, a3 as HistoryMessage, aI as ImageBase64Source, aJ as ImageContentPart, aK as ImageMimeType, aL as ImageSource, aM as ImageUrlSource, ao as Interceptors, ap as LLMCallControllerContext, aq as LLMErrorControllerContext, b2 as LLMMessageBuilder, b0 as LLMRole, aD as LLMistOptions, ar as MessageInterceptorContext, as as MessageTurn, d as MockBuilder, f as MockManager, l as MockMatcher, n as MockMatcherContext, o as MockOptions, M as MockProviderAdapter, p as MockRegistration, q as MockResponse, r as MockStats, b5 as ModelFeatures, bb as ModelIdentifierParser, b6 as ModelLimits, b7 as ModelPricing, at as ObserveChunkContext, au as ObserveCompactionContext, av as ObserveGadgetCompleteContext, aw as ObserveGadgetStartContext, ax as ObserveLLMCallContext, ay as ObserveLLMCompleteContext, az as ObserveLLMErrorContext, aA as Observers, bd as PromptConfig, be as PromptContext, bf as PromptTemplate, ba as ProviderIdentifier, bl as QuickOptions, bt as StoredMedia, aN as TextContentPart, bu as TextOnlyAction, bv as TextOnlyContext, bw as TextOnlyCustomHandler, bx as TextOnlyGadgetConfig, by as TextOnlyHandler, bz as TextOnlyStrategy, a4 as TrailingMessage, a5 as TrailingMessageContext, b8 as VisionAnalyzeOptions, b9 as VisionAnalyzeResult, aO as audioFromBase64, aP as audioFromBuffer, a8 as collectEvents, a9 as collectText, bm as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, aQ as detectAudioMimeType, aR as detectImageMimeType, b1 as extractText, g as getMockManager, aS as imageFromBase64, aT as imageFromBuffer, aU as imageFromUrl, aV as isAudioPart, aW as isDataUrl, aX as isImagePart, aY as isTextPart, m as mockLLM, b3 as normalizeContent, aZ as parseDataUrl, bi as resolveHintTemplate, bj as resolvePromptTemplate, bk as resolveRulesTemplate, aa as runWithHandlers, bn as stream, a_ as text, a$ as toBase64 } from './mock-stream-Jgg5u6Uf.js';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';
@@ -713,289 +713,93 @@ declare class HookPresets {
 }
 
 /**
- * ConversationManager handles conversation state and message building.
- * Extracted from AgentLoop to follow Single Responsibility Principle.
- */
-
-/**
- * Options for ConversationManager constructor.
- */
-interface ConversationManagerOptions {
-    /** Custom gadget start marker prefix */
-    startPrefix?: string;
-    /** Custom gadget end marker prefix */
-    endPrefix?: string;
-    /** Custom argument prefix for block format */
-    argPrefix?: string;
-}
-/**
- * Default implementation of IConversationManager.
- * Manages conversation history by building on top of base messages (system prompt, gadget instructions).
- */
-declare class ConversationManager implements IConversationManager {
-    private readonly baseMessages;
-    private readonly initialMessages;
-    private historyBuilder;
-    private readonly startPrefix?;
-    private readonly endPrefix?;
-    private readonly argPrefix?;
-    constructor(baseMessages: LLMMessage[], initialMessages: LLMMessage[], options?: ConversationManagerOptions);
-    addUserMessage(content: MessageContent): void;
-    addAssistantMessage(content: string): void;
-    addGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): void;
-    getMessages(): LLMMessage[];
-    getHistoryMessages(): LLMMessage[];
-    getBaseMessages(): LLMMessage[];
-    replaceHistory(newHistory: LLMMessage[]): void;
-}
-
-/**
- * StreamProcessor: The heart of the new hooks architecture.
+ * CompactionManager - Central orchestrator for context compaction.
  *
- * Replaces the complex wiring between Agent, ResponseProcessor, and GadgetRuntime.
- * Owns ALL stream processing and hook coordination with a clean, predictable flow.
+ * Monitors token usage and coordinates compaction strategies to keep
+ * conversation context within model limits.
  */
 
 /**
- * Configuration for the StreamProcessor.
- */
-interface StreamProcessorOptions {
-    /** Current iteration number */
-    iteration: number;
-    /** Gadget registry for execution */
-    registry: GadgetRegistry;
-    /** Custom gadget start prefix */
-    gadgetStartPrefix?: string;
-    /** Custom gadget end prefix */
-    gadgetEndPrefix?: string;
-    /** Custom argument prefix for block format */
-    gadgetArgPrefix?: string;
-    /** Hooks for lifecycle events */
-    hooks?: AgentHooks;
-    /** Logger instance */
-    logger?: Logger<ILogObj>;
-    /** Callback for human input */
-    onHumanInputRequired?: (question: string) => Promise<string>;
-    /** Whether to stop on gadget errors */
-    stopOnGadgetError?: boolean;
-    /** Custom error continuation logic */
-    shouldContinueAfterError?: (context: {
-        error: string;
-        gadgetName: string;
-        errorType: "parse" | "validation" | "execution";
-        parameters?: Record<string, unknown>;
-    }) => boolean | Promise<boolean>;
-    /** Default gadget timeout */
-    defaultGadgetTimeoutMs?: number;
-    /** LLMist client for ExecutionContext.llmist */
-    client?: LLMist;
-}
-/**
- * Result of stream processing.
+ * Pre-computed token counts to avoid redundant counting.
+ * Passed from checkAndCompact to compact for efficiency.
  */
-interface StreamProcessingResult {
-    /** All emitted events */
-    outputs: StreamEvent[];
-    /** Whether the loop should break */
-    shouldBreakLoop: boolean;
-    /** Whether any gadgets were executed */
-    didExecuteGadgets: boolean;
-    /** LLM finish reason */
-    finishReason: string | null;
-    /** Token usage (including cached token counts when available) */
-    usage?: TokenUsage;
-    /** The raw accumulated response text */
-    rawResponse: string;
-    /** The final message (after interceptors) */
-    finalMessage: string;
+interface PrecomputedTokens {
+    historyMessages: LLMMessage[];
+    baseMessages: LLMMessage[];
+    historyTokens: number;
+    baseTokens: number;
+    currentTokens: number;
 }
 /**
- * StreamProcessor: Coordinates all stream processing and hook execution.
+ * CompactionManager orchestrates context compaction for an agent.
  *
- * Execution order:
- * 1. Raw chunk arrives from LLM
- * 2. Interceptor: interceptRawChunk (transform raw text)
- * 3. Observer: onStreamChunk (logging)
- * 4. Parse for gadgets
- * 5. If gadget found:
- *    a. Interceptor: interceptGadgetParameters (transform params)
- *    b. Controller: beforeGadgetExecution (can skip)
- *    c. Observer: onGadgetExecutionStart
- *    d. Execute gadget
- *    e. Interceptor: interceptGadgetResult (transform result)
- *    f. Controller: afterGadgetExecution (can provide fallback)
- *    g. Observer: onGadgetExecutionComplete
- * 6. If text chunk:
- *    a. Interceptor: interceptTextChunk (transform display text)
- *    b. Yield to user
- * 7. Stream complete
- * 8. Interceptor: interceptAssistantMessage (transform final message)
+ * It:
+ * - Monitors token usage before each LLM call
+ * - Triggers compaction when threshold is exceeded
+ * - Coordinates with ConversationManager to update history
+ * - Tracks statistics for observability
  */
-declare class StreamProcessor {
-    private readonly iteration;
-    private readonly registry;
-    private readonly hooks;
-    private readonly logger;
-    private readonly parser;
-    private readonly executor;
-    private readonly stopOnGadgetError;
-    private readonly shouldContinueAfterError?;
-    private accumulatedText;
-    private shouldStopExecution;
-    private observerFailureCount;
-    /** Gadgets waiting for their dependencies to complete */
-    private pendingGadgets;
-    /** Completed gadget results, keyed by invocation ID */
-    private completedResults;
-    /** Invocation IDs of gadgets that have failed (error or skipped due to dependency) */
-    private failedInvocations;
-    constructor(options: StreamProcessorOptions);
-    /**
-     * Process an LLM stream and return structured results.
-     */
-    process(stream: AsyncIterable<LLMStreamChunk>): Promise<StreamProcessingResult>;
-    /**
-     * Process a single parsed event (text or gadget call).
-     */
-    private processEvent;
-    /**
-     * Process a text event through interceptors.
-     */
-    private processTextEvent;
+declare class CompactionManager {
+    private readonly client;
+    private readonly model;
+    private readonly config;
+    private readonly strategy;
+    private modelLimits?;
+    private totalCompactions;
+    private totalTokensSaved;
+    private lastTokenCount;
+    constructor(client: LLMist, model: string, config?: CompactionConfig);
     /**
-     * Process a gadget call through the full lifecycle, handling dependencies.
+     * Check if compaction is needed and perform it if so.
      *
-     * 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.
-     */
-    private processGadgetCall;
-    /**
-     * Execute a gadget through the full hook lifecycle.
-     * This is the core execution logic, extracted from processGadgetCall.
-     */
-    private executeGadgetWithHooks;
-    /**
-     * Handle a gadget that cannot execute because a dependency failed.
-     * Calls the onDependencySkipped controller to allow customization.
-     */
-    private handleFailedDependency;
-    /**
-     * Process pending gadgets whose dependencies are now satisfied.
-     * Executes ready gadgets in parallel and continues until no more can be triggered.
-     */
-    private processPendingGadgets;
-    /**
-     * Safely execute an observer, catching and logging any errors.
-     * Observers are non-critical, so errors are logged but don't crash the system.
+     * @param conversation - The conversation manager to compact
+     * @param iteration - Current agent iteration (for event metadata)
+     * @returns CompactionEvent if compaction was performed, null otherwise
      */
-    private safeObserve;
+    checkAndCompact(conversation: IConversationManager, iteration: number): Promise<CompactionEvent | null>;
     /**
-     * Execute multiple observers in parallel.
-     * All observers run concurrently and failures are tracked but don't crash.
+     * Force compaction regardless of threshold.
+     *
+     * @param conversation - The conversation manager to compact
+     * @param iteration - Current agent iteration (for event metadata). Use -1 for manual compaction.
+     * @param precomputed - Optional pre-computed token counts (passed from checkAndCompact for efficiency)
+     * @returns CompactionEvent with compaction details
      */
-    private runObserversInParallel;
+    compact(conversation: IConversationManager, iteration: number, precomputed?: PrecomputedTokens): Promise<CompactionEvent | null>;
     /**
-     * Check if execution should continue after an error.
-     *
-     * Returns true if we should continue processing subsequent gadgets, false if we should stop.
-     *
-     * Logic:
-     * - If custom shouldContinueAfterError is provided, use it
-     * - Otherwise, use stopOnGadgetError config:
-     *   - stopOnGadgetError=true → return false (stop execution)
-     *   - stopOnGadgetError=false → return true (continue execution)
+     * Get compaction statistics.
      */
-    private checkContinueAfterError;
+    getStats(): CompactionStats;
     /**
-     * Determine the type of error from a gadget execution.
+     * Check if compaction is enabled.
      */
-    private determineErrorType;
+    isEnabled(): boolean;
 }
 
 /**
- * Storage for large gadget outputs that exceed the configured limit.
+ * Hybrid Compaction Strategy
  *
- * When a gadget returns more data than the configured limit, the output
- * is stored here and can be browsed later using GadgetOutputViewer.
- */
-/**
- * Metadata and content for a stored gadget output.
+ * Combines sliding window and summarization for the best of both worlds:
+ * 1. Identifies which turns to compact vs keep (like sliding window)
+ * 2. Summarizes the older turns (like summarization)
+ * 3. Returns summary + recent turns intact
+ *
+ * Falls back to sliding window if there are too few turns to summarize.
  */
-interface StoredOutput {
-    /** Unique identifier (e.g., "Search_d34db33f") */
-    id: string;
-    /** Name of the gadget that produced this output */
-    gadgetName: string;
-    /** Full output content */
-    content: string;
-    /** Size in bytes */
-    byteSize: number;
-    /** Number of lines */
-    lineCount: number;
-    /** When the output was stored */
-    timestamp: Date;
-}
+
 /**
- * In-memory store for large gadget outputs.
- *
- * Outputs are stored with generated IDs in the format `{GadgetName}_{hex8}`.
- * The store is tied to an agent run and cleared when the agent completes.
- *
- * @example
- * ```typescript
- * const store = new GadgetOutputStore();
- * const id = store.store("Search", largeOutput);
- * // id = "Search_a1b2c3d4"
+ * Hybrid strategy - summarizes old turns + keeps recent turns.
  *
- * const stored = store.get(id);
- * console.log(stored?.lineCount); // 4200
- * ```
+ * This is the recommended default strategy as it:
+ * - Preserves important historical context via summarization
+ * - Keeps recent conversation turns verbatim for continuity
+ * - Falls back gracefully to sliding window when appropriate
  */
-declare class GadgetOutputStore {
-    private outputs;
-    /**
-     * 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: string, content: string): string;
-    /**
-     * 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: string): StoredOutput | undefined;
-    /**
-     * Check if an output exists.
-     *
-     * @param id - The output ID to check
-     * @returns True if the output exists
-     */
-    has(id: string): boolean;
-    /**
-     * Get all stored output IDs.
-     *
-     * @returns Array of output IDs
-     */
-    getIds(): string[];
-    /**
-     * Get the number of stored outputs.
-     */
-    get size(): number;
-    /**
-     * Clear all stored outputs.
-     * Called when the agent run completes.
-     */
-    clear(): void;
-    /**
-     * Generate a unique ID for a stored output.
-     * Format: {GadgetName}_{8 hex chars}
-     */
-    private generateId;
+declare class HybridStrategy implements CompactionStrategy {
+    readonly name = "hybrid";
+    private readonly slidingWindow;
+    private readonly summarization;
+    compact(messages: LLMMessage[], config: ResolvedCompactionConfig, context: CompactionContext): Promise<CompactionResult>;
 }
 
 /**
@@ -1055,93 +859,125 @@ declare class SummarizationStrategy implements CompactionStrategy {
 }
 
 /**
- * Hybrid Compaction Strategy
- *
- * Combines sliding window and summarization for the best of both worlds:
- * 1. Identifies which turns to compact vs keep (like sliding window)
- * 2. Summarizes the older turns (like summarization)
- * 3. Returns summary + recent turns intact
- *
- * Falls back to sliding window if there are too few turns to summarize.
+ * ConversationManager handles conversation state and message building.
+ * Extracted from AgentLoop to follow Single Responsibility Principle.
  */
 
 /**
- * Hybrid strategy - summarizes old turns + keeps recent turns.
- *
- * This is the recommended default strategy as it:
- * - Preserves important historical context via summarization
- * - Keeps recent conversation turns verbatim for continuity
- * - Falls back gracefully to sliding window when appropriate
+ * Options for ConversationManager constructor.
  */
-declare class HybridStrategy implements CompactionStrategy {
-    readonly name = "hybrid";
-    private readonly slidingWindow;
-    private readonly summarization;
-    compact(messages: LLMMessage[], config: ResolvedCompactionConfig, context: CompactionContext): Promise<CompactionResult>;
+interface ConversationManagerOptions {
+    /** Custom gadget start marker prefix */
+    startPrefix?: string;
+    /** Custom gadget end marker prefix */
+    endPrefix?: string;
+    /** Custom argument prefix for block format */
+    argPrefix?: string;
+}
+/**
+ * Default implementation of IConversationManager.
+ * Manages conversation history by building on top of base messages (system prompt, gadget instructions).
+ */
+declare class ConversationManager implements IConversationManager {
+    private readonly baseMessages;
+    private readonly initialMessages;
+    private historyBuilder;
+    private readonly startPrefix?;
+    private readonly endPrefix?;
+    private readonly argPrefix?;
+    constructor(baseMessages: LLMMessage[], initialMessages: LLMMessage[], options?: ConversationManagerOptions);
+    addUserMessage(content: MessageContent): void;
+    addAssistantMessage(content: string): void;
+    addGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string, media?: GadgetMediaOutput[], mediaIds?: string[]): void;
+    getMessages(): LLMMessage[];
+    getHistoryMessages(): LLMMessage[];
+    getBaseMessages(): LLMMessage[];
+    replaceHistory(newHistory: LLMMessage[]): void;
 }
 
 /**
- * CompactionManager - Central orchestrator for context compaction.
+ * Storage for large gadget outputs that exceed the configured limit.
  *
- * Monitors token usage and coordinates compaction strategies to keep
- * conversation context within model limits.
+ * When a gadget returns more data than the configured limit, the output
+ * is stored here and can be browsed later using GadgetOutputViewer.
  */
-
 /**
- * Pre-computed token counts to avoid redundant counting.
- * Passed from checkAndCompact to compact for efficiency.
+ * Metadata and content for a stored gadget output.
  */
-interface PrecomputedTokens {
-    historyMessages: LLMMessage[];
-    baseMessages: LLMMessage[];
-    historyTokens: number;
-    baseTokens: number;
-    currentTokens: number;
+interface StoredOutput {
+    /** Unique identifier (e.g., "Search_d34db33f") */
+    id: string;
+    /** Name of the gadget that produced this output */
+    gadgetName: string;
+    /** Full output content */
+    content: string;
+    /** Size in bytes */
+    byteSize: number;
+    /** Number of lines */
+    lineCount: number;
+    /** When the output was stored */
+    timestamp: Date;
 }
 /**
- * CompactionManager orchestrates context compaction for an agent.
+ * In-memory store for large gadget outputs.
  *
- * It:
- * - Monitors token usage before each LLM call
- * - Triggers compaction when threshold is exceeded
- * - Coordinates with ConversationManager to update history
- * - Tracks statistics for observability
+ * Outputs are stored with generated IDs in the format `{GadgetName}_{hex8}`.
+ * The store is tied to an agent run and cleared when the agent completes.
+ *
+ * @example
+ * ```typescript
+ * const store = new GadgetOutputStore();
+ * const id = store.store("Search", largeOutput);
+ * // id = "Search_a1b2c3d4"
+ *
+ * const stored = store.get(id);
+ * console.log(stored?.lineCount); // 4200
+ * ```
  */
-declare class CompactionManager {
-    private readonly client;
-    private readonly model;
-    private readonly config;
-    private readonly strategy;
-    private modelLimits?;
-    private totalCompactions;
-    private totalTokensSaved;
-    private lastTokenCount;
-    constructor(client: LLMist, model: string, config?: CompactionConfig);
+declare class GadgetOutputStore {
+    private outputs;
+    /**
+     * 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: string, content: string): string;
+    /**
+     * 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: string): StoredOutput | undefined;
+    /**
+     * Check if an output exists.
+     *
+     * @param id - The output ID to check
+     * @returns True if the output exists
+     */
+    has(id: string): boolean;
     /**
-     * Check if compaction is needed and perform it if so.
+     * Get all stored output IDs.
      *
-     * @param conversation - The conversation manager to compact
-     * @param iteration - Current agent iteration (for event metadata)
-     * @returns CompactionEvent if compaction was performed, null otherwise
+     * @returns Array of output IDs
      */
-    checkAndCompact(conversation: IConversationManager, iteration: number): Promise<CompactionEvent | null>;
+    getIds(): string[];
     /**
-     * Force compaction regardless of threshold.
-     *
-     * @param conversation - The conversation manager to compact
-     * @param iteration - Current agent iteration (for event metadata). Use -1 for manual compaction.
-     * @param precomputed - Optional pre-computed token counts (passed from checkAndCompact for efficiency)
-     * @returns CompactionEvent with compaction details
+     * Get the number of stored outputs.
      */
-    compact(conversation: IConversationManager, iteration: number, precomputed?: PrecomputedTokens): Promise<CompactionEvent | null>;
+    get size(): number;
     /**
-     * Get compaction statistics.
+     * Clear all stored outputs.
+     * Called when the agent run completes.
      */
-    getStats(): CompactionStats;
+    clear(): void;
     /**
-     * Check if compaction is enabled.
+     * Generate a unique ID for a stored output.
+     * Format: {GadgetName}_{8 hex chars}
      */
-    isEnabled(): boolean;
+    private generateId;
 }
 
 /**
@@ -1188,134 +1024,300 @@ declare class CompactionManager {
  */
 interface IterationHintOptions {
     /**
-     * When to show the hint.
-     * - "always": Show on every iteration
-     * - "late": Show only when >= 50% through iterations
-     * - "urgent": Show only when >= 80% through iterations
-     * @default "always"
+     * When to show the hint.
+     * - "always": Show on every iteration
+     * - "late": Show only when >= 50% through iterations
+     * - "urgent": Show only when >= 80% through iterations
+     * @default "always"
+     */
+    timing?: "always" | "late" | "urgent";
+    /**
+     * Whether to include urgency indicators for late iterations.
+     * Adds extra text when running low on iterations.
+     * @default true
+     */
+    showUrgency?: boolean;
+    /**
+     * Custom template. Supports placeholders: {iteration}, {maxIterations}, {remaining}
+     * Or a function receiving HintContext.
+     * @default DEFAULT_HINTS.iterationProgressHint
+     */
+    template?: HintTemplate;
+}
+/**
+ * Options for parallel gadget usage hint.
+ */
+interface ParallelGadgetHintOptions {
+    /**
+     * Minimum number of gadget calls to consider "efficient".
+     * If response has fewer calls, hint will suggest parallelization.
+     * @default 2
+     */
+    minGadgetsForEfficiency?: number;
+    /**
+     * Custom message when single gadget detected.
+     * @default DEFAULT_HINTS.parallelGadgetsHint
+     */
+    message?: string;
+    /**
+     * Whether to enable this hint.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Combined hints configuration for createHints().
+ */
+interface HintsConfig {
+    /**
+     * Enable iteration progress hints.
+     * Pass `true` for defaults, or options object for customization.
+     */
+    iterationProgress?: boolean | IterationHintOptions;
+    /**
+     * Enable parallel gadget hints.
+     * Pass `true` for defaults, or options object for customization.
+     */
+    parallelGadgets?: boolean | ParallelGadgetHintOptions;
+    /**
+     * Additional custom hooks to merge.
+     */
+    custom?: AgentHooks[];
+}
+/**
+ * Creates a proactive hint that informs the LLM about iteration progress.
+ *
+ * This hint is injected before each LLM call (via beforeLLMCall controller),
+ * helping the LLM understand how much "budget" remains for completing the task.
+ *
+ * @param options - Configuration options
+ * @returns AgentHooks that can be merged with other hooks
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - show on every iteration
+ * const hooks = iterationProgressHint();
+ *
+ * // Show only when running low on iterations
+ * const hooks = iterationProgressHint({ timing: "late" });
+ *
+ * // Custom template
+ * const hooks = iterationProgressHint({
+ *   template: "Turn {iteration} of {maxIterations}. {remaining} turns left.",
+ * });
+ * ```
+ */
+declare function iterationProgressHint(options?: IterationHintOptions): AgentHooks;
+/**
+ * Creates a reactive hint that encourages parallel gadget usage.
+ *
+ * This hint analyzes the LLM's response and, if only a single gadget was called,
+ * appends a reminder that multiple gadgets can be used in parallel for efficiency.
+ *
+ * @param options - Configuration options
+ * @returns AgentHooks that can be merged with other hooks
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const hooks = parallelGadgetHint();
+ *
+ * // Custom threshold and message
+ * const hooks = parallelGadgetHint({
+ *   minGadgetsForEfficiency: 3,
+ *   message: "Consider calling multiple gadgets at once!",
+ * });
+ * ```
+ */
+declare function parallelGadgetHint(options?: ParallelGadgetHintOptions): AgentHooks;
+/**
+ * Creates combined hints from a configuration object.
+ *
+ * This is a convenience function that creates and merges multiple hints
+ * based on a simple configuration object.
+ *
+ * @param config - Configuration for which hints to enable
+ * @returns Merged AgentHooks
+ *
+ * @example
+ * ```typescript
+ * const hooks = createHints({
+ *   iterationProgress: { timing: "late" },
+ *   parallelGadgets: true,
+ * });
+ *
+ * const agent = new AgentBuilder()
+ *   .withHooks(HookPresets.merge(existingHooks, hooks))
+ *   .build();
+ * ```
+ */
+declare function createHints(config: HintsConfig): AgentHooks;
+
+/**
+ * StreamProcessor: The heart of the new hooks architecture.
+ *
+ * Replaces the complex wiring between Agent, ResponseProcessor, and GadgetRuntime.
+ * Owns ALL stream processing and hook coordination with a clean, predictable flow.
+ */
+
+/**
+ * Configuration for the StreamProcessor.
+ */
+interface StreamProcessorOptions {
+    /** Current iteration number */
+    iteration: number;
+    /** Gadget registry for execution */
+    registry: GadgetRegistry;
+    /** Custom gadget start prefix */
+    gadgetStartPrefix?: string;
+    /** Custom gadget end prefix */
+    gadgetEndPrefix?: string;
+    /** Custom argument prefix for block format */
+    gadgetArgPrefix?: string;
+    /** Hooks for lifecycle events */
+    hooks?: AgentHooks;
+    /** Logger instance */
+    logger?: Logger<ILogObj>;
+    /** Callback for human input */
+    onHumanInputRequired?: (question: string) => Promise<string>;
+    /** Whether to stop on gadget errors */
+    stopOnGadgetError?: boolean;
+    /** Custom error continuation logic */
+    shouldContinueAfterError?: (context: {
+        error: string;
+        gadgetName: string;
+        errorType: "parse" | "validation" | "execution";
+        parameters?: Record<string, unknown>;
+    }) => boolean | Promise<boolean>;
+    /** Default gadget timeout */
+    defaultGadgetTimeoutMs?: number;
+    /** LLMist client for ExecutionContext.llmist */
+    client?: LLMist;
+    /** MediaStore for storing gadget media outputs */
+    mediaStore?: MediaStore;
+}
+/**
+ * Result of stream processing.
+ */
+interface StreamProcessingResult {
+    /** All emitted events */
+    outputs: StreamEvent[];
+    /** Whether the loop should break */
+    shouldBreakLoop: boolean;
+    /** Whether any gadgets were executed */
+    didExecuteGadgets: boolean;
+    /** LLM finish reason */
+    finishReason: string | null;
+    /** Token usage (including cached token counts when available) */
+    usage?: TokenUsage;
+    /** The raw accumulated response text */
+    rawResponse: string;
+    /** The final message (after interceptors) */
+    finalMessage: string;
+}
+/**
+ * StreamProcessor: Coordinates all stream processing and hook execution.
+ *
+ * Execution order:
+ * 1. Raw chunk arrives from LLM
+ * 2. Interceptor: interceptRawChunk (transform raw text)
+ * 3. Observer: onStreamChunk (logging)
+ * 4. Parse for gadgets
+ * 5. If gadget found:
+ *    a. Interceptor: interceptGadgetParameters (transform params)
+ *    b. Controller: beforeGadgetExecution (can skip)
+ *    c. Observer: onGadgetExecutionStart
+ *    d. Execute gadget
+ *    e. Interceptor: interceptGadgetResult (transform result)
+ *    f. Controller: afterGadgetExecution (can provide fallback)
+ *    g. Observer: onGadgetExecutionComplete
+ * 6. If text chunk:
+ *    a. Interceptor: interceptTextChunk (transform display text)
+ *    b. Yield to user
+ * 7. Stream complete
+ * 8. Interceptor: interceptAssistantMessage (transform final message)
+ */
+declare class StreamProcessor {
+    private readonly iteration;
+    private readonly registry;
+    private readonly hooks;
+    private readonly logger;
+    private readonly parser;
+    private readonly executor;
+    private readonly stopOnGadgetError;
+    private readonly shouldContinueAfterError?;
+    private accumulatedText;
+    private shouldStopExecution;
+    private observerFailureCount;
+    /** Gadgets waiting for their dependencies to complete */
+    private pendingGadgets;
+    /** Completed gadget results, keyed by invocation ID */
+    private completedResults;
+    /** Invocation IDs of gadgets that have failed (error or skipped due to dependency) */
+    private failedInvocations;
+    constructor(options: StreamProcessorOptions);
+    /**
+     * Process an LLM stream and return structured results.
      */
-    timing?: "always" | "late" | "urgent";
+    process(stream: AsyncIterable<LLMStreamChunk>): Promise<StreamProcessingResult>;
     /**
-     * Whether to include urgency indicators for late iterations.
-     * Adds extra text when running low on iterations.
-     * @default true
+     * Process a single parsed event (text or gadget call).
      */
-    showUrgency?: boolean;
+    private processEvent;
     /**
-     * Custom template. Supports placeholders: {iteration}, {maxIterations}, {remaining}
-     * Or a function receiving HintContext.
-     * @default DEFAULT_HINTS.iterationProgressHint
+     * Process a text event through interceptors.
      */
-    template?: HintTemplate;
-}
-/**
- * Options for parallel gadget usage hint.
- */
-interface ParallelGadgetHintOptions {
+    private processTextEvent;
     /**
-     * Minimum number of gadget calls to consider "efficient".
-     * If response has fewer calls, hint will suggest parallelization.
-     * @default 2
+     * 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.
      */
-    minGadgetsForEfficiency?: number;
+    private processGadgetCall;
     /**
-     * Custom message when single gadget detected.
-     * @default DEFAULT_HINTS.parallelGadgetsHint
+     * Execute a gadget through the full hook lifecycle.
+     * This is the core execution logic, extracted from processGadgetCall.
      */
-    message?: string;
+    private executeGadgetWithHooks;
     /**
-     * Whether to enable this hint.
-     * @default true
+     * Handle a gadget that cannot execute because a dependency failed.
+     * Calls the onDependencySkipped controller to allow customization.
      */
-    enabled?: boolean;
-}
-/**
- * Combined hints configuration for createHints().
- */
-interface HintsConfig {
+    private handleFailedDependency;
     /**
-     * Enable iteration progress hints.
-     * Pass `true` for defaults, or options object for customization.
+     * Process pending gadgets whose dependencies are now satisfied.
+     * Executes ready gadgets in parallel and continues until no more can be triggered.
      */
-    iterationProgress?: boolean | IterationHintOptions;
+    private processPendingGadgets;
     /**
-     * Enable parallel gadget hints.
-     * Pass `true` for defaults, or options object for customization.
+     * Safely execute an observer, catching and logging any errors.
+     * Observers are non-critical, so errors are logged but don't crash the system.
      */
-    parallelGadgets?: boolean | ParallelGadgetHintOptions;
+    private safeObserve;
     /**
-     * Additional custom hooks to merge.
+     * Execute multiple observers in parallel.
+     * All observers run concurrently and failures are tracked but don't crash.
      */
-    custom?: AgentHooks[];
+    private runObserversInParallel;
+    /**
+     * Check if execution should continue after an error.
+     *
+     * Returns true if we should continue processing subsequent gadgets, false if we should stop.
+     *
+     * Logic:
+     * - If custom shouldContinueAfterError is provided, use it
+     * - Otherwise, use stopOnGadgetError config:
+     *   - stopOnGadgetError=true → return false (stop execution)
+     *   - stopOnGadgetError=false → return true (continue execution)
+     */
+    private checkContinueAfterError;
+    /**
+     * Determine the type of error from a gadget execution.
+     */
+    private determineErrorType;
 }
-/**
- * Creates a proactive hint that informs the LLM about iteration progress.
- *
- * This hint is injected before each LLM call (via beforeLLMCall controller),
- * helping the LLM understand how much "budget" remains for completing the task.
- *
- * @param options - Configuration options
- * @returns AgentHooks that can be merged with other hooks
- *
- * @example
- * ```typescript
- * // Basic usage - show on every iteration
- * const hooks = iterationProgressHint();
- *
- * // Show only when running low on iterations
- * const hooks = iterationProgressHint({ timing: "late" });
- *
- * // Custom template
- * const hooks = iterationProgressHint({
- *   template: "Turn {iteration} of {maxIterations}. {remaining} turns left.",
- * });
- * ```
- */
-declare function iterationProgressHint(options?: IterationHintOptions): AgentHooks;
-/**
- * Creates a reactive hint that encourages parallel gadget usage.
- *
- * This hint analyzes the LLM's response and, if only a single gadget was called,
- * appends a reminder that multiple gadgets can be used in parallel for efficiency.
- *
- * @param options - Configuration options
- * @returns AgentHooks that can be merged with other hooks
- *
- * @example
- * ```typescript
- * // Basic usage
- * const hooks = parallelGadgetHint();
- *
- * // Custom threshold and message
- * const hooks = parallelGadgetHint({
- *   minGadgetsForEfficiency: 3,
- *   message: "Consider calling multiple gadgets at once!",
- * });
- * ```
- */
-declare function parallelGadgetHint(options?: ParallelGadgetHintOptions): AgentHooks;
-/**
- * Creates combined hints from a configuration object.
- *
- * This is a convenience function that creates and merges multiple hints
- * based on a simple configuration object.
- *
- * @param config - Configuration for which hints to enable
- * @returns Merged AgentHooks
- *
- * @example
- * ```typescript
- * const hooks = createHints({
- *   iterationProgress: { timing: "late" },
- *   parallelGadgets: true,
- * });
- *
- * const agent = new AgentBuilder()
- *   .withHooks(HookPresets.merge(existingHooks, hooks))
- *   .build();
- * ```
- */
-declare function createHints(config: HintsConfig): AgentHooks;
 
 /**
  * Model shortcuts and aliases for more expressive DX.
@@ -1541,25 +1543,6 @@ interface CreateGadgetConfig<TSchema extends ZodType> {
  */
 declare function createGadget<TSchema extends ZodType>(config: CreateGadgetConfig<TSchema>): BaseGadget;
 
-/**
- * Create a GadgetOutputViewer gadget instance bound to a specific output store.
- *
- * This is a factory function because the gadget needs access to the output store,
- * which is created per-agent-run.
- *
- * @param store - The GadgetOutputStore to read outputs from
- * @param maxOutputChars - Maximum characters to return (default: 76,800 = ~19k tokens)
- * @returns A GadgetOutputViewer gadget instance
- *
- * @example
- * ```typescript
- * const store = new GadgetOutputStore();
- * const viewer = createGadgetOutputViewer(store, 76_800);
- * registry.register("GadgetOutputViewer", viewer);
- * ```
- */
-declare function createGadgetOutputViewer(store: GadgetOutputStore, maxOutputChars?: number): BaseGadget;
-
 /**
  * Exception that gadgets can throw to signal the agent loop should terminate.
  *
@@ -1669,10 +1652,11 @@ declare class GadgetExecutor {
     private readonly onHumanInputRequired?;
     private readonly defaultGadgetTimeoutMs?;
     private readonly client?;
+    private readonly mediaStore?;
     private readonly logger;
     private readonly errorFormatter;
     private readonly argPrefix;
-    constructor(registry: GadgetRegistry, onHumanInputRequired?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined, errorFormatterOptions?: ErrorFormatterOptions, client?: LLMist | undefined);
+    constructor(registry: GadgetRegistry, onHumanInputRequired?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined, errorFormatterOptions?: ErrorFormatterOptions, client?: LLMist | undefined, mediaStore?: MediaStore | undefined);
     /**
      * Creates a promise that rejects with a TimeoutException after the specified timeout.
      * Aborts the provided AbortController before rejecting, allowing gadgets to clean up.
@@ -1680,7 +1664,8 @@ declare class GadgetExecutor {
     private createTimeoutPromise;
     /**
      * 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.
      */
     private normalizeExecuteResult;
     execute(call: ParsedGadgetCall): Promise<GadgetExecutionResult>;
@@ -1692,6 +1677,25 @@ declare class GadgetExecutor {
     private deepEquals;
 }
 
+/**
+ * Create a GadgetOutputViewer gadget instance bound to a specific output store.
+ *
+ * This is a factory function because the gadget needs access to the output store,
+ * which is created per-agent-run.
+ *
+ * @param store - The GadgetOutputStore to read outputs from
+ * @param maxOutputChars - Maximum characters to return (default: 76,800 = ~19k tokens)
+ * @returns A GadgetOutputViewer gadget instance
+ *
+ * @example
+ * ```typescript
+ * const store = new GadgetOutputStore();
+ * const viewer = createGadgetOutputViewer(store, 76_800);
+ * registry.register("GadgetOutputViewer", viewer);
+ * ```
+ */
+declare function createGadgetOutputViewer(store: GadgetOutputStore, maxOutputChars?: number): BaseGadget;
+
 interface StreamParserOptions {
     startPrefix?: string;
     endPrefix?: string;
@@ -1887,6 +1891,207 @@ declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>):
     };
 };
 
+/**
+ * Helper functions for gadget authors to easily return media outputs.
+ *
+ * These functions provide type-specific conveniences while using the
+ * generic GadgetMediaOutput system underneath.
+ *
+ * @example
+ * ```typescript
+ * import { resultWithImage } from "llmist/gadgets";
+ *
+ * const screenshotGadget = createGadget({
+ *   name: "Screenshot",
+ *   schema: z.object({ url: z.string() }),
+ *   execute: async ({ url }) => {
+ *     const screenshot = await takeScreenshot(url);
+ *     return resultWithImage(
+ *       `Screenshot of ${url}`,
+ *       screenshot,
+ *       { description: "Webpage screenshot" }
+ *     );
+ *   },
+ * });
+ * ```
+ */
+
+/**
+ * Create a GadgetMediaOutput from raw data.
+ *
+ * @param kind - Type of media
+ * @param data - Raw binary data (Buffer or Uint8Array)
+ * @param mimeType - MIME type string
+ * @param options - Optional description, metadata, and fileName
+ * @returns A GadgetMediaOutput ready to include in results
+ */
+declare function createMedia(kind: MediaKind, data: Buffer | Uint8Array, mimeType: string, options?: {
+    description?: string;
+    metadata?: MediaMetadata;
+    fileName?: string;
+}): GadgetMediaOutput;
+/**
+ * Create a result with multiple media outputs.
+ *
+ * @param result - Text result string
+ * @param media - Array of GadgetMediaOutput items (must not be empty)
+ * @param cost - Optional cost in USD
+ * @returns A GadgetExecuteResultWithMedia
+ * @throws Error if media array is empty
+ *
+ * @example
+ * ```typescript
+ * return resultWithMedia(
+ *   "Generated 2 charts",
+ *   [
+ *     createMedia("image", barChartPng, "image/png", { description: "Bar chart" }),
+ *     createMedia("image", pieChartPng, "image/png", { description: "Pie chart" }),
+ *   ],
+ *   0.002
+ * );
+ * ```
+ */
+declare function resultWithMedia(result: string, media: GadgetMediaOutput[], cost?: number): GadgetExecuteResultWithMedia;
+/**
+ * Options for resultWithImage helper.
+ */
+interface ImageOptions {
+    /** MIME type (auto-detected if not provided) */
+    mimeType?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Image dimensions and other metadata */
+    metadata?: MediaMetadata;
+    /** Cost in USD */
+    cost?: number;
+    /** Filename to use when saving (if not provided, auto-generated) */
+    fileName?: string;
+}
+/**
+ * Create a result with a single image output.
+ *
+ * @param result - Text result string
+ * @param imageData - Raw image data (PNG, JPEG, GIF, WebP)
+ * @param options - Optional MIME type, description, metadata, cost
+ * @returns A GadgetExecuteResultWithMedia
+ *
+ * @example
+ * ```typescript
+ * const screenshot = await page.screenshot({ type: "png" });
+ * return resultWithImage(
+ *   "Screenshot captured",
+ *   screenshot,
+ *   { description: "Homepage screenshot", metadata: { width: 1920, height: 1080 } }
+ * );
+ * ```
+ */
+declare function resultWithImage(result: string, imageData: Buffer | Uint8Array, options?: ImageOptions): GadgetExecuteResultWithMedia;
+/**
+ * Image item for resultWithImages helper.
+ */
+interface ImageItem {
+    /** Raw image data */
+    data: Buffer | Uint8Array;
+    /** MIME type (auto-detected if not provided) */
+    mimeType?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Image dimensions and other metadata */
+    metadata?: MediaMetadata;
+    /** Filename to use when saving (if not provided, auto-generated) */
+    fileName?: string;
+}
+/**
+ * Create a result with multiple image outputs.
+ *
+ * @param result - Text result string
+ * @param images - Array of image items (must not be empty)
+ * @param cost - Optional cost in USD
+ * @returns A GadgetExecuteResultWithMedia
+ * @throws Error if images array is empty
+ *
+ * @example
+ * ```typescript
+ * return resultWithImages(
+ *   "Generated comparison images",
+ *   [
+ *     { data: beforeImg, description: "Before" },
+ *     { data: afterImg, description: "After" },
+ *   ],
+ *   0.01
+ * );
+ * ```
+ */
+declare function resultWithImages(result: string, images: ImageItem[], cost?: number): GadgetExecuteResultWithMedia;
+/**
+ * Options for resultWithAudio helper.
+ */
+interface AudioOptions {
+    /** MIME type (auto-detected if not provided) */
+    mimeType?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Cost in USD */
+    cost?: number;
+    /** Filename to use when saving (if not provided, auto-generated) */
+    fileName?: string;
+}
+/**
+ * Create a result with a single audio output.
+ *
+ * @param result - Text result string
+ * @param audioData - Raw audio data (MP3, WAV, OGG, etc.)
+ * @param options - Optional MIME type, description, duration, cost
+ * @returns A GadgetExecuteResultWithMedia
+ *
+ * @example
+ * ```typescript
+ * const speech = await generateSpeech(text);
+ * return resultWithAudio(
+ *   `Generated speech for: "${text.slice(0, 50)}..."`,
+ *   speech,
+ *   { mimeType: "audio/mp3", durationMs: 5000 }
+ * );
+ * ```
+ */
+declare function resultWithAudio(result: string, audioData: Buffer | Uint8Array, options?: AudioOptions): GadgetExecuteResultWithMedia;
+/**
+ * Options for resultWithFile helper.
+ */
+interface FileOptions {
+    /** Human-readable description */
+    description?: string;
+    /** Cost in USD */
+    cost?: number;
+    /** Filename to use when saving (if not provided, auto-generated) */
+    fileName?: string;
+}
+/**
+ * Create a result with a generic file output.
+ *
+ * Use this for arbitrary file types that don't fit image/audio categories.
+ *
+ * @param result - Text result string
+ * @param fileData - Raw file data
+ * @param mimeType - MIME type (required, not auto-detected)
+ * @param options - Optional description and cost
+ * @returns A GadgetExecuteResultWithMedia
+ *
+ * @example
+ * ```typescript
+ * const pdf = await generatePdf(content);
+ * return resultWithFile(
+ *   "Generated PDF report",
+ *   pdf,
+ *   "application/pdf",
+ *   { description: "Monthly report" }
+ * );
+ * ```
+ */
+declare function resultWithFile(result: string, fileData: Buffer | Uint8Array, mimeType: string, options?: FileOptions): GadgetExecuteResultWithMedia;
+
 /**
  * Validation utilities for gadget parameters.
  *
@@ -2317,4 +2522,4 @@ declare class OpenAIChatProvider extends BaseProviderAdapter {
 }
 declare function createOpenAIProviderFromEnv(): OpenAIChatProvider | null;
 
-export { AbortError, AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, CompactionConfig, CompactionContext, CompactionEvent, CompactionManager, CompactionResult, CompactionStats, CompactionStrategy, ConversationManager, type CreateGadgetConfig, ExecutionContext, Gadget, type GadgetConfig, GadgetExample, GadgetExecuteReturn, GadgetExecutionResult, GadgetExecutor, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HintTemplate, type HintsConfig, HookPresets, HumanInputException, HybridStrategy, IConversationManager, type IterationHintOptions, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, LLMist, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, MessageContent, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, type ParallelGadgetHintOptions, ParsedGadgetCall, ProviderAdapter, ResolvedCompactionConfig, SlidingWindowStrategy, type StoredOutput, StreamEvent, StreamParser, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, SummarizationStrategy, TokenUsage, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, iterationProgressHint, parallelGadgetHint, resolveModel, validateAndApplyDefaults, validateGadgetParams };
+export { AbortError, AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, CompactionConfig, CompactionContext, CompactionEvent, CompactionManager, CompactionResult, CompactionStats, CompactionStrategy, ConversationManager, type CreateGadgetConfig, ExecutionContext, Gadget, type GadgetConfig, GadgetExample, GadgetExecuteResultWithMedia, GadgetExecuteReturn, GadgetExecutionResult, GadgetExecutor, GadgetMediaOutput, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HintTemplate, type HintsConfig, HookPresets, HumanInputException, HybridStrategy, IConversationManager, type IterationHintOptions, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, LLMist, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, MediaKind, MediaMetadata, MediaStore, MessageContent, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, type ParallelGadgetHintOptions, ParsedGadgetCall, ProviderAdapter, ResolvedCompactionConfig, SlidingWindowStrategy, type StoredOutput, StreamEvent, StreamParser, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, SummarizationStrategy, TokenUsage, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createLogger, createMedia, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, iterationProgressHint, parallelGadgetHint, resolveModel, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, validateAndApplyDefaults, validateGadgetParams };