llmist 16.2.3 → 16.2.5

package/dist/index.d.cts

@@ -1896,7 +1896,7 @@ interface Observers {
     onRateLimitThrottle?: (context: ObserveRateLimitThrottleContext) => void | Promise<void>;
     /** Called when a retry attempt is made after a failed LLM call */
     onRetryAttempt?: (context: ObserveRetryAttemptContext) => void | Promise<void>;
-    /** Called when a skill is activated (via UseSkill gadget or pre-activation) */
+    /** Called when a skill is activated (via LoadSkill gadget or pre-activation) */
     onSkillActivated?: (context: ObserveSkillActivatedContext) => void | Promise<void>;
 }
 /**
@@ -7328,11 +7328,14 @@ declare class CompactionManager {
     private readonly model;
     private readonly config;
     private readonly strategy;
+    private readonly logger;
     private modelLimits?;
+    private hasWarnedModelNotFound;
+    private hasWarnedNoTokenCounting;
     private totalCompactions;
     private totalTokensSaved;
     private lastTokenCount;
-    constructor(client: LLMist, model: string, config?: CompactionConfig);
+    constructor(client: LLMist, model: string, config?: CompactionConfig, logger?: Logger<ILogObj>);
     /**
      * Check if compaction is needed and perform it if so.
      *
@@ -7350,6 +7353,22 @@ declare class CompactionManager {
      * @returns CompactionEvent with compaction details
      */
     compact(conversation: IConversationManager, iteration: number, precomputed?: PrecomputedTokens): Promise<CompactionEvent | null>;
+    /**
+     * Feed API-reported input token count for reactive threshold checking.
+     * Call this after each LLM response with the actual inputTokens from usage.
+     */
+    updateUsage(inputTokens: number): void;
+    /**
+     * Check if compaction should trigger based on API-reported usage.
+     * Unlike checkAndCompact() which uses estimated token counts,
+     * this uses the ground-truth token count from the last LLM response.
+     */
+    shouldCompactFromUsage(): boolean;
+    /**
+     * Resolve and cache model limits from registry. Warns once if not found.
+     * @returns true if limits are available, false otherwise
+     */
+    private resolveModelLimits;
     /**
      * Get compaction statistics.
      */
@@ -8613,20 +8632,16 @@ declare class GadgetCallParser {
 /**
  * Character-to-token ratio for fallback token estimation.
  *
- * Rationale: When native token counting APIs fail, we estimate tokens using
- * a rough heuristic of 4 characters per token. This is based on empirical
- * observations across multiple LLM providers:
- * - OpenAI's GPT models average ~4 chars/token for English text
- * - Anthropic's Claude models have similar characteristics
- * - Gemini models also approximate this ratio
- *
- * This is intentionally conservative to avoid underestimating token usage.
- * While not perfectly accurate, it provides a reasonable fallback when
- * precise tokenization is unavailable.
+ * Used only when tiktoken (the primary fallback) is unavailable. A value of 2
+ * errs on the side of overestimating token count, which is safer for
+ * compaction triggers and output limiting.
  *
- * Reference: https://help.openai.com/en/articles/4936856-what-are-tokens-and-how-to-count-them
+ * Rationale: The previous value of 4 was based on English prose averages, but
+ * agentic sessions are dominated by JSON, code, and structured data where the
+ * real ratio is ~1.5-2.5 chars/token. A 4-char estimate underestimated tokens
+ * by up to 250%, causing compaction and output limiting to never trigger.
  */
-declare const FALLBACK_CHARS_PER_TOKEN = 4;
+declare const FALLBACK_CHARS_PER_TOKEN = 2;
 
 /**
  * Subagent creation helper for gadget authors.
@@ -9554,8 +9569,14 @@ declare abstract class OpenAICompatibleProvider<TConfig extends OpenAICompatible
     protected executeStreamRequest(payload: Parameters<OpenAI["chat"]["completions"]["create"]>[0], signal?: AbortSignal): Promise<AsyncIterable<ChatCompletionChunk>>;
     protected normalizeProviderStream(iterable: AsyncIterable<unknown>): LLMStream;
     /**
-     * Count tokens using character-based fallback estimation.
-     * Most meta-providers don't have a native token counting API.
+     * Count tokens using tiktoken o200k_base encoding.
+     *
+     * While o200k_base isn't model-exact for non-OpenAI models routed through
+     * meta-providers like OpenRouter, BPE tokenizers with 200K vocab produce
+     * counts within 10-20% of true values — far better than the character-based
+     * fallback which can be off by 250% for JSON/code-heavy content.
+     *
+     * Falls back to character-based estimation if tiktoken fails.
      */
     countTokens(messages: LLMMessage[], descriptor: ModelDescriptor, _spec?: ModelSpec): Promise<number>;
 }
@@ -10047,6 +10068,28 @@ declare function resolveInstructions(instructions: string, options?: {
     enableShellPreprocessing?: boolean;
 }): string;
 
+/**
+ * LoadSkill meta-gadget — bridges the skill system into the gadget execution pipeline.
+ *
+ * When skills are registered with an agent, this gadget is auto-created and added
+ * to the gadget registry. The LLM can invoke it like any other gadget, and the
+ * skill's instructions are returned as the gadget result.
+ *
+ * This approach requires zero changes to the stream processor or agent loop.
+ *
+ * @module skills/load-skill-gadget
+ */
+
+/** Name for the auto-generated LoadSkill gadget. */
+declare const LOAD_SKILL_GADGET_NAME = "LoadSkill";
+/**
+ * Create the LoadSkill meta-gadget from a skill registry.
+ *
+ * The gadget description includes a summary of all available skills,
+ * so the LLM knows what skills exist and when to load them.
+ */
+declare function createLoadSkillGadget(registry: SkillRegistry): AbstractGadget;
+
 /**
  * Filesystem-based skill discovery and loading.
  *
@@ -10133,28 +10176,6 @@ declare function parseSkillContent(content: string, sourcePath: string, source:
  */
 declare function validateMetadata(metadata: SkillMetadata): string[];
 
