llmist 1.7.0 → 2.0.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { ZodType, ZodTypeAny } from 'zod';
 export { z } from 'zod';
-import { A as AgentHooks, q as ModelRegistry, I as IConversationManager, b as LLMMessage, S as StreamEvent, T as TokenUsage, G as GadgetRegistry, a as LLMStreamChunk, C as CompactionStrategy, R as ResolvedCompactionConfig, r as CompactionContext, s as CompactionResult, t as LLMist, u as CompactionConfig, v as CompactionEvent, w as CompactionStats, H as HintTemplate, x as GadgetExample, B as BaseGadget, P as ParsedGadgetCall, y as GadgetExecutionResult, z as ProviderAdapter, D as ModelDescriptor, E as ModelSpec, F as LLMGenerationOptions, L as LLMStream } from './mock-stream-BMuFlQI1.cjs';
-export { X as AfterGadgetExecutionAction, Y as AfterGadgetExecutionControllerContext, Z as AfterLLMCallAction, _ as AfterLLMCallControllerContext, $ as AfterLLMErrorAction, O as AgentBuilder, a0 as AgentOptions, a1 as BeforeGadgetExecutionAction, a2 as BeforeLLMCallAction, a3 as ChunkInterceptorContext, a4 as Controllers, aq as CostEstimate, al as DEFAULT_COMPACTION_CONFIG, aA as DEFAULT_HINTS, aB as DEFAULT_PROMPTS, am as DEFAULT_SUMMARIZATION_PROMPT, Q as EventHandlers, aI as GadgetClass, a5 as GadgetExecutionControllerContext, aJ as GadgetOrClass, a6 as GadgetParameterInterceptorContext, a7 as GadgetResultInterceptorContext, aw as HintContext, J as HistoryMessage, a8 as Interceptors, a9 as LLMCallControllerContext, aa as LLMErrorControllerContext, ap as LLMMessageBuilder, ao as LLMRole, an as LLMistOptions, ab as MessageInterceptorContext, aj as MessageTurn, d as MockBuilder, f as MockManager, j as MockMatcher, k as MockMatcherContext, l as MockOptions, M as MockProviderAdapter, n as MockRegistration, o as MockResponse, p as MockStats, ar as ModelFeatures, av as ModelIdentifierParser, as as ModelLimits, at as ModelPricing, ac as ObserveChunkContext, ak as ObserveCompactionContext, ad as ObserveGadgetCompleteContext, ae as ObserveGadgetStartContext, af as ObserveLLMCallContext, ag as ObserveLLMCompleteContext, ah as ObserveLLMErrorContext, ai as Observers, ax as PromptConfig, ay as PromptContext, az as PromptTemplate, au as ProviderIdentifier, aF as QuickOptions, aK as TextOnlyAction, aL as TextOnlyContext, aM as TextOnlyCustomHandler, aN as TextOnlyGadgetConfig, aO as TextOnlyHandler, aP as TextOnlyStrategy, K as TrailingMessage, N as TrailingMessageContext, U as collectEvents, V as collectText, aG as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM, aC as resolveHintTemplate, aD as resolvePromptTemplate, aE as resolveRulesTemplate, W as runWithHandlers, aH as stream } from './mock-stream-BMuFlQI1.cjs';
+import { A as AgentHooks, q as ModelRegistry, I as IConversationManager, b as LLMMessage, S as StreamEvent, T as TokenUsage, G as GadgetRegistry, r as LLMist, a as LLMStreamChunk, C as CompactionStrategy, R as ResolvedCompactionConfig, s as CompactionContext, t as CompactionResult, u as CompactionConfig, v as CompactionEvent, w as CompactionStats, H as HintTemplate, E as ExecutionContext, x as GadgetExecuteReturn, y as GadgetExample, B as BaseGadget, P as ParsedGadgetCall, z as GadgetExecutionResult, D as ProviderAdapter, F as ModelDescriptor, J as ModelSpec, K as LLMGenerationOptions, L as LLMStream } from './mock-stream-BQHut0lQ.cjs';
+export { Z as AfterGadgetExecutionAction, _ as AfterGadgetExecutionControllerContext, $ as AfterLLMCallAction, a0 as AfterLLMCallControllerContext, a1 as AfterLLMErrorAction, U as AgentBuilder, a2 as AgentOptions, a3 as BeforeGadgetExecutionAction, a4 as BeforeLLMCallAction, a5 as ChunkInterceptorContext, a6 as Controllers, as as CostEstimate, aM as CostReportingLLMist, an as DEFAULT_COMPACTION_CONFIG, aC as DEFAULT_HINTS, aD as DEFAULT_PROMPTS, ao as DEFAULT_SUMMARIZATION_PROMPT, V as EventHandlers, aK as GadgetClass, aN as GadgetExecuteResult, a7 as GadgetExecutionControllerContext, aL as GadgetOrClass, a8 as GadgetParameterInterceptorContext, a9 as GadgetResultInterceptorContext, ay as HintContext, N as HistoryMessage, aa as Interceptors, ab as LLMCallControllerContext, ac as LLMErrorControllerContext, ar as LLMMessageBuilder, aq as LLMRole, ap as LLMistOptions, ad as MessageInterceptorContext, al as MessageTurn, d as MockBuilder, f as MockManager, j as MockMatcher, k as MockMatcherContext, l as MockOptions, M as MockProviderAdapter, n as MockRegistration, o as MockResponse, p as MockStats, at as ModelFeatures, ax as ModelIdentifierParser, au as ModelLimits, av as ModelPricing, ae as ObserveChunkContext, am as ObserveCompactionContext, af as ObserveGadgetCompleteContext, ag as ObserveGadgetStartContext, ah as ObserveLLMCallContext, ai as ObserveLLMCompleteContext, aj as ObserveLLMErrorContext, ak as Observers, az as PromptConfig, aA as PromptContext, aB as PromptTemplate, aw as ProviderIdentifier, aH as QuickOptions, aO as TextOnlyAction, aP as TextOnlyContext, aQ as TextOnlyCustomHandler, aR as TextOnlyGadgetConfig, aS as TextOnlyHandler, aT as TextOnlyStrategy, O as TrailingMessage, Q as TrailingMessageContext, W as collectEvents, X as collectText, aI as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM, aE as resolveHintTemplate, aF as resolvePromptTemplate, aG as resolveRulesTemplate, Y as runWithHandlers, aJ as stream } from './mock-stream-BQHut0lQ.cjs';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';
@@ -85,7 +85,7 @@ interface ProgressStats {
     totalOutputTokens: number;
     /** Total tokens (input + output) */
     totalTokens: number;
-    /** Cumulative cost in USD (requires modelRegistry) */
+    /** Cumulative cost in USD (includes LLM and gadget costs; requires modelRegistry for LLM cost estimation) */
     totalCost: number;
     /** Elapsed time in seconds since first call */
     elapsedSeconds: number;
@@ -787,6 +787,8 @@ interface StreamProcessorOptions {
     }) => boolean | Promise<boolean>;
     /** Default gadget timeout */
     defaultGadgetTimeoutMs?: number;
