llmist 0.6.2 → 0.8.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { ZodType, ZodTypeAny } from 'zod';
 export { z } from 'zod';
-import { A as AgentHooks, o as ModelRegistry, L as LLMMessage, P as ParameterFormat, S as StreamEvent, G as GadgetRegistry, p as LLMStreamChunk, q as GadgetExample, B as BaseGadget, r as ParsedGadgetCall, s as GadgetExecutionResult, t as ProviderAdapter, u as ModelDescriptor, v as ModelSpec, w as LLMGenerationOptions, x as LLMStream } from './mock-stream-B5R6XPif.cjs';
-export { F as AfterGadgetExecutionAction, I as AfterGadgetExecutionControllerContext, J as AfterLLMCallAction, K as AfterLLMCallControllerContext, N as AfterLLMErrorAction, y as AgentBuilder, O as AgentOptions, Q as BeforeGadgetExecutionAction, R as BeforeLLMCallAction, T as ChunkInterceptorContext, U as Controllers, ab as CostEstimate, al as DEFAULT_PROMPTS, E as EventHandlers, as as GadgetClass, V as GadgetExecutionControllerContext, at as GadgetOrClass, W as GadgetParameterInterceptorContext, X as GadgetResultInterceptorContext, H as HistoryMessage, Y as Interceptors, Z as LLMCallControllerContext, _ as LLMErrorControllerContext, aa as LLMMessageBuilder, a9 as LLMRole, a8 as LLMist, a7 as LLMistOptions, $ as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, ac as ModelFeatures, ah as ModelIdentifierParser, ad as ModelLimits, ae as ModelPricing, a0 as ObserveChunkContext, a1 as ObserveGadgetCompleteContext, a2 as ObserveGadgetStartContext, a3 as ObserveLLMCallContext, a4 as ObserveLLMCompleteContext, a5 as ObserveLLMErrorContext, a6 as Observers, ai as PromptConfig, aj as PromptContext, ak as PromptTemplate, af as ProviderIdentifier, ao as QuickOptions, ar as StreamParser, au as TextOnlyAction, av as TextOnlyContext, aw as TextOnlyCustomHandler, ax as TextOnlyGadgetConfig, ay as TextOnlyHandler, az as TextOnlyStrategy, ag as TokenUsage, z as collectEvents, C as collectText, ap as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, am as resolvePromptTemplate, an as resolveRulesTemplate, D as runWithHandlers, aq as stream } from './mock-stream-B5R6XPif.cjs';
+import { A as AgentHooks, o as ModelRegistry, L as LLMMessage, P as ParameterFormat, S as StreamEvent, T as TokenUsage, G as GadgetRegistry, p as LLMStreamChunk, q as GadgetExample, B as BaseGadget, r as ParsedGadgetCall, s as GadgetExecutionResult, t as ProviderAdapter, u as ModelDescriptor, v as ModelSpec, w as LLMGenerationOptions, x as LLMStream } from './mock-stream-CjmvWDc3.cjs';
+export { F as AfterGadgetExecutionAction, I as AfterGadgetExecutionControllerContext, J as AfterLLMCallAction, K as AfterLLMCallControllerContext, N as AfterLLMErrorAction, y as AgentBuilder, O as AgentOptions, Q as BeforeGadgetExecutionAction, R as BeforeLLMCallAction, U as ChunkInterceptorContext, V as Controllers, ac as CostEstimate, al as DEFAULT_PROMPTS, E as EventHandlers, as as GadgetClass, W as GadgetExecutionControllerContext, at as GadgetOrClass, X as GadgetParameterInterceptorContext, Y as GadgetResultInterceptorContext, H as HistoryMessage, Z as Interceptors, _ as LLMCallControllerContext, $ as LLMErrorControllerContext, ab as LLMMessageBuilder, aa as LLMRole, a9 as LLMist, a8 as LLMistOptions, a0 as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, ad as ModelFeatures, ah as ModelIdentifierParser, ae as ModelLimits, af as ModelPricing, a1 as ObserveChunkContext, a2 as ObserveGadgetCompleteContext, a3 as ObserveGadgetStartContext, a4 as ObserveLLMCallContext, a5 as ObserveLLMCompleteContext, a6 as ObserveLLMErrorContext, a7 as Observers, ai as PromptConfig, aj as PromptContext, ak as PromptTemplate, ag as ProviderIdentifier, ao as QuickOptions, ar as StreamParser, au as TextOnlyAction, av as TextOnlyContext, aw as TextOnlyCustomHandler, ax as TextOnlyGadgetConfig, ay as TextOnlyHandler, az as TextOnlyStrategy, z as collectEvents, C as collectText, ap as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, am as resolvePromptTemplate, an as resolveRulesTemplate, D as runWithHandlers, aq as stream } from './mock-stream-CjmvWDc3.cjs';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';
@@ -797,12 +797,8 @@ interface StreamProcessingResult {
     didExecuteGadgets: boolean;
     /** LLM finish reason */
     finishReason: string | null;
-    /** Token usage */
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-    };
+    /** Token usage (including cached token counts when available) */
+    usage?: TokenUsage;
     /** The raw accumulated response text */
     rawResponse: string;
     /** The final message (after interceptors) */
