llmist 2.6.0 → 3.1.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, 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 { 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, N as NestedAgentEvent, b as LLMStreamChunk, K as ExecutionContext, O as GadgetExecuteReturn, P as GadgetExample, A as AbstractGadget, Q as ParsedGadgetCall, U as GadgetExecutionResult, V as MediaKind, W as MediaMetadata, X as GadgetExecuteResultWithMedia, Y as ProviderAdapter, Z as ModelDescriptor, _ as ModelSpec, $ as LLMGenerationOptions, a as LLMStream, a0 as ImageModelSpec, a1 as ImageGenerationOptions, a2 as ImageGenerationResult, a3 as SpeechModelSpec, a4 as SpeechGenerationOptions, a5 as SpeechGenerationResult } from './mock-stream-CTLm00_q.js';
+export { ae as AfterGadgetExecutionAction, af as AfterGadgetExecutionControllerContext, ag as AfterLLMCallAction, ah as AfterLLMCallControllerContext, ai as AfterLLMErrorAction, a9 as AgentBuilder, aj as AgentOptions, aH as AudioContentPart, aI as AudioMimeType, aJ as AudioSource, ak as BeforeGadgetExecutionAction, al as BeforeLLMCallAction, am as ChunkInterceptorContext, aK as ContentPart, an as Controllers, b7 as CostEstimate, bt as CostReportingLLMist, aE as DEFAULT_COMPACTION_CONFIG, bj as DEFAULT_HINTS, bk as DEFAULT_PROMPTS, aF as DEFAULT_SUMMARIZATION_PROMPT, aa as EventHandlers, br as GadgetClass, bu as GadgetExecuteResult, ao as GadgetExecutionControllerContext, bs as GadgetOrClass, ap as GadgetParameterInterceptorContext, aq as GadgetResultInterceptorContext, bv as GadgetSkippedEvent, bf as HintContext, a6 as HistoryMessage, aL as ImageBase64Source, aM as ImageContentPart, aN as ImageMimeType, aO as ImageSource, aP as ImageUrlSource, ar as Interceptors, as as LLMCallControllerContext, at as LLMErrorControllerContext, b5 as LLMMessageBuilder, aG as LLMistOptions, au as MessageInterceptorContext, b3 as MessageRole, av 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, b8 as ModelFeatures, be as ModelIdentifierParser, b9 as ModelLimits, ba as ModelPricing, aw as ObserveChunkContext, ax as ObserveCompactionContext, ay as ObserveGadgetCompleteContext, az as ObserveGadgetStartContext, aA as ObserveLLMCallContext, aB as ObserveLLMCompleteContext, aC as ObserveLLMErrorContext, aD as Observers, bg as PromptContext, bh as PromptTemplate, bi as PromptTemplateConfig, bd as ProviderIdentifier, bw as StoredMedia, aQ as TextContentPart, bo as TextGenerationOptions, bx as TextOnlyAction, by as TextOnlyContext, bz as TextOnlyCustomHandler, bA as TextOnlyGadgetConfig, bB as TextOnlyHandler, bC as TextOnlyStrategy, a7 as TrailingMessage, a8 as TrailingMessageContext, bb as VisionAnalyzeOptions, bc as VisionAnalyzeResult, aR as audioFromBase64, aS as audioFromBuffer, ab as collectEvents, ac as collectText, bp as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, aT as detectAudioMimeType, aU as detectImageMimeType, b4 as extractMessageText, g as getMockManager, aV as imageFromBase64, aW as imageFromBuffer, aX as imageFromUrl, aY as isAudioPart, aZ as isDataUrl, a_ as isImagePart, a$ as isTextPart, m as mockLLM, b6 as normalizeMessageContent, b0 as parseDataUrl, bl as resolveHintTemplate, bm as resolvePromptTemplate, bn as resolveRulesTemplate, ad as runWithHandlers, bq as stream, b1 as text, b2 as toBase64 } from './mock-stream-CTLm00_q.js';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';
@@ -888,7 +888,7 @@ declare class ConversationManager implements IConversationManager {
     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;
+    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, media?: GadgetMediaOutput[], mediaIds?: string[]): void;
     getMessages(): LLMMessage[];
     getHistoryMessages(): LLMMessage[];
     getBaseMessages(): LLMMessage[];
