llmist 1.7.0 → 2.0.0

package/dist/{mock-stream-BMuFlQI1.d.cts → mock-stream-BQHut0lQ.d.cts}

@@ -315,6 +315,271 @@ interface ResolvedCompactionConfig {
     onCompaction?: (event: CompactionEvent) => void;
 }
 
+/**
+ * Model Registry
+ *
+ * Centralized registry for querying LLM model specifications,
+ * validating configurations, and estimating costs.
+ *
+ * Model data is provided by ProviderAdapter implementations and
+ * automatically populated when providers are registered.
+ */
+
+declare class ModelRegistry {
+    private modelSpecs;
+    private providerMap;
+    /**
+     * Register a provider and collect its model specifications
+     */
+    registerProvider(provider: ProviderAdapter): void;
+    /**
+     * Register a custom model specification at runtime
+     *
+     * Use this to add models that aren't in the built-in catalog, such as:
+     * - Fine-tuned models with custom pricing
+     * - New models not yet supported by llmist
+     * - Custom deployments with different configurations
+     *
+     * @param spec - Complete model specification
+     * @throws {Error} If spec is missing required fields
+     *
+     * @example
+     * ```ts
+     * client.modelRegistry.registerModel({
+     *   provider: "openai",
+     *   modelId: "ft:gpt-4o-2024-08-06:my-org:custom:abc123",
+     *   displayName: "My Fine-tuned GPT-4o",
+     *   contextWindow: 128_000,
+     *   maxOutputTokens: 16_384,
+     *   pricing: { input: 7.5, output: 30.0 },
+     *   knowledgeCutoff: "2024-08",
+     *   features: { streaming: true, functionCalling: true, vision: true }
+     * });
+     * ```
+     */
+    registerModel(spec: ModelSpec): void;
+    /**
+     * Register multiple custom model specifications at once
+     *
+     * @param specs - Array of complete model specifications
+     *
+     * @example
+     * ```ts
+     * client.modelRegistry.registerModels([
+     *   { provider: "openai", modelId: "gpt-5", ... },
+     *   { provider: "openai", modelId: "gpt-5-mini", ... }
+     * ]);
+     * ```
+     */
+    registerModels(specs: ModelSpec[]): void;
+    /**
+     * Get model specification by model ID
+     * @param modelId - Full model identifier (e.g., 'gpt-5', 'claude-sonnet-4-5-20250929')
+     * @returns ModelSpec if found, undefined otherwise
+     */
+    getModelSpec(modelId: string): ModelSpec | undefined;
+    /**
+     * List all models, optionally filtered by provider
+     * @param providerId - Optional provider ID to filter by (e.g., 'openai', 'anthropic')
+     * @returns Array of ModelSpec objects
+     */
+    listModels(providerId?: string): ModelSpec[];
+    /**
+     * Get context window and output limits for a model
+     * @param modelId - Full model identifier
+     * @returns ModelLimits if model found, undefined otherwise
+     */
+    getModelLimits(modelId: string): ModelLimits | undefined;
+    /**
+     * Estimate API cost for a given model and token usage
+     * @param modelId - Full model identifier
+     * @param inputTokens - Number of input tokens (total, including cached and cache creation)
+     * @param outputTokens - Number of output tokens
+     * @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, cachedInputTokens?: number, cacheCreationInputTokens?: number): CostEstimate | undefined;
+    /**
+     * Validate that requested token count fits within model limits
+     * @param modelId - Full model identifier
+     * @param requestedTokens - Total tokens requested (input + output)
+     * @returns true if valid, false if model not found or exceeds limits
+     */
+    validateModelConfig(modelId: string, requestedTokens: number): boolean;
+    /**
+     * Check if a model supports a specific feature
+     * @param modelId - Full model identifier
+     * @param feature - Feature to check ('streaming', 'functionCalling', 'vision', etc.)
+     * @returns true if model supports feature, false otherwise
+     */
+    supportsFeature(modelId: string, feature: keyof ModelSpec["features"]): boolean;
+    /**
+     * Get all models that support a specific feature
+     * @param feature - Feature to filter by
+     * @param providerId - Optional provider ID to filter by
+     * @returns Array of ModelSpec objects that support the feature
+     */
+    getModelsByFeature(feature: keyof ModelSpec["features"], providerId?: string): ModelSpec[];
+    /**
+     * Get the most cost-effective model for a given provider and token budget
+     * @param inputTokens - Expected input tokens
+     * @param outputTokens - Expected output tokens
+     * @param providerId - Optional provider ID to filter by
+     * @returns ModelSpec with lowest total cost, or undefined if no models found
+     */
+    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.
+ *
+ * These methods provide convenient shortcuts for common operations
+ * without requiring full agent setup.
+ *
+ * @example
+ * ```typescript
+ * // Quick completion
+ * const answer = await llmist.complete("What is 2+2?");
+ *
+ * // Quick streaming
+ * for await (const chunk of llmist.stream("Tell me a story")) {
+ *   process.stdout.write(chunk);
+ * }
+ * ```
+ */
+
+/**
+ * Options for quick execution methods.
+ */
+interface QuickOptions {
+    /** Model to use (supports aliases like "gpt4", "sonnet", "flash") */
+    model?: string;
+    /** Temperature (0-1) */
+    temperature?: number;
+    /** System prompt */
+    systemPrompt?: string;
+    /** Max tokens to generate */
+    maxTokens?: number;
+}
+/**
+ * Quick completion - returns final text response.
+ *
+ * @param client - LLMist client instance
+ * @param prompt - User prompt
+ * @param options - Optional configuration
+ * @returns Complete text response
+ *
+ * @example
+ * ```typescript
+ * const client = new LLMist();
+ * const answer = await complete(client, "What is 2+2?");
+ * console.log(answer); // "4" or "2+2 equals 4"
+ * ```
+ */
+declare function complete(client: LLMist, prompt: string, options?: QuickOptions): Promise<string>;
+/**
+ * Quick streaming - returns async generator of text chunks.
+ *
+ * @param client - LLMist client instance
+ * @param prompt - User prompt
+ * @param options - Optional configuration
+ * @returns Async generator yielding text chunks
+ *
+ * @example
+ * ```typescript
+ * const client = new LLMist();
+ *
+ * for await (const chunk of stream(client, "Tell me a story")) {
+ *   process.stdout.write(chunk);
+ * }
+ * ```
+ */
+declare function stream(client: LLMist, prompt: string, options?: QuickOptions): AsyncGenerator<string>;
+
 /**
  * Example of gadget usage to help LLMs understand proper invocation.
  *
@@ -350,7 +615,34 @@ interface GadgetExecutionResult {
     error?: string;
     executionTimeMs: number;
     breaksLoop?: boolean;
+    /** Cost of gadget execution in USD. Defaults to 0 if not provided by gadget. */
+    cost?: number;
 }