@@ -1660,6 +1656,7 @@ type GeminiChunk = {
         promptTokenCount?: number;
         candidatesTokenCount?: number;
         totalTokenCount?: number;
+        cachedContentTokenCount?: number;
     };
 };
 declare class GeminiGenerativeProvider extends BaseProviderAdapter {
@@ -1769,4 +1766,4 @@ declare class OpenAIChatProvider extends BaseProviderAdapter {
 }
 declare function createOpenAIProviderFromEnv(): OpenAIChatProvider | null;
 
-export { AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, ConversationManager, type CreateGadgetConfig, Gadget, type GadgetConfig, GadgetExample, GadgetExecutionResult, GadgetExecutor, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HookPresets, HumanInputException, type IConversationManager, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, ParsedGadgetCall, ProviderAdapter, type StoredOutput, StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, resolveModel, validateAndApplyDefaults, validateGadgetParams };
+export { AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, ConversationManager, type CreateGadgetConfig, Gadget, type GadgetConfig, GadgetExample, GadgetExecutionResult, GadgetExecutor, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HookPresets, HumanInputException, type IConversationManager, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, ParsedGadgetCall, ProviderAdapter, type StoredOutput, StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, TokenUsage, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, 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, o as ModelRegistry, L as LLMMessage, P as ParameterFormat, S as StreamEvent, G as GadgetRegistry, p as LLMStreamChunk, q as GadgetExample, B as BaseGadget, r as ParsedGadgetCall, s as GadgetExecutionResult, t as ProviderAdapter, u as ModelDescriptor, v as ModelSpec, w as LLMGenerationOptions, x as LLMStream } from './mock-stream-B5R6XPif.js';
-export { F as AfterGadgetExecutionAction, I as AfterGadgetExecutionControllerContext, J as AfterLLMCallAction, K as AfterLLMCallControllerContext, N as AfterLLMErrorAction, y as AgentBuilder, O as AgentOptions, Q as BeforeGadgetExecutionAction, R as BeforeLLMCallAction, T as ChunkInterceptorContext, U as Controllers, ab as CostEstimate, al as DEFAULT_PROMPTS, E as EventHandlers, as as GadgetClass, V as GadgetExecutionControllerContext, at as GadgetOrClass, W as GadgetParameterInterceptorContext, X as GadgetResultInterceptorContext, H as HistoryMessage, Y as Interceptors, Z as LLMCallControllerContext, _ as LLMErrorControllerContext, aa as LLMMessageBuilder, a9 as LLMRole, a8 as LLMist, a7 as LLMistOptions, $ as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, ac as ModelFeatures, ah as ModelIdentifierParser, ad as ModelLimits, ae as ModelPricing, a0 as ObserveChunkContext, a1 as ObserveGadgetCompleteContext, a2 as ObserveGadgetStartContext, a3 as ObserveLLMCallContext, a4 as ObserveLLMCompleteContext, a5 as ObserveLLMErrorContext, a6 as Observers, ai as PromptConfig, aj as PromptContext, ak as PromptTemplate, af as ProviderIdentifier, ao as QuickOptions, ar as StreamParser, au as TextOnlyAction, av as TextOnlyContext, aw as TextOnlyCustomHandler, ax as TextOnlyGadgetConfig, ay as TextOnlyHandler, az as TextOnlyStrategy, ag as TokenUsage, z as collectEvents, C as collectText, ap as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, am as resolvePromptTemplate, an as resolveRulesTemplate, D as runWithHandlers, aq as stream } from './mock-stream-B5R6XPif.js';
+import { A as AgentHooks, o as ModelRegistry, L as LLMMessage, P as ParameterFormat, S as StreamEvent, T as TokenUsage, G as GadgetRegistry, p as LLMStreamChunk, q as GadgetExample, B as BaseGadget, r as ParsedGadgetCall, s as GadgetExecutionResult, t as ProviderAdapter, u as ModelDescriptor, v as ModelSpec, w as LLMGenerationOptions, x as LLMStream } from './mock-stream-CjmvWDc3.js';
+export { F as AfterGadgetExecutionAction, I as AfterGadgetExecutionControllerContext, J as AfterLLMCallAction, K as AfterLLMCallControllerContext, N as AfterLLMErrorAction, y as AgentBuilder, O as AgentOptions, Q as BeforeGadgetExecutionAction, R as BeforeLLMCallAction, U as ChunkInterceptorContext, V as Controllers, ac as CostEstimate, al as DEFAULT_PROMPTS, E as EventHandlers, as as GadgetClass, W as GadgetExecutionControllerContext, at as GadgetOrClass, X as GadgetParameterInterceptorContext, Y as GadgetResultInterceptorContext, H as HistoryMessage, Z as Interceptors, _ as LLMCallControllerContext, $ as LLMErrorControllerContext, ab as LLMMessageBuilder, aa as LLMRole, a9 as LLMist, a8 as LLMistOptions, a0 as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, ad as ModelFeatures, ah as ModelIdentifierParser, ae as ModelLimits, af as ModelPricing, a1 as ObserveChunkContext, a2 as ObserveGadgetCompleteContext, a3 as ObserveGadgetStartContext, a4 as ObserveLLMCallContext, a5 as ObserveLLMCompleteContext, a6 as ObserveLLMErrorContext, a7 as Observers, ai as PromptConfig, aj as PromptContext, ak as PromptTemplate, ag as ProviderIdentifier, ao as QuickOptions, ar as StreamParser, au as TextOnlyAction, av as TextOnlyContext, aw as TextOnlyCustomHandler, ax as TextOnlyGadgetConfig, ay as TextOnlyHandler, az as TextOnlyStrategy, z as collectEvents, C as collectText, ap as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, am as resolvePromptTemplate, an as resolveRulesTemplate, D as runWithHandlers, aq as stream } from './mock-stream-CjmvWDc3.js';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';
@@ -797,12 +797,8 @@ interface StreamProcessingResult {
     didExecuteGadgets: boolean;
     /** LLM finish reason */
     finishReason: string | null;
-    /** Token usage */
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-    };
+    /** Token usage (including cached token counts when available) */
+    usage?: TokenUsage;
     /** The raw accumulated response text */
     rawResponse: string;
     /** The final message (after interceptors) */
@@ -1660,6 +1656,7 @@ type GeminiChunk = {
         promptTokenCount?: number;
         candidatesTokenCount?: number;
         totalTokenCount?: number;
+        cachedContentTokenCount?: number;
     };
 };
 declare class GeminiGenerativeProvider extends BaseProviderAdapter {
@@ -1769,4 +1766,4 @@ declare class OpenAIChatProvider extends BaseProviderAdapter {
 }
 declare function createOpenAIProviderFromEnv(): OpenAIChatProvider | null;
 
-export { AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, ConversationManager, type CreateGadgetConfig, Gadget, type GadgetConfig, GadgetExample, GadgetExecutionResult, GadgetExecutor, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HookPresets, HumanInputException, type IConversationManager, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, ParsedGadgetCall, ProviderAdapter, type StoredOutput, StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, resolveModel, validateAndApplyDefaults, validateGadgetParams };
+export { AgentHooks, AnthropicMessagesProvider, BaseGadget, BreakLoopException, ConversationManager, type CreateGadgetConfig, Gadget, type GadgetConfig, GadgetExample, GadgetExecutionResult, GadgetExecutor, GadgetOutputStore, GadgetRegistry, GeminiGenerativeProvider, HookPresets, HumanInputException, type IConversationManager, LLMGenerationOptions, LLMMessage, LLMStream, LLMStreamChunk, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, ModelDescriptor, ModelRegistry, ModelSpec, OpenAIChatProvider, ParsedGadgetCall, ProviderAdapter, type StoredOutput, StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, TokenUsage, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, resolveModel, validateAndApplyDefaults, validateGadgetParams };

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   mockLLM,
   validateAndApplyDefaults,
   validateGadgetParams
-} from "./chunk-TSR25DAY.js";
+} from "./chunk-4IMGADVY.js";
 import {
   AgentBuilder,
   AnthropicMessagesProvider,
@@ -74,7 +74,7 @@ import {
   resolveRulesTemplate,
   runWithHandlers,
   stream
-} from "./chunk-DVK6ZQOV.js";
+} from "./chunk-62M4TDAK.js";
 
 // src/index.ts
 init_builder();

