llmist 2.5.0 → 3.0.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 { s as AgentHooks, t as ModelRegistry, u as LLMist, C as CompactionConfig, I as IConversationManager, v as CompactionEvent, L as LLMMessage, w as CompactionStats, x as CompactionStrategy, R as ResolvedCompactionConfig, y as CompactionContext, z as CompactionResult, B as MessageContent, G as GadgetMediaOutput, H as HintTemplate, S as StreamEvent, T as TokenUsage, D as GadgetRegistry, E as MediaStore, F as AgentContextConfig, J as SubagentConfigMap, b as LLMStreamChunk, K as ExecutionContext, N as GadgetExecuteReturn, O as GadgetExample, A as AbstractGadget, P as ParsedGadgetCall, Q as GadgetExecutionResult, U as MediaKind, V as MediaMetadata, W as GadgetExecuteResultWithMedia, X as ProviderAdapter, Y as ModelDescriptor, Z as ModelSpec, _ as LLMGenerationOptions, a as LLMStream, $ as ImageModelSpec, a0 as ImageGenerationOptions, a1 as ImageGenerationResult, a2 as SpeechModelSpec, a3 as SpeechGenerationOptions, a4 as SpeechGenerationResult } from './mock-stream-COHw8h9b.js';
+export { ad as AfterGadgetExecutionAction, ae as AfterGadgetExecutionControllerContext, af as AfterLLMCallAction, ag as AfterLLMCallControllerContext, ah as AfterLLMErrorAction, a8 as AgentBuilder, ai as AgentOptions, aG as AudioContentPart, aH as AudioMimeType, aI as AudioSource, aj as BeforeGadgetExecutionAction, ak as BeforeLLMCallAction, al as ChunkInterceptorContext, aJ as ContentPart, am as Controllers, b6 as CostEstimate, bs as CostReportingLLMist, aD as DEFAULT_COMPACTION_CONFIG, bi as DEFAULT_HINTS, bj as DEFAULT_PROMPTS, aE as DEFAULT_SUMMARIZATION_PROMPT, a9 as EventHandlers, bq as GadgetClass, bt as GadgetExecuteResult, an as GadgetExecutionControllerContext, br as GadgetOrClass, ao as GadgetParameterInterceptorContext, ap as GadgetResultInterceptorContext, bu as GadgetSkippedEvent, be as HintContext, a5 as HistoryMessage, aK as ImageBase64Source, aL as ImageContentPart, aM as ImageMimeType, aN as ImageSource, aO as ImageUrlSource, aq as Interceptors, ar as LLMCallControllerContext, as as LLMErrorControllerContext, b4 as LLMMessageBuilder, aF as LLMistOptions, at as MessageInterceptorContext, b2 as MessageRole, 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, b7 as ModelFeatures, bd as ModelIdentifierParser, b8 as ModelLimits, b9 as ModelPricing, av as ObserveChunkContext, aw as ObserveCompactionContext, ax as ObserveGadgetCompleteContext, ay as ObserveGadgetStartContext, az as ObserveLLMCallContext, aA as ObserveLLMCompleteContext, aB as ObserveLLMErrorContext, aC as Observers, bf as PromptContext, bg as PromptTemplate, bh as PromptTemplateConfig, bc as ProviderIdentifier, bv as StoredMedia, aP as TextContentPart, bn as TextGenerationOptions, bw as TextOnlyAction, bx as TextOnlyContext, by as TextOnlyCustomHandler, bz as TextOnlyGadgetConfig, bA as TextOnlyHandler, bB as TextOnlyStrategy, a6 as TrailingMessage, a7 as TrailingMessageContext, ba as VisionAnalyzeOptions, bb as VisionAnalyzeResult, aQ as audioFromBase64, aR as audioFromBuffer, aa as collectEvents, ab as collectText, bo as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, aS as detectAudioMimeType, aT as detectImageMimeType, b3 as extractMessageText, g as getMockManager, aU as imageFromBase64, aV as imageFromBuffer, aW as imageFromUrl, aX as isAudioPart, aY as isDataUrl, aZ as isImagePart, a_ as isTextPart, m as mockLLM, b5 as normalizeMessageContent, a$ as parseDataUrl, bk as resolveHintTemplate, bl as resolvePromptTemplate, bm as resolveRulesTemplate, ac as runWithHandlers, bp as stream, b0 as text, b1 as toBase64 } from './mock-stream-COHw8h9b.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;
+    addGadgetCallResult(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;
 }
 
 /**
@@ -1194,128 +1030,298 @@ interface IterationHintOptions {
      * - "urgent": Show only when >= 80% through iterations
      * @default "always"
      */
