llmist 6.0.0 → 6.2.0

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

@@ -1,4 +1,5 @@
-import { ZodTypeAny } from 'zod';
+import * as zod from 'zod';
+import { ZodType, ZodTypeAny } from 'zod';
 import { Logger, ILogObj } from 'tslog';
 
 /**
@@ -213,6 +214,943 @@ interface SpeechModelSpec {
     };
 }
 
+interface LLMGenerationOptions {
+    model: string;
+    messages: LLMMessage[];
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    stopSequences?: string[];
+    responseFormat?: "text";
+    metadata?: Record<string, unknown>;
+    extra?: Record<string, unknown>;
+    /**
+     * Optional abort signal for cancelling the request mid-flight.
+     *
+     * When the signal is aborted, the provider will attempt to cancel
+     * the underlying HTTP request and the stream will terminate with
+     * an abort error. Use `isAbortError()` from `@/core/errors` to
+     * detect cancellation in error handling.
+     *
+     * @example
+     * ```typescript
+     * const controller = new AbortController();
+     *
+     * const stream = client.stream({
+     *   model: "claude-3-5-sonnet-20241022",
+     *   messages: [{ role: "user", content: "Tell me a long story" }],
+     *   signal: controller.signal,
+     * });
+     *
+     * // Cancel after 5 seconds
+     * setTimeout(() => controller.abort(), 5000);
+     *
+     * try {
+     *   for await (const chunk of stream) {
+     *     process.stdout.write(chunk.text);
+     *   }
+     * } catch (error) {
+     *   if (isAbortError(error)) {
+     *     console.log("\nRequest was cancelled");
+     *   } else {
+     *     throw error;
+     *   }
+     * }
+     * ```
+     */
+    signal?: AbortSignal;
+}
+interface TokenUsage {
+    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;
+}
+interface LLMStreamChunk {
+    text: string;
+    /**
+     * Indicates that the provider has finished producing output and includes the reason if available.
+     */
+    finishReason?: string | null;
+    /**
+     * Token usage information, typically available in the final chunk when the stream completes.
+     */
+    usage?: TokenUsage;
+    /**
+     * Provider specific payload emitted at the same time as the text chunk. This is useful for debugging and tests.
+     */
+    rawEvent?: unknown;
+}
+interface LLMStream extends AsyncIterable<LLMStreamChunk> {
+}
+type ProviderIdentifier = string;
+interface ModelDescriptor {
+    provider: string;
+    name: string;
+}
+declare class ModelIdentifierParser {
+    private readonly defaultProvider;
+    constructor(defaultProvider?: string);
+    parse(identifier: string): ModelDescriptor;
+}
+
+/**
+ * Unified event types for the Execution Tree.
+ *
+ * All events carry full tree context (nodeId, parentId, depth, path).
+ * No special SubagentEvent wrapper needed - subagent events are regular
+ * events with depth > 0.
+ *
+ * @module core/execution-events
+ */
+
+/**
+ * Base properties shared by all execution events.
+ * Every event carries full tree context.
+ */
+interface BaseExecutionEvent {
+    /** Monotonically increasing event ID */
+    eventId: number;
+    /** Event timestamp */
+    timestamp: number;
+    /** Node that emitted this event */
+    nodeId: string;
+    /** Parent node ID (null for root events) */
+    parentId: string | null;
+    /** Nesting depth (0 = root, 1 = child, etc.) */
+    depth: number;
+    /** Full path from root to this node */
+    path: string[];
+}
+/**
+ * Emitted when an LLM call starts.
+ */
+interface LLMCallStartEvent extends BaseExecutionEvent {
+    type: "llm_call_start";
+    /** Iteration number within agent loop (1-indexed) */
+    iteration: number;
+    /** Model identifier */
+    model: string;
+    /** Request messages */
+    request?: LLMMessage[];
+}
+/**
+ * Emitted for each streaming chunk from LLM.
+ */
+interface LLMCallStreamEvent extends BaseExecutionEvent {
+    type: "llm_call_stream";
+    /** Text chunk */
+    chunk: string;
+}
+/**
+ * Emitted when an LLM call completes successfully.
+ */
+interface LLMCallCompleteEvent extends BaseExecutionEvent {
+    type: "llm_call_complete";
+    /** Complete response text */
+    response: string;
+    /** Token usage */
+    usage?: TokenUsage;
+    /** Finish reason from LLM */
+    finishReason?: string | null;
+    /** Cost in USD */
+    cost?: number;
+}
+/**
+ * Emitted when an LLM call fails.
+ */
+interface LLMCallErrorEvent extends BaseExecutionEvent {
+    type: "llm_call_error";
+    /** The error that occurred */
+    error: Error;
+    /** Whether the error was recovered by a controller */
+    recovered: boolean;
+}
+/**
+ * Emitted when a gadget call is parsed from LLM output (before execution).
+ */
+interface GadgetCallEvent extends BaseExecutionEvent {
+    type: "gadget_call";
+    /** Invocation ID */
+    invocationId: string;
+    /** Gadget name */
+    name: string;
+    /** Parameters */
+    parameters: Record<string, unknown>;
+    /** Dependencies (other invocation IDs) */
+    dependencies: string[];
+}
+/**
+ * Emitted when gadget execution starts.
+ */
+interface GadgetStartEvent extends BaseExecutionEvent {
+    type: "gadget_start";
+    /** Invocation ID */
+    invocationId: string;
+    /** Gadget name */
+    name: string;
+}
+/**
+ * Emitted when gadget execution completes successfully.
+ */
+interface GadgetCompleteEvent extends BaseExecutionEvent {
+    type: "gadget_complete";
+    /** Invocation ID */
+    invocationId: string;
+    /** Gadget name */
+    name: string;
+    /** Result string */
+    result: string;
+    /** Execution time in ms */
+    executionTimeMs: number;
+    /** Cost in USD */
+    cost?: number;
+    /** Media outputs */
+    media?: GadgetMediaOutput[];
+}
+/**
+ * Emitted when gadget execution fails.
+ */
+interface GadgetErrorEvent extends BaseExecutionEvent {
+    type: "gadget_error";
+    /** Invocation ID */
+    invocationId: string;
+    /** Gadget name */
+    name: string;
+    /** Error message */
+    error: string;
+    /** Execution time in ms */
+    executionTimeMs: number;
+}
+/**
+ * Emitted when a gadget is skipped.
+ */
+interface GadgetSkippedEvent$1 extends BaseExecutionEvent {
+    type: "gadget_skipped";
+    /** Invocation ID */
+    invocationId: string;
+    /** Gadget name */
+    name: string;
+    /** Reason for skipping */
+    reason: "dependency_failed" | "controller_skip";
+    /** Error message (combines reason and failedDependencyError for consistency with GadgetErrorEvent) */
+    error: string;
+    /** Failed dependency invocation ID (if dependency_failed) */
+    failedDependency?: string;
+    /** Error message from failed dependency */
+    failedDependencyError?: string;
+}
+/**
+ * Emitted for text output from LLM (pure notification, not a tree node).
+ */
+interface TextEvent extends BaseExecutionEvent {
+    type: "text";
+    /** Text content */
+    content: string;
+}
+/**
+ * Emitted when context compaction occurs.
+ */
+interface CompactionEvent$1 extends BaseExecutionEvent {
+    type: "compaction";
+    /** Tokens before compaction */
+    tokensBefore: number;
+    /** Tokens after compaction */
+    tokensAfter: number;
+    /** Compaction strategy used */
+    strategy: string;
+    /** Messages removed */
+    messagesRemoved: number;
+}
+/**
+ * Emitted when human input is required.
+ */
+interface HumanInputRequiredEvent extends BaseExecutionEvent {
+    type: "human_input_required";
+    /** Question for the user */
+    question: string;
+    /** Gadget name requesting input */
+    gadgetName: string;
+    /** Invocation ID */
+    invocationId: string;
+}
+/**
+ * Emitted when the execution stream completes.
+ */
+interface StreamCompleteEvent extends BaseExecutionEvent {
+    type: "stream_complete";
+    /** Whether any gadgets were executed */
+    didExecuteGadgets: boolean;
+    /** Whether the agent loop should break */
+    shouldBreakLoop: boolean;
+    /** Total cost for this iteration */
+    iterationCost?: number;
+}
+/**
+ * All LLM-related events.
+ */
+type LLMEvent = LLMCallStartEvent | LLMCallStreamEvent | LLMCallCompleteEvent | LLMCallErrorEvent;
+/**
+ * All gadget-related events.
+ */
+type GadgetEvent = GadgetCallEvent | GadgetStartEvent | GadgetCompleteEvent | GadgetErrorEvent | GadgetSkippedEvent$1;
+/**
+ * Union of all execution events.
+ */
+type ExecutionEvent = LLMCallStartEvent | LLMCallStreamEvent | LLMCallCompleteEvent | LLMCallErrorEvent | GadgetCallEvent | GadgetStartEvent | GadgetCompleteEvent | GadgetErrorEvent | GadgetSkippedEvent$1 | TextEvent | CompactionEvent$1 | HumanInputRequiredEvent | StreamCompleteEvent;
+/**
+ * Event type discriminator.
+ */
+type ExecutionEventType = ExecutionEvent["type"] | "*";
+/**
+ * Check if an event is an LLM event.
+ */
+declare function isLLMEvent(event: ExecutionEvent): event is LLMEvent;
+/**
+ * Check if an event is a gadget event.
+ */
+declare function isGadgetEvent(event: ExecutionEvent): event is GadgetEvent;
+/**
+ * Check if an event is from a subagent (nested execution).
+ */
+declare function isSubagentEvent(event: ExecutionEvent): boolean;
+/**
+ * Check if an event is from the root agent.
+ */
+declare function isRootEvent(event: ExecutionEvent): boolean;
+/**
+ * Filter events by depth.
+ */
+declare function filterByDepth(events: ExecutionEvent[], depth: number): ExecutionEvent[];
+/**
+ * Filter events by parent node.
+ */
+declare function filterByParent(events: ExecutionEvent[], parentId: string): ExecutionEvent[];
+/**
+ * Filter events to only root-level events.
+ */
+declare function filterRootEvents(events: ExecutionEvent[]): ExecutionEvent[];
+/**
+ * Group events by their parent node.
+ */
+declare function groupByParent(events: ExecutionEvent[]): Map<string | null, ExecutionEvent[]>;
+
+/**
+ * First-class Execution Tree model for nested subagent support.
+ *
+ * The ExecutionTree is THE single source of truth for execution state.
+ * All nodes (including nested subagent nodes) live in one tree.
+ * Events are projections of tree changes.
+ *
+ * @module core/execution-tree
+ */
+
+/**
+ * Unique identifier for any execution node.
+ * Format examples: "llm_1", "gadget_abc123", "llm_1_2" (nested)
+ */
+type NodeId = string;
+/**
+ * Node type discriminator.
+ */
+type ExecutionNodeType = "llm_call" | "gadget";
+/**
+ * Base properties shared by all execution nodes.
+ */
+interface BaseExecutionNode {
+    /** Unique identifier for this node */
+    id: NodeId;
+    /** Node type discriminator */
+    type: ExecutionNodeType;
+    /** Parent node ID (null for root nodes) */
+    parentId: NodeId | null;
+    /** Nesting depth (0 = root, 1 = child of gadget, etc.) */
+    depth: number;
+    /** Path from root to this node: ["llm_1", "gadget_abc", "llm_1_1"] */
+    path: NodeId[];
+    /** Creation timestamp */
+    createdAt: number;
+    /** Completion timestamp (null if in progress) */
+    completedAt: number | null;
+}
+/**
+ * LLM call execution node.
+ */
+interface LLMCallNode extends BaseExecutionNode {
+    type: "llm_call";
+    /** Iteration number within the agent loop (1-indexed for display) */
+    iteration: number;
+    /** Model identifier */
+    model: string;
+    /** Request messages (set when call starts) */
+    request?: LLMMessage[];
+    /** Accumulated response text */
+    response: string;
+    /** Token usage (set on completion) */
+    usage?: TokenUsage;
+    /** Finish reason from LLM */
+    finishReason?: string | null;
+    /** Cost in USD */
+    cost?: number;
+    /** Child node IDs (gadgets spawned by this LLM call) */
+    children: NodeId[];
+}
+/**
+ * Gadget execution state.
+ */
+type GadgetState = "pending" | "running" | "completed" | "failed" | "skipped";
+/**
+ * Gadget execution node.
+ */
+interface GadgetNode extends BaseExecutionNode {
+    type: "gadget";
+    /** Invocation ID (LLM-generated or auto) */
+    invocationId: string;
+    /** Gadget name */
+    name: string;
+    /** Parameters passed to the gadget */
+    parameters: Record<string, unknown>;
+    /** Dependencies (other invocation IDs this gadget waits for) */
+    dependencies: string[];
+    /** Execution state */
+    state: GadgetState;
+    /** Result string (if completed successfully) */
+    result?: string;
+    /** Error message (if failed or skipped) */
+    error?: string;
+    /** Failed dependency invocation ID (if skipped due to dependency) */
+    failedDependency?: string;
+    /** Execution time in milliseconds */
+    executionTimeMs?: number;
+    /** Cost in USD */
+    cost?: number;
+    /** Media outputs from this gadget */
+    media?: GadgetMediaOutput[];
+    /** Child node IDs (nested LLM calls for subagent gadgets) */
+    children: NodeId[];
+    /** Whether this gadget is a subagent (has nested LLM calls) */
+    isSubagent: boolean;
+}
+/**
+ * Union of all execution node types.
+ */
+type ExecutionNode = LLMCallNode | GadgetNode;
+interface AddLLMCallParams {
+    /** Iteration number (1-indexed) */
+    iteration: number;
+    /** Model identifier */
+    model: string;
+    /** Request messages */
+    request?: LLMMessage[];
+    /** Parent node ID (for subagent LLM calls) */
+    parentId?: NodeId | null;
+}
+interface AddGadgetParams {
+    /** Invocation ID */
+    invocationId: string;
+    /** Gadget name */
+    name: string;
+    /** Parameters */
+    parameters: Record<string, unknown>;
+    /** Dependencies */
+    dependencies?: string[];
+    /** Parent LLM call node ID */
+    parentId?: NodeId | null;
+}
+interface CompleteLLMCallParams {
+    /** Accumulated response text */
+    response?: string;
+    /** Token usage */
+    usage?: TokenUsage;
+    /** Finish reason */
+    finishReason?: string | null;
+    /** Cost in USD */
+    cost?: number;
+}
+interface CompleteGadgetParams {
+    /** Result string */
+    result?: string;
+    /** Error message */
+    error?: string;
+    /** Failed dependency (for skipped gadgets) */
+    failedDependency?: string;
+    /** Execution time in ms */
+    executionTimeMs?: number;
+    /** Cost in USD */
+    cost?: number;
+    /** Media outputs */
+    media?: GadgetMediaOutput[];
+}
+
+/** Event listener function type */
+type EventListener = (event: ExecutionEvent) => void;
+/**
+ * The Execution Tree - single source of truth for all execution state.
+ *
+ * Features:
+ * - Stores all nodes (LLM calls, gadgets) in a hierarchical structure
+ * - Emits events on mutations
+ * - Provides query methods for aggregation (costs, media, descendants)
+ * - Supports single shared tree model for nested subagents
+ *
+ * @example
+ * ```typescript
+ * const tree = new ExecutionTree();
+ *
+ * // Add root LLM call
+ * const llmNode = tree.addLLMCall({ iteration: 1, model: "sonnet" });
+ *
+ * // Add gadget under the LLM call
+ * const gadgetNode = tree.addGadget({
+ *   invocationId: "gc_1",
+ *   name: "ReadFile",
+ *   parameters: { path: "/foo.txt" },
+ *   parentId: llmNode.id,
+ * });
+ *
+ * // Complete the gadget
+ * tree.completeGadget(gadgetNode.id, { result: "file contents", executionTimeMs: 50 });
+ *
+ * // Query total cost
+ * console.log(tree.getTotalCost());
+ * ```
+ */
+declare class ExecutionTree {
+    private nodes;
+    private rootIds;
+    private eventListeners;
+    private eventIdCounter;
+    private invocationIdToNodeId;
+    private eventQueue;
+    private eventWaiters;
+    private isCompleted;
+    /**
+     * Base depth for all nodes in this tree.
+     * Used when this tree is a subagent's view into a parent tree.
+     */
+    readonly baseDepth: number;
+    /**
+     * Parent node ID for subagent trees.
+     * All root nodes in this tree will have this as their parentId.
+     */
+    readonly parentNodeId: NodeId | null;
+    constructor(options?: {
+        baseDepth?: number;
+        parentNodeId?: NodeId | null;
+    });
+    private generateLLMCallId;
+    private gadgetIdCounter;
+    private generateGadgetId;
+    private emit;
+    private createBaseEventProps;
+    /**
+     * Add a new LLM call node to the tree.
+     */
+    addLLMCall(params: AddLLMCallParams): LLMCallNode;
+    /**
+     * Add text to an LLM call's response (for streaming).
+     */
+    appendLLMResponse(nodeId: NodeId, chunk: string): void;
+    /**
+     * Complete an LLM call node.
+     */
+    completeLLMCall(nodeId: NodeId, params: CompleteLLMCallParams): void;
+    /**
+     * Mark an LLM call as failed.
+     */
+    failLLMCall(nodeId: NodeId, error: Error, recovered: boolean): void;
+    /**
+     * Add a new gadget node to the tree.
+     */
+    addGadget(params: AddGadgetParams): GadgetNode;
+    /**
+     * Mark a gadget as started (running).
+     */
+    startGadget(nodeId: NodeId): void;
+    /**
+     * Complete a gadget node successfully.
+     */
+    completeGadget(nodeId: NodeId, params: CompleteGadgetParams): void;
+    /**
+     * Mark a gadget as skipped due to dependency failure.
+     */
+    skipGadget(nodeId: NodeId, failedDependency: string, failedDependencyError: string, reason: "dependency_failed" | "controller_skip"): void;
+    /**
+     * Emit a text event (notification only, not stored in tree).
+     */
+    emitText(content: string, llmCallNodeId: NodeId): void;
+    /**
+     * Get a node by ID.
+     */
+    getNode(id: NodeId): ExecutionNode | undefined;
+    /**
+     * Get a gadget node by invocation ID.
+     */
+    getNodeByInvocationId(invocationId: string): GadgetNode | undefined;
+    /**
+     * Get all root nodes (depth 0 for this tree).
+     */
+    getRoots(): ExecutionNode[];
+    /**
+     * Get children of a node.
+     */
+    getChildren(id: NodeId): ExecutionNode[];
+    /**
+     * Get ancestors of a node (from root to parent).
+     */
+    getAncestors(id: NodeId): ExecutionNode[];
+    /**
+     * Get all descendants of a node.
+     */
+    getDescendants(id: NodeId, type?: ExecutionNodeType): ExecutionNode[];
+    /**
+     * Get the current (most recent incomplete) LLM call node.
+     */
+    getCurrentLLMCallId(): NodeId | undefined;
+    /**
+     * Get total cost for entire tree.
+     */
+    getTotalCost(): number;
+    /**
+     * Get total cost for a subtree (node and all descendants).
+     */
+    getSubtreeCost(nodeId: NodeId): number;
+    /**
+     * Get token usage for entire tree.
+     */
+    getTotalTokens(): {
+        input: number;
+        output: number;
+        cached: number;
+    };
+    /**
+     * Get token usage for a subtree.
+     */
+    getSubtreeTokens(nodeId: NodeId): {
+        input: number;
+        output: number;
+        cached: number;
+    };
+    /**
+     * Collect all media from a subtree.
+     */
+    getSubtreeMedia(nodeId: NodeId): GadgetMediaOutput[];
+    /**
+     * Check if a subtree is complete (all nodes finished).
+     */
+    isSubtreeComplete(nodeId: NodeId): boolean;
+    /**
+     * Get node counts.
+     */
+    getNodeCount(): {
+        llmCalls: number;
+        gadgets: number;
+    };
+    /**
+     * Subscribe to events of a specific type.
+     * Returns unsubscribe function.
+     *
+     * @param type - Event type to subscribe to (use "*" for all events)
+     * @param listener - Callback function that receives matching events
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = tree.on("gadget_complete", (event) => {
+     *   if (event.type === "gadget_complete") {
+     *     console.log(`Gadget ${event.name} completed`);
+     *   }
+     * });
+     * ```
+     */
+    on(type: ExecutionEventType, listener: EventListener): () => void;
+    /**
+     * Subscribe to all events.
+     */
+    onAll(listener: EventListener): () => void;
+    /**
+     * Get async iterable of all events.
+     * Events are yielded as they occur.
+     */
+    events(): AsyncGenerator<ExecutionEvent>;
+    /**
+     * Mark the tree as complete (no more events will be emitted).
+     */
+    complete(): void;
+    /**
+     * Check if the tree is complete.
+     */
+    isComplete(): boolean;
+}
+
+/**
+ * Function-based gadget creation helper.
+ *
+ * For simple gadgets, use createGadget() instead of defining a class.
+ * Parameters are automatically typed from the Zod schema.
+ *
+ * @example
+ * ```typescript
+ * const calculator = createGadget({
+ *   description: "Performs arithmetic operations",
+ *   schema: z.object({
+ *     operation: z.enum(["add", "subtract"]),
+ *     a: z.number(),
+ *     b: z.number(),
+ *   }),
+ *   execute: ({ operation, a, b }) => {
+ *     // Automatically typed!
+ *     return operation === "add" ? String(a + b) : String(a - b);
+ *   },
+ * });
+ * ```
+ */
+
+/**
+ * Infer the TypeScript type from a Zod schema.
+ */
+type InferSchema$1<T> = T extends ZodType<infer U> ? U : never;
+/**
+ * Configuration for creating a function-based gadget.
+ */
+interface CreateGadgetConfig<TSchema extends ZodType> {
+    /** Optional custom name (defaults to "FunctionGadget") */
+    name?: string;
+    /** Human-readable description of what the gadget does */
+    description: string;
+    /** Zod schema for parameter validation */
+    schema: TSchema;
+    /**
+     * Execution function with typed parameters.
+     * Can return string or { result, cost? }.
+     * Optionally receives ExecutionContext for callback-based cost reporting.
+     */
+    execute: (params: InferSchema$1<TSchema>, ctx?: ExecutionContext) => GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
+    /** Optional timeout in milliseconds */
+    timeoutMs?: number;
+    /** Optional usage examples to help LLMs understand proper invocation */
+    examples?: GadgetExample<InferSchema$1<TSchema>>[];
+}
+/**
+ * Creates a gadget from a function (simpler than class-based approach).
+ *
+ * This is perfect for simple gadgets where you don't need the full
+ * power of a class. Parameters are automatically typed from the schema.
+ *
+ * @param config - Configuration with execute function and schema
+ * @returns Gadget instance ready to be registered
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { createGadget } from 'llmist';
+ *
+ * // Simple calculator gadget
+ * const calculator = createGadget({
+ *   description: "Performs arithmetic operations",
+ *   schema: z.object({
+ *     operation: z.enum(["add", "subtract", "multiply", "divide"]),
+ *     a: z.number().describe("First number"),
+ *     b: z.number().describe("Second number"),
+ *   }),
+ *   execute: ({ operation, a, b }) => {
+ *     // Parameters are automatically typed!
+ *     switch (operation) {
+ *       case "add": return String(a + b);
+ *       case "subtract": return String(a - b);
+ *       case "multiply": return String(a * b);
+ *       case "divide": return String(a / b);
+ *     }
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Async gadget with custom name and timeout
+ * const weather = createGadget({
+ *   name: "weather",
+ *   description: "Fetches current weather for a city",
+ *   schema: z.object({
+ *     city: z.string().min(1).describe("City name"),
+ *   }),
+ *   timeoutMs: 10000,
+ *   execute: async ({ city }) => {
+ *     const response = await fetch(`https://api.weather.com/${city}`);
+ *     const data = await response.json();
+ *     return `Weather in ${city}: ${data.description}, ${data.temp}°C`;
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use with agent
+ * const agent = LLMist.createAgent()
+ *   .withGadgets(calculator, weather)
+ *   .ask("What's the weather in Paris and what's 10 + 5?");
+ * ```
+ */
+declare function createGadget<TSchema extends ZodType>(config: CreateGadgetConfig<TSchema>): AbstractGadget;
+
+/**
+ * Type-safe gadget factory with automatic parameter inference.
+ *
+ * Gadget eliminates the need for manual type assertions
+ * by automatically inferring parameter types from the Zod schema.
+ *
+ * @example
+ * ```typescript
+ * class Calculator extends Gadget({
+ *   description: "Performs arithmetic operations",
+ *   schema: z.object({
+ *     operation: z.enum(["add", "subtract"]),
+ *     a: z.number(),
+ *     b: z.number(),
+ *   }),
+ * }) {
+ *   // ✨ params is automatically typed!
+ *   execute(params: this['params']): string {
+ *     const { operation, a, b } = params; // All typed!
+ *     return operation === "add" ? String(a + b) : String(a - b);
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Infer the TypeScript type from a Zod schema.
+ */
+type InferSchema<T> = T extends ZodType<infer U> ? U : never;
+/**
+ * Configuration for creating a typed gadget.
+ */
+interface GadgetConfig<TSchema extends ZodType> {
+    /** Human-readable description of what the gadget does */
+    description: string;
+    /** Zod schema for parameter validation */
+    schema: TSchema;
+    /** Optional custom name (defaults to class name) */
+    name?: string;
+    /** Optional timeout in milliseconds */
+    timeoutMs?: number;
+    /** Optional usage examples to help LLMs understand proper invocation */
+    examples?: GadgetExample<InferSchema<TSchema>>[];
+}
+/**
+ * Factory function to create a typed gadget base class.
+ *
+ * The returned class automatically infers parameter types from the Zod schema,
+ * eliminating the need for manual type assertions in the execute method.
+ *
+ * @param config - Configuration with description and schema
+ * @returns Base class to extend with typed execute method
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { Gadget } from 'llmist';
+ *
+ * class Calculator extends Gadget({
+ *   description: "Performs arithmetic operations",
+ *   schema: z.object({
+ *     operation: z.enum(["add", "subtract", "multiply", "divide"]),
+ *     a: z.number().describe("First number"),
+ *     b: z.number().describe("Second number"),
+ *   }),
+ * }) {
+ *   execute(params: this['params']): string {
+ *     // params is automatically typed as:
+ *     // { operation: "add" | "subtract" | "multiply" | "divide"; a: number; b: number }
+ *     const { operation, a, b } = params;
+ *
+ *     switch (operation) {
+ *       case "add": return String(a + b);
+ *       case "subtract": return String(a - b);
+ *       case "multiply": return String(a * b);
+ *       case "divide": return String(a / b);
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With async execution
+ * class WeatherGadget extends Gadget({
+ *   description: "Fetches weather for a city",
+ *   schema: z.object({
+ *     city: z.string().min(1).describe("City name"),
+ *   }),
+ *   timeoutMs: 10000,
+ * }) {
+ *   async execute(params: this['params']): Promise<string> {
+ *     const { city } = params; // Automatically typed as { city: string }
+ *     const weather = await fetchWeather(city);
+ *     return `Weather in ${city}: ${weather}`;
+ *   }
+ * }
+ * ```
+ */
+declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>): {
+    new (): {
+        description: string;
+        parameterSchema: TSchema;
+        name: string | undefined;
+        timeoutMs: number | undefined;
+        examples: GadgetExample<InferSchema<TSchema>>[] | undefined;
+        /**
+         * Type helper property for accessing inferred parameter type.
+         * This is used in the execute method signature: `execute(params: this['params'])`
+         *
+         * Note: This is just for type inference - the actual params in execute()
+         * will be Record<string, unknown> which you can safely cast to this['params']
+         */
+        readonly params: InferSchema<TSchema>;
+        /**
+         * Execute the gadget. Subclasses should cast params to this['params'].
+         *
+         * @param params - Validated parameters from the LLM
+         * @param ctx - Optional execution context for cost reporting and LLM access
+         * @returns Result as a string, or an object with result and optional cost
+         *
+         * @example
+         * ```typescript
+         * // Simple string return (free gadget)
+         * execute(params: this['params']) {
+         *   return String(params.a + params.b);
+         * }
+         *
+         * // Using context for callback-based cost reporting
+         * execute(params: this['params'], ctx) {
+         *   ctx.reportCost(0.001);
+         *   return "result";
+         * }
+         *
+         * // Using wrapped LLMist for automatic cost tracking
+         * async execute(params: this['params'], ctx) {
+         *   return ctx.llmist.complete('Summarize: ' + params.text);
+         * }
+         * ```
+         */
+        execute(params: Record<string, unknown>, ctx?: ExecutionContext): GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
+        throwIfAborted(ctx?: ExecutionContext): void;
+        onAbort(ctx: ExecutionContext | undefined, cleanup: () => void | Promise<void>): void;
+        createLinkedAbortController(ctx?: ExecutionContext): AbortController;
+        get instruction(): string;
+        getInstruction(optionsOrArgPrefix?: string | {
+            argPrefix?: string;
+            startPrefix?: string;
+            endPrefix?: string;
+        }): string;
+    } & {
+        params: InferSchema<TSchema>;
+    };
+};
+
 /**
  * Model Catalog Types
  *
@@ -643,89 +1581,6 @@ declare class ModelRegistry {
     getCheapestModel(inputTokens: number, outputTokens: number, providerId?: string): ModelSpec | undefined;
 }
 
-interface LLMGenerationOptions {
-    model: string;
-    messages: LLMMessage[];
-    maxTokens?: number;
-    temperature?: number;
-    topP?: number;
-    stopSequences?: string[];
-    responseFormat?: "text";
-    metadata?: Record<string, unknown>;
-    extra?: Record<string, unknown>;
-    /**
-     * Optional abort signal for cancelling the request mid-flight.
-     *
-     * When the signal is aborted, the provider will attempt to cancel
-     * the underlying HTTP request and the stream will terminate with
-     * an abort error. Use `isAbortError()` from `@/core/errors` to
-     * detect cancellation in error handling.
-     *
-     * @example
-     * ```typescript
-     * const controller = new AbortController();
-     *
-     * const stream = client.stream({
-     *   model: "claude-3-5-sonnet-20241022",
-     *   messages: [{ role: "user", content: "Tell me a long story" }],
-     *   signal: controller.signal,
-     * });
-     *
-     * // Cancel after 5 seconds
-     * setTimeout(() => controller.abort(), 5000);
-     *
-     * try {
-     *   for await (const chunk of stream) {
-     *     process.stdout.write(chunk.text);
-     *   }
-     * } catch (error) {
-     *   if (isAbortError(error)) {
-     *     console.log("\nRequest was cancelled");
-     *   } else {
-     *     throw error;
-     *   }
-     * }
-     * ```
-     */
-    signal?: AbortSignal;
-}
-interface TokenUsage {
-    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;
-}
-interface LLMStreamChunk {
-    text: string;
-    /**
-     * Indicates that the provider has finished producing output and includes the reason if available.
-     */
-    finishReason?: string | null;
-    /**
-     * Token usage information, typically available in the final chunk when the stream completes.
-     */
-    usage?: TokenUsage;
-    /**
-     * Provider specific payload emitted at the same time as the text chunk. This is useful for debugging and tests.
-     */
-    rawEvent?: unknown;
-}
-interface LLMStream extends AsyncIterable<LLMStreamChunk> {
-}
-type ProviderIdentifier = string;
-interface ModelDescriptor {
-    provider: string;
-    name: string;
-}
-declare class ModelIdentifierParser {
-    private readonly defaultProvider;
-    constructor(defaultProvider?: string);
-    parse(identifier: string): ModelDescriptor;
-}
-
 /**
  * Quick execution methods for simple use cases.
  *
@@ -1091,6 +1946,8 @@ interface SubagentEvent {
     gadgetInvocationId: string;
     /** Nesting depth (1 = direct child, 2 = grandchild, etc.) */
     depth: number;