package/dist/{mock-stream-B5R6XPif.d.cts → mock-stream-CjmvWDc3.d.cts}

@@ -374,6 +374,8 @@ interface ModelPricing {
     output: number;
     /** Price per 1 million cached input tokens in USD (if supported) */
     cachedInput?: number;
+    /** Price per 1 million cache write tokens in USD (Anthropic: 1.25x input price) */
+    cacheWriteInput?: number;
 }
 interface ModelFeatures {
     /** Supports streaming responses */
@@ -426,6 +428,10 @@ interface ModelLimits {
 }
 interface CostEstimate {
     inputCost: number;
+    /** Cost for cached input tokens (already included in inputCost calculation) */
+    cachedInputCost: number;
+    /** Cost for cache creation tokens (already included in inputCost calculation, Anthropic only) */
+    cacheCreationCost: number;
     outputCost: number;
     totalCost: number;
     currency: "USD";
@@ -446,6 +452,10 @@ 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;
@@ -587,12 +597,13 @@ declare class ModelRegistry {
     /**
      * Estimate API cost for a given model and token usage
      * @param modelId - Full model identifier
-     * @param inputTokens - Number of input tokens
+     * @param inputTokens - Number of input tokens (total, including cached and cache creation)
      * @param outputTokens - Number of output tokens
-     * @param useCachedInput - Whether to use cached input pricing (if supported by provider)
+     * @param cachedInputTokens - Number of cached input tokens (subset of inputTokens)
+     * @param cacheCreationInputTokens - Number of cache creation tokens (subset of inputTokens, Anthropic only)
      * @returns CostEstimate if model found, undefined otherwise
      */
-    estimateCost(modelId: string, inputTokens: number, outputTokens: number, useCachedInput?: boolean): CostEstimate | undefined;
+    estimateCost(modelId: string, inputTokens: number, outputTokens: number, cachedInputTokens?: number, cacheCreationInputTokens?: number): CostEstimate | undefined;
     /**
      * Validate that requested token count fits within model limits
      * @param modelId - Full model identifier
@@ -1179,11 +1190,8 @@ interface ObserveLLMCompleteContext {
     iteration: number;
     options: Readonly<LLMGenerationOptions>;
     finishReason: string | null;
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-    };
+    /** Token usage including cached token counts when available */
+    usage?: TokenUsage;
     /** The complete raw response text */
     rawResponse: string;
     /** The final message that will be added to history (after interceptors) */
@@ -1242,12 +1250,8 @@ interface ObserveChunkContext {
     rawChunk: string;
     /** Accumulated text so far */
     accumulatedText: string;
-    /** Token usage if available (Anthropic sends input tokens at stream start) */
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-    };
+    /** Token usage if available (providers send usage at stream start/end) */
+    usage?: TokenUsage;
     logger: Logger<ILogObj>;
 }
 /**
@@ -1387,11 +1391,8 @@ interface AfterLLMCallControllerContext {
     iteration: number;
     options: Readonly<LLMGenerationOptions>;
     finishReason: string | null;
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-    };
+    /** Token usage including cached token counts when available */
+    usage?: TokenUsage;
     /** The final message (after interceptors) that will be added to history */
     finalMessage: string;
     logger: Logger<ILogObj>;
@@ -1565,6 +1566,18 @@ interface AgentOptions {
     }>;
     /** Text-only handler */
     textOnlyHandler?: TextOnlyHandler;
+    /**
+     * Handler for text content that appears alongside gadget calls.
+     * When set, text accompanying gadgets will be wrapped as a synthetic gadget call.
+     */
+    textWithGadgetsHandler?: {
+        /** Name of the gadget to use for wrapping text */
+        gadgetName: string;
+        /** Maps text content to gadget parameters */
+        parameterMapping: (text: string) => Record<string, unknown>;
+        /** Maps text content to the result string (optional, defaults to text) */
+        resultMapping?: (text: string) => string;
+    };
     /** Stop on gadget error */
     stopOnGadgetError?: boolean;
     /** Custom error continuation logic */
@@ -1612,6 +1625,7 @@ declare class Agent {
     private readonly gadgetEndPrefix?;
     private readonly onHumanInputRequired?;
     private readonly textOnlyHandler;
+    private readonly textWithGadgetsHandler?;
     private readonly stopOnGadgetError;
     private readonly shouldContinueAfterError?;
     private readonly defaultGadgetTimeoutMs?;
@@ -1741,6 +1755,7 @@ declare class AgentBuilder {
     private gadgetStartPrefix?;
     private gadgetEndPrefix?;
     private textOnlyHandler?;
+    private textWithGadgetsHandler?;
     private stopOnGadgetError?;
     private shouldContinueAfterError?;
     private defaultGadgetTimeoutMs?;
@@ -1949,6 +1964,31 @@ declare class AgentBuilder {
      * ```
      */
     withTextOnlyHandler(handler: TextOnlyHandler): this;
+    /**
+     * Set the handler for text content that appears alongside gadget calls.
+     *
+     * When set, text accompanying gadget responses will be wrapped as a
+     * synthetic gadget call before the actual gadget results in the
+     * conversation history.
+     *
+     * @param handler - Configuration for wrapping text
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * // Wrap text as TellUser gadget
+     * .withTextWithGadgetsHandler({
+     *   gadgetName: "TellUser",
+     *   parameterMapping: (text) => ({ message: text, done: false, type: "info" }),
+     *   resultMapping: (text) => `ℹ️  ${text}`,
+     * })
+     * ```
+     */
+    withTextWithGadgetsHandler(handler: {
+        gadgetName: string;
+        parameterMapping: (text: string) => Record<string, unknown>;
+        resultMapping?: (text: string) => string;
+    }): this;
     /**
      * Set whether to stop gadget execution on first error.
      *
@@ -2047,6 +2087,37 @@ declare class AgentBuilder {
      * ```
      */
     withGadgetOutputLimitPercent(percent: number): this;
+    /**
+     * Add a synthetic gadget call to the conversation history.
+     *
+     * 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.
+     *
+     * @param gadgetName - Name of the gadget
+     * @param parameters - Parameters passed to the gadget
+     * @param result - Result returned by the gadget
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withSyntheticGadgetCall(
+     *   'TellUser',
+     *   {
+     *     message: '👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
+     *     done: false,
+     *     type: 'info'
+     *   },
+     *   'ℹ️  👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands'
+     * )
+     * ```
+     */
+    withSyntheticGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): this;
+    /**
+     * Format parameters for synthetic gadget calls.
+     * Uses heredoc for multiline string values.
+     */
+    private formatSyntheticParameters;
     /**
      * Build and create the agent with the given user prompt.
      * Returns the Agent instance ready to run.
@@ -2702,4 +2773,4 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
-export { type MessageInterceptorContext as $, type AgentHooks as A, BaseGadget as B, collectText as C, runWithHandlers as D, type EventHandlers as E, type AfterGadgetExecutionAction as F, GadgetRegistry as G, type HistoryMessage as H, type AfterGadgetExecutionControllerContext as I, type AfterLLMCallAction as J, type AfterLLMCallControllerContext as K, type LLMMessage as L, MockProviderAdapter as M, type AfterLLMErrorAction as N, type AgentOptions as O, type ParameterFormat as P, type BeforeGadgetExecutionAction as Q, type BeforeLLMCallAction as R, type StreamEvent as S, type ChunkInterceptorContext as T, type Controllers as U, type GadgetExecutionControllerContext as V, type GadgetParameterInterceptorContext as W, type GadgetResultInterceptorContext as X, type Interceptors as Y, type LLMCallControllerContext as Z, type LLMErrorControllerContext as _, MockBuilder as a, type ObserveChunkContext as a0, type ObserveGadgetCompleteContext as a1, type ObserveGadgetStartContext as a2, type ObserveLLMCallContext as a3, type ObserveLLMCompleteContext as a4, type ObserveLLMErrorContext as a5, type Observers as a6, type LLMistOptions as a7, LLMist as a8, type LLMRole as a9, LLMMessageBuilder as aa, type CostEstimate as ab, type ModelFeatures as ac, type ModelLimits as ad, type ModelPricing as ae, type ProviderIdentifier as af, type TokenUsage as ag, ModelIdentifierParser as ah, type PromptConfig as ai, type PromptContext as aj, type PromptTemplate as ak, DEFAULT_PROMPTS as al, resolvePromptTemplate as am, resolveRulesTemplate as an, type QuickOptions as ao, complete as ap, stream as aq, StreamParser as ar, type GadgetClass as as, type GadgetOrClass as at, type TextOnlyAction as au, type TextOnlyContext as av, type TextOnlyCustomHandler as aw, type TextOnlyGadgetConfig as ax, type TextOnlyHandler as ay, type TextOnlyStrategy as az, createMockClient as b, createMockAdapter as c, MockManager as d, createMockStream as e, createTextMockStream as f, getMockManager as g, type MockMatcher as h, type MockMatcherContext as i, type MockOptions as j, type MockRegistration as k, type MockResponse as l, mockLLM as m, type MockStats as n, ModelRegistry as o, type LLMStreamChunk as p, type GadgetExample as q, type ParsedGadgetCall as r, type GadgetExecutionResult as s, type ProviderAdapter as t, type ModelDescriptor as u, type ModelSpec as v, type LLMGenerationOptions as w, type LLMStream as x, AgentBuilder as y, collectEvents as z };
+export { type LLMErrorControllerContext as $, type AgentHooks as A, BaseGadget as B, collectText as C, runWithHandlers as D, type EventHandlers as E, type AfterGadgetExecutionAction as F, GadgetRegistry as G, type HistoryMessage as H, type AfterGadgetExecutionControllerContext as I, type AfterLLMCallAction as J, type AfterLLMCallControllerContext as K, type LLMMessage as L, MockProviderAdapter as M, type AfterLLMErrorAction as N, type AgentOptions as O, type ParameterFormat as P, type BeforeGadgetExecutionAction as Q, type BeforeLLMCallAction as R, type StreamEvent as S, type TokenUsage as T, type ChunkInterceptorContext as U, type Controllers as V, type GadgetExecutionControllerContext as W, type GadgetParameterInterceptorContext as X, type GadgetResultInterceptorContext as Y, type Interceptors as Z, type LLMCallControllerContext as _, MockBuilder as a, type MessageInterceptorContext as a0, type ObserveChunkContext as a1, type ObserveGadgetCompleteContext as a2, type ObserveGadgetStartContext as a3, type ObserveLLMCallContext as a4, type ObserveLLMCompleteContext as a5, type ObserveLLMErrorContext as a6, type Observers as a7, type LLMistOptions as a8, LLMist as a9, type LLMRole as aa, LLMMessageBuilder as ab, type CostEstimate as ac, type ModelFeatures as ad, type ModelLimits as ae, type ModelPricing as af, type ProviderIdentifier as ag, ModelIdentifierParser as ah, type PromptConfig as ai, type PromptContext as aj, type PromptTemplate as ak, DEFAULT_PROMPTS as al, resolvePromptTemplate as am, resolveRulesTemplate as an, type QuickOptions as ao, complete as ap, stream as aq, StreamParser as ar, type GadgetClass as as, type GadgetOrClass as at, type TextOnlyAction as au, type TextOnlyContext as av, type TextOnlyCustomHandler as aw, type TextOnlyGadgetConfig as ax, type TextOnlyHandler as ay, type TextOnlyStrategy as az, createMockClient as b, createMockAdapter as c, MockManager as d, createMockStream as e, createTextMockStream as f, getMockManager as g, type MockMatcher as h, type MockMatcherContext as i, type MockOptions as j, type MockRegistration as k, type MockResponse as l, mockLLM as m, type MockStats as n, ModelRegistry as o, type LLMStreamChunk as p, type GadgetExample as q, type ParsedGadgetCall as r, type GadgetExecutionResult as s, type ProviderAdapter as t, type ModelDescriptor as u, type ModelSpec as v, type LLMGenerationOptions as w, type LLMStream as x, AgentBuilder as y, collectEvents as z };

package/dist/{mock-stream-B5R6XPif.d.ts → mock-stream-CjmvWDc3.d.ts}

@@ -374,6 +374,8 @@ interface ModelPricing {
     output: number;
     /** Price per 1 million cached input tokens in USD (if supported) */
     cachedInput?: number;
+    /** Price per 1 million cache write tokens in USD (Anthropic: 1.25x input price) */
+    cacheWriteInput?: number;
 }
 interface ModelFeatures {
     /** Supports streaming responses */
@@ -426,6 +428,10 @@ interface ModelLimits {
 }
 interface CostEstimate {
     inputCost: number;
+    /** Cost for cached input tokens (already included in inputCost calculation) */
+    cachedInputCost: number;
+    /** Cost for cache creation tokens (already included in inputCost calculation, Anthropic only) */
+    cacheCreationCost: number;
     outputCost: number;
     totalCost: number;
     currency: "USD";
@@ -446,6 +452,10 @@ 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;
@@ -587,12 +597,13 @@ declare class ModelRegistry {
     /**
      * Estimate API cost for a given model and token usage
      * @param modelId - Full model identifier
-     * @param inputTokens - Number of input tokens
+     * @param inputTokens - Number of input tokens (total, including cached and cache creation)
      * @param outputTokens - Number of output tokens
-     * @param useCachedInput - Whether to use cached input pricing (if supported by provider)
+     * @param cachedInputTokens - Number of cached input tokens (subset of inputTokens)
+     * @param cacheCreationInputTokens - Number of cache creation tokens (subset of inputTokens, Anthropic only)
      * @returns CostEstimate if model found, undefined otherwise
      */
-    estimateCost(modelId: string, inputTokens: number, outputTokens: number, useCachedInput?: boolean): CostEstimate | undefined;
+    estimateCost(modelId: string, inputTokens: number, outputTokens: number, cachedInputTokens?: number, cacheCreationInputTokens?: number): CostEstimate | undefined;
     /**
      * Validate that requested token count fits within model limits
      * @param modelId - Full model identifier
@@ -1179,11 +1190,8 @@ interface ObserveLLMCompleteContext {
     iteration: number;
     options: Readonly<LLMGenerationOptions>;
     finishReason: string | null;
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-    };
+    /** Token usage including cached token counts when available */
+    usage?: TokenUsage;
     /** The complete raw response text */
     rawResponse: string;
     /** The final message that will be added to history (after interceptors) */
@@ -1242,12 +1250,8 @@ interface ObserveChunkContext {
     rawChunk: string;
     /** Accumulated text so far */
     accumulatedText: string;
-    /** Token usage if available (Anthropic sends input tokens at stream start) */
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-    };
+    /** Token usage if available (providers send usage at stream start/end) */
+    usage?: TokenUsage;
     logger: Logger<ILogObj>;
 }
 /**
@@ -1387,11 +1391,8 @@ interface AfterLLMCallControllerContext {
     iteration: number;
     options: Readonly<LLMGenerationOptions>;
     finishReason: string | null;
-    usage?: {
-        inputTokens: number;
-        outputTokens: number;
-        totalTokens: number;
-    };
+    /** Token usage including cached token counts when available */
+    usage?: TokenUsage;
     /** The final message (after interceptors) that will be added to history */
     finalMessage: string;
     logger: Logger<ILogObj>;
@@ -1565,6 +1566,18 @@ interface AgentOptions {
     }>;
     /** Text-only handler */
     textOnlyHandler?: TextOnlyHandler;
+    /**
+     * Handler for text content that appears alongside gadget calls.
+     * When set, text accompanying gadgets will be wrapped as a synthetic gadget call.
+     */
+    textWithGadgetsHandler?: {
+        /** Name of the gadget to use for wrapping text */
+        gadgetName: string;
+        /** Maps text content to gadget parameters */
+        parameterMapping: (text: string) => Record<string, unknown>;
+        /** Maps text content to the result string (optional, defaults to text) */
+        resultMapping?: (text: string) => string;
+    };
     /** Stop on gadget error */
     stopOnGadgetError?: boolean;
     /** Custom error continuation logic */
@@ -1612,6 +1625,7 @@ declare class Agent {
     private readonly gadgetEndPrefix?;
     private readonly onHumanInputRequired?;
     private readonly textOnlyHandler;
+    private readonly textWithGadgetsHandler?;
     private readonly stopOnGadgetError;
     private readonly shouldContinueAfterError?;
     private readonly defaultGadgetTimeoutMs?;
@@ -1741,6 +1755,7 @@ declare class AgentBuilder {
     private gadgetStartPrefix?;
     private gadgetEndPrefix?;
     private textOnlyHandler?;
+    private textWithGadgetsHandler?;
     private stopOnGadgetError?;
     private shouldContinueAfterError?;
     private defaultGadgetTimeoutMs?;
@@ -1949,6 +1964,31 @@ declare class AgentBuilder {
      * ```
      */
     withTextOnlyHandler(handler: TextOnlyHandler): this;
+    /**
+     * Set the handler for text content that appears alongside gadget calls.
+     *
+     * When set, text accompanying gadget responses will be wrapped as a
+     * synthetic gadget call before the actual gadget results in the
+     * conversation history.
+     *
+     * @param handler - Configuration for wrapping text
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * // Wrap text as TellUser gadget
+     * .withTextWithGadgetsHandler({
+     *   gadgetName: "TellUser",
+     *   parameterMapping: (text) => ({ message: text, done: false, type: "info" }),
+     *   resultMapping: (text) => `ℹ️  ${text}`,
+     * })
+     * ```
+     */
+    withTextWithGadgetsHandler(handler: {
+        gadgetName: string;
+        parameterMapping: (text: string) => Record<string, unknown>;
+        resultMapping?: (text: string) => string;
+    }): this;
     /**
      * Set whether to stop gadget execution on first error.
      *
@@ -2047,6 +2087,37 @@ declare class AgentBuilder {
      * ```
      */
     withGadgetOutputLimitPercent(percent: number): this;
+    /**
+     * Add a synthetic gadget call to the conversation history.
+     *
+     * 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.
+     *
+     * @param gadgetName - Name of the gadget
+     * @param parameters - Parameters passed to the gadget
+     * @param result - Result returned by the gadget
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withSyntheticGadgetCall(
+     *   'TellUser',
+     *   {
+     *     message: '👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
+     *     done: false,
+     *     type: 'info'
+     *   },
+     *   'ℹ️  👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands'
+     * )
+     * ```
+     */
+    withSyntheticGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): this;
+    /**
+     * Format parameters for synthetic gadget calls.
+     * Uses heredoc for multiline string values.
+     */
+    private formatSyntheticParameters;
     /**
      * Build and create the agent with the given user prompt.
      * Returns the Agent instance ready to run.
@@ -2702,4 +2773,4 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
-export { type MessageInterceptorContext as $, type AgentHooks as A, BaseGadget as B, collectText as C, runWithHandlers as D, type EventHandlers as E, type AfterGadgetExecutionAction as F, GadgetRegistry as G, type HistoryMessage as H, type AfterGadgetExecutionControllerContext as I, type AfterLLMCallAction as J, type AfterLLMCallControllerContext as K, type LLMMessage as L, MockProviderAdapter as M, type AfterLLMErrorAction as N, type AgentOptions as O, type ParameterFormat as P, type BeforeGadgetExecutionAction as Q, type BeforeLLMCallAction as R, type StreamEvent as S, type ChunkInterceptorContext as T, type Controllers as U, type GadgetExecutionControllerContext as V, type GadgetParameterInterceptorContext as W, type GadgetResultInterceptorContext as X, type Interceptors as Y, type LLMCallControllerContext as Z, type LLMErrorControllerContext as _, MockBuilder as a, type ObserveChunkContext as a0, type ObserveGadgetCompleteContext as a1, type ObserveGadgetStartContext as a2, type ObserveLLMCallContext as a3, type ObserveLLMCompleteContext as a4, type ObserveLLMErrorContext as a5, type Observers as a6, type LLMistOptions as a7, LLMist as a8, type LLMRole as a9, LLMMessageBuilder as aa, type CostEstimate as ab, type ModelFeatures as ac, type ModelLimits as ad, type ModelPricing as ae, type ProviderIdentifier as af, type TokenUsage as ag, ModelIdentifierParser as ah, type PromptConfig as ai, type PromptContext as aj, type PromptTemplate as ak, DEFAULT_PROMPTS as al, resolvePromptTemplate as am, resolveRulesTemplate as an, type QuickOptions as ao, complete as ap, stream as aq, StreamParser as ar, type GadgetClass as as, type GadgetOrClass as at, type TextOnlyAction as au, type TextOnlyContext as av, type TextOnlyCustomHandler as aw, type TextOnlyGadgetConfig as ax, type TextOnlyHandler as ay, type TextOnlyStrategy as az, createMockClient as b, createMockAdapter as c, MockManager as d, createMockStream as e, createTextMockStream as f, getMockManager as g, type MockMatcher as h, type MockMatcherContext as i, type MockOptions as j, type MockRegistration as k, type MockResponse as l, mockLLM as m, type MockStats as n, ModelRegistry as o, type LLMStreamChunk as p, type GadgetExample as q, type ParsedGadgetCall as r, type GadgetExecutionResult as s, type ProviderAdapter as t, type ModelDescriptor as u, type ModelSpec as v, type LLMGenerationOptions as w, type LLMStream as x, AgentBuilder as y, collectEvents as z };
+export { type LLMErrorControllerContext as $, type AgentHooks as A, BaseGadget as B, collectText as C, runWithHandlers as D, type EventHandlers as E, type AfterGadgetExecutionAction as F, GadgetRegistry as G, type HistoryMessage as H, type AfterGadgetExecutionControllerContext as I, type AfterLLMCallAction as J, type AfterLLMCallControllerContext as K, type LLMMessage as L, MockProviderAdapter as M, type AfterLLMErrorAction as N, type AgentOptions as O, type ParameterFormat as P, type BeforeGadgetExecutionAction as Q, type BeforeLLMCallAction as R, type StreamEvent as S, type TokenUsage as T, type ChunkInterceptorContext as U, type Controllers as V, type GadgetExecutionControllerContext as W, type GadgetParameterInterceptorContext as X, type GadgetResultInterceptorContext as Y, type Interceptors as Z, type LLMCallControllerContext as _, MockBuilder as a, type MessageInterceptorContext as a0, type ObserveChunkContext as a1, type ObserveGadgetCompleteContext as a2, type ObserveGadgetStartContext as a3, type ObserveLLMCallContext as a4, type ObserveLLMCompleteContext as a5, type ObserveLLMErrorContext as a6, type Observers as a7, type LLMistOptions as a8, LLMist as a9, type LLMRole as aa, LLMMessageBuilder as ab, type CostEstimate as ac, type ModelFeatures as ad, type ModelLimits as ae, type ModelPricing as af, type ProviderIdentifier as ag, ModelIdentifierParser as ah, type PromptConfig as ai, type PromptContext as aj, type PromptTemplate as ak, DEFAULT_PROMPTS as al, resolvePromptTemplate as am, resolveRulesTemplate as an, type QuickOptions as ao, complete as ap, stream as aq, StreamParser as ar, type GadgetClass as as, type GadgetOrClass as at, type TextOnlyAction as au, type TextOnlyContext as av, type TextOnlyCustomHandler as aw, type TextOnlyGadgetConfig as ax, type TextOnlyHandler as ay, type TextOnlyStrategy as az, createMockClient as b, createMockAdapter as c, MockManager as d, createMockStream as e, createTextMockStream as f, getMockManager as g, type MockMatcher as h, type MockMatcherContext as i, type MockOptions as j, type MockRegistration as k, type MockResponse as l, mockLLM as m, type MockStats as n, ModelRegistry as o, type LLMStreamChunk as p, type GadgetExample as q, type ParsedGadgetCall as r, type GadgetExecutionResult as s, type ProviderAdapter as t, type ModelDescriptor as u, type ModelSpec as v, type LLMGenerationOptions as w, type LLMStream as x, AgentBuilder as y, collectEvents as z };