-/**
- * UseSkill meta-gadget — bridges the skill system into the gadget execution pipeline.
- *
- * When skills are registered with an agent, this gadget is auto-created and added
- * to the gadget registry. The LLM can invoke it like any other gadget, and the
- * skill's instructions are returned as the gadget result.
- *
- * This approach requires zero changes to the stream processor or agent loop.
- *
- * @module skills/use-skill-gadget
- */
-
-/** Name for the auto-generated UseSkill gadget. */
-declare const USE_SKILL_GADGET_NAME = "UseSkill";
-/**
- * Create the UseSkill meta-gadget from a skill registry.
- *
- * The gadget description includes a summary of all available skills,
- * so the LLM knows what skills exist and when to use them.
- */
-declare function createUseSkillGadget(registry: SkillRegistry): AbstractGadget;
-
 /**
  * Config resolution utility for subagent gadgets.
  *
@@ -10584,4 +10605,4 @@ declare const timing: {
  */
 declare function getHostExports(ctx: ExecutionContext): HostExports;
 
-export { AbortException, AbstractGadget, type AddGadgetParams, type AddLLMCallParams, type AfterGadgetExecutionAction, type AfterGadgetExecutionControllerContext, type AfterLLMCallAction, type AfterLLMCallControllerContext, type AfterLLMErrorAction, Agent, AgentBuilder, type AgentHooks, type AgentOptions, AnthropicMessagesProvider, type AudioContentPart, type AudioMimeType, type AudioSource, type BaseExecutionEvent, BaseSessionManager, type BeforeGadgetExecutionAction, type BeforeLLMCallAction, type BeforeSkillActivationAction, BudgetPricingUnavailableError, type CachingConfig, type CachingScope, type ChunkInterceptorContext, type CompactionConfig, type CompactionContext, type CompactionEvent, CompactionManager, type CompactionResult, type CompactionStats, type CompactionStrategy, type CompleteGadgetParams, type CompleteLLMCallParams, type ContentPart, type Controllers, ConversationManager, type CostEstimate, type CostReportingLLMist, type CreateGadgetConfig, DEFAULT_COMPACTION_CONFIG, DEFAULT_HINTS, DEFAULT_PROMPTS, DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_SUMMARIZATION_PROMPT, type EventHandlers, type ExecutionContext, type ExecutionEvent, type ExecutionEventType, type ExecutionNode, type ExecutionNodeType, ExecutionTree, FALLBACK_CHARS_PER_TOKEN, type FileLoggingOptions, type FileLoggingState, type FileWrittenInfo, type FormatLLMErrorContext, GADGET_ARG_PREFIX, GADGET_END_PREFIX, GADGET_START_PREFIX, Gadget, type GadgetCallEvent, GadgetCallParser, type GadgetClass, type GadgetCompleteEvent, type GadgetConfig, type GadgetErrorEvent, type GadgetEvent, type GadgetExample, type GadgetExecuteResult, type GadgetExecuteResultWithMedia, type GadgetExecuteReturn, type GadgetExecutionControllerContext, type GadgetExecutionMode, type GadgetExecutionResult, GadgetExecutor, type GadgetExecutorOptions, type GadgetFactoryExports, type GadgetMediaOutput, type GadgetNode, type GadgetOrClass, GadgetOutputStore, type GadgetParameterInterceptorContext, GadgetRegistry, type GadgetResultInterceptorContext, type GadgetSkippedEvent, type GadgetStartEvent, type GadgetState, GeminiGenerativeProvider, type HintContext, type HintTemplate, type HintsConfig, type HistoryMessage, HookPresets, type HostExports, HuggingFaceProvider, type HumanInputRequiredEvent, HumanInputRequiredException, HybridStrategy, type IConversationManager, type ISessionManager, type ImageBase64Source, type ImageContentPart, type ImageGenerationOptions, type ImageGenerationResult, type ImageMimeType, type ImageModelSpec, type ImageSource, type ImageUrlSource, type Interceptors, type IterationHintOptions, type LLMCallCompleteEvent, type LLMCallControllerContext, type LLMCallErrorEvent, type LLMCallNode, type LLMCallStartEvent, type LLMCallStreamEvent, type LLMErrorControllerContext, type LLMEvent, type LLMGenerationOptions, type LLMMessage, LLMMessageBuilder, type LLMResponseEndEvent, type LLMStream, type LLMStreamChunk, LLMist, type LLMistOptions, type LLMistPackageManifest, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, type MediaKind, type MediaMetadata, MediaStore, type MessageContent, type MessageInterceptorContext, type MessageRole, type MessageTurn, type ModelDescriptor, type ModelFeatures, ModelIdentifierParser, type ModelLimits, type ModelPricing, ModelRegistry, type ModelSpec, type NodeId, type ObserveChunkContext, type ObserveCompactionContext, type ObserveGadgetCompleteContext, type ObserveGadgetStartContext, type ObserveLLMCallContext, type ObserveLLMCompleteContext, type ObserveLLMErrorContext, type ObserveRateLimitThrottleContext, type ObserveRetryAttemptContext, type ObserveSkillActivatedContext, type Observers, OpenAIChatProvider, type OpenAICompatibleConfig, OpenAICompatibleProvider, type OpenRouterConfig, OpenRouterProvider, type OpenRouterRouting, type OutputLimitConfig, type ParallelGadgetHintOptions, type ParsedGadgetCall, type ParsedSkill, type PrefixConfig, type PresetDefinition, type PromptContext, type PromptTemplate, type PromptTemplateConfig, type ProviderAdapter, type ProviderIdentifier, type RateLimitConfig, type RateLimitStats, RateLimitTracker, type ReasoningConfig, type ReasoningEffort, type ResolveValueOptions, type ResolvedCompactionConfig, type ResolvedRateLimitConfig, type ResolvedRetryConfig, type RetryConfig, type RetryOptions, type SessionManifestEntry, SimpleSessionManager, Skill, type SkillActivation, type SkillActivationControllerContext, type SkillActivationOptions, type SkillInstructionInterceptorContext, type SkillMetadata, SkillRegistry, type SkillResource, type SkillSource, SlidingWindowStrategy, type SpeechGenerationOptions, type SpeechGenerationResult, type SpeechModelSpec, type StoredMedia, type StoredOutput, type StreamCompleteEvent, type StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type SubagentConfig, type SubagentConfigMap, type SubagentContext, type SubagentManifestEntry, type SubagentOptions, SummarizationStrategy, TaskCompletionSignal, type TextContentPart, type TextEvent, type TextGenerationOptions, type TextOnlyAction, type TextOnlyContext, type TextOnlyCustomHandler, type TextOnlyGadgetConfig, type TextOnlyHandler, type TextOnlyStrategy, type ThinkingChunk, type ThinkingEvent, TimeoutException, type TokenUsage, type TrailingMessage, type TrailingMessageContext, type CompactionEvent$1 as TreeCompactionEvent, type TreeConfig, type GadgetSkippedEvent$1 as TreeGadgetSkippedEvent, type TriggeredLimitInfo, USE_SKILL_GADGET_NAME, type ValidationIssue, type ValidationResult, type VisionAnalyzeOptions, type VisionAnalyzeResult, audioFromBase64, audioFromBuffer, collectEvents, collectText, complete, createAnthropicProviderFromEnv, createFileLoggingState, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createHuggingFaceProviderFromEnv, createLogger, createMediaOutput, createOpenAIProviderFromEnv, createOpenRouterProviderFromEnv, createSubagent, createUseSkillGadget, defaultLogger, detectAudioMimeType, detectImageMimeType, discoverProviderAdapters, discoverSkills, extractMessageText, extractRetryAfterMs, filterByDepth, filterByParent, filterRootEvents, format, formatBytes, formatCallNumber, formatDate, formatDuration, formatLLMError, formatLlmRequest, gadgetError, gadgetSuccess, getErrorMessage, getHostExports, getModelId, getPresetGadgets, getProvider, getSubagent, groupByParent, hasHostExports, hasPreset, hasProviderPrefix, hasSubagents, humanDelay, imageFromBase64, imageFromBuffer, imageFromUrl, isAbortError, isAudioPart, isDataUrl, isGadgetEvent, isImagePart, isLLMEvent, isLikelyContextOverflow, isRetryableError, isRootEvent, isSubagentEvent, isTextPart, iterationProgressHint, listPresets, listSubagents, loadSkillsFromDirectory, normalizeMessageContent, parallelGadgetHint, parseDataUrl, parseFrontmatter, parseManifest, parseMetadata, parseRetryAfterHeader, parseSkillContent, parseSkillFile, randomDelay, resetFileLoggingState, resolveConfig, resolveHintTemplate, resolveInstructions, resolveModel, resolvePromptTemplate, resolveRateLimitConfig, resolveRetryConfig, resolveRulesTemplate, resolveSubagentModel, resolveSubagentTimeout, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, runWithHandlers, scanResources, schemaToJSONSchema, stream, stripProviderPrefix, substituteArguments, substituteVariables, text, timing, toBase64, truncate, validateAndApplyDefaults, validateGadgetParams, validateGadgetSchema, validateMetadata, withErrorHandling, withRetry, withTimeout };
+export { AbortException, AbstractGadget, type AddGadgetParams, type AddLLMCallParams, type AfterGadgetExecutionAction, type AfterGadgetExecutionControllerContext, type AfterLLMCallAction, type AfterLLMCallControllerContext, type AfterLLMErrorAction, Agent, AgentBuilder, type AgentHooks, type AgentOptions, AnthropicMessagesProvider, type AudioContentPart, type AudioMimeType, type AudioSource, type BaseExecutionEvent, BaseSessionManager, type BeforeGadgetExecutionAction, type BeforeLLMCallAction, type BeforeSkillActivationAction, BudgetPricingUnavailableError, type CachingConfig, type CachingScope, type ChunkInterceptorContext, type CompactionConfig, type CompactionContext, type CompactionEvent, CompactionManager, type CompactionResult, type CompactionStats, type CompactionStrategy, type CompleteGadgetParams, type CompleteLLMCallParams, type ContentPart, type Controllers, ConversationManager, type CostEstimate, type CostReportingLLMist, type CreateGadgetConfig, DEFAULT_COMPACTION_CONFIG, DEFAULT_HINTS, DEFAULT_PROMPTS, DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_SUMMARIZATION_PROMPT, type EventHandlers, type ExecutionContext, type ExecutionEvent, type ExecutionEventType, type ExecutionNode, type ExecutionNodeType, ExecutionTree, FALLBACK_CHARS_PER_TOKEN, type FileLoggingOptions, type FileLoggingState, type FileWrittenInfo, type FormatLLMErrorContext, GADGET_ARG_PREFIX, GADGET_END_PREFIX, GADGET_START_PREFIX, Gadget, type GadgetCallEvent, GadgetCallParser, type GadgetClass, type GadgetCompleteEvent, type GadgetConfig, type GadgetErrorEvent, type GadgetEvent, type GadgetExample, type GadgetExecuteResult, type GadgetExecuteResultWithMedia, type GadgetExecuteReturn, type GadgetExecutionControllerContext, type GadgetExecutionMode, type GadgetExecutionResult, GadgetExecutor, type GadgetExecutorOptions, type GadgetFactoryExports, type GadgetMediaOutput, type GadgetNode, type GadgetOrClass, GadgetOutputStore, type GadgetParameterInterceptorContext, GadgetRegistry, type GadgetResultInterceptorContext, type GadgetSkippedEvent, type GadgetStartEvent, type GadgetState, GeminiGenerativeProvider, type HintContext, type HintTemplate, type HintsConfig, type HistoryMessage, HookPresets, type HostExports, HuggingFaceProvider, type HumanInputRequiredEvent, HumanInputRequiredException, HybridStrategy, type IConversationManager, type ISessionManager, type ImageBase64Source, type ImageContentPart, type ImageGenerationOptions, type ImageGenerationResult, type ImageMimeType, type ImageModelSpec, type ImageSource, type ImageUrlSource, type Interceptors, type IterationHintOptions, type LLMCallCompleteEvent, type LLMCallControllerContext, type LLMCallErrorEvent, type LLMCallNode, type LLMCallStartEvent, type LLMCallStreamEvent, type LLMErrorControllerContext, type LLMEvent, type LLMGenerationOptions, type LLMMessage, LLMMessageBuilder, type LLMResponseEndEvent, type LLMStream, type LLMStreamChunk, LLMist, type LLMistOptions, type LLMistPackageManifest, LOAD_SKILL_GADGET_NAME, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, type MediaKind, type MediaMetadata, MediaStore, type MessageContent, type MessageInterceptorContext, type MessageRole, type MessageTurn, type ModelDescriptor, type ModelFeatures, ModelIdentifierParser, type ModelLimits, type ModelPricing, ModelRegistry, type ModelSpec, type NodeId, type ObserveChunkContext, type ObserveCompactionContext, type ObserveGadgetCompleteContext, type ObserveGadgetStartContext, type ObserveLLMCallContext, type ObserveLLMCompleteContext, type ObserveLLMErrorContext, type ObserveRateLimitThrottleContext, type ObserveRetryAttemptContext, type ObserveSkillActivatedContext, type Observers, OpenAIChatProvider, type OpenAICompatibleConfig, OpenAICompatibleProvider, type OpenRouterConfig, OpenRouterProvider, type OpenRouterRouting, type OutputLimitConfig, type ParallelGadgetHintOptions, type ParsedGadgetCall, type ParsedSkill, type PrefixConfig, type PresetDefinition, type PromptContext, type PromptTemplate, type PromptTemplateConfig, type ProviderAdapter, type ProviderIdentifier, type RateLimitConfig, type RateLimitStats, RateLimitTracker, type ReasoningConfig, type ReasoningEffort, type ResolveValueOptions, type ResolvedCompactionConfig, type ResolvedRateLimitConfig, type ResolvedRetryConfig, type RetryConfig, type RetryOptions, type SessionManifestEntry, SimpleSessionManager, Skill, type SkillActivation, type SkillActivationControllerContext, type SkillActivationOptions, type SkillInstructionInterceptorContext, type SkillMetadata, SkillRegistry, type SkillResource, type SkillSource, SlidingWindowStrategy, type SpeechGenerationOptions, type SpeechGenerationResult, type SpeechModelSpec, type StoredMedia, type StoredOutput, type StreamCompleteEvent, type StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type SubagentConfig, type SubagentConfigMap, type SubagentContext, type SubagentManifestEntry, type SubagentOptions, SummarizationStrategy, TaskCompletionSignal, type TextContentPart, type TextEvent, type TextGenerationOptions, type TextOnlyAction, type TextOnlyContext, type TextOnlyCustomHandler, type TextOnlyGadgetConfig, type TextOnlyHandler, type TextOnlyStrategy, type ThinkingChunk, type ThinkingEvent, TimeoutException, type TokenUsage, type TrailingMessage, type TrailingMessageContext, type CompactionEvent$1 as TreeCompactionEvent, type TreeConfig, type GadgetSkippedEvent$1 as TreeGadgetSkippedEvent, type TriggeredLimitInfo, type ValidationIssue, type ValidationResult, type VisionAnalyzeOptions, type VisionAnalyzeResult, audioFromBase64, audioFromBuffer, collectEvents, collectText, complete, createAnthropicProviderFromEnv, createFileLoggingState, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createHuggingFaceProviderFromEnv, createLoadSkillGadget, createLogger, createMediaOutput, createOpenAIProviderFromEnv, createOpenRouterProviderFromEnv, createSubagent, defaultLogger, detectAudioMimeType, detectImageMimeType, discoverProviderAdapters, discoverSkills, extractMessageText, extractRetryAfterMs, filterByDepth, filterByParent, filterRootEvents, format, formatBytes, formatCallNumber, formatDate, formatDuration, formatLLMError, formatLlmRequest, gadgetError, gadgetSuccess, getErrorMessage, getHostExports, getModelId, getPresetGadgets, getProvider, getSubagent, groupByParent, hasHostExports, hasPreset, hasProviderPrefix, hasSubagents, humanDelay, imageFromBase64, imageFromBuffer, imageFromUrl, isAbortError, isAudioPart, isDataUrl, isGadgetEvent, isImagePart, isLLMEvent, isLikelyContextOverflow, isRetryableError, isRootEvent, isSubagentEvent, isTextPart, iterationProgressHint, listPresets, listSubagents, loadSkillsFromDirectory, normalizeMessageContent, parallelGadgetHint, parseDataUrl, parseFrontmatter, parseManifest, parseMetadata, parseRetryAfterHeader, parseSkillContent, parseSkillFile, randomDelay, resetFileLoggingState, resolveConfig, resolveHintTemplate, resolveInstructions, resolveModel, resolvePromptTemplate, resolveRateLimitConfig, resolveRetryConfig, resolveRulesTemplate, resolveSubagentModel, resolveSubagentTimeout, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, runWithHandlers, scanResources, schemaToJSONSchema, stream, stripProviderPrefix, substituteArguments, substituteVariables, text, timing, toBase64, truncate, validateAndApplyDefaults, validateGadgetParams, validateGadgetSchema, validateMetadata, withErrorHandling, withRetry, withTimeout };

