llmist 1.1.0 → 1.3.0

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, S as StreamEvent, T as TokenUsage, G as GadgetRegistry, p as LLMStreamChunk, q as GadgetExample, B as BaseGadget, P as ParsedGadgetCall, r as GadgetExecutionResult, s as ProviderAdapter, t as ModelDescriptor, u as ModelSpec, v as LLMGenerationOptions, w as LLMStream } from './mock-stream-DKF5yatf.js';
-export { D as AfterGadgetExecutionAction, F as AfterGadgetExecutionControllerContext, I as AfterLLMCallAction, J as AfterLLMCallControllerContext, K as AfterLLMErrorAction, x as AgentBuilder, N as AgentOptions, O as BeforeGadgetExecutionAction, Q as BeforeLLMCallAction, R as ChunkInterceptorContext, U as Controllers, ab as CostEstimate, ak as DEFAULT_PROMPTS, E as EventHandlers, aq as GadgetClass, V as GadgetExecutionControllerContext, ar 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, ag 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, ah as PromptConfig, ai as PromptContext, aj as PromptTemplate, af as ProviderIdentifier, an as QuickOptions, as as TextOnlyAction, at as TextOnlyContext, au as TextOnlyCustomHandler, av as TextOnlyGadgetConfig, aw as TextOnlyHandler, ax as TextOnlyStrategy, y as collectEvents, z as collectText, ao as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, al as resolvePromptTemplate, am as resolveRulesTemplate, C as runWithHandlers, ap as stream } from './mock-stream-DKF5yatf.js';
+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-DNt-HBTn.js';
+export { V as AfterGadgetExecutionAction, W as AfterGadgetExecutionControllerContext, X as AfterLLMCallAction, Y as AfterLLMCallControllerContext, Z as AfterLLMErrorAction, K as AgentBuilder, _ as AgentOptions, $ as BeforeGadgetExecutionAction, a0 as BeforeLLMCallAction, a1 as ChunkInterceptorContext, a2 as Controllers, ao as CostEstimate, aj as DEFAULT_COMPACTION_CONFIG, ay as DEFAULT_HINTS, az as DEFAULT_PROMPTS, ak as DEFAULT_SUMMARIZATION_PROMPT, N as EventHandlers, aG as GadgetClass, a3 as GadgetExecutionControllerContext, aH as GadgetOrClass, a4 as GadgetParameterInterceptorContext, a5 as GadgetResultInterceptorContext, au as HintContext, J as HistoryMessage, a6 as Interceptors, a7 as LLMCallControllerContext, a8 as LLMErrorControllerContext, an as LLMMessageBuilder, am as LLMRole, al as LLMistOptions, a9 as MessageInterceptorContext, ah 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, ap as ModelFeatures, at as ModelIdentifierParser, aq as ModelLimits, ar as ModelPricing, aa as ObserveChunkContext, ai as ObserveCompactionContext, ab as ObserveGadgetCompleteContext, ac as ObserveGadgetStartContext, ad as ObserveLLMCallContext, ae as ObserveLLMCompleteContext, af as ObserveLLMErrorContext, ag as Observers, av as PromptConfig, aw as PromptContext, ax as PromptTemplate, as as ProviderIdentifier, aD as QuickOptions, aI as TextOnlyAction, aJ as TextOnlyContext, aK as TextOnlyCustomHandler, aL as TextOnlyGadgetConfig, aM as TextOnlyHandler, aN as TextOnlyStrategy, O as collectEvents, Q as collectText, aE as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM, aA as resolveHintTemplate, aB as resolvePromptTemplate, aC as resolveRulesTemplate, U as runWithHandlers, aF as stream } from './mock-stream-DNt-HBTn.js';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';
@@ -500,6 +500,31 @@ declare class HookPresets {
      * @see {@link https://github.com/zbigniewsobiecki/llmist/blob/main/docs/HOOKS.md#hookpresetserrorlogging | Full documentation}
      */
     static errorLogging(): AgentHooks;
+    /**
+     * Tracks context compaction events.
+     *
+     * **Output:**
+     * - Compaction events with 🗜️ emoji
+     * - Strategy name, tokens before/after, and savings
+     * - Cumulative statistics
+     *
+     * **Use cases:**
+     * - Monitoring long-running conversations
+     * - Understanding when and how compaction occurs
+     * - Debugging context management issues
+     *
+     * **Performance:** Minimal overhead. Simple console output.
+     *
+     * @returns Hook configuration that can be passed to .withHooks()
+     *
+     * @example
+     * ```typescript
+     * await LLMist.createAgent()
+     *   .withHooks(HookPresets.compactionTracking())
+     *   .ask("Your prompt");
+     * ```
+     */
+    static compactionTracking(): AgentHooks;
     /**
      * Returns empty hook configuration for clean output without any logging.
      *
@@ -687,34 +712,6 @@ declare class HookPresets {
     static monitoring(options?: LoggingOptions): AgentHooks;
 }
 
-/**
- * Core interfaces for the Agent architecture.
- * These interfaces define the contracts for the composable services that make up the agent system.
- */
-
-/**
- * Manages the conversation history and message building.
- * This interface abstracts conversation state management from the orchestration logic.
- */
-interface IConversationManager {
-    /**
-     * Adds a user message to the conversation.
-     */
-    addUserMessage(content: string): void;
-    /**
-     * Adds an assistant message to the conversation.
-     */
-    addAssistantMessage(content: string): void;
-    /**
-     * Adds a gadget call and its result to the conversation.
-     */
-    addGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): void;
-    /**
-     * Gets the complete conversation history including base messages (system prompts, gadget instructions).
-     */
-    getMessages(): LLMMessage[];
-}
-
 /**
  * ConversationManager handles conversation state and message building.
  * Extracted from AgentLoop to follow Single Responsibility Principle.
@@ -738,12 +735,18 @@ interface ConversationManagerOptions {
 declare class ConversationManager implements IConversationManager {
     private readonly baseMessages;
     private readonly initialMessages;
-    private readonly historyBuilder;
+    private historyBuilder;
+    private readonly startPrefix?;
+    private readonly endPrefix?;
+    private readonly argPrefix?;
     constructor(baseMessages: LLMMessage[], initialMessages: LLMMessage[], options?: ConversationManagerOptions);
     addUserMessage(content: string): void;
     addAssistantMessage(content: string): void;
     addGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): void;
     getMessages(): LLMMessage[];
+    getHistoryMessages(): LLMMessage[];
+    getBaseMessages(): LLMMessage[];
+    replaceHistory(newHistory: LLMMessage[]): void;
 }
 
 /**
@@ -968,6 +971,325 @@ declare class GadgetOutputStore {
     private generateId;
 }
 
+/**
+ * Sliding Window Compaction Strategy
+ *
+ * A fast, no-LLM-call strategy that simply keeps the most recent N turns
+ * and drops older ones. Best for:
+ * - Long-running conversations where older context becomes irrelevant
+ * - Scenarios requiring minimal latency
+ * - As a fallback when summarization is too slow
+ */
+
+/**
+ * Sliding window strategy - keeps recent turns, drops older ones.
+ *
+ * This strategy:
+ * 1. Groups messages into logical turns (user + assistant pairs)
+ * 2. Keeps the `preserveRecentTurns` most recent turns
+ * 3. Inserts a truncation marker at the beginning
+ * 4. Requires no LLM call - very fast
+ */
+declare class SlidingWindowStrategy implements CompactionStrategy {
+    readonly name = "sliding-window";
+    compact(messages: LLMMessage[], config: ResolvedCompactionConfig, context: CompactionContext): Promise<CompactionResult>;
+}
+
+/**
+ * Summarization Compaction Strategy
+ *
+ * Uses an LLM to summarize older conversation messages into a concise summary.
+ * Best for:
+ * - Tasks where historical context matters
+ * - Complex multi-step reasoning
+ * - When accuracy is more important than speed
+ */
+
+/**
+ * Summarization strategy - uses LLM to compress conversation history.
+ *
+ * This strategy:
+ * 1. Groups messages into logical turns
+ * 2. Keeps recent turns intact
+ * 3. Summarizes older turns using LLM
+ * 4. Returns summary + recent turns
+ */
+declare class SummarizationStrategy implements CompactionStrategy {
+    readonly name = "summarization";
+    compact(messages: LLMMessage[], config: ResolvedCompactionConfig, context: CompactionContext): Promise<CompactionResult>;
+    /**
+     * Formats messages into a readable conversation format for summarization.
+     */
+    private formatTurnsForSummary;
+    /**
+     * Generates a summary using the configured LLM.
+     */
+    private generateSummary;
+}
+
+/**
+ * Hybrid Compaction Strategy
+ *
+ * Combines sliding window and summarization for the best of both worlds:
+ * 1. Identifies which turns to compact vs keep (like sliding window)
+ * 2. Summarizes the older turns (like summarization)
+ * 3. Returns summary + recent turns intact
+ *
+ * Falls back to sliding window if there are too few turns to summarize.
+ */
+
+/**
+ * Hybrid strategy - summarizes old turns + keeps recent turns.
+ *
+ * This is the recommended default strategy as it:
+ * - Preserves important historical context via summarization
+ * - Keeps recent conversation turns verbatim for continuity
+ * - Falls back gracefully to sliding window when appropriate
+ */
+declare class HybridStrategy implements CompactionStrategy {
+    readonly name = "hybrid";
+    private readonly slidingWindow;
+    private readonly summarization;
+    compact(messages: LLMMessage[], config: ResolvedCompactionConfig, context: CompactionContext): Promise<CompactionResult>;
+}
+
+/**
+ * CompactionManager - Central orchestrator for context compaction.
+ *
+ * Monitors token usage and coordinates compaction strategies to keep
+ * conversation context within model limits.
+ */
+
+/**
+ * Pre-computed token counts to avoid redundant counting.
+ * Passed from checkAndCompact to compact for efficiency.
+ */
+interface PrecomputedTokens {
+    historyMessages: LLMMessage[];
+    baseMessages: LLMMessage[];
+    historyTokens: number;
+    baseTokens: number;
+    currentTokens: number;
+}
+/**
+ * CompactionManager orchestrates context compaction for an agent.
+ *
+ * It:
+ * - Monitors token usage before each LLM call
+ * - Triggers compaction when threshold is exceeded
+ * - Coordinates with ConversationManager to update history
+ * - Tracks statistics for observability
+ */
+declare class CompactionManager {
+    private readonly client;
+    private readonly model;
+    private readonly config;
+    private readonly strategy;
+    private modelLimits?;
+    private totalCompactions;
+    private totalTokensSaved;
+    private lastTokenCount;
+    constructor(client: LLMist, model: string, config?: CompactionConfig);
+    /**
+     * Check if compaction is needed and perform it if so.
+     *
+     * @param conversation - The conversation manager to compact
+     * @param iteration - Current agent iteration (for event metadata)
+     * @returns CompactionEvent if compaction was performed, null otherwise
+     */
+    checkAndCompact(conversation: IConversationManager, iteration: number): Promise<CompactionEvent | null>;
+    /**
+     * Force compaction regardless of threshold.
+     *
+     * @param conversation - The conversation manager to compact
+     * @param iteration - Current agent iteration (for event metadata). Use -1 for manual compaction.
+     * @param precomputed - Optional pre-computed token counts (passed from checkAndCompact for efficiency)
+     * @returns CompactionEvent with compaction details
+     */
+    compact(conversation: IConversationManager, iteration: number, precomputed?: PrecomputedTokens): Promise<CompactionEvent | null>;
+    /**
+     * Get compaction statistics.
+     */
+    getStats(): CompactionStats;
+    /**
+     * Check if compaction is enabled.
+     */
+    isEnabled(): boolean;
+}
+
+/**
+ * LLM Assistance Hints System
+ *
+ * Provides reusable hook factories that inject helpful context and coaching
+ * messages to guide LLM behavior during agentic execution.
+ *
+ * ## Two Types of Hints
+ *
+ * 1. **Proactive (beforeLLMCall)**: Inject context before LLM generates response
+ *    - Example: Iteration progress ("You're on iteration 3/10")
+ *
+ * 2. **Reactive (afterLLMCall)**: Coach based on what LLM did
+ *    - Example: "Tip: You can call multiple gadgets in parallel"
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { createHints, iterationProgressHint, parallelGadgetHint } from "llmist";
+ *
+ * // Option 1: Use individual hints
+ * const agent = new AgentBuilder()
+ *   .withHooks(HookPresets.merge(
+ *     iterationProgressHint({ timing: "late" }),
+ *     parallelGadgetHint(),
+ *   ))
+ *   .build();
+ *
+ * // Option 2: Use convenience factory
+ * const agent = new AgentBuilder()
+ *   .withHooks(createHints({
+ *     iterationProgress: { timing: "late" },
+ *     parallelGadgets: true,
+ *   }))
+ *   .build();
+ * ```
+ *
+ * @module agent/hints
+ */
+
+/**
+ * Options for iteration progress hint.
+ */
+interface IterationHintOptions {
+    /**
+     * When to show the hint.
+     * - "always": Show on every iteration
+     * - "late": Show only when >= 50% through iterations
+     * - "urgent": Show only when >= 80% through iterations
+     * @default "always"
+     */
+    timing?: "always" | "late" | "urgent";
+    /**
+     * Whether to include urgency indicators for late iterations.
+     * Adds extra text when running low on iterations.
+     * @default true
+     */
+    showUrgency?: boolean;
+    /**
+     * Custom template. Supports placeholders: {iteration}, {maxIterations}, {remaining}
+     * Or a function receiving HintContext.
+     * @default DEFAULT_HINTS.iterationProgressHint
+     */
+    template?: HintTemplate;
+}
+/**
+ * Options for parallel gadget usage hint.
+ */
+interface ParallelGadgetHintOptions {
+    /**
+     * Minimum number of gadget calls to consider "efficient".
+     * If response has fewer calls, hint will suggest parallelization.
+     * @default 2
+     */
+    minGadgetsForEfficiency?: number;
+    /**
+     * Custom message when single gadget detected.
+     * @default DEFAULT_HINTS.parallelGadgetsHint
+     */
+    message?: string;
+    /**
+     * Whether to enable this hint.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Combined hints configuration for createHints().
+ */
+interface HintsConfig {
+    /**
+     * Enable iteration progress hints.
+     * Pass `true` for defaults, or options object for customization.
+     */
+    iterationProgress?: boolean | IterationHintOptions;
+    /**
+     * Enable parallel gadget hints.
+     * Pass `true` for defaults, or options object for customization.
+     */
+    parallelGadgets?: boolean | ParallelGadgetHintOptions;
+    /**
+     * Additional custom hooks to merge.
+     */
+    custom?: AgentHooks[];
+}
+/**
+ * Creates a proactive hint that informs the LLM about iteration progress.
+ *
+ * This hint is injected before each LLM call (via beforeLLMCall controller),
+ * helping the LLM understand how much "budget" remains for completing the task.
+ *
+ * @param options - Configuration options
+ * @returns AgentHooks that can be merged with other hooks
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - show on every iteration
+ * const hooks = iterationProgressHint();
+ *
+ * // Show only when running low on iterations
+ * const hooks = iterationProgressHint({ timing: "late" });
+ *
+ * // Custom template
+ * const hooks = iterationProgressHint({
+ *   template: "Turn {iteration} of {maxIterations}. {remaining} turns left.",
+ * });
+ * ```
+ */
+declare function iterationProgressHint(options?: IterationHintOptions): AgentHooks;
+/**
+ * Creates a reactive hint that encourages parallel gadget usage.
+ *
+ * This hint analyzes the LLM's response and, if only a single gadget was called,
+ * appends a reminder that multiple gadgets can be used in parallel for efficiency.
+ *
+ * @param options - Configuration options
+ * @returns AgentHooks that can be merged with other hooks
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const hooks = parallelGadgetHint();
+ *
+ * // Custom threshold and message
+ * const hooks = parallelGadgetHint({
+ *   minGadgetsForEfficiency: 3,
+ *   message: "Consider calling multiple gadgets at once!",
+ * });
+ * ```
+ */
+declare function parallelGadgetHint(options?: ParallelGadgetHintOptions): AgentHooks;
+/**
+ * Creates combined hints from a configuration object.
+ *
+ * This is a convenience function that creates and merges multiple hints
+ * based on a simple configuration object.
+ *
+ * @param config - Configuration for which hints to enable
+ * @returns Merged AgentHooks
+ *
+ * @example
+ * ```typescript
+ * const hooks = createHints({
+ *   iterationProgress: { timing: "late" },
+ *   parallelGadgets: true,
+ * });
+ *
+ * const agent = new AgentBuilder()
+ *   .withHooks(HookPresets.merge(existingHooks, hooks))
+ *   .build();
+ * ```
+ */
+declare function createHints(config: HintsConfig): AgentHooks;
+
 /**
  * Model shortcuts and aliases for more expressive DX.
  *
@@ -1284,6 +1606,7 @@ declare class GadgetExecutor {
     private readonly defaultGadgetTimeoutMs?;
     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);
     /**
      * Creates a promise that rejects with a TimeoutException after the specified timeout.
@@ -1291,6 +1614,11 @@ declare class GadgetExecutor {
     private createTimeoutPromise;
     execute(call: ParsedGadgetCall): Promise<GadgetExecutionResult>;
     executeAll(calls: ParsedGadgetCall[]): Promise<GadgetExecutionResult[]>;
+    /**
+     * Deep equality check for objects/arrays.
+     * Used to detect if parameters were modified by an interceptor.
+     */
+    private deepEquals;
 }
 
 interface StreamParserOptions {
@@ -1835,4 +2163,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, StreamParser, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, TokenUsage, type ValidationIssue, type ValidationResult, createAnthropicProviderFromEnv, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createLogger, createOpenAIProviderFromEnv, defaultLogger, discoverProviderAdapters, getModelId, getProvider, hasProviderPrefix, resolveModel, validateAndApplyDefaults, validateGadgetParams };
+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 };