llmist 16.0.3 → 16.1.0

package/dist/index.d.ts

@@ -632,8 +632,6 @@ interface CompleteGadgetParams {
     storedMedia?: StoredMedia[];
 }
 
-/** Event listener function type */
-type EventListener = (event: ExecutionEvent) => void;
 /**
  * The Execution Tree - single source of truth for all execution state.
  *
@@ -668,12 +666,9 @@ type EventListener = (event: ExecutionEvent) => void;
 declare class ExecutionTree {
     private nodes;
     private rootIds;
-    private eventListeners;
-    private eventIdCounter;
     private invocationIdToNodeId;
-    private eventQueue;
-    private eventWaiters;
-    private isCompleted;
+    private emitter;
+    private aggregator;
     /**
      * Base depth for all nodes in this tree.
      * Used when this tree is a subagent's view into a parent tree.
@@ -831,11 +826,11 @@ declare class ExecutionTree {
      * });
      * ```
      */
-    on(type: ExecutionEventType, listener: EventListener): () => void;
+    on(type: ExecutionEventType, listener: (event: ExecutionEvent) => void): () => void;
     /**
      * Subscribe to all events.
      */
-    onAll(listener: EventListener): () => void;
+    onAll(listener: (event: ExecutionEvent) => void): () => void;
     /**
      * Get async iterable of all events.
      * Events are yielded as they occur.
@@ -843,6 +838,7 @@ declare class ExecutionTree {
     events(): AsyncGenerator<ExecutionEvent>;
     /**
      * Mark the tree as complete (no more events will be emitted).
+     * Wakes up any consumers waiting in the events() async generator.
      */
     complete(): void;
     /**
@@ -1127,7 +1123,6 @@ declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>):
         throwIfAborted(ctx?: ExecutionContext): void;
         onAbort(ctx: ExecutionContext | undefined, cleanup: () => void | Promise<void>): void;
         createLinkedAbortController(ctx?: ExecutionContext): AbortController;
-        get instruction(): string;
         getInstruction(optionsOrArgPrefix?: string | {
             argPrefix?: string;
             startPrefix?: string;
@@ -1138,6 +1133,253 @@ declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>):
     };
 };
 
+/**
+ * Proactive rate limiting for LLM API calls.
+ *
+ * Tracks request and token usage in sliding windows to prevent rate limit errors
+ * before they occur. Works in conjunction with reactive backoff (retry.ts) for
+ * comprehensive rate limit handling.
+ */
+/**
+ * Configuration for proactive rate limiting.
+ *
+ * Set these values based on your API tier to prevent rate limit errors.
+ * When limits are approached, requests will be automatically delayed.
+ *
+ * @example
+ * ```typescript
+ * // Gemini free tier limits
+ * const agent = LLMist.createAgent()
+ *   .withRateLimits({
+ *     requestsPerMinute: 15,
+ *     tokensPerMinute: 1_000_000,
+ *     safetyMargin: 0.8,
+ *   });
+ *
+ * // OpenAI Tier 1 limits
+ * const agent = LLMist.createAgent()
+ *   .withRateLimits({
+ *     requestsPerMinute: 500,
+ *     tokensPerMinute: 200_000,
+ *   });
+ * ```
+ */
+interface RateLimitConfig {
+    /**
+     * Maximum requests per minute.
+     * Set based on your API tier. If not set, RPM limiting is disabled.
+     */
+    requestsPerMinute?: number;
+    /**
+     * Maximum tokens per minute (input + output combined).
+     * Set based on your API tier. If not set, TPM limiting is disabled.
+     */
+    tokensPerMinute?: number;
+    /**
+     * Maximum tokens per day (optional).
+     * Useful for Gemini free tier which has daily limits.
+     * If not set, daily limiting is disabled.
+     */
+    tokensPerDay?: number;
+    /**
+     * Safety margin - start throttling at this percentage of limit.
+     * A value of 0.9 means throttling starts at 90% of the limit.
+     * Lower values provide more safety but may reduce throughput.
+     * @default 0.9
+     */
+    safetyMargin?: number;
+    /**
+     * Whether proactive rate limiting is enabled.
+     * @default true (when any limit is configured)
+     */
+    enabled?: boolean;
+}
+/**
+ * Resolved rate limit configuration with all defaults applied.
+ */
+interface ResolvedRateLimitConfig {
+    requestsPerMinute?: number;
+    tokensPerMinute?: number;
+    tokensPerDay?: number;
+    safetyMargin: number;
+    enabled: boolean;
+}
+/**
+ * Default rate limit configuration values.
+ */
+declare const DEFAULT_RATE_LIMIT_CONFIG: Pick<ResolvedRateLimitConfig, "safetyMargin" | "enabled">;
+/**
+ * Resolves a partial rate limit configuration by applying defaults.
+ *
+ * @param config - Partial configuration (optional)
+ * @returns Fully resolved configuration
+ */
+declare function resolveRateLimitConfig(config?: RateLimitConfig): ResolvedRateLimitConfig;
+/**
+ * Information about a triggered rate limit.
+ */
+interface TriggeredLimitInfo {
+    /** Current usage value */
+    current: number;
+    /** Configured limit value */
+    limit: number;
+    /** Effective limit after safety margin (limit × safetyMargin) */
+    effectiveLimit: number;
+}
+/**
+ * Usage statistics from the rate limit tracker.
+ */
+interface RateLimitStats {
+    /** Current requests per minute */
+    rpm: number;
+    /** Current tokens per minute */
+    tpm: number;
+    /** Tokens used today (UTC) */
+    dailyTokens: number;
+    /** Whether any limit is currently being approached */
+    isApproachingLimit: boolean;
+    /** Delay required before next request (0 if none) */
+    requiredDelayMs: number;
+    /** Which limit(s) triggered throttling, if any (present when requiredDelayMs > 0) */
+    triggeredBy?: {
+        rpm?: TriggeredLimitInfo;
+        tpm?: TriggeredLimitInfo;
+        daily?: TriggeredLimitInfo;
+    };
+}
+/**
+ * Tracks API usage and calculates required delays for proactive rate limiting.
+ *
+ * Uses sliding windows to track requests and token usage, automatically
+ * calculating delays needed to stay within configured limits.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new RateLimitTracker({
+ *   requestsPerMinute: 60,
+ *   tokensPerMinute: 100000,
+ * });
+ *
+ * // Before each request
+ * const delay = tracker.getRequiredDelayMs();
+ * if (delay > 0) {
+ *   await sleep(delay);
+ * }
+ *
+ * // After each request
+ * tracker.recordUsage(inputTokens, outputTokens);
+ * ```
+ */
+declare class RateLimitTracker {
+    private config;
+    /** Timestamps of requests in the current minute window */
+    private requestTimestamps;
+    /** Token usage entries in the current minute window */
+    private tokenUsage;
+    /** Daily token count */
+    private dailyTokens;
+    /** Date string (YYYY-MM-DD UTC) for daily reset tracking */
+    private dailyResetDate;
+    /** Count of pending reservations (for backward compatibility) */
+    private pendingReservations;
+    constructor(config?: RateLimitConfig);
+    /**
+     * Record a completed request with its token usage.
+     *
+     * If reserveRequest() was called before the LLM call (recommended for concurrent
+     * scenarios), the request timestamp was already recorded. Otherwise, this method
+     * will add it for backward compatibility.
+     *
+     * @param inputTokens - Number of input tokens used
+     * @param outputTokens - Number of output tokens generated
+     */
+    recordUsage(inputTokens: number, outputTokens: number): void;
+    /**
+     * Calculate the delay needed before the next request.
+     *
+     * Returns 0 if no delay is needed, otherwise returns the number of
+     * milliseconds to wait to stay within rate limits.
+     *
+     * @returns Delay in milliseconds (0 if none needed)
+     */
+    getRequiredDelayMs(): number;
+    /**
+     * Check if we're approaching any configured limits.
+     *
+     * @returns true if any limit is at or above the safety margin threshold
+     */
+    isApproachingLimit(): boolean;
+    /**
+     * Get current usage statistics.
+     *
+     * @returns Current usage stats for monitoring/logging
+     */
+    getUsageStats(): RateLimitStats;
+    /**
+     * Reset all tracking state.
+     * Useful for testing or when switching API keys/tiers.
+     */
+    reset(): void;
+    /**
+     * Update configuration dynamically.
+     * Useful when API tier changes or for testing.
+     *
+     * @param config - New configuration to apply
+     */
+    updateConfig(config: RateLimitConfig): void;
+    /**
+     * Reserve a request slot before making an LLM call.
+     *
+     * This is critical for concurrent subagents sharing a rate limiter.
+     * Without reservation, multiple subagents checking getRequiredDelayMs()
+     * simultaneously would all see zero usage and proceed, causing rate limit errors.
+     *
+     * Call this AFTER waiting for getRequiredDelayMs() but BEFORE making the LLM call.
+     * The reservation ensures subsequent concurrent checks see the pending request.
+     *
+     * @example
+     * ```typescript
+     * // Proactive rate limiting with reservation
+     * const delay = tracker.getRequiredDelayMs();
+     * if (delay > 0) await sleep(delay);
+     *
+     * tracker.reserveRequest(); // Claim slot BEFORE making call
+     * try {
+     *   const result = await llm.call();
+     *   tracker.recordUsage(result.inputTokens, result.outputTokens);
+     * } catch (error) {
+     *   // Request already reserved; recordUsage updates token count
+     *   throw error;
+     * }
+     * ```
+     */
+    reserveRequest(): void;
+    /**
+     * Calculate delay needed based on RPM limit.
+     */
+    private calculateRpmDelay;
+    /**
+     * Calculate delay needed based on TPM limit.
+     */
+    private calculateTpmDelay;
+    /**
+     * Remove entries older than 1 minute from the sliding window.
+     */
+    private pruneOldEntries;
+    /**
+     * Check if the day has changed (UTC) and reset daily counters.
+     */
+    private checkDailyReset;
+    /**
+     * Get current date in YYYY-MM-DD format (UTC).
+     */
+    private getCurrentDateUTC;
+    /**
+     * Calculate milliseconds until midnight UTC.
+     */
+    private getTimeUntilMidnightUTC;
+}
+
 /**
  * Model Catalog Types
  *
@@ -1457,255 +1699,8 @@ interface ResolvedCompactionConfig {
 }
 
 /**
- * Proactive rate limiting for LLM API calls.
- *
- * Tracks request and token usage in sliding windows to prevent rate limit errors
- * before they occur. Works in conjunction with reactive backoff (retry.ts) for
- * comprehensive rate limit handling.
- */
-/**
- * Configuration for proactive rate limiting.
- *
- * Set these values based on your API tier to prevent rate limit errors.
- * When limits are approached, requests will be automatically delayed.
- *
- * @example
- * ```typescript
- * // Gemini free tier limits
- * const agent = LLMist.createAgent()
- *   .withRateLimits({
- *     requestsPerMinute: 15,
- *     tokensPerMinute: 1_000_000,
- *     safetyMargin: 0.8,
- *   });
- *
- * // OpenAI Tier 1 limits
- * const agent = LLMist.createAgent()
- *   .withRateLimits({
- *     requestsPerMinute: 500,
- *     tokensPerMinute: 200_000,
- *   });
- * ```
- */
-interface RateLimitConfig {
-    /**
-     * Maximum requests per minute.
-     * Set based on your API tier. If not set, RPM limiting is disabled.
-     */
-    requestsPerMinute?: number;
-    /**
-     * Maximum tokens per minute (input + output combined).
-     * Set based on your API tier. If not set, TPM limiting is disabled.
-     */
-    tokensPerMinute?: number;
-    /**
-     * Maximum tokens per day (optional).
-     * Useful for Gemini free tier which has daily limits.
-     * If not set, daily limiting is disabled.
-     */
-    tokensPerDay?: number;
-    /**
-     * Safety margin - start throttling at this percentage of limit.
-     * A value of 0.9 means throttling starts at 90% of the limit.
-     * Lower values provide more safety but may reduce throughput.
-     * @default 0.9
-     */
-    safetyMargin?: number;
-    /**
-     * Whether proactive rate limiting is enabled.
-     * @default true (when any limit is configured)
-     */
-    enabled?: boolean;
-}
-/**
- * Resolved rate limit configuration with all defaults applied.
- */
-interface ResolvedRateLimitConfig {
-    requestsPerMinute?: number;
-    tokensPerMinute?: number;
-    tokensPerDay?: number;
-    safetyMargin: number;
-    enabled: boolean;
-}
-/**
- * Default rate limit configuration values.
- */
-declare const DEFAULT_RATE_LIMIT_CONFIG: Pick<ResolvedRateLimitConfig, "safetyMargin" | "enabled">;
-/**
- * Resolves a partial rate limit configuration by applying defaults.
- *
- * @param config - Partial configuration (optional)
- * @returns Fully resolved configuration
- */
-declare function resolveRateLimitConfig(config?: RateLimitConfig): ResolvedRateLimitConfig;
-/**
- * Information about a triggered rate limit.
- */
-interface TriggeredLimitInfo {
-    /** Current usage value */
-    current: number;
-    /** Configured limit value */
-    limit: number;
-    /** Effective limit after safety margin (limit × safetyMargin) */
-    effectiveLimit: number;
-}
-/**
- * Usage statistics from the rate limit tracker.
- */
-interface RateLimitStats {
-    /** Current requests per minute */
-    rpm: number;
-    /** Current tokens per minute */
-    tpm: number;
-    /** Tokens used today (UTC) */
-    dailyTokens: number;
-    /** Whether any limit is currently being approached */
-    isApproachingLimit: boolean;
-    /** Delay required before next request (0 if none) */
-    requiredDelayMs: number;
-    /** Which limit(s) triggered throttling, if any (present when requiredDelayMs > 0) */
-    triggeredBy?: {
-        rpm?: TriggeredLimitInfo;
-        tpm?: TriggeredLimitInfo;
-        daily?: TriggeredLimitInfo;
-    };
-}
-/**
- * Tracks API usage and calculates required delays for proactive rate limiting.
- *
- * Uses sliding windows to track requests and token usage, automatically
- * calculating delays needed to stay within configured limits.
- *
- * @example
- * ```typescript
- * const tracker = new RateLimitTracker({
- *   requestsPerMinute: 60,
- *   tokensPerMinute: 100000,
- * });
- *
- * // Before each request
- * const delay = tracker.getRequiredDelayMs();
- * if (delay > 0) {
- *   await sleep(delay);
- * }
- *
- * // After each request
- * tracker.recordUsage(inputTokens, outputTokens);
- * ```
- */
-declare class RateLimitTracker {
-    private config;
-    /** Timestamps of requests in the current minute window */
-    private requestTimestamps;
-    /** Token usage entries in the current minute window */
-    private tokenUsage;
-    /** Daily token count */
-    private dailyTokens;
-    /** Date string (YYYY-MM-DD UTC) for daily reset tracking */
-    private dailyResetDate;
-    /** Count of pending reservations (for backward compatibility) */
-    private pendingReservations;
-    constructor(config?: RateLimitConfig);
-    /**
-     * Record a completed request with its token usage.
-     *
-     * If reserveRequest() was called before the LLM call (recommended for concurrent
-     * scenarios), the request timestamp was already recorded. Otherwise, this method
-     * will add it for backward compatibility.
-     *
-     * @param inputTokens - Number of input tokens used
-     * @param outputTokens - Number of output tokens generated
-     */
-    recordUsage(inputTokens: number, outputTokens: number): void;
-    /**
-     * Calculate the delay needed before the next request.
-     *
-     * Returns 0 if no delay is needed, otherwise returns the number of
-     * milliseconds to wait to stay within rate limits.
-     *
-     * @returns Delay in milliseconds (0 if none needed)
-     */
-    getRequiredDelayMs(): number;
-    /**
-     * Check if we're approaching any configured limits.
-     *
-     * @returns true if any limit is at or above the safety margin threshold
-     */
-    isApproachingLimit(): boolean;
-    /**
-     * Get current usage statistics.
-     *
-     * @returns Current usage stats for monitoring/logging
-     */
-    getUsageStats(): RateLimitStats;
-    /**
-     * Reset all tracking state.
-     * Useful for testing or when switching API keys/tiers.
-     */
-    reset(): void;
-    /**
-     * Update configuration dynamically.
-     * Useful when API tier changes or for testing.
-     *
-     * @param config - New configuration to apply
-     */
-    updateConfig(config: RateLimitConfig): void;
-    /**
-     * Reserve a request slot before making an LLM call.
-     *
-     * This is critical for concurrent subagents sharing a rate limiter.
-     * Without reservation, multiple subagents checking getRequiredDelayMs()
-     * simultaneously would all see zero usage and proceed, causing rate limit errors.
-     *
-     * Call this AFTER waiting for getRequiredDelayMs() but BEFORE making the LLM call.
-     * The reservation ensures subsequent concurrent checks see the pending request.
-     *
-     * @example
-     * ```typescript
-     * // Proactive rate limiting with reservation
-     * const delay = tracker.getRequiredDelayMs();
-     * if (delay > 0) await sleep(delay);
-     *
-     * tracker.reserveRequest(); // Claim slot BEFORE making call
-     * try {
-     *   const result = await llm.call();
-     *   tracker.recordUsage(result.inputTokens, result.outputTokens);
-     * } catch (error) {
-     *   // Request already reserved; recordUsage updates token count
-     *   throw error;
-     * }
-     * ```
-     */
-    reserveRequest(): void;
-    /**
-     * Calculate delay needed based on RPM limit.
-     */
-    private calculateRpmDelay;
-    /**
-     * Calculate delay needed based on TPM limit.
-     */
-    private calculateTpmDelay;
-    /**
-     * Remove entries older than 1 minute from the sliding window.
-     */
-    private pruneOldEntries;
-    /**
-     * Check if the day has changed (UTC) and reset daily counters.
-     */
-    private checkDailyReset;
-    /**
-     * Get current date in YYYY-MM-DD format (UTC).
-     */
-    private getCurrentDateUTC;
-    /**
-     * Calculate milliseconds until midnight UTC.
-     */
-    private getTimeUntilMidnightUTC;
-}
-
-/**
- * Metadata present when an event originates from a subagent.
- * Undefined for top-level agent events.
+ * Metadata present when an event originates from a subagent.
+ * Undefined for top-level agent events.
  *
  * When using subagent gadgets (like BrowseWeb), hook observers receive events
  * from both the main agent AND subagents. Check this context to distinguish.
@@ -1823,13 +1818,6 @@ interface ObserveGadgetCompleteContext {
     gadgetName: string;
     invocationId: string;
     parameters: Readonly<Record<string, unknown>>;
-    /**
-     * Original result before interceptors.
-     * @deprecated No longer populated. Use `finalResult` instead.
-     * With the unified event architecture, observers receive the final (post-interceptor)
-     * result from the ExecutionTree.
-     */
-    originalResult?: string;
     /** Final result after interceptors (the value stored in ExecutionTree) */
     finalResult?: string;
     error?: string;
@@ -2058,12 +2046,13 @@ interface Interceptors {
      */
     interceptGadgetParameters?: (parameters: Readonly<Record<string, unknown>>, context: GadgetParameterInterceptorContext) => Record<string, unknown>;
     /**
-     * Intercept and transform gadget results after execution.
+     * Intercept and transform gadget results and error messages after execution.
      * This affects what gets sent back to the LLM and stored in history.
+     * Called for both successful results (result.result) and errors (result.error).
      *
-     * @param result - The gadget result text
+     * @param result - The gadget result or error text
      * @param context - Context information including parameters and execution time
-     * @returns Transformed result text (cannot be suppressed)
+     * @returns Transformed text (cannot be suppressed)
      */
     interceptGadgetResult?: (result: string, context: GadgetResultInterceptorContext) => string;
 }
@@ -2941,377 +2930,168 @@ declare function parseRetryAfterHeader(value: string): number | null;
 declare function extractRetryAfterMs(error: Error): number | null;
 
 /**
- * Example of gadget usage to help LLMs understand proper invocation.
- *
- * Examples are rendered alongside the schema in `getInstruction()` to provide
- * concrete usage patterns for the LLM.
+ * Subagent configuration types.
  *
- * @template TParams - Inferred parameter type from Zod schema (defaults to Record<string, unknown>)
+ * Simple config shapes passed to gadgets for subagent configuration.
+ * No external dependencies — self-contained data shapes.
  *
- * @example
- * ```typescript
- * const calculator = createGadget({
- *   schema: z.object({ a: z.number(), b: z.number() }),
- *   examples: [
- *     { params: { a: 5, b: 3 }, output: "8", comment: "Addition example" }
- *   ],
- *   // ...
- * });
- * ```
+ * @module
  */
-interface GadgetExample<TParams = Record<string, unknown>> {
-    /** Example parameter values (typed to match schema) */
-    params: TParams;
-    /** Optional expected output/result string */
-    output?: string;
-    /** Optional description explaining what this example demonstrates */
-    comment?: string;
-}
 /**
- * Supported media types for gadget output.
- * Extensible via union - add new types as needed.
+ * Parent agent configuration passed to gadgets.
+ * Contains settings that subagents can inherit.
  */
-type MediaKind = "image" | "audio" | "video" | "file";
+interface AgentContextConfig {
+    /** Model identifier used by the parent agent */
+    model: string;
+    /** Temperature setting used by the parent agent */
+    temperature?: number;
+}
 /**
- * Type-specific metadata for media outputs.
- * Extensible via index signature for future media types.
+ * Configuration for a single subagent.
+ * Can be defined globally in `[subagents.Name]` or per-profile in `[profile.subagents.Name]`.
+ *
+ * @example
+ * ```toml
+ * [subagents.BrowseWeb]
+ * model = "inherit"      # Use parent agent's model
+ * maxIterations = 20
+ * headless = true
+ * ```
  */
