llmist 0.6.2 → 0.7.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { ZodType, ZodTypeAny } from 'zod';
 export { z } from 'zod';
-import { A as AgentHooks, o as ModelRegistry, L as LLMMessage, P as ParameterFormat, S as StreamEvent, G as GadgetRegistry, p as LLMStreamChunk, q as GadgetExample, B as BaseGadget, r as ParsedGadgetCall, s as GadgetExecutionResult, t as ProviderAdapter, u as ModelDescriptor, v as ModelSpec, w as LLMGenerationOptions, x as LLMStream } from './mock-stream-B5R6XPif.cjs';
-export { F as AfterGadgetExecutionAction, I as AfterGadgetExecutionControllerContext, J as AfterLLMCallAction, K as AfterLLMCallControllerContext, N as AfterLLMErrorAction, y as AgentBuilder, O as AgentOptions, Q as BeforeGadgetExecutionAction, R as BeforeLLMCallAction, T as ChunkInterceptorContext, U as Controllers, ab as CostEstimate, al as DEFAULT_PROMPTS, E as EventHandlers, as as GadgetClass, V as GadgetExecutionControllerContext, at as GadgetOrClass, W as GadgetParameterInterceptorContext, X as GadgetResultInterceptorContext, H as HistoryMessage, Y as Interceptors, Z as LLMCallControllerContext, _ as LLMErrorControllerContext, aa as LLMMessageBuilder, a9 as LLMRole, a8 as LLMist, a7 as LLMistOptions, $ as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, ac as ModelFeatures, ah as ModelIdentifierParser, ad as ModelLimits, ae as ModelPricing, a0 as ObserveChunkContext, a1 as ObserveGadgetCompleteContext, a2 as ObserveGadgetStartContext, a3 as ObserveLLMCallContext, a4 as ObserveLLMCompleteContext, a5 as ObserveLLMErrorContext, a6 as Observers, ai as PromptConfig, aj as PromptContext, ak as PromptTemplate, af as ProviderIdentifier, ao as QuickOptions, ar as StreamParser, au as TextOnlyAction, av as TextOnlyContext, aw as TextOnlyCustomHandler, ax as TextOnlyGadgetConfig, ay as TextOnlyHandler, az as TextOnlyStrategy, ag as TokenUsage, z as collectEvents, C as collectText, ap as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, am as resolvePromptTemplate, an as resolveRulesTemplate, D as runWithHandlers, aq as stream } from './mock-stream-B5R6XPif.cjs';
+import { A as AgentHooks, o as ModelRegistry, L as LLMMessage, P as ParameterFormat, S as StreamEvent, G as GadgetRegistry, p as LLMStreamChunk, q as GadgetExample, B as BaseGadget, r as ParsedGadgetCall, s as GadgetExecutionResult, t as ProviderAdapter, u as ModelDescriptor, v as ModelSpec, w as LLMGenerationOptions, x as LLMStream } from './mock-stream-B2qwECvd.cjs';
+export { F as AfterGadgetExecutionAction, I as AfterGadgetExecutionControllerContext, J as AfterLLMCallAction, K as AfterLLMCallControllerContext, N as AfterLLMErrorAction, y as AgentBuilder, O as AgentOptions, Q as BeforeGadgetExecutionAction, R as BeforeLLMCallAction, T as ChunkInterceptorContext, U as Controllers, ab as CostEstimate, al as DEFAULT_PROMPTS, E as EventHandlers, as as GadgetClass, V as GadgetExecutionControllerContext, at as GadgetOrClass, W as GadgetParameterInterceptorContext, X as GadgetResultInterceptorContext, H as HistoryMessage, Y as Interceptors, Z as LLMCallControllerContext, _ as LLMErrorControllerContext, aa as LLMMessageBuilder, a9 as LLMRole, a8 as LLMist, a7 as LLMistOptions, $ as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, ac as ModelFeatures, ah as ModelIdentifierParser, ad as ModelLimits, ae as ModelPricing, a0 as ObserveChunkContext, a1 as ObserveGadgetCompleteContext, a2 as ObserveGadgetStartContext, a3 as ObserveLLMCallContext, a4 as ObserveLLMCompleteContext, a5 as ObserveLLMErrorContext, a6 as Observers, ai as PromptConfig, aj as PromptContext, ak as PromptTemplate, af as ProviderIdentifier, ao as QuickOptions, ar as StreamParser, au as TextOnlyAction, av as TextOnlyContext, aw as TextOnlyCustomHandler, ax as TextOnlyGadgetConfig, ay as TextOnlyHandler, az as TextOnlyStrategy, ag as TokenUsage, z as collectEvents, C as collectText, ap as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, am as resolvePromptTemplate, an as resolveRulesTemplate, D as runWithHandlers, aq as stream } from './mock-stream-B2qwECvd.cjs';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ZodType, ZodTypeAny } from 'zod';
 export { z } from 'zod';
