llmist 3.1.0 → 5.0.0

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

@@ -1022,34 +1022,60 @@ type StreamEvent = {
 } | {
     type: "compaction";
     event: CompactionEvent;
-} | StreamCompletionEvent;
+} | SubagentStreamEvent | StreamCompletionEvent;
+/** Event for forwarding subagent activity through the stream */
+interface SubagentStreamEvent {
+    type: "subagent_event";
+    subagentEvent: SubagentEvent;
+}
 /**
- * Information about an LLM call within a nested subagent.
+ * Information about an LLM call within a subagent.
  * Used by parent agents to display real-time progress of subagent LLM calls.
+ *
+ * This interface provides full context about subagent LLM calls, enabling
+ * first-class display with the same metrics as top-level agents (cached tokens, cost, etc.).
  */
 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 */
+    /** Input tokens sent to the LLM (for backward compat, prefer usage.inputTokens) */
     inputTokens?: number;
-    /** Output tokens received from the LLM */
+    /** Output tokens received from the LLM (for backward compat, prefer usage.outputTokens) */
     outputTokens?: number;
     /** Reason the LLM stopped generating (e.g., "stop", "tool_use") */
     finishReason?: string;
     /** Elapsed time in milliseconds */
     elapsedMs?: number;
+    /**
+     * Full token usage including cached token counts.
+     * This provides the same level of detail as top-level agent calls.
+     */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        /** Number of input tokens served from cache (subset of inputTokens) */
+        cachedInputTokens?: number;
+        /** Number of input tokens written to cache (subset of inputTokens, Anthropic only) */
+        cacheCreationInputTokens?: number;
+    };
+    /**
+     * Cost of this LLM call in USD.
+     * Calculated by the subagent if it has access to model registry.
+     */
+    cost?: number;
 }
 /**
  * Event emitted by subagent gadgets to report internal agent activity.
- * Enables real-time display of nested LLM calls and gadget executions.
+ * 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.onNestedEvent?.({
+ *   ctx.onSubagentEvent?.({
  *     type: event.type === "gadget_call" ? "gadget_call" : "gadget_result",
  *     gadgetInvocationId: parentInvocationId,
  *     depth: 1,
@@ -1058,10 +1084,10 @@ interface LLMCallInfo {
  * }
  * ```
  */
-interface NestedAgentEvent {
-    /** Type of nested 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 nested event belongs to */
+    /** Invocation ID of the parent gadget this subagent event belongs to */
     gadgetInvocationId: string;
     /** Nesting depth (1 = direct child, 2 = grandchild, etc.) */
     depth: number;
@@ -1389,7 +1415,7 @@ interface ExecutionContext {
      *
      * 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.
+     * 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.
@@ -1410,7 +1436,7 @@ interface ExecutionContext {
      * }
      * ```
      */
-    onNestedEvent?: (event: NestedAgentEvent) => void;
+    onSubagentEvent?: (event: SubagentEvent) => void;
 }
 /**
  * Parent agent configuration passed to gadgets.
@@ -3037,6 +3063,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.
@@ -3045,6 +3099,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.
@@ -3057,6 +3113,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.
@@ -3073,6 +3131,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.
@@ -3085,6 +3145,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.
@@ -3097,6 +3159,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.
@@ -3117,6 +3181,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.
@@ -3132,6 +3198,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.
@@ -3146,6 +3214,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.
@@ -3188,6 +3258,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.
@@ -3200,6 +3272,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.
@@ -3572,8 +3646,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;
+    /** Callback for subagent gadgets to report subagent events to parent */
+    onSubagentEvent?: (event: SubagentEvent) => void;
 }
 /**
  * Agent: Lean orchestrator that delegates to StreamProcessor.
@@ -3618,12 +3692,19 @@ declare class Agent {
     private readonly signal?;
     private readonly agentContextConfig;
     private readonly subagentConfig?;
-    private readonly onNestedEvent?;
+    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.
      *
@@ -3829,7 +3910,7 @@ declare class AgentBuilder {
     private signal?;
     private trailingMessage?;
     private subagentConfig?;
-    private nestedEventCallback?;
+    private subagentEventCallback?;
     private parentContext?;
     constructor(client?: LLMist);
     /**
@@ -4247,35 +4328,35 @@ declare class AgentBuilder {
      */
     withSubagentConfig(config: SubagentConfigMap): this;
     /**
-     * Set the callback for nested subagent events.
+     * Set the callback for subagent events.
      *
-     * Subagent gadgets (like BrowseWeb) can use ExecutionContext.onNestedEvent
+     * 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 nested agent events
+     * @param callback - Function to handle subagent events
      * @returns This builder for chaining
      *
      * @example
      * ```typescript
-     * .withNestedEventCallback((event) => {
+     * .withSubagentEventCallback((event) => {
      *   if (event.type === "llm_call_start") {
-     *     console.log(`  Nested LLM #${event.event.iteration} starting...`);
+     *     console.log(`  Subagent LLM #${event.event.iteration} starting...`);
      *   } else if (event.type === "gadget_call") {
      *     console.log(`    ⏵ ${event.event.call.gadgetName}...`);
      *   }
      * })
      * ```
      */
-    withNestedEventCallback(callback: (event: NestedAgentEvent) => void): this;
+    withSubagentEventCallback(callback: (event: SubagentEvent) => void): this;
     /**
-     * Enable automatic nested event forwarding to parent agent.
+     * 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 `onNestedEvent` from the execution
+     * 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
@@ -4353,7 +4434,7 @@ declare class AgentBuilder {
     /**
      * Compose the final hooks, including:
      * - Trailing message injection (if configured)
-     * - Nested event forwarding for LLM calls (if parentContext is set)
+     * - Subagent event forwarding for LLM calls (if parentContext is set)
      */
     private composeHooks;
     /**
@@ -5261,4 +5342,4 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
-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 };
+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 };