llmist 3.0.0 → 3.1.0

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

@@ -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;
 /**
@@ -1314,6 +1378,39 @@ interface ExecutionContext {
      * ```
      */
     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.
@@ -3475,6 +3572,8 @@ interface AgentOptions {
     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.
@@ -3519,6 +3618,7 @@ declare class Agent {
     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.
@@ -3729,6 +3829,8 @@ declare class AgentBuilder {
     private signal?;
     private trailingMessage?;
     private subagentConfig?;
+    private nestedEventCallback?;
+    private parentContext?;
     constructor(client?: LLMist);
     /**
      * Set the model to use.
@@ -4144,6 +4246,62 @@ declare class AgentBuilder {
      * ```
      */
     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.
      *
@@ -4193,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;
     /**
@@ -5101,4 +5261,4 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
-export { type ImageModelSpec 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 GadgetExecuteReturn as N, type GadgetExample as O, type ParsedGadgetCall as P, type GadgetExecutionResult as Q, type ResolvedCompactionConfig as R, type StreamEvent as S, type TokenUsage as T, type MediaKind as U, type MediaMetadata as V, type GadgetExecuteResultWithMedia as W, type ProviderAdapter as X, type ModelDescriptor as Y, type ModelSpec as Z, type LLMGenerationOptions as _, type LLMStream as a, parseDataUrl as a$, type ImageGenerationOptions as a0, type ImageGenerationResult as a1, type SpeechModelSpec as a2, type SpeechGenerationOptions as a3, type SpeechGenerationResult as a4, type HistoryMessage as a5, type TrailingMessage as a6, type TrailingMessageContext as a7, AgentBuilder as a8, type EventHandlers as a9, type ObserveLLMCompleteContext as aA, type ObserveLLMErrorContext as aB, type Observers as aC, DEFAULT_COMPACTION_CONFIG as aD, DEFAULT_SUMMARIZATION_PROMPT as aE, type LLMistOptions as aF, type AudioContentPart as aG, type AudioMimeType as aH, type AudioSource as aI, type ContentPart as aJ, type ImageBase64Source as aK, type ImageContentPart as aL, type ImageMimeType as aM, type ImageSource as aN, type ImageUrlSource as aO, type TextContentPart as aP, audioFromBase64 as aQ, audioFromBuffer as aR, detectAudioMimeType as aS, detectImageMimeType as aT, imageFromBase64 as aU, imageFromBuffer as aV, imageFromUrl as aW, isAudioPart as aX, isDataUrl as aY, isImagePart as aZ, isTextPart as a_, collectEvents as aa, collectText as ab, runWithHandlers as ac, type AfterGadgetExecutionAction as ad, type AfterGadgetExecutionControllerContext as ae, type AfterLLMCallAction as af, type AfterLLMCallControllerContext as ag, type AfterLLMErrorAction as ah, type AgentOptions as ai, type BeforeGadgetExecutionAction as aj, type BeforeLLMCallAction as ak, type ChunkInterceptorContext as al, type Controllers as am, type GadgetExecutionControllerContext as an, type GadgetParameterInterceptorContext as ao, type GadgetResultInterceptorContext as ap, type Interceptors as aq, type LLMCallControllerContext as ar, type LLMErrorControllerContext as as, type MessageInterceptorContext as at, type MessageTurn as au, type ObserveChunkContext as av, type ObserveCompactionContext as aw, type ObserveGadgetCompleteContext as ax, type ObserveGadgetStartContext as ay, type ObserveLLMCallContext as az, type LLMStreamChunk as b, text as b0, toBase64 as b1, type MessageRole as b2, extractMessageText as b3, LLMMessageBuilder as b4, normalizeMessageContent as b5, type CostEstimate as b6, type ModelFeatures as b7, type ModelLimits as b8, type ModelPricing as b9, type TextOnlyHandler as bA, type TextOnlyStrategy as bB, type VisionAnalyzeOptions as ba, type VisionAnalyzeResult as bb, type ProviderIdentifier as bc, ModelIdentifierParser as bd, type HintContext as be, type PromptContext as bf, type PromptTemplate as bg, type PromptTemplateConfig as bh, DEFAULT_HINTS as bi, DEFAULT_PROMPTS as bj, resolveHintTemplate as bk, resolvePromptTemplate as bl, resolveRulesTemplate as bm, type TextGenerationOptions as bn, complete as bo, stream as bp, type GadgetClass as bq, type GadgetOrClass as br, type CostReportingLLMist as bs, type GadgetExecuteResult as bt, type GadgetSkippedEvent as bu, type StoredMedia as bv, type TextOnlyAction as bw, type TextOnlyContext as bx, type TextOnlyCustomHandler as by, type TextOnlyGadgetConfig 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 };
+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 };