-    timing?: "always" | "late" | "urgent";
+    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 requesting human input during execution */
+    requestHumanInput?: (question: string) => Promise<string>;
+    /** Whether to stop on gadget errors */
+    stopOnGadgetError?: boolean;
+    /** Custom error recovery logic */
+    canRecoverFromGadgetError?: (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;
+    /** Parent agent configuration for subagents to inherit */
+    agentConfig?: AgentContextConfig;
+    /** Subagent-specific configuration overrides */
+    subagentConfig?: SubagentConfigMap;
+}
+/**
+ * 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 canRecoverFromGadgetError?;
+    private responseText;
+    private executionHalted;
+    private observerFailureCount;
+    /** Gadgets waiting for their dependencies to complete */
+    private gadgetsAwaitingDependencies;
+    /** 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;
     /**
-     * Whether to include urgency indicators for late iterations.
-     * Adds extra text when running low on iterations.
-     * @default true
+     * 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.
      */
-    showUrgency?: boolean;
+    private processGadgetCall;
     /**
-     * Custom template. Supports placeholders: {iteration}, {maxIterations}, {remaining}
-     * Or a function receiving HintContext.
-     * @default DEFAULT_HINTS.iterationProgressHint
+     * Execute a gadget through the full hook lifecycle.
+     * This is the core execution logic, extracted from processGadgetCall.
      */