package/dist/index.d.ts

@@ -1896,7 +1896,7 @@ interface Observers {
     onRateLimitThrottle?: (context: ObserveRateLimitThrottleContext) => void | Promise<void>;
     /** Called when a retry attempt is made after a failed LLM call */
     onRetryAttempt?: (context: ObserveRetryAttemptContext) => void | Promise<void>;
-    /** Called when a skill is activated (via UseSkill gadget or pre-activation) */
+    /** Called when a skill is activated (via LoadSkill gadget or pre-activation) */
     onSkillActivated?: (context: ObserveSkillActivatedContext) => void | Promise<void>;
 }
 /**
@@ -7328,11 +7328,14 @@ declare class CompactionManager {
     private readonly model;
     private readonly config;
     private readonly strategy;
+    private readonly logger;
     private modelLimits?;
+    private hasWarnedModelNotFound;
+    private hasWarnedNoTokenCounting;
     private totalCompactions;
     private totalTokensSaved;
     private lastTokenCount;
-    constructor(client: LLMist, model: string, config?: CompactionConfig);
+    constructor(client: LLMist, model: string, config?: CompactionConfig, logger?: Logger<ILogObj>);
     /**
      * Check if compaction is needed and perform it if so.
      *
@@ -7350,6 +7353,22 @@ declare class CompactionManager {
      * @returns CompactionEvent with compaction details
      */
     compact(conversation: IConversationManager, iteration: number, precomputed?: PrecomputedTokens): Promise<CompactionEvent | null>;