@@ -1178,12 +1178,12 @@ interface StreamProcessorOptions {
     hooks?: AgentHooks;
     /** Logger instance */
     logger?: Logger<ILogObj>;
-    /** Callback for human input */
-    onHumanInputRequired?: (question: string) => Promise<string>;
+    /** Callback for requesting human input during execution */
+    requestHumanInput?: (question: string) => Promise<string>;
     /** Whether to stop on gadget errors */
     stopOnGadgetError?: boolean;
-    /** Custom error continuation logic */
-    shouldContinueAfterError?: (context: {
+    /** Custom error recovery logic */
+    canRecoverFromGadgetError?: (context: {
         error: string;
         gadgetName: string;
         errorType: "parse" | "validation" | "execution";
@@ -1195,6 +1195,12 @@ interface StreamProcessorOptions {
     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;
+    /** Callback for subagent gadgets to report nested events to parent */
+    onNestedEvent?: (event: NestedAgentEvent) => void;
 }
 /**
  * Result of stream processing.
@@ -1245,25 +1251,38 @@ declare class StreamProcessor {
     private readonly parser;
     private readonly executor;
     private readonly stopOnGadgetError;
-    private readonly shouldContinueAfterError?;
-    private accumulatedText;
-    private shouldStopExecution;
+    private readonly canRecoverFromGadgetError?;
+    private responseText;
+    private executionHalted;
     private observerFailureCount;
     /** Gadgets waiting for their dependencies to complete */
-    private pendingGadgets;
+    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 an LLM stream and yield events in real-time.
+     *
+     * This is an async generator that yields events immediately as they occur:
+     * - Text events are yielded as text is streamed from the LLM
+     * - gadget_call events are yielded immediately when a gadget call is parsed
+     * - gadget_result events are yielded when gadget execution completes
+     *
+     * The final event is always a StreamCompletionEvent containing metadata.
      */
-    process(stream: AsyncIterable<LLMStreamChunk>): Promise<StreamProcessingResult>;
+    process(stream: AsyncIterable<LLMStreamChunk>): AsyncGenerator<StreamEvent>;
     /**
      * Process a single parsed event (text or gadget call).
+     * @deprecated Use processEventGenerator for real-time streaming
      */
     private processEvent;
+    /**
+     * Process a single parsed event, yielding events in real-time.
+     * Generator version of processEvent for streaming support.
+     */
+    private processEventGenerator;
     /**
      * Process a text event through interceptors.
      */
@@ -1276,11 +1295,24 @@ declare class StreamProcessor {
      * After each execution, pending gadgets are checked to see if they can now run.
      */
     private processGadgetCall;
+    /**
+     * Process a gadget call, yielding events in real-time.
+     *
+     * Key difference from processGadgetCall: yields gadget_call event IMMEDIATELY
+     * when parsed (before execution), enabling real-time UI feedback.
+     */
+    private processGadgetCallGenerator;
     /**
      * Execute a gadget through the full hook lifecycle.
      * This is the core execution logic, extracted from processGadgetCall.
+     * @deprecated Use executeGadgetGenerator for real-time streaming
      */
     private executeGadgetWithHooks;
+    /**
+     * Execute a gadget and yield the result event.
+     * Generator version that yields gadget_result immediately when execution completes.
+     */
+    private executeGadgetGenerator;
     /**
      * Handle a gadget that cannot execute because a dependency failed.
      * Calls the onDependencySkipped controller to allow customization.
@@ -1291,6 +1323,14 @@ declare class StreamProcessor {
      * Executes ready gadgets in parallel and continues until no more can be triggered.
      */
     private processPendingGadgets;
+    /**
+     * Process pending gadgets, yielding events in real-time.
+     * Generator version that yields events as gadgets complete.
+     *
+     * Note: Gadgets are still executed in parallel for efficiency,
+     * but results are yielded as they become available.
+     */
+    private processPendingGadgetsGenerator;
     /**
      * Safely execute an observer, catching and logging any errors.
      * Observers are non-critical, so errors are logged but don't crash the system.
@@ -1302,17 +1342,17 @@ declare class StreamProcessor {
      */
     private runObserversInParallel;
     /**
-     * Check if execution should continue after an error.
+     * 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 shouldContinueAfterError is provided, use it
+     * - If custom canRecoverFromGadgetError is provided, use it
      * - Otherwise, use stopOnGadgetError config:
      *   - stopOnGadgetError=true → return false (stop execution)
      *   - stopOnGadgetError=false → return true (continue execution)
      */
-    private checkContinueAfterError;
+    private checkCanRecoverFromError;
     /**
      * Determine the type of error from a gadget execution.
      */
@@ -1541,14 +1581,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;
+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
@@ -1564,12 +1604,12 @@ declare function createGadget<TSchema extends ZodType>(config: CreateGadgetConfi
  * }) {
  *   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);
 }
 /**
@@ -1577,7 +1617,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
  *
@@ -1596,15 +1636,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.
  *
@@ -1620,7 +1694,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);
@@ -1634,7 +1708,7 @@ declare class HumanInputException extends Error {
  * }
  * ```
  */
-declare class AbortError extends Error {
+declare class AbortException extends Error {
     constructor(message?: string);
 }
 
@@ -1649,25 +1723,28 @@ 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 onNestedEvent?;
     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, mediaStore?: MediaStore | 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, onNestedEvent?: ((event: NestedAgentEvent) => void) | 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.
+     * 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[]>;
     /**
@@ -1694,7 +1771,7 @@ declare class GadgetExecutor {
  * registry.register("GadgetOutputViewer", viewer);
  * ```
  */
-declare function createGadgetOutputViewer(store: GadgetOutputStore, maxOutputChars?: number): BaseGadget;
+declare function createGadgetOutputViewer(store: GadgetOutputStore, maxOutputChars?: number): AbstractGadget;
 
 interface StreamParserOptions {
     startPrefix?: string;
@@ -1702,16 +1779,24 @@ interface StreamParserOptions {
     /** 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
@@ -1720,7 +1805,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
@@ -1925,7 +2010,7 @@ declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>):
  * @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?: {
+declare function createMediaOutput(kind: MediaKind, data: Buffer | Uint8Array, mimeType: string, options?: {
     description?: string;
     metadata?: MediaMetadata;
     fileName?: string;
@@ -1944,8 +2029,8 @@ declare function createMedia(kind: MediaKind, data: Buffer | Uint8Array, mimeTyp
  * return resultWithMedia(
  *   "Generated 2 charts",
  *   [
- *     createMedia("image", barChartPng, "image/png", { description: "Bar chart" }),
- *     createMedia("image", pieChartPng, "image/png", { description: "Pie chart" }),
+ *     createMediaOutput("image", barChartPng, "image/png", { description: "Bar chart" }),
+ *     createMediaOutput("image", pieChartPng, "image/png", { description: "Pie chart" }),
  *   ],
  *   0.002
  * );
@@ -2183,7 +2268,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.
@@ -2275,16 +2360,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.
@@ -2295,13 +2380,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 {
@@ -2312,7 +2397,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.
@@ -2323,7 +2408,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.
      *
@@ -2398,7 +2483,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>;
@@ -2434,8 +2519,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;
     /**
@@ -2475,7 +2560,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:
@@ -2494,7 +2579,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.
      *
@@ -2522,4 +2607,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, 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 };
+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 };

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   Gadget,
   HookPresets,
   createHints,
-  createMedia,
+  createMediaOutput,
   iterationProgressHint,
   parallelGadgetHint,
   resultWithAudio,
@@ -11,24 +11,24 @@ import {
   resultWithImages,
   resultWithMedia,
   z
-} from "./chunk-4IHLIYW5.js";
+} from "./chunk-LFI4WQVV.js";
 import {
-  AbortError,
+  AbortException,
+  AbstractGadget,
   AgentBuilder,
   AnthropicMessagesProvider,
-  BaseGadget,
-  BreakLoopException,
   CompactionManager,
   ConversationManager,
   DEFAULT_COMPACTION_CONFIG,
   DEFAULT_HINTS,
   DEFAULT_PROMPTS,
   DEFAULT_SUMMARIZATION_PROMPT,
+  GadgetCallParser,
   GadgetExecutor,
   GadgetOutputStore,
   GadgetRegistry,
   GeminiGenerativeProvider,
-  HumanInputException,
+  HumanInputRequiredException,
   HybridStrategy,
   LLMMessageBuilder,
   LLMist,
@@ -41,9 +41,10 @@ import {
   ModelRegistry,
   OpenAIChatProvider,
   SlidingWindowStrategy,
-  StreamParser,
   StreamProcessor,
   SummarizationStrategy,
+  TaskCompletionSignal,
+  TimeoutException,
   audioFromBase64,
   audioFromBuffer,
   collectEvents,
@@ -63,7 +64,7 @@ import {
   detectAudioMimeType,
   detectImageMimeType,
   discoverProviderAdapters,
-  extractText,
+  extractMessageText,
   getMockManager,
   getModelId,
   getProvider,
@@ -76,7 +77,7 @@ import {
   isImagePart,
   isTextPart,
   mockLLM,
-  normalizeContent,
+  normalizeMessageContent,
   parseDataUrl,
   resolveHintTemplate,
   resolveModel,
@@ -88,13 +89,12 @@ import {
   toBase64,
   validateAndApplyDefaults,
   validateGadgetParams
-} from "./chunk-364PEMVT.js";
+} from "./chunk-JCFPJMRQ.js";
 export {
-  AbortError,
+  AbortException,
+  AbstractGadget,
   AgentBuilder,
   AnthropicMessagesProvider,
-  BaseGadget,
-  BreakLoopException,
   CompactionManager,
   ConversationManager,
   DEFAULT_COMPACTION_CONFIG,
@@ -102,12 +102,13 @@ export {
   DEFAULT_PROMPTS,
   DEFAULT_SUMMARIZATION_PROMPT,
   Gadget,
+  GadgetCallParser,
   GadgetExecutor,
   GadgetOutputStore,
   GadgetRegistry,
   GeminiGenerativeProvider,
   HookPresets,
-  HumanInputException,
+  HumanInputRequiredException,
   HybridStrategy,
   LLMMessageBuilder,
   LLMist,
@@ -120,9 +121,10 @@ export {
   ModelRegistry,
   OpenAIChatProvider,
   SlidingWindowStrategy,
-  StreamParser,
   StreamProcessor,
   SummarizationStrategy,
+  TaskCompletionSignal,
+  TimeoutException,
   audioFromBase64,
   audioFromBuffer,
   collectEvents,
@@ -134,7 +136,7 @@ export {
   createGeminiProviderFromEnv,
   createHints,
   createLogger,
-  createMedia,
+  createMediaOutput,
   createMockAdapter,
   createMockClient,
   createMockStream,
@@ -144,7 +146,7 @@ export {
   detectAudioMimeType,
   detectImageMimeType,
   discoverProviderAdapters,
-  extractText,
+  extractMessageText,
   getMockManager,
   getModelId,
   getProvider,
@@ -158,7 +160,7 @@ export {
   isTextPart,
   iterationProgressHint,
   mockLLM,
-  normalizeContent,
+  normalizeMessageContent,
   parallelGadgetHint,
   parseDataUrl,
   resolveHintTemplate,