llmist 3.0.0 → 4.0.0

package/dist/{mock-stream-COHw8h9b.d.ts → mock-stream-BvNYtrlG.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,57 @@ type StreamEvent = {
 } | {
     type: "compaction";
     event: CompactionEvent;
-};
+} | SubagentStreamEvent | StreamCompletionEvent;
+/** Event for forwarding subagent activity through the stream */
+interface SubagentStreamEvent {
+    type: "subagent_event";
+    subagentEvent: SubagentEvent;
+}
+/**
+ * Information about an LLM call within a 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 subagent LLM calls and gadget executions.
+ *
+ * @example
+ * ```typescript
+ * // Forwarding events from subagent to parent
+ * for await (const event of subagent.run()) {
+ *   ctx.onSubagentEvent?.({
+ *     type: event.type === "gadget_call" ? "gadget_call" : "gadget_result",
+ *     gadgetInvocationId: parentInvocationId,
+ *     depth: 1,
+ *     event,
+ *   });
+ * }
+ * ```
+ */
+interface SubagentEvent {
+    /** Type of subagent event */
+    type: "llm_call_start" | "llm_call_end" | "gadget_call" | "gadget_result";
+    /** Invocation ID of the parent gadget this subagent 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 +1383,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 subagent 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
+     *   }
+     * }
+     * ```
+     */
+    onSubagentEvent?: (event: SubagentEvent) => void;
 }
 /**
  * Parent agent configuration passed to gadgets.
@@ -2940,6 +3042,34 @@ declare function collectText(agentGenerator: AsyncGenerator<StreamEvent>): Promi
  * @module agent/hooks
  */
 
+/**
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * observers: {
+ *   onLLMCallStart: (ctx) => {
+ *     if (ctx.subagentContext) {
+ *       // Event from a subagent
+ *       console.log(`↳ Subagent LLM (depth=${ctx.subagentContext.depth})`);
+ *     } else {
+ *       // Event from the main agent
+ *       console.log('Main agent LLM call');
+ *     }
+ *   }
+ * }
+ * ```
+ */
+interface SubagentContext {
+    /** Invocation ID of the parent gadget that spawned this subagent */
+    parentGadgetInvocationId: string;
+    /** Nesting depth: 1 = direct child, 2 = grandchild, etc. */
+    depth: number;
+}
 /**
  * Context provided when an LLM call starts.
  * Read-only observation point.
@@ -2948,6 +3078,8 @@ interface ObserveLLMCallContext {
     iteration: number;
     options: Readonly<LLMGenerationOptions>;
     logger: Logger<ILogObj>;
+    /** Present when event is from a subagent (undefined for top-level agent) */
+    subagentContext?: SubagentContext;
 }
 /**
  * Context provided when an LLM call is ready to execute.
@@ -2960,6 +3092,8 @@ interface ObserveLLMCallReadyContext {
     /** Final options after any controller modifications (e.g., trailing messages) */
     options: Readonly<LLMGenerationOptions>;
     logger: Logger<ILogObj>;
+    /** Present when event is from a subagent (undefined for top-level agent) */
+    subagentContext?: SubagentContext;
 }
 /**
  * Context provided when an LLM call completes successfully.
@@ -2976,6 +3110,8 @@ interface ObserveLLMCompleteContext {
     /** The final message that will be added to history (after interceptors) */
     finalMessage: string;
     logger: Logger<ILogObj>;
+    /** Present when event is from a subagent (undefined for top-level agent) */
+    subagentContext?: SubagentContext;
 }
 /**
  * Context provided when an LLM call fails.
@@ -2988,6 +3124,8 @@ interface ObserveLLMErrorContext {
     /** Whether the error was recovered by a controller */
     recovered: boolean;
     logger: Logger<ILogObj>;
+    /** Present when event is from a subagent (undefined for top-level agent) */
+    subagentContext?: SubagentContext;
 }
 /**
  * Context provided when a gadget execution starts.
@@ -3000,6 +3138,8 @@ interface ObserveGadgetStartContext {
     /** Parameters after controller modifications */
     parameters: Readonly<Record<string, unknown>>;
     logger: Logger<ILogObj>;
+    /** Present when event is from a subagent (undefined for top-level agent) */
+    subagentContext?: SubagentContext;
 }
 /**
  * Context provided when a gadget execution completes.
@@ -3020,6 +3160,8 @@ interface ObserveGadgetCompleteContext {
     /** Cost of gadget execution in USD. 0 if gadget didn't report cost. */
     cost?: number;
     logger: Logger<ILogObj>;
+    /** Present when event is from a subagent (undefined for top-level agent) */
+    subagentContext?: SubagentContext;
 }
 /**
  * Context provided when a gadget is skipped due to a failed dependency.
@@ -3035,6 +3177,8 @@ interface ObserveGadgetSkippedContext {
     /** The error message from the failed dependency */
     failedDependencyError: string;
     logger: Logger<ILogObj>;
+    /** Present when event is from a subagent (undefined for top-level agent) */
+    subagentContext?: SubagentContext;
 }
 /**
  * Context provided for each stream chunk.
@@ -3049,6 +3193,8 @@ interface ObserveChunkContext {
     /** Token usage if available (providers send usage at stream start/end) */
     usage?: TokenUsage;
     logger: Logger<ILogObj>;
