llmist 6.0.0 → 6.2.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { ZodType, ZodTypeAny } from 'zod';
+import { ZodTypeAny } from 'zod';
 export { z } from 'zod';
-import { s as AgentHooks, t as ModelRegistry, u as LLMist, C as CompactionConfig, I as IConversationManager, v as CompactionEvent, L as LLMMessage, w as CompactionStats, x as CompactionStrategy, R as ResolvedCompactionConfig, y as CompactionContext, z as CompactionResult, B as MessageContent, G as GadgetMediaOutput, H as HintTemplate, S as StreamEvent, T as TokenUsage, D as GadgetRegistry, E as MediaStore, F as AgentContextConfig, J as SubagentConfigMap, K as SubagentEvent, b as LLMStreamChunk, N as ExecutionContext, O as GadgetExecuteReturn, P as GadgetExample, A as AbstractGadget, Q as ParsedGadgetCall, U as GadgetExecutionResult, V as MediaKind, W as MediaMetadata, X as GadgetExecuteResultWithMedia, Y as ProviderAdapter, Z as ModelDescriptor, _ as ModelSpec, $ as LLMGenerationOptions, a as LLMStream, a0 as ImageModelSpec, a1 as ImageGenerationOptions, a2 as ImageGenerationResult, a3 as SpeechModelSpec, a4 as SpeechGenerationOptions, a5 as SpeechGenerationResult } from './mock-stream-CAY53Q6u.cjs';
-export { ae as AfterGadgetExecutionAction, af as AfterGadgetExecutionControllerContext, ag as AfterLLMCallAction, ah as AfterLLMCallControllerContext, ai as AfterLLMErrorAction, a9 as AgentBuilder, aj as AgentOptions, aI as AudioContentPart, aJ as AudioMimeType, aK as AudioSource, ak as BeforeGadgetExecutionAction, al as BeforeLLMCallAction, am as ChunkInterceptorContext, aL as ContentPart, an as Controllers, b8 as CostEstimate, bu as CostReportingLLMist, aF as DEFAULT_COMPACTION_CONFIG, bk as DEFAULT_HINTS, bl as DEFAULT_PROMPTS, aG as DEFAULT_SUMMARIZATION_PROMPT, aa as EventHandlers, bs as GadgetClass, bv as GadgetExecuteResult, ao as GadgetExecutionControllerContext, bt as GadgetOrClass, ap as GadgetParameterInterceptorContext, aq as GadgetResultInterceptorContext, bw as GadgetSkippedEvent, bg as HintContext, a6 as HistoryMessage, aM as ImageBase64Source, aN as ImageContentPart, aO as ImageMimeType, aP as ImageSource, aQ as ImageUrlSource, ar as Interceptors, as as LLMCallControllerContext, at as LLMErrorControllerContext, b6 as LLMMessageBuilder, aH as LLMistOptions, au as MessageInterceptorContext, b4 as MessageRole, av as MessageTurn, d as MockBuilder, f as MockManager, l as MockMatcher, n as MockMatcherContext, o as MockOptions, M as MockProviderAdapter, p as MockRegistration, q as MockResponse, r as MockStats, b9 as ModelFeatures, bf as ModelIdentifierParser, ba as ModelLimits, bb as ModelPricing, aw as ObserveChunkContext, ax as ObserveCompactionContext, ay as ObserveGadgetCompleteContext, az as ObserveGadgetStartContext, aA as ObserveLLMCallContext, aB as ObserveLLMCompleteContext, aC as ObserveLLMErrorContext, aD as Observers, bh as PromptContext, bi as PromptTemplate, bj as PromptTemplateConfig, be as ProviderIdentifier, bx as StoredMedia, aE as SubagentContext, by as SubagentStreamEvent, aR as TextContentPart, bp as TextGenerationOptions, bz as TextOnlyAction, bA as TextOnlyContext, bB as TextOnlyCustomHandler, bC as TextOnlyGadgetConfig, bD as TextOnlyHandler, bE as TextOnlyStrategy, a7 as TrailingMessage, a8 as TrailingMessageContext, bc as VisionAnalyzeOptions, bd as VisionAnalyzeResult, aS as audioFromBase64, aT as audioFromBuffer, ab as collectEvents, ac as collectText, bq as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, aU as detectAudioMimeType, aV as detectImageMimeType, b5 as extractMessageText, g as getMockManager, aW as imageFromBase64, aX as imageFromBuffer, aY as imageFromUrl, aZ as isAudioPart, a_ as isDataUrl, a$ as isImagePart, b0 as isTextPart, m as mockLLM, b7 as normalizeMessageContent, b1 as parseDataUrl, bm as resolveHintTemplate, bn as resolvePromptTemplate, bo as resolveRulesTemplate, ad as runWithHandlers, br as stream, b2 as text, b3 as toBase64 } from './mock-stream-CAY53Q6u.cjs';
+import { s as AgentHooks, t as ModelRegistry, u as LLMist, C as CompactionConfig, I as IConversationManager, v as CompactionEvent, L as LLMMessage, w as CompactionStats, x as CompactionStrategy, R as ResolvedCompactionConfig, y as CompactionContext, z as CompactionResult, B as MessageContent, G as GadgetMediaOutput, H as HintTemplate, S as StreamEvent, T as TokenUsage, D as GadgetRegistry, E as MediaStore, F as AgentContextConfig, J as SubagentConfigMap, K as SubagentEvent, N as ExecutionTree, O as NodeId, b as LLMStreamChunk, P as ParsedGadgetCall, Q as GadgetExecutionResult, A as AbstractGadget, U as MediaKind, V as MediaMetadata, W as GadgetExecuteResultWithMedia, X as ExecutionContext, Y as ProviderAdapter, Z as ModelDescriptor, _ as ModelSpec, $ as LLMGenerationOptions, a as LLMStream, a0 as ImageModelSpec, a1 as ImageGenerationOptions, a2 as ImageGenerationResult, a3 as SpeechModelSpec, a4 as SpeechGenerationOptions, a5 as SpeechGenerationResult, a6 as HostExports } from './mock-stream-DG4wF-NH.cjs';
+export { aJ as AddGadgetParams, aK as AddLLMCallParams, af as AfterGadgetExecutionAction, ag as AfterGadgetExecutionControllerContext, ah as AfterLLMCallAction, ai as AfterLLMCallControllerContext, aj as AfterLLMErrorAction, aa as AgentBuilder, ak as AgentOptions, bg as AudioContentPart, bh as AudioMimeType, bi as AudioSource, aS as BaseExecutionEvent, al as BeforeGadgetExecutionAction, am as BeforeLLMCallAction, an as ChunkInterceptorContext, aL as CompleteGadgetParams, aM as CompleteLLMCallParams, bj as ContentPart, ao as Controllers, bI as CostEstimate, c6 as CostReportingLLMist, c0 as CreateGadgetConfig, aG as DEFAULT_COMPACTION_CONFIG, bU as DEFAULT_HINTS, bV as DEFAULT_PROMPTS, aH as DEFAULT_SUMMARIZATION_PROMPT, ab as EventHandlers, aU as ExecutionEvent, aV as ExecutionEventType, aN as ExecutionNode, aO as ExecutionNodeType, c5 as Gadget, aW as GadgetCallEvent, c2 as GadgetClass, aX as GadgetCompleteEvent, c4 as GadgetConfig, aY as GadgetErrorEvent, aZ as GadgetEvent, c7 as GadgetExample, c8 as GadgetExecuteResult, c9 as GadgetExecuteReturn, ap as GadgetExecutionControllerContext, aP as GadgetNode, c3 as GadgetOrClass, aq as GadgetParameterInterceptorContext, ar as GadgetResultInterceptorContext, ca as GadgetSkippedEvent, a$ as GadgetStartEvent, aQ as GadgetState, bQ as HintContext, a7 as HistoryMessage, b0 as HumanInputRequiredEvent, bk as ImageBase64Source, bl as ImageContentPart, bm as ImageMimeType, bn as ImageSource, bo as ImageUrlSource, as as Interceptors, b1 as LLMCallCompleteEvent, at as LLMCallControllerContext, b2 as LLMCallErrorEvent, aR as LLMCallNode, b3 as LLMCallStartEvent, b4 as LLMCallStreamEvent, au as LLMErrorControllerContext, b5 as LLMEvent, bG as LLMMessageBuilder, aI as LLMistOptions, av as MessageInterceptorContext, bE as MessageRole, aw as MessageTurn, d as MockBuilder, f as MockManager, l as MockMatcher, n as MockMatcherContext, o as MockOptions, M as MockProviderAdapter, p as MockRegistration, q as MockResponse, r as MockStats, bJ as ModelFeatures, bP as ModelIdentifierParser, bK as ModelLimits, bL as ModelPricing, ax as ObserveChunkContext, ay as ObserveCompactionContext, az as ObserveGadgetCompleteContext, aA as ObserveGadgetStartContext, aB as ObserveLLMCallContext, aC as ObserveLLMCompleteContext, aD as ObserveLLMErrorContext, aE as Observers, bR as PromptContext, bS as PromptTemplate, bT as PromptTemplateConfig, bO as ProviderIdentifier, cb as StoredMedia, b6 as StreamCompleteEvent, aF as SubagentContext, cc as SubagentStreamEvent, bp as TextContentPart, b7 as TextEvent, bZ as TextGenerationOptions, cd as TextOnlyAction, ce as TextOnlyContext, cf as TextOnlyCustomHandler, cg as TextOnlyGadgetConfig, ch as TextOnlyHandler, ci as TextOnlyStrategy, a8 as TrailingMessage, a9 as TrailingMessageContext, aT as TreeCompactionEvent, a_ as TreeGadgetSkippedEvent, bM as VisionAnalyzeOptions, bN as VisionAnalyzeResult, bq as audioFromBase64, br as audioFromBuffer, ac as collectEvents, ad as collectText, b_ as complete, c1 as createGadget, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, bs as detectAudioMimeType, bt as detectImageMimeType, bF as extractMessageText, b8 as filterByDepth, b9 as filterByParent, ba as filterRootEvents, g as getMockManager, bb as groupByParent, bu as imageFromBase64, bv as imageFromBuffer, bw as imageFromUrl, bx as isAudioPart, by as isDataUrl, bc as isGadgetEvent, bz as isImagePart, bd as isLLMEvent, be as isRootEvent, bf as isSubagentEvent, bA as isTextPart, m as mockLLM, bH as normalizeMessageContent, bB as parseDataUrl, bW as resolveHintTemplate, bX as resolvePromptTemplate, bY as resolveRulesTemplate, ae as runWithHandlers, b$ as stream, bC as text, bD as toBase64 } from './mock-stream-DG4wF-NH.cjs';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';
@@ -888,7 +888,7 @@ declare class ConversationManager implements IConversationManager {
     constructor(baseMessages: LLMMessage[], initialMessages: LLMMessage[], options?: ConversationManagerOptions);
     addUserMessage(content: MessageContent): void;
     addAssistantMessage(content: string): void;
-    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, media?: GadgetMediaOutput[], mediaIds?: string[]): void;
+    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[]): void;
     getMessages(): LLMMessage[];
     getHistoryMessages(): LLMMessage[];
     getBaseMessages(): LLMMessage[];