+    /** LLMist client for ExecutionContext.llmist */
+    client?: LLMist;
 }
 /**
  * Result of stream processing.
@@ -1441,8 +1443,12 @@ interface CreateGadgetConfig<TSchema extends ZodType> {
     description: string;
     /** Zod schema for parameter validation */
     schema: TSchema;
-    /** Execution function with typed parameters */
-    execute: (params: InferSchema$1<TSchema>) => string | Promise<string>;
+    /**
+     * 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 */
@@ -1591,6 +1597,38 @@ declare class HumanInputException extends Error {
     readonly question: string;
     constructor(question: string);
 }
+/**
+ * Exception thrown when gadget execution is aborted.
+ *
+ * Gadgets can throw this exception when they detect the abort signal has been
+ * triggered. This is typically used via the `throwIfAborted()` helper method
+ * on the Gadget base class.
+ *
+ * @example
+ * ```typescript
+ * class LongRunningGadget extends Gadget({
+ *   name: 'LongRunning',
+ *   description: 'Performs a long operation with checkpoints',
+ *   schema: z.object({ data: z.string() }),
+ * }) {
+ *   async execute(params: this['params'], ctx: ExecutionContext): Promise<string> {
+ *     // Check at key points - throws AbortError if aborted
+ *     this.throwIfAborted(ctx);
+ *
+ *     await this.doPartOne(params.data);
+ *
+ *     this.throwIfAborted(ctx);
+ *
+ *     await this.doPartTwo(params.data);
+ *
+ *     return 'completed';
+ *   }
+ * }
+ * ```
+ */
+declare class AbortError extends Error {
+    constructor(message?: string);
+}
 
 interface ErrorFormatterOptions {
     /** Custom argument prefix for block format examples. Default: "!!!ARG:" */
@@ -1605,14 +1643,21 @@ declare class GadgetExecutor {
     private readonly registry;
     private readonly onHumanInputRequired?;
     private readonly defaultGadgetTimeoutMs?;
+    private readonly client?;
     private readonly logger;
     private readonly errorFormatter;
     private readonly argPrefix;
-    constructor(registry: GadgetRegistry, onHumanInputRequired?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined, errorFormatterOptions?: ErrorFormatterOptions);
+    constructor(registry: GadgetRegistry, onHumanInputRequired?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined, errorFormatterOptions?: ErrorFormatterOptions, client?: LLMist | undefined);
     /**
      * Creates a promise that rejects with a TimeoutException after the specified timeout.
+     * Aborts the provided AbortController before rejecting, allowing gadgets to clean up.
      */
     private createTimeoutPromise;
+    /**
+     * Normalizes gadget execute result to consistent format.
+     * Handles both string returns (backwards compat) and object returns with cost.
+     */
+    private normalizeExecuteResult;
     execute(call: ParsedGadgetCall): Promise<GadgetExecutionResult>;
     executeAll(calls: ParsedGadgetCall[]): Promise<GadgetExecutionResult[]>;
     /**
@@ -1774,18 +1819,30 @@ declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>):
          * Execute the gadget. Subclasses should cast params to this['params'].
          *
          * @param params - Validated parameters from the LLM
-         * @returns Result as a string (or Promise<string> for async gadgets)
+         * @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
-         * execute(params: Record<string, unknown>): string {
-         *   const typed = params as this['params'];
-         *   // Now 'typed' is fully typed!
-         *   return String(typed.a + typed.b);
+         * // 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>): string | Promise<string>;
+        execute(params: Record<string, unknown>, ctx?: ExecutionContext): GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
+        throwIfAborted(ctx?: ExecutionContext): void;
         get instruction(): string;
         getInstruction(optionsOrArgPrefix?: string | {
             argPrefix?: string;
@@ -2169,4 +2226,4 @@ declare class OpenAIChatProvider extends BaseProviderAdapter {
 }
 declare function createOpenAIProviderFromEnv(): OpenAIChatProvider | null;
 
-export { AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, CompactionConfig, CompactionContext, CompactionEvent, CompactionManager, CompactionResult, CompactionStats, CompactionStrategy, ConversationManager, type CreateGadgetConfig, Gadget, type GadgetConfig, GadgetExample, GadgetExecutionResult, GadgetExecutor, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HintTemplate, type HintsConfig, HookPresets, HumanInputException, HybridStrategy, IConversationManager, type IterationHintOptions, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, LLMist, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, type ParallelGadgetHintOptions, ParsedGadgetCall, ProviderAdapter, ResolvedCompactionConfig, SlidingWindowStrategy, type StoredOutput, StreamEvent, StreamParser, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, SummarizationStrategy, TokenUsage, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, iterationProgressHint, parallelGadgetHint, resolveModel, validateAndApplyDefaults, validateGadgetParams };
+export { AbortError, AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, CompactionConfig, CompactionContext, CompactionEvent, CompactionManager, CompactionResult, CompactionStats, CompactionStrategy, ConversationManager, type CreateGadgetConfig, ExecutionContext, Gadget, type GadgetConfig, GadgetExample, GadgetExecuteReturn, GadgetExecutionResult, GadgetExecutor, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HintTemplate, type HintsConfig, HookPresets, HumanInputException, HybridStrategy, IConversationManager, type IterationHintOptions, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, LLMist, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, type ParallelGadgetHintOptions, ParsedGadgetCall, ProviderAdapter, ResolvedCompactionConfig, SlidingWindowStrategy, type StoredOutput, StreamEvent, StreamParser, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, SummarizationStrategy, TokenUsage, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, iterationProgressHint, parallelGadgetHint, resolveModel, validateAndApplyDefaults, validateGadgetParams };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ZodType, ZodTypeAny } from 'zod';
 export { z } from 'zod';
-import { A as AgentHooks, q as ModelRegistry, I as IConversationManager, b as LLMMessage, S as StreamEvent, T as TokenUsage, G as GadgetRegistry, a as LLMStreamChunk, C as CompactionStrategy, R as ResolvedCompactionConfig, r as CompactionContext, s as CompactionResult, t as LLMist, u as CompactionConfig, v as CompactionEvent, w as CompactionStats, H as HintTemplate, x as GadgetExample, B as BaseGadget, P as ParsedGadgetCall, y as GadgetExecutionResult, z as ProviderAdapter, D as ModelDescriptor, E as ModelSpec, F as LLMGenerationOptions, L as LLMStream } from './mock-stream-BMuFlQI1.js';
-export { X as AfterGadgetExecutionAction, Y as AfterGadgetExecutionControllerContext, Z as AfterLLMCallAction, _ as AfterLLMCallControllerContext, $ as AfterLLMErrorAction, O as AgentBuilder, a0 as AgentOptions, a1 as BeforeGadgetExecutionAction, a2 as BeforeLLMCallAction, a3 as ChunkInterceptorContext, a4 as Controllers, aq as CostEstimate, al as DEFAULT_COMPACTION_CONFIG, aA as DEFAULT_HINTS, aB as DEFAULT_PROMPTS, am as DEFAULT_SUMMARIZATION_PROMPT, Q as EventHandlers, aI as GadgetClass, a5 as GadgetExecutionControllerContext, aJ as GadgetOrClass, a6 as GadgetParameterInterceptorContext, a7 as GadgetResultInterceptorContext, aw as HintContext, J as HistoryMessage, a8 as Interceptors, a9 as LLMCallControllerContext, aa as LLMErrorControllerContext, ap as LLMMessageBuilder, ao as LLMRole, an as LLMistOptions, ab as MessageInterceptorContext, aj as MessageTurn, d as MockBuilder, f as MockManager, j as MockMatcher, k as MockMatcherContext, l as MockOptions, M as MockProviderAdapter, n as MockRegistration, o as MockResponse, p as MockStats, ar as ModelFeatures, av as ModelIdentifierParser, as as ModelLimits, at as ModelPricing, ac as ObserveChunkContext, ak as ObserveCompactionContext, ad as ObserveGadgetCompleteContext, ae as ObserveGadgetStartContext, af as ObserveLLMCallContext, ag as ObserveLLMCompleteContext, ah as ObserveLLMErrorContext, ai as Observers, ax as PromptConfig, ay as PromptContext, az as PromptTemplate, au as ProviderIdentifier, aF as QuickOptions, aK as TextOnlyAction, aL as TextOnlyContext, aM as TextOnlyCustomHandler, aN as TextOnlyGadgetConfig, aO as TextOnlyHandler, aP as TextOnlyStrategy, K as TrailingMessage, N as TrailingMessageContext, U as collectEvents, V as collectText, aG as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM, aC as resolveHintTemplate, aD as resolvePromptTemplate, aE as resolveRulesTemplate, W as runWithHandlers, aH as stream } from './mock-stream-BMuFlQI1.js';
+import { A as AgentHooks, q as ModelRegistry, I as IConversationManager, b as LLMMessage, S as StreamEvent, T as TokenUsage, G as GadgetRegistry, r as LLMist, a as LLMStreamChunk, C as CompactionStrategy, R as ResolvedCompactionConfig, s as CompactionContext, t as CompactionResult, u as CompactionConfig, v as CompactionEvent, w as CompactionStats, H as HintTemplate, E as ExecutionContext, x as GadgetExecuteReturn, y as GadgetExample, B as BaseGadget, P as ParsedGadgetCall, z as GadgetExecutionResult, D as ProviderAdapter, F as ModelDescriptor, J as ModelSpec, K as LLMGenerationOptions, L as LLMStream } from './mock-stream-BQHut0lQ.js';
+export { Z as AfterGadgetExecutionAction, _ as AfterGadgetExecutionControllerContext, $ as AfterLLMCallAction, a0 as AfterLLMCallControllerContext, a1 as AfterLLMErrorAction, U as AgentBuilder, a2 as AgentOptions, a3 as BeforeGadgetExecutionAction, a4 as BeforeLLMCallAction, a5 as ChunkInterceptorContext, a6 as Controllers, as as CostEstimate, aM as CostReportingLLMist, an as DEFAULT_COMPACTION_CONFIG, aC as DEFAULT_HINTS, aD as DEFAULT_PROMPTS, ao as DEFAULT_SUMMARIZATION_PROMPT, V as EventHandlers, aK as GadgetClass, aN as GadgetExecuteResult, a7 as GadgetExecutionControllerContext, aL as GadgetOrClass, a8 as GadgetParameterInterceptorContext, a9 as GadgetResultInterceptorContext, ay as HintContext, N as HistoryMessage, aa as Interceptors, ab as LLMCallControllerContext, ac as LLMErrorControllerContext, ar as LLMMessageBuilder, aq as LLMRole, ap as LLMistOptions, ad as MessageInterceptorContext, al as MessageTurn, d as MockBuilder, f as MockManager, j as MockMatcher, k as MockMatcherContext, l as MockOptions, M as MockProviderAdapter, n as MockRegistration, o as MockResponse, p as MockStats, at as ModelFeatures, ax as ModelIdentifierParser, au as ModelLimits, av as ModelPricing, ae as ObserveChunkContext, am as ObserveCompactionContext, af as ObserveGadgetCompleteContext, ag as ObserveGadgetStartContext, ah as ObserveLLMCallContext, ai as ObserveLLMCompleteContext, aj as ObserveLLMErrorContext, ak as Observers, az as PromptConfig, aA as PromptContext, aB as PromptTemplate, aw as ProviderIdentifier, aH as QuickOptions, aO as TextOnlyAction, aP as TextOnlyContext, aQ as TextOnlyCustomHandler, aR as TextOnlyGadgetConfig, aS as TextOnlyHandler, aT as TextOnlyStrategy, O as TrailingMessage, Q as TrailingMessageContext, W as collectEvents, X as collectText, aI as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM, aE as resolveHintTemplate, aF as resolvePromptTemplate, aG as resolveRulesTemplate, Y as runWithHandlers, aJ as stream } from './mock-stream-BQHut0lQ.js';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';
@@ -85,7 +85,7 @@ interface ProgressStats {
     totalOutputTokens: number;
     /** Total tokens (input + output) */
     totalTokens: number;
-    /** Cumulative cost in USD (requires modelRegistry) */
+    /** Cumulative cost in USD (includes LLM and gadget costs; requires modelRegistry for LLM cost estimation) */
     totalCost: number;
     /** Elapsed time in seconds since first call */
     elapsedSeconds: number;
@@ -787,6 +787,8 @@ interface StreamProcessorOptions {
     }) => boolean | Promise<boolean>;
     /** Default gadget timeout */
     defaultGadgetTimeoutMs?: number;
+    /** LLMist client for ExecutionContext.llmist */
+    client?: LLMist;
 }
 /**
  * Result of stream processing.
@@ -1441,8 +1443,12 @@ interface CreateGadgetConfig<TSchema extends ZodType> {
     description: string;
     /** Zod schema for parameter validation */
     schema: TSchema;