+    /**
+     * Feed API-reported input token count for reactive threshold checking.
+     * Call this after each LLM response with the actual inputTokens from usage.
+     */
+    updateUsage(inputTokens: number): void;
+    /**
+     * Check if compaction should trigger based on API-reported usage.
+     * Unlike checkAndCompact() which uses estimated token counts,
+     * this uses the ground-truth token count from the last LLM response.
+     */
+    shouldCompactFromUsage(): boolean;
+    /**
+     * Resolve and cache model limits from registry. Warns once if not found.
+     * @returns true if limits are available, false otherwise
+     */
+    private resolveModelLimits;
     /**
      * Get compaction statistics.
      */
@@ -8613,20 +8632,16 @@ declare class GadgetCallParser {
 /**
  * Character-to-token ratio for fallback token estimation.
  *
- * Rationale: When native token counting APIs fail, we estimate tokens using
- * a rough heuristic of 4 characters per token. This is based on empirical
- * observations across multiple LLM providers:
- * - OpenAI's GPT models average ~4 chars/token for English text
- * - Anthropic's Claude models have similar characteristics
- * - Gemini models also approximate this ratio
- *
- * This is intentionally conservative to avoid underestimating token usage.
- * While not perfectly accurate, it provides a reasonable fallback when
- * precise tokenization is unavailable.
+ * Used only when tiktoken (the primary fallback) is unavailable. A value of 2
+ * errs on the side of overestimating token count, which is safer for
+ * compaction triggers and output limiting.
  *
- * Reference: https://help.openai.com/en/articles/4936856-what-are-tokens-and-how-to-count-them
+ * Rationale: The previous value of 4 was based on English prose averages, but
+ * agentic sessions are dominated by JSON, code, and structured data where the
+ * real ratio is ~1.5-2.5 chars/token. A 4-char estimate underestimated tokens
+ * by up to 250%, causing compaction and output limiting to never trigger.
  */
-declare const FALLBACK_CHARS_PER_TOKEN = 4;
+declare const FALLBACK_CHARS_PER_TOKEN = 2;
 
 /**
  * Subagent creation helper for gadget authors.
@@ -9554,8 +9569,14 @@ declare abstract class OpenAICompatibleProvider<TConfig extends OpenAICompatible
     protected executeStreamRequest(payload: Parameters<OpenAI["chat"]["completions"]["create"]>[0], signal?: AbortSignal): Promise<AsyncIterable<ChatCompletionChunk>>;
     protected normalizeProviderStream(iterable: AsyncIterable<unknown>): LLMStream;
     /**
-     * Count tokens using character-based fallback estimation.
-     * Most meta-providers don't have a native token counting API.
+     * Count tokens using tiktoken o200k_base encoding.
+     *
+     * While o200k_base isn't model-exact for non-OpenAI models routed through
+     * meta-providers like OpenRouter, BPE tokenizers with 200K vocab produce
+     * counts within 10-20% of true values — far better than the character-based
+     * fallback which can be off by 250% for JSON/code-heavy content.
+     *
+     * Falls back to character-based estimation if tiktoken fails.
      */
     countTokens(messages: LLMMessage[], descriptor: ModelDescriptor, _spec?: ModelSpec): Promise<number>;
 }