@@ -1180,15 +1180,6 @@ interface StreamProcessorOptions {
     logger?: Logger<ILogObj>;
     /** Callback for requesting human input during execution */
     requestHumanInput?: (question: string) => Promise<string>;
-    /** Whether to stop on gadget errors */
-    stopOnGadgetError?: boolean;
-    /** Custom error recovery logic */
-    canRecoverFromGadgetError?: (context: {
-        error: string;
-        gadgetName: string;
-        errorType: "parse" | "validation" | "execution";
-        parameters?: Record<string, unknown>;
-    }) => boolean | Promise<boolean>;
     /** Default gadget timeout */
     defaultGadgetTimeoutMs?: number;
     /** LLMist client for ExecutionContext.llmist */
@@ -1201,6 +1192,12 @@ interface StreamProcessorOptions {
     subagentConfig?: SubagentConfigMap;
     /** Callback for subagent gadgets to report subagent events to parent */
     onSubagentEvent?: (event: SubagentEvent) => void;
+    /** Execution tree for tracking LLM calls and gadget executions */
+    tree?: ExecutionTree;
+    /** Parent node ID (for gadget nodes created by this processor) */
+    parentNodeId?: NodeId | null;
+    /** Base depth for nodes created by this processor */
+    baseDepth?: number;
 }
 /**
  * Result of stream processing.
@@ -1250,10 +1247,10 @@ declare class StreamProcessor {
     private readonly logger;
     private readonly parser;
     private readonly executor;
-    private readonly stopOnGadgetError;
-    private readonly canRecoverFromGadgetError?;
+    private readonly tree?;
+    private readonly parentNodeId;
+    private readonly baseDepth;
     private responseText;
-    private executionHalted;
     private observerFailureCount;
     /** Gadgets waiting for their dependencies to complete */
     private gadgetsAwaitingDependencies;
@@ -1263,6 +1260,8 @@ declare class StreamProcessor {
     private failedInvocations;
     /** Promises for independent gadgets currently executing (fire-and-forget) */
     private inFlightExecutions;
+    /** Queue of completed gadget results ready to be yielded (for real-time streaming) */
+    private completedResultsQueue;
     constructor(options: StreamProcessorOptions);
     /**
      * Process an LLM stream and yield events in real-time.
@@ -1275,14 +1274,8 @@ declare class StreamProcessor {
      * The final event is always a StreamCompletionEvent containing metadata.
      */
     process(stream: AsyncIterable<LLMStreamChunk>): AsyncGenerator<StreamEvent>;
-    /**
-     * Process a single parsed event (text or gadget call).
-     * @deprecated Use processEventGenerator for real-time streaming
-     */
-    private processEvent;
     /**
      * Process a single parsed event, yielding events in real-time.
-     * Generator version of processEvent for streaming support.
      */
     private processEventGenerator;
     /**
@@ -1316,17 +1309,26 @@ declare class StreamProcessor {
      */
     private executeGadgetGenerator;
     /**
-     * Execute a gadget and collect all events into an array (non-blocking).
+     * 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;
     /**
-     * Collect results from all fire-and-forget (in-flight) gadget executions.
-     * Called at stream end to await parallel independent gadgets.
-     * Clears the inFlightExecutions map after collection.
-     * @returns Array of all events from completed gadgets
+     * Drain all completed results from the queue.
+     * Used to yield results as they complete during stream processing.
+     * @returns Generator that yields all events currently in the queue
+     */
+    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 collectInFlightResults;
+    private waitForInFlightExecutions;
     /**
      * Handle a gadget that cannot execute because a dependency failed.
      * Calls the onDependencySkipped controller to allow customization.
@@ -1355,22 +1357,6 @@ declare class StreamProcessor {
      * All observers run concurrently and failures are tracked but don't crash.
      */
     private runObserversInParallel;
-    /**
-     * Check if execution can recover from an error.
-     *
-     * Returns true if we should continue processing subsequent gadgets, false if we should stop.
-     *
-     * Logic:
-     * - If custom canRecoverFromGadgetError is provided, use it
-     * - Otherwise, use stopOnGadgetError config:
-     *   - stopOnGadgetError=true → return false (stop execution)
-     *   - stopOnGadgetError=false → return true (continue execution)
-     */
-    private checkCanRecoverFromError;
-    /**
-     * Determine the type of error from a gadget execution.
-     */
-    private determineErrorType;
 }
 
 /**
@@ -1487,116 +1473,6 @@ declare function getProvider(model: string): string | undefined;
  */
 declare function getModelId(model: string): string;
 
-/**
- * Function-based gadget creation helper.
- *
- * For simple gadgets, use createGadget() instead of defining a class.
- * Parameters are automatically typed from the Zod schema.
- *
- * @example
- * ```typescript
- * const calculator = createGadget({
- *   description: "Performs arithmetic operations",
- *   schema: z.object({
- *     operation: z.enum(["add", "subtract"]),
- *     a: z.number(),
- *     b: z.number(),
- *   }),
- *   execute: ({ operation, a, b }) => {
- *     // Automatically typed!
- *     return operation === "add" ? String(a + b) : String(a - b);
- *   },
- * });
- * ```
- */
-
-/**
- * Infer the TypeScript type from a Zod schema.
- */
-type InferSchema$1<T> = T extends ZodType<infer U> ? U : never;
-/**
- * Configuration for creating a function-based gadget.
- */
-interface CreateGadgetConfig<TSchema extends ZodType> {
-    /** Optional custom name (defaults to "FunctionGadget") */
-    name?: string;
-    /** Human-readable description of what the gadget does */
-    description: string;
-    /** Zod schema for parameter validation */
-    schema: TSchema;
-    /**
-     * Execution function with typed parameters.
-     * Can return string or { result, cost? }.
-     * Optionally receives ExecutionContext for callback-based cost reporting.
-     */
-    execute: (params: InferSchema$1<TSchema>, ctx?: ExecutionContext) => GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
-    /** Optional timeout in milliseconds */
-    timeoutMs?: number;
-    /** Optional usage examples to help LLMs understand proper invocation */
-    examples?: GadgetExample<InferSchema$1<TSchema>>[];
-}
-/**
- * Creates a gadget from a function (simpler than class-based approach).
- *
- * This is perfect for simple gadgets where you don't need the full
- * power of a class. Parameters are automatically typed from the schema.
- *
- * @param config - Configuration with execute function and schema
- * @returns Gadget instance ready to be registered
- *
- * @example
- * ```typescript
- * import { z } from 'zod';
- * import { createGadget } from 'llmist';
- *
- * // Simple calculator gadget
- * const calculator = createGadget({
- *   description: "Performs arithmetic operations",
- *   schema: z.object({
- *     operation: z.enum(["add", "subtract", "multiply", "divide"]),
- *     a: z.number().describe("First number"),
- *     b: z.number().describe("Second number"),
- *   }),
- *   execute: ({ operation, a, b }) => {
- *     // Parameters are automatically typed!
- *     switch (operation) {
- *       case "add": return String(a + b);
- *       case "subtract": return String(a - b);
- *       case "multiply": return String(a * b);
- *       case "divide": return String(a / b);
- *     }
- *   },
- * });
- * ```
- *
- * @example
- * ```typescript
- * // Async gadget with custom name and timeout
- * const weather = createGadget({
- *   name: "weather",
- *   description: "Fetches current weather for a city",
- *   schema: z.object({
- *     city: z.string().min(1).describe("City name"),
- *   }),
- *   timeoutMs: 10000,
- *   execute: async ({ city }) => {
- *     const response = await fetch(`https://api.weather.com/${city}`);
- *     const data = await response.json();
- *     return `Weather in ${city}: ${data.description}, ${data.temp}°C`;
- *   },
- * });
- * ```
- *
- * @example
- * ```typescript
- * // Use with agent
- * const agent = LLMist.createAgent()
- *   .withGadgets(calculator, weather)
- *   .ask("What's the weather in Paris and what's 10 + 5?");
- * ```
- */
-declare function createGadget<TSchema extends ZodType>(config: CreateGadgetConfig<TSchema>): AbstractGadget;
-
 /**
  * Signal that a gadget throws to indicate task completion and agent termination.
  *
@@ -1744,13 +1620,17 @@ declare class GadgetExecutor {
     private readonly agentConfig?;
     private readonly subagentConfig?;
     private readonly onSubagentEvent?;
+    private readonly tree?;
+    private readonly parentNodeId?;
+    private readonly baseDepth?;
     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, onSubagentEvent?: ((event: SubagentEvent) => void) | undefined);
+    constructor(registry: GadgetRegistry, requestHumanInput?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined, errorFormatterOptions?: ErrorFormatterOptions, client?: LLMist | undefined, mediaStore?: MediaStore | undefined, agentConfig?: AgentContextConfig | undefined, subagentConfig?: SubagentConfigMap | undefined, onSubagentEvent?: ((event: SubagentEvent) => void) | undefined, tree?: ExecutionTree | undefined, parentNodeId?: (NodeId | null) | undefined, baseDepth?: number | undefined);
     /**
      * Creates a promise that rejects with a TimeoutException after the specified timeout.
      * Aborts the provided AbortController before rejecting, allowing gadgets to clean up.
+     * Returns both the promise and a cancel function to clear the timeout when no longer needed.
      */
     private createTimeoutPromise;
     /**
@@ -1835,161 +1715,6 @@ declare class GadgetCallParser {
     reset(): void;
 }
 
-/**
- * Type-safe gadget factory with automatic parameter inference.
- *
- * Gadget eliminates the need for manual type assertions
- * by automatically inferring parameter types from the Zod schema.
- *
- * @example
- * ```typescript
- * class Calculator extends Gadget({
- *   description: "Performs arithmetic operations",
- *   schema: z.object({
- *     operation: z.enum(["add", "subtract"]),
- *     a: z.number(),
- *     b: z.number(),
- *   }),
- * }) {
- *   // ✨ params is automatically typed!
- *   execute(params: this['params']): string {
- *     const { operation, a, b } = params; // All typed!
- *     return operation === "add" ? String(a + b) : String(a - b);
- *   }
- * }
- * ```
- */
-
-/**
- * Infer the TypeScript type from a Zod schema.
- */
-type InferSchema<T> = T extends ZodType<infer U> ? U : never;
-/**
- * Configuration for creating a typed gadget.
- */
-interface GadgetConfig<TSchema extends ZodType> {
-    /** Human-readable description of what the gadget does */
-    description: string;
-    /** Zod schema for parameter validation */
-    schema: TSchema;
-    /** Optional custom name (defaults to class name) */
-    name?: string;
-    /** Optional timeout in milliseconds */
-    timeoutMs?: number;
-    /** Optional usage examples to help LLMs understand proper invocation */
-    examples?: GadgetExample<InferSchema<TSchema>>[];
-}
-/**
- * Factory function to create a typed gadget base class.
- *
- * The returned class automatically infers parameter types from the Zod schema,
- * eliminating the need for manual type assertions in the execute method.
- *
- * @param config - Configuration with description and schema
- * @returns Base class to extend with typed execute method
- *
- * @example
- * ```typescript
- * import { z } from 'zod';
- * import { Gadget } from 'llmist';
- *
- * class Calculator extends Gadget({
- *   description: "Performs arithmetic operations",
- *   schema: z.object({
- *     operation: z.enum(["add", "subtract", "multiply", "divide"]),
- *     a: z.number().describe("First number"),
- *     b: z.number().describe("Second number"),
- *   }),
- * }) {
- *   execute(params: this['params']): string {
- *     // params is automatically typed as:
- *     // { operation: "add" | "subtract" | "multiply" | "divide"; a: number; b: number }
- *     const { operation, a, b } = params;
- *
- *     switch (operation) {
- *       case "add": return String(a + b);
- *       case "subtract": return String(a - b);
- *       case "multiply": return String(a * b);
- *       case "divide": return String(a / b);
- *     }
- *   }
- * }
- * ```
- *
- * @example
- * ```typescript
- * // With async execution
- * class WeatherGadget extends Gadget({
- *   description: "Fetches weather for a city",
- *   schema: z.object({
- *     city: z.string().min(1).describe("City name"),
- *   }),
- *   timeoutMs: 10000,
- * }) {
- *   async execute(params: this['params']): Promise<string> {
- *     const { city } = params; // Automatically typed as { city: string }
- *     const weather = await fetchWeather(city);
- *     return `Weather in ${city}: ${weather}`;
- *   }
- * }
- * ```
- */
-declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>): {
-    new (): {
-        description: string;
-        parameterSchema: TSchema;
-        name: string | undefined;
-        timeoutMs: number | undefined;
-        examples: GadgetExample<InferSchema<TSchema>>[] | undefined;
-        /**
-         * Type helper property for accessing inferred parameter type.
-         * This is used in the execute method signature: `execute(params: this['params'])`
-         *
-         * Note: This is just for type inference - the actual params in execute()
-         * will be Record<string, unknown> which you can safely cast to this['params']
-         */
-        readonly params: InferSchema<TSchema>;
-        /**
-         * Execute the gadget. Subclasses should cast params to this['params'].
-         *
-         * @param params - Validated parameters 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: this['params']) {
-         *   return String(params.a + params.b);
-         * }
-         *
-         * // Using context for callback-based cost reporting
-         * execute(params: this['params'], ctx) {
-         *   ctx.reportCost(0.001);
-         *   return "result";
-         * }
-         *
-         * // Using wrapped LLMist for automatic cost tracking
-         * async execute(params: this['params'], ctx) {
-         *   return ctx.llmist.complete('Summarize: ' + params.text);
-         * }
-         * ```
-         */
-        execute(params: Record<string, unknown>, ctx?: ExecutionContext): GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
-        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;
-            endPrefix?: string;
-        }): string;
-    } & {
-        params: InferSchema<TSchema>;
-    };
-};
-
 /**
  * Helper functions for gadget authors to easily return media outputs.
  *
@@ -2334,6 +2059,115 @@ declare function createLogger(options?: LoggerOptions): Logger<ILogObj>;
  */
 declare const defaultLogger: Logger<ILogObj>;
 