+    /** LLM iteration number within the subagent (for gadget parenting in TUI) */
+    iteration?: number;
     /** The actual event data - either a StreamEvent or LLMCallInfo */
     event: StreamEvent | LLMCallInfo;
 }
@@ -1437,6 +2294,134 @@ interface ExecutionContext {
      * ```
      */
     onSubagentEvent?: (event: SubagentEvent) => void;
+    /**
+     * The execution tree tracking all LLM calls and gadget executions.
+     *
+     * Subagent gadgets can use the tree to:
+     * - Automatically aggregate costs via `tree.getSubtreeCost(nodeId)`
+     * - Collect media outputs via `tree.getSubtreeMedia(nodeId)`
+     * - Query token usage via `tree.getSubtreeTokens(nodeId)`
+     *
+     * When using `withParentContext(ctx)`, the subagent shares the parent's tree,
+     * enabling unified cost tracking and progress visibility across all nesting levels.
+     *
+     * This is optional - it will be `undefined` for:
+     * - Gadgets executed via CLI `gadget run` command
+     * - Direct gadget testing without agent context
+     * - Legacy code that hasn't adopted the ExecutionTree model
+     *
+     * @example
+     * ```typescript
+     * execute: async (params, ctx) => {
+     *   // Build subagent with parent context (shares tree)
+     *   const agent = new AgentBuilder(client)
+     *     .withParentContext(ctx)
+     *     .withGadgets(Navigate, Click)
+     *     .ask(params.task);
+     *
+     *   for await (const event of agent.run()) {
+     *     // Process events...
+     *   }
+     *
+     *   // After subagent completes, costs are automatically tracked in tree
+     *   // No need for manual cost aggregation!
+     *   const subtreeCost = ctx.tree?.getSubtreeCost(ctx.nodeId!);
+     *
+     *   // Media from all nested gadgets also aggregated
+     *   const allMedia = ctx.tree?.getSubtreeMedia(ctx.nodeId!);
+     *
+     *   return { result: "done", media: allMedia };
+     * }
+     * ```
+     */
+    tree?: ExecutionTree;
+    /**
+     * The tree node ID for this gadget execution.
+     *
+     * This identifies the current gadget's node in the execution tree.
+     * Use with tree methods to query/aggregate data for this subtree:
+     * - `tree.getSubtreeCost(nodeId)` - total cost including nested calls
+     * - `tree.getSubtreeMedia(nodeId)` - all media from nested gadgets
+     * - `tree.getSubtreeTokens(nodeId)` - token usage breakdown
+     * - `tree.getDescendants(nodeId)` - all child nodes
+     *
+     * Note: This is distinct from `invocationId` which identifies the gadget call
+     * (used in conversation history). `nodeId` is the tree node identifier.
+     */
+    nodeId?: NodeId;
+    /**
+     * Nesting depth of this gadget execution.
+     *
+     * - 0 = Root level (direct gadget call from main agent)
+     * - 1 = First-level subagent (gadget called by a gadget)
+     * - 2+ = Deeper nesting
+     *
+     * Useful for:
+     * - Conditional behavior based on nesting level
+     * - Logging with appropriate indentation
+     * - Limiting recursion depth
+     *
+     * @example
+     * ```typescript
+     * execute: async (params, ctx) => {
+     *   // Prevent infinite recursion
+     *   if ((ctx.depth ?? 0) > 3) {
+     *     return "Maximum nesting depth reached";
+     *   }
+     *
+     *   // Log with depth-aware indentation
+     *   const indent = "  ".repeat(ctx.depth ?? 0);
+     *   console.log(`${indent}Executing at depth ${ctx.depth}`);
+     * }
+     * ```
+     */
+    depth?: number;
+    /**
+     * Host llmist exports for external gadgets.
+     *
+     * External gadgets MUST use these instead of importing from 'llmist'
+     * to ensure they use the same version as the host CLI, enabling proper
+     * tree sharing and feature compatibility.
+     *
+     * Use the `getHostExports(ctx)` helper function to access these exports
+     * with proper error handling.
+     *
+     * @example
+     * ```typescript
+     * import { getHostExports, Gadget, z } from 'llmist';
+     *
+     * class BrowseWeb extends Gadget({...}) {
+     *   async execute(params, ctx) {
+     *     const { AgentBuilder } = getHostExports(ctx);
+     *     const agent = new AgentBuilder()
+     *       .withParentContext(ctx)
+     *       .ask(params.task);
+     *   }
+     * }
+     * ```
+     */
+    hostExports?: HostExports;
+}
+/**
+ * Host llmist exports provided to external gadgets via ExecutionContext.
+ *
+ * This ensures external gadgets use the same class instances as the host CLI,
+ * enabling proper tree sharing and avoiding the "dual-package problem" where
+ * different versions of llmist have incompatible classes.
+ */
+interface HostExports {
+    /** AgentBuilder for creating subagents with proper tree sharing */
+    AgentBuilder: typeof AgentBuilder;
+    /** Gadget factory for defining gadgets */
+    Gadget: typeof Gadget;
+    /** createGadget for functional gadget definitions */
+    createGadget: typeof createGadget;
+    /** ExecutionTree for tree operations */
+    ExecutionTree: typeof ExecutionTree;
+    /** LLMist client */
+    LLMist: typeof LLMist;
+    /** Zod schema builder */
+    z: typeof zod.z;
 }
 /**
  * Parent agent configuration passed to gadgets.
@@ -2143,13 +3128,16 @@ declare class LLMMessageBuilder {
      * Record a gadget execution result in the message history.
      * Creates an assistant message with the gadget invocation and a user message with the result.
      *
+     * The invocationId is shown to the LLM so it can reference previous calls when building dependencies.
+     *
      * @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 invocationId - Invocation ID (shown to LLM so it can reference for dependencies)
      * @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;
+    addGadgetCallResult(gadget: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[]): this;
     /**
      * Format parameters as Block format with JSON Pointer paths.
      * Uses the configured argPrefix for consistency with system prompt.
@@ -3623,15 +4611,6 @@ interface AgentOptions {
         /** Maps text content to the result string (optional, defaults to text) */
         resultMapping?: (text: string) => string;
     };
-    /** Stop on gadget error */
-    stopOnGadgetError?: boolean;
-    /** Custom error recovery logic */
-    canRecoverFromGadgetError?: (context: {
-        error: string;
-        gadgetName: string;
-        errorType: "parse" | "validation" | "execution";
-        parameters?: Record<string, unknown>;
-    }) => boolean | Promise<boolean>;
     /** Default gadget timeout */
     defaultGadgetTimeoutMs?: number;
     /** Custom prompt configuration for gadget system prompts */
@@ -3648,6 +4627,22 @@ interface AgentOptions {
     subagentConfig?: SubagentConfigMap;
     /** Callback for subagent gadgets to report subagent events to parent */
     onSubagentEvent?: (event: SubagentEvent) => void;
+    /**
+     * Shared execution tree for tracking all LLM calls and gadget executions.
+     * If provided (by a parent subagent), nodes are added to this tree.
+     * If not provided, the Agent creates its own tree.
+     */
+    parentTree?: ExecutionTree;
+    /**
+     * Parent node ID in the tree (when this agent is a subagent).
+     * Used to set parentId on all nodes created by this agent.
+     */
+    parentNodeId?: NodeId;
+    /**
+     * Base depth for nodes created by this agent.
+     * Root agents use 0; subagents use (parentDepth + 1).
+     */
+    baseDepth?: number;
 }
 /**
  * Agent: Lean orchestrator that delegates to StreamProcessor.
@@ -3679,8 +4674,6 @@ declare class Agent {
     private readonly requestHumanInput?;
     private readonly textOnlyHandler;
     private readonly textWithGadgetsHandler?;
-    private readonly stopOnGadgetError;
-    private readonly canRecoverFromGadgetError?;
     private readonly defaultGadgetTimeoutMs?;
     private readonly defaultMaxTokens?;
     private hasUserPrompt;
@@ -3695,6 +4688,10 @@ declare class Agent {
     private readonly userSubagentEventCallback?;
     private readonly pendingSubagentEvents;
     private readonly onSubagentEvent;
+    private syntheticInvocationCounter;
+    private readonly tree;
+    private readonly parentNodeId;
+    private readonly baseDepth;
     /**
      * Creates a new Agent instance.
      * @internal This constructor is private. Use LLMist.createAgent() or AgentBuilder instead.
@@ -3752,6 +4749,46 @@ declare class Agent {
      * ```
      */
     getMediaStore(): MediaStore;
+    /**
+     * Get the execution tree for this agent.
+     *
+     * The execution tree provides a first-class model of all LLM calls and gadget executions,
+     * including nested subagent activity. Use this to:
+     * - Query execution state: `tree.getNode(id)`
+     * - Get total cost: `tree.getTotalCost()`
+     * - Get subtree cost/media/tokens: `tree.getSubtreeCost(nodeId)`
+     * - Subscribe to events: `tree.on("llm_call_complete", handler)`
+     * - Stream all events: `for await (const event of tree.events())`
+     *
+     * For subagents (created with `withParentContext`), the tree is shared with the parent,
+     * enabling unified tracking and real-time visibility across all nesting levels.
+     *
+     * @returns The ExecutionTree instance
+     *
+     * @example
+     * ```typescript
+     * const agent = LLMist.createAgent()
+     *   .withModel("sonnet")
+     *   .withGadgets(BrowseWeb)
+     *   .ask("Research topic X");
+     *
+     * for await (const event of agent.run()) {
+     *   // Process events...
+     * }
+     *
+     * // After execution, query the tree
+     * const tree = agent.getTree();
+     * console.log(`Total cost: $${tree.getTotalCost().toFixed(4)}`);
+     *
+     * // Inspect all LLM calls
+     * for (const node of tree.getAllNodes()) {
+     *   if (node.type === "llm_call") {
+     *     console.log(`LLM #${node.iteration}: ${node.model}`);
+     *   }
+     * }
+     * ```
+     */
+    getTree(): ExecutionTree;
     /**
      * Manually trigger context compaction.
      *
@@ -3901,8 +4938,6 @@ declare class AgentBuilder {
     private gadgetArgPrefix?;
     private textOnlyHandler?;
     private textWithGadgetsHandler?;
-    private stopOnGadgetError?;
-    private canRecoverFromGadgetError?;
     private defaultGadgetTimeoutMs?;
     private gadgetOutputLimit?;
     private gadgetOutputLimitPercent?;
@@ -4140,61 +5175,6 @@ declare class AgentBuilder {
         parameterMapping: (text: string) => Record<string, unknown>;
         resultMapping?: (text: string) => string;
     }): this;
-    /**
-     * Set whether to stop gadget execution on first error.
-     *
-     * When true (default), if a gadget fails:
-     * - Subsequent gadgets in the same response are skipped
-     * - LLM stream is cancelled to save costs
-     * - Agent loop continues with error in context
-     *
-     * When false:
-     * - All gadgets in the response still execute
-     * - LLM stream continues to completion
-     *
-     * @param stop - Whether to stop on gadget error
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withStopOnGadgetError(false)
-     * ```
-     */
-    withStopOnGadgetError(stop: boolean): this;
-    /**
-     * Set custom error handling logic.
-     *
-     * Provides fine-grained control over whether to continue after different types of errors.
-     * Overrides `stopOnGadgetError` when provided.
-     *
-     * **Note:** This builder method configures the underlying `canRecoverFromGadgetError` option
-     * in `AgentOptions`. The method is named `withErrorHandler` for better developer experience,
-     * 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.
-     * @returns This builder for chaining
-     *
-     * @example
-     * ```typescript
-     * .withErrorHandler((context) => {
-     *   // Stop on parse errors, continue on validation/execution errors
-     *   if (context.errorType === "parse") {
-     *     return false;
-     *   }
-     *   if (context.error.includes("CRITICAL")) {
-     *     return false;
-     *   }
-     *   return true;
-     * })
-     * ```
-     */
-    withErrorHandler(handler: (context: {
-        error: string;
-        gadgetName: string;
-        errorType: "parse" | "validation" | "execution";
-        parameters?: Record<string, unknown>;
-    }) => boolean | Promise<boolean>): this;
     /**
      * Set default timeout for gadget execution.
      *
@@ -4359,6 +5339,15 @@ declare class AgentBuilder {
      * The method extracts `invocationId` and `onSubagentEvent` from the execution
      * context and sets up automatic forwarding via hooks and event wrapping.
      *
+     * **NEW: Shared Tree Model** - When the parent provides an ExecutionTree via context,
+     * the subagent shares that tree instead of creating its own. This enables:
+     * - Unified cost tracking across all nesting levels
+     * - Automatic media aggregation via `tree.getSubtreeMedia(nodeId)`
+     * - Real-time visibility of nested execution in the parent
+     *
+     * **Signal Forwarding** - When parent context includes a signal, it's automatically
+     * forwarded to the subagent for proper cancellation propagation.
+     *
      * @param ctx - ExecutionContext passed to the gadget's execute() method
      * @param depth - Nesting depth (default: 1 for direct child)
      * @returns This builder for chaining
@@ -4379,6 +5368,11 @@ declare class AgentBuilder {
      *       result = event.content;
      *     }
      *   }
+     *
+     *   // After subagent completes, costs are automatically aggregated
+     *   // No manual tracking needed - use tree methods:
+     *   const totalCost = ctx.tree?.getSubtreeCost(ctx.nodeId!);
+     *   const allMedia = ctx.tree?.getSubtreeMedia(ctx.nodeId!);
      * }
      * ```
      */
@@ -4410,11 +5404,13 @@ declare class AgentBuilder {
      *
      * This is useful for in-context learning - showing the LLM what "past self"
      * did correctly so it mimics the pattern. The call is formatted with proper
-     * markers and parameter format.
+     * markers and parameter format, including the invocation ID so the LLM can
+     * reference previous calls when building dependencies.
      *
      * @param gadgetName - Name of the gadget
      * @param parameters - Parameters passed to the gadget
      * @param result - Result returned by the gadget
+     * @param invocationId - Invocation ID (shown to LLM so it can reference for dependencies)
      * @returns This builder for chaining
      *
      * @example
@@ -4426,15 +5422,18 @@ declare class AgentBuilder {
      *     done: false,
      *     type: 'info'
      *   },
-     *   'ℹ️  👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands'
+     *   'ℹ️  👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
+     *   'gc_1'
      * )
      * ```
      */
-    withSyntheticGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): this;
+    withSyntheticGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string): this;
     /**
-     * Compose the final hooks, including:
-     * - Trailing message injection (if configured)
-     * - Subagent event forwarding for LLM calls (if parentContext is set)
+     * Compose the final hooks, including trailing message injection if configured.
+     *
+     * Note: Subagent event visibility is now handled entirely by the ExecutionTree.
+     * When a subagent uses withParentContext(ctx), it shares the parent's tree,
+     * and all events are automatically visible to tree subscribers (like the TUI).
      */
     private composeHooks;
     /**
@@ -4604,9 +5603,10 @@ interface IConversationManager {
     addAssistantMessage(content: string): void;
     /**
      * Adds a gadget call and its result to the conversation.
+     * The invocationId is shown to the LLM so it can reference previous calls when building dependencies.
      * Optionally includes media outputs (images, audio, etc.) for multimodal results.
      */
-    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, media?: GadgetMediaOutput[], mediaIds?: string[]): void;
+    addGadgetCallResult(gadgetName: string, parameters: Record<string, unknown>, result: string, invocationId: string, media?: GadgetMediaOutput[], mediaIds?: string[]): void;
     /**
      * Gets the complete conversation history including base messages (system prompts, gadget instructions).
      */
@@ -5342,4 +6342,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 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 };
+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, ExecutionTree as N, type NodeId 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 ExecutionContext as X, type ProviderAdapter as Y, type ModelDescriptor as Z, type ModelSpec as _, type LLMStream as a, type GadgetStartEvent 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 HostExports as a6, type HistoryMessage as a7, type TrailingMessage as a8, type TrailingMessageContext as a9, type ObserveGadgetStartContext as aA, type ObserveLLMCallContext as aB, type ObserveLLMCompleteContext as aC, type ObserveLLMErrorContext as aD, type Observers as aE, type SubagentContext as aF, DEFAULT_COMPACTION_CONFIG as aG, DEFAULT_SUMMARIZATION_PROMPT as aH, type LLMistOptions as aI, type AddGadgetParams as aJ, type AddLLMCallParams as aK, type CompleteGadgetParams as aL, type CompleteLLMCallParams as aM, type ExecutionNode as aN, type ExecutionNodeType as aO, type GadgetNode as aP, type GadgetState as aQ, type LLMCallNode as aR, type BaseExecutionEvent as aS, type CompactionEvent$1 as aT, type ExecutionEvent as aU, type ExecutionEventType as aV, type GadgetCallEvent as aW, type GadgetCompleteEvent as aX, type GadgetErrorEvent as aY, type GadgetEvent as aZ, type GadgetSkippedEvent$1 as a_, AgentBuilder as aa, type EventHandlers as ab, collectEvents as ac, collectText as ad, runWithHandlers as ae, type AfterGadgetExecutionAction as af, type AfterGadgetExecutionControllerContext as ag, type AfterLLMCallAction as ah, type AfterLLMCallControllerContext as ai, type AfterLLMErrorAction as aj, type AgentOptions as ak, type BeforeGadgetExecutionAction as al, type BeforeLLMCallAction as am, type ChunkInterceptorContext as an, type Controllers as ao, type GadgetExecutionControllerContext as ap, type GadgetParameterInterceptorContext as aq, type GadgetResultInterceptorContext as ar, type Interceptors as as, type LLMCallControllerContext as at, type LLMErrorControllerContext as au, type MessageInterceptorContext as av, type MessageTurn as aw, type ObserveChunkContext as ax, type ObserveCompactionContext as ay, type ObserveGadgetCompleteContext as az, type LLMStreamChunk as b, stream as b$, type HumanInputRequiredEvent as b0, type LLMCallCompleteEvent as b1, type LLMCallErrorEvent as b2, type LLMCallStartEvent as b3, type LLMCallStreamEvent as b4, type LLMEvent as b5, type StreamCompleteEvent as b6, type TextEvent as b7, filterByDepth as b8, filterByParent as b9, isTextPart as bA, parseDataUrl as bB, text as bC, toBase64 as bD, type MessageRole as bE, extractMessageText as bF, LLMMessageBuilder as bG, normalizeMessageContent as bH, type CostEstimate as bI, type ModelFeatures as bJ, type ModelLimits as bK, type ModelPricing as bL, type VisionAnalyzeOptions as bM, type VisionAnalyzeResult as bN, type ProviderIdentifier as bO, ModelIdentifierParser as bP, type HintContext as bQ, type PromptContext as bR, type PromptTemplate as bS, type PromptTemplateConfig as bT, DEFAULT_HINTS as bU, DEFAULT_PROMPTS as bV, resolveHintTemplate as bW, resolvePromptTemplate as bX, resolveRulesTemplate as bY, type TextGenerationOptions as bZ, complete as b_, filterRootEvents as ba, groupByParent as bb, isGadgetEvent as bc, isLLMEvent as bd, isRootEvent as be, isSubagentEvent as bf, type AudioContentPart as bg, type AudioMimeType as bh, type AudioSource as bi, type ContentPart as bj, type ImageBase64Source as bk, type ImageContentPart as bl, type ImageMimeType as bm, type ImageSource as bn, type ImageUrlSource as bo, type TextContentPart as bp, audioFromBase64 as bq, audioFromBuffer as br, detectAudioMimeType as bs, detectImageMimeType as bt, imageFromBase64 as bu, imageFromBuffer as bv, imageFromUrl as bw, isAudioPart as bx, isDataUrl as by, isImagePart as bz, createMockAdapter as c, type CreateGadgetConfig as c0, createGadget as c1, type GadgetClass as c2, type GadgetOrClass as c3, type GadgetConfig as c4, Gadget as c5, type CostReportingLLMist as c6, type GadgetExample as c7, type GadgetExecuteResult as c8, type GadgetExecuteReturn as c9, type GadgetSkippedEvent as ca, type StoredMedia as cb, type SubagentStreamEvent as cc, type TextOnlyAction as cd, type TextOnlyContext as ce, type TextOnlyCustomHandler as cf, type TextOnlyGadgetConfig as cg, type TextOnlyHandler as ch, type TextOnlyStrategy as ci, 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 };