-interface MediaMetadata {
-    /** Width in pixels (images, video) */
-    width?: number;
-    /** Height in pixels (images, video) */
-    height?: number;
-    /** Duration in milliseconds (audio, video) */
-    durationMs?: number;
-    /** Allow additional metadata for future extensions */
+interface SubagentConfig {
+    /**
+     * Model to use for this subagent.
+     * - "inherit": Use parent agent's model (default behavior)
+     * - Any model ID: Use specific model (e.g., "sonnet", "haiku", "gpt-4o")
+     */
+    model?: string;
+    /** Maximum iterations for the subagent loop */
+    maxIterations?: number;
+    /** Budget limit in USD for the subagent */
+    budget?: number;
+    /**
+     * Timeout for the subagent gadget execution in milliseconds.
+     * Overrides the gadget's hardcoded timeoutMs when set.
+     * Set to 0 to disable timeout for this gadget.
+     */
+    timeoutMs?: number;
+    /**
+     * Maximum number of concurrent executions allowed for this gadget.
+     * When the limit is reached, additional calls are queued and processed
+     * as earlier executions complete (FIFO order).
+     * Set to 0 or omit to allow unlimited concurrent executions (default).
+     */
+    maxConcurrent?: number;
+    /** Additional subagent-specific options */
     [key: string]: unknown;
 }
 /**
- * Media output from a gadget execution.
- * Supports images, audio, video, and arbitrary files.
+ * Map of subagent names to their configurations.
+ */
+type SubagentConfigMap = Record<string, SubagentConfig>;
+/**
+ * Gadget execution mode controlling how multiple gadgets are executed.
+ *
+ * - `'parallel'` (default): Gadgets without dependencies execute concurrently (fire-and-forget).
+ *   This maximizes throughput but gadgets may complete in any order.
+ *
+ * - `'sequential'`: Gadgets execute one at a time, each awaiting completion before the next starts.
+ *   Useful for:
+ *   - Gadgets with implicit ordering dependencies (e.g., file operations)
+ *   - Debugging and tracing execution flow
+ *   - Resource-constrained environments
+ *   - Ensuring deterministic execution order
+ *
+ * Note: Explicit `dependsOn` relationships are always respected regardless of mode.
+ * Sequential mode effectively enforces a global `maxConcurrent: 1` for all gadgets.
  *
  * @example
  * ```typescript
- * // Image output
- * const imageOutput: GadgetMediaOutput = {
- *   kind: "image",
- *   data: base64EncodedPng,
- *   mimeType: "image/png",
- *   description: "Screenshot of webpage",
- *   metadata: { width: 1920, height: 1080 }
- * };
+ * const agent = LLMist.createAgent()
+ *   .withModel("sonnet")
+ *   .withGadgets(FileReader, FileWriter)
+ *   .withGadgetExecutionMode('sequential')  // Execute one at a time
+ *   .ask("Process files in order");
  * ```
  */
-interface GadgetMediaOutput {
-    /** Type of media (discriminator for type-specific handling) */
-    kind: MediaKind;
-    /** Base64-encoded media data */
-    data: string;
-    /** Full MIME type (e.g., "image/png", "audio/mp3", "video/mp4") */
-    mimeType: string;
-    /** Human-readable description of the media */
-    description?: string;
-    /** Type-specific metadata */
-    metadata?: MediaMetadata;
-    /** Optional filename to use when saving (if not provided, auto-generated) */
-    fileName?: string;
-}
+type GadgetExecutionMode = "parallel" | "sequential";
+
 /**
- * Stored media item with metadata and file path.
- *
- * Created by MediaStore when a gadget returns media outputs.
- * Contains the abstract ID, file path, and metadata for display.
+ * Image generation namespace with automatic cost reporting.
  */
-interface StoredMedia {
-    /** Unique ID for this media item (e.g., "media_a1b2c3") */
-    id: string;
-    /** Type of media */
-    kind: MediaKind;
-    /** Actual file path on disk (internal use) */
-    path: string;
-    /** MIME type */
-    mimeType: string;
-    /** File size in bytes */
-    sizeBytes: number;
-    /** Human-readable description */
-    description?: string;
-    /** Type-specific metadata */
-    metadata?: MediaMetadata;
-    /** Name of the gadget that created this media */
-    gadgetName: string;
-    /** When the media was stored */
-    createdAt: Date;
+interface CostReportingImageNamespace {
+    /**
+     * Generate images from a text prompt.
+     * Costs are automatically reported to the execution context.
+     */
+    generate(options: ImageGenerationOptions): Promise<ImageGenerationResult>;
 }
-interface GadgetExecutionResult {
-    gadgetName: string;
-    invocationId: string;
-    parameters: Record<string, unknown>;
-    result?: string;
-    error?: string;
-    executionTimeMs: number;
-    breaksLoop?: boolean;
-    /** Cost of gadget execution in USD. Defaults to 0 if not provided by gadget. */
-    cost?: number;
-    /** Media outputs from the gadget (images, audio, video, files) */
-    media?: GadgetMediaOutput[];
-    /** Abstract IDs for media outputs (e.g., ["media_a1b2c3"]) */
-    mediaIds?: string[];
-    /** Stored media with paths (for CLI display) */
-    storedMedia?: StoredMedia[];
+/**
+ * Speech generation namespace with automatic cost reporting.
+ */
+interface CostReportingSpeechNamespace {
+    /**
+     * Generate speech audio from text.
+     * Costs are automatically reported to the execution context.
+     */
+    generate(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
 }
 /**
- * Result returned by gadget execute() method.
- * Can be a simple string or an object with result and optional cost.
+ * LLMist client interface for use within gadgets.
+ *
+ * Provides LLM completion methods that automatically report costs
+ * via the execution context. All LLM calls made through this client
+ * will have their costs tracked and included in the gadget's total cost.
  *
  * @example
  * ```typescript
- * // Simple string return (free gadget)
- * execute: () => "result"
- *
- * // Object return with cost
- * execute: () => ({ result: "data", cost: 0.001 })
+ * execute: async ({ text }, ctx) => {
+ *   // LLM costs are automatically reported
+ *   const summary = await ctx.llmist.complete('Summarize: ' + text, {
+ *     model: 'haiku',
+ *   });
+ *   return summary;
+ * }
  * ```
  */
-interface GadgetExecuteResult {
-    /** The execution result as a string */
-    result: string;
-    /** Optional cost in USD (e.g., 0.001 for $0.001) */
-    cost?: number;
+interface CostReportingLLMist {
+    /**
+     * Quick completion - returns final text response.
+     * Costs are automatically reported to the execution context.
+     */
+    complete(prompt: string, options?: TextGenerationOptions): Promise<string>;
+    /**
+     * Quick streaming - returns async generator of text chunks.
+     * Costs are automatically reported when the stream completes.
+     */
+    streamText(prompt: string, options?: TextGenerationOptions): AsyncGenerator<string>;
+    /**
+     * Low-level stream access for full control.
+     * Costs are automatically reported based on usage metadata in chunks.
+     */
+    stream(options: LLMGenerationOptions): LLMStream;
+    /**
+     * Access to model registry for cost estimation.
+     */
+    readonly modelRegistry: ModelRegistry;
+    /**
+     * Image generation with automatic cost reporting.
+     * Costs are reported based on model and generation parameters.
+     */
+    readonly image: CostReportingImageNamespace;
+    /**
+     * Speech generation with automatic cost reporting.
+     * Costs are reported based on input length and model pricing.
+     */
+    readonly speech: CostReportingSpeechNamespace;
 }
 /**
- * Extended result type with media support.
- * Use this when gadget returns images, audio, video, or files.
- *
- * @example
- * ```typescript
- * // Return with image
- * execute: () => ({
- *   result: "Screenshot captured",
- *   media: [{
- *     kind: "image",
- *     data: base64EncodedPng,
- *     mimeType: "image/png",
- *     description: "Screenshot"
- *   }],
- *   cost: 0.001
- * })
- * ```
- */
-interface GadgetExecuteResultWithMedia {
-    /** The execution result as a string */
-    result: string;
-    /** Media outputs (images, audio, video, files) */
-    media?: GadgetMediaOutput[];
-    /** Optional cost in USD (e.g., 0.001 for $0.001) */
-    cost?: number;
-}
-/**
- * Union type for backwards-compatible execute() return type.
- * Gadgets can return:
- * - string (legacy, cost = 0)
- * - GadgetExecuteResult (result + optional cost)
- * - GadgetExecuteResultWithMedia (result + optional media + optional cost)
- */
-type GadgetExecuteReturn = string | GadgetExecuteResult | GadgetExecuteResultWithMedia;
-interface ParsedGadgetCall {
-    gadgetName: string;
-    invocationId: string;
-    parametersRaw: string;
-    parameters?: Record<string, unknown>;
-    parseError?: string;
-    /** List of invocation IDs this gadget depends on. Empty array if no dependencies. */
-    dependencies: string[];
-}
-
-/** Event emitted when a gadget is skipped due to a failed dependency */
-interface GadgetSkippedEvent {
-    type: "gadget_skipped";
-    gadgetName: string;
-    invocationId: string;
-    parameters: Record<string, unknown>;
-    /** The invocation ID of the dependency that failed */
-    failedDependency: string;
-    /** The error message from the failed dependency */
-    failedDependencyError: string;
-}
-/**
- * Event emitted when stream processing completes, containing metadata.
- * This allows the async generator to "return" metadata while still yielding events.
- */
-interface StreamCompletionEvent {
-    type: "stream_complete";
-    /** The reason the LLM stopped generating (e.g., "stop", "tool_use") */
-    finishReason: string | null;
-    /** Token usage statistics from the LLM call */
-    usage?: TokenUsage;
-    /** Raw response text from the LLM */
-    rawResponse: string;
-    /** Final message after all interceptors applied */
-    finalMessage: string;
-    /** Whether any gadgets were executed during this iteration */
-    didExecuteGadgets: boolean;
-    /** Whether to break the agent loop (e.g., TaskComplete was called) */
-    shouldBreakLoop: boolean;
-    /** Accumulated thinking/reasoning content from reasoning models */
-    thinkingContent?: string;
-}
-type StreamEvent = {
-    type: "text";
-    content: string;
-} | {
-    type: "thinking";
-    content: string;
-    thinkingType: "thinking" | "redacted";
-} | {
-    type: "gadget_call";
-    call: ParsedGadgetCall;
-} | {
-    type: "gadget_result";
-    result: GadgetExecutionResult;
-} | GadgetSkippedEvent | {
-    type: "human_input_required";
-    question: string;
-    gadgetName: string;
-    invocationId: string;
-} | {
-    type: "compaction";
-    event: CompactionEvent;
-} | {
-    type: "llm_response_end";
-    finishReason: string | null;
-    usage?: TokenUsage;
-} | StreamCompletionEvent;
-
-type TextOnlyHandler = TextOnlyStrategy | TextOnlyGadgetConfig | TextOnlyCustomHandler;
-/**
- * Simple strategies for common cases
- * - 'terminate': End the loop (default behavior)
- * - 'acknowledge': Continue to next iteration
- * - 'wait_for_input': Request human input
- */
-type TextOnlyStrategy = "terminate" | "acknowledge" | "wait_for_input";
-/**
- * Configuration for triggering a gadget when receiving text-only response
- */
-interface TextOnlyGadgetConfig {
-    type: "gadget";
-    name: string;
-    /**
-     * Optional function to map text to gadget parameters.
-     * If not provided, text will be passed as { text: string }
-     */
-    parameterMapping?: (text: string) => Record<string, unknown>;
-}
-/**
- * Custom handler for complex text-only response scenarios
- */
-interface TextOnlyCustomHandler {
-    type: "custom";
-    handler: (context: TextOnlyContext) => Promise<TextOnlyAction> | TextOnlyAction;
-}
-/**
- * Context provided to custom text-only handlers
- */
-interface TextOnlyContext {
-    /** The complete text response from the LLM */
-    text: string;
-    /** Current iteration number */
-    iteration: number;
-    /** Full conversation history */
-    conversation: LLMMessage[];
-    /** Logger instance */
-    logger: Logger<ILogObj>;
-}
-/**
- * Actions that can be returned by text-only handlers
- */
-type TextOnlyAction = {
-    action: "continue";
-} | {
-    action: "terminate";
-} | {
-    action: "wait_for_input";
-    question?: string;
-} | {
-    action: "trigger_gadget";
-    name: string;
-    parameters: Record<string, unknown>;
-};
-/**
- * LLMist client interface for use within gadgets.
- *
- * Provides LLM completion methods that automatically report costs
- * via the execution context. All LLM calls made through this client
- * will have their costs tracked and included in the gadget's total cost.
- *
- * @example
- * ```typescript
- * execute: async ({ text }, ctx) => {
- *   // LLM costs are automatically reported
- *   const summary = await ctx.llmist.complete('Summarize: ' + text, {
- *     model: 'haiku',
- *   });
- *   return summary;
- * }
- * ```
- */
-/**
- * Image generation namespace with automatic cost reporting.
- */
-interface CostReportingImageNamespace {
-    /**
-     * Generate images from a text prompt.
-     * Costs are automatically reported to the execution context.
-     */
-    generate(options: ImageGenerationOptions): Promise<ImageGenerationResult>;
-}
-/**
- * Speech generation namespace with automatic cost reporting.
- */
-interface CostReportingSpeechNamespace {
-    /**
-     * Generate speech audio from text.
-     * Costs are automatically reported to the execution context.
-     */
-    generate(options: SpeechGenerationOptions): Promise<SpeechGenerationResult>;
-}
-interface CostReportingLLMist {
-    /**
-     * Quick completion - returns final text response.
-     * Costs are automatically reported to the execution context.
-     */
-    complete(prompt: string, options?: TextGenerationOptions): Promise<string>;
-    /**
-     * Quick streaming - returns async generator of text chunks.
-     * Costs are automatically reported when the stream completes.
-     */
-    streamText(prompt: string, options?: TextGenerationOptions): AsyncGenerator<string>;
-    /**
-     * Low-level stream access for full control.
-     * Costs are automatically reported based on usage metadata in chunks.
-     */
-    stream(options: LLMGenerationOptions): LLMStream;
-    /**
-     * Access to model registry for cost estimation.
-     */
-    readonly modelRegistry: ModelRegistry;
-    /**
-     * Image generation with automatic cost reporting.
-     * Costs are reported based on model and generation parameters.
-     */
-    readonly image: CostReportingImageNamespace;
-    /**
-     * Speech generation with automatic cost reporting.
-     * Costs are reported based on input length and model pricing.
-     */
-    readonly speech: CostReportingSpeechNamespace;
-}
-/**
- * Execution context provided to gadgets during execution.
- *
- * Contains utilities for cost reporting and LLM access.
- * This parameter is optional for backwards compatibility -
- * existing gadgets without the context parameter continue to work.
+ * Execution context provided to gadgets during execution.
+ *
+ * Contains utilities for cost reporting and LLM access.
+ * This parameter is optional for backwards compatibility -
+ * existing gadgets without the context parameter continue to work.
  *
  * @example
  * ```typescript
@@ -3758,1885 +3538,1308 @@ interface HostExports {
     /** Zod schema builder */
     z: typeof zod.z;
 }
+
 /**
- * Parent agent configuration passed to gadgets.
- * Contains settings that subagents can inherit.
+ * Media output types for gadgets returning images, audio, video, or files.
+ *
+ * This module contains pure data shapes with zero cross-module dependencies.
+ * Imported by execution result types, stream event types, and execution context types.
+ *
+ * @module
  */
-interface AgentContextConfig {
-    /** Model identifier used by the parent agent */
-    model: string;
-    /** Temperature setting used by the parent agent */
-    temperature?: number;
+/**
+ * Supported media types for gadget output.
+ * Extensible via union - add new types as needed.
+ */
+type MediaKind = "image" | "audio" | "video" | "file";
+/**
+ * Type-specific metadata for media outputs.
+ * Extensible via index signature for future media types.
+ */
+interface MediaMetadata {
+    /** Width in pixels (images, video) */
+    width?: number;
+    /** Height in pixels (images, video) */
+    height?: number;
+    /** Duration in milliseconds (audio, video) */
+    durationMs?: number;
+    /** Allow additional metadata for future extensions */
+    [key: string]: unknown;
 }
 /**
- * Configuration for a single subagent.
- * Can be defined globally in `[subagents.Name]` or per-profile in `[profile.subagents.Name]`.
+ * Media output from a gadget execution.
+ * Supports images, audio, video, and arbitrary files.
  *
  * @example
- * ```toml
- * [subagents.BrowseWeb]
- * model = "inherit"      # Use parent agent's model
- * maxIterations = 20
- * headless = true
+ * ```typescript
+ * // Image output
+ * const imageOutput: GadgetMediaOutput = {
+ *   kind: "image",
+ *   data: base64EncodedPng,
+ *   mimeType: "image/png",
+ *   description: "Screenshot of webpage",
+ *   metadata: { width: 1920, height: 1080 }
+ * };
  * ```
  */
-interface SubagentConfig {
-    /**
-     * Model to use for this subagent.
-     * - "inherit": Use parent agent's model (default behavior)
-     * - Any model ID: Use specific model (e.g., "sonnet", "haiku", "gpt-4o")
-     */
-    model?: string;
-    /** Maximum iterations for the subagent loop */
-    maxIterations?: number;
-    /** Budget limit in USD for the subagent */
-    budget?: number;
-    /**
-     * Timeout for the subagent gadget execution in milliseconds.
-     * Overrides the gadget's hardcoded timeoutMs when set.
-     * Set to 0 to disable timeout for this gadget.
-     */
-    timeoutMs?: number;
-    /**
-     * Maximum number of concurrent executions allowed for this gadget.
-     * When the limit is reached, additional calls are queued and processed
-     * as earlier executions complete (FIFO order).
-     * Set to 0 or omit to allow unlimited concurrent executions (default).
-     */
-    maxConcurrent?: number;
-    /** Additional subagent-specific options */
-    [key: string]: unknown;
-}
-/**
- * Map of subagent names to their configurations.
- */
-type SubagentConfigMap = Record<string, SubagentConfig>;
-/**
- * Gadget execution mode controlling how multiple gadgets are executed.
- *
- * - `'parallel'` (default): Gadgets without dependencies execute concurrently (fire-and-forget).
- *   This maximizes throughput but gadgets may complete in any order.
- *
- * - `'sequential'`: Gadgets execute one at a time, each awaiting completion before the next starts.
- *   Useful for:
- *   - Gadgets with implicit ordering dependencies (e.g., file operations)
- *   - Debugging and tracing execution flow
- *   - Resource-constrained environments
- *   - Ensuring deterministic execution order
- *
- * Note: Explicit `dependsOn` relationships are always respected regardless of mode.
- * Sequential mode effectively enforces a global `maxConcurrent: 1` for all gadgets.
- *
- * @example
- * ```typescript
- * const agent = LLMist.createAgent()
- *   .withModel("sonnet")
- *   .withGadgets(FileReader, FileWriter)
- *   .withGadgetExecutionMode('sequential')  // Execute one at a time
- *   .ask("Process files in order");
- * ```
- */
-type GadgetExecutionMode = "parallel" | "sequential";
-
-/**
- * Abstract base class for gadgets. Most users should use the `Gadget()` factory
- * or `createGadget()` function instead, as they provide better type safety
- * and simpler APIs.
- *
- * Extend this class directly only when you need advanced control over gadget behavior.
- */
-declare abstract class AbstractGadget {
-    /**
-     * The name of the gadget. Used for identification when LLM calls it.
-     * If not provided, defaults to the class name.
-     */
-    name?: string;
-    /**
-     * Human-readable description of what the gadget does.
-     */
-    abstract description: string;
-    /**
-     * Optional Zod schema describing the expected input payload. When provided,
-     * it will be validated before execution and transformed into a JSON Schema
-     * representation that is surfaced to the LLM as part of the instructions.
-     */
-    parameterSchema?: ZodTypeAny;
-    /**
-     * Optional timeout in milliseconds for gadget execution.
-     * If execution exceeds this timeout, a TimeoutException will be thrown.
-     * If not set, the global defaultGadgetTimeoutMs from runtime options will be used.
-     * Set to 0 or undefined to disable timeout for this gadget.
-     */
-    timeoutMs?: number;
-    /**
-     * Optional usage examples to help LLMs understand proper invocation.
-     * Examples are rendered in getInstruction() alongside the schema.
-     *
-     * Note: Uses broader `unknown` type to allow typed examples from subclasses
-     * while maintaining runtime compatibility.
-     */
-    examples?: GadgetExample<unknown>[];
-    /**
-     * Maximum number of concurrent executions allowed for this gadget.
-     * Use this to prevent race conditions in gadgets that modify shared state.
-     *
-     * - `1` = Sequential execution (only one instance runs at a time)
-     * - `0` or `undefined` = Unlimited concurrency (default)
-     * - `N > 1` = At most N concurrent executions
-     *
-     * This property sets a safety floor: external configuration (SubagentConfig)
-     * can only make concurrency MORE restrictive, never less. For example, if
-     * a gadget declares `maxConcurrent: 1`, external config cannot override it
-     * to allow parallel execution.
-     *
-     * @example
-     * ```typescript
-     * // File writer that must run sequentially to avoid race conditions
-     * class WriteFile extends Gadget({
-     *   description: 'Writes content to a file',
-     *   schema: z.object({ path: z.string(), content: z.string() }),
-     *   maxConcurrent: 1, // Sequential - prevents race conditions
-     * }) {
-     *   execute(params: this['params']) { ... }
-     * }
-     * ```
-     */
-    maxConcurrent?: number;
-    /**
-     * If true, this gadget must execute alone — no other gadgets in the same
-     * LLM response can run in parallel. When an exclusive gadget arrives and
-     * other gadgets are already in-flight, it is deferred until they complete.
-     *
-     * Use for gadgets that terminate the agent loop (e.g., Finish), where
-     * sibling tool results must be visible to the LLM before the loop ends.
-     *
-     * This is a safety floor: external config cannot weaken it.
-     */
-    exclusive?: boolean;
-    /**
-     * Execute the gadget with the given parameters.
-     * Can be synchronous or asynchronous.
-     *
-     * @param params - Parameters passed from the LLM
-     * @param ctx - Optional execution context for cost reporting and LLM access
-     * @returns Result as a string, or an object with result and optional cost
-     *
-     * @example
-     * ```typescript
-     * // Simple string return (free gadget)
-     * execute(params) {
-     *   return "result";
-     * }
-     *
-     * // Object return with cost tracking
-     * execute(params) {
-     *   return { result: "data", cost: 0.001 };
-     * }
-     *
-     * // Using context for callback-based cost reporting
-     * execute(params, ctx) {
-     *   ctx.reportCost(0.001);
-     *   return "result";
-     * }
-     *
-     * // Using wrapped LLMist for automatic cost tracking
-     * async execute(params, ctx) {
-     *   const summary = await ctx.llmist.complete('Summarize: ' + params.text);
-     *   return summary;
-     * }
-     * ```
-     */
-    abstract execute(params: Record<string, unknown>, ctx?: ExecutionContext): GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
-    /**
-     * Throws an AbortException if the execution has been aborted.
-     *
-     * Call this at key checkpoints in long-running gadgets to allow early exit
-     * when the gadget has been cancelled (e.g., due to timeout). This enables
-     * resource cleanup and prevents unnecessary work after cancellation.
-     *
-     * @param ctx - The execution context containing the abort signal
-     * @throws AbortException if ctx.signal.aborted is true
-     *
-     * @example
-     * ```typescript
-     * class DataProcessor extends Gadget({
-     *   description: 'Processes data in multiple steps',
-     *   schema: z.object({ items: z.array(z.string()) }),
-     * }) {
-     *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
-     *     const results: string[] = [];
-     *
-     *     for (const item of params.items) {
-     *       // Check before each expensive operation
-     *       this.throwIfAborted(ctx);
-     *
-     *       results.push(await this.processItem(item));
-     *     }
-     *
-     *     return results.join(', ');
-     *   }
-     * }
-     * ```
-     */
-    throwIfAborted(ctx?: ExecutionContext): void;
-    /**
-     * Register a cleanup function to run when execution is aborted (timeout or cancellation).
-     * The cleanup function is called immediately if the signal is already aborted.
-     * Errors thrown by the cleanup function are silently ignored.
-     *
-     * Use this to clean up resources like browser instances, database connections,
-     * or child processes when the gadget is cancelled due to timeout.
-     *
-     * @param ctx - The execution context containing the abort signal
-     * @param cleanup - Function to run on abort (can be sync or async)
-     *
-     * @example
-     * ```typescript
-     * class BrowserGadget extends Gadget({
-     *   description: 'Fetches web page content',
-     *   schema: z.object({ url: z.string() }),
-     * }) {
-     *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
-     *     const browser = await chromium.launch();
-     *     this.onAbort(ctx, () => browser.close());
-     *
-     *     const page = await browser.newPage();
-     *     this.onAbort(ctx, () => page.close());
-     *
-     *     await page.goto(params.url);
-     *     const content = await page.content();
-     *
-     *     await browser.close();
-     *     return content;
-     *   }
-     * }
-     * ```
-     */
-    onAbort(ctx: ExecutionContext | undefined, cleanup: () => void | Promise<void>): void;
-    /**
-     * Create an AbortController linked to the execution context's signal.
-     * When the parent signal aborts, the returned controller also aborts with the same reason.
-     *
-     * Useful for passing abort signals to child operations like fetch() while still
-     * being able to abort them independently if needed.
-     *
-     * @param ctx - The execution context containing the parent abort signal
-     * @returns A new AbortController linked to the parent signal
-     *
-     * @example
-     * ```typescript
-     * class FetchGadget extends Gadget({
-     *   description: 'Fetches data from URL',
-     *   schema: z.object({ url: z.string() }),
-     * }) {
-     *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
-     *     const controller = this.createLinkedAbortController(ctx);
-     *
-     *     // fetch() will automatically abort when parent times out
-     *     const response = await fetch(params.url, { signal: controller.signal });
-     *     return response.text();
-     *   }
-     * }
-     * ```
-     */
-    createLinkedAbortController(ctx?: ExecutionContext): AbortController;
-    /**
-     * Auto-generated instruction text for the LLM.
-     * Combines name, description, and parameter schema into a formatted instruction.
-     * @deprecated Use getInstruction() instead
-     */
-    get instruction(): string;
-    /**
-     * Generate instruction text for the LLM.
-     * Combines name, description, and parameter schema into a formatted instruction.
-     *
-     * @param optionsOrArgPrefix - Optional custom prefixes for examples, or just argPrefix string for backwards compatibility
-     * @returns Formatted instruction string
-     */
-    getInstruction(optionsOrArgPrefix?: string | {
-        argPrefix?: string;
-        startPrefix?: string;
-        endPrefix?: string;
-    }): string;
-}
-
-/**
- * Context provided to prompt template functions for rendering dynamic content.
- */
-interface PromptContext {
-    /** Custom gadget start prefix */
-    startPrefix: string;
-    /** Custom gadget end prefix */
-    endPrefix: string;
-    /** Custom argument prefix for block format */
-    argPrefix: string;
-    /** Number of gadgets being registered */
-    gadgetCount: number;
-    /** Names of all gadgets */
-    gadgetNames: string[];
-}
-/**
- * Context provided to hint template functions for rendering dynamic hints.
- */
-interface HintContext {
-    /** Current iteration (1-based for readability) */
-    iteration: number;
-    /** Maximum iterations allowed */
-    maxIterations: number;
-    /** Iterations remaining (maxIterations - iteration) */
-    remaining: number;
-    /** Number of gadget calls in the current response */
-    gadgetCallCount?: number;
-}
-/**
- * Template that can be either a static string or a function that renders based on context.
- */
-type PromptTemplate = string | ((context: PromptContext) => string);
-/**
- * Template for hints that can be either a static string or a function that renders based on hint context.
- */
-type HintTemplate = string | ((context: HintContext) => string);
-/**
- * Configuration for customizing all prompts used internally by llmist.
- *
- * Each field can be either a string (static text) or a function that receives
- * context and returns a string (for dynamic content).
- *
- * @example
- * ```typescript
- * const customConfig: PromptTemplateConfig = {
- *   mainInstruction: "USE ONLY THE GADGET MARKERS BELOW:",
- *   criticalUsage: "Important: Follow the exact format shown.",
- *   rules: (ctx) => [
- *     "Always use the markers to invoke gadgets",
- *     "Never use function calling",
- *     `You have ${ctx.gadgetCount} gadgets available`
- *   ]
- * };
- * ```
- */
-interface PromptTemplateConfig {
-    /**
-     * Main instruction block that appears at the start of the gadget system prompt.
-     * Default emphasizes using text markers instead of function calling.
-     */
-    mainInstruction?: PromptTemplate;
-    /**
-     * Critical usage instruction that appears in the usage section.
-     * Default emphasizes the exact format requirement.
-     */
-    criticalUsage?: PromptTemplate;
-    /**
-     * Format description for the block parameter format.
-     * Default uses the configured argPrefix dynamically.
-     */
-    formatDescription?: PromptTemplate;
-    /**
-     * Rules that appear in the rules section.
-     * Can be an array of strings or a function that returns an array.
-     * Default includes rules about not using function calling.
-     */
-    rules?: PromptTemplate | string[] | ((context: PromptContext) => string[]);
-    /**
-     * Custom examples to show in the examples section.
-     * If provided, replaces the default examples entirely.
-     * Should be a function that returns formatted example strings.
-     */
-    customExamples?: (context: PromptContext) => string;
-    /**
-     * Hint shown when LLM uses only one gadget per response.
-     * Encourages parallel gadget usage for efficiency.
-     */
-    parallelGadgetsHint?: HintTemplate;
-    /**
-     * Template for iteration progress hint.
-     * Informs the LLM about remaining iterations to help plan work.
-     *
-     * When using a string template, supports placeholders:
-     * - {iteration}: Current iteration (1-based)
-     * - {maxIterations}: Maximum iterations allowed
-     * - {remaining}: Iterations remaining
-     */
-    iterationProgressHint?: HintTemplate;
-}
-/**
- * Default hint templates used by llmist.
- */
-declare const DEFAULT_HINTS: {
-    readonly parallelGadgetsHint: "Tip: You can call multiple gadgets in a single response for efficiency.";
-    readonly iterationProgressHint: "[Iteration {iteration}/{maxIterations}] Plan your actions accordingly.";
-};
-/**
- * Default prompt templates used by llmist.
- */
-declare const DEFAULT_PROMPTS: Required<Omit<PromptTemplateConfig, "rules" | "customExamples" | "parallelGadgetsHint" | "iterationProgressHint"> & {
-    rules: (context: PromptContext) => string[];
-    customExamples: null;
-}>;
-/**
- * Resolve a prompt template to a string using the given context.
- */
-declare function resolvePromptTemplate(template: PromptTemplate | undefined, defaultValue: PromptTemplate, context: PromptContext): string;
-/**
- * Resolve rules template to an array of strings.
- */
-declare function resolveRulesTemplate(rules: PromptTemplateConfig["rules"] | undefined, context: PromptContext): string[];
-/**
- * Resolve a hint template to a string using the given context.
- * Supports both function templates and string templates with placeholders.
- *
- * @param template - The hint template to resolve
- * @param defaultValue - Default value if template is undefined
- * @param context - Context for rendering the template
- * @returns The resolved hint string
- */
-declare function resolveHintTemplate(template: HintTemplate | undefined, defaultValue: string, context: HintContext): string;
-
-type MessageRole = "system" | "user" | "assistant";
-/**
- * Message content can be a simple string (text only) or an array of content parts (multimodal).
- * Using a string is simpler for text-only messages, while arrays support images and audio.
- */
-type MessageContent = string | ContentPart[];
-interface LLMMessage {
-    role: MessageRole;
-    content: MessageContent;
-    name?: string;
-    metadata?: Record<string, unknown>;
-}
-/**
- * Normalize message content to an array of content parts.
- * Converts string content to a single text part.
- *
- * @param content - Message content (string or ContentPart[])
- * @returns Array of content parts
- */
-declare function normalizeMessageContent(content: MessageContent): ContentPart[];
-/**
- * Extract text from message content.
- * Concatenates all text parts in the content.
- *
- * @param content - Message content (string or ContentPart[])
- * @returns Combined text from all text parts
- */
-declare function extractMessageText(content: MessageContent): string;
-declare class LLMMessageBuilder {
-    private readonly messages;
-    private startPrefix;
-    private endPrefix;
-    private argPrefix;
-    private promptConfig;
-    constructor(promptConfig?: PromptTemplateConfig);
-    /**
-     * Set custom prefixes for gadget markers.
-     * Used to configure history builder to match system prompt markers.
-     */
-    withPrefixes(startPrefix: string, endPrefix: string, argPrefix?: string): this;
-    addSystem(content: string, metadata?: Record<string, unknown>): this;
-    addGadgets(gadgets: AbstractGadget[], options?: {
-        startPrefix?: string;
-        endPrefix?: string;
-        argPrefix?: string;
-    }): this;
-    private buildGadgetsSection;
-    private buildUsageSection;
-    private buildExamplesSection;
-    private buildRulesSection;
-    /**
-     * Add a user message.
-     * Content can be a string (text only) or an array of content parts (multimodal).
-     *
-     * @param content - Message content
-     * @param metadata - Optional metadata
-     *
-     * @example
-     * ```typescript
-     * // Text only
-     * builder.addUser("Hello!");
-     *
-     * // Multimodal
-     * builder.addUser([
-     *   text("What's in this image?"),
-     *   imageFromBuffer(imageData),
-     * ]);
-     * ```
-     */
-    addUser(content: MessageContent, metadata?: Record<string, unknown>): this;
-    addAssistant(content: string, metadata?: Record<string, unknown>): this;
-    /**
-     * Add a user message with an image attachment.
-     *
-     * @param textContent - Text prompt
-     * @param imageData - Image data (Buffer, Uint8Array, or base64 string)
-     * @param mimeType - Optional MIME type (auto-detected if not provided)
-     *
-     * @example
-     * ```typescript
-     * builder.addUserWithImage(
-     *   "What's in this image?",
-     *   await fs.readFile("photo.jpg"),
-     *   "image/jpeg"  // Optional - auto-detected
-     * );
-     * ```
-     */
-    addUserWithImage(textContent: string, imageData: Buffer | Uint8Array | string, mimeType?: ImageMimeType): this;
-    /**
-     * Add a user message with an image URL (OpenAI only).
-     *
-     * @param textContent - Text prompt
-     * @param imageUrl - URL to the image
-     *
-     * @example
-     * ```typescript
-     * builder.addUserWithImageUrl(
-     *   "What's in this image?",
-     *   "https://example.com/image.jpg"
-     * );
-     * ```
-     */
-    addUserWithImageUrl(textContent: string, imageUrl: string): this;
-    /**
-     * Add a user message with an audio attachment (Gemini only).
-     *
-     * @param textContent - Text prompt
-     * @param audioData - Audio data (Buffer, Uint8Array, or base64 string)
-     * @param mimeType - Optional MIME type (auto-detected if not provided)
-     *
-     * @example
-     * ```typescript
-     * builder.addUserWithAudio(
-     *   "Transcribe this audio",
-     *   await fs.readFile("recording.mp3"),
-     *   "audio/mp3"  // Optional - auto-detected
-     * );
-     * ```
-     */
-    addUserWithAudio(textContent: string, audioData: Buffer | Uint8Array | string, mimeType?: AudioMimeType): this;
-    /**
-     * Add a user message with multiple content parts.
-     * Provides full flexibility for complex multimodal messages.
-     *
-     * @param parts - Array of content parts
-     *
-     * @example
-     * ```typescript
-     * builder.addUserMultimodal([
-     *   text("Compare these images:"),
-     *   imageFromBuffer(image1),
-     *   imageFromBuffer(image2),
-     * ]);
-     * ```
-     */
-    addUserMultimodal(parts: ContentPart[]): this;
-    /**
-     * Record a gadget execution result in the message history.
-     * Creates an assistant message with the gadget invocation and a user message with the result.
-     *
-     * The invocationId is shown to the LLM so it can reference previous calls when building dependencies.
-     *
-     * @param gadget - Name of the gadget that was executed
-     * @param parameters - Parameters that were passed to the gadget
-     * @param result - Text result from the gadget execution
-     * @param invocationId - Invocation ID (shown to LLM so it can reference for dependencies)
-     * @param media - Optional media outputs from the gadget
-     * @param mediaIds - Optional IDs for the media outputs
-     * @param storedMedia - Optional stored media info including file paths
-     */
-    addGadgetCallResult(gadget: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[]): this;
-    /**
-     * Format parameters as Block format with JSON Pointer paths.
-     * Uses the configured argPrefix for consistency with system prompt.
-     */
-    private formatBlockParameters;
-    build(): LLMMessage[];
-}
-
-/**
- * Provider-agnostic reasoning effort level.
- *
- * Maps to provider-specific values:
- * - **OpenAI**: "none"|"low"|"medium"|"high"|"xhigh"
- * - **Anthropic**: budget_tokens (1024–32768)
- * - **Gemini 3**: thinkingLevel "minimal"|"low"|"medium"|"high"
- * - **Gemini 2.5**: thinkingBudget (0–24576)
- * - **DeepSeek**: binary (enabled/disabled)
- */
-type ReasoningEffort = "none" | "low" | "medium" | "high" | "maximum";
-/**
- * Configuration for reasoning/thinking mode on supported models.
- *
- * When `enabled` is true, the provider will be instructed to use
- * extended reasoning before generating its response.
- */
-interface ReasoningConfig {
-    /** Whether reasoning is enabled */
-    enabled: boolean;
-    /** Reasoning effort level (default: "medium") */
-    effort?: ReasoningEffort;
-    /** Explicit token budget for thinking (Anthropic/Gemini 2.5, overrides effort) */
-    budgetTokens?: number;
-    /** Whether to surface thinking content in the stream (default: true) */
-    includeThinking?: boolean;
-    /** Enable interleaved thinking for multi-turn tool use (Anthropic only) */
-    interleaved?: boolean;
-}
-/**
- * A chunk of thinking/reasoning content from a reasoning model.
- *
- * Emitted during streaming when a reasoning model produces thinking output.
- * The `type` field distinguishes actual thinking from redacted content
- * (e.g., Anthropic may redact thinking in certain scenarios).
- */
-interface ThinkingChunk {
-    /** The thinking text content */
-    content: string;
-    /** Whether this is actual thinking or redacted content */
-    type: "thinking" | "redacted";
-    /** Verification signature (Anthropic/Gemini) */
-    signature?: string;
-}
-/**
- * What content to include in the cache.
- *
- * - `"system"`: Cache only system prompt (lowest cost, highest reuse)
- * - `"conversation"`: Cache system prompt + all conversation turns except the latest user message
- */
-type CachingScope = "system" | "conversation";
-/**
- * Configuration for context caching across providers.
- *
- * Context caching allows reusing previously computed key-value pairs across
- * requests, reducing latency and cost for repeated context.
- *
- * Provider behavior:
- * - **Anthropic**: Automatic ephemeral caching via `cache_control` markers (always-on by default).
- *   Use `enabled: false` to disable markers and opt out of caching.
- * - **Gemini**: Explicit cache lifecycle via `caches.create()`. Requires `scope` and `ttl`.
- * - **OpenAI**: Server-side automatic caching (no-op, but respects the unified API).
- */
-interface CachingConfig {
-    /** Whether context caching is enabled */
-    enabled: boolean;
-    /**
-     * What to cache (Gemini only, default: "conversation").
-     * - `"system"`: Cache only system-derived messages
-     * - `"conversation"`: Cache system + all turns except the latest user message
-     */
-    scope?: CachingScope;
-    /** TTL for cache entries (Gemini only, format: "3600s", default: "3600s", min: "300s") */
-    ttl?: string;
-    /** Minimum token count for content to be eligible for caching (Gemini default: 32768) */
-    minTokenThreshold?: number;
-}
-interface LLMGenerationOptions {
-    model: string;
-    messages: LLMMessage[];
-    maxTokens?: number;
-    temperature?: number;
-    topP?: number;
-    stopSequences?: string[];
-    responseFormat?: "text";
-    metadata?: Record<string, unknown>;
-    extra?: Record<string, unknown>;
-    /**
-     * Optional abort signal for cancelling the request mid-flight.
-     *
-     * When the signal is aborted, the provider will attempt to cancel
-     * the underlying HTTP request and the stream will terminate with
-     * an abort error. Use `isAbortError()` from `@/core/errors` to
-     * detect cancellation in error handling.
-     *
-     * @example
-     * ```typescript
-     * const controller = new AbortController();
-     *
-     * const stream = client.stream({
-     *   model: "claude-3-5-sonnet-20241022",
-     *   messages: [{ role: "user", content: "Tell me a long story" }],
-     *   signal: controller.signal,
-     * });
-     *
-     * // Cancel after 5 seconds
-     * setTimeout(() => controller.abort(), 5000);
-     *
-     * try {
-     *   for await (const chunk of stream) {
-     *     process.stdout.write(chunk.text);
-     *   }
-     * } catch (error) {
-     *   if (isAbortError(error)) {
-     *     console.log("\nRequest was cancelled");
-     *   } else {
-     *     throw error;
-     *   }
-     * }
-     * ```
-     */
-    signal?: AbortSignal;
-    /** Reasoning/thinking configuration for reasoning-capable models */
-    reasoning?: ReasoningConfig;
-    /** Context caching configuration for supported providers */
-    caching?: CachingConfig;
-}
-interface TokenUsage {
-    inputTokens: number;
-    outputTokens: number;
-    totalTokens: number;
-    /** Number of input tokens served from cache (subset of inputTokens) */
-    cachedInputTokens?: number;
-    /** Number of input tokens written to cache (subset of inputTokens, Anthropic only) */
-    cacheCreationInputTokens?: number;
-    /** Number of reasoning/thinking tokens used (subset of outputTokens) */
-    reasoningTokens?: number;
-}
-interface LLMStreamChunk {
-    text: string;
-    /**
-     * Indicates that the provider has finished producing output and includes the reason if available.
-     */
-    finishReason?: string | null;
-    /**
-     * Token usage information, typically available in the final chunk when the stream completes.
-     */
-    usage?: TokenUsage;
-    /**
-     * Provider specific payload emitted at the same time as the text chunk. This is useful for debugging and tests.
-     */
-    rawEvent?: unknown;
-    /** Thinking/reasoning content from reasoning models */
-    thinking?: ThinkingChunk;
-}
-interface LLMStream extends AsyncIterable<LLMStreamChunk> {
-}
-type ProviderIdentifier = string;
-interface ModelDescriptor {
-    provider: string;
-    name: string;
-}
-declare class ModelIdentifierParser {
-    private readonly defaultProvider;
-    constructor(defaultProvider?: string);
-    parse(identifier: string): ModelDescriptor;
-}
-
-type GadgetClass = new (...args: unknown[]) => AbstractGadget;
-type GadgetOrClass = AbstractGadget | GadgetClass;
-declare class GadgetRegistry {
-    private readonly gadgets;
-    /**
-     * Creates a registry from an array of gadget classes or instances,
-     * or an object mapping names to gadgets.
-     *
-     * @param gadgets - Array of gadgets/classes or object with custom names
-     * @returns New GadgetRegistry with all gadgets registered
-     *
-     * @example
-     * ```typescript
-     * // From array of classes
-     * const registry = GadgetRegistry.from([Calculator, Weather]);
-     *
-     * // From array of instances
-     * const registry = GadgetRegistry.from([new Calculator(), new Weather()]);
-     *
-     * // From object with custom names
-     * const registry = GadgetRegistry.from({
-     *   calc: Calculator,
-     *   weather: new Weather({ apiKey: "..." })
-     * });
-     * ```
-     */
-    static from(gadgets: GadgetOrClass[] | Record<string, GadgetOrClass>): GadgetRegistry;
-    /**
-     * Registers multiple gadgets at once from an array.
-     *
-     * @param gadgets - Array of gadget instances or classes
-     * @returns This registry for chaining
-     *
-     * @example
-     * ```typescript
-     * registry.registerMany([Calculator, Weather, Email]);
-     * registry.registerMany([new Calculator(), new Weather()]);
-     * ```
-     */
-    registerMany(gadgets: GadgetOrClass[]): this;
-    register(name: string, gadget: AbstractGadget): void;
-    registerByClass(gadget: AbstractGadget): void;
-    get(name: string): AbstractGadget | undefined;
-    has(name: string): boolean;
-    getNames(): string[];
-    getAll(): AbstractGadget[];
-    unregister(name: string): boolean;
-    clear(): void;
+interface GadgetMediaOutput {
+    /** Type of media (discriminator for type-specific handling) */
+    kind: MediaKind;
+    /** Base64-encoded media data */
+    data: string;
+    /** Full MIME type (e.g., "image/png", "audio/mp3", "video/mp4") */
+    mimeType: string;
+    /** Human-readable description of the media */
+    description?: string;
+    /** Type-specific metadata */
+    metadata?: MediaMetadata;
+    /** Optional filename to use when saving (if not provided, auto-generated) */
+    fileName?: string;
 }
-
 /**
- * Event handler sugar for cleaner event processing.
+ * Stored media item with metadata and file path.
  *
- * Instead of verbose if/else chains, use named handlers
- * for each event type.
+ * Created by MediaStore when a gadget returns media outputs.
+ * Contains the abstract ID, file path, and metadata for display.
+ */
+interface StoredMedia {
+    /** Unique ID for this media item (e.g., "media_a1b2c3") */
+    id: string;
+    /** Type of media */
+    kind: MediaKind;
+    /** Actual file path on disk (internal use) */
+    path: string;
+    /** MIME type */
+    mimeType: string;
+    /** File size in bytes */
+    sizeBytes: number;
+    /** Human-readable description */
+    description?: string;
+    /** Type-specific metadata */
+    metadata?: MediaMetadata;
+    /** Name of the gadget that created this media */
+    gadgetName: string;
+    /** When the media was stored */
+    createdAt: Date;
+}
+/**
+ * Example of gadget usage to help LLMs understand proper invocation.
+ *
+ * Examples are rendered alongside the schema in `getInstruction()` to provide
+ * concrete usage patterns for the LLM.
+ *
+ * @template TParams - Inferred parameter type from Zod schema (defaults to Record<string, unknown>)
  *
  * @example
  * ```typescript
- * await agent.runWith({
- *   onText: (content) => console.log("LLM:", content),
- *   onGadgetResult: (result) => console.log("Result:", result.result),
+ * const calculator = createGadget({
+ *   schema: z.object({ a: z.number(), b: z.number() }),
+ *   examples: [
+ *     { params: { a: 5, b: 3 }, output: "8", comment: "Addition example" }
+ *   ],
+ *   // ...
  * });
  * ```
  */
+interface GadgetExample<TParams = Record<string, unknown>> {
+    /** Example parameter values (typed to match schema) */
+    params: TParams;
+    /** Optional expected output/result string */
+    output?: string;
+    /** Optional description explaining what this example demonstrates */
+    comment?: string;
+}
 
 /**
- * Named event handlers for different event types.
+ * Execution result types for gadget calls.
+ *
+ * Contains result types returned by gadget `execute()` methods and the
+ * internal result type used after execution completes.
+ *
+ * @module
  */
-interface EventHandlers {
-    /** Called when text is generated by the LLM */
-    onText?: (content: string) => void | Promise<void>;
-    /** Called when a gadget is about to be executed */
-    onGadgetCall?: (call: {
-        gadgetName: string;
-        invocationId: string;
-        parameters?: Record<string, unknown>;
-        parametersRaw: string;
-        dependencies: string[];
-    }) => void | Promise<void>;
-    /** Called when a gadget execution completes */
-    onGadgetResult?: (result: {
-        gadgetName: string;
-        invocationId: string;
-        result?: string;
-        error?: string;
-        parameters: Record<string, unknown>;
-    }) => void | Promise<void>;
-    /** Called when human input is required */
-    onHumanInputRequired?: (data: {
-        question: string;
-        gadgetName: string;
-    }) => void | Promise<void>;
-    /** Called for any other event type */
-    onOther?: (event: StreamEvent) => void | Promise<void>;
+
+interface GadgetExecutionResult {
+    gadgetName: string;
+    invocationId: string;
+    parameters: Record<string, unknown>;
+    result?: string;
+    error?: string;
+    executionTimeMs: number;
+    breaksLoop?: boolean;
+    /** Cost of gadget execution in USD. Defaults to 0 if not provided by gadget. */
+    cost?: number;
+    /** Media outputs from the gadget (images, audio, video, files) */
+    media?: GadgetMediaOutput[];
+    /** Abstract IDs for media outputs (e.g., ["media_a1b2c3"]) */
+    mediaIds?: string[];
+    /** Stored media with paths (for CLI display) */
+    storedMedia?: StoredMedia[];
 }
 /**
- * Helper to run an agent with named event handlers.
- *
- * @param agentGenerator - Agent's run() async generator
- * @param handlers - Named event handlers
+ * Result returned by gadget execute() method.
+ * Can be a simple string or an object with result and optional cost.
  *
  * @example
  * ```typescript
- * await runWithHandlers(agent.run(), {
- *   onText: (text) => console.log("LLM:", text),
- *   onGadgetResult: (result) => console.log("Result:", result.result),
- * });
+ * // Simple string return (free gadget)
+ * execute: () => "result"
+ *
+ * // Object return with cost
+ * execute: () => ({ result: "data", cost: 0.001 })
  * ```
  */
-declare function runWithHandlers(agentGenerator: AsyncGenerator<StreamEvent>, handlers: EventHandlers): Promise<void>;
+interface GadgetExecuteResult {
+    /** The execution result as a string */
+    result: string;
+    /** Optional cost in USD (e.g., 0.001 for $0.001) */
+    cost?: number;
+}
 /**
- * Helper to collect events by type.
- *
- * @param agentGenerator - Agent's run() async generator
- * @param collect - Object specifying which event types to collect
- * @returns Object with collected events
+ * Extended result type with media support.
+ * Use this when gadget returns images, audio, video, or files.
  *
  * @example
  * ```typescript
- * const { text, gadgetResults } = await collectEvents(agent.run(), {
- *   text: true,
- *   gadgetResults: true,
- * });
- *
- * console.log("Full response:", text.join(""));
- * console.log("Gadget calls:", gadgetResults.length);
+ * // Return with image
+ * execute: () => ({
+ *   result: "Screenshot captured",
+ *   media: [{
+ *     kind: "image",
+ *     data: base64EncodedPng,
+ *     mimeType: "image/png",
+ *     description: "Screenshot"
+ *   }],
+ *   cost: 0.001
+ * })
  * ```
  */
-declare function collectEvents(agentGenerator: AsyncGenerator<StreamEvent>, collect: {
-    text?: boolean;
-    gadgetCalls?: boolean;
-    gadgetResults?: boolean;
-}): Promise<{
-    text: string[];
-    gadgetCalls: Array<{
-        gadgetName: string;
-        parameters: Record<string, unknown>;
-    }>;
-    gadgetResults: Array<{
-        gadgetName: string;
-        result?: string;
-        error?: string;
-        parameters: Record<string, unknown>;
-    }>;
-}>;
+interface GadgetExecuteResultWithMedia {
+    /** The execution result as a string */
+    result: string;
+    /** Media outputs (images, audio, video, files) */
+    media?: GadgetMediaOutput[];
+    /** Optional cost in USD (e.g., 0.001 for $0.001) */
+    cost?: number;
+}
+/**
+ * Union type for backwards-compatible execute() return type.
+ * Gadgets can return:
+ * - string (legacy, cost = 0)
+ * - GadgetExecuteResult (result + optional cost)
+ * - GadgetExecuteResultWithMedia (result + optional media + optional cost)
+ */
+type GadgetExecuteReturn = string | GadgetExecuteResult | GadgetExecuteResultWithMedia;
+interface ParsedGadgetCall {
+    gadgetName: string;
+    invocationId: string;
+    parametersRaw: string;
+    parameters?: Record<string, unknown>;
+    parseError?: string;
+    /** List of invocation IDs this gadget depends on. Empty array if no dependencies. */
+    dependencies: string[];
+}
+
+/**
+ * Stream event types emitted during agent execution.
+ *
+ * Contains all discriminated union members for `StreamEvent`, plus
+ * `StreamCompletionEvent` and `GadgetSkippedEvent`.
+ *
+ * @module
+ */
+
+/** Event emitted when a gadget is skipped due to a failed dependency */
+interface GadgetSkippedEvent {
+    type: "gadget_skipped";
+    gadgetName: string;
+    invocationId: string;
+    parameters: Record<string, unknown>;
+    /** The invocation ID of the dependency that failed */
+    failedDependency: string;
+    /** The error message from the failed dependency */
+    failedDependencyError: string;
+}
+/**
+ * Event emitted when stream processing completes, containing metadata.
+ * This allows the async generator to "return" metadata while still yielding events.
+ */
+interface StreamCompletionEvent {
+    type: "stream_complete";
+    /** The reason the LLM stopped generating (e.g., "stop", "tool_use") */
+    finishReason: string | null;
+    /** Token usage statistics from the LLM call */
+    usage?: TokenUsage;
+    /** Raw response text from the LLM */
+    rawResponse: string;
+    /** Final message after all interceptors applied */
+    finalMessage: string;
+    /** Whether any gadgets were executed during this iteration */
+    didExecuteGadgets: boolean;
+    /** Whether to break the agent loop (e.g., TaskComplete was called) */
+    shouldBreakLoop: boolean;
+    /** Accumulated thinking/reasoning content from reasoning models */
+    thinkingContent?: string;
+}
+type StreamEvent = {
+    type: "text";
+    content: string;
+} | {
+    type: "thinking";
+    content: string;
+    thinkingType: "thinking" | "redacted";
+} | {
+    type: "gadget_call";
+    call: ParsedGadgetCall;
+} | {
+    type: "gadget_result";
+    result: GadgetExecutionResult;
+} | GadgetSkippedEvent | {
+    type: "human_input_required";
+    question: string;
+    gadgetName: string;
+    invocationId: string;
+} | {
+    type: "compaction";
+    event: CompactionEvent;
+} | {
+    type: "llm_response_end";
+    finishReason: string | null;
+    usage?: TokenUsage;
+} | StreamCompletionEvent;
+
 /**
- * Helper to collect only text from an agent run.
+ * Text-only response handler types.
  *
- * @param agentGenerator - Agent's run() async generator
- * @returns Combined text response
+ * Defines the handler configuration for when the LLM returns a text-only response
+ * (no gadget calls). Supports simple strategies, gadget triggers, and custom handlers.
  *
- * @example
- * ```typescript
- * const response = await collectText(agent.run());
- * console.log(response);
- * ```
+ * @module
  */
-declare function collectText(agentGenerator: AsyncGenerator<StreamEvent>): Promise<string>;
 
+type TextOnlyHandler = TextOnlyStrategy | TextOnlyGadgetConfig | TextOnlyCustomHandler;
 /**
- * Fluent builder for creating agents with delightful DX.
- *
- * @example
- * ```typescript
- * const agent = await LLMist.createAgent()
- *   .withModel("sonnet")
- *   .withSystem("You are a helpful assistant")
- *   .withGadgets(Calculator, Weather)
- *   .withMaxIterations(10)
- *   .ask("What's the weather in Paris?");
- *
- * for await (const event of agent.run()) {
- *   // process events
- * }
- * ```
+ * Simple strategies for common cases
+ * - 'terminate': End the loop (default behavior)
+ * - 'acknowledge': Continue to next iteration
+ * - 'wait_for_input': Request human input
  */
-
+type TextOnlyStrategy = "terminate" | "acknowledge" | "wait_for_input";
 /**
- * Message for conversation history.
- * User messages can be text (string) or multimodal (ContentPart[]).
+ * Configuration for triggering a gadget when receiving text-only response
  */
-type HistoryMessage = {
-    user: string | ContentPart[];
-} | {
-    assistant: string;
-} | {
-    system: string;
-};
+interface TextOnlyGadgetConfig {
+    type: "gadget";
+    name: string;
+    /**
+     * Optional function to map text to gadget parameters.
+     * If not provided, text will be passed as { text: string }
+     */
+    parameterMapping?: (text: string) => Record<string, unknown>;
+}
 /**
- * Context available to trailing message functions.
- * Provides iteration information for dynamic message generation.
+ * Custom handler for complex text-only response scenarios
  */
-type TrailingMessageContext = Pick<LLMCallControllerContext, "iteration" | "maxIterations" | "budget" | "totalCost">;
+interface TextOnlyCustomHandler {
+    type: "custom";
+    handler: (context: TextOnlyContext) => Promise<TextOnlyAction> | TextOnlyAction;
+}
 /**
- * Trailing message can be a static string or a function that generates the message.
- * The function receives context about the current iteration.
+ * Context provided to custom text-only handlers
  */
-type TrailingMessage = string | ((ctx: TrailingMessageContext) => string);
+interface TextOnlyContext {
+    /** The complete text response from the LLM */
+    text: string;
+    /** Current iteration number */
+    iteration: number;
+    /** Full conversation history */
+    conversation: LLMMessage[];
+    /** Logger instance */
+    logger: Logger<ILogObj>;
+}
 /**
- * Fluent builder for creating agents.
+ * Actions that can be returned by text-only handlers
+ */
+type TextOnlyAction = {
+    action: "continue";
+} | {
+    action: "terminate";
+} | {
+    action: "wait_for_input";
+    question?: string;
+} | {
+    action: "trigger_gadget";
+    name: string;
+    parameters: Record<string, unknown>;
+};
+
+/**
+ * Abstract base class for gadgets. Most users should use the `Gadget()` factory
+ * or `createGadget()` function instead, as they provide better type safety
+ * and simpler APIs.
  *
- * Provides a chainable API for configuring and creating agents,
- * making the code more expressive and easier to read.
+ * Extend this class directly only when you need advanced control over gadget behavior.
  */
-declare class AgentBuilder {
-    private client?;
-    private model?;
-    private systemPrompt?;
-    private temperature?;
-    private maxIterations?;
-    private budget?;
-    private logger?;
-    private hooks?;
-    private promptConfig?;
-    private gadgets;
-    private initialMessages;
-    private requestHumanInput?;
-    private gadgetStartPrefix?;
-    private gadgetEndPrefix?;
-    private gadgetArgPrefix?;
-    private textOnlyHandler?;
-    private textWithGadgetsHandler?;
-    private defaultGadgetTimeoutMs?;
-    private gadgetExecutionMode?;
-    private maxGadgetsPerResponse?;
-    private gadgetOutputLimit?;
-    private gadgetOutputLimitPercent?;
-    private compactionConfig?;
-    private retryConfig?;
-    private rateLimitConfig?;
-    private signal?;
-    private trailingMessage?;
-    private subagentConfig?;
-    private parentContext?;
-    private parentObservers?;
-    private sharedRateLimitTracker?;
-    private sharedRetryConfig?;
-    private reasoningConfig?;
-    private cachingConfig?;
-    constructor(client?: LLMist);
+declare abstract class AbstractGadget {
     /**
-     * Set the model to use.
-     * Supports aliases like "gpt4", "sonnet", "flash".
-     *
-     * @param model - Model name or alias
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withModel("sonnet")           // Alias
-     * .withModel("gpt-5-nano")       // Auto-detects provider
-     * .withModel("openai:gpt-5")     // Explicit provider
-     * ```
+     * The name of the gadget. Used for identification when LLM calls it.
+     * If not provided, defaults to the class name.
      */
-    withModel(model: string): this;
+    name?: string;
     /**
-     * Set the system prompt.
-     *
-     * @param prompt - System prompt
-     * @returns This builder for chaining
+     * Human-readable description of what the gadget does.
      */
-    withSystem(prompt: string): this;
+    abstract description: string;
     /**
-     * Set the temperature (0-1).
-     *
-     * @param temperature - Temperature value
-     * @returns This builder for chaining
+     * Optional Zod schema describing the expected input payload. When provided,
+     * it will be validated before execution and transformed into a JSON Schema
+     * representation that is surfaced to the LLM as part of the instructions.
      */
-    withTemperature(temperature: number): this;
+    parameterSchema?: ZodTypeAny;
+    /**
+     * Optional timeout in milliseconds for gadget execution.
+     * If execution exceeds this timeout, a TimeoutException will be thrown.
+     * If not set, the global defaultGadgetTimeoutMs from runtime options will be used.
+     * Set to 0 or undefined to disable timeout for this gadget.
+     */
+    timeoutMs?: number;
     /**
-     * Set maximum iterations.
+     * Optional usage examples to help LLMs understand proper invocation.
+     * Examples are rendered in getInstruction() alongside the schema.
      *
-     * @param max - Maximum number of iterations
-     * @returns This builder for chaining
+     * Note: Uses broader `unknown` type to allow typed examples from subclasses
+     * while maintaining runtime compatibility.
      */
-    withMaxIterations(max: number): this;
+    examples?: GadgetExample<unknown>[];
     /**
-     * Set the budget limit in USD.
-     * The agent loop stops when cumulative cost reaches this limit.
+     * Maximum number of concurrent executions allowed for this gadget.
+     * Use this to prevent race conditions in gadgets that modify shared state.
+     *
+     * - `1` = Sequential execution (only one instance runs at a time)
+     * - `0` or `undefined` = Unlimited concurrency (default)
+     * - `N > 1` = At most N concurrent executions
      *
-     * @param amountUSD - Maximum spend in USD
-     * @returns This builder for chaining
+     * This property sets a safety floor: external configuration (SubagentConfig)
+     * can only make concurrency MORE restrictive, never less. For example, if
+     * a gadget declares `maxConcurrent: 1`, external config cannot override it
+     * to allow parallel execution.
      *
      * @example
      * ```typescript
-     * .withBudget(0.50)  // Stop after $0.50 spent
+     * // File writer that must run sequentially to avoid race conditions
+     * class WriteFile extends Gadget({
+     *   description: 'Writes content to a file',
+     *   schema: z.object({ path: z.string(), content: z.string() }),
+     *   maxConcurrent: 1, // Sequential - prevents race conditions
+     * }) {
+     *   execute(params: this['params']) { ... }
+     * }
      * ```
      */
-    withBudget(amountUSD: number): this;
+    maxConcurrent?: number;
     /**
-     * Set logger instance.
+     * If true, this gadget must execute alone — no other gadgets in the same
+     * LLM response can run in parallel. When an exclusive gadget arrives and
+     * other gadgets are already in-flight, it is deferred until they complete.
+     *
+     * Use for gadgets that terminate the agent loop (e.g., Finish), where
+     * sibling tool results must be visible to the LLM before the loop ends.
      *
-     * @param logger - Logger instance
-     * @returns This builder for chaining
+     * This is a safety floor: external config cannot weaken it.
      */
-    withLogger(logger: Logger<ILogObj>): this;
+    exclusive?: boolean;
     /**
-     * Add hooks for agent lifecycle events.
+     * Execute the gadget with the given parameters.
+     * Can be synchronous or asynchronous.
      *
-     * @param hooks - Agent hooks configuration
-     * @returns This builder for chaining
+     * @param params - Parameters passed from the LLM
+     * @param ctx - Optional execution context for cost reporting and LLM access
+     * @returns Result as a string, or an object with result and optional cost
      *
      * @example
      * ```typescript
-     * import { HookPresets } from 'llmist/hooks';
+     * // Simple string return (free gadget)
+     * execute(params) {
+     *   return "result";
+     * }
      *
-     * .withHooks(HookPresets.logging())
-     * .withHooks(HookPresets.merge(
-     *   HookPresets.logging(),
-     *   HookPresets.timing()
-     * ))
-     * ```
-     */
-    withHooks(hooks: AgentHooks): this;
-    /**
-     * Configure custom prompts for gadget system messages.
+     * // Object return with cost tracking
+     * execute(params) {
+     *   return { result: "data", cost: 0.001 };
+     * }
      *
-     * @param config - Prompt configuration object
-     * @returns This builder for chaining
+     * // Using context for callback-based cost reporting
+     * execute(params, ctx) {
+     *   ctx.reportCost(0.001);
+     *   return "result";
+     * }
      *
-     * @example
-     * ```typescript
-     * .withPromptTemplateConfig({
-     *   mainInstruction: "Use the gadget markers below:",
-     *   rules: ["Always use markers", "Never use function calling"]
-     * })
+     * // Using wrapped LLMist for automatic cost tracking
+     * async execute(params, ctx) {
+     *   const summary = await ctx.llmist.complete('Summarize: ' + params.text);
+     *   return summary;
+     * }
      * ```
      */
-    withPromptTemplateConfig(config: PromptTemplateConfig): this;
+    abstract execute(params: Record<string, unknown>, ctx?: ExecutionContext): GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
     /**
-     * Add gadgets (classes or instances).
-     * Can be called multiple times to add more gadgets.
+     * Throws an AbortException if the execution has been aborted.
+     *
+     * Call this at key checkpoints in long-running gadgets to allow early exit
+     * when the gadget has been cancelled (e.g., due to timeout). This enables
+     * resource cleanup and prevents unnecessary work after cancellation.
      *
-     * @param gadgets - Gadget classes or instances
-     * @returns This builder for chaining
+     * @param ctx - The execution context containing the abort signal
+     * @throws AbortException if ctx.signal.aborted is true
      *
      * @example
      * ```typescript
-     * .withGadgets(Calculator, Weather, Email)
-     * .withGadgets(new Calculator(), new Weather())
-     * .withGadgets(createGadget({ ... }))
-     * ```
-     */
-    withGadgets(...gadgets: GadgetOrClass[]): this;
-    /**
-     * Add conversation history messages.
-     * Useful for continuing previous conversations.
+     * class DataProcessor extends Gadget({
+     *   description: 'Processes data in multiple steps',
+     *   schema: z.object({ items: z.array(z.string()) }),
+     * }) {
+     *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
+     *     const results: string[] = [];
+     *
+     *     for (const item of params.items) {
+     *       // Check before each expensive operation
+     *       this.throwIfAborted(ctx);
      *
-     * @param messages - Array of history messages
-     * @returns This builder for chaining
+     *       results.push(await this.processItem(item));
+     *     }
      *
-     * @example
-     * ```typescript
-     * .withHistory([
-     *   { user: "Hello" },
-     *   { assistant: "Hi there!" },
-     *   { user: "How are you?" },
-     *   { assistant: "I'm doing well, thanks!" }
-     * ])
+     *     return results.join(', ');
+     *   }
+     * }
      * ```
      */
-    withHistory(messages: HistoryMessage[]): this;
+    throwIfAborted(ctx?: ExecutionContext): void;
     /**
-     * Add a single message to the conversation history.
+     * Register a cleanup function to run when execution is aborted (timeout or cancellation).
+     * The cleanup function is called immediately if the signal is already aborted.
+     * Errors thrown by the cleanup function are silently ignored.
+     *
+     * Use this to clean up resources like browser instances, database connections,
+     * or child processes when the gadget is cancelled due to timeout.
      *
-     * @param message - Single history message
-     * @returns This builder for chaining
+     * @param ctx - The execution context containing the abort signal
+     * @param cleanup - Function to run on abort (can be sync or async)
      *
      * @example
      * ```typescript
-     * .addMessage({ user: "Hello" })
-     * .addMessage({ assistant: "Hi there!" })
-     * ```
-     */
-    addMessage(message: HistoryMessage): this;
-    /**
-     * Clear any previously set conversation history.
-     * Used before setting new cumulative history in REPL mode.
+     * class BrowserGadget extends Gadget({
+     *   description: 'Fetches web page content',
+     *   schema: z.object({ url: z.string() }),
+     * }) {
+     *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
+     *     const browser = await chromium.launch();
+     *     this.onAbort(ctx, () => browser.close());
      *
-     * @returns This builder for chaining
+     *     const page = await browser.newPage();
+     *     this.onAbort(ctx, () => page.close());
      *
-     * @example
-     * ```typescript
-     * // Reset history before setting new cumulative history
-     * builder.clearHistory().withHistory(cumulativeHistory);
+     *     await page.goto(params.url);
+     *     const content = await page.content();
+     *
+     *     await browser.close();
+     *     return content;
+     *   }
+     * }
      * ```
      */
-    clearHistory(): this;
+    onAbort(ctx: ExecutionContext | undefined, cleanup: () => void | Promise<void>): void;
     /**
-     * Continue conversation from a previous agent's history.
-     * Extracts full conversation history and sets it as initial messages.
+     * Create an AbortController linked to the execution context's signal.
+     * When the parent signal aborts, the returned controller also aborts with the same reason.
      *
-     * This is the recommended way to implement REPL session continuation.
-     * It automatically handles history extraction and format conversion.
+     * Useful for passing abort signals to child operations like fetch() while still
+     * being able to abort them independently if needed.
      *
-     * @param agent - The previous agent to continue from
-     * @returns This builder for chaining
+     * @param ctx - The execution context containing the parent abort signal
+     * @returns A new AbortController linked to the parent signal
      *
      * @example
      * ```typescript
-     * // REPL loop with session continuity
-     * let previousAgent: Agent | null = null;
+     * class FetchGadget extends Gadget({
+     *   description: 'Fetches data from URL',
+     *   schema: z.object({ url: z.string() }),
+     * }) {
+     *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
+     *     const controller = this.createLinkedAbortController(ctx);
      *
-     * while (true) {
-     *   if (previousAgent) {
-     *     builder.continueFrom(previousAgent);
+     *     // fetch() will automatically abort when parent times out
+     *     const response = await fetch(params.url, { signal: controller.signal });
+     *     return response.text();
      *   }
-     *   const agent = builder.ask(prompt);
-     *   await runAgent(agent);
-     *   previousAgent = agent;
      * }
      * ```
      */
-    continueFrom(agent: Agent): this;
+    createLinkedAbortController(ctx?: ExecutionContext): AbortController;
     /**
-     * Set the human input handler for interactive conversations.
-     *
-     * @param handler - Function to handle human input requests
-     * @returns This builder for chaining
+     * Generate instruction text for the LLM.
+     * Combines name, description, and parameter schema into a formatted instruction.
      *
-     * @example
-     * ```typescript
-     * .onHumanInput(async (question) => {
-     *   return await promptUser(question);
-     * })
-     * ```
+     * @param optionsOrArgPrefix - Optional custom prefixes for examples, or just argPrefix string for backwards compatibility
+     * @returns Formatted instruction string
      */
-    onHumanInput(handler: (question: string) => Promise<string>): this;
+    getInstruction(optionsOrArgPrefix?: string | {
+        argPrefix?: string;
+        startPrefix?: string;
+        endPrefix?: string;
+    }): string;
+}
+
+/**
+ * Context provided to prompt template functions for rendering dynamic content.
+ */
+interface PromptContext {
+    /** Custom gadget start prefix */
+    startPrefix: string;
+    /** Custom gadget end prefix */
+    endPrefix: string;
+    /** Custom argument prefix for block format */
+    argPrefix: string;
+    /** Number of gadgets being registered */
+    gadgetCount: number;
+    /** Names of all gadgets */
+    gadgetNames: string[];
+}
+/**
+ * Context provided to hint template functions for rendering dynamic hints.
+ */
+interface HintContext {
+    /** Current iteration (1-based for readability) */
+    iteration: number;
+    /** Maximum iterations allowed */
+    maxIterations: number;
+    /** Iterations remaining (maxIterations - iteration) */
+    remaining: number;
+    /** Number of gadget calls in the current response */
+    gadgetCallCount?: number;
+}
+/**
+ * Template that can be either a static string or a function that renders based on context.
+ */
+type PromptTemplate = string | ((context: PromptContext) => string);
+/**
+ * Template for hints that can be either a static string or a function that renders based on hint context.
+ */
+type HintTemplate = string | ((context: HintContext) => string);
+/**
+ * Configuration for customizing all prompts used internally by llmist.
+ *
+ * Each field can be either a string (static text) or a function that receives
+ * context and returns a string (for dynamic content).
+ *
+ * @example
+ * ```typescript
+ * const customConfig: PromptTemplateConfig = {
+ *   mainInstruction: "USE ONLY THE GADGET MARKERS BELOW:",
+ *   criticalUsage: "Important: Follow the exact format shown.",
+ *   rules: (ctx) => [
+ *     "Always use the markers to invoke gadgets",
+ *     "Never use function calling",
+ *     `You have ${ctx.gadgetCount} gadgets available`
+ *   ]
+ * };
+ * ```
+ */
+interface PromptTemplateConfig {
     /**
-     * Set custom gadget marker prefix.
-     *
-     * @param prefix - Custom start prefix for gadget markers
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withGadgetStartPrefix("<<GADGET_START>>")
-     * ```
+     * Main instruction block that appears at the start of the gadget system prompt.
+     * Default emphasizes using text markers instead of function calling.
      */
-    withGadgetStartPrefix(prefix: string): this;
+    mainInstruction?: PromptTemplate;
     /**
-     * Set custom gadget marker suffix.
-     *
-     * @param suffix - Custom end suffix for gadget markers
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withGadgetEndPrefix("<<GADGET_END>>")
-     * ```
+     * Critical usage instruction that appears in the usage section.
+     * Default emphasizes the exact format requirement.
      */
-    withGadgetEndPrefix(suffix: string): this;
+    criticalUsage?: PromptTemplate;
     /**
-     * Set custom argument prefix for block format parameters.
-     *
-     * @param prefix - Custom prefix for argument markers (default: "!!!ARG:")
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withGadgetArgPrefix("<<ARG>>")
-     * ```
+     * Format description for the block parameter format.
+     * Default uses the configured argPrefix dynamically.
      */
-    withGadgetArgPrefix(prefix: string): this;
+    formatDescription?: PromptTemplate;
     /**
-     * Set the text-only handler strategy.
-     *
-     * Controls what happens when the LLM returns text without calling any gadgets:
-     * - "terminate": End the agent loop (default)
-     * - "acknowledge": Continue the loop for another iteration
-     * - "wait_for_input": Wait for human input
-     * - Custom handler: Provide a function for dynamic behavior
-     *
-     * @param handler - Text-only handler strategy or custom handler
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Simple strategy
-     * .withTextOnlyHandler("acknowledge")
-     *
-     * // Custom handler
-     * .withTextOnlyHandler({
-     *   type: "custom",
-     *   handler: async (context) => {
-     *     if (context.text.includes("?")) {
-     *       return { action: "wait_for_input", question: context.text };
-     *     }
-     *     return { action: "continue" };
-     *   }
-     * })
-     * ```
+     * Rules that appear in the rules section.
+     * Can be an array of strings or a function that returns an array.
+     * Default includes rules about not using function calling.
      */
-    withTextOnlyHandler(handler: TextOnlyHandler): this;
+    rules?: PromptTemplate | string[] | ((context: PromptContext) => string[]);
     /**
-     * Set the handler for text content that appears alongside gadget calls.
-     *
-     * When set, text accompanying gadget responses will be wrapped as a
-     * synthetic gadget call before the actual gadget results in the
-     * conversation history.
-     *
-     * @param handler - Configuration for wrapping text
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Wrap text as TellUser gadget
-     * .withTextWithGadgetsHandler({
-     *   gadgetName: "TellUser",
-     *   parameterMapping: (text) => ({ message: text, done: false, type: "info" }),
-     *   resultMapping: (text) => `ℹ️  ${text}`,
-     * })
-     * ```
+     * Custom examples to show in the examples section.
+     * If provided, replaces the default examples entirely.
+     * Should be a function that returns formatted example strings.
      */
-    withTextWithGadgetsHandler(handler: {
-        gadgetName: string;
-        parameterMapping: (text: string) => Record<string, unknown>;
-        resultMapping?: (text: string) => string;
-    }): this;
+    customExamples?: (context: PromptContext) => string;
     /**
-     * Set default timeout for gadget execution.
-     *
-     * @param timeoutMs - Timeout in milliseconds (must be non-negative)
-     * @returns This builder for chaining
-     * @throws {Error} If timeout is negative
-     *
-     * @example
-     * ```typescript
-     * .withDefaultGadgetTimeout(5000) // 5 second timeout
-     * ```
+     * Hint shown when LLM uses only one gadget per response.
+     * Encourages parallel gadget usage for efficiency.
      */
-    withDefaultGadgetTimeout(timeoutMs: number): this;
+    parallelGadgetsHint?: HintTemplate;
     /**
-     * Set the gadget execution mode.
-     *
-     * Controls how multiple gadgets are executed when the LLM calls them:
-     * - `'parallel'` (default): Gadgets without dependencies execute concurrently
-     * - `'sequential'`: Gadgets execute one at a time, each awaiting completion
-     *
-     * @param mode - Execution mode ('parallel' or 'sequential')
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Sequential execution for ordered file operations
-     * .withGadgetExecutionMode('sequential')
+     * Template for iteration progress hint.
+     * Informs the LLM about remaining iterations to help plan work.
      *
-     * // Parallel execution (default) for independent operations
-     * .withGadgetExecutionMode('parallel')
-     * ```
+     * When using a string template, supports placeholders:
+     * - {iteration}: Current iteration (1-based)
+     * - {maxIterations}: Maximum iterations allowed
+     * - {remaining}: Iterations remaining
      */
-    withGadgetExecutionMode(mode: GadgetExecutionMode): this;
+    iterationProgressHint?: HintTemplate;
+}
+/**
+ * Default hint templates used by llmist.
+ */
+declare const DEFAULT_HINTS: {
+    readonly parallelGadgetsHint: "Tip: You can call multiple gadgets in a single response for efficiency.";
+    readonly iterationProgressHint: "[Iteration {iteration}/{maxIterations}] Plan your actions accordingly.";
+};
+/**
+ * Default prompt templates used by llmist.
+ */
+declare const DEFAULT_PROMPTS: Required<Omit<PromptTemplateConfig, "rules" | "customExamples" | "parallelGadgetsHint" | "iterationProgressHint"> & {
+    rules: (context: PromptContext) => string[];
+    customExamples: null;
+}>;
+/**
+ * Resolve a prompt template to a string using the given context.
+ */
+declare function resolvePromptTemplate(template: PromptTemplate | undefined, defaultValue: PromptTemplate, context: PromptContext): string;
+/**
+ * Resolve rules template to an array of strings.
+ */
+declare function resolveRulesTemplate(rules: PromptTemplateConfig["rules"] | undefined, context: PromptContext): string[];
+/**
+ * Resolve a hint template to a string using the given context.
+ * Supports both function templates and string templates with placeholders.
+ *
+ * @param template - The hint template to resolve
+ * @param defaultValue - Default value if template is undefined
+ * @param context - Context for rendering the template
+ * @returns The resolved hint string
+ */
+declare function resolveHintTemplate(template: HintTemplate | undefined, defaultValue: string, context: HintContext): string;
+
+type MessageRole = "system" | "user" | "assistant";
+/**
+ * Message content can be a simple string (text only) or an array of content parts (multimodal).
+ * Using a string is simpler for text-only messages, while arrays support images and audio.
+ */
+type MessageContent = string | ContentPart[];
+interface LLMMessage {
+    role: MessageRole;
+    content: MessageContent;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Normalize message content to an array of content parts.
+ * Converts string content to a single text part.
+ *
+ * @param content - Message content (string or ContentPart[])
+ * @returns Array of content parts
+ */
+declare function normalizeMessageContent(content: MessageContent): ContentPart[];
+/**
+ * Extract text from message content.
+ * Concatenates all text parts in the content.
+ *
+ * @param content - Message content (string or ContentPart[])
+ * @returns Combined text from all text parts
+ */
+declare function extractMessageText(content: MessageContent): string;
+declare class LLMMessageBuilder {
+    private readonly messages;
+    private startPrefix;
+    private endPrefix;
+    private argPrefix;
+    private promptConfig;
+    constructor(promptConfig?: PromptTemplateConfig);
+    /**
+     * Set custom prefixes for gadget markers.
+     * Used to configure history builder to match system prompt markers.
+     */
+    withPrefixes(startPrefix: string, endPrefix: string, argPrefix?: string): this;
+    addSystem(content: string, metadata?: Record<string, unknown>): this;
+    addGadgets(gadgets: AbstractGadget[], options?: {
+        startPrefix?: string;
+        endPrefix?: string;
+        argPrefix?: string;
+    }): this;
+    private buildGadgetsSection;
+    private buildUsageSection;
+    private buildExamplesSection;
+    private buildRulesSection;
     /**
-     * Set the maximum number of gadgets to execute per LLM response.
-     *
-     * When the limit is reached, remaining gadgets are skipped with an informative
-     * message visible to the LLM, allowing it to adjust on the next iteration.
-     * Gadgets already in-flight (executing in parallel) are allowed to complete.
+     * Add a user message.
+     * Content can be a string (text only) or an array of content parts (multimodal).
      *
-     * @param max - Maximum gadgets per response (0 = unlimited, default)
-     * @returns This builder for chaining
-     * @throws {Error} If max is negative or non-integer
+     * @param content - Message content
+     * @param metadata - Optional metadata
      *
      * @example
      * ```typescript
-     * // Limit to 5 gadgets per response
-     * LLMist.createAgent()
-     *   .withModel("sonnet")
-     *   .withGadgets(ReadFile, WriteFile, Search)
-     *   .withMaxGadgetsPerResponse(5)
-     *   .ask("Process these files...");
+     * // Text only
+     * builder.addUser("Hello!");
+     *
+     * // Multimodal
+     * builder.addUser([
+     *   text("What's in this image?"),
+     *   imageFromBuffer(imageData),
+     * ]);
      * ```
      */
-    withMaxGadgetsPerResponse(max: number): this;
+    addUser(content: MessageContent, metadata?: Record<string, unknown>): this;
+    addAssistant(content: string, metadata?: Record<string, unknown>): this;
     /**
-     * Enable or disable gadget output limiting.
-     *
-     * When enabled, gadget outputs exceeding the configured limit are stored
-     * and can be browsed using the GadgetOutputViewer gadget.
+     * Add a user message with an image attachment.
      *
-     * @param enabled - Whether to enable output limiting (default: true)
-     * @returns This builder for chaining
+     * @param textContent - Text prompt
+     * @param imageData - Image data (Buffer, Uint8Array, or base64 string)
+     * @param mimeType - Optional MIME type (auto-detected if not provided)
      *
      * @example
      * ```typescript
-     * .withGadgetOutputLimit(false) // Disable output limiting
+     * builder.addUserWithImage(
+     *   "What's in this image?",
+     *   await fs.readFile("photo.jpg"),
+     *   "image/jpeg"  // Optional - auto-detected
+     * );
      * ```
      */
-    withGadgetOutputLimit(enabled: boolean): this;
+    addUserWithImage(textContent: string, imageData: Buffer | Uint8Array | string, mimeType?: ImageMimeType): this;
     /**
-     * Set the maximum gadget output as a percentage of the model's context window.
-     *
-     * Outputs exceeding this limit are stored for later browsing with GadgetOutputViewer.
+     * Add a user message with an image URL (OpenAI only).
      *
-     * @param percent - Percentage of context window (1-100, default: 15)
-     * @returns This builder for chaining
-     * @throws {Error} If percent is not between 1 and 100
+     * @param textContent - Text prompt
+     * @param imageUrl - URL to the image
      *
      * @example
      * ```typescript
-     * .withGadgetOutputLimitPercent(25) // 25% of context window
+     * builder.addUserWithImageUrl(
+     *   "What's in this image?",
+     *   "https://example.com/image.jpg"
+     * );
      * ```
      */
-    withGadgetOutputLimitPercent(percent: number): this;
+    addUserWithImageUrl(textContent: string, imageUrl: string): this;
     /**
-     * Configure context compaction.
-     *
-     * Context compaction automatically manages conversation history to prevent
-     * context window overflow in long-running agent conversations.
+     * Add a user message with an audio attachment (Gemini only).
      *
-     * @param config - Compaction configuration options
-     * @returns This builder for chaining
+     * @param textContent - Text prompt
+     * @param audioData - Audio data (Buffer, Uint8Array, or base64 string)
+     * @param mimeType - Optional MIME type (auto-detected if not provided)
      *
      * @example
      * ```typescript
-     * // Custom thresholds
-     * .withCompaction({
-     *   triggerThresholdPercent: 70,
-     *   targetPercent: 40,
-     *   preserveRecentTurns: 10,
-     * })
-     *
-     * // Different strategy
-     * .withCompaction({
-     *   strategy: 'sliding-window',
-     * })
-     *
-     * // With callback
-     * .withCompaction({
-     *   onCompaction: (event) => {
-     *     console.log(`Saved ${event.tokensBefore - event.tokensAfter} tokens`);
-     *   }
-     * })
+     * builder.addUserWithAudio(
+     *   "Transcribe this audio",
+     *   await fs.readFile("recording.mp3"),
+     *   "audio/mp3"  // Optional - auto-detected
+     * );
      * ```
      */
-    withCompaction(config: CompactionConfig): this;
+    addUserWithAudio(textContent: string, audioData: Buffer | Uint8Array | string, mimeType?: AudioMimeType): this;
     /**
-     * Disable context compaction.
-     *
-     * By default, compaction is enabled. Use this method to explicitly disable it.
+     * Add a user message with multiple content parts.
+     * Provides full flexibility for complex multimodal messages.
      *
-     * @returns This builder for chaining
+     * @param parts - Array of content parts
      *
      * @example
      * ```typescript
-     * .withoutCompaction() // Disable automatic compaction
+     * builder.addUserMultimodal([
+     *   text("Compare these images:"),
+     *   imageFromBuffer(image1),
+     *   imageFromBuffer(image2),
+     * ]);
      * ```
      */
-    withoutCompaction(): this;
+    addUserMultimodal(parts: ContentPart[]): this;
     /**
-     * Configure retry behavior for LLM API calls.
-     *
-     * Retry is enabled by default with conservative settings (3 retries, exponential backoff).
-     * Use this method to customize retry behavior for rate limits, timeouts, and transient errors.
-     *
-     * @param config - Retry configuration options
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Custom retry configuration
-     * .withRetry({
-     *   retries: 5,
-     *   minTimeout: 2000,
-     *   maxTimeout: 60000,
-     * })
+     * Record a gadget execution result in the message history.
+     * Creates an assistant message with the gadget invocation and a user message with the result.
      *
-     * // With monitoring callbacks
-     * .withRetry({
-     *   onRetry: (error, attempt) => {
-     *     console.log(`Retry ${attempt}: ${error.message}`);
-     *   },
-     *   onRetriesExhausted: (error, attempts) => {
-     *     alerting.warn(`Failed after ${attempts} attempts`);
-     *   }
-     * })
+     * The invocationId is shown to the LLM so it can reference previous calls when building dependencies.
      *
-     * // Custom retry logic
-     * .withRetry({
-     *   shouldRetry: (error) => error.message.includes('429'),
-     * })
-     * ```
+     * @param gadget - Name of the gadget that was executed
+     * @param parameters - Parameters that were passed to the gadget
+     * @param result - Text result from the gadget execution
+     * @param invocationId - Invocation ID (shown to LLM so it can reference for dependencies)
+     * @param media - Optional media outputs from the gadget
+     * @param mediaIds - Optional IDs for the media outputs
+     * @param storedMedia - Optional stored media info including file paths
      */
-    withRetry(config: RetryConfig): this;
+    addGadgetCallResult(gadget: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[], storedMedia?: StoredMedia[]): this;
     /**
-     * Disable automatic retry for LLM API calls.
-     *
-     * By default, retry is enabled. Use this method to explicitly disable it.
-     *
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withoutRetry() // Disable automatic retry
-     * ```
+     * Format parameters as Block format with JSON Pointer paths.
+     * Uses the configured argPrefix for consistency with system prompt.
      */
-    withoutRetry(): this;
+    private formatBlockParameters;
+    build(): LLMMessage[];
+}
+
+/**
+ * Provider-agnostic reasoning effort level.
+ *
+ * Maps to provider-specific values:
+ * - **OpenAI**: "none"|"low"|"medium"|"high"|"xhigh"
+ * - **Anthropic**: budget_tokens (1024–32768)
+ * - **Gemini 3**: thinkingLevel "minimal"|"low"|"medium"|"high"
+ * - **Gemini 2.5**: thinkingBudget (0–24576)
+ * - **DeepSeek**: binary (enabled/disabled)
+ */
+type ReasoningEffort = "none" | "low" | "medium" | "high" | "maximum";
+/**
+ * Configuration for reasoning/thinking mode on supported models.
+ *
+ * When `enabled` is true, the provider will be instructed to use
+ * extended reasoning before generating its response.
+ */
+interface ReasoningConfig {
+    /** Whether reasoning is enabled */
+    enabled: boolean;
+    /** Reasoning effort level (default: "medium") */
+    effort?: ReasoningEffort;
+    /** Explicit token budget for thinking (Anthropic/Gemini 2.5, overrides effort) */
+    budgetTokens?: number;
+    /** Whether to surface thinking content in the stream (default: true) */
+    includeThinking?: boolean;
+    /** Enable interleaved thinking for multi-turn tool use (Anthropic only) */
+    interleaved?: boolean;
+}
+/**
+ * A chunk of thinking/reasoning content from a reasoning model.
+ *
+ * Emitted during streaming when a reasoning model produces thinking output.
+ * The `type` field distinguishes actual thinking from redacted content
+ * (e.g., Anthropic may redact thinking in certain scenarios).
+ */
+interface ThinkingChunk {
+    /** The thinking text content */
+    content: string;
+    /** Whether this is actual thinking or redacted content */
+    type: "thinking" | "redacted";
+    /** Verification signature (Anthropic/Gemini) */
+    signature?: string;
+}
+/**
+ * What content to include in the cache.
+ *
+ * - `"system"`: Cache only system prompt (lowest cost, highest reuse)
+ * - `"conversation"`: Cache system prompt + all conversation turns except the latest user message
+ */
+type CachingScope = "system" | "conversation";
+/**
+ * Configuration for context caching across providers.
+ *
+ * Context caching allows reusing previously computed key-value pairs across
+ * requests, reducing latency and cost for repeated context.
+ *
+ * Provider behavior:
+ * - **Anthropic**: Automatic ephemeral caching via `cache_control` markers (always-on by default).
+ *   Use `enabled: false` to disable markers and opt out of caching.
+ * - **Gemini**: Explicit cache lifecycle via `caches.create()`. Requires `scope` and `ttl`.
+ * - **OpenAI**: Server-side automatic caching (no-op, but respects the unified API).
+ */
+interface CachingConfig {
+    /** Whether context caching is enabled */
+    enabled: boolean;
     /**
-     * Configure proactive rate limiting to prevent rate limit errors.
-     *
-     * Set limits based on your API tier to automatically throttle requests
-     * before hitting provider limits. Works in conjunction with reactive
-     * retry/backoff for comprehensive rate limit handling.
-     *
-     * @param config - Rate limit configuration
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Gemini free tier limits
-     * .withRateLimits({
-     *   requestsPerMinute: 15,
-     *   tokensPerMinute: 1_000_000,
-     *   safetyMargin: 0.8,  // Start throttling at 80%
-     * })
-     *
-     * // OpenAI Tier 1 limits
-     * .withRateLimits({
-     *   requestsPerMinute: 500,
-     *   tokensPerMinute: 200_000,
-     * })
-     *
-     * // With daily limit (Gemini free tier)
-     * .withRateLimits({
-     *   requestsPerMinute: 15,
-     *   tokensPerDay: 1_500_000,
-     * })
-     * ```
+     * What to cache (Gemini only, default: "conversation").
+     * - `"system"`: Cache only system-derived messages
+     * - `"conversation"`: Cache system + all turns except the latest user message
      */
-    withRateLimits(config: RateLimitConfig): this;
+    scope?: CachingScope;
+    /** TTL for cache entries (Gemini only, format: "3600s", default: "3600s", min: "300s") */
+    ttl?: string;
+    /** Minimum token count for content to be eligible for caching (Gemini default: 32768) */
+    minTokenThreshold?: number;
+}
+interface LLMGenerationOptions {
+    model: string;
+    messages: LLMMessage[];
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    stopSequences?: string[];
+    responseFormat?: "text";
+    metadata?: Record<string, unknown>;
+    extra?: Record<string, unknown>;
     /**
-     * Set an abort signal for cancelling requests mid-flight.
-     *
-     * When the signal is aborted, the current LLM request will be cancelled
-     * and the agent loop will exit gracefully.
+     * Optional abort signal for cancelling the request mid-flight.
      *
-     * @param signal - AbortSignal from an AbortController
-     * @returns This builder for chaining
+     * When the signal is aborted, the provider will attempt to cancel
+     * the underlying HTTP request and the stream will terminate with
+     * an abort error. Use `isAbortError()` from `@/core/errors` to
+     * detect cancellation in error handling.
      *
      * @example
      * ```typescript
      * const controller = new AbortController();
      *
-     * // Cancel after 30 seconds
-     * setTimeout(() => controller.abort(), 30000);
+     * const stream = client.stream({
+     *   model: "claude-3-5-sonnet-20241022",
+     *   messages: [{ role: "user", content: "Tell me a long story" }],
+     *   signal: controller.signal,
+     * });
      *
-     * const agent = LLMist.createAgent()
-     *   .withModel("sonnet")
-     *   .withSignal(controller.signal)
-     *   .ask("Write a long story");
+     * // Cancel after 5 seconds
+     * setTimeout(() => controller.abort(), 5000);
      *
-     * // Or cancel on user action
-     * document.getElementById("cancel").onclick = () => controller.abort();
+     * try {
+     *   for await (const chunk of stream) {
+     *     process.stdout.write(chunk.text);
+     *   }
+     * } catch (error) {
+     *   if (isAbortError(error)) {
+     *     console.log("\nRequest was cancelled");
+     *   } else {
+     *     throw error;
+     *   }
+     * }
      * ```
      */
-    withSignal(signal: AbortSignal): this;
+    signal?: AbortSignal;
+    /** Reasoning/thinking configuration for reasoning-capable models */
+    reasoning?: ReasoningConfig;
+    /** Context caching configuration for supported providers */
+    caching?: CachingConfig;
+}
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    /** Number of input tokens served from cache (subset of inputTokens) */
+    cachedInputTokens?: number;
+    /** Number of input tokens written to cache (subset of inputTokens, Anthropic only) */
+    cacheCreationInputTokens?: number;
+    /** Number of reasoning/thinking tokens used (subset of outputTokens) */
+    reasoningTokens?: number;
+}
+interface LLMStreamChunk {
+    text: string;
     /**
-     * Enable reasoning/thinking mode for reasoning-capable models.
-     *
-     * Can be called with:
-     * - No args: enables reasoning at "medium" effort
-     * - A string effort level: `withReasoning("high")`
-     * - A full config object: `withReasoning({ enabled: true, budgetTokens: 10000 })`
-     *
-     * @param config - Optional effort level or full reasoning config
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Simple — medium effort
-     * LLMist.createAgent()
-     *   .withModel("o3")
-     *   .withReasoning()
-     *   .ask("Solve this logic puzzle...");
-     *
-     * // Explicit effort level
-     * LLMist.createAgent()
-     *   .withModel("anthropic:claude-4-opus")
-     *   .withReasoning("high")
-     *   .ask("Analyze this complex problem");
-     *
-     * // Full config with explicit token budget
-     * LLMist.createAgent()
-     *   .withModel("anthropic:claude-4-opus")
-     *   .withReasoning({ enabled: true, budgetTokens: 16000 })
-     *   .ask("Step through this proof");
-     * ```
+     * Indicates that the provider has finished producing output and includes the reason if available.
      */
-    withReasoning(config?: ReasoningConfig | ReasoningEffort): this;
+    finishReason?: string | null;
     /**
-     * Explicitly disable reasoning for this agent, even if the model supports it.
-     *
-     * By default, reasoning is auto-enabled at "medium" effort for models with
-     * `features.reasoning: true`. Use this to opt out.
-     *
-     * @returns This builder for chaining
+     * Token usage information, typically available in the final chunk when the stream completes.
      */
-    withoutReasoning(): this;
+    usage?: TokenUsage;
     /**
-     * Enable context caching for supported providers.
-     *
-     * Can be called with:
-     * - No args: enables caching with defaults (`{ enabled: true }`)
-     * - A full config object: `withCaching({ enabled: true, scope: "system", ttl: "7200s" })`
-     *
-     * Provider behavior:
-     * - **Anthropic**: Caching is always-on by default via `cache_control` markers.
-     *   Calling `withCaching()` explicitly is a no-op (it's already enabled).
-     * - **Gemini**: Creates an explicit cache via `caches.create()` for the configured scope.
-     * - **OpenAI**: Server-side automatic caching (no-op).
-     *
-     * @param config - Optional caching configuration
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Simple — enable with defaults
-     * LLMist.createAgent()
-     *   .withModel("gemini:gemini-2.5-flash")
-     *   .withCaching()
-     *   .ask("Analyze this large codebase...");
-     *
-     * // Cache only system prompt with longer TTL
-     * LLMist.createAgent()
-     *   .withModel("gemini:gemini-2.5-pro")
-     *   .withCaching({ enabled: true, scope: "system", ttl: "7200s" })
-     *   .ask("...");
-     * ```
+     * Provider specific payload emitted at the same time as the text chunk. This is useful for debugging and tests.
      */
-    withCaching(config?: CachingConfig): this;
+    rawEvent?: unknown;
+    /** Thinking/reasoning content from reasoning models */
+    thinking?: ThinkingChunk;
+}
+interface LLMStream extends AsyncIterable<LLMStreamChunk> {
+}
+type ProviderIdentifier = string;
+interface ModelDescriptor {
+    provider: string;
+    name: string;
+}
+declare class ModelIdentifierParser {
+    private readonly defaultProvider;
+    constructor(defaultProvider?: string);
+    parse(identifier: string): ModelDescriptor;
+}
+
+type GadgetClass = new (...args: unknown[]) => AbstractGadget;
+type GadgetOrClass = AbstractGadget | GadgetClass;
+declare class GadgetRegistry {
+    private readonly gadgets;
     /**
-     * Explicitly disable context caching.
-     *
-     * For Anthropic, this removes `cache_control` markers from requests,
-     * opting out of prompt caching entirely.
+     * Creates a registry from an array of gadget classes or instances,
+     * or an object mapping names to gadgets.
      *
-     * @returns This builder for chaining
+     * @param gadgets - Array of gadgets/classes or object with custom names
+     * @returns New GadgetRegistry with all gadgets registered
      *
      * @example
      * ```typescript
-     * // Disable Anthropic's automatic caching
-     * LLMist.createAgent()
-     *   .withModel("sonnet")
-     *   .withoutCaching()
-     *   .ask("...");
-     * ```
-     */
-    withoutCaching(): this;
-    /**
-     * Set subagent configuration overrides.
-     *
-     * Subagent gadgets (like BrowseWeb) can read these settings from ExecutionContext
-     * to inherit model and other options from the CLI configuration.
+     * // From array of classes
+     * const registry = GadgetRegistry.from([Calculator, Weather]);
      *
-     * @param config - Subagent configuration map keyed by gadget name
-     * @returns This builder for chaining
+     * // From array of instances
+     * const registry = GadgetRegistry.from([new Calculator(), new Weather()]);
      *
-     * @example
-     * ```typescript
-     * .withSubagentConfig({
-     *   BrowseWeb: { model: "inherit", maxIterations: 20, headless: true },
-     *   CodeAnalyzer: { model: "sonnet", maxIterations: 10 }
-     * })
+     * // From object with custom names
+     * const registry = GadgetRegistry.from({
+     *   calc: Calculator,
+     *   weather: new Weather({ apiKey: "..." })
+     * });
      * ```
      */
-    withSubagentConfig(config: SubagentConfigMap): this;
+    static from(gadgets: GadgetOrClass[] | Record<string, GadgetOrClass>): GadgetRegistry;
     /**
-     * Share parent agent's ExecutionTree for unified event visibility.
-     *
-     * When building a subagent inside a gadget, call this method to share the
-     * parent's ExecutionTree. This is the **single source of truth** for all
-     * execution events, enabling:
-     *
-     * - **Unified cost tracking** - All nested agent costs aggregate automatically
-     * - **Real-time visibility** - Parent's `tree.onAll()` subscribers see all events
-     * - **Depth tracking** - Events have correct `depth` (1 for child, 2 for grandchild, etc.)
-     * - **Parent linking** - Events have `parentId` pointing to spawning gadget
-     * - **Media aggregation** - Use `tree.getSubtreeMedia(nodeId)` after completion
-     *
-     * **Signal Forwarding** - When parent context includes a signal, it's automatically
-     * forwarded to the subagent for proper cancellation propagation.
-     *
-     * **Logger Inheritance** - When parent context includes a logger, it's inherited
-     * by the subagent for consistent structured logging.
+     * Registers multiple gadgets at once from an array.
      *
-     * @param ctx - ExecutionContext passed to the gadget's execute() method
-     * @param depth - Nesting depth (default: 1 for direct child)
-     * @returns This builder for chaining
+     * @param gadgets - Array of gadget instances or classes
+     * @returns This registry for chaining
      *
      * @example
      * ```typescript
-     * // In a subagent gadget like BrowseWeb:
-     * execute: async (params, ctx) => {
-     *   const agent = new AgentBuilder(client)
-     *     .withModel(model)
-     *     .withGadgets(Navigate, Click, Screenshot)
-     *     .withParentContext(ctx)  // <-- Shares parent's tree
-     *     .ask(params.task);
-     *
-     *   for await (const event of agent.run()) {
-     *     // Events automatically flow through shared tree
-     *     if (event.type === "text") {
-     *       result = event.content;
-     *     }
-     *   }
-     *
-     *   // After subagent completes, access aggregated data:
-     *   const totalCost = ctx.tree?.getSubtreeCost(ctx.nodeId!);
-     *   const allMedia = ctx.tree?.getSubtreeMedia(ctx.nodeId!);
-     * }
+     * registry.registerMany([Calculator, Weather, Email]);
+     * registry.registerMany([new Calculator(), new Weather()]);
      * ```
      */
+    registerMany(gadgets: GadgetOrClass[]): this;
+    register(name: string, gadget: AbstractGadget): void;
+    registerByClass(gadget: AbstractGadget): void;
+    get(name: string): AbstractGadget | undefined;
+    has(name: string): boolean;
+    getNames(): string[];
+    getAll(): AbstractGadget[];
+    unregister(name: string): boolean;
+    clear(): void;
+}
+
+/**
+ * Context available to trailing message functions.
+ * Provides iteration information for dynamic message generation.
+ */
+type TrailingMessageContext = Pick<LLMCallControllerContext, "iteration" | "maxIterations" | "budget" | "totalCost">;
+/**
+ * Trailing message can be a static string or a function that generates the message.
+ * The function receives context about the current iteration.
+ */
+type TrailingMessage = string | ((ctx: TrailingMessageContext) => string);
+
+/**
+ * Message for conversation history.
+ * User messages can be text (string) or multimodal (ContentPart[]).
+ */
+type HistoryMessage = {
+    user: string | ContentPart[];
+} | {
+    assistant: string;
+} | {
+    system: string;
+};
+
+/**
+ * Event handler sugar for cleaner event processing.
+ *
+ * Instead of verbose if/else chains, use named handlers
+ * for each event type.
+ *
+ * @example
+ * ```typescript
+ * await agent.runWith({
+ *   onText: (content) => console.log("LLM:", content),
+ *   onGadgetResult: (result) => console.log("Result:", result.result),
+ * });
+ * ```
+ */
+
+/**
+ * Named event handlers for different event types.
+ */
+interface EventHandlers {
+    /** Called when text is generated by the LLM */
+    onText?: (content: string) => void | Promise<void>;
+    /** Called when a gadget is about to be executed */
+    onGadgetCall?: (call: {
+        gadgetName: string;
+        invocationId: string;
+        parameters?: Record<string, unknown>;
+        parametersRaw: string;
+        dependencies: string[];
+    }) => void | Promise<void>;
+    /** Called when a gadget execution completes */
+    onGadgetResult?: (result: {
+        gadgetName: string;
+        invocationId: string;
+        result?: string;
+        error?: string;
+        parameters: Record<string, unknown>;
+    }) => void | Promise<void>;
+    /** Called when human input is required */
+    onHumanInputRequired?: (data: {
+        question: string;
+        gadgetName: string;
+    }) => void | Promise<void>;
+    /** Called for any other event type */
+    onOther?: (event: StreamEvent) => void | Promise<void>;
+}
+/**
+ * Helper to run an agent with named event handlers.
+ *
+ * @param agentGenerator - Agent's run() async generator
+ * @param handlers - Named event handlers
+ *
+ * @example
+ * ```typescript
+ * await runWithHandlers(agent.run(), {
+ *   onText: (text) => console.log("LLM:", text),
+ *   onGadgetResult: (result) => console.log("Result:", result.result),
+ * });
+ * ```
+ */
+declare function runWithHandlers(agentGenerator: AsyncGenerator<StreamEvent>, handlers: EventHandlers): Promise<void>;
+/**
+ * Helper to collect events by type.
+ *
+ * @param agentGenerator - Agent's run() async generator
+ * @param collect - Object specifying which event types to collect
+ * @returns Object with collected events
+ *
+ * @example
+ * ```typescript
+ * const { text, gadgetResults } = await collectEvents(agent.run(), {
+ *   text: true,
+ *   gadgetResults: true,
+ * });
+ *
+ * console.log("Full response:", text.join(""));
+ * console.log("Gadget calls:", gadgetResults.length);
+ * ```
+ */
+declare function collectEvents(agentGenerator: AsyncGenerator<StreamEvent>, collect: {
+    text?: boolean;
+    gadgetCalls?: boolean;
+    gadgetResults?: boolean;
+}): Promise<{
+    text: string[];
+    gadgetCalls: Array<{
+        gadgetName: string;
+        parameters: Record<string, unknown>;
+    }>;
+    gadgetResults: Array<{
+        gadgetName: string;
+        result?: string;
+        error?: string;
+        parameters: Record<string, unknown>;
+    }>;
+}>;
+/**
+ * Helper to collect only text from an agent run.
+ *
+ * @param agentGenerator - Agent's run() async generator
+ * @returns Combined text response
+ *
+ * @example
+ * ```typescript
+ * const response = await collectText(agent.run());
+ * console.log(response);
+ * ```
+ */
+declare function collectText(agentGenerator: AsyncGenerator<StreamEvent>): Promise<string>;
+
+/**
+ * Fluent builder for creating agents with delightful DX.
+ */
+
+/**
+ * Fluent builder for creating agents.
+ *
+ * Provides a chainable API for configuring and creating agents,
+ * making the code more expressive and easier to read.
+ */
+declare class AgentBuilder {
+    private core;
+    private gadgets;
+    private retry;
+    private subagents;
+    private policies;
+    constructor(client?: LLMist);
+    /** Set the model to use. Supports aliases like "sonnet", "flash". */
+    withModel(model: string): this;
+    /** Set the system prompt. */
+    withSystem(prompt: string): this;
+    /** Set the temperature (0-1). */
+    withTemperature(temperature: number): this;
+    /** Set maximum iterations. */
+    withMaxIterations(max: number): this;
+    /** Set the budget limit in USD. */
+    withBudget(amountUSD: number): this;
+    /** Set logger instance. */
+    withLogger(logger: Logger<ILogObj>): this;
+    /** Add hooks for agent lifecycle events. */
+    withHooks(hooks: AgentHooks): this;
+    /** Configure custom prompts for gadget system messages. */
+    withPromptTemplateConfig(config: PromptTemplateConfig): this;
+    /** Add gadgets (classes or instances). */
+    withGadgets(...gadgets: GadgetOrClass[]): this;
+    /** Add conversation history messages. */
+    withHistory(messages: HistoryMessage[]): this;
+    /** Add a single message to the conversation history. */
+    addMessage(message: HistoryMessage): this;
+    /** Clear any previously set conversation history. */
+    clearHistory(): this;
+    /** Continue conversation from a previous agent's history. */
+    continueFrom(agent: Agent): this;
+    /** Set the human input handler for interactive conversations. */
+    onHumanInput(handler: (question: string) => Promise<string>): this;
+    /** Set custom gadget marker prefix. */
+    withGadgetStartPrefix(prefix: string): this;
+    /** Set custom gadget marker suffix. */
+    withGadgetEndPrefix(suffix: string): this;
+    /** Set custom argument prefix for block format parameters. */
+    withGadgetArgPrefix(prefix: string): this;
+    /** Set the text-only handler strategy. */
+    withTextOnlyHandler(handler: TextOnlyHandler): this;
+    /** Set the handler for text content that appears alongside gadget calls. */
+    withTextWithGadgetsHandler(handler: {
+        gadgetName: string;
+        parameterMapping: (text: string) => Record<string, unknown>;
+        resultMapping?: (text: string) => string;
+    }): this;
+    /** Set default timeout for gadget execution. */
+    withDefaultGadgetTimeout(timeoutMs: number): this;
+    /** Set the gadget execution mode ('parallel' or 'sequential'). */
+    withGadgetExecutionMode(mode: GadgetExecutionMode): this;
+    /** Set the maximum number of gadgets to execute per LLM response. */
+    withMaxGadgetsPerResponse(max: number): this;
+    /** Enable or disable gadget output limiting. */
+    withGadgetOutputLimit(enabled: boolean): this;
+    /** Set the maximum gadget output as a percentage of the context window. */
+    withGadgetOutputLimitPercent(percent: number): this;
+    /** Configure context compaction. */
+    withCompaction(config: CompactionConfig): this;
+    /** Disable context compaction. */
+    withoutCompaction(): this;
+    /** Configure retry behavior for LLM API calls. */
+    withRetry(config: RetryConfig): this;
+    /** Disable automatic retry for LLM API calls. */
+    withoutRetry(): this;
+    /** Configure proactive rate limiting to prevent rate limit errors. */
+    withRateLimits(config: RateLimitConfig): this;
+    /** Set an abort signal for cancelling requests mid-flight. */
+    withSignal(signal: AbortSignal): this;
+    /** Enable reasoning/thinking mode for reasoning-capable models. */
+    withReasoning(config?: ReasoningConfig | ReasoningEffort): this;
+    /** Explicitly disable reasoning for this agent. */
+    withoutReasoning(): this;
+    /** Enable context caching for supported providers. */
+    withCaching(config?: CachingConfig): this;
+    /** Explicitly disable context caching. */
+    withoutCaching(): this;
+    /** Set subagent configuration overrides. */
+    withSubagentConfig(config: SubagentConfigMap): this;
+    /** Share parent agent's ExecutionTree for unified event visibility. */
     withParentContext(ctx: ExecutionContext, depth?: number): this;
-    /**
-     * Add an ephemeral trailing message that appears at the end of each LLM request.
-     *
-     * The message is NOT persisted to conversation history - it only appears in the
-     * current LLM call. This is useful for injecting context-specific instructions
-     * or reminders without polluting the conversation history.
-     *
-     * @param message - Static string or function that generates the message
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * // Static message
-     * .withTrailingMessage("Always respond in JSON format.")
-     *
-     * // Dynamic message based on iteration
-     * .withTrailingMessage((ctx) =>
-     *   `[Iteration ${ctx.iteration}/${ctx.maxIterations}] Stay focused on the task.`
-     * )
-     * ```
-     */
+    /** Add an ephemeral trailing message that appears at the end of each LLM request. */
     withTrailingMessage(message: TrailingMessage): this;
-    /**
-     * Add a synthetic gadget call to the conversation history.
-     *
-     * This is useful for in-context learning - showing the LLM what "past self"
-     * did correctly so it mimics the pattern. The call is formatted with proper
-     * markers and parameter format, including the invocation ID so the LLM can
-     * reference previous calls when building dependencies.
-     *
-     * @param gadgetName - Name of the gadget
-     * @param parameters - Parameters passed to the gadget
-     * @param result - Result returned by the gadget
-     * @param invocationId - Invocation ID (shown to LLM so it can reference for dependencies)
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withSyntheticGadgetCall(
-     *   'TellUser',
-     *   {
-     *     message: '👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
-     *     done: false,
-     *     type: 'info'
-     *   },
-     *   'ℹ️  👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
-     *   'gc_1'
-     * )
-     * ```
-     */
+    /** Add a synthetic gadget call to the conversation history for in-context learning. */
     withSyntheticGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string): this;
-    /**
-     * Compose the final hooks, including trailing message injection if configured.
-     *
-     * Note: Subagent event visibility is now handled entirely by the ExecutionTree.
-     * When a subagent uses withParentContext(ctx), it shares the parent's tree,
-     * and all events are automatically visible to tree subscribers (like the TUI).
-     *
-     * Environment-based file logging (via LLMIST_LOG_RAW_DIRECTORY) is automatically
-     * injected if the env var is set. User-provided hooks take precedence.
-     */
     private composeHooks;
-    /**
-     * Format parameters as block format with JSON Pointer paths.
-     */
-    private formatBlockParameters;
-    /**
-     * Build and create the agent with the given user prompt.
-     * Returns the Agent instance ready to run.
-     *
-     * @param userPrompt - User's question or request
-     * @returns Configured Agent instance
-     *
-     * @example
-     * ```typescript
-     * const agent = await LLMist.createAgent()
-     *   .withModel("sonnet")
-     *   .withGadgets(Calculator)
-     *   .ask("What is 2+2?");
-     *
-     * for await (const event of agent.run()) {
-     *   // handle events
-     * }
-     * ```
-     */
-    /**
-     * Build AgentOptions with the given user prompt.
-     * Centralizes options construction for ask(), askWithImage(), and askWithContent().
-     */
     private buildAgentOptions;
+    /** Create agent and start with a user prompt. */
     ask(userPrompt: string): Agent;
-    /**
-     * Build and create the agent with a multimodal user prompt (text + image).
-     * Returns the Agent instance ready to run.
-     *
-     * @param textPrompt - Text prompt describing what to do with the image
-     * @param imageData - Image data (Buffer, Uint8Array, or base64 string)
-     * @param mimeType - Optional MIME type (auto-detected if not provided)
-     * @returns Configured Agent instance
-     *
-     * @example
-     * ```typescript
-     * const agent = LLMist.createAgent()
-     *   .withModel("gpt-4o")
-     *   .withSystem("You analyze images")
-     *   .askWithImage(
-     *     "What's in this image?",
-     *     await fs.readFile("photo.jpg")
-     *   );
-     *
-     * for await (const event of agent.run()) {
-     *   // handle events
-     * }
-     * ```
-     */
+    /** Create agent with multimodal input (text + image). */
     askWithImage(textPrompt: string, imageData: Buffer | Uint8Array | string, mimeType?: ImageMimeType): Agent;
-    /**
-     * Build and return an Agent configured with multimodal content.
-     * More flexible than askWithImage - accepts any combination of content parts.
-     *
-     * @param content - Array of content parts (text, images, audio)
-     * @returns A configured Agent ready for execution
-     *
-     * @example
-     * ```typescript
-     * import { text, imageFromBuffer, audioFromBuffer } from "llmist";
-     *
-     * const agent = LLMist.createAgent()
-     *   .withModel("gemini:gemini-2.5-flash")
-     *   .askWithContent([
-     *     text("Describe this image and transcribe the audio:"),
-     *     imageFromBuffer(imageData),
-     *     audioFromBuffer(audioData),
-     *   ]);
-     *
-     * for await (const event of agent.run()) {
-     *   // handle events
-     * }
-     * ```
-     */
+    /** Create agent with flexible multimodal content parts. */
     askWithContent(content: ContentPart[]): Agent;
-    /**
-     * Build, run, and collect only the text response.
-     * Convenient for simple queries where you just want the final answer.
-     *
-     * @param userPrompt - User's question or request
-     * @returns Promise resolving to the complete text response
-     *
-     * @example
-     * ```typescript
-     * const answer = await LLMist.createAgent()
-     *   .withModel("gpt4-mini")
-     *   .withGadgets(Calculator)
-     *   .askAndCollect("What is 42 * 7?");
-     *
-     * console.log(answer); // "294"
-     * ```
-     */
+    /** Run agent and collect text response. */
     askAndCollect(userPrompt: string): Promise<string>;
-    /**
-     * Build and run with event handlers.
-     * Combines agent creation and event handling in one call.
-     *
-     * @param userPrompt - User's question or request
-     * @param handlers - Event handlers
-     *
-     * @example
-     * ```typescript
-     * await LLMist.createAgent()
-     *   .withModel("sonnet")
-     *   .withGadgets(Calculator)
-     *   .askWith("What is 2+2?", {
-     *     onText: (text) => console.log("LLM:", text),
-     *     onGadgetResult: (result) => console.log("Result:", result.result),
-     *   });
-     * ```
-     */
+    /** Run agent with event handlers. */
     askWith(userPrompt: string, handlers: EventHandlers): Promise<void>;
-    /**
-     * Build the agent without a user prompt.
-     *
-     * Returns an Agent instance that can be inspected (e.g., check registered gadgets)
-     * but cannot be run without first calling .ask(prompt).
-     *
-     * This is useful for:
-     * - Testing: Inspect the registry, configuration, etc.
-     * - Advanced use cases: Build agent configuration separately from execution
-     *
-     * @returns Configured Agent instance (without user prompt)
-     *
-     * @example
-     * ```typescript
-     * // Build agent for inspection
-     * const agent = new AgentBuilder()
-     *   .withModel("sonnet")
-     *   .withGadgets(Calculator, Weather)
-     *   .build();
-     *
-     * // Inspect registered gadgets
-     * console.log(agent.getRegistry().getNames()); // ['Calculator', 'Weather']
-     *
-     * // Note: Calling agent.run() will throw an error
-     * // Use .ask(prompt) instead if you want to run the agent
-     * ```
-     */
+    /** Build agent without a prompt (useful for testing/inspection). */
     build(): Agent;
 }
 
@@ -6244,24 +5447,167 @@ interface IConversationManager {
      * Used by compaction to update history after compression.
      * @param newHistory - The compacted history messages to replace with
      */
-    replaceHistory(newHistory: LLMMessage[]): void;
+    replaceHistory(newHistory: LLMMessage[]): void;
+    /**
+     * Gets full conversation history including initial messages and runtime history.
+     * Used for REPL session continuation - returns everything except base (system) messages.
+     * This combines:
+     * - initialMessages: History from previous sessions (set via withHistory())
+     * - historyBuilder: Messages from the current session
+     */
+    getConversationHistory(): LLMMessage[];
+}
+
+/**
+ * Storage for large gadget outputs that exceed the configured limit.
+ *
+ * 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.
+ */
+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"
+ *
+ * const stored = store.get(id);
+ * console.log(stored?.lineCount); // 4200
+ * ```
+ */
+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;
+}
+
+/**
+ * OutputLimitManager - Manages gadget output size limiting.
+ *
+ * Calculates character limits from model context windows, registers
+ * GadgetOutputViewer when enabled, and chains the output limiter
+ * interceptor with user-provided hooks.
+ */
+
+/**
+ * Configuration for output limiting.
+ */
+interface OutputLimitConfig {
+    /** Whether output limiting is enabled (default: true) */
+    enabled?: boolean;
+    /** Max gadget output as % of model context window (default: 15) */
+    limitPercent?: number;
+}
+
+/**
+ * Agent: Lean orchestrator using the clean hooks architecture.
+ *
+ * The Agent delegates ALL stream processing and hook coordination to StreamProcessor,
+ * making it a simple loop orchestrator with clear responsibilities.
+ */
+
+/**
+ * Configuration for the execution tree context (shared tree model with subagents).
+ */
+interface TreeConfig {
+    /**
+     * Shared execution tree for tracking all LLM calls and gadget executions.
+     * If provided (by a parent subagent), nodes are added to this tree.
+     * If not provided, the Agent creates its own tree.
+     */
+    tree?: ExecutionTree;
+    /**
+     * Parent node ID in the tree (when this agent is a subagent).
+     * Used to set parentId on all nodes created by this agent.
+     */
+    parentNodeId?: NodeId;
+    /**
+     * Base depth for nodes created by this agent.
+     * Root agents use 0; subagents use (parentDepth + 1).
+     */
+    baseDepth?: number;
     /**
-     * Gets full conversation history including initial messages and runtime history.
-     * Used for REPL session continuation - returns everything except base (system) messages.
-     * This combines:
-     * - initialMessages: History from previous sessions (set via withHistory())
-     * - historyBuilder: Messages from the current session
+     * Parent agent's observer hooks for subagent visibility.
+     *
+     * When a subagent is created with withParentContext(ctx), these observers
+     * are also called for gadget events (in addition to the subagent's own hooks),
+     * enabling the parent to observe subagent gadget activity.
      */
-    getConversationHistory(): LLMMessage[];
+    parentObservers?: Observers;
 }
-
 /**
- * Agent: Lean orchestrator using the clean hooks architecture.
- *
- * The Agent delegates ALL stream processing and hook coordination to StreamProcessor,
- * making it a simple loop orchestrator with clear responsibilities.
+ * Configuration for custom gadget block format prefixes.
  */
-
+interface PrefixConfig {
+    /** Custom gadget start prefix */
+    gadgetStartPrefix?: string;
+    /** Custom gadget end prefix */
+    gadgetEndPrefix?: string;
+    /** Custom gadget argument prefix for block format parameters */
+    gadgetArgPrefix?: string;
+}
 /**
  * Configuration options for the Agent.
  */
@@ -6288,12 +5634,10 @@ interface AgentOptions {
     hooks?: AgentHooks;
     /** Callback for requesting human input during execution */
     requestHumanInput?: (question: string) => Promise<string>;
-    /** Custom gadget start prefix */
-    gadgetStartPrefix?: string;
-    /** Custom gadget end prefix */
-    gadgetEndPrefix?: string;
-    /** Custom gadget argument prefix for block format parameters */
-    gadgetArgPrefix?: string;
+    /**
+     * Gadget prefix configuration (start/end/arg prefixes for block format).
+     */
+    prefixConfig?: PrefixConfig;
     /** Initial messages. User messages support multimodal content. */
     initialMessages?: Array<{
         role: "system" | "user" | "assistant";
@@ -6319,10 +5663,10 @@ interface AgentOptions {
     gadgetExecutionMode?: GadgetExecutionMode;
     /** Custom prompt configuration for gadget system prompts */
     promptConfig?: PromptTemplateConfig;
-    /** Enable gadget output limiting (default: true) */
-    gadgetOutputLimit?: boolean;
-    /** Max gadget output as % of model context window (default: 15) */
-    gadgetOutputLimitPercent?: number;
+    /**
+     * Gadget output limit configuration.
+     */
+    outputLimitConfig?: OutputLimitConfig;
     /** Context compaction configuration (enabled by default) */
     compactionConfig?: CompactionConfig;
     /** Retry configuration for LLM API calls (enabled by default) */
@@ -6340,29 +5684,9 @@ interface AgentOptions {
     /** Maximum gadgets to execute per LLM response (0 = unlimited) */
     maxGadgetsPerResponse?: number;
     /**
-     * Shared execution tree for tracking all LLM calls and gadget executions.
-     * If provided (by a parent subagent), nodes are added to this tree.
-     * If not provided, the Agent creates its own tree.
-     */
-    parentTree?: ExecutionTree;
-    /**
-     * Parent node ID in the tree (when this agent is a subagent).
-     * Used to set parentId on all nodes created by this agent.
-     */
-    parentNodeId?: NodeId;
-    /**
-     * Base depth for nodes created by this agent.
-     * Root agents use 0; subagents use (parentDepth + 1).
-     */
-    baseDepth?: number;
-    /**
-     * Parent agent's observer hooks for subagent visibility.
-     *
-     * When a subagent is created with withParentContext(ctx), these observers
-     * are also called for gadget events (in addition to the subagent's own hooks),
-     * enabling the parent to observe subagent gadget activity.
+     * Execution tree configuration (shared tree model with subagents).
      */
-    parentObservers?: Observers;
+    treeConfig?: TreeConfig;
     /**
      * Shared rate limit tracker from parent agent.
      *
@@ -6403,19 +5727,11 @@ declare class Agent {
     private readonly hooks;
     private readonly conversation;
     private readonly registry;
-    private readonly gadgetStartPrefix?;
-    private readonly gadgetEndPrefix?;
-    private readonly gadgetArgPrefix?;
-    private readonly requestHumanInput?;
-    private readonly textOnlyHandler;
-    private readonly textWithGadgetsHandler?;
-    private readonly defaultGadgetTimeoutMs?;
-    private readonly gadgetExecutionMode;
+    private readonly prefixConfig?;
+    private readonly conversationUpdater;
     private readonly defaultMaxTokens?;
     private hasUserPrompt;
-    private readonly outputStore;
-    private readonly outputLimitEnabled;
-    private readonly outputLimitCharLimit;
+    private readonly outputLimitManager;
     private readonly compactionManager?;
     private readonly mediaStore;
     private readonly signal?;
@@ -6423,17 +5739,13 @@ declare class Agent {
     private readonly caching?;
     private readonly retryConfig;
     private readonly rateLimitTracker?;
-    private readonly agentContextConfig;
-    private readonly subagentConfig?;
-    private readonly maxGadgetsPerResponse;
-    private syntheticInvocationCounter;
     private readonly completedInvocationIds;
     private readonly failedInvocationIds;
     private readonly pendingUserMessages;
     private readonly tree;
     private readonly parentNodeId;
-    private readonly baseDepth;
-    private readonly parentObservers?;
+    private readonly streamProcessorFactory;
+    private readonly llmCallLifecycle;
     /**
      * Creates a new Agent instance.
      * @internal This constructor is private. Use LLMist.createAgent() or AgentBuilder instead.
@@ -6614,6 +5926,16 @@ declare class Agent {
      * @throws {Error} If no user prompt was provided (when using build() without ask())
      */
     run(): AsyncGenerator<StreamEvent>;
+    /**
+     * Execute a single LLM call attempt with full retry orchestration.
+     *
+     * Delegates all retry logic to RetryOrchestrator, then propagates the accumulated
+     * invocation IDs back to the agent's cross-iteration tracking sets.
+     *
+     * Yields stream events in real-time and returns the final stream completion metadata
+     * along with accumulated tracking state from the final successful attempt only.
+     */
+    private executeWithRetry;
     /**
      * Create LLM stream with proactive rate limit protection.
      *
@@ -6622,30 +5944,20 @@ declare class Agent {
      */
     private createStream;
     /**
-     * Simple sleep utility for rate limit delays.
-     */
-    private sleep;
-    /**
-     * Handle LLM error through controller.
-     */
-    private handleLLMError;
-    /**
-     * Handle text-only response (no gadgets called).
+     * Factory method for constructing a StreamProcessor for a given iteration.
+     *
+     * Delegates to StreamProcessorFactory, which encapsulates all static
+     * StreamProcessor configuration. Cross-iteration mutable state is passed here.
      */
-    private handleTextOnlyResponse;
+    private createStreamProcessor;
     /**
-     * Safely execute an observer, catching and logging any errors.
+     * Simple sleep utility for rate limit delays.
      */
-    private safeObserve;
+    private sleep;
     /**
      * Resolve max tokens from model catalog.
      */
     private resolveMaxTokensFromCatalog;
-    /**
-     * Chain the output limiter interceptor with user-provided hooks.
-     * The limiter runs first, then chains to any user interceptor.
-     */
-    private chainOutputLimiterWithUserHooks;
     /**
      * Check abort signal and notify observers if aborted.
      * @returns true if agent should terminate
@@ -6656,43 +5968,6 @@ declare class Agent {
      * @returns compaction stream event if compaction occurred, null otherwise
      */
     private checkAndPerformCompaction;
-    /**
-     * Resolve reasoning configuration with auto-enable logic.
-     *
-     * Priority: explicit config > auto-enable for reasoning models > undefined
-     * When a model has `features.reasoning: true` and no explicit config is set,
-     * reasoning is automatically enabled at "medium" effort.
-     */
-    private resolveReasoningConfig;
-    /**
-     * Resolve caching configuration.
-     *
-     * Priority: explicit config > default enabled (preserves Anthropic's existing behavior)
-     * Default is `{ enabled: true }` which means:
-     * - Anthropic: `cache_control` markers are added (existing behavior preserved)
-     * - Gemini: Cache manager is consulted but skips if no explicit config was set
-     * - OpenAI: No-op (server-side automatic)
-     */
-    private resolveCachingConfig;
-    /**
-     * Prepare LLM call options, create tree node, and process beforeLLMCall controller.
-     * @returns options, node ID, and optional skipWithSynthetic response if controller wants to skip
-     */
-    private prepareLLMCall;
-    /**
-     * Calculate cost and complete LLM call in execution tree.
-     * Also records usage to rate limit tracker for proactive throttling.
-     */
-    private completeLLMCallInTree;
-    /**
-     * Process afterLLMCall controller and return modified final message.
-     */
-    private processAfterLLMCallController;
-    /**
-     * Update conversation history with gadget results or text-only response.
-     * @returns true if loop should break (text-only handler requested termination)
-     */
-    private updateConversationWithResults;
     /**
      * Run agent with named event handlers (syntactic sugar).
      *
@@ -7143,6 +6418,8 @@ declare class HookPresets {
     /**
      * Tracks cumulative token usage across all LLM calls.
      *
+     * @public
+     *
      * **Output:**
      * - Per-call token count with 📊 emoji
      * - Cumulative total across all calls
@@ -7320,6 +6597,8 @@ declare class HookPresets {
     /**
      * Logs detailed error information for debugging and troubleshooting.
      *
+     * @public
+     *
      * **Output:**
      * - LLM errors with ❌ emoji, including model and recovery status
      * - Gadget errors with full context (parameters, error message)
@@ -7381,6 +6660,8 @@ declare class HookPresets {
     /**
      * Tracks context compaction events.
      *
+     * @public
+     *
      * **Output:**
      * - Compaction events with 🗜️ emoji
      * - Strategy name, tokens before/after, and savings
@@ -7474,6 +6755,8 @@ declare class HookPresets {
     /**
      * Returns empty hook configuration for clean output without any logging.
      *
+     * @public
+     *
      * **Output:**
      * - None. Returns {} (empty object).
      *
@@ -7600,6 +6883,8 @@ declare class HookPresets {
     /**
      * Composite preset combining logging, timing, tokenTracking, and errorLogging.
      *
+     * @public
+     *
      * This is the recommended preset for development and initial production deployments,
      * providing comprehensive observability with a single method call.
      *
@@ -7842,91 +7127,6 @@ declare class ConversationManager implements IConversationManager {
     getConversationHistory(): LLMMessage[];
 }
 
-/**
- * Storage for large gadget outputs that exceed the configured limit.
- *
- * 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.
- */
-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"
- *
- * const stored = store.get(id);
- * console.log(stored?.lineCount); // 4200
- * ```
- */
-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;
-}
-
 /**
  * LLM Assistance Hints System
  *
@@ -8105,6 +7305,18 @@ declare function createHints(config: HintsConfig): AgentHooks;
  *
  * Replaces the complex wiring between Agent, ResponseProcessor, and GadgetRuntime.
  * Owns ALL stream processing and hook coordination with a clean, predictable flow.
+ *
+ * After refactoring, StreamProcessor is a thin orchestrator (~300 lines) that:
+ * - Iterates over raw LLM stream chunks
+ * - Applies raw-chunk and text-chunk interceptors
+ * - Delegates gadget dispatch to GadgetDispatcher
+ * - Yields events in real-time
+ * - Applies the final assistant-message interceptor
+ *
+ * Extracted classes:
+ * - GadgetLimitGuard     — maxGadgetsPerResponse enforcement
+ * - GadgetHookLifecycle  — full hook sequence for a single gadget
+ * - GadgetDispatcher     — dispatch decision tree + concurrency + dependency
  */
 
 /**
@@ -8172,6 +7384,11 @@ interface StreamProcessorOptions {
 }
 /**
  * Result of stream processing.
+ *
+ * @deprecated StreamProcessor.process() is now an async generator that yields
+ * StreamEvent items directly. Use StreamCompletionEvent (the final yielded event)
+ * to obtain the metadata formerly returned in this type. This interface is retained
+ * for backward compatibility but is not used internally.
  */
 interface StreamProcessingResult {
     /** All emitted events */
@@ -8190,21 +7407,14 @@ interface StreamProcessingResult {
     finalMessage: string;
 }
 /**
- * StreamProcessor: Coordinates all stream processing and hook execution.
+ * StreamProcessor: Thin orchestrator for stream processing and hook coordination.
  *
  * 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
+ * 5. If gadget found → delegate to GadgetDispatcher
  * 6. If text chunk:
  *    a. Interceptor: interceptTextChunk (transform display text)
  *    b. Yield to user
@@ -8213,43 +7423,16 @@ interface StreamProcessingResult {
  */
 declare class StreamProcessor {
     private readonly iteration;
-    private readonly registry;
     private readonly hooks;
     private readonly logger;
     private readonly parser;
-    private readonly executor;
     private readonly tree?;
-    private readonly parentNodeId;
-    private readonly baseDepth;
-    private readonly gadgetExecutionMode;
     private responseText;
-    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;
-    /** Promises for independent gadgets currently executing (fire-and-forget) */
-    private inFlightExecutions;
+    private readonly dependencyResolver;
     /** Queue of completed gadget results ready to be yielded (for real-time streaming) */
     private completedResultsQueue;
-    /** Subagent configuration map for checking maxConcurrent limits */
-    private readonly subagentConfig?;
-    /** Track active execution count per gadget name */
-    private activeCountByGadget;
-    /** Queue of gadgets waiting for a concurrency slot (per gadget name) */
-    private concurrencyQueue;
-    /** Queue of exclusive gadgets deferred until in-flight gadgets complete */
-    private exclusiveQueue;
-    /** Invocation IDs completed in previous iterations (read-only reference from Agent) */
-    private readonly priorCompletedInvocations;
-    /** Invocation IDs that failed in previous iterations (read-only reference from Agent) */
-    private readonly priorFailedInvocations;
-    private readonly parentObservers?;
-    private readonly maxGadgetsPerResponse;
-    private gadgetStartedCount;
-    private limitExceeded;
+    private readonly dispatcher;
+    private readonly limitGuard;
     constructor(options: StreamProcessorOptions);
     /**
      * Process an LLM stream and yield events in real-time.
@@ -8270,45 +7453,6 @@ declare class StreamProcessor {
      * Process a text event through interceptors.
      */
     private processTextEvent;
-    /**
-     * Process a gadget call, yielding events in real-time.
-     *
-     * Yields gadget_call event IMMEDIATELY when parsed (before execution),
-     * enabling real-time UI feedback.
-     */
-    private processGadgetCallGenerator;
-    /**
-     * Get the effective concurrency limit for a gadget.
-     * Uses "most restrictive wins" strategy: the lowest non-zero value from
-     * external config (SubagentConfig) and gadget's intrinsic maxConcurrent.
-     *
-     * This ensures gadget authors can set safety floors (e.g., maxConcurrent: 1
-     * for file writers) that cannot be weakened by external configuration.
-     *
-     * @returns 0 if unlimited, otherwise the effective limit
-     */
-    private getConcurrencyLimit;
-    /**
-     * Start a gadget execution with concurrency tracking.
-     * Increments active count, starts execution, and schedules queue processing on completion.
-     */
-    private startGadgetWithConcurrencyTracking;
-    /**
-     * Process the next queued gadget for a given gadget name if a slot is available.
-     */
-    private processQueuedGadget;
-    /**
-     * Execute a gadget through the full hook lifecycle and yield events.
-     * Handles parameter interception, before/after controllers, observers,
-     * execution, result interception, and tree tracking.
-     */
-    private executeGadgetGenerator;
-    /**
-     * Execute a gadget and push events to the completed results queue (non-blocking).
-     * Used for fire-and-forget parallel execution of independent gadgets.
-     * Results are pushed to completedResultsQueue for real-time streaming to the caller.
-     */
-    private executeGadgetAndCollect;
     /**
      * Drain all completed results from the queue.
      * Used to yield results as they complete during stream processing.
@@ -8316,53 +7460,14 @@ declare class StreamProcessor {
      */
     private drainCompletedResults;
     /**
-     * Wait for all in-flight gadget executions to complete, yielding events in real-time.
-     * Called at stream end to ensure all parallel executions finish.
-     * Results and subagent events are pushed to completedResultsQueue during execution.
-     * This generator yields queued events while polling, enabling real-time display
-     * of subagent activity (LLM calls, nested gadgets) during long-running gadgets.
-     * Clears the inFlightExecutions map after all gadgets complete.
-     */
-    private waitForInFlightExecutions;
-    /**
-     * Check if there are any gadgets waiting in concurrency queues.
-     */
-    private hasQueuedGadgets;
-    /**
-     * Get total count of queued gadgets across all queues.
-     */
-    private getQueuedGadgetCount;
-    /**
-     * Get total count of actively executing gadgets across all types.
-     * Used to know when all work is truly complete (not just when allDone resolves).
-     */
-    private getTotalActiveGadgetCount;
-    /**
-     * Handle a gadget that cannot execute because a dependency failed.
-     * Calls the onDependencySkipped controller to allow customization.
-     */
-    private handleFailedDependency;
-    /**
-     * Check if gadget execution should be skipped due to maxGadgetsPerResponse limit.
-     * If limit is exceeded, yields skip events and returns true.
-     * If execution can proceed, increments counter and returns false.
-     *
-     * @returns true if gadget should be skipped, false if execution can proceed
-     */
-    private checkGadgetLimitExceeded;
-    /**
-     * Process pending gadgets whose dependencies are now satisfied.
-     * Yields events in real-time as gadgets complete.
+     * Update gadget result tracking flags based on a stream event.
+     * Checks if the event is a gadget_result and, if so, marks gadgets as executed
+     * and sets the break-loop flag when the result requests it.
      *
-     * Gadgets are executed in parallel for efficiency,
-     * but results are yielded as they become available.
+     * @param evt - The stream event to inspect
+     * @param state - Mutable state object holding the tracking flags
      */
-    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.
-     */
-    private safeObserve;
+    private trackGadgetResult;
     /**
      * Execute multiple observers in parallel.
      * All observers run concurrently and failures are tracked but don't crash.
@@ -8536,6 +7641,26 @@ declare function getProvider(model: string): string | undefined;
  * ```
  */
 declare function getModelId(model: string): string;
+/**
+ * Strip the provider prefix from a model string.
+ *
+ * Identical to {@link getModelId}: removes the `provider:` portion and returns
+ * just the model ID. If there is no prefix, the original string is returned.
+ *
+ * Use this when you need the bare model ID (e.g. for a cost-registry lookup)
+ * and the input may or may not carry a provider prefix.
+ *
+ * @param modelId - Full model string, optionally with provider prefix
+ * @returns Model ID without provider prefix
+ *
+ * @example
+ * ```typescript
+ * stripProviderPrefix('openai:gpt-4o')          // → 'gpt-4o'
+ * stripProviderPrefix('anthropic:claude-sonnet') // → 'claude-sonnet'
+ * stripProviderPrefix('gpt-4o')                 // → 'gpt-4o'  (no prefix — returned as-is)
+ * ```
+ */
+declare function stripProviderPrefix(modelId: string): string;
 
 /**
  * Signal that a gadget throws to indicate task completion and agent termination.
@@ -8700,6 +7825,51 @@ interface ErrorFormatterOptions {
     endPrefix?: string;
 }
 
+/**
+ * Options for constructing a GadgetExecutor.
+ */
+interface GadgetExecutorOptions {
+    /** Gadget registry used to look up and execute gadgets */
+    registry: GadgetRegistry;
+    /** Optional callback to request human input during gadget execution */
+    requestHumanInput?: (question: string) => Promise<string>;
+    /** Logger instance; defaults to a new "llmist:executor" logger if omitted */
+    logger?: Logger<ILogObj>;
+    /** Default timeout in milliseconds applied to all gadgets without an explicit timeout */
+    defaultGadgetTimeoutMs?: number;
+    /** Options for formatting gadget execution errors */
+    errorFormatterOptions?: ErrorFormatterOptions;
+    /** LLMist client made available to gadgets via ExecutionContext.llmist */
+    client?: LLMist;
+    /** Media store for persisting gadget media outputs */
+    mediaStore?: MediaStore;
+    /** Parent agent configuration inherited by subagents */
+    agentConfig?: AgentContextConfig;
+    /** Per-gadget configuration overrides (e.g., timeoutMs, model) */
+    subagentConfig?: SubagentConfigMap;
+    /** Execution tree for tracking LLM calls and gadget executions */
+    tree?: ExecutionTree;
+    /** Parent node ID in the execution tree */
+    parentNodeId?: NodeId | null;
+    /** Base depth for nodes created during execution */
+    baseDepth?: number;
+    /**
+     * Parent agent's observer hooks for subagent visibility.
+     * When a subagent uses withParentContext(ctx), these observers are also called
+     * for gadget events in addition to the subagent's own hooks.
+     */
+    parentObservers?: Observers;
+    /**
+     * Current agent's observers.
+     * Passed to ExecutionContext.parentObservers so gadgets creating subagents
+     * can inherit them via withParentContext(ctx).
+     */
+    currentObservers?: Observers;
+    /** Shared rate limit tracker for coordinated throttling across subagents */
+    rateLimitTracker?: RateLimitTracker;
+    /** Shared retry config for consistent backoff behavior across subagents */
+    retryConfig?: ResolvedRetryConfig;
+}
 declare class GadgetExecutor {
     private readonly registry;
     private readonly requestHumanInput?;
@@ -8718,7 +7888,7 @@ declare class GadgetExecutor {
     private readonly logger;
     private readonly errorFormatter;
     private readonly argPrefix;
-    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, tree?: ExecutionTree | undefined, parentNodeId?: (NodeId | null) | undefined, baseDepth?: number | undefined, parentObservers?: Observers | undefined, currentObservers?: Observers | undefined, rateLimitTracker?: RateLimitTracker | undefined, retryConfig?: ResolvedRetryConfig | undefined);
+    constructor(options: GadgetExecutorOptions);
     /**
      * Creates a promise that rejects with a TimeoutException after the specified timeout.
      * Aborts the provided AbortController before rejecting, allowing gadgets to clean up.
@@ -8732,7 +7902,6 @@ declare class GadgetExecutor {
      */
     private unifyExecuteResult;
     execute(call: ParsedGadgetCall): Promise<GadgetExecutionResult>;
-    executeAll(calls: ParsedGadgetCall[]): Promise<GadgetExecutionResult[]>;
 }
 
 /**
@@ -10913,4 +10082,4 @@ declare const timing: {
  */
 declare function getHostExports(ctx: ExecutionContext): HostExports;
 
-export { AbortException, AbstractGadget, type AddGadgetParams, type AddLLMCallParams, type AfterGadgetExecutionAction, type AfterGadgetExecutionControllerContext, type AfterLLMCallAction, type AfterLLMCallControllerContext, type AfterLLMErrorAction, Agent, AgentBuilder, type AgentHooks, type AgentOptions, AnthropicMessagesProvider, type AudioContentPart, type AudioMimeType, type AudioSource, type BaseExecutionEvent, BaseSessionManager, type BeforeGadgetExecutionAction, type BeforeLLMCallAction, BudgetPricingUnavailableError, type CachingConfig, type CachingScope, type ChunkInterceptorContext, type CompactionConfig, type CompactionContext, type CompactionEvent, CompactionManager, type CompactionResult, type CompactionStats, type CompactionStrategy, type CompleteGadgetParams, type CompleteLLMCallParams, type ContentPart, type Controllers, ConversationManager, type CostEstimate, type CostReportingLLMist, type CreateGadgetConfig, DEFAULT_COMPACTION_CONFIG, DEFAULT_HINTS, DEFAULT_PROMPTS, DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_SUMMARIZATION_PROMPT, type EventHandlers, type ExecutionContext, type ExecutionEvent, type ExecutionEventType, type ExecutionNode, type ExecutionNodeType, ExecutionTree, FALLBACK_CHARS_PER_TOKEN, type FileLoggingOptions, type FileLoggingState, type FileWrittenInfo, type FormatLLMErrorContext, GADGET_ARG_PREFIX, GADGET_END_PREFIX, GADGET_START_PREFIX, Gadget, type GadgetCallEvent, GadgetCallParser, type GadgetClass, type GadgetCompleteEvent, type GadgetConfig, type GadgetErrorEvent, type GadgetEvent, type GadgetExample, type GadgetExecuteResult, type GadgetExecuteResultWithMedia, type GadgetExecuteReturn, type GadgetExecutionControllerContext, type GadgetExecutionMode, type GadgetExecutionResult, GadgetExecutor, type GadgetFactoryExports, type GadgetMediaOutput, type GadgetNode, type GadgetOrClass, GadgetOutputStore, type GadgetParameterInterceptorContext, GadgetRegistry, type GadgetResultInterceptorContext, type GadgetSkippedEvent, type GadgetStartEvent, type GadgetState, GeminiGenerativeProvider, type HintContext, type HintTemplate, type HintsConfig, type HistoryMessage, HookPresets, type HostExports, HuggingFaceProvider, type HumanInputRequiredEvent, HumanInputRequiredException, HybridStrategy, type IConversationManager, type ISessionManager, type ImageBase64Source, type ImageContentPart, type ImageGenerationOptions, type ImageGenerationResult, type ImageMimeType, type ImageModelSpec, type ImageSource, type ImageUrlSource, type Interceptors, type IterationHintOptions, type LLMCallCompleteEvent, type LLMCallControllerContext, type LLMCallErrorEvent, type LLMCallNode, type LLMCallStartEvent, type LLMCallStreamEvent, type LLMErrorControllerContext, type LLMEvent, type LLMGenerationOptions, type LLMMessage, LLMMessageBuilder, type LLMResponseEndEvent, type LLMStream, type LLMStreamChunk, LLMist, type LLMistOptions, type LLMistPackageManifest, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, type MediaKind, type MediaMetadata, MediaStore, type MessageContent, type MessageInterceptorContext, type MessageRole, type MessageTurn, type ModelDescriptor, type ModelFeatures, ModelIdentifierParser, type ModelLimits, type ModelPricing, ModelRegistry, type ModelSpec, type NodeId, type ObserveChunkContext, type ObserveCompactionContext, type ObserveGadgetCompleteContext, type ObserveGadgetStartContext, type ObserveLLMCallContext, type ObserveLLMCompleteContext, type ObserveLLMErrorContext, type ObserveRateLimitThrottleContext, type ObserveRetryAttemptContext, type Observers, OpenAIChatProvider, type OpenAICompatibleConfig, OpenAICompatibleProvider, type OpenRouterConfig, OpenRouterProvider, type OpenRouterRouting, type ParallelGadgetHintOptions, type ParsedGadgetCall, type PresetDefinition, type PromptContext, type PromptTemplate, type PromptTemplateConfig, type ProviderAdapter, type ProviderIdentifier, type RateLimitConfig, type RateLimitStats, RateLimitTracker, type ReasoningConfig, type ReasoningEffort, type ResolveValueOptions, type ResolvedCompactionConfig, type ResolvedRateLimitConfig, type ResolvedRetryConfig, type RetryConfig, type RetryOptions, type SessionManifestEntry, SimpleSessionManager, SlidingWindowStrategy, type SpeechGenerationOptions, type SpeechGenerationResult, type SpeechModelSpec, type StoredMedia, type StoredOutput, type StreamCompleteEvent, type StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type SubagentConfig, type SubagentConfigMap, type SubagentContext, type SubagentManifestEntry, type SubagentOptions, SummarizationStrategy, TaskCompletionSignal, type TextContentPart, type TextEvent, type TextGenerationOptions, type TextOnlyAction, type TextOnlyContext, type TextOnlyCustomHandler, type TextOnlyGadgetConfig, type TextOnlyHandler, type TextOnlyStrategy, type ThinkingChunk, type ThinkingEvent, TimeoutException, type TokenUsage, type TrailingMessage, type TrailingMessageContext, type CompactionEvent$1 as TreeCompactionEvent, type GadgetSkippedEvent$1 as TreeGadgetSkippedEvent, type TriggeredLimitInfo, type ValidationIssue, type ValidationResult, type VisionAnalyzeOptions, type VisionAnalyzeResult, audioFromBase64, audioFromBuffer, collectEvents, collectText, complete, createAnthropicProviderFromEnv, createFileLoggingState, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createHuggingFaceProviderFromEnv, createLogger, createMediaOutput, createOpenAIProviderFromEnv, createOpenRouterProviderFromEnv, createSubagent, defaultLogger, detectAudioMimeType, detectImageMimeType, discoverProviderAdapters, extractMessageText, extractRetryAfterMs, filterByDepth, filterByParent, filterRootEvents, format, formatBytes, formatCallNumber, formatDate, formatDuration, formatLLMError, formatLlmRequest, gadgetError, gadgetSuccess, getErrorMessage, getHostExports, getModelId, getPresetGadgets, getProvider, getSubagent, groupByParent, hasHostExports, hasPreset, hasProviderPrefix, hasSubagents, humanDelay, imageFromBase64, imageFromBuffer, imageFromUrl, isAbortError, isAudioPart, isDataUrl, isGadgetEvent, isImagePart, isLLMEvent, isRetryableError, isRootEvent, isSubagentEvent, isTextPart, iterationProgressHint, listPresets, listSubagents, normalizeMessageContent, parallelGadgetHint, parseDataUrl, parseManifest, parseRetryAfterHeader, randomDelay, resetFileLoggingState, resolveConfig, resolveHintTemplate, resolveModel, resolvePromptTemplate, resolveRateLimitConfig, resolveRetryConfig, resolveRulesTemplate, resolveSubagentModel, resolveSubagentTimeout, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, runWithHandlers, schemaToJSONSchema, stream, text, timing, toBase64, truncate, validateAndApplyDefaults, validateGadgetParams, validateGadgetSchema, withErrorHandling, withRetry, withTimeout };
+export { AbortException, AbstractGadget, type AddGadgetParams, type AddLLMCallParams, type AfterGadgetExecutionAction, type AfterGadgetExecutionControllerContext, type AfterLLMCallAction, type AfterLLMCallControllerContext, type AfterLLMErrorAction, Agent, AgentBuilder, type AgentHooks, type AgentOptions, AnthropicMessagesProvider, type AudioContentPart, type AudioMimeType, type AudioSource, type BaseExecutionEvent, BaseSessionManager, type BeforeGadgetExecutionAction, type BeforeLLMCallAction, BudgetPricingUnavailableError, type CachingConfig, type CachingScope, type ChunkInterceptorContext, type CompactionConfig, type CompactionContext, type CompactionEvent, CompactionManager, type CompactionResult, type CompactionStats, type CompactionStrategy, type CompleteGadgetParams, type CompleteLLMCallParams, type ContentPart, type Controllers, ConversationManager, type CostEstimate, type CostReportingLLMist, type CreateGadgetConfig, DEFAULT_COMPACTION_CONFIG, DEFAULT_HINTS, DEFAULT_PROMPTS, DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_SUMMARIZATION_PROMPT, type EventHandlers, type ExecutionContext, type ExecutionEvent, type ExecutionEventType, type ExecutionNode, type ExecutionNodeType, ExecutionTree, FALLBACK_CHARS_PER_TOKEN, type FileLoggingOptions, type FileLoggingState, type FileWrittenInfo, type FormatLLMErrorContext, GADGET_ARG_PREFIX, GADGET_END_PREFIX, GADGET_START_PREFIX, Gadget, type GadgetCallEvent, GadgetCallParser, type GadgetClass, type GadgetCompleteEvent, type GadgetConfig, type GadgetErrorEvent, type GadgetEvent, type GadgetExample, type GadgetExecuteResult, type GadgetExecuteResultWithMedia, type GadgetExecuteReturn, type GadgetExecutionControllerContext, type GadgetExecutionMode, type GadgetExecutionResult, GadgetExecutor, type GadgetExecutorOptions, type GadgetFactoryExports, type GadgetMediaOutput, type GadgetNode, type GadgetOrClass, GadgetOutputStore, type GadgetParameterInterceptorContext, GadgetRegistry, type GadgetResultInterceptorContext, type GadgetSkippedEvent, type GadgetStartEvent, type GadgetState, GeminiGenerativeProvider, type HintContext, type HintTemplate, type HintsConfig, type HistoryMessage, HookPresets, type HostExports, HuggingFaceProvider, type HumanInputRequiredEvent, HumanInputRequiredException, HybridStrategy, type IConversationManager, type ISessionManager, type ImageBase64Source, type ImageContentPart, type ImageGenerationOptions, type ImageGenerationResult, type ImageMimeType, type ImageModelSpec, type ImageSource, type ImageUrlSource, type Interceptors, type IterationHintOptions, type LLMCallCompleteEvent, type LLMCallControllerContext, type LLMCallErrorEvent, type LLMCallNode, type LLMCallStartEvent, type LLMCallStreamEvent, type LLMErrorControllerContext, type LLMEvent, type LLMGenerationOptions, type LLMMessage, LLMMessageBuilder, type LLMResponseEndEvent, type LLMStream, type LLMStreamChunk, LLMist, type LLMistOptions, type LLMistPackageManifest, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, type MediaKind, type MediaMetadata, MediaStore, type MessageContent, type MessageInterceptorContext, type MessageRole, type MessageTurn, type ModelDescriptor, type ModelFeatures, ModelIdentifierParser, type ModelLimits, type ModelPricing, ModelRegistry, type ModelSpec, type NodeId, type ObserveChunkContext, type ObserveCompactionContext, type ObserveGadgetCompleteContext, type ObserveGadgetStartContext, type ObserveLLMCallContext, type ObserveLLMCompleteContext, type ObserveLLMErrorContext, type ObserveRateLimitThrottleContext, type ObserveRetryAttemptContext, type Observers, OpenAIChatProvider, type OpenAICompatibleConfig, OpenAICompatibleProvider, type OpenRouterConfig, OpenRouterProvider, type OpenRouterRouting, type OutputLimitConfig, type ParallelGadgetHintOptions, type ParsedGadgetCall, type PrefixConfig, type PresetDefinition, type PromptContext, type PromptTemplate, type PromptTemplateConfig, type ProviderAdapter, type ProviderIdentifier, type RateLimitConfig, type RateLimitStats, RateLimitTracker, type ReasoningConfig, type ReasoningEffort, type ResolveValueOptions, type ResolvedCompactionConfig, type ResolvedRateLimitConfig, type ResolvedRetryConfig, type RetryConfig, type RetryOptions, type SessionManifestEntry, SimpleSessionManager, SlidingWindowStrategy, type SpeechGenerationOptions, type SpeechGenerationResult, type SpeechModelSpec, type StoredMedia, type StoredOutput, type StreamCompleteEvent, type StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type SubagentConfig, type SubagentConfigMap, type SubagentContext, type SubagentManifestEntry, type SubagentOptions, SummarizationStrategy, TaskCompletionSignal, type TextContentPart, type TextEvent, type TextGenerationOptions, type TextOnlyAction, type TextOnlyContext, type TextOnlyCustomHandler, type TextOnlyGadgetConfig, type TextOnlyHandler, type TextOnlyStrategy, type ThinkingChunk, type ThinkingEvent, TimeoutException, type TokenUsage, type TrailingMessage, type TrailingMessageContext, type CompactionEvent$1 as TreeCompactionEvent, type TreeConfig, type GadgetSkippedEvent$1 as TreeGadgetSkippedEvent, type TriggeredLimitInfo, type ValidationIssue, type ValidationResult, type VisionAnalyzeOptions, type VisionAnalyzeResult, audioFromBase64, audioFromBuffer, collectEvents, collectText, complete, createAnthropicProviderFromEnv, createFileLoggingState, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createHuggingFaceProviderFromEnv, createLogger, createMediaOutput, createOpenAIProviderFromEnv, createOpenRouterProviderFromEnv, createSubagent, defaultLogger, detectAudioMimeType, detectImageMimeType, discoverProviderAdapters, extractMessageText, extractRetryAfterMs, filterByDepth, filterByParent, filterRootEvents, format, formatBytes, formatCallNumber, formatDate, formatDuration, formatLLMError, formatLlmRequest, gadgetError, gadgetSuccess, getErrorMessage, getHostExports, getModelId, getPresetGadgets, getProvider, getSubagent, groupByParent, hasHostExports, hasPreset, hasProviderPrefix, hasSubagents, humanDelay, imageFromBase64, imageFromBuffer, imageFromUrl, isAbortError, isAudioPart, isDataUrl, isGadgetEvent, isImagePart, isLLMEvent, isRetryableError, isRootEvent, isSubagentEvent, isTextPart, iterationProgressHint, listPresets, listSubagents, normalizeMessageContent, parallelGadgetHint, parseDataUrl, parseManifest, parseRetryAfterHeader, randomDelay, resetFileLoggingState, resolveConfig, resolveHintTemplate, resolveModel, resolvePromptTemplate, resolveRateLimitConfig, resolveRetryConfig, resolveRulesTemplate, resolveSubagentModel, resolveSubagentTimeout, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, runWithHandlers, schemaToJSONSchema, stream, stripProviderPrefix, text, timing, toBase64, truncate, validateAndApplyDefaults, validateGadgetParams, validateGadgetSchema, withErrorHandling, withRetry, withTimeout };