@@ -10047,6 +10068,28 @@ declare function resolveInstructions(instructions: string, options?: {
     enableShellPreprocessing?: boolean;
 }): string;
 
+/**
+ * LoadSkill meta-gadget — bridges the skill system into the gadget execution pipeline.
+ *
+ * When skills are registered with an agent, this gadget is auto-created and added
+ * to the gadget registry. The LLM can invoke it like any other gadget, and the
+ * skill's instructions are returned as the gadget result.
+ *
+ * This approach requires zero changes to the stream processor or agent loop.
+ *
+ * @module skills/load-skill-gadget
+ */
+
+/** Name for the auto-generated LoadSkill gadget. */
+declare const LOAD_SKILL_GADGET_NAME = "LoadSkill";
+/**
+ * Create the LoadSkill meta-gadget from a skill registry.
+ *
+ * The gadget description includes a summary of all available skills,
+ * so the LLM knows what skills exist and when to load them.
+ */
+declare function createLoadSkillGadget(registry: SkillRegistry): AbstractGadget;
+
 /**
  * Filesystem-based skill discovery and loading.
  *
@@ -10133,28 +10176,6 @@ declare function parseSkillContent(content: string, sourcePath: string, source:
  */
 declare function validateMetadata(metadata: SkillMetadata): string[];
 