+    /** Present when event is from a subagent (undefined for top-level agent) */
+    subagentContext?: SubagentContext;
 }
 /**
  * Observers: Read-only hooks for side effects.
@@ -3091,6 +3237,8 @@ interface ObserveCompactionContext {
     stats: CompactionStats;
     /** Logger instance */
     logger: Logger<ILogObj>;
+    /** Present when event is from a subagent (undefined for top-level agent) */
+    subagentContext?: SubagentContext;
 }
 /**
  * Context provided when the agent is aborted via AbortSignal.
@@ -3103,6 +3251,8 @@ interface ObserveAbortContext {
     reason?: unknown;
     /** Logger instance */
     logger: Logger<ILogObj>;
+    /** Present when event is from a subagent (undefined for top-level agent) */
+    subagentContext?: SubagentContext;
 }
 /**
  * Context for chunk interception.
@@ -3475,6 +3625,8 @@ interface AgentOptions {
     signal?: AbortSignal;
     /** Subagent-specific configuration overrides (from CLI config) */
     subagentConfig?: SubagentConfigMap;
+    /** Callback for subagent gadgets to report subagent events to parent */
+    onSubagentEvent?: (event: SubagentEvent) => void;
 }
 /**
  * Agent: Lean orchestrator that delegates to StreamProcessor.
@@ -3519,11 +3671,19 @@ declare class Agent {
     private readonly signal?;
     private readonly agentContextConfig;
     private readonly subagentConfig?;
+    private readonly userSubagentEventCallback?;
+    private readonly pendingSubagentEvents;
+    private readonly onSubagentEvent;
     /**
      * Creates a new Agent instance.
      * @internal This constructor is private. Use LLMist.createAgent() or AgentBuilder instead.
      */
     constructor(key: typeof AGENT_INTERNAL_KEY, options: AgentOptions);
+    /**
+     * Flush pending subagent events as StreamEvents.
+     * Called from run() to yield queued subagent events from subagent gadgets.
+     */
+    private flushPendingSubagentEvents;
     /**
      * Get the gadget registry for this agent.
      *
@@ -3729,6 +3889,8 @@ declare class AgentBuilder {
     private signal?;
     private trailingMessage?;
     private subagentConfig?;
+    private subagentEventCallback?;
+    private parentContext?;
     constructor(client?: LLMist);
     /**
      * Set the model to use.
@@ -4144,6 +4306,62 @@ declare class AgentBuilder {
      * ```
      */
     withSubagentConfig(config: SubagentConfigMap): this;
+    /**
+     * Set the callback for subagent events.
+     *
+     * Subagent gadgets (like BrowseWeb) can use ExecutionContext.onSubagentEvent
+     * 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 subagent events
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withSubagentEventCallback((event) => {
+     *   if (event.type === "llm_call_start") {
+     *     console.log(`  Subagent LLM #${event.event.iteration} starting...`);
+     *   } else if (event.type === "gadget_call") {
+     *     console.log(`    ⏵ ${event.event.call.gadgetName}...`);
+     *   }
+     * })
+     * ```
+     */
+    withSubagentEventCallback(callback: (event: SubagentEvent) => void): this;
+    /**
+     * Enable automatic subagent 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 `onSubagentEvent` 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 +4411,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)
+     * - Subagent event forwarding for LLM calls (if parentContext is set)
      */
     private composeHooks;
     /**
@@ -5101,4 +5321,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 SubagentEvent as K, type LLMMessage as L, MockProviderAdapter as M, type ExecutionContext 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, isImagePart 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, type SubagentContext as aE, DEFAULT_COMPACTION_CONFIG as aF, DEFAULT_SUMMARIZATION_PROMPT as aG, type LLMistOptions as aH, type AudioContentPart as aI, type AudioMimeType as aJ, type AudioSource as aK, type ContentPart as aL, type ImageBase64Source as aM, type ImageContentPart as aN, type ImageMimeType as aO, type ImageSource as aP, type ImageUrlSource as aQ, type TextContentPart as aR, audioFromBase64 as aS, audioFromBuffer as aT, detectAudioMimeType as aU, detectImageMimeType as aV, imageFromBase64 as aW, imageFromBuffer as aX, imageFromUrl as aY, isAudioPart as aZ, isDataUrl 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, isTextPart as b0, parseDataUrl as b1, text as b2, toBase64 as b3, type MessageRole as b4, extractMessageText as b5, LLMMessageBuilder as b6, normalizeMessageContent as b7, type CostEstimate as b8, type ModelFeatures as b9, type TextOnlyContext as bA, type TextOnlyCustomHandler as bB, type TextOnlyGadgetConfig as bC, type TextOnlyHandler as bD, type TextOnlyStrategy as bE, type ModelLimits as ba, type ModelPricing as bb, type VisionAnalyzeOptions as bc, type VisionAnalyzeResult as bd, type ProviderIdentifier as be, ModelIdentifierParser as bf, type HintContext as bg, type PromptContext as bh, type PromptTemplate as bi, type PromptTemplateConfig as bj, DEFAULT_HINTS as bk, DEFAULT_PROMPTS as bl, resolveHintTemplate as bm, resolvePromptTemplate as bn, resolveRulesTemplate as bo, type TextGenerationOptions as bp, complete as bq, stream as br, type GadgetClass as bs, type GadgetOrClass as bt, type CostReportingLLMist as bu, type GadgetExecuteResult as bv, type GadgetSkippedEvent as bw, type StoredMedia as bx, type SubagentStreamEvent as by, type TextOnlyAction 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 };