+/**
+ * Result returned by gadget execute() method.
+ * Can be a simple string or an object with result and optional cost.
+ *
+ * @example
+ * ```typescript
+ * // Simple string return (free gadget)
+ * execute: () => "result"
+ *
+ * // Object return with cost
+ * execute: () => ({ result: "data", cost: 0.001 })
+ * ```
+ */
+interface GadgetExecuteResult {
+    /** The execution result as a string */
+    result: string;
+    /** Optional cost in USD (e.g., 0.001 for $0.001) */
+    cost?: number;
+}
+/**
+ * Union type for backwards-compatible execute() return type.
+ * Gadgets can return either a string (legacy, cost = 0) or
+ * an object with result and optional cost.
+ */
+type GadgetExecuteReturn = string | GadgetExecuteResult;
 interface ParsedGadgetCall {
     gadgetName: string;
     invocationId: string;
@@ -433,6 +725,174 @@ type TextOnlyAction = {
     name: string;
     parameters: Record<string, unknown>;
 };
+/**
+ * LLMist client interface for use within gadgets.
+ *
+ * Provides LLM completion methods that automatically report costs
+ * via the execution context. All LLM calls made through this client
+ * will have their costs tracked and included in the gadget's total cost.
+ *
+ * @example
+ * ```typescript
+ * execute: async ({ text }, ctx) => {
+ *   // LLM costs are automatically reported
+ *   const summary = await ctx.llmist.complete('Summarize: ' + text, {
+ *     model: 'haiku',
+ *   });
+ *   return summary;
+ * }
+ * ```
+ */
+interface CostReportingLLMist {
+    /**
+     * Quick completion - returns final text response.
+     * Costs are automatically reported to the execution context.
+     */
+    complete(prompt: string, options?: QuickOptions): Promise<string>;
+    /**
+     * Quick streaming - returns async generator of text chunks.
+     * Costs are automatically reported when the stream completes.
+     */
+    streamText(prompt: string, options?: QuickOptions): AsyncGenerator<string>;
+    /**
+     * Low-level stream access for full control.
+     * Costs are automatically reported based on usage metadata in chunks.
+     */
+    stream(options: LLMGenerationOptions): LLMStream;
+    /**
+     * Access to model registry for cost estimation.
+     */
+    readonly modelRegistry: ModelRegistry;
+}
+/**
+ * Execution context provided to gadgets during execution.
+ *
+ * Contains utilities for cost reporting and LLM access.
+ * This parameter is optional for backwards compatibility -
+ * existing gadgets without the context parameter continue to work.
+ *
+ * @example
+ * ```typescript
+ * // Using reportCost() for manual cost reporting
+ * const apiGadget = createGadget({
+ *   description: 'Calls external API',
+ *   schema: z.object({ query: z.string() }),
+ *   execute: async ({ query }, ctx) => {
+ *     const result = await callExternalAPI(query);
+ *     ctx.reportCost(0.001); // Report $0.001 cost
+ *     return result;
+ *   },
+ * });
+ *
+ * // Using ctx.llmist for automatic LLM cost tracking
+ * const summarizer = createGadget({
+ *   description: 'Summarizes text using LLM',
+ *   schema: z.object({ text: z.string() }),
+ *   execute: async ({ text }, ctx) => {
+ *     // LLM costs are automatically reported!
+ *     return ctx.llmist.complete('Summarize: ' + text);
+ *   },
+ * });
+ * ```
+ */
+interface ExecutionContext {
+    /**
+     * Report a cost incurred during gadget execution.
+     *
+     * Costs are accumulated and added to the gadget's total cost.
+     * Can be called multiple times during execution.
+     * This is summed with any cost returned from the execute() method
+     * and any costs from ctx.llmist calls.
+     *
+     * @param amount - Cost in USD (e.g., 0.001 for $0.001)
+     *
+     * @example
+     * ```typescript
+     * execute: async (params, ctx) => {
+     *   await callExternalAPI(params.query);
+     *   ctx.reportCost(0.001); // $0.001 per API call
+     *
+     *   await callAnotherAPI(params.data);
+     *   ctx.reportCost(0.002); // Can be called multiple times
+     *
+     *   return 'done';
+     *   // Total cost: $0.003
+     * }
+     * ```
+     */
+    reportCost(amount: number): void;
+    /**
+     * Pre-configured LLMist client that automatically reports LLM costs
+     * as gadget costs via the reportCost() callback.
+     *
+     * All LLM calls made through this client will have their costs
+     * automatically tracked and included in the gadget's total cost.
+     *
+     * This property is optional - it will be `undefined` if:
+     * - The gadget is executed via CLI `gadget run` command
+     * - The gadget is tested directly without agent context
+     * - No LLMist client was provided to the executor
+     *
+     * Always check for availability before use: `ctx.llmist?.complete(...)`
+     *
+     * @example
+     * ```typescript
+     * execute: async ({ text }, ctx) => {
+     *   // Check if llmist is available
+     *   if (!ctx.llmist) {
+     *     return 'LLM not available in this context';
+     *   }
+     *
+     *   // LLM costs are automatically reported
+     *   const summary = await ctx.llmist.complete('Summarize: ' + text, {
+     *     model: 'haiku',
+     *   });
+     *
+     *   // Additional manual costs can still be reported
+     *   ctx.reportCost(0.0001); // Processing overhead
+     *
+     *   return summary;
+     * }
+     * ```
+     */
+    llmist?: CostReportingLLMist;
+    /**
+     * Abort signal for cancellation support.
+     *
+     * When a gadget times out, this signal is aborted before the TimeoutException
+     * is thrown. Gadgets can use this to clean up resources (close browsers,
+     * cancel HTTP requests, etc.) when execution is cancelled.
+     *
+     * The signal is always provided (never undefined) to simplify gadget code.
+     *
+     * @example
+     * ```typescript
+     * // Check for abort at key checkpoints
+     * execute: async (params, ctx) => {
+     *   if (ctx.signal.aborted) return 'Aborted';
+     *
+     *   await doExpensiveWork();
+     *
+     *   if (ctx.signal.aborted) return 'Aborted';
+     *   return result;
+     * }
+     *
+     * // Register cleanup handlers
+     * execute: async (params, ctx) => {
+     *   const browser = await chromium.launch();
+     *   ctx.signal.addEventListener('abort', () => browser.close(), { once: true });
+     *   // ... use browser
+     * }
+     *
+     * // Pass to fetch for automatic cancellation
+     * execute: async ({ url }, ctx) => {
+     *   const response = await fetch(url, { signal: ctx.signal });
+     *   return await response.text();
+     * }
+     * ```
+     */
+    signal: AbortSignal;
+}
 
 /**
  * Internal base class for gadgets. Most users should use the `Gadget` class
@@ -477,9 +937,67 @@ declare abstract class BaseGadget {
      * Can be synchronous or asynchronous.
      *
      * @param params - Parameters passed from the LLM
-     * @returns Result as a string
+     * @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) {
+     *   return "result";
+     * }
+     *
+     * // Object return with cost tracking
+     * execute(params) {
+     *   return { result: "data", cost: 0.001 };
+     * }
+     *
+     * // Using context for callback-based cost reporting
+     * execute(params, ctx) {
+     *   ctx.reportCost(0.001);
+     *   return "result";
+     * }
+     *
+     * // Using wrapped LLMist for automatic cost tracking
+     * async execute(params, ctx) {
+     *   const summary = await ctx.llmist.complete('Summarize: ' + params.text);
+     *   return summary;
+     * }
+     * ```
+     */
+    abstract execute(params: Record<string, unknown>, ctx?: ExecutionContext): GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
+    /**
+     * Throws an AbortError if the execution has been aborted.
+     *
+     * Call this at key checkpoints in long-running gadgets to allow early exit
+     * when the gadget has been cancelled (e.g., due to timeout). This enables
+     * resource cleanup and prevents unnecessary work after cancellation.
+     *
+     * @param ctx - The execution context containing the abort signal
+     * @throws AbortError if ctx.signal.aborted is true
+     *
+     * @example
+     * ```typescript
+     * class DataProcessor extends Gadget({
+     *   description: 'Processes data in multiple steps',
+     *   schema: z.object({ items: z.array(z.string()) }),
+     * }) {
+     *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
+     *     const results: string[] = [];
+     *
+     *     for (const item of params.items) {
+     *       // Check before each expensive operation
+     *       this.throwIfAborted(ctx);
+     *
+     *       results.push(await this.processItem(item));
+     *     }
+     *
+     *     return results.join(', ');
+     *   }
+     * }
+     * ```
      */
-    abstract execute(params: Record<string, unknown>): string | Promise<string>;
+    throwIfAborted(ctx?: ExecutionContext): void;
     /**
      * Auto-generated instruction text for the LLM.
      * Combines name, description, and parameter schema into a formatted instruction.
@@ -613,146 +1131,63 @@ declare const DEFAULT_PROMPTS: Required<Omit<PromptConfig, "rules" | "customExam
     rules: (context: PromptContext) => string[];
     customExamples: null;
 }>;
-/**
- * Resolve a prompt template to a string using the given context.
- */
-declare function resolvePromptTemplate(template: PromptTemplate | undefined, defaultValue: PromptTemplate, context: PromptContext): string;
-/**
- * Resolve rules template to an array of strings.
- */
-declare function resolveRulesTemplate(rules: PromptConfig["rules"] | undefined, context: PromptContext): string[];
-/**
- * Resolve a hint template to a string using the given context.
- * Supports both function templates and string templates with placeholders.
- *
- * @param template - The hint template to resolve
- * @param defaultValue - Default value if template is undefined
- * @param context - Context for rendering the template
- * @returns The resolved hint string
- */
-declare function resolveHintTemplate(template: HintTemplate | undefined, defaultValue: string, context: HintContext): string;
-
-type LLMRole = "system" | "user" | "assistant";
-interface LLMMessage {
-    role: LLMRole;
-    content: string;
-    name?: string;
-    metadata?: Record<string, unknown>;
-}
-declare class LLMMessageBuilder {
-    private readonly messages;
-    private startPrefix;
-    private endPrefix;
-    private argPrefix;
-    private promptConfig;
-    constructor(promptConfig?: PromptConfig);
-    /**
-     * Set custom prefixes for gadget markers.
-     * Used to configure history builder to match system prompt markers.
-     */
-    withPrefixes(startPrefix: string, endPrefix: string, argPrefix?: string): this;
-    addSystem(content: string, metadata?: Record<string, unknown>): this;
-    addGadgets(gadgets: BaseGadget[], options?: {
-        startPrefix?: string;
-        endPrefix?: string;
-        argPrefix?: string;
-    }): this;
-    private buildGadgetsSection;
-    private buildUsageSection;
-    private buildExamplesSection;
-    private buildRulesSection;
-    addUser(content: string, metadata?: Record<string, unknown>): this;
-    addAssistant(content: string, metadata?: Record<string, unknown>): this;
-    addGadgetCall(gadget: string, parameters: Record<string, unknown>, result: string): this;
-    /**
-     * Format parameters as Block format with JSON Pointer paths.
-     * Uses the configured argPrefix for consistency with system prompt.
-     */
-    private formatBlockParameters;
-    build(): LLMMessage[];
-}
-
-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;
+/**
+ * Resolve a prompt template to a string using the given context.
+ */
+declare function resolvePromptTemplate(template: PromptTemplate | undefined, defaultValue: PromptTemplate, context: PromptContext): string;
+/**
+ * Resolve rules template to an array of strings.
+ */
+declare function resolveRulesTemplate(rules: PromptConfig["rules"] | undefined, context: PromptContext): string[];
+/**
+ * Resolve a hint template to a string using the given context.
+ * Supports both function templates and string templates with placeholders.
+ *
+ * @param template - The hint template to resolve
+ * @param defaultValue - Default value if template is undefined
+ * @param context - Context for rendering the template
+ * @returns The resolved hint string
+ */
+declare function resolveHintTemplate(template: HintTemplate | undefined, defaultValue: string, context: HintContext): string;
+
+type LLMRole = "system" | "user" | "assistant";
+interface LLMMessage {
+    role: LLMRole;
+    content: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
 }
-interface LLMStreamChunk {
-    text: string;
-    /**
-     * Indicates that the provider has finished producing output and includes the reason if available.
-     */
-    finishReason?: string | null;
+declare class LLMMessageBuilder {
+    private readonly messages;
+    private startPrefix;
+    private endPrefix;
+    private argPrefix;
+    private promptConfig;
+    constructor(promptConfig?: PromptConfig);
     /**
-     * Token usage information, typically available in the final chunk when the stream completes.
+     * Set custom prefixes for gadget markers.
+     * Used to configure history builder to match system prompt markers.
      */
-    usage?: TokenUsage;
+    withPrefixes(startPrefix: string, endPrefix: string, argPrefix?: string): this;
+    addSystem(content: string, metadata?: Record<string, unknown>): this;
+    addGadgets(gadgets: BaseGadget[], options?: {
+        startPrefix?: string;
+        endPrefix?: string;
+        argPrefix?: string;
+    }): this;
+    private buildGadgetsSection;
+    private buildUsageSection;
+    private buildExamplesSection;
+    private buildRulesSection;
+    addUser(content: string, metadata?: Record<string, unknown>): this;
+    addAssistant(content: string, metadata?: Record<string, unknown>): this;
+    addGadgetCall(gadget: string, parameters: Record<string, unknown>, result: string): this;
     /**
-     * Provider specific payload emitted at the same time as the text chunk. This is useful for debugging and tests.
+     * Format parameters as Block format with JSON Pointer paths.
+     * Uses the configured argPrefix for consistency with system prompt.
      */
-    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;
+    private formatBlockParameters;
+    build(): LLMMessage[];
 }
 
 interface ProviderAdapter {
@@ -789,188 +1224,6 @@ interface ProviderAdapter {
     countTokens?(messages: LLMMessage[], descriptor: ModelDescriptor, spec?: ModelSpec): Promise<number>;
 }
 
-/**
- * Model Registry
- *
- * Centralized registry for querying LLM model specifications,
- * validating configurations, and estimating costs.
- *
- * Model data is provided by ProviderAdapter implementations and
- * automatically populated when providers are registered.
- */
-
-declare class ModelRegistry {
-    private modelSpecs;
-    private providerMap;
-    /**
-     * Register a provider and collect its model specifications
-     */
-    registerProvider(provider: ProviderAdapter): void;
-    /**
-     * Register a custom model specification at runtime
-     *
-     * Use this to add models that aren't in the built-in catalog, such as:
-     * - Fine-tuned models with custom pricing
-     * - New models not yet supported by llmist
-     * - Custom deployments with different configurations
-     *
-     * @param spec - Complete model specification
-     * @throws {Error} If spec is missing required fields
-     *
-     * @example
-     * ```ts
-     * client.modelRegistry.registerModel({
-     *   provider: "openai",
-     *   modelId: "ft:gpt-4o-2024-08-06:my-org:custom:abc123",
-     *   displayName: "My Fine-tuned GPT-4o",
-     *   contextWindow: 128_000,
-     *   maxOutputTokens: 16_384,
-     *   pricing: { input: 7.5, output: 30.0 },
-     *   knowledgeCutoff: "2024-08",
-     *   features: { streaming: true, functionCalling: true, vision: true }
-     * });
-     * ```
-     */
-    registerModel(spec: ModelSpec): void;
-    /**
-     * Register multiple custom model specifications at once
-     *
-     * @param specs - Array of complete model specifications
-     *
-     * @example
-     * ```ts
-     * client.modelRegistry.registerModels([
-     *   { provider: "openai", modelId: "gpt-5", ... },
-     *   { provider: "openai", modelId: "gpt-5-mini", ... }
-     * ]);
-     * ```
-     */
-    registerModels(specs: ModelSpec[]): void;
-    /**
-     * Get model specification by model ID
-     * @param modelId - Full model identifier (e.g., 'gpt-5', 'claude-sonnet-4-5-20250929')
-     * @returns ModelSpec if found, undefined otherwise
-     */
-    getModelSpec(modelId: string): ModelSpec | undefined;
-    /**
-     * List all models, optionally filtered by provider
-     * @param providerId - Optional provider ID to filter by (e.g., 'openai', 'anthropic')
-     * @returns Array of ModelSpec objects
-     */
-    listModels(providerId?: string): ModelSpec[];
-    /**
-     * Get context window and output limits for a model
-     * @param modelId - Full model identifier
-     * @returns ModelLimits if model found, undefined otherwise
-     */
-    getModelLimits(modelId: string): ModelLimits | undefined;
-    /**
-     * Estimate API cost for a given model and token usage
-     * @param modelId - Full model identifier
-     * @param inputTokens - Number of input tokens (total, including cached and cache creation)
-     * @param outputTokens - Number of output tokens
-     * @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, cachedInputTokens?: number, cacheCreationInputTokens?: number): CostEstimate | undefined;
-    /**
-     * Validate that requested token count fits within model limits
-     * @param modelId - Full model identifier
-     * @param requestedTokens - Total tokens requested (input + output)
-     * @returns true if valid, false if model not found or exceeds limits
-     */
-    validateModelConfig(modelId: string, requestedTokens: number): boolean;
-    /**
-     * Check if a model supports a specific feature
-     * @param modelId - Full model identifier
-     * @param feature - Feature to check ('streaming', 'functionCalling', 'vision', etc.)
-     * @returns true if model supports feature, false otherwise
-     */
-    supportsFeature(modelId: string, feature: keyof ModelSpec["features"]): boolean;
-    /**
-     * Get all models that support a specific feature
-     * @param feature - Feature to filter by
-     * @param providerId - Optional provider ID to filter by
-     * @returns Array of ModelSpec objects that support the feature
-     */
-    getModelsByFeature(feature: keyof ModelSpec["features"], providerId?: string): ModelSpec[];
-    /**
-     * Get the most cost-effective model for a given provider and token budget
-     * @param inputTokens - Expected input tokens
-     * @param outputTokens - Expected output tokens
-     * @param providerId - Optional provider ID to filter by
-     * @returns ModelSpec with lowest total cost, or undefined if no models found
-     */
-    getCheapestModel(inputTokens: number, outputTokens: number, providerId?: string): ModelSpec | undefined;
-}
-
-/**
- * Quick execution methods for simple use cases.
- *
- * These methods provide convenient shortcuts for common operations
- * without requiring full agent setup.
- *
- * @example
- * ```typescript
- * // Quick completion
- * const answer = await llmist.complete("What is 2+2?");
- *
- * // Quick streaming
- * for await (const chunk of llmist.stream("Tell me a story")) {
- *   process.stdout.write(chunk);
- * }
- * ```
- */
-
-/**
- * Options for quick execution methods.
- */
-interface QuickOptions {
-    /** Model to use (supports aliases like "gpt4", "sonnet", "flash") */
-    model?: string;
-    /** Temperature (0-1) */
-    temperature?: number;
-    /** System prompt */
-    systemPrompt?: string;
-    /** Max tokens to generate */
-    maxTokens?: number;
-}
-/**
- * Quick completion - returns final text response.
- *
- * @param client - LLMist client instance
- * @param prompt - User prompt
- * @param options - Optional configuration
- * @returns Complete text response
- *
- * @example
- * ```typescript
- * const client = new LLMist();
- * const answer = await complete(client, "What is 2+2?");
- * console.log(answer); // "4" or "2+2 equals 4"
- * ```
- */
-declare function complete(client: LLMist, prompt: string, options?: QuickOptions): Promise<string>;
-/**
- * Quick streaming - returns async generator of text chunks.
- *
- * @param client - LLMist client instance
- * @param prompt - User prompt
- * @param options - Optional configuration
- * @returns Async generator yielding text chunks
- *
- * @example
- * ```typescript
- * const client = new LLMist();
- *
- * for await (const chunk of stream(client, "Tell me a story")) {
- *   process.stdout.write(chunk);
- * }
- * ```
- */
-declare function stream(client: LLMist, prompt: string, options?: QuickOptions): AsyncGenerator<string>;
-
 interface LLMistOptions {
     /**
      * Provider adapters to register manually.
@@ -1508,6 +1761,8 @@ interface ObserveGadgetCompleteContext {
     error?: string;
     executionTimeMs: number;
     breaksLoop?: boolean;
+    /** Cost of gadget execution in USD. 0 if gadget didn't report cost. */
+    cost?: number;
     logger: Logger<ILogObj>;
 }
 /**
@@ -3264,4 +3519,4 @@ declare function createTextMockStream(text: string, options?: {
     usage?: MockResponse["usage"];
 }): LLMStream;
 
-export { type AfterLLMErrorAction as $, type AgentHooks as A, BaseGadget as B, type CompactionStrategy as C, type ModelDescriptor as D, type ModelSpec as E, type LLMGenerationOptions as F, GadgetRegistry as G, type HintTemplate as H, type IConversationManager as I, type HistoryMessage as J, type TrailingMessage as K, type LLMStream as L, MockProviderAdapter as M, type TrailingMessageContext as N, AgentBuilder as O, type ParsedGadgetCall as P, type EventHandlers as Q, type ResolvedCompactionConfig as R, type StreamEvent as S, type TokenUsage as T, collectEvents as U, collectText as V, runWithHandlers as W, type AfterGadgetExecutionAction as X, type AfterGadgetExecutionControllerContext as Y, type AfterLLMCallAction as Z, type AfterLLMCallControllerContext as _, type LLMStreamChunk as a, type AgentOptions as a0, type BeforeGadgetExecutionAction as a1, type BeforeLLMCallAction as a2, type ChunkInterceptorContext as a3, type Controllers as a4, type GadgetExecutionControllerContext as a5, type GadgetParameterInterceptorContext as a6, type GadgetResultInterceptorContext as a7, type Interceptors as a8, type LLMCallControllerContext as a9, DEFAULT_HINTS as aA, DEFAULT_PROMPTS as aB, resolveHintTemplate as aC, resolvePromptTemplate as aD, resolveRulesTemplate as aE, type QuickOptions as aF, complete as aG, stream as aH, type GadgetClass as aI, type GadgetOrClass as aJ, type TextOnlyAction as aK, type TextOnlyContext as aL, type TextOnlyCustomHandler as aM, type TextOnlyGadgetConfig as aN, type TextOnlyHandler as aO, type TextOnlyStrategy as aP, type LLMErrorControllerContext as aa, type MessageInterceptorContext as ab, type ObserveChunkContext as ac, type ObserveGadgetCompleteContext as ad, type ObserveGadgetStartContext as ae, type ObserveLLMCallContext as af, type ObserveLLMCompleteContext as ag, type ObserveLLMErrorContext as ah, type Observers as ai, type MessageTurn as aj, type ObserveCompactionContext as ak, DEFAULT_COMPACTION_CONFIG as al, DEFAULT_SUMMARIZATION_PROMPT as am, type LLMistOptions as an, type LLMRole as ao, LLMMessageBuilder as ap, type CostEstimate as aq, type ModelFeatures as ar, type ModelLimits as as, type ModelPricing as at, type ProviderIdentifier as au, ModelIdentifierParser as av, type HintContext as aw, type PromptConfig as ax, type PromptContext as ay, type PromptTemplate as az, type LLMMessage as b, createMockAdapter as c, MockBuilder as d, createMockClient as e, MockManager as f, getMockManager as g, createMockStream as h, createTextMockStream as i, type MockMatcher as j, type MockMatcherContext as k, type MockOptions as l, mockLLM as m, type MockRegistration as n, type MockResponse as o, type MockStats as p, ModelRegistry as q, type CompactionContext as r, type CompactionResult as s, LLMist as t, type CompactionConfig as u, type CompactionEvent as v, type CompactionStats as w, type GadgetExample as x, type GadgetExecutionResult as y, type ProviderAdapter as z };
+export { type AfterLLMCallAction as $, type AgentHooks as A, BaseGadget as B, type CompactionStrategy as C, type ProviderAdapter as D, type ExecutionContext as E, type ModelDescriptor as F, GadgetRegistry as G, type HintTemplate as H, type IConversationManager as I, type ModelSpec as J, type LLMGenerationOptions as K, type LLMStream as L, MockProviderAdapter as M, type HistoryMessage as N, type TrailingMessage as O, type ParsedGadgetCall as P, type TrailingMessageContext as Q, type ResolvedCompactionConfig as R, type StreamEvent as S, type TokenUsage as T, AgentBuilder as U, type EventHandlers as V, collectEvents as W, collectText as X, runWithHandlers as Y, type AfterGadgetExecutionAction as Z, type AfterGadgetExecutionControllerContext as _, type LLMStreamChunk as a, type AfterLLMCallControllerContext as a0, type AfterLLMErrorAction as a1, type AgentOptions as a2, type BeforeGadgetExecutionAction as a3, type BeforeLLMCallAction as a4, type ChunkInterceptorContext as a5, type Controllers as a6, type GadgetExecutionControllerContext as a7, type GadgetParameterInterceptorContext as a8, type GadgetResultInterceptorContext as a9, type PromptContext as aA, type PromptTemplate as aB, DEFAULT_HINTS as aC, DEFAULT_PROMPTS as aD, resolveHintTemplate as aE, resolvePromptTemplate as aF, resolveRulesTemplate as aG, type QuickOptions as aH, complete as aI, stream as aJ, type GadgetClass as aK, type GadgetOrClass as aL, type CostReportingLLMist as aM, type GadgetExecuteResult as aN, type TextOnlyAction as aO, type TextOnlyContext as aP, type TextOnlyCustomHandler as aQ, type TextOnlyGadgetConfig as aR, type TextOnlyHandler as aS, type TextOnlyStrategy as aT, type Interceptors as aa, type LLMCallControllerContext as ab, type LLMErrorControllerContext as ac, type MessageInterceptorContext as ad, type ObserveChunkContext as ae, type ObserveGadgetCompleteContext as af, type ObserveGadgetStartContext as ag, type ObserveLLMCallContext as ah, type ObserveLLMCompleteContext as ai, type ObserveLLMErrorContext as aj, type Observers as ak, type MessageTurn as al, type ObserveCompactionContext as am, DEFAULT_COMPACTION_CONFIG as an, DEFAULT_SUMMARIZATION_PROMPT as ao, type LLMistOptions as ap, type LLMRole as aq, LLMMessageBuilder as ar, type CostEstimate as as, type ModelFeatures as at, type ModelLimits as au, type ModelPricing as av, type ProviderIdentifier as aw, ModelIdentifierParser as ax, type HintContext as ay, type PromptConfig as az, type LLMMessage as b, createMockAdapter as c, MockBuilder as d, createMockClient as e, MockManager as f, getMockManager as g, createMockStream as h, createTextMockStream as i, type MockMatcher as j, type MockMatcherContext as k, type MockOptions as l, mockLLM as m, type MockRegistration as n, type MockResponse as o, type MockStats as p, ModelRegistry as q, LLMist as r, type CompactionContext as s, type CompactionResult as t, type CompactionConfig as u, type CompactionEvent as v, type CompactionStats as w, type GadgetExecuteReturn as x, type GadgetExample as y, type GadgetExecutionResult as z };