-/**
- * UseSkill meta-gadget — bridges the skill system into the gadget execution pipeline.
- *
- * When skills are registered with an agent, this gadget is auto-created and added
- * to the gadget registry. The LLM can invoke it like any other gadget, and the
- * skill's instructions are returned as the gadget result.
- *
- * This approach requires zero changes to the stream processor or agent loop.
- *
- * @module skills/use-skill-gadget
- */
-
-/** Name for the auto-generated UseSkill gadget. */
-declare const USE_SKILL_GADGET_NAME = "UseSkill";
-/**
- * Create the UseSkill meta-gadget from a skill registry.
- *
- * The gadget description includes a summary of all available skills,
- * so the LLM knows what skills exist and when to use them.
- */
-declare function createUseSkillGadget(registry: SkillRegistry): AbstractGadget;
-
 /**
  * Config resolution utility for subagent gadgets.
  *
@@ -10584,4 +10605,4 @@ declare const timing: {
  */
 declare function getHostExports(ctx: ExecutionContext): HostExports;
 
-export { AbortException, AbstractGadget, type AddGadgetParams, type AddLLMCallParams, type AfterGadgetExecutionAction, type AfterGadgetExecutionControllerContext, type AfterLLMCallAction, type AfterLLMCallControllerContext, type AfterLLMErrorAction, Agent, AgentBuilder, type AgentHooks, type AgentOptions, AnthropicMessagesProvider, type AudioContentPart, type AudioMimeType, type AudioSource, type BaseExecutionEvent, BaseSessionManager, type BeforeGadgetExecutionAction, type BeforeLLMCallAction, type BeforeSkillActivationAction, BudgetPricingUnavailableError, type CachingConfig, type CachingScope, type ChunkInterceptorContext, type CompactionConfig, type CompactionContext, type CompactionEvent, CompactionManager, type CompactionResult, type CompactionStats, type CompactionStrategy, type CompleteGadgetParams, type CompleteLLMCallParams, type ContentPart, type Controllers, ConversationManager, type CostEstimate, type CostReportingLLMist, type CreateGadgetConfig, DEFAULT_COMPACTION_CONFIG, DEFAULT_HINTS, DEFAULT_PROMPTS, DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_SUMMARIZATION_PROMPT, type EventHandlers, type ExecutionContext, type ExecutionEvent, type ExecutionEventType, type ExecutionNode, type ExecutionNodeType, ExecutionTree, FALLBACK_CHARS_PER_TOKEN, type FileLoggingOptions, type FileLoggingState, type FileWrittenInfo, type FormatLLMErrorContext, GADGET_ARG_PREFIX, GADGET_END_PREFIX, GADGET_START_PREFIX, Gadget, type GadgetCallEvent, GadgetCallParser, type GadgetClass, type GadgetCompleteEvent, type GadgetConfig, type GadgetErrorEvent, type GadgetEvent, type GadgetExample, type GadgetExecuteResult, type GadgetExecuteResultWithMedia, type GadgetExecuteReturn, type GadgetExecutionControllerContext, type GadgetExecutionMode, type GadgetExecutionResult, GadgetExecutor, type GadgetExecutorOptions, type GadgetFactoryExports, type GadgetMediaOutput, type GadgetNode, type GadgetOrClass, GadgetOutputStore, type GadgetParameterInterceptorContext, GadgetRegistry, type GadgetResultInterceptorContext, type GadgetSkippedEvent, type GadgetStartEvent, type GadgetState, GeminiGenerativeProvider, type HintContext, type HintTemplate, type HintsConfig, type HistoryMessage, HookPresets, type HostExports, HuggingFaceProvider, type HumanInputRequiredEvent, HumanInputRequiredException, HybridStrategy, type IConversationManager, type ISessionManager, type ImageBase64Source, type ImageContentPart, type ImageGenerationOptions, type ImageGenerationResult, type ImageMimeType, type ImageModelSpec, type ImageSource, type ImageUrlSource, type Interceptors, type IterationHintOptions, type LLMCallCompleteEvent, type LLMCallControllerContext, type LLMCallErrorEvent, type LLMCallNode, type LLMCallStartEvent, type LLMCallStreamEvent, type LLMErrorControllerContext, type LLMEvent, type LLMGenerationOptions, type LLMMessage, LLMMessageBuilder, type LLMResponseEndEvent, type LLMStream, type LLMStreamChunk, LLMist, type LLMistOptions, type LLMistPackageManifest, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, type MediaKind, type MediaMetadata, MediaStore, type MessageContent, type MessageInterceptorContext, type MessageRole, type MessageTurn, type ModelDescriptor, type ModelFeatures, ModelIdentifierParser, type ModelLimits, type ModelPricing, ModelRegistry, type ModelSpec, type NodeId, type ObserveChunkContext, type ObserveCompactionContext, type ObserveGadgetCompleteContext, type ObserveGadgetStartContext, type ObserveLLMCallContext, type ObserveLLMCompleteContext, type ObserveLLMErrorContext, type ObserveRateLimitThrottleContext, type ObserveRetryAttemptContext, type ObserveSkillActivatedContext, type Observers, OpenAIChatProvider, type OpenAICompatibleConfig, OpenAICompatibleProvider, type OpenRouterConfig, OpenRouterProvider, type OpenRouterRouting, type OutputLimitConfig, type ParallelGadgetHintOptions, type ParsedGadgetCall, type ParsedSkill, type PrefixConfig, type PresetDefinition, type PromptContext, type PromptTemplate, type PromptTemplateConfig, type ProviderAdapter, type ProviderIdentifier, type RateLimitConfig, type RateLimitStats, RateLimitTracker, type ReasoningConfig, type ReasoningEffort, type ResolveValueOptions, type ResolvedCompactionConfig, type ResolvedRateLimitConfig, type ResolvedRetryConfig, type RetryConfig, type RetryOptions, type SessionManifestEntry, SimpleSessionManager, Skill, type SkillActivation, type SkillActivationControllerContext, type SkillActivationOptions, type SkillInstructionInterceptorContext, type SkillMetadata, SkillRegistry, type SkillResource, type SkillSource, SlidingWindowStrategy, type SpeechGenerationOptions, type SpeechGenerationResult, type SpeechModelSpec, type StoredMedia, type StoredOutput, type StreamCompleteEvent, type StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type SubagentConfig, type SubagentConfigMap, type SubagentContext, type SubagentManifestEntry, type SubagentOptions, SummarizationStrategy, TaskCompletionSignal, type TextContentPart, type TextEvent, type TextGenerationOptions, type TextOnlyAction, type TextOnlyContext, type TextOnlyCustomHandler, type TextOnlyGadgetConfig, type TextOnlyHandler, type TextOnlyStrategy, type ThinkingChunk, type ThinkingEvent, TimeoutException, type TokenUsage, type TrailingMessage, type TrailingMessageContext, type CompactionEvent$1 as TreeCompactionEvent, type TreeConfig, type GadgetSkippedEvent$1 as TreeGadgetSkippedEvent, type TriggeredLimitInfo, USE_SKILL_GADGET_NAME, type ValidationIssue, type ValidationResult, type VisionAnalyzeOptions, type VisionAnalyzeResult, audioFromBase64, audioFromBuffer, collectEvents, collectText, complete, createAnthropicProviderFromEnv, createFileLoggingState, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createHuggingFaceProviderFromEnv, createLogger, createMediaOutput, createOpenAIProviderFromEnv, createOpenRouterProviderFromEnv, createSubagent, createUseSkillGadget, defaultLogger, detectAudioMimeType, detectImageMimeType, discoverProviderAdapters, discoverSkills, extractMessageText, extractRetryAfterMs, filterByDepth, filterByParent, filterRootEvents, format, formatBytes, formatCallNumber, formatDate, formatDuration, formatLLMError, formatLlmRequest, gadgetError, gadgetSuccess, getErrorMessage, getHostExports, getModelId, getPresetGadgets, getProvider, getSubagent, groupByParent, hasHostExports, hasPreset, hasProviderPrefix, hasSubagents, humanDelay, imageFromBase64, imageFromBuffer, imageFromUrl, isAbortError, isAudioPart, isDataUrl, isGadgetEvent, isImagePart, isLLMEvent, isLikelyContextOverflow, isRetryableError, isRootEvent, isSubagentEvent, isTextPart, iterationProgressHint, listPresets, listSubagents, loadSkillsFromDirectory, normalizeMessageContent, parallelGadgetHint, parseDataUrl, parseFrontmatter, parseManifest, parseMetadata, parseRetryAfterHeader, parseSkillContent, parseSkillFile, randomDelay, resetFileLoggingState, resolveConfig, resolveHintTemplate, resolveInstructions, resolveModel, resolvePromptTemplate, resolveRateLimitConfig, resolveRetryConfig, resolveRulesTemplate, resolveSubagentModel, resolveSubagentTimeout, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, runWithHandlers, scanResources, schemaToJSONSchema, stream, stripProviderPrefix, substituteArguments, substituteVariables, text, timing, toBase64, truncate, validateAndApplyDefaults, validateGadgetParams, validateGadgetSchema, validateMetadata, withErrorHandling, withRetry, withTimeout };
+export { AbortException, AbstractGadget, type AddGadgetParams, type AddLLMCallParams, type AfterGadgetExecutionAction, type AfterGadgetExecutionControllerContext, type AfterLLMCallAction, type AfterLLMCallControllerContext, type AfterLLMErrorAction, Agent, AgentBuilder, type AgentHooks, type AgentOptions, AnthropicMessagesProvider, type AudioContentPart, type AudioMimeType, type AudioSource, type BaseExecutionEvent, BaseSessionManager, type BeforeGadgetExecutionAction, type BeforeLLMCallAction, type BeforeSkillActivationAction, BudgetPricingUnavailableError, type CachingConfig, type CachingScope, type ChunkInterceptorContext, type CompactionConfig, type CompactionContext, type CompactionEvent, CompactionManager, type CompactionResult, type CompactionStats, type CompactionStrategy, type CompleteGadgetParams, type CompleteLLMCallParams, type ContentPart, type Controllers, ConversationManager, type CostEstimate, type CostReportingLLMist, type CreateGadgetConfig, DEFAULT_COMPACTION_CONFIG, DEFAULT_HINTS, DEFAULT_PROMPTS, DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_SUMMARIZATION_PROMPT, type EventHandlers, type ExecutionContext, type ExecutionEvent, type ExecutionEventType, type ExecutionNode, type ExecutionNodeType, ExecutionTree, FALLBACK_CHARS_PER_TOKEN, type FileLoggingOptions, type FileLoggingState, type FileWrittenInfo, type FormatLLMErrorContext, GADGET_ARG_PREFIX, GADGET_END_PREFIX, GADGET_START_PREFIX, Gadget, type GadgetCallEvent, GadgetCallParser, type GadgetClass, type GadgetCompleteEvent, type GadgetConfig, type GadgetErrorEvent, type GadgetEvent, type GadgetExample, type GadgetExecuteResult, type GadgetExecuteResultWithMedia, type GadgetExecuteReturn, type GadgetExecutionControllerContext, type GadgetExecutionMode, type GadgetExecutionResult, GadgetExecutor, type GadgetExecutorOptions, type GadgetFactoryExports, type GadgetMediaOutput, type GadgetNode, type GadgetOrClass, GadgetOutputStore, type GadgetParameterInterceptorContext, GadgetRegistry, type GadgetResultInterceptorContext, type GadgetSkippedEvent, type GadgetStartEvent, type GadgetState, GeminiGenerativeProvider, type HintContext, type HintTemplate, type HintsConfig, type HistoryMessage, HookPresets, type HostExports, HuggingFaceProvider, type HumanInputRequiredEvent, HumanInputRequiredException, HybridStrategy, type IConversationManager, type ISessionManager, type ImageBase64Source, type ImageContentPart, type ImageGenerationOptions, type ImageGenerationResult, type ImageMimeType, type ImageModelSpec, type ImageSource, type ImageUrlSource, type Interceptors, type IterationHintOptions, type LLMCallCompleteEvent, type LLMCallControllerContext, type LLMCallErrorEvent, type LLMCallNode, type LLMCallStartEvent, type LLMCallStreamEvent, type LLMErrorControllerContext, type LLMEvent, type LLMGenerationOptions, type LLMMessage, LLMMessageBuilder, type LLMResponseEndEvent, type LLMStream, type LLMStreamChunk, LLMist, type LLMistOptions, type LLMistPackageManifest, LOAD_SKILL_GADGET_NAME, type LoggerOptions, type LoggingOptions, MODEL_ALIASES, type MediaKind, type MediaMetadata, MediaStore, type MessageContent, type MessageInterceptorContext, type MessageRole, type MessageTurn, type ModelDescriptor, type ModelFeatures, ModelIdentifierParser, type ModelLimits, type ModelPricing, ModelRegistry, type ModelSpec, type NodeId, type ObserveChunkContext, type ObserveCompactionContext, type ObserveGadgetCompleteContext, type ObserveGadgetStartContext, type ObserveLLMCallContext, type ObserveLLMCompleteContext, type ObserveLLMErrorContext, type ObserveRateLimitThrottleContext, type ObserveRetryAttemptContext, type ObserveSkillActivatedContext, type Observers, OpenAIChatProvider, type OpenAICompatibleConfig, OpenAICompatibleProvider, type OpenRouterConfig, OpenRouterProvider, type OpenRouterRouting, type OutputLimitConfig, type ParallelGadgetHintOptions, type ParsedGadgetCall, type ParsedSkill, type PrefixConfig, type PresetDefinition, type PromptContext, type PromptTemplate, type PromptTemplateConfig, type ProviderAdapter, type ProviderIdentifier, type RateLimitConfig, type RateLimitStats, RateLimitTracker, type ReasoningConfig, type ReasoningEffort, type ResolveValueOptions, type ResolvedCompactionConfig, type ResolvedRateLimitConfig, type ResolvedRetryConfig, type RetryConfig, type RetryOptions, type SessionManifestEntry, SimpleSessionManager, Skill, type SkillActivation, type SkillActivationControllerContext, type SkillActivationOptions, type SkillInstructionInterceptorContext, type SkillMetadata, SkillRegistry, type SkillResource, type SkillSource, SlidingWindowStrategy, type SpeechGenerationOptions, type SpeechGenerationResult, type SpeechModelSpec, type StoredMedia, type StoredOutput, type StreamCompleteEvent, type StreamEvent, type StreamProcessingResult, StreamProcessor, type StreamProcessorOptions, type SubagentConfig, type SubagentConfigMap, type SubagentContext, type SubagentManifestEntry, type SubagentOptions, SummarizationStrategy, TaskCompletionSignal, type TextContentPart, type TextEvent, type TextGenerationOptions, type TextOnlyAction, type TextOnlyContext, type TextOnlyCustomHandler, type TextOnlyGadgetConfig, type TextOnlyHandler, type TextOnlyStrategy, type ThinkingChunk, type ThinkingEvent, TimeoutException, type TokenUsage, type TrailingMessage, type TrailingMessageContext, type CompactionEvent$1 as TreeCompactionEvent, type TreeConfig, type GadgetSkippedEvent$1 as TreeGadgetSkippedEvent, type TriggeredLimitInfo, type ValidationIssue, type ValidationResult, type VisionAnalyzeOptions, type VisionAnalyzeResult, audioFromBase64, audioFromBuffer, collectEvents, collectText, complete, createAnthropicProviderFromEnv, createFileLoggingState, createGadget, createGadgetOutputViewer, createGeminiProviderFromEnv, createHints, createHuggingFaceProviderFromEnv, createLoadSkillGadget, createLogger, createMediaOutput, createOpenAIProviderFromEnv, createOpenRouterProviderFromEnv, createSubagent, defaultLogger, detectAudioMimeType, detectImageMimeType, discoverProviderAdapters, discoverSkills, extractMessageText, extractRetryAfterMs, filterByDepth, filterByParent, filterRootEvents, format, formatBytes, formatCallNumber, formatDate, formatDuration, formatLLMError, formatLlmRequest, gadgetError, gadgetSuccess, getErrorMessage, getHostExports, getModelId, getPresetGadgets, getProvider, getSubagent, groupByParent, hasHostExports, hasPreset, hasProviderPrefix, hasSubagents, humanDelay, imageFromBase64, imageFromBuffer, imageFromUrl, isAbortError, isAudioPart, isDataUrl, isGadgetEvent, isImagePart, isLLMEvent, isLikelyContextOverflow, isRetryableError, isRootEvent, isSubagentEvent, isTextPart, iterationProgressHint, listPresets, listSubagents, loadSkillsFromDirectory, normalizeMessageContent, parallelGadgetHint, parseDataUrl, parseFrontmatter, parseManifest, parseMetadata, parseRetryAfterHeader, parseSkillContent, parseSkillFile, randomDelay, resetFileLoggingState, resolveConfig, resolveHintTemplate, resolveInstructions, resolveModel, resolvePromptTemplate, resolveRateLimitConfig, resolveRetryConfig, resolveRulesTemplate, resolveSubagentModel, resolveSubagentTimeout, resolveValue, resultWithAudio, resultWithFile, resultWithImage, resultWithImages, resultWithMedia, runWithHandlers, scanResources, schemaToJSONSchema, stream, stripProviderPrefix, substituteArguments, substituteVariables, text, timing, toBase64, truncate, validateAndApplyDefaults, validateGadgetParams, validateGadgetSchema, validateMetadata, withErrorHandling, withRetry, withTimeout };