+/**
+ * Config resolution utility for subagent gadgets.
+ *
+ * Simplifies the common pattern of resolving configuration from multiple sources:
+ * 1. Runtime params (explicit gadget call parameters)
+ * 2. Subagent config (from CLI [subagents.Name] sections)
+ * 3. Parent agent config (model inheritance)
+ * 4. Package defaults
+ *
+ * @module utils/config-resolver
+ */
+
+/**
+ * Options for resolving a single config value.
+ */
+interface ResolveValueOptions<T> {
+    /** Runtime parameter value (highest priority) */
+    runtime?: T;
+    /** Subagent config key to check */
+    subagentKey?: string;
+    /** Parent config key to check (for inheritance) - "model" or "temperature" */
+    parentKey?: "model" | "temperature";
+    /** Default value (lowest priority) */
+    defaultValue: T;
+    /** Whether "inherit" string means use parent value */
+    handleInherit?: boolean;
+}
+/**
+ * Resolve a single configuration value through the priority chain.
+ *
+ * Priority (highest to lowest):
+ * 1. Runtime parameter (if provided and not undefined)
+ * 2. Subagent config (from ctx.subagentConfig[gadgetName][key])
+ * 3. Parent config (from ctx.agentConfig[key], if parentKey specified)
+ * 4. Default value
+ *
+ * Special handling for "inherit" string:
+ * - If handleInherit is true and value is "inherit", falls through to parent/default
+ *
+ * @param ctx - ExecutionContext from gadget execution
+ * @param gadgetName - Name of the subagent gadget (e.g., "BrowseWeb")
+ * @param options - Resolution options
+ * @returns Resolved value
+ *
+ * @example
+ * ```typescript
+ * const model = resolveValue(ctx, "BrowseWeb", {
+ *   runtime: params.model,
+ *   subagentKey: "model",
+ *   parentKey: "model",
+ *   defaultValue: "sonnet",
+ *   handleInherit: true,
+ * });
+ * ```
+ */
+declare function resolveValue<T>(ctx: ExecutionContext, gadgetName: string, options: ResolveValueOptions<T>): T;
+/**
+ * Bulk configuration resolution for subagent gadgets.
+ *
+ * Takes a map of config keys to their resolution options and returns
+ * a fully resolved configuration object.
+ *
+ * @param ctx - ExecutionContext from gadget execution
+ * @param gadgetName - Name of the subagent gadget (e.g., "BrowseWeb")
+ * @param config - Map of config keys to resolution options
+ * @returns Fully resolved configuration object
+ *
+ * @example
+ * ```typescript
+ * // Before: 27 lines of manual fallback logic
+ * const subagentConfig = ctx.subagentConfig?.Dhalsim ?? {};
+ * const parentModel = ctx.agentConfig?.model;
+ * const model = params.model ?? subagentConfig.model ?? parentModel ?? "sonnet";
+ * const maxIterations = params.maxIterations ?? subagentConfig.maxIterations ?? 15;
+ * const headless = params.headless ?? subagentConfig.headless ?? true;
+ *
+ * // After: One function call
+ * const { model, maxIterations, headless } = resolveConfig(ctx, "BrowseWeb", {
+ *   model: { runtime: params.model, subagentKey: "model", parentKey: "model", defaultValue: "sonnet", handleInherit: true },
+ *   maxIterations: { runtime: params.maxIterations, subagentKey: "maxIterations", defaultValue: 15 },
+ *   headless: { runtime: params.headless, subagentKey: "headless", defaultValue: true },
+ * });
+ * ```
+ */
+declare function resolveConfig<T extends Record<string, unknown>>(ctx: ExecutionContext, gadgetName: string, config: {
+    [K in keyof T]: ResolveValueOptions<T[K]>;
+}): T;
+/**
+ * Convenience function for resolving subagent model with "inherit" support.
+ *
+ * This is the most common resolution pattern for subagent gadgets:
+ * - Use runtime model if provided
+ * - Check subagent config for model override
+ * - Inherit parent model if configured
+ * - Fall back to default
+ *
+ * @param ctx - ExecutionContext from gadget execution
+ * @param gadgetName - Name of the subagent gadget
+ * @param runtimeModel - Model from gadget parameters
+ * @param defaultModel - Default model if nothing else specified
+ * @returns Resolved model string
+ *
+ * @example
+ * ```typescript
+ * const model = resolveSubagentModel(ctx, "BrowseWeb", params.model, "sonnet");
+ * ```
+ */
+declare function resolveSubagentModel(ctx: ExecutionContext, gadgetName: string, runtimeModel: string | undefined, defaultModel: string): string;
+
 /**
  * Base Provider Adapter
  *
@@ -2621,4 +2455,43 @@ declare class OpenAIChatProvider extends BaseProviderAdapter {
 }
 declare function createOpenAIProviderFromEnv(): OpenAIChatProvider | null;
 
-export { AbortException, AbstractGadget, AgentHooks, AnthropicMessagesProvider, CompactionConfig, CompactionContext, CompactionEvent, CompactionManager, CompactionResult, CompactionStats, CompactionStrategy, ConversationManager, type CreateGadgetConfig, ExecutionContext, Gadget, GadgetCallParser, type GadgetConfig, GadgetExample, GadgetExecuteResultWithMedia, GadgetExecuteReturn, GadgetExecutionResult, GadgetExecutor, GadgetMediaOutput, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HintTemplate, type HintsConfig, HookPresets, HumanInputRequiredException, HybridStrategy, IConversationManager, type IterationHintOptions, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, LLMist, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, MediaKind, MediaMetadata, MediaStore, MessageContent, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, type ParallelGadgetHintOptions, ParsedGadgetCall, ProviderAdapter, ResolvedCompactionConfig, SlidingWindowStrategy, type StoredOutput, StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, SubagentEvent, SummarizationStrategy, TaskCompletionSignal, TimeoutException, TokenUsage, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createLogger, createMediaOutput, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, iterationProgressHint, parallelGadgetHint, resolveModel, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, validateAndApplyDefaults, validateGadgetParams };
+/**
+ * Get host llmist exports from execution context.
+ *
+ * External gadgets MUST use this instead of importing classes directly from 'llmist'
+ * to ensure they use the same version as the host CLI, enabling proper tree sharing
+ * and avoiding the "dual-package problem".
+ *
+ * @param ctx - The execution context passed to gadget.execute()
+ * @returns The host's llmist exports (AgentBuilder, Gadget, etc.)
+ * @throws Error if ctx or ctx.hostExports is undefined
+ *
+ * @example
+ * ```typescript
+ * import { getHostExports, Gadget, z } from 'llmist';
+ * import type { ExecutionContext } from 'llmist';
+ *
+ * class BrowseWeb extends Gadget({
+ *   name: 'BrowseWeb',
+ *   description: 'Browse a website autonomously',
+ *   schema: z.object({ task: z.string(), url: z.string() }),
+ * }) {
+ *   async execute(params: this['params'], ctx?: ExecutionContext) {
+ *     // Get host's AgentBuilder to ensure tree sharing works correctly
+ *     const { AgentBuilder } = getHostExports(ctx!);
+ *
+ *     const agent = new AgentBuilder()
+ *       .withParentContext(ctx!)
+ *       .withGadgets(Navigate, Click, Screenshot)
+ *       .ask(params.task);
+ *
+ *     for await (const event of agent.run()) {
+ *       // Events flow through host's shared tree
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function getHostExports(ctx: ExecutionContext): HostExports;
+
+export { AbortException, AbstractGadget, AgentHooks, AnthropicMessagesProvider, CompactionConfig, CompactionContext, CompactionEvent, CompactionManager, CompactionResult, CompactionStats, CompactionStrategy, ConversationManager, ExecutionContext, ExecutionTree, GadgetCallParser, GadgetExecuteResultWithMedia, GadgetExecutionResult, GadgetExecutor, GadgetMediaOutput, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HintTemplate, type HintsConfig, HookPresets, HostExports, HumanInputRequiredException, HybridStrategy, IConversationManager, type IterationHintOptions, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, LLMist, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, MediaKind, MediaMetadata, MediaStore, MessageContent, ModelDescriptor, ModelRegistry, ModelSpec, NodeId, OpenAIChatProvider, type ParallelGadgetHintOptions, ParsedGadgetCall, ProviderAdapter, type ResolveValueOptions, ResolvedCompactionConfig, SlidingWindowStrategy, type StoredOutput, StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, SubagentEvent, SummarizationStrategy, TaskCompletionSignal, TimeoutException, TokenUsage, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createLogger, createMediaOutput, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getHostExports, getModelId, getProvider, hasProviderPrefix, iterationProgressHint, parallelGadgetHint, resolveConfig, resolveModel, resolveSubagentModel, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, validateAndApplyDefaults, validateGadgetParams };