-    template?: HintTemplate;
-}
-/**
- * Options for parallel gadget usage hint.
- */
-interface ParallelGadgetHintOptions {
+    private executeGadgetWithHooks;
     /**
-     * Minimum number of gadget calls to consider "efficient".
-     * If response has fewer calls, hint will suggest parallelization.
-     * @default 2
+     * Handle a gadget that cannot execute because a dependency failed.
+     * Calls the onDependencySkipped controller to allow customization.
      */
-    minGadgetsForEfficiency?: number;
+    private handleFailedDependency;
     /**
-     * Custom message when single gadget detected.
-     * @default DEFAULT_HINTS.parallelGadgetsHint
+     * Process pending gadgets whose dependencies are now satisfied.
+     * Executes ready gadgets in parallel and continues until no more can be triggered.
      */
-    message?: string;
+    private processPendingGadgets;
     /**
-     * Whether to enable this hint.
-     * @default true
+     * Safely execute an observer, catching and logging any errors.
+     * Observers are non-critical, so errors are logged but don't crash the system.
      */
-    enabled?: boolean;
-}
-/**
- * Combined hints configuration for createHints().
- */
-interface HintsConfig {
+    private safeObserve;
     /**
-     * Enable iteration progress hints.
-     * Pass `true` for defaults, or options object for customization.
+     * Execute multiple observers in parallel.
+     * All observers run concurrently and failures are tracked but don't crash.
      */
-    iterationProgress?: boolean | IterationHintOptions;
+    private runObserversInParallel;
     /**
-     * Enable parallel gadget hints.
-     * Pass `true` for defaults, or options object for customization.
+     * Check if execution can recover from an error.
+     *
+     * Returns true if we should continue processing subsequent gadgets, false if we should stop.
+     *
+     * Logic:
+     * - If custom canRecoverFromGadgetError is provided, use it
+     * - Otherwise, use stopOnGadgetError config:
+     *   - stopOnGadgetError=true → return false (stop execution)
+     *   - stopOnGadgetError=false → return true (continue execution)
      */
-    parallelGadgets?: boolean | ParallelGadgetHintOptions;
+    private checkCanRecoverFromError;
     /**
-     * Additional custom hooks to merge.
+     * Determine the type of error from a gadget execution.
      */
-    custom?: AgentHooks[];
+    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.
@@ -1539,33 +1545,14 @@ interface CreateGadgetConfig<TSchema extends ZodType> {
  *   .ask("What's the weather in Paris and what's 10 + 5?");
  * ```
  */
-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;
+declare function createGadget<TSchema extends ZodType>(config: CreateGadgetConfig<TSchema>): AbstractGadget;
 
 /**
- * Exception that gadgets can throw to signal the agent loop should terminate.
+ * Signal that a gadget throws to indicate task completion and agent termination.
  *
- * When a gadget throws this exception, the agent loop will:
+ * When a gadget throws this signal, the agent loop will:
  * 1. Complete the current iteration
- * 2. Return the exception message as the gadget's result
+ * 2. Return the signal message as the gadget's result
  * 3. Exit the loop instead of continuing to the next iteration
  *
  * @example
@@ -1581,12 +1568,12 @@ declare function createGadgetOutputViewer(store: GadgetOutputStore, maxOutputCha
  * }) {
  *   execute(params: this['params']): string {
  *     const message = params.message || 'Task completed';
- *     throw new BreakLoopException(message);
+ *     throw new TaskCompletionSignal(message);
  *   }
  * }
  * ```
  */
-declare class BreakLoopException extends Error {
+declare class TaskCompletionSignal extends Error {
     constructor(message?: string);
 }
 /**
@@ -1594,7 +1581,7 @@ declare class BreakLoopException extends Error {
  *
  * When a gadget throws this exception, the agent loop will:
  * 1. Pause execution and wait for human input
- * 2. If `onHumanInputRequired` callback is provided, call it and await the answer
+ * 2. If `requestHumanInput` callback is provided, call it and await the answer
  * 3. Return the user's answer as the gadget's result
  * 4. Continue the loop with the answer added to conversation history
  *
@@ -1613,15 +1600,49 @@ declare class BreakLoopException extends Error {
  *   }),
  * }) {
  *   execute(params: this['params']): string {
- *     throw new HumanInputException(params.question);
+ *     throw new HumanInputRequiredException(params.question);
  *   }
  * }
  * ```
  */
-declare class HumanInputException extends Error {
+declare class HumanInputRequiredException extends Error {
     readonly question: string;
     constructor(question: string);
 }
+/**
+ * Exception thrown when a gadget execution exceeds its timeout limit.
+ *
+ * When a gadget's execution time exceeds either:
+ * - The gadget's own `timeoutMs` property, or
+ * - The global `defaultGadgetTimeoutMs` configured in runtime/agent loop options
+ *
+ * The executor will automatically throw this exception and return it as an error.
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * class SlowApiGadget extends Gadget({
+ *   name: 'SlowApi',
+ *   description: 'Calls a slow external API',
+ *   timeoutMs: 5000, // 5 second timeout
+ *   schema: z.object({
+ *     endpoint: z.string(),
+ *   }),
+ * }) {
+ *   async execute(params: this['params']): Promise<string> {
+ *     // If this takes longer than 5 seconds, execution will be aborted
+ *     const response = await fetch(params.endpoint);
+ *     return await response.text();
+ *   }
+ * }
+ * ```
+ */
+declare class TimeoutException extends Error {
+    readonly timeoutMs: number;
+    readonly gadgetName: string;
+    constructor(gadgetName: string, timeoutMs: number);
+}
 /**
  * Exception thrown when gadget execution is aborted.
  *
@@ -1637,7 +1658,7 @@ declare class HumanInputException extends Error {
  *   schema: z.object({ data: z.string() }),
  * }) {
  *   async execute(params: this['params'], ctx: ExecutionContext): Promise<string> {
- *     // Check at key points - throws AbortError if aborted
+ *     // Check at key points - throws AbortException if aborted
  *     this.throwIfAborted(ctx);
  *
  *     await this.doPartOne(params.data);
@@ -1651,7 +1672,7 @@ declare class HumanInputException extends Error {
  * }
  * ```
  */
-declare class AbortError extends Error {
+declare class AbortException extends Error {
     constructor(message?: string);
 }
 
@@ -1666,23 +1687,27 @@ interface ErrorFormatterOptions {
 
 declare class GadgetExecutor {
     private readonly registry;
-    private readonly onHumanInputRequired?;
+    private readonly requestHumanInput?;
     private readonly defaultGadgetTimeoutMs?;
     private readonly client?;
+    private readonly mediaStore?;
+    private readonly agentConfig?;
+    private readonly subagentConfig?;
     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, requestHumanInput?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined, errorFormatterOptions?: ErrorFormatterOptions, client?: LLMist | undefined, mediaStore?: MediaStore | undefined, agentConfig?: AgentContextConfig | undefined, subagentConfig?: SubagentConfigMap | undefined);
     /**
      * Creates a promise that rejects with a TimeoutException after the specified timeout.
      * Aborts the provided AbortController before rejecting, allowing gadgets to clean up.
      */
     private createTimeoutPromise;
     /**
-     * Normalizes gadget execute result to consistent format.
-     * Handles both string returns (backwards compat) and object returns with cost.
+     * Unify gadget execute result to consistent internal format.
+     * Handles string returns (backwards compat), object returns with cost,
+     * and object returns with media.
      */
-    private normalizeExecuteResult;
+    private unifyExecuteResult;
     execute(call: ParsedGadgetCall): Promise<GadgetExecutionResult>;
     executeAll(calls: ParsedGadgetCall[]): Promise<GadgetExecutionResult[]>;
     /**
@@ -1692,22 +1717,49 @@ 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): AbstractGadget;
+
 interface StreamParserOptions {
     startPrefix?: string;
     endPrefix?: string;
     /** Prefix for block format arguments. Default: "!!!ARG:" */
     argPrefix?: string;
 }
-declare class StreamParser {
+/**
+ * Parser for extracting gadget invocations from LLM text output.
+ * Processes text chunks incrementally and emits events for text and gadget calls.
+ */
+declare class GadgetCallParser {
     private buffer;
-    private lastReportedTextLength;
+    private lastEmittedTextOffset;
     private readonly startPrefix;
     private readonly endPrefix;
     private readonly argPrefix;
     constructor(options?: StreamParserOptions);
-    private takeTextUntil;
     /**
-     * Parse gadget name with optional invocation ID and dependencies.
+     * Extract and consume text up to the given index.
+     * Returns undefined if no meaningful text to emit.
+     */
+    private extractTextSegment;
+    /**
+     * Parse gadget invocation metadata from the header line.
      *
      * Supported formats:
      * - `GadgetName` - Auto-generate ID, no dependencies
@@ -1716,7 +1768,7 @@ declare class StreamParser {
      *
      * Dependencies must be comma-separated invocation IDs.
      */
-    private parseGadgetName;
+    private parseInvocationMetadata;
     /**
      * Extract the error message from a parse error.
      * Preserves full message since the error formatter adds contextual help
@@ -1887,6 +1939,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 createMediaOutput(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",
+ *   [
+ *     createMediaOutput("image", barChartPng, "image/png", { description: "Bar chart" }),
+ *     createMediaOutput("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.
  *
@@ -1978,7 +2231,7 @@ declare function validateAndApplyDefaults<T = Record<string, unknown>>(schema: Z
  * }
  * ```
  */
-declare function validateGadgetParams(gadget: BaseGadget, params: Record<string, unknown>): ValidationResult;
+declare function validateGadgetParams(gadget: AbstractGadget, params: Record<string, unknown>): ValidationResult;
 
 /**
  * Logger configuration options for the library.
@@ -2070,16 +2323,16 @@ declare abstract class BaseProviderAdapter implements ProviderAdapter {
      */
     protected prepareMessages(messages: LLMMessage[]): LLMMessage[];
     /**
-     * Build the provider-specific request payload.
+     * Build the provider-specific API request.
      * This method must be implemented by each concrete provider.
      *
      * @param options - The generation options
      * @param descriptor - The model descriptor
      * @param spec - Optional model specification with metadata
      * @param messages - The prepared messages
-     * @returns Provider-specific payload ready for the API call
+     * @returns Provider-specific request object ready for the API call
      */
-    protected abstract buildRequestPayload(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec: ModelSpec | undefined, messages: LLMMessage[]): unknown;
+    protected abstract buildApiRequest(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec: ModelSpec | undefined, messages: LLMMessage[]): unknown;
     /**
      * Execute the stream request using the provider's SDK.
      * This method must be implemented by each concrete provider.
@@ -2090,13 +2343,13 @@ declare abstract class BaseProviderAdapter implements ProviderAdapter {
      */
     protected abstract executeStreamRequest(payload: unknown, signal?: AbortSignal): Promise<AsyncIterable<unknown>>;
     /**
-     * Wrap the provider-specific stream into the universal LLMStream format.
+     * Normalize the provider-specific stream into the universal LLMStream format.
      * This method must be implemented by each concrete provider.
      *
      * @param rawStream - The provider-specific stream
      * @returns Universal LLMStream
      */
-    protected abstract wrapStream(rawStream: AsyncIterable<unknown>): LLMStream;
+    protected abstract normalizeProviderStream(rawStream: AsyncIterable<unknown>): LLMStream;
 }
 
 declare class AnthropicMessagesProvider extends BaseProviderAdapter {
@@ -2107,7 +2360,7 @@ declare class AnthropicMessagesProvider extends BaseProviderAdapter {
     generateImage(): Promise<never>;
     supportsSpeechGeneration(_modelId: string): boolean;
     generateSpeech(): Promise<never>;
-    protected buildRequestPayload(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec: ModelSpec | undefined, messages: LLMMessage[]): MessageCreateParamsStreaming;
+    protected buildApiRequest(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec: ModelSpec | undefined, messages: LLMMessage[]): MessageCreateParamsStreaming;
     /**
      * Convert llmist content to Anthropic's content block format.
      * Handles text, images (base64 only), and applies cache_control.
@@ -2118,7 +2371,7 @@ declare class AnthropicMessagesProvider extends BaseProviderAdapter {
      */
     private convertImagePart;
     protected executeStreamRequest(payload: MessageCreateParamsStreaming, signal?: AbortSignal): Promise<AsyncIterable<MessageStreamEvent>>;
-    protected wrapStream(iterable: AsyncIterable<unknown>): LLMStream;
+    protected normalizeProviderStream(iterable: AsyncIterable<unknown>): LLMStream;
     /**
      * Count tokens in messages using Anthropic's native token counting API.
      *
@@ -2193,7 +2446,7 @@ declare class GeminiGenerativeProvider extends BaseProviderAdapter {
     getSpeechModelSpecs(): SpeechModelSpec[];
     supportsSpeechGeneration(modelId: string): boolean;
     generateSpeech(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
-    protected buildRequestPayload(options: LLMGenerationOptions, descriptor: ModelDescriptor, _spec: ModelSpec | undefined, messages: LLMMessage[]): {
+    protected buildApiRequest(options: LLMGenerationOptions, descriptor: ModelDescriptor, _spec: ModelSpec | undefined, messages: LLMMessage[]): {
         model: string;
         contents: GeminiContent[];
         config: Record<string, unknown>;
@@ -2229,8 +2482,8 @@ declare class GeminiGenerativeProvider extends BaseProviderAdapter {
      */
     private convertToGeminiParts;
     private buildGenerationConfig;
-    protected wrapStream(iterable: AsyncIterable<unknown>): LLMStream;
-    private extractText;
+    protected normalizeProviderStream(iterable: AsyncIterable<unknown>): LLMStream;
+    private extractMessageText;
     private extractFinishReason;
     private extractUsage;
     /**
@@ -2270,7 +2523,7 @@ declare class OpenAIChatProvider extends BaseProviderAdapter {
     getSpeechModelSpecs(): SpeechModelSpec[];
     supportsSpeechGeneration(modelId: string): boolean;
     generateSpeech(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
-    protected buildRequestPayload(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec: ModelSpec | undefined, messages: LLMMessage[]): Parameters<OpenAI["chat"]["completions"]["create"]>[0];
+    protected buildApiRequest(options: LLMGenerationOptions, descriptor: ModelDescriptor, spec: ModelSpec | undefined, messages: LLMMessage[]): Parameters<OpenAI["chat"]["completions"]["create"]>[0];
     /**
      * Convert an LLMMessage to OpenAI's ChatCompletionMessageParam.
      * Handles role-specific content type requirements:
@@ -2289,7 +2542,7 @@ declare class OpenAIChatProvider extends BaseProviderAdapter {
      */
     private convertImagePart;
     protected executeStreamRequest(payload: Parameters<OpenAI["chat"]["completions"]["create"]>[0], signal?: AbortSignal): Promise<AsyncIterable<ChatCompletionChunk>>;
-    protected wrapStream(iterable: AsyncIterable<unknown>): LLMStream;
+    protected normalizeProviderStream(iterable: AsyncIterable<unknown>): LLMStream;
     /**
      * Count tokens in messages using OpenAI's tiktoken library.
      *
@@ -2317,4 +2570,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 { AbortException, AbstractGadget, AgentHooks, AnthropicMessagesProvider, CompactionConfig, CompactionContext, CompactionEvent, CompactionManager, CompactionResult, CompactionStats, CompactionStrategy, ConversationManager, type CreateGadgetConfig, ExecutionContext, Gadget, GadgetCallParser, type GadgetConfig, GadgetExample, GadgetExecuteResultWithMedia, GadgetExecuteReturn, GadgetExecutionResult, GadgetExecutor, GadgetMediaOutput, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HintTemplate, type HintsConfig, HookPresets, HumanInputRequiredException, 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, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, SummarizationStrategy, TaskCompletionSignal, TimeoutException, TokenUsage, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createLogger, createMediaOutput, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, iterationProgressHint, parallelGadgetHint, resolveModel, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, validateAndApplyDefaults, validateGadgetParams };