llmist 2.6.0 → 3.1.0

package/dist/{mock-stream-Jgg5u6Uf.d.ts → mock-stream-CTLm00_q.d.ts}

@@ -745,9 +745,9 @@ declare class ModelIdentifierParser {
  */
 
 /**
- * Options for quick execution methods.
+ * Options for text generation methods (complete/stream).
  */
-interface QuickOptions {
+interface TextGenerationOptions {
     /** Model to use (supports aliases like "gpt4", "sonnet", "flash") */
     model?: string;
     /** Temperature (0-1) */
@@ -772,7 +772,7 @@ interface QuickOptions {
  * console.log(answer); // "4" or "2+2 equals 4"
  * ```
  */
-declare function complete(client: LLMist, prompt: string, options?: QuickOptions): Promise<string>;
+declare function complete(client: LLMist, prompt: string, options?: TextGenerationOptions): Promise<string>;
 /**
  * Quick streaming - returns async generator of text chunks.
  *
@@ -790,7 +790,7 @@ declare function complete(client: LLMist, prompt: string, options?: QuickOptions
  * }
  * ```
  */
-declare function stream(client: LLMist, prompt: string, options?: QuickOptions): AsyncGenerator<string>;
+declare function stream(client: LLMist, prompt: string, options?: TextGenerationOptions): AsyncGenerator<string>;
 
 /**
  * Example of gadget usage to help LLMs understand proper invocation.
@@ -986,6 +986,25 @@ interface GadgetSkippedEvent {
     /** 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;
+}
 type StreamEvent = {
     type: "text";
     content: string;
@@ -1003,7 +1022,52 @@ type StreamEvent = {
 } | {
     type: "compaction";
     event: CompactionEvent;
-};
+} | StreamCompletionEvent;
+/**
+ * Information about an LLM call within a nested subagent.
+ * Used by parent agents to display real-time progress of subagent LLM calls.
+ */
+interface LLMCallInfo {
+    /** Iteration number within the subagent loop */
+    iteration: number;
+    /** Model identifier (e.g., "sonnet", "gpt-4o") */
+    model: string;
+    /** Input tokens sent to the LLM */
+    inputTokens?: number;
+    /** Output tokens received from the LLM */
+    outputTokens?: number;
+    /** Reason the LLM stopped generating (e.g., "stop", "tool_use") */
+    finishReason?: string;
+    /** Elapsed time in milliseconds */
+    elapsedMs?: number;
+}
+/**
+ * Event emitted by subagent gadgets to report internal agent activity.
+ * Enables real-time display of nested LLM calls and gadget executions.
+ *
+ * @example
+ * ```typescript
+ * // Forwarding events from subagent to parent
+ * for await (const event of subagent.run()) {
+ *   ctx.onNestedEvent?.({
+ *     type: event.type === "gadget_call" ? "gadget_call" : "gadget_result",
+ *     gadgetInvocationId: parentInvocationId,
+ *     depth: 1,
+ *     event,
+ *   });
+ * }
+ * ```
+ */
+interface NestedAgentEvent {
+    /** Type of nested event */
+    type: "llm_call_start" | "llm_call_end" | "gadget_call" | "gadget_result";
+    /** Invocation ID of the parent gadget this nested event belongs to */
+    gadgetInvocationId: string;
+    /** Nesting depth (1 = direct child, 2 = grandchild, etc.) */
+    depth: number;
+    /** The actual event data - either a StreamEvent or LLMCallInfo */
+    event: StreamEvent | LLMCallInfo;
+}
 
 type TextOnlyHandler = TextOnlyStrategy | TextOnlyGadgetConfig | TextOnlyCustomHandler;
 /**
@@ -1103,12 +1167,12 @@ interface CostReportingLLMist {
      * Quick completion - returns final text response.
      * Costs are automatically reported to the execution context.
      */
-    complete(prompt: string, options?: QuickOptions): Promise<string>;
+    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?: QuickOptions): AsyncGenerator<string>;
+    streamText(prompt: string, options?: TextGenerationOptions): AsyncGenerator<string>;
     /**
      * Low-level stream access for full control.
      * Costs are automatically reported based on usage metadata in chunks.
@@ -1257,16 +1321,144 @@ interface ExecutionContext {
      * ```
      */
     signal: AbortSignal;
+    /**
+     * Parent agent configuration for subagents to inherit.
+     *
+     * Contains the model and settings of the agent that invoked this gadget.
+     * Subagent gadgets (like BrowseWeb) can use this to inherit the parent's
+     * model by default, rather than using hardcoded defaults.
+     *
+     * This is optional - it will be `undefined` for:
+     * - Gadgets executed via CLI `gadget run` command
+     * - Direct gadget testing without agent context
+     *
+     * @example
+     * ```typescript
+     * execute: async (params, ctx) => {
+     *   // Inherit parent model unless explicitly specified
+     *   const model = params.model ?? ctx.agentConfig?.model ?? "sonnet";
+     *
+     *   const agent = new AgentBuilder(new LLMist())
+     *     .withModel(model)
+     *     .build();
+     *   // ...
+     * }
+     * ```
+     */
+    agentConfig?: AgentContextConfig;
+    /**
+     * Subagent-specific configuration overrides from CLI config.
+     *
+     * Contains per-subagent settings defined in `[subagents.Name]` or
+     * `[profile.subagents.Name]` sections of cli.toml. Allows users to
+     * customize subagent behavior without modifying gadget parameters.
+     *
+     * Resolution priority (highest to lowest):
+     * 1. Runtime params (explicit gadget call)
+     * 2. Profile-level subagent config
+     * 3. Global subagent config
+     * 4. Parent model (if "inherit")
+     * 5. Package defaults
+     *
+     * @example
+     * ```typescript
+     * execute: async (params, ctx) => {
+     *   const subagentConfig = ctx.subagentConfig?.BrowseWeb ?? {};
+     *
+     *   const model = params.model
+     *     ?? subagentConfig.model
+     *     ?? ctx.agentConfig?.model
+     *     ?? "sonnet";
+     *
+     *   const maxIterations = params.maxIterations
+     *     ?? subagentConfig.maxIterations
+     *     ?? 15;
+     *   // ...
+     * }
+     * ```
+     */
+    subagentConfig?: SubagentConfigMap;
+    /**
+     * Unique invocation ID for this gadget execution.
+     * Used by `withParentContext()` to identify which parent gadget
+     * nested events belong to.
+     */
+    invocationId?: string;
+    /**
+     * Callback for subagent gadgets to report internal events to the parent.
+     *
+     * When provided, subagent gadgets (like BrowseWeb) can use this callback
+     * to report their internal LLM calls and gadget executions in real-time.
+     * This enables the parent agent to display nested progress indicators.
+     *
+     * **Recommended:** Use `builder.withParentContext(ctx)` instead of calling
+     * this directly - it handles all the forwarding automatically.
+     *
+     * @example
+     * ```typescript
+     * // In a subagent gadget like BrowseWeb - just ONE LINE needed:
+     * execute: async (params, ctx) => {
+     *   const agent = new AgentBuilder(client)
+     *     .withModel(model)
+     *     .withGadgets(Navigate, Click)
+     *     .withParentContext(ctx)  // <-- Enables automatic event forwarding!
+     *     .ask(task);
+     *
+     *   for await (const event of agent.run()) {
+     *     // Events automatically forwarded - just process normally
+     *   }
+     * }
+     * ```
+     */
+    onNestedEvent?: (event: NestedAgentEvent) => void;
+}
+/**
+ * Parent agent configuration passed to gadgets.
+ * Contains settings that subagents can inherit.
+ */
+interface AgentContextConfig {
+    /** Model identifier used by the parent agent */
+    model: string;
+    /** Temperature setting used by the parent agent */
+    temperature?: number;
 }
+/**
+ * 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 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;
+    /** Additional subagent-specific options */
+    [key: string]: unknown;
+}
+/**
+ * Map of subagent names to their configurations.
+ */
+type SubagentConfigMap = Record<string, SubagentConfig>;
 
 /**
- * Internal base class for gadgets. Most users should use the `Gadget` class
- * (formerly TypedGadget) or `createGadget()` function instead, as they provide
- * better type safety and simpler APIs.
+ * 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.
  *
- * @internal
+ * Extend this class directly only when you need advanced control over gadget behavior.
  */
-declare abstract class BaseGadget {
+declare abstract class AbstractGadget {
     /**
      * The name of the gadget. Used for identification when LLM calls it.
      * If not provided, defaults to the class name.
@@ -1332,14 +1524,14 @@ declare abstract class BaseGadget {
      */
     abstract execute(params: Record<string, unknown>, ctx?: ExecutionContext): GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
     /**
-     * Throws an AbortError if the execution has been aborted.
+     * 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 AbortError if ctx.signal.aborted is true
+     * @throws AbortException if ctx.signal.aborted is true
      *
      * @example
      * ```typescript
@@ -1697,7 +1889,7 @@ type HintTemplate = string | ((context: HintContext) => string);
  *
  * @example
  * ```typescript
- * const customConfig: PromptConfig = {
+ * const customConfig: PromptTemplateConfig = {
  *   mainInstruction: "USE ONLY THE GADGET MARKERS BELOW:",
  *   criticalUsage: "Important: Follow the exact format shown.",
  *   rules: (ctx) => [
@@ -1708,7 +1900,7 @@ type HintTemplate = string | ((context: HintContext) => string);
  * };
  * ```
  */
-interface PromptConfig {
+interface PromptTemplateConfig {
     /**
      * Main instruction block that appears at the start of the gadget system prompt.
      * Default emphasizes using text markers instead of function calling.
@@ -1762,7 +1954,7 @@ declare const DEFAULT_HINTS: {
 /**
  * Default prompt templates used by llmist.
  */
-declare const DEFAULT_PROMPTS: Required<Omit<PromptConfig, "rules" | "customExamples" | "parallelGadgetsHint" | "iterationProgressHint"> & {
+declare const DEFAULT_PROMPTS: Required<Omit<PromptTemplateConfig, "rules" | "customExamples" | "parallelGadgetsHint" | "iterationProgressHint"> & {
     rules: (context: PromptContext) => string[];
     customExamples: null;
 }>;
@@ -1773,7 +1965,7 @@ declare function resolvePromptTemplate(template: PromptTemplate | undefined, def
 /**
  * Resolve rules template to an array of strings.
  */
-declare function resolveRulesTemplate(rules: PromptConfig["rules"] | undefined, context: PromptContext): string[];
+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.
@@ -1785,14 +1977,14 @@ declare function resolveRulesTemplate(rules: PromptConfig["rules"] | undefined,
  */
 declare function resolveHintTemplate(template: HintTemplate | undefined, defaultValue: string, context: HintContext): string;
 
-type LLMRole = "system" | "user" | "assistant";
+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: LLMRole;
+    role: MessageRole;
     content: MessageContent;
     name?: string;
     metadata?: Record<string, unknown>;
@@ -1804,7 +1996,7 @@ interface LLMMessage {
  * @param content - Message content (string or ContentPart[])
  * @returns Array of content parts
  */
-declare function normalizeContent(content: MessageContent): ContentPart[];
+declare function normalizeMessageContent(content: MessageContent): ContentPart[];
 /**
  * Extract text from message content.
  * Concatenates all text parts in the content.
@@ -1812,21 +2004,21 @@ declare function normalizeContent(content: MessageContent): ContentPart[];
  * @param content - Message content (string or ContentPart[])
  * @returns Combined text from all text parts
  */
-declare function extractText(content: MessageContent): string;
+declare function extractMessageText(content: MessageContent): string;
 declare class LLMMessageBuilder {
     private readonly messages;
     private startPrefix;
     private endPrefix;
     private argPrefix;
     private promptConfig;
-    constructor(promptConfig?: 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: BaseGadget[], options?: {
+    addGadgets(gadgets: AbstractGadget[], options?: {
         startPrefix?: string;
         endPrefix?: string;
         argPrefix?: string;
@@ -1921,7 +2113,17 @@ declare class LLMMessageBuilder {
      * ```
      */
     addUserMultimodal(parts: ContentPart[]): this;
-    addGadgetCall(gadget: string, parameters: Record<string, unknown>, result: string, media?: GadgetMediaOutput[], mediaIds?: string[]): 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.
+     *
+     * @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 media - Optional media outputs from the gadget
+     * @param mediaIds - Optional IDs for the media outputs
+     */
+    addGadgetCallResult(gadget: string, parameters: Record<string, unknown>, result: string, media?: GadgetMediaOutput[], mediaIds?: string[]): this;
     /**
      * Format parameters as Block format with JSON Pointer paths.
      * Uses the configured argPrefix for consistency with system prompt.
@@ -2114,7 +2316,7 @@ declare class TextNamespace {
      * @param options - Optional configuration
      * @returns Complete text response
      */
-    complete(prompt: string, options?: QuickOptions): Promise<string>;
+    complete(prompt: string, options?: TextGenerationOptions): Promise<string>;
     /**
      * Stream text chunks.
      *
@@ -2122,7 +2324,7 @@ declare class TextNamespace {
      * @param options - Optional configuration
      * @returns Async generator yielding text chunks
      */
-    stream(prompt: string, options?: QuickOptions): AsyncGenerator<string>;
+    stream(prompt: string, options?: TextGenerationOptions): AsyncGenerator<string>;
 }
 
 /**
@@ -2345,7 +2547,7 @@ declare class LLMist {
      * });
      * ```
      */
-    static complete(prompt: string, options?: QuickOptions): Promise<string>;
+    static complete(prompt: string, options?: TextGenerationOptions): Promise<string>;
     /**
      * Quick streaming - returns async generator of text chunks.
      * Convenient for streaming responses without needing agent setup.
@@ -2369,7 +2571,7 @@ declare class LLMist {
      * }
      * ```
      */
-    static stream(prompt: string, options?: QuickOptions): AsyncGenerator<string>;
+    static stream(prompt: string, options?: TextGenerationOptions): AsyncGenerator<string>;
     /**
      * Instance method: Quick completion using this client instance.
      *
@@ -2377,7 +2579,7 @@ declare class LLMist {
      * @param options - Optional configuration
      * @returns Complete text response
      */
-    complete(prompt: string, options?: QuickOptions): Promise<string>;
+    complete(prompt: string, options?: TextGenerationOptions): Promise<string>;
     /**
      * Instance method: Quick streaming using this client instance.
      *
@@ -2385,7 +2587,7 @@ declare class LLMist {
      * @param options - Optional configuration
      * @returns Async generator yielding text chunks
      */
-    streamText(prompt: string, options?: QuickOptions): AsyncGenerator<string>;
+    streamText(prompt: string, options?: TextGenerationOptions): AsyncGenerator<string>;
     /**
      * Create a fluent agent builder.
      * Provides a chainable API for configuring and creating agents.
@@ -2432,8 +2634,8 @@ declare class LLMist {
     createAgent(): AgentBuilder;
 }
 
-type GadgetClass = new (...args: unknown[]) => BaseGadget;
-type GadgetOrClass = BaseGadget | GadgetClass;
+type GadgetClass = new (...args: unknown[]) => AbstractGadget;
+type GadgetOrClass = AbstractGadget | GadgetClass;
 declare class GadgetRegistry {
     private readonly gadgets;
     /**
@@ -2472,12 +2674,12 @@ declare class GadgetRegistry {
      * ```
      */
     registerMany(gadgets: GadgetOrClass[]): this;
-    register(name: string, gadget: BaseGadget): void;
-    registerByClass(gadget: BaseGadget): void;
-    get(name: string): BaseGadget | undefined;
+    register(name: string, gadget: AbstractGadget): void;
+    registerByClass(gadget: AbstractGadget): void;
+    get(name: string): AbstractGadget | undefined;
     has(name: string): boolean;
     getNames(): string[];
-    getAll(): BaseGadget[];
+    getAll(): AbstractGadget[];
     unregister(name: string): boolean;
     clear(): void;
 }
@@ -3320,8 +3522,8 @@ interface AgentOptions {
     logger?: Logger<ILogObj>;
     /** Clean hooks system */
     hooks?: AgentHooks;
-    /** Callback for human input */
-    onHumanInputRequired?: (question: string) => Promise<string>;
+    /** Callback for requesting human input during execution */
+    requestHumanInput?: (question: string) => Promise<string>;
     /** Custom gadget start prefix */
     gadgetStartPrefix?: string;
     /** Custom gadget end prefix */
@@ -3349,8 +3551,8 @@ interface AgentOptions {
     };
     /** Stop on gadget error */
     stopOnGadgetError?: boolean;
-    /** Custom error continuation logic */
-    shouldContinueAfterError?: (context: {
+    /** Custom error recovery logic */
+    canRecoverFromGadgetError?: (context: {
         error: string;
         gadgetName: string;
         errorType: "parse" | "validation" | "execution";
@@ -3359,7 +3561,7 @@ interface AgentOptions {
     /** Default gadget timeout */
     defaultGadgetTimeoutMs?: number;
     /** Custom prompt configuration for gadget system prompts */
-    promptConfig?: PromptConfig;
+    promptConfig?: PromptTemplateConfig;
     /** Enable gadget output limiting (default: true) */
     gadgetOutputLimit?: boolean;
     /** Max gadget output as % of model context window (default: 15) */
@@ -3368,6 +3570,10 @@ interface AgentOptions {
     compactionConfig?: CompactionConfig;
     /** Optional abort signal for cancelling requests mid-flight */
     signal?: AbortSignal;
+    /** Subagent-specific configuration overrides (from CLI config) */
+    subagentConfig?: SubagentConfigMap;
+    /** Callback for subagent gadgets to report nested events to parent */
+    onNestedEvent?: (event: NestedAgentEvent) => void;
 }
 /**
  * Agent: Lean orchestrator that delegates to StreamProcessor.
@@ -3396,20 +3602,23 @@ declare class Agent {
     private readonly gadgetStartPrefix?;
     private readonly gadgetEndPrefix?;
     private readonly gadgetArgPrefix?;
-    private readonly onHumanInputRequired?;
+    private readonly requestHumanInput?;
     private readonly textOnlyHandler;
     private readonly textWithGadgetsHandler?;
     private readonly stopOnGadgetError;
-    private readonly shouldContinueAfterError?;
+    private readonly canRecoverFromGadgetError?;
     private readonly defaultGadgetTimeoutMs?;
     private readonly defaultMaxTokens?;
-    private userPromptProvided;
+    private hasUserPrompt;
     private readonly outputStore;
     private readonly outputLimitEnabled;
     private readonly outputLimitCharLimit;
     private readonly compactionManager?;
     private readonly mediaStore;
     private readonly signal?;
+    private readonly agentContextConfig;
+    private readonly subagentConfig?;
+    private readonly onNestedEvent?;
     /**
      * Creates a new Agent instance.
      * @internal This constructor is private. Use LLMist.createAgent() or AgentBuilder instead.
@@ -3526,10 +3735,10 @@ declare class Agent {
      */
     private resolveMaxTokensFromCatalog;
     /**
-     * Merge the output limiter interceptor into user-provided hooks.
+     * Chain the output limiter interceptor with user-provided hooks.
      * The limiter runs first, then chains to any user interceptor.
      */
-    private mergeOutputLimiterHook;
+    private chainOutputLimiterWithUserHooks;
     /**
      * Run agent with named event handlers (syntactic sugar).
      *
@@ -3605,20 +3814,23 @@ declare class AgentBuilder {
     private promptConfig?;
     private gadgets;
     private initialMessages;
-    private onHumanInputRequired?;
+    private requestHumanInput?;
     private gadgetStartPrefix?;
     private gadgetEndPrefix?;
     private gadgetArgPrefix?;
     private textOnlyHandler?;
     private textWithGadgetsHandler?;
     private stopOnGadgetError?;
-    private shouldContinueAfterError?;
+    private canRecoverFromGadgetError?;
     private defaultGadgetTimeoutMs?;
     private gadgetOutputLimit?;
     private gadgetOutputLimitPercent?;
     private compactionConfig?;
     private signal?;
     private trailingMessage?;
+    private subagentConfig?;
+    private nestedEventCallback?;
+    private parentContext?;
     constructor(client?: LLMist);
     /**
      * Set the model to use.
@@ -3689,13 +3901,13 @@ declare class AgentBuilder {
      *
      * @example
      * ```typescript
-     * .withPromptConfig({
+     * .withPromptTemplateConfig({
      *   mainInstruction: "Use the gadget markers below:",
      *   rules: ["Always use markers", "Never use function calling"]
      * })
      * ```
      */
-    withPromptConfig(config: PromptConfig): this;
+    withPromptTemplateConfig(config: PromptTemplateConfig): this;
     /**
      * Add gadgets (classes or instances).
      * Can be called multiple times to add more gadgets.
@@ -3874,9 +4086,9 @@ declare class AgentBuilder {
      * Provides fine-grained control over whether to continue after different types of errors.
      * Overrides `stopOnGadgetError` when provided.
      *
-     * **Note:** This builder method configures the underlying `shouldContinueAfterError` option
+     * **Note:** This builder method configures the underlying `canRecoverFromGadgetError` option
      * in `AgentOptions`. The method is named `withErrorHandler` for better developer experience,
-     * but maps to the `shouldContinueAfterError` property internally.
+     * but maps to the `canRecoverFromGadgetError` property internally.
      *
      * @param handler - Function that decides whether to continue after an error.
      *                  Return `true` to continue execution, `false` to stop.
@@ -4016,6 +4228,80 @@ declare class AgentBuilder {
      * ```
      */
     withSignal(signal: AbortSignal): 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.
+     *
+     * @param config - Subagent configuration map keyed by gadget name
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withSubagentConfig({
+     *   BrowseWeb: { model: "inherit", maxIterations: 20, headless: true },
+     *   CodeAnalyzer: { model: "sonnet", maxIterations: 10 }
+     * })
+     * ```
+     */
+    withSubagentConfig(config: SubagentConfigMap): this;
+    /**
+     * Set the callback for nested subagent events.
+     *
+     * Subagent gadgets (like BrowseWeb) can use ExecutionContext.onNestedEvent
+     * to report their internal LLM calls and gadget executions in real-time.
+     * This callback receives those events, enabling hierarchical progress display.
+     *
+     * @param callback - Function to handle nested agent events
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withNestedEventCallback((event) => {
+     *   if (event.type === "llm_call_start") {
+     *     console.log(`  Nested LLM #${event.event.iteration} starting...`);
+     *   } else if (event.type === "gadget_call") {
+     *     console.log(`    ⏵ ${event.event.call.gadgetName}...`);
+     *   }
+     * })
+     * ```
+     */
+    withNestedEventCallback(callback: (event: NestedAgentEvent) => void): this;
+    /**
+     * Enable automatic nested event forwarding to parent agent.
+     *
+     * When building a subagent inside a gadget, call this method to automatically
+     * forward all LLM calls and gadget events to the parent agent. This enables
+     * hierarchical progress display without any manual event handling.
+     *
+     * The method extracts `invocationId` and `onNestedEvent` from the execution
+     * context and sets up automatic forwarding via hooks and event wrapping.
+     *
+     * @param ctx - ExecutionContext passed to the gadget's execute() method
+     * @param depth - Nesting depth (default: 1 for direct child)
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * // In a subagent gadget like BrowseWeb - ONE LINE enables auto-forwarding:
+     * execute: async (params, ctx) => {
+     *   const agent = new AgentBuilder(client)
+     *     .withModel(model)
+     *     .withGadgets(Navigate, Click, Screenshot)
+     *     .withParentContext(ctx)  // <-- This is all you need!
+     *     .ask(params.task);
+     *
+     *   for await (const event of agent.run()) {
+     *     // Events automatically forwarded - just process normally
+     *     if (event.type === "text") {
+     *       result = event.content;
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    withParentContext(ctx: ExecutionContext, depth?: number): this;
     /**
      * Add an ephemeral trailing message that appears at the end of each LLM request.
      *
@@ -4065,7 +4351,9 @@ declare class AgentBuilder {
      */
     withSyntheticGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): this;
     /**
-     * Compose the final hooks, including trailing message if configured.
+     * Compose the final hooks, including:
+     * - Trailing message injection (if configured)
+     * - Nested event forwarding for LLM calls (if parentContext is set)
      */
     private composeHooks;
     /**
@@ -4237,7 +4525,7 @@ interface IConversationManager {
      * Adds a gadget call and its result to the conversation.
      * Optionally includes media outputs (images, audio, etc.) for multimodal results.
      */
-    addGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string, media?: GadgetMediaOutput[], mediaIds?: string[]): void;
+    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, media?: GadgetMediaOutput[], mediaIds?: string[]): void;
     /**
      * Gets the complete conversation history including base messages (system prompts, gadget instructions).
      */
@@ -4973,4 +5261,4 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
-export { type ImageGenerationResult as $, type AgentHooks as A, BaseGadget as B, type CompactionConfig as C, GadgetRegistry as D, MediaStore as E, type ExecutionContext as F, type GadgetMediaOutput as G, type HintTemplate as H, type IConversationManager as I, type GadgetExecuteReturn as J, type GadgetExample as K, type LLMMessage as L, MockProviderAdapter as M, type GadgetExecutionResult as N, type MediaKind as O, type ParsedGadgetCall as P, type MediaMetadata as Q, type ResolvedCompactionConfig as R, type StreamEvent as S, type TokenUsage as T, type GadgetExecuteResultWithMedia as U, type ProviderAdapter as V, type ModelDescriptor as W, type ModelSpec as X, type LLMGenerationOptions as Y, type ImageModelSpec as Z, type ImageGenerationOptions as _, type LLMStream as a, toBase64 as a$, type SpeechModelSpec as a0, type SpeechGenerationOptions as a1, type SpeechGenerationResult as a2, type HistoryMessage as a3, type TrailingMessage as a4, type TrailingMessageContext as a5, AgentBuilder as a6, type EventHandlers as a7, collectEvents as a8, collectText as a9, type Observers as aA, DEFAULT_COMPACTION_CONFIG as aB, DEFAULT_SUMMARIZATION_PROMPT as aC, type LLMistOptions as aD, type AudioContentPart as aE, type AudioMimeType as aF, type AudioSource as aG, type ContentPart as aH, type ImageBase64Source as aI, type ImageContentPart as aJ, type ImageMimeType as aK, type ImageSource as aL, type ImageUrlSource as aM, type TextContentPart as aN, audioFromBase64 as aO, audioFromBuffer as aP, detectAudioMimeType as aQ, detectImageMimeType as aR, imageFromBase64 as aS, imageFromBuffer as aT, imageFromUrl as aU, isAudioPart as aV, isDataUrl as aW, isImagePart as aX, isTextPart as aY, parseDataUrl as aZ, text as a_, runWithHandlers as aa, type AfterGadgetExecutionAction as ab, type AfterGadgetExecutionControllerContext as ac, type AfterLLMCallAction as ad, type AfterLLMCallControllerContext as ae, type AfterLLMErrorAction as af, type AgentOptions as ag, type BeforeGadgetExecutionAction as ah, type BeforeLLMCallAction as ai, type ChunkInterceptorContext as aj, type Controllers as ak, type GadgetExecutionControllerContext as al, type GadgetParameterInterceptorContext as am, type GadgetResultInterceptorContext as an, type Interceptors as ao, type LLMCallControllerContext as ap, type LLMErrorControllerContext as aq, type MessageInterceptorContext as ar, type MessageTurn as as, type ObserveChunkContext as at, type ObserveCompactionContext as au, type ObserveGadgetCompleteContext as av, type ObserveGadgetStartContext as aw, type ObserveLLMCallContext as ax, type ObserveLLMCompleteContext as ay, type ObserveLLMErrorContext as az, type LLMStreamChunk as b, type LLMRole as b0, extractText as b1, LLMMessageBuilder as b2, normalizeContent as b3, type CostEstimate as b4, type ModelFeatures as b5, type ModelLimits as b6, type ModelPricing as b7, type VisionAnalyzeOptions as b8, type VisionAnalyzeResult as b9, type ProviderIdentifier as ba, ModelIdentifierParser as bb, type HintContext as bc, type PromptConfig as bd, type PromptContext as be, type PromptTemplate as bf, DEFAULT_HINTS as bg, DEFAULT_PROMPTS as bh, resolveHintTemplate as bi, resolvePromptTemplate as bj, resolveRulesTemplate as bk, type QuickOptions as bl, complete as bm, stream as bn, type GadgetClass as bo, type GadgetOrClass as bp, type CostReportingLLMist as bq, type GadgetExecuteResult as br, type GadgetSkippedEvent as bs, type StoredMedia as bt, type TextOnlyAction as bu, type TextOnlyContext as bv, type TextOnlyCustomHandler as bw, type TextOnlyGadgetConfig as bx, type TextOnlyHandler as by, type TextOnlyStrategy as bz, createMockAdapter as c, MockBuilder as d, createMockClient as e, MockManager as f, getMockManager as g, createMockStream as h, createTextMockStream as i, type MockAudioData as j, type MockImageData as k, type MockMatcher as l, mockLLM as m, type MockMatcherContext as n, type MockOptions as o, type MockRegistration as p, type MockResponse as q, type MockStats as r, ModelRegistry as s, LLMist as t, type CompactionEvent as u, type CompactionStats as v, type CompactionStrategy as w, type CompactionContext as x, type CompactionResult as y, type MessageContent as z };
+export { type LLMGenerationOptions as $, AbstractGadget as A, type MessageContent as B, type CompactionConfig as C, GadgetRegistry as D, MediaStore as E, type AgentContextConfig as F, type GadgetMediaOutput as G, type HintTemplate as H, type IConversationManager as I, type SubagentConfigMap as J, type ExecutionContext as K, type LLMMessage as L, MockProviderAdapter as M, type NestedAgentEvent as N, type GadgetExecuteReturn as O, type GadgetExample as P, type ParsedGadgetCall as Q, type ResolvedCompactionConfig as R, type StreamEvent as S, type TokenUsage as T, type GadgetExecutionResult as U, type MediaKind as V, type MediaMetadata as W, type GadgetExecuteResultWithMedia as X, type ProviderAdapter as Y, type ModelDescriptor as Z, type ModelSpec as _, type LLMStream as a, isTextPart as a$, type ImageModelSpec as a0, type ImageGenerationOptions as a1, type ImageGenerationResult as a2, type SpeechModelSpec as a3, type SpeechGenerationOptions as a4, type SpeechGenerationResult as a5, type HistoryMessage as a6, type TrailingMessage as a7, type TrailingMessageContext as a8, AgentBuilder as a9, type ObserveLLMCallContext as aA, type ObserveLLMCompleteContext as aB, type ObserveLLMErrorContext as aC, type Observers as aD, DEFAULT_COMPACTION_CONFIG as aE, DEFAULT_SUMMARIZATION_PROMPT as aF, type LLMistOptions as aG, type AudioContentPart as aH, type AudioMimeType as aI, type AudioSource as aJ, type ContentPart as aK, type ImageBase64Source as aL, type ImageContentPart as aM, type ImageMimeType as aN, type ImageSource as aO, type ImageUrlSource as aP, type TextContentPart as aQ, audioFromBase64 as aR, audioFromBuffer as aS, detectAudioMimeType as aT, detectImageMimeType as aU, imageFromBase64 as aV, imageFromBuffer as aW, imageFromUrl as aX, isAudioPart as aY, isDataUrl as aZ, isImagePart as a_, type EventHandlers as aa, collectEvents as ab, collectText as ac, runWithHandlers as ad, type AfterGadgetExecutionAction as ae, type AfterGadgetExecutionControllerContext as af, type AfterLLMCallAction as ag, type AfterLLMCallControllerContext as ah, type AfterLLMErrorAction as ai, type AgentOptions as aj, type BeforeGadgetExecutionAction as ak, type BeforeLLMCallAction as al, type ChunkInterceptorContext as am, type Controllers as an, type GadgetExecutionControllerContext as ao, type GadgetParameterInterceptorContext as ap, type GadgetResultInterceptorContext as aq, type Interceptors as ar, type LLMCallControllerContext as as, type LLMErrorControllerContext as at, type MessageInterceptorContext as au, type MessageTurn as av, type ObserveChunkContext as aw, type ObserveCompactionContext as ax, type ObserveGadgetCompleteContext as ay, type ObserveGadgetStartContext as az, type LLMStreamChunk as b, parseDataUrl as b0, text as b1, toBase64 as b2, type MessageRole as b3, extractMessageText as b4, LLMMessageBuilder as b5, normalizeMessageContent as b6, type CostEstimate as b7, type ModelFeatures as b8, type ModelLimits as b9, type TextOnlyGadgetConfig as bA, type TextOnlyHandler as bB, type TextOnlyStrategy as bC, type ModelPricing as ba, type VisionAnalyzeOptions as bb, type VisionAnalyzeResult as bc, type ProviderIdentifier as bd, ModelIdentifierParser as be, type HintContext as bf, type PromptContext as bg, type PromptTemplate as bh, type PromptTemplateConfig as bi, DEFAULT_HINTS as bj, DEFAULT_PROMPTS as bk, resolveHintTemplate as bl, resolvePromptTemplate as bm, resolveRulesTemplate as bn, type TextGenerationOptions as bo, complete as bp, stream as bq, type GadgetClass as br, type GadgetOrClass as bs, type CostReportingLLMist as bt, type GadgetExecuteResult as bu, type GadgetSkippedEvent as bv, type StoredMedia as bw, type TextOnlyAction as bx, type TextOnlyContext as by, type TextOnlyCustomHandler as bz, createMockAdapter as c, MockBuilder as d, createMockClient as e, MockManager as f, getMockManager as g, createMockStream as h, createTextMockStream as i, type MockAudioData as j, type MockImageData as k, type MockMatcher as l, mockLLM as m, type MockMatcherContext as n, type MockOptions as o, type MockRegistration as p, type MockResponse as q, type MockStats as r, type AgentHooks as s, ModelRegistry as t, LLMist as u, type CompactionEvent as v, type CompactionStats as w, type CompactionStrategy as x, type CompactionContext as y, type CompactionResult as z };