llmist 1.2.0 → 1.3.1

package/dist/cli.cjs

@@ -1113,6 +1113,417 @@ var init_output_viewer = __esm({
   }
 });
 
+// src/agent/compaction/config.ts
+function resolveCompactionConfig(config = {}) {
+  const trigger = config.triggerThresholdPercent ?? DEFAULT_COMPACTION_CONFIG.triggerThresholdPercent;
+  const target = config.targetPercent ?? DEFAULT_COMPACTION_CONFIG.targetPercent;
+  if (target >= trigger) {
+    console.warn(
+      `[llmist/compaction] targetPercent (${target}) should be less than triggerThresholdPercent (${trigger}) to be effective.`
+    );
+  }
+  const strategy = config.strategy ?? DEFAULT_COMPACTION_CONFIG.strategy;
+  const strategyName = typeof strategy === "object" && "name" in strategy ? strategy.name : strategy;
+  return {
+    enabled: config.enabled ?? DEFAULT_COMPACTION_CONFIG.enabled,
+    strategy: strategyName,
+    triggerThresholdPercent: trigger,
+    targetPercent: target,
+    preserveRecentTurns: config.preserveRecentTurns ?? DEFAULT_COMPACTION_CONFIG.preserveRecentTurns,
+    summarizationModel: config.summarizationModel,
+    summarizationPrompt: config.summarizationPrompt ?? DEFAULT_SUMMARIZATION_PROMPT,
+    onCompaction: config.onCompaction
+  };
+}
+var DEFAULT_COMPACTION_CONFIG, DEFAULT_SUMMARIZATION_PROMPT;
+var init_config = __esm({
+  "src/agent/compaction/config.ts"() {
+    "use strict";
+    DEFAULT_COMPACTION_CONFIG = {
+      enabled: true,
+      strategy: "hybrid",
+      triggerThresholdPercent: 80,
+      targetPercent: 50,
+      preserveRecentTurns: 5
+    };
+    DEFAULT_SUMMARIZATION_PROMPT = `Summarize this conversation history concisely, preserving:
+1. Key decisions made and their rationale
+2. Important facts and data discovered
+3. Errors encountered and how they were resolved
+4. Current task context and goals
+
+Format as a brief narrative paragraph, not bullet points.
+Previous conversation:`;
+  }
+});
+
+// src/agent/compaction/strategy.ts
+function groupIntoTurns(messages) {
+  const turns = [];
+  let currentTurn = [];
+  for (const msg of messages) {
+    if (msg.role === "user" && currentTurn.length > 0) {
+      turns.push({
+        messages: currentTurn,
+        tokenEstimate: estimateTurnTokens(currentTurn)
+      });
+      currentTurn = [msg];
+    } else {
+      currentTurn.push(msg);
+    }
+  }
+  if (currentTurn.length > 0) {
+    turns.push({
+      messages: currentTurn,
+      tokenEstimate: estimateTurnTokens(currentTurn)
+    });
+  }
+  return turns;
+}
+function estimateTurnTokens(messages) {
+  return Math.ceil(messages.reduce((sum, msg) => sum + (msg.content?.length ?? 0), 0) / 4);
+}
+function flattenTurns(turns) {
+  return turns.flatMap((turn) => turn.messages);
+}
+var init_strategy = __esm({
+  "src/agent/compaction/strategy.ts"() {
+    "use strict";
+  }
+});
+
+// src/agent/compaction/strategies/sliding-window.ts
+var TRUNCATION_MARKER_TEMPLATE, SlidingWindowStrategy;
+var init_sliding_window = __esm({
+  "src/agent/compaction/strategies/sliding-window.ts"() {
+    "use strict";
+    init_strategy();
+    TRUNCATION_MARKER_TEMPLATE = "[Previous conversation truncated. Removed {count} turn(s) to fit context window.]";
+    SlidingWindowStrategy = class {
+      name = "sliding-window";
+      async compact(messages, config, context) {
+        const turns = groupIntoTurns(messages);
+        const preserveCount = Math.min(config.preserveRecentTurns, turns.length);
+        if (turns.length <= preserveCount) {
+          return {
+            messages,
+            strategyName: this.name,
+            metadata: {
+              originalCount: messages.length,
+              compactedCount: messages.length,
+              tokensBefore: context.currentTokens,
+              tokensAfter: context.currentTokens
+            }
+          };
+        }
+        const turnsToKeep = turns.slice(-preserveCount);
+        const turnsRemoved = turns.length - preserveCount;
+        const truncationMarker = {
+          role: "user",
+          content: TRUNCATION_MARKER_TEMPLATE.replace("{count}", turnsRemoved.toString())
+        };
+        const compactedMessages = [truncationMarker, ...flattenTurns(turnsToKeep)];
+        const tokensAfter = Math.ceil(
+          compactedMessages.reduce((sum, msg) => sum + (msg.content?.length ?? 0), 0) / 4
+        );
+        return {
+          messages: compactedMessages,
+          strategyName: this.name,
+          metadata: {
+            originalCount: messages.length,
+            compactedCount: compactedMessages.length,
+            tokensBefore: context.currentTokens,
+            tokensAfter
+          }
+        };
+      }
+    };
+  }
+});
+
+// src/agent/compaction/strategies/summarization.ts
+var SummarizationStrategy;
+var init_summarization = __esm({
+  "src/agent/compaction/strategies/summarization.ts"() {
+    "use strict";
+    init_strategy();
+    SummarizationStrategy = class {
+      name = "summarization";
+      async compact(messages, config, context) {
+        const turns = groupIntoTurns(messages);
+        const preserveCount = Math.min(config.preserveRecentTurns, turns.length);
+        if (turns.length <= preserveCount) {
+          return {
+            messages,
+            strategyName: this.name,
+            metadata: {
+              originalCount: messages.length,
+              compactedCount: messages.length,
+              tokensBefore: context.currentTokens,
+              tokensAfter: context.currentTokens
+            }
+          };
+        }
+        const turnsToSummarize = turns.slice(0, -preserveCount);
+        const turnsToKeep = turns.slice(-preserveCount);
+        const conversationToSummarize = this.formatTurnsForSummary(flattenTurns(turnsToSummarize));
+        const summary = await this.generateSummary(conversationToSummarize, config, context);
+        const summaryMessage = {
+          role: "user",
+          content: `[Previous conversation summary]
+${summary}
+[End of summary - conversation continues below]`
+        };
+        const compactedMessages = [summaryMessage, ...flattenTurns(turnsToKeep)];
+        const tokensAfter = Math.ceil(
+          compactedMessages.reduce((sum, msg) => sum + (msg.content?.length ?? 0), 0) / 4
+        );
+        return {
+          messages: compactedMessages,
+          summary,
+          strategyName: this.name,
+          metadata: {
+            originalCount: messages.length,
+            compactedCount: compactedMessages.length,
+            tokensBefore: context.currentTokens,
+            tokensAfter
+          }
+        };
+      }
+      /**
+       * Formats messages into a readable conversation format for summarization.
+       */
+      formatTurnsForSummary(messages) {
+        return messages.map((msg) => {
+          const role = msg.role.charAt(0).toUpperCase() + msg.role.slice(1);
+          return `${role}: ${msg.content}`;
+        }).join("\n\n");
+      }
+      /**
+       * Generates a summary using the configured LLM.
+       */
+      async generateSummary(conversation, config, context) {
+        const model = config.summarizationModel ?? context.model;
+        const prompt = `${config.summarizationPrompt}
+
+${conversation}`;
+        const response = await context.client.complete(prompt, {
+          model,
+          temperature: 0.3
+          // Low temperature for factual summarization
+        });
+        return response.trim();
+      }
+    };
+  }
+});
+
+// src/agent/compaction/strategies/hybrid.ts
+var MIN_TURNS_FOR_SUMMARIZATION, HybridStrategy;
+var init_hybrid = __esm({
+  "src/agent/compaction/strategies/hybrid.ts"() {
+    "use strict";
+    init_strategy();
+    init_sliding_window();
+    init_summarization();
+    MIN_TURNS_FOR_SUMMARIZATION = 3;
+    HybridStrategy = class {
+      name = "hybrid";
+      slidingWindow = new SlidingWindowStrategy();
+      summarization = new SummarizationStrategy();
+      async compact(messages, config, context) {
+        const turns = groupIntoTurns(messages);
+        const preserveCount = Math.min(config.preserveRecentTurns, turns.length);
+        if (turns.length <= preserveCount) {
+          return {
+            messages,
+            strategyName: this.name,
+            metadata: {
+              originalCount: messages.length,
+              compactedCount: messages.length,
+              tokensBefore: context.currentTokens,
+              tokensAfter: context.currentTokens
+            }
+          };
+        }
+        const turnsToSummarize = turns.length - preserveCount;
+        if (turnsToSummarize < MIN_TURNS_FOR_SUMMARIZATION) {
+          return this.slidingWindow.compact(messages, config, context);
+        }
+        return this.summarization.compact(messages, config, context);
+      }
+    };
+  }
+});
+
+// src/agent/compaction/strategies/index.ts
+var init_strategies = __esm({
+  "src/agent/compaction/strategies/index.ts"() {
+    "use strict";
+    init_sliding_window();
+    init_summarization();
+    init_hybrid();
+  }
+});
+
+// src/agent/compaction/manager.ts
+function createStrategy(name) {
+  switch (name) {
+    case "sliding-window":
+      return new SlidingWindowStrategy();
+    case "summarization":
+      return new SummarizationStrategy();
+    case "hybrid":
+      return new HybridStrategy();
+    default:
+      throw new Error(`Unknown compaction strategy: ${name}`);
+  }
+}
+var CompactionManager;
+var init_manager = __esm({
+  "src/agent/compaction/manager.ts"() {
+    "use strict";
+    init_config();
+    init_strategies();
+    CompactionManager = class {
+      client;
+      model;
+      config;
+      strategy;
+      modelLimits;
+      // Statistics
+      totalCompactions = 0;
+      totalTokensSaved = 0;
+      lastTokenCount = 0;
+      constructor(client, model, config = {}) {
+        this.client = client;
+        this.model = model;
+        this.config = resolveCompactionConfig(config);
+        if (typeof config.strategy === "object" && "compact" in config.strategy) {
+          this.strategy = config.strategy;
+        } else {
+          this.strategy = createStrategy(this.config.strategy);
+        }
+      }
+      /**
+       * 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
+       */
+      async checkAndCompact(conversation, iteration) {
+        if (!this.config.enabled) {
+          return null;
+        }
+        if (!this.modelLimits) {
+          this.modelLimits = this.client.modelRegistry.getModelLimits(this.model);
+          if (!this.modelLimits) {
+            return null;
+          }
+        }
+        if (!this.client.countTokens) {
+          return null;
+        }
+        const messages = conversation.getMessages();
+        const currentTokens = await this.client.countTokens(this.model, messages);
+        this.lastTokenCount = currentTokens;
+        const usagePercent = currentTokens / this.modelLimits.contextWindow * 100;
+        if (usagePercent < this.config.triggerThresholdPercent) {
+          return null;
+        }
+        const historyMessages = conversation.getHistoryMessages();
+        const baseMessages = conversation.getBaseMessages();
+        const historyTokens = await this.client.countTokens(this.model, historyMessages);
+        const baseTokens = await this.client.countTokens(this.model, baseMessages);
+        return this.compact(conversation, iteration, {
+          historyMessages,
+          baseMessages,
+          historyTokens,
+          baseTokens,
+          currentTokens: historyTokens + baseTokens
+        });
+      }
+      /**
+       * 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
+       */
+      async compact(conversation, iteration, precomputed) {
+        if (!this.modelLimits) {
+          this.modelLimits = this.client.modelRegistry.getModelLimits(this.model);
+          if (!this.modelLimits) {
+            return null;
+          }
+        }
+        const historyMessages = precomputed?.historyMessages ?? conversation.getHistoryMessages();
+        const baseMessages = precomputed?.baseMessages ?? conversation.getBaseMessages();
+        const historyTokens = precomputed?.historyTokens ?? await this.client.countTokens(this.model, historyMessages);
+        const baseTokens = precomputed?.baseTokens ?? await this.client.countTokens(this.model, baseMessages);
+        const currentTokens = precomputed?.currentTokens ?? historyTokens + baseTokens;
+        const targetTotalTokens = Math.floor(
+          this.modelLimits.contextWindow * this.config.targetPercent / 100
+        );
+        const targetHistoryTokens = Math.max(0, targetTotalTokens - baseTokens);
+        const result = await this.strategy.compact(historyMessages, this.config, {
+          currentTokens: historyTokens,
+          targetTokens: targetHistoryTokens,
+          modelLimits: this.modelLimits,
+          client: this.client,
+          model: this.config.summarizationModel ?? this.model
+        });
+        conversation.replaceHistory(result.messages);
+        const afterTokens = await this.client.countTokens(this.model, conversation.getMessages());
+        const tokensSaved = currentTokens - afterTokens;
+        this.totalCompactions++;
+        this.totalTokensSaved += tokensSaved;
+        this.lastTokenCount = afterTokens;
+        const event = {
+          strategy: result.strategyName,
+          tokensBefore: currentTokens,
+          tokensAfter: afterTokens,
+          messagesBefore: historyMessages.length + baseMessages.length,
+          messagesAfter: result.messages.length + baseMessages.length,
+          summary: result.summary,
+          iteration
+        };
+        if (this.config.onCompaction) {
+          try {
+            this.config.onCompaction(event);
+          } catch (err) {
+            console.warn("[llmist/compaction] onCompaction callback error:", err);
+          }
+        }
+        return event;
+      }
+      /**
+       * Get compaction statistics.
+       */
+      getStats() {
+        const contextWindow = this.modelLimits?.contextWindow ?? 0;
+        return {
+          totalCompactions: this.totalCompactions,
+          totalTokensSaved: this.totalTokensSaved,
+          currentUsage: {
+            tokens: this.lastTokenCount,
+            percent: contextWindow > 0 ? this.lastTokenCount / contextWindow * 100 : 0
+          },
+          contextWindow
+        };
+      }
+      /**
+       * Check if compaction is enabled.
+       */
+      isEnabled() {
+        return this.config.enabled;
+      }
+    };
+  }
+});
+
 // src/agent/gadget-output-store.ts
 var import_node_crypto, GadgetOutputStore;
 var init_gadget_output_store = __esm({
@@ -1215,10 +1626,16 @@ var init_conversation_manager = __esm({
       baseMessages;
       initialMessages;
       historyBuilder;
+      startPrefix;
+      endPrefix;
+      argPrefix;
       constructor(baseMessages, initialMessages, options = {}) {
         this.baseMessages = baseMessages;
         this.initialMessages = initialMessages;
         this.historyBuilder = new LLMMessageBuilder();
+        this.startPrefix = options.startPrefix;
+        this.endPrefix = options.endPrefix;
+        this.argPrefix = options.argPrefix;
         if (options.startPrefix && options.endPrefix) {
           this.historyBuilder.withPrefixes(options.startPrefix, options.endPrefix, options.argPrefix);
         }
@@ -1235,6 +1652,25 @@ var init_conversation_manager = __esm({
       getMessages() {
         return [...this.baseMessages, ...this.initialMessages, ...this.historyBuilder.build()];
       }
+      getHistoryMessages() {
+        return this.historyBuilder.build();
+      }
+      getBaseMessages() {
+        return [...this.baseMessages, ...this.initialMessages];
+      }
+      replaceHistory(newHistory) {
+        this.historyBuilder = new LLMMessageBuilder();
+        if (this.startPrefix && this.endPrefix) {
+          this.historyBuilder.withPrefixes(this.startPrefix, this.endPrefix, this.argPrefix);
+        }
+        for (const msg of newHistory) {
+          if (msg.role === "user") {
+            this.historyBuilder.addUser(msg.content);
+          } else if (msg.role === "assistant") {
+            this.historyBuilder.addAssistant(msg.content);
+          }
+        }
+      }
     };
   }
 });
@@ -2781,6 +3217,7 @@ var init_agent = __esm({
     init_model_shortcuts();
     init_output_viewer();
     init_logger();
+    init_manager();
     init_gadget_output_store();
     init_agent_internal_key();
     init_conversation_manager();
@@ -2811,6 +3248,8 @@ var init_agent = __esm({
       outputStore;
       outputLimitEnabled;
       outputLimitCharLimit;
+      // Context compaction
+      compactionManager;
       /**
        * Creates a new Agent instance.
        * @internal This constructor is private. Use LLMist.createAgent() or AgentBuilder instead.
@@ -2870,6 +3309,14 @@ var init_agent = __esm({
         if (options.userPrompt) {
           this.conversation.addUserMessage(options.userPrompt);
         }
+        const compactionEnabled = options.compactionConfig?.enabled ?? true;
+        if (compactionEnabled) {
+          this.compactionManager = new CompactionManager(
+            this.client,
+            this.model,
+            options.compactionConfig
+          );
+        }
       }
       /**
        * Get the gadget registry for this agent.
@@ -2892,6 +3339,53 @@ var init_agent = __esm({
       getRegistry() {
         return this.registry;
       }
+      /**
+       * Manually trigger context compaction.
+       *
+       * Forces compaction regardless of threshold. Useful for:
+       * - Pre-emptive context management before expected long operations
+       * - Testing compaction behavior
+       *
+       * @returns CompactionEvent if compaction was performed, null if not configured or no history
+       *
+       * @example
+       * ```typescript
+       * const agent = await LLMist.createAgent()
+       *   .withModel('sonnet')
+       *   .withCompaction()
+       *   .ask('...');
+       *
+       * // Manually compact before a long operation
+       * const event = await agent.compact();
+       * if (event) {
+       *   console.log(`Saved ${event.tokensBefore - event.tokensAfter} tokens`);
+       * }
+       * ```
+       */
+      async compact() {
+        if (!this.compactionManager) {
+          return null;
+        }
+        return this.compactionManager.compact(this.conversation, -1);
+      }
+      /**
+       * Get compaction statistics.
+       *
+       * @returns CompactionStats if compaction is enabled, null otherwise
+       *
+       * @example
+       * ```typescript
+       * const stats = agent.getCompactionStats();
+       * if (stats) {
+       *   console.log(`Total compactions: ${stats.totalCompactions}`);
+       *   console.log(`Tokens saved: ${stats.totalTokensSaved}`);
+       *   console.log(`Current usage: ${stats.currentUsage.percent.toFixed(1)}%`);
+       * }
+       * ```
+       */
+      getCompactionStats() {
+        return this.compactionManager?.getStats() ?? null;
+      }
       /**
        * Run the agent loop.
        * Clean, simple orchestration - all complexity is in StreamProcessor.
@@ -2912,6 +3406,30 @@ var init_agent = __esm({
         while (currentIteration < this.maxIterations) {
           this.logger.debug("Starting iteration", { iteration: currentIteration });
           try {
+            if (this.compactionManager) {
+              const compactionEvent = await this.compactionManager.checkAndCompact(
+                this.conversation,
+                currentIteration
+              );
+              if (compactionEvent) {
+                this.logger.info("Context compacted", {
+                  strategy: compactionEvent.strategy,
+                  tokensBefore: compactionEvent.tokensBefore,
+                  tokensAfter: compactionEvent.tokensAfter
+                });
+                yield { type: "compaction", event: compactionEvent };
+                await this.safeObserve(async () => {
+                  if (this.hooks.observers?.onCompaction) {
+                    await this.hooks.observers.onCompaction({
+                      iteration: currentIteration,
+                      event: compactionEvent,
+                      stats: this.compactionManager.getStats(),
+                      logger: this.logger
+                    });
+                  }
+                });
+              }
+            }
             let llmOptions = {
               model: this.model,
               messages: this.conversation.getMessages(),
@@ -2931,6 +3449,7 @@ var init_agent = __esm({
             if (this.hooks.controllers?.beforeLLMCall) {
               const context = {
                 iteration: currentIteration,
+                maxIterations: this.maxIterations,
                 options: llmOptions,
                 logger: this.logger
               };
@@ -2995,12 +3514,17 @@ var init_agent = __esm({
             });
             let finalMessage = result.finalMessage;
             if (this.hooks.controllers?.afterLLMCall) {
+              const gadgetCallCount = result.outputs.filter(
+                (output) => output.type === "gadget_result"
+              ).length;
               const context = {
                 iteration: currentIteration,
+                maxIterations: this.maxIterations,
                 options: llmOptions,
                 finishReason: result.finishReason,
                 usage: result.usage,
                 finalMessage: result.finalMessage,
+                gadgetCallCount,
                 logger: this.logger
               };
               const action = await this.hooks.controllers.afterLLMCall(context);
@@ -5235,6 +5759,7 @@ var init_builder = __esm({
       defaultGadgetTimeoutMs;
       gadgetOutputLimit;
       gadgetOutputLimitPercent;
+      compactionConfig;
       constructor(client) {
         this.client = client;
       }
@@ -5630,6 +6155,57 @@ var init_builder = __esm({
         this.gadgetOutputLimitPercent = percent;
         return this;
       }
+      /**
+       * Configure context compaction.
+       *
+       * Context compaction automatically manages conversation history to prevent
+       * context window overflow in long-running agent conversations.
+       *
+       * @param config - Compaction configuration options
+       * @returns This builder for chaining
+       *
+       * @example
+       * ```typescript
+       * // Custom thresholds
+       * .withCompaction({
+       *   triggerThresholdPercent: 70,
+       *   targetPercent: 40,
+       *   preserveRecentTurns: 10,
+       * })
+       *
+       * // Different strategy
+       * .withCompaction({
+       *   strategy: 'sliding-window',
+       * })
+       *
+       * // With callback
+       * .withCompaction({
+       *   onCompaction: (event) => {
+       *     console.log(`Saved ${event.tokensBefore - event.tokensAfter} tokens`);
+       *   }
+       * })
+       * ```
+       */
+      withCompaction(config) {
+        this.compactionConfig = { ...config, enabled: config.enabled ?? true };
+        return this;
+      }
+      /**
+       * Disable context compaction.
+       *
+       * By default, compaction is enabled. Use this method to explicitly disable it.
+       *
+       * @returns This builder for chaining
+       *
+       * @example
+       * ```typescript
+       * .withoutCompaction() // Disable automatic compaction
+       * ```
+       */
+      withoutCompaction() {
+        this.compactionConfig = { enabled: false };
+        return this;
+      }
       /**
        * Add a synthetic gadget call to the conversation history.
        *
@@ -5745,7 +6321,8 @@ ${endPrefix}`
           shouldContinueAfterError: this.shouldContinueAfterError,
           defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
           gadgetOutputLimit: this.gadgetOutputLimit,
-          gadgetOutputLimitPercent: this.gadgetOutputLimitPercent
+          gadgetOutputLimitPercent: this.gadgetOutputLimitPercent,
+          compactionConfig: this.compactionConfig
         };
         return new Agent(AGENT_INTERNAL_KEY, options);
       }
@@ -5847,7 +6424,8 @@ ${endPrefix}`
           shouldContinueAfterError: this.shouldContinueAfterError,
           defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
           gadgetOutputLimit: this.gadgetOutputLimit,
-          gadgetOutputLimitPercent: this.gadgetOutputLimitPercent
+          gadgetOutputLimitPercent: this.gadgetOutputLimitPercent,
+          compactionConfig: this.compactionConfig
         };
         return new Agent(AGENT_INTERNAL_KEY, options);
       }
@@ -5906,7 +6484,7 @@ var import_commander2 = require("commander");
 // package.json
 var package_default = {
   name: "llmist",
-  version: "1.1.0",
+  version: "1.3.0",
   description: "Universal TypeScript LLM client with streaming-first agent framework. Works with any model - no structured outputs or native tool calling required. Implements its own flexible grammar for function calling.",
   type: "module",
   main: "dist/index.cjs",
@@ -6053,26 +6631,16 @@ var askUser = createGadget({
 });
 var tellUser = createGadget({
   name: "TellUser",
-  description: "Tell the user something important. Set done=true when your work is complete and you want to end the conversation.",
+  description: "Tell the user something important.",
   schema: import_zod2.z.object({
     message: import_zod2.z.string().optional().describe("The message to display to the user in Markdown"),
-    done: import_zod2.z.boolean().default(false).describe("Set to true to end the conversation, false to continue"),
     type: import_zod2.z.enum(["info", "success", "warning", "error"]).default("info").describe("Message type: info, success, warning, or error")
   }),
   examples: [
     {
-      comment: "Report successful completion and end the conversation",
-      params: {
-        message: "I've completed the refactoring. All tests pass.",
-        done: true,
-        type: "success"
-      }
-    },
-    {
-      comment: "Warn the user about something without ending",
+      comment: "Warn the user about something",
       params: {
         message: "Found 3 files with potential issues. Continuing analysis...",
-        done: false,
         type: "warning"
       }
     },
@@ -6080,12 +6648,11 @@ var tellUser = createGadget({
       comment: "Share detailed analysis with bullet points (use heredoc for multiline)",
       params: {
         message: "Here's what I found in the codebase:\n\n1. **Main entry point**: `src/index.ts` exports all public APIs\n2. **Core logic**: Located in `src/core/` with 5 modules\n3. **Tests**: Good coverage in `src/__tests__/`\n\nI'll continue exploring the core modules.",
-        done: false,
         type: "info"
       }
     }
   ],
-  execute: ({ message, done, type }) => {
+  execute: ({ message, type }) => {
     if (!message || message.trim() === "") {
       return "\u26A0\uFE0F  TellUser was called without a message. Please provide content in the 'message' field.";
     }
@@ -6095,14 +6662,24 @@ var tellUser = createGadget({
       warning: "\u26A0\uFE0F  ",
       error: "\u274C "
     };
-    const plainResult = prefixes[type] + message;
-    if (done) {
-      throw new BreakLoopException(plainResult);
+    return prefixes[type] + message;
+  }
+});
+var finish = createGadget({
+  name: "Finish",
+  description: "Signal that you have completed your task. Call this when your work is done.",
+  schema: import_zod2.z.object({}),
+  examples: [
+    {
+      comment: "Signal task completion",
+      params: {}
     }
-    return plainResult;
+  ],
+  execute: () => {
+    throw new BreakLoopException("Task completed");
   }
 });
-var builtinGadgets = [askUser, tellUser];
+var builtinGadgets = [askUser, tellUser, finish];
 
 // src/cli/gadgets.ts
 var import_node_fs2 = __toESM(require("fs"), 1);
@@ -6658,6 +7235,17 @@ var StreamProgress = class {
     } else {
       parts.push(iterPart);
     }
+    const usagePercent = this.getContextUsagePercent();
+    if (usagePercent !== null) {
+      const formatted = `${Math.round(usagePercent)}%`;
+      if (usagePercent >= 80) {
+        parts.push(import_chalk2.default.red(formatted));
+      } else if (usagePercent >= 50) {
+        parts.push(import_chalk2.default.yellow(formatted));
+      } else {
+        parts.push(import_chalk2.default.green(formatted));
+      }
+    }
     if (this.callInputTokens > 0) {
       const prefix = this.callInputTokensEstimated ? "~" : "";
       parts.push(import_chalk2.default.dim("\u2191") + import_chalk2.default.yellow(` ${prefix}${formatTokens(this.callInputTokens)}`));
@@ -6693,6 +7281,21 @@ var StreamProgress = class {
       return 0;
     }
   }
+  /**
+   * Calculates context window usage percentage.
+   * Returns null if model is unknown or context window unavailable.
+   */
+  getContextUsagePercent() {
+    if (!this.modelRegistry || !this.model || this.callInputTokens === 0) {
+      return null;
+    }
+    const modelName = this.model.includes(":") ? this.model.split(":")[1] : this.model;
+    const limits = this.modelRegistry.getModelLimits(modelName);
+    if (!limits?.contextWindow) {
+      return null;
+    }
+    return this.callInputTokens / limits.contextWindow * 100;
+  }
   renderCumulativeMode(spinner) {
     const elapsed = ((Date.now() - this.totalStartTime) / 1e3).toFixed(1);
     const parts = [];
@@ -7320,7 +7923,9 @@ function resolveTemplate(eta, template, context = {}, configPath) {
   try {
     const fullContext = {
       ...context,
-      env: process.env
+      env: process.env,
+      date: (/* @__PURE__ */ new Date()).toISOString().split("T")[0]
+      // "2025-12-01"
     };
     return eta.renderString(template, fullContext);
   } catch (error) {