-    /** Execution function with typed parameters */
-    execute: (params: InferSchema$1<TSchema>) => string | Promise<string>;
+    /**
+     * 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 */
@@ -1591,6 +1597,38 @@ declare class HumanInputException extends Error {
     readonly question: string;
     constructor(question: string);
 }
+/**
+ * Exception thrown when gadget execution is aborted.
+ *
+ * Gadgets can throw this exception when they detect the abort signal has been
+ * triggered. This is typically used via the `throwIfAborted()` helper method
+ * on the Gadget base class.
+ *
+ * @example
+ * ```typescript
+ * class LongRunningGadget extends Gadget({
+ *   name: 'LongRunning',
+ *   description: 'Performs a long operation with checkpoints',
+ *   schema: z.object({ data: z.string() }),
+ * }) {
+ *   async execute(params: this['params'], ctx: ExecutionContext): Promise<string> {
+ *     // Check at key points - throws AbortError if aborted
+ *     this.throwIfAborted(ctx);
+ *
+ *     await this.doPartOne(params.data);
+ *
+ *     this.throwIfAborted(ctx);
+ *
+ *     await this.doPartTwo(params.data);
+ *
+ *     return 'completed';
+ *   }
+ * }
+ * ```
+ */
+declare class AbortError extends Error {
+    constructor(message?: string);
+}
 
 interface ErrorFormatterOptions {
     /** Custom argument prefix for block format examples. Default: "!!!ARG:" */
@@ -1605,14 +1643,21 @@ declare class GadgetExecutor {
     private readonly registry;
     private readonly onHumanInputRequired?;
     private readonly defaultGadgetTimeoutMs?;
+    private readonly client?;
     private readonly logger;
     private readonly errorFormatter;
     private readonly argPrefix;
-    constructor(registry: GadgetRegistry, onHumanInputRequired?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined, errorFormatterOptions?: ErrorFormatterOptions);
+    constructor(registry: GadgetRegistry, onHumanInputRequired?: ((question: string) => Promise<string>) | undefined, logger?: Logger<ILogObj>, defaultGadgetTimeoutMs?: number | undefined, errorFormatterOptions?: ErrorFormatterOptions, client?: LLMist | undefined);
     /**
      * Creates a promise that rejects with a TimeoutException after the specified timeout.
+     * Aborts the provided AbortController before rejecting, allowing gadgets to clean up.
      */
     private createTimeoutPromise;
+    /**
+     * Normalizes gadget execute result to consistent format.
+     * Handles both string returns (backwards compat) and object returns with cost.
+     */
+    private normalizeExecuteResult;
     execute(call: ParsedGadgetCall): Promise<GadgetExecutionResult>;
     executeAll(calls: ParsedGadgetCall[]): Promise<GadgetExecutionResult[]>;
     /**
@@ -1774,18 +1819,30 @@ declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>):
          * Execute the gadget. Subclasses should cast params to this['params'].
          *
          * @param params - Validated parameters from the LLM
-         * @returns Result as a string (or Promise<string> for async gadgets)
+         * @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
-         * execute(params: Record<string, unknown>): string {
-         *   const typed = params as this['params'];
-         *   // Now 'typed' is fully typed!
-         *   return String(typed.a + typed.b);
+         * // 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>): string | Promise<string>;
+        execute(params: Record<string, unknown>, ctx?: ExecutionContext): GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
+        throwIfAborted(ctx?: ExecutionContext): void;
         get instruction(): string;
         getInstruction(optionsOrArgPrefix?: string | {
             argPrefix?: string;
@@ -2169,4 +2226,4 @@ declare class OpenAIChatProvider extends BaseProviderAdapter {
 }
 declare function createOpenAIProviderFromEnv(): OpenAIChatProvider | null;
 
-export { AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, CompactionConfig, CompactionContext, CompactionEvent, CompactionManager, CompactionResult, CompactionStats, CompactionStrategy, ConversationManager, type CreateGadgetConfig, Gadget, type GadgetConfig, GadgetExample, GadgetExecutionResult, GadgetExecutor, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HintTemplate, type HintsConfig, HookPresets, HumanInputException, HybridStrategy, IConversationManager, type IterationHintOptions, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, LLMist, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, type ParallelGadgetHintOptions, ParsedGadgetCall, ProviderAdapter, ResolvedCompactionConfig, SlidingWindowStrategy, type StoredOutput, StreamEvent, StreamParser, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, SummarizationStrategy, TokenUsage, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, iterationProgressHint, parallelGadgetHint, resolveModel, validateAndApplyDefaults, validateGadgetParams };
+export { AbortError, AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, CompactionConfig, CompactionContext, CompactionEvent, CompactionManager, CompactionResult, CompactionStats, CompactionStrategy, ConversationManager, type CreateGadgetConfig, ExecutionContext, Gadget, type GadgetConfig, GadgetExample, GadgetExecuteReturn, GadgetExecutionResult, GadgetExecutor, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HintTemplate, type HintsConfig, HookPresets, HumanInputException, HybridStrategy, IConversationManager, type IterationHintOptions, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, LLMist, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, type ParallelGadgetHintOptions, ParsedGadgetCall, ProviderAdapter, ResolvedCompactionConfig, SlidingWindowStrategy, type StoredOutput, StreamEvent, StreamParser, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, SummarizationStrategy, TokenUsage, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, iterationProgressHint, parallelGadgetHint, resolveModel, validateAndApplyDefaults, validateGadgetParams };

package/dist/index.js

@@ -5,8 +5,9 @@ import {
   iterationProgressHint,
   parallelGadgetHint,
   z
-} from "./chunk-JGORHSHC.js";
+} from "./chunk-LFSIEPAE.js";
 import {
+  AbortError,
   AgentBuilder,
   AnthropicMessagesProvider,
   BaseGadget,
@@ -64,8 +65,9 @@ import {
   stream,
   validateAndApplyDefaults,
   validateGadgetParams
-} from "./chunk-E52IO2NO.js";
+} from "./chunk-LBHWVCZ2.js";
 export {
+  AbortError,
   AgentBuilder,
   AnthropicMessagesProvider,
   BaseGadget,