-import { A as AgentHooks, o as ModelRegistry, L as LLMMessage, P as ParameterFormat, S as StreamEvent, G as GadgetRegistry, p as LLMStreamChunk, q as GadgetExample, B as BaseGadget, r as ParsedGadgetCall, s as GadgetExecutionResult, t as ProviderAdapter, u as ModelDescriptor, v as ModelSpec, w as LLMGenerationOptions, x as LLMStream } from './mock-stream-B5R6XPif.js';
-export { F as AfterGadgetExecutionAction, I as AfterGadgetExecutionControllerContext, J as AfterLLMCallAction, K as AfterLLMCallControllerContext, N as AfterLLMErrorAction, y as AgentBuilder, O as AgentOptions, Q as BeforeGadgetExecutionAction, R as BeforeLLMCallAction, T as ChunkInterceptorContext, U as Controllers, ab as CostEstimate, al as DEFAULT_PROMPTS, E as EventHandlers, as as GadgetClass, V as GadgetExecutionControllerContext, at as GadgetOrClass, W as GadgetParameterInterceptorContext, X as GadgetResultInterceptorContext, H as HistoryMessage, Y as Interceptors, Z as LLMCallControllerContext, _ as LLMErrorControllerContext, aa as LLMMessageBuilder, a9 as LLMRole, a8 as LLMist, a7 as LLMistOptions, $ as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, ac as ModelFeatures, ah as ModelIdentifierParser, ad as ModelLimits, ae as ModelPricing, a0 as ObserveChunkContext, a1 as ObserveGadgetCompleteContext, a2 as ObserveGadgetStartContext, a3 as ObserveLLMCallContext, a4 as ObserveLLMCompleteContext, a5 as ObserveLLMErrorContext, a6 as Observers, ai as PromptConfig, aj as PromptContext, ak as PromptTemplate, af as ProviderIdentifier, ao as QuickOptions, ar as StreamParser, au as TextOnlyAction, av as TextOnlyContext, aw as TextOnlyCustomHandler, ax as TextOnlyGadgetConfig, ay as TextOnlyHandler, az as TextOnlyStrategy, ag as TokenUsage, z as collectEvents, C as collectText, ap as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, am as resolvePromptTemplate, an as resolveRulesTemplate, D as runWithHandlers, aq as stream } from './mock-stream-B5R6XPif.js';
+import { A as AgentHooks, o as ModelRegistry, L as LLMMessage, P as ParameterFormat, S as StreamEvent, G as GadgetRegistry, p as LLMStreamChunk, q as GadgetExample, B as BaseGadget, r as ParsedGadgetCall, s as GadgetExecutionResult, t as ProviderAdapter, u as ModelDescriptor, v as ModelSpec, w as LLMGenerationOptions, x as LLMStream } from './mock-stream-B2qwECvd.js';
+export { F as AfterGadgetExecutionAction, I as AfterGadgetExecutionControllerContext, J as AfterLLMCallAction, K as AfterLLMCallControllerContext, N as AfterLLMErrorAction, y as AgentBuilder, O as AgentOptions, Q as BeforeGadgetExecutionAction, R as BeforeLLMCallAction, T as ChunkInterceptorContext, U as Controllers, ab as CostEstimate, al as DEFAULT_PROMPTS, E as EventHandlers, as as GadgetClass, V as GadgetExecutionControllerContext, at as GadgetOrClass, W as GadgetParameterInterceptorContext, X as GadgetResultInterceptorContext, H as HistoryMessage, Y as Interceptors, Z as LLMCallControllerContext, _ as LLMErrorControllerContext, aa as LLMMessageBuilder, a9 as LLMRole, a8 as LLMist, a7 as LLMistOptions, $ as MessageInterceptorContext, a as MockBuilder, d as MockManager, h as MockMatcher, i as MockMatcherContext, j as MockOptions, M as MockProviderAdapter, k as MockRegistration, l as MockResponse, n as MockStats, ac as ModelFeatures, ah as ModelIdentifierParser, ad as ModelLimits, ae as ModelPricing, a0 as ObserveChunkContext, a1 as ObserveGadgetCompleteContext, a2 as ObserveGadgetStartContext, a3 as ObserveLLMCallContext, a4 as ObserveLLMCompleteContext, a5 as ObserveLLMErrorContext, a6 as Observers, ai as PromptConfig, aj as PromptContext, ak as PromptTemplate, af as ProviderIdentifier, ao as QuickOptions, ar as StreamParser, au as TextOnlyAction, av as TextOnlyContext, aw as TextOnlyCustomHandler, ax as TextOnlyGadgetConfig, ay as TextOnlyHandler, az as TextOnlyStrategy, ag as TokenUsage, z as collectEvents, C as collectText, ap as complete, c as createMockAdapter, b as createMockClient, e as createMockStream, f as createTextMockStream, g as getMockManager, m as mockLLM, am as resolvePromptTemplate, an as resolveRulesTemplate, D as runWithHandlers, aq as stream } from './mock-stream-B2qwECvd.js';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';

package/dist/index.js

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

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

@@ -1565,6 +1565,18 @@ interface AgentOptions {
     }>;
     /** Text-only handler */
     textOnlyHandler?: TextOnlyHandler;
+    /**
+     * Handler for text content that appears alongside gadget calls.
+     * When set, text accompanying gadgets will be wrapped as a synthetic gadget call.
+     */
+    textWithGadgetsHandler?: {
+        /** Name of the gadget to use for wrapping text */
+        gadgetName: string;
+        /** Maps text content to gadget parameters */
+        parameterMapping: (text: string) => Record<string, unknown>;
+        /** Maps text content to the result string (optional, defaults to text) */
+        resultMapping?: (text: string) => string;
+    };
     /** Stop on gadget error */
     stopOnGadgetError?: boolean;
     /** Custom error continuation logic */
@@ -1612,6 +1624,7 @@ declare class Agent {
     private readonly gadgetEndPrefix?;
     private readonly onHumanInputRequired?;
     private readonly textOnlyHandler;
+    private readonly textWithGadgetsHandler?;
     private readonly stopOnGadgetError;
     private readonly shouldContinueAfterError?;
     private readonly defaultGadgetTimeoutMs?;
@@ -1741,6 +1754,7 @@ declare class AgentBuilder {
     private gadgetStartPrefix?;
     private gadgetEndPrefix?;
     private textOnlyHandler?;
+    private textWithGadgetsHandler?;
     private stopOnGadgetError?;
     private shouldContinueAfterError?;
     private defaultGadgetTimeoutMs?;
@@ -1949,6 +1963,31 @@ declare class AgentBuilder {
      * ```
      */
     withTextOnlyHandler(handler: TextOnlyHandler): this;
+    /**
+     * Set the handler for text content that appears alongside gadget calls.
+     *
+     * When set, text accompanying gadget responses will be wrapped as a
+     * synthetic gadget call before the actual gadget results in the
+     * conversation history.
+     *
+     * @param handler - Configuration for wrapping text
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * // Wrap text as TellUser gadget
+     * .withTextWithGadgetsHandler({
+     *   gadgetName: "TellUser",
+     *   parameterMapping: (text) => ({ message: text, done: false, type: "info" }),
+     *   resultMapping: (text) => `ℹ️  ${text}`,
+     * })
+     * ```
+     */
+    withTextWithGadgetsHandler(handler: {
+        gadgetName: string;
+        parameterMapping: (text: string) => Record<string, unknown>;
+        resultMapping?: (text: string) => string;
+    }): this;
     /**
      * Set whether to stop gadget execution on first error.
      *
@@ -2047,6 +2086,37 @@ declare class AgentBuilder {
      * ```
      */
     withGadgetOutputLimitPercent(percent: number): this;
+    /**
+     * Add a synthetic gadget call to the conversation history.
+     *
+     * This is useful for in-context learning - showing the LLM what "past self"
+     * did correctly so it mimics the pattern. The call is formatted with proper
+     * markers and parameter format.
+     *
+     * @param gadgetName - Name of the gadget
+     * @param parameters - Parameters passed to the gadget
+     * @param result - Result returned by the gadget
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withSyntheticGadgetCall(
+     *   'TellUser',
+     *   {
+     *     message: '👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
+     *     done: false,
+     *     type: 'info'
+     *   },
+     *   'ℹ️  👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands'
+     * )
+     * ```
+     */
+    withSyntheticGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): this;
+    /**
+     * Format parameters for synthetic gadget calls.
+     * Uses heredoc for multiline string values.
+     */
+    private formatSyntheticParameters;
     /**
      * Build and create the agent with the given user prompt.
      * Returns the Agent instance ready to run.

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

@@ -1565,6 +1565,18 @@ interface AgentOptions {
     }>;
     /** Text-only handler */
     textOnlyHandler?: TextOnlyHandler;
+    /**
+     * Handler for text content that appears alongside gadget calls.
+     * When set, text accompanying gadgets will be wrapped as a synthetic gadget call.
+     */
+    textWithGadgetsHandler?: {
+        /** Name of the gadget to use for wrapping text */
+        gadgetName: string;
+        /** Maps text content to gadget parameters */
+        parameterMapping: (text: string) => Record<string, unknown>;
+        /** Maps text content to the result string (optional, defaults to text) */
+        resultMapping?: (text: string) => string;
+    };
     /** Stop on gadget error */
     stopOnGadgetError?: boolean;
     /** Custom error continuation logic */
@@ -1612,6 +1624,7 @@ declare class Agent {
     private readonly gadgetEndPrefix?;
     private readonly onHumanInputRequired?;
     private readonly textOnlyHandler;
+    private readonly textWithGadgetsHandler?;
     private readonly stopOnGadgetError;
     private readonly shouldContinueAfterError?;
     private readonly defaultGadgetTimeoutMs?;
@@ -1741,6 +1754,7 @@ declare class AgentBuilder {
     private gadgetStartPrefix?;
     private gadgetEndPrefix?;
     private textOnlyHandler?;
+    private textWithGadgetsHandler?;
     private stopOnGadgetError?;
     private shouldContinueAfterError?;
     private defaultGadgetTimeoutMs?;
@@ -1949,6 +1963,31 @@ declare class AgentBuilder {
      * ```
      */
     withTextOnlyHandler(handler: TextOnlyHandler): this;
+    /**
+     * Set the handler for text content that appears alongside gadget calls.
+     *
+     * When set, text accompanying gadget responses will be wrapped as a
+     * synthetic gadget call before the actual gadget results in the
+     * conversation history.
+     *
+     * @param handler - Configuration for wrapping text
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * // Wrap text as TellUser gadget
+     * .withTextWithGadgetsHandler({
+     *   gadgetName: "TellUser",
+     *   parameterMapping: (text) => ({ message: text, done: false, type: "info" }),
+     *   resultMapping: (text) => `ℹ️  ${text}`,
+     * })
+     * ```
+     */
+    withTextWithGadgetsHandler(handler: {
+        gadgetName: string;
+        parameterMapping: (text: string) => Record<string, unknown>;
+        resultMapping?: (text: string) => string;
+    }): this;
     /**
      * Set whether to stop gadget execution on first error.
      *
@@ -2047,6 +2086,37 @@ declare class AgentBuilder {
      * ```
      */
     withGadgetOutputLimitPercent(percent: number): this;
+    /**
+     * Add a synthetic gadget call to the conversation history.
+     *
+     * This is useful for in-context learning - showing the LLM what "past self"
+     * did correctly so it mimics the pattern. The call is formatted with proper
+     * markers and parameter format.
+     *
+     * @param gadgetName - Name of the gadget
+     * @param parameters - Parameters passed to the gadget
+     * @param result - Result returned by the gadget
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * .withSyntheticGadgetCall(
+     *   'TellUser',
+     *   {
+     *     message: '👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
+     *     done: false,
+     *     type: 'info'
+     *   },
+     *   'ℹ️  👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands'
+     * )
+     * ```
+     */
+    withSyntheticGadgetCall(gadgetName: string, parameters: Record<string, unknown>, result: string): this;
+    /**
+     * Format parameters for synthetic gadget calls.
+     * Uses heredoc for multiline string values.
+     */
+    private formatSyntheticParameters;
     /**
      * Build and create the agent with the given user prompt.
      * Returns the Agent instance ready to run.

package/dist/testing/index.cjs

@@ -922,6 +922,10 @@ function formatParamsAsYaml(params) {
   }
   return lines.join("\n");
 }
+function formatTomlInlineTable(obj) {
+  const entries = Object.entries(obj).map(([k, v]) => `${k} = ${formatTomlValue(v)}`);
+  return `{ ${entries.join(", ")} }`;
+}
 function formatTomlValue(value) {
   if (typeof value === "string") {
     if (value.includes("\n")) {
@@ -939,10 +943,17 @@ ${delimiter}`;
     return '""';
   }
   if (Array.isArray(value)) {
-    return JSON.stringify(value);
+    if (value.length === 0) return "[]";
+    const items = value.map((item) => {
+      if (typeof item === "object" && item !== null && !Array.isArray(item)) {
+        return formatTomlInlineTable(item);
+      }
+      return formatTomlValue(item);
+    });
+    return `[${items.join(", ")}]`;
   }
   if (typeof value === "object") {
-    return JSON.stringify(value);
+    return formatTomlInlineTable(value);
   }
   return JSON.stringify(value);
 }
@@ -1958,6 +1969,14 @@ function preprocessTomlHeredoc(tomlStr) {
   }
   return result.join("\n");
 }
+function stripMarkdownFences(content) {
+  let cleaned = content.trim();
+  const openingFence = /^```(?:toml|yaml|json)?\s*\n/i;
+  const closingFence = /\n?```\s*$/;
+  cleaned = cleaned.replace(openingFence, "");
+  cleaned = cleaned.replace(closingFence, "");
+  return cleaned.trim();
+}
 var yaml2, import_js_toml, globalInvocationCounter, StreamParser;
 var init_parser = __esm({
   "src/gadgets/parser.ts"() {
@@ -2013,35 +2032,36 @@ var init_parser = __esm({
        * Parse parameter string according to configured format
        */
       parseParameters(raw) {
+        const cleaned = stripMarkdownFences(raw);
         if (this.parameterFormat === "json") {
           try {
-            return { parameters: JSON.parse(raw) };
+            return { parameters: JSON.parse(cleaned) };
           } catch (error) {
             return { parseError: this.truncateParseError(error, "JSON") };
           }
         }
         if (this.parameterFormat === "yaml") {
           try {
-            return { parameters: yaml2.load(preprocessYaml(raw)) };
+            return { parameters: yaml2.load(preprocessYaml(cleaned)) };
           } catch (error) {
             return { parseError: this.truncateParseError(error, "YAML") };
           }
         }
         if (this.parameterFormat === "toml") {
           try {
-            return { parameters: (0, import_js_toml.load)(preprocessTomlHeredoc(raw)) };
+            return { parameters: (0, import_js_toml.load)(preprocessTomlHeredoc(cleaned)) };
           } catch (error) {
             return { parseError: this.truncateParseError(error, "TOML") };
           }
         }
         try {
-          return { parameters: JSON.parse(raw) };
+          return { parameters: JSON.parse(cleaned) };
         } catch {
           try {
-            return { parameters: (0, import_js_toml.load)(preprocessTomlHeredoc(raw)) };
+            return { parameters: (0, import_js_toml.load)(preprocessTomlHeredoc(cleaned)) };
           } catch {
             try {
-              return { parameters: yaml2.load(preprocessYaml(raw)) };
+              return { parameters: yaml2.load(preprocessYaml(cleaned)) };
             } catch (error) {
               return { parseError: this.truncateParseError(error, "auto") };
             }
@@ -2587,6 +2607,7 @@ var init_agent = __esm({
       gadgetEndPrefix;
       onHumanInputRequired;
       textOnlyHandler;
+      textWithGadgetsHandler;
       stopOnGadgetError;
       shouldContinueAfterError;
       defaultGadgetTimeoutMs;
@@ -2617,6 +2638,7 @@ var init_agent = __esm({
         this.gadgetEndPrefix = options.gadgetEndPrefix;
         this.onHumanInputRequired = options.onHumanInputRequired;
         this.textOnlyHandler = options.textOnlyHandler ?? "terminate";
+        this.textWithGadgetsHandler = options.textWithGadgetsHandler;
         this.stopOnGadgetError = options.stopOnGadgetError ?? true;
         this.shouldContinueAfterError = options.shouldContinueAfterError;
         this.defaultGadgetTimeoutMs = options.defaultGadgetTimeoutMs;
@@ -2804,6 +2826,17 @@ var init_agent = __esm({
               }
             }
             if (result.didExecuteGadgets) {
+              if (this.textWithGadgetsHandler) {
+                const textContent = result.outputs.filter((output) => output.type === "text").map((output) => output.content).join("");
+                if (textContent.trim()) {
+                  const { gadgetName, parameterMapping, resultMapping } = this.textWithGadgetsHandler;
+                  this.conversation.addGadgetCall(
+                    gadgetName,
+                    parameterMapping(textContent),
+                    resultMapping ? resultMapping(textContent) : textContent
+                  );
+                }
+              }
               for (const output of result.outputs) {
                 if (output.type === "gadget_result") {
                   const gadgetResult = output.result;
@@ -2815,7 +2848,13 @@ var init_agent = __esm({
                 }
               }
             } else {
-              this.conversation.addAssistantMessage(finalMessage);
+              if (finalMessage.trim()) {
+                this.conversation.addGadgetCall(
+                  "TellUser",
+                  { message: finalMessage, done: false, type: "info" },
+                  `\u2139\uFE0F  ${finalMessage}`
+                );
+              }
               const shouldBreak = await this.handleTextOnlyResponse(finalMessage);
               if (shouldBreak) {
                 break;
@@ -3000,6 +3039,7 @@ var AgentBuilder;
 var init_builder = __esm({
   "src/agent/builder.ts"() {
     "use strict";
+    init_constants();
     init_model_shortcuts();
     init_registry();
     init_agent();
@@ -3021,6 +3061,7 @@ var init_builder = __esm({
       gadgetStartPrefix;
       gadgetEndPrefix;
       textOnlyHandler;
+      textWithGadgetsHandler;
       stopOnGadgetError;
       shouldContinueAfterError;
       defaultGadgetTimeoutMs;
@@ -3283,6 +3324,30 @@ var init_builder = __esm({
         this.textOnlyHandler = handler;
         return this;
       }
+      /**
+       * Set the handler for text content that appears alongside gadget calls.
+       *
+       * When set, text accompanying gadget responses will be wrapped as a
+       * synthetic gadget call before the actual gadget results in the
+       * conversation history.
+       *
+       * @param handler - Configuration for wrapping text
+       * @returns This builder for chaining
+       *
+       * @example
+       * ```typescript
+       * // Wrap text as TellUser gadget
+       * .withTextWithGadgetsHandler({
+       *   gadgetName: "TellUser",
+       *   parameterMapping: (text) => ({ message: text, done: false, type: "info" }),
+       *   resultMapping: (text) => `ℹ️  ${text}`,
+       * })
+       * ```
+       */
+      withTextWithGadgetsHandler(handler) {
+        this.textWithGadgetsHandler = handler;
+        return this;
+      }
       /**
        * Set whether to stop gadget execution on first error.
        *
@@ -3397,6 +3462,69 @@ var init_builder = __esm({
         this.gadgetOutputLimitPercent = percent;
         return this;
       }
+      /**
+       * Add a synthetic gadget call to the conversation history.
+       *
+       * This is useful for in-context learning - showing the LLM what "past self"
+       * did correctly so it mimics the pattern. The call is formatted with proper
+       * markers and parameter format.
+       *
+       * @param gadgetName - Name of the gadget
+       * @param parameters - Parameters passed to the gadget
+       * @param result - Result returned by the gadget
+       * @returns This builder for chaining
+       *
+       * @example
+       * ```typescript
+       * .withSyntheticGadgetCall(
+       *   'TellUser',
+       *   {
+       *     message: '👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands',
+       *     done: false,
+       *     type: 'info'
+       *   },
+       *   'ℹ️  👋 Hello!\n\nHere\'s what I can do:\n- Analyze code\n- Run commands'
+       * )
+       * ```
+       */
+      withSyntheticGadgetCall(gadgetName, parameters, result) {
+        const startPrefix = this.gadgetStartPrefix ?? GADGET_START_PREFIX;
+        const endPrefix = this.gadgetEndPrefix ?? GADGET_END_PREFIX;
+        const format = this.parameterFormat ?? "yaml";
+        const paramStr = this.formatSyntheticParameters(parameters, format);
+        this.initialMessages.push({
+          role: "assistant",
+          content: `${startPrefix}${gadgetName}
+${paramStr}
+${endPrefix}`
+        });
+        this.initialMessages.push({
+          role: "user",
+          content: `Result: ${result}`
+        });
+        return this;
+      }
+      /**
+       * Format parameters for synthetic gadget calls.
+       * Uses heredoc for multiline string values.
+       */
+      formatSyntheticParameters(parameters, format) {
+        if (format === "json" || format === "auto") {
+          return JSON.stringify(parameters);
+        }
+        return Object.entries(parameters).map(([key, value]) => {
+          if (typeof value === "string" && value.includes("\n")) {
+            const separator = format === "yaml" ? ":" : " =";
+            return `${key}${separator} <<<EOF
+${value}
+EOF`;
+          }
+          if (format === "yaml") {
+            return typeof value === "string" ? `${key}: ${value}` : `${key}: ${JSON.stringify(value)}`;
+          }
+          return `${key} = ${JSON.stringify(value)}`;
+        }).join("\n");
+      }
       /**
        * Build and create the agent with the given user prompt.
        * Returns the Agent instance ready to run.
@@ -3439,6 +3567,7 @@ var init_builder = __esm({
           gadgetStartPrefix: this.gadgetStartPrefix,
           gadgetEndPrefix: this.gadgetEndPrefix,
           textOnlyHandler: this.textOnlyHandler,
+          textWithGadgetsHandler: this.textWithGadgetsHandler,
           stopOnGadgetError: this.stopOnGadgetError,
           shouldContinueAfterError: this.shouldContinueAfterError,
           defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,
@@ -3540,6 +3669,7 @@ var init_builder = __esm({
           gadgetStartPrefix: this.gadgetStartPrefix,
           gadgetEndPrefix: this.gadgetEndPrefix,
           textOnlyHandler: this.textOnlyHandler,
+          textWithGadgetsHandler: this.textWithGadgetsHandler,
           stopOnGadgetError: this.stopOnGadgetError,
           shouldContinueAfterError: this.shouldContinueAfterError,
           defaultGadgetTimeoutMs: this.defaultGadgetTimeoutMs,