llmist 2.0.0 → 2.1.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { ZodType, ZodTypeAny } from 'zod';
 export { z } from 'zod';
-import { A as AgentHooks, q as ModelRegistry, I as IConversationManager, b as LLMMessage, S as StreamEvent, T as TokenUsage, G as GadgetRegistry, r as LLMist, a as LLMStreamChunk, C as CompactionStrategy, R as ResolvedCompactionConfig, s as CompactionContext, t as CompactionResult, u as CompactionConfig, v as CompactionEvent, w as CompactionStats, H as HintTemplate, E as ExecutionContext, x as GadgetExecuteReturn, y as GadgetExample, B as BaseGadget, P as ParsedGadgetCall, z as GadgetExecutionResult, D as ProviderAdapter, F as ModelDescriptor, J as ModelSpec, K as LLMGenerationOptions, L as LLMStream } from './mock-stream-BQHut0lQ.cjs';
-export { Z as AfterGadgetExecutionAction, _ as AfterGadgetExecutionControllerContext, $ as AfterLLMCallAction, a0 as AfterLLMCallControllerContext, a1 as AfterLLMErrorAction, U as AgentBuilder, a2 as AgentOptions, a3 as BeforeGadgetExecutionAction, a4 as BeforeLLMCallAction, a5 as ChunkInterceptorContext, a6 as Controllers, as as CostEstimate, aM as CostReportingLLMist, an as DEFAULT_COMPACTION_CONFIG, aC as DEFAULT_HINTS, aD as DEFAULT_PROMPTS, ao as DEFAULT_SUMMARIZATION_PROMPT, V as EventHandlers, aK as GadgetClass, aN as GadgetExecuteResult, a7 as GadgetExecutionControllerContext, aL as GadgetOrClass, a8 as GadgetParameterInterceptorContext, a9 as GadgetResultInterceptorContext, ay as HintContext, N as HistoryMessage, aa as Interceptors, ab as LLMCallControllerContext, ac as LLMErrorControllerContext, ar as LLMMessageBuilder, aq as LLMRole, ap as LLMistOptions, ad as MessageInterceptorContext, al as MessageTurn, d as MockBuilder, f as MockManager, j as MockMatcher, k as MockMatcherContext, l as MockOptions, M as MockProviderAdapter, n as MockRegistration, o as MockResponse, p as MockStats, at as ModelFeatures, ax as ModelIdentifierParser, au as ModelLimits, av as ModelPricing, ae as ObserveChunkContext, am as ObserveCompactionContext, af as ObserveGadgetCompleteContext, ag as ObserveGadgetStartContext, ah as ObserveLLMCallContext, ai as ObserveLLMCompleteContext, aj as ObserveLLMErrorContext, ak as Observers, az as PromptConfig, aA as PromptContext, aB as PromptTemplate, aw as ProviderIdentifier, aH as QuickOptions, aO as TextOnlyAction, aP as TextOnlyContext, aQ as TextOnlyCustomHandler, aR as TextOnlyGadgetConfig, aS as TextOnlyHandler, aT as TextOnlyStrategy, O as TrailingMessage, Q as TrailingMessageContext, W as collectEvents, X as collectText, aI as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM, aE as resolveHintTemplate, aF as resolvePromptTemplate, aG as resolveRulesTemplate, Y as runWithHandlers, aJ as stream } from './mock-stream-BQHut0lQ.cjs';
+import { A as AgentHooks, q as ModelRegistry, I as IConversationManager, b as LLMMessage, S as StreamEvent, T as TokenUsage, G as GadgetRegistry, r as LLMist, a as LLMStreamChunk, C as CompactionStrategy, R as ResolvedCompactionConfig, s as CompactionContext, t as CompactionResult, u as CompactionConfig, v as CompactionEvent, w as CompactionStats, H as HintTemplate, E as ExecutionContext, x as GadgetExecuteReturn, y as GadgetExample, B as BaseGadget, P as ParsedGadgetCall, z as GadgetExecutionResult, D as ProviderAdapter, F as ModelDescriptor, J as ModelSpec, K as LLMGenerationOptions, L as LLMStream } from './mock-stream-HF7MBNhi.cjs';
+export { Z as AfterGadgetExecutionAction, _ as AfterGadgetExecutionControllerContext, $ as AfterLLMCallAction, a0 as AfterLLMCallControllerContext, a1 as AfterLLMErrorAction, U as AgentBuilder, a2 as AgentOptions, a3 as BeforeGadgetExecutionAction, a4 as BeforeLLMCallAction, a5 as ChunkInterceptorContext, a6 as Controllers, as as CostEstimate, aM as CostReportingLLMist, an as DEFAULT_COMPACTION_CONFIG, aC as DEFAULT_HINTS, aD as DEFAULT_PROMPTS, ao as DEFAULT_SUMMARIZATION_PROMPT, V as EventHandlers, aK as GadgetClass, aN as GadgetExecuteResult, a7 as GadgetExecutionControllerContext, aL as GadgetOrClass, a8 as GadgetParameterInterceptorContext, a9 as GadgetResultInterceptorContext, ay as HintContext, N as HistoryMessage, aa as Interceptors, ab as LLMCallControllerContext, ac as LLMErrorControllerContext, ar as LLMMessageBuilder, aq as LLMRole, ap as LLMistOptions, ad as MessageInterceptorContext, al as MessageTurn, d as MockBuilder, f as MockManager, j as MockMatcher, k as MockMatcherContext, l as MockOptions, M as MockProviderAdapter, n as MockRegistration, o as MockResponse, p as MockStats, at as ModelFeatures, ax as ModelIdentifierParser, au as ModelLimits, av as ModelPricing, ae as ObserveChunkContext, am as ObserveCompactionContext, af as ObserveGadgetCompleteContext, ag as ObserveGadgetStartContext, ah as ObserveLLMCallContext, ai as ObserveLLMCompleteContext, aj as ObserveLLMErrorContext, ak as Observers, az as PromptConfig, aA as PromptContext, aB as PromptTemplate, aw as ProviderIdentifier, aH as QuickOptions, aO as TextOnlyAction, aP as TextOnlyContext, aQ as TextOnlyCustomHandler, aR as TextOnlyGadgetConfig, aS as TextOnlyHandler, aT as TextOnlyStrategy, O as TrailingMessage, Q as TrailingMessageContext, W as collectEvents, X as collectText, aI as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM, aE as resolveHintTemplate, aF as resolvePromptTemplate, aG as resolveRulesTemplate, Y as runWithHandlers, aJ as stream } from './mock-stream-HF7MBNhi.cjs';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';
@@ -1843,6 +1843,8 @@ declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>):
          */
         execute(params: Record<string, unknown>, ctx?: ExecutionContext): GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
         throwIfAborted(ctx?: ExecutionContext): void;
+        onAbort(ctx: ExecutionContext | undefined, cleanup: () => void | Promise<void>): void;
+        createLinkedAbortController(ctx?: ExecutionContext): AbortController;
         get instruction(): string;
         getInstruction(optionsOrArgPrefix?: string | {
             argPrefix?: string;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ZodType, ZodTypeAny } from 'zod';
 export { z } from 'zod';
-import { A as AgentHooks, q as ModelRegistry, I as IConversationManager, b as LLMMessage, S as StreamEvent, T as TokenUsage, G as GadgetRegistry, r as LLMist, a as LLMStreamChunk, C as CompactionStrategy, R as ResolvedCompactionConfig, s as CompactionContext, t as CompactionResult, u as CompactionConfig, v as CompactionEvent, w as CompactionStats, H as HintTemplate, E as ExecutionContext, x as GadgetExecuteReturn, y as GadgetExample, B as BaseGadget, P as ParsedGadgetCall, z as GadgetExecutionResult, D as ProviderAdapter, F as ModelDescriptor, J as ModelSpec, K as LLMGenerationOptions, L as LLMStream } from './mock-stream-BQHut0lQ.js';
-export { Z as AfterGadgetExecutionAction, _ as AfterGadgetExecutionControllerContext, $ as AfterLLMCallAction, a0 as AfterLLMCallControllerContext, a1 as AfterLLMErrorAction, U as AgentBuilder, a2 as AgentOptions, a3 as BeforeGadgetExecutionAction, a4 as BeforeLLMCallAction, a5 as ChunkInterceptorContext, a6 as Controllers, as as CostEstimate, aM as CostReportingLLMist, an as DEFAULT_COMPACTION_CONFIG, aC as DEFAULT_HINTS, aD as DEFAULT_PROMPTS, ao as DEFAULT_SUMMARIZATION_PROMPT, V as EventHandlers, aK as GadgetClass, aN as GadgetExecuteResult, a7 as GadgetExecutionControllerContext, aL as GadgetOrClass, a8 as GadgetParameterInterceptorContext, a9 as GadgetResultInterceptorContext, ay as HintContext, N as HistoryMessage, aa as Interceptors, ab as LLMCallControllerContext, ac as LLMErrorControllerContext, ar as LLMMessageBuilder, aq as LLMRole, ap as LLMistOptions, ad as MessageInterceptorContext, al as MessageTurn, d as MockBuilder, f as MockManager, j as MockMatcher, k as MockMatcherContext, l as MockOptions, M as MockProviderAdapter, n as MockRegistration, o as MockResponse, p as MockStats, at as ModelFeatures, ax as ModelIdentifierParser, au as ModelLimits, av as ModelPricing, ae as ObserveChunkContext, am as ObserveCompactionContext, af as ObserveGadgetCompleteContext, ag as ObserveGadgetStartContext, ah as ObserveLLMCallContext, ai as ObserveLLMCompleteContext, aj as ObserveLLMErrorContext, ak as Observers, az as PromptConfig, aA as PromptContext, aB as PromptTemplate, aw as ProviderIdentifier, aH as QuickOptions, aO as TextOnlyAction, aP as TextOnlyContext, aQ as TextOnlyCustomHandler, aR as TextOnlyGadgetConfig, aS as TextOnlyHandler, aT as TextOnlyStrategy, O as TrailingMessage, Q as TrailingMessageContext, W as collectEvents, X as collectText, aI as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM, aE as resolveHintTemplate, aF as resolvePromptTemplate, aG as resolveRulesTemplate, Y as runWithHandlers, aJ as stream } from './mock-stream-BQHut0lQ.js';
+import { A as AgentHooks, q as ModelRegistry, I as IConversationManager, b as LLMMessage, S as StreamEvent, T as TokenUsage, G as GadgetRegistry, r as LLMist, a as LLMStreamChunk, C as CompactionStrategy, R as ResolvedCompactionConfig, s as CompactionContext, t as CompactionResult, u as CompactionConfig, v as CompactionEvent, w as CompactionStats, H as HintTemplate, E as ExecutionContext, x as GadgetExecuteReturn, y as GadgetExample, B as BaseGadget, P as ParsedGadgetCall, z as GadgetExecutionResult, D as ProviderAdapter, F as ModelDescriptor, J as ModelSpec, K as LLMGenerationOptions, L as LLMStream } from './mock-stream-HF7MBNhi.js';
+export { Z as AfterGadgetExecutionAction, _ as AfterGadgetExecutionControllerContext, $ as AfterLLMCallAction, a0 as AfterLLMCallControllerContext, a1 as AfterLLMErrorAction, U as AgentBuilder, a2 as AgentOptions, a3 as BeforeGadgetExecutionAction, a4 as BeforeLLMCallAction, a5 as ChunkInterceptorContext, a6 as Controllers, as as CostEstimate, aM as CostReportingLLMist, an as DEFAULT_COMPACTION_CONFIG, aC as DEFAULT_HINTS, aD as DEFAULT_PROMPTS, ao as DEFAULT_SUMMARIZATION_PROMPT, V as EventHandlers, aK as GadgetClass, aN as GadgetExecuteResult, a7 as GadgetExecutionControllerContext, aL as GadgetOrClass, a8 as GadgetParameterInterceptorContext, a9 as GadgetResultInterceptorContext, ay as HintContext, N as HistoryMessage, aa as Interceptors, ab as LLMCallControllerContext, ac as LLMErrorControllerContext, ar as LLMMessageBuilder, aq as LLMRole, ap as LLMistOptions, ad as MessageInterceptorContext, al as MessageTurn, d as MockBuilder, f as MockManager, j as MockMatcher, k as MockMatcherContext, l as MockOptions, M as MockProviderAdapter, n as MockRegistration, o as MockResponse, p as MockStats, at as ModelFeatures, ax as ModelIdentifierParser, au as ModelLimits, av as ModelPricing, ae as ObserveChunkContext, am as ObserveCompactionContext, af as ObserveGadgetCompleteContext, ag as ObserveGadgetStartContext, ah as ObserveLLMCallContext, ai as ObserveLLMCompleteContext, aj as ObserveLLMErrorContext, ak as Observers, az as PromptConfig, aA as PromptContext, aB as PromptTemplate, aw as ProviderIdentifier, aH as QuickOptions, aO as TextOnlyAction, aP as TextOnlyContext, aQ as TextOnlyCustomHandler, aR as TextOnlyGadgetConfig, aS as TextOnlyHandler, aT as TextOnlyStrategy, O as TrailingMessage, Q as TrailingMessageContext, W as collectEvents, X as collectText, aI as complete, c as createMockAdapter, e as createMockClient, h as createMockStream, i as createTextMockStream, g as getMockManager, m as mockLLM, aE as resolveHintTemplate, aF as resolvePromptTemplate, aG as resolveRulesTemplate, Y as runWithHandlers, aJ as stream } from './mock-stream-HF7MBNhi.js';
 import { Logger, ILogObj } from 'tslog';
 import { MessageCreateParamsStreaming, MessageStreamEvent } from '@anthropic-ai/sdk/resources/messages';
 import OpenAI from 'openai';
@@ -1843,6 +1843,8 @@ declare function Gadget<TSchema extends ZodType>(config: GadgetConfig<TSchema>):
          */
         execute(params: Record<string, unknown>, ctx?: ExecutionContext): GadgetExecuteReturn | Promise<GadgetExecuteReturn>;
         throwIfAborted(ctx?: ExecutionContext): void;
+        onAbort(ctx: ExecutionContext | undefined, cleanup: () => void | Promise<void>): void;
+        createLinkedAbortController(ctx?: ExecutionContext): AbortController;
         get instruction(): string;
         getInstruction(optionsOrArgPrefix?: string | {
             argPrefix?: string;

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   iterationProgressHint,
   parallelGadgetHint,
   z
-} from "./chunk-LFSIEPAE.js";
+} from "./chunk-LSCCBXS7.js";
 import {
   AbortError,
   AgentBuilder,
@@ -65,7 +65,7 @@ import {
   stream,
   validateAndApplyDefaults,
   validateGadgetParams
-} from "./chunk-LBHWVCZ2.js";
+} from "./chunk-PDYVT3FI.js";
 export {
   AbortError,
   AgentBuilder,

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

@@ -998,6 +998,67 @@ declare abstract class BaseGadget {
      * ```
      */
     throwIfAborted(ctx?: ExecutionContext): void;
+    /**
+     * Register a cleanup function to run when execution is aborted (timeout or cancellation).
+     * The cleanup function is called immediately if the signal is already aborted.
+     * Errors thrown by the cleanup function are silently ignored.
+     *
+     * Use this to clean up resources like browser instances, database connections,
+     * or child processes when the gadget is cancelled due to timeout.
+     *
+     * @param ctx - The execution context containing the abort signal
+     * @param cleanup - Function to run on abort (can be sync or async)
+     *
+     * @example
+     * ```typescript
+     * class BrowserGadget extends Gadget({
+     *   description: 'Fetches web page content',
+     *   schema: z.object({ url: z.string() }),
+     * }) {
+     *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
+     *     const browser = await chromium.launch();
+     *     this.onAbort(ctx, () => browser.close());
+     *
+     *     const page = await browser.newPage();
+     *     this.onAbort(ctx, () => page.close());
+     *
+     *     await page.goto(params.url);
+     *     const content = await page.content();
+     *
+     *     await browser.close();
+     *     return content;
+     *   }
+     * }
+     * ```
+     */
+    onAbort(ctx: ExecutionContext | undefined, cleanup: () => void | Promise<void>): void;
+    /**
+     * Create an AbortController linked to the execution context's signal.
+     * When the parent signal aborts, the returned controller also aborts with the same reason.
+     *
+     * Useful for passing abort signals to child operations like fetch() while still
+     * being able to abort them independently if needed.
+     *
+     * @param ctx - The execution context containing the parent abort signal
+     * @returns A new AbortController linked to the parent signal
+     *
+     * @example
+     * ```typescript
+     * class FetchGadget extends Gadget({
+     *   description: 'Fetches data from URL',
+     *   schema: z.object({ url: z.string() }),
+     * }) {
+     *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
+     *     const controller = this.createLinkedAbortController(ctx);
+     *
+     *     // fetch() will automatically abort when parent times out
+     *     const response = await fetch(params.url, { signal: controller.signal });
+     *     return response.text();
+     *   }
+     * }
+     * ```
+     */
+    createLinkedAbortController(ctx?: ExecutionContext): AbortController;
     /**
      * Auto-generated instruction text for the LLM.
      * Combines name, description, and parameter schema into a formatted instruction.
@@ -1672,16 +1733,17 @@ declare function collectText(agentGenerator: AsyncGenerator<StreamEvent>): Promi
  * LLM CALL LIFECYCLE:
  * 1. onLLMCallStart (observer)
  * 2. beforeLLMCall (controller) - can skip/modify
- * 3. [LLM API Call]
- * 4. For each stream chunk:
+ * 3. onLLMCallReady (observer) - final state before API call
+ * 4. [LLM API Call]
+ * 5. For each stream chunk:
  *    a. interceptRawChunk (interceptor)
  *    b. onStreamChunk (observer)
  *    c. Parse for gadgets
  *    d. If gadget found -> GADGET LIFECYCLE
  *    e. If text -> interceptTextChunk -> emit
- * 5. afterLLMCall (controller) - can append/modify
- * 6. interceptAssistantMessage (interceptor)
- * 7. onLLMCallComplete (observer)
+ * 6. afterLLMCall (controller) - can append/modify
+ * 7. interceptAssistantMessage (interceptor)
+ * 8. onLLMCallComplete (observer)
  *
  * GADGET LIFECYCLE:
  * 1. interceptGadgetParameters (interceptor)
@@ -1705,6 +1767,18 @@ interface ObserveLLMCallContext {
     options: Readonly<LLMGenerationOptions>;
     logger: Logger<ILogObj>;
 }
+/**
+ * Context provided when an LLM call is ready to execute.
+ * Fires AFTER beforeLLMCall controller modifications, BEFORE the actual API call.
+ * Use this for logging the exact request being sent to the LLM.
+ */
+interface ObserveLLMCallReadyContext {
+    iteration: number;
+    maxIterations: number;
+    /** Final options after any controller modifications (e.g., trailing messages) */
+    options: Readonly<LLMGenerationOptions>;
+    logger: Logger<ILogObj>;
+}
 /**
  * Context provided when an LLM call completes successfully.
  * Read-only observation point.
@@ -1786,8 +1860,10 @@ interface ObserveChunkContext {
  * - Run in parallel (no ordering guarantees)
  */
 interface Observers {
-    /** Called when an LLM call starts */
+    /** Called when an LLM call starts (before controller modifications) */
     onLLMCallStart?: (context: ObserveLLMCallContext) => void | Promise<void>;
+    /** Called when an LLM call is ready (after controller modifications, before API call) */
+    onLLMCallReady?: (context: ObserveLLMCallReadyContext) => void | Promise<void>;
     /** Called when an LLM call completes successfully */
     onLLMCallComplete?: (context: ObserveLLMCompleteContext) => void | Promise<void>;
     /** Called when an LLM call fails */

package/dist/{mock-stream-BQHut0lQ.d.ts → mock-stream-HF7MBNhi.d.ts}

@@ -998,6 +998,67 @@ declare abstract class BaseGadget {
      * ```
      */
     throwIfAborted(ctx?: ExecutionContext): void;
+    /**
+     * Register a cleanup function to run when execution is aborted (timeout or cancellation).
+     * The cleanup function is called immediately if the signal is already aborted.
+     * Errors thrown by the cleanup function are silently ignored.
+     *
+     * Use this to clean up resources like browser instances, database connections,
+     * or child processes when the gadget is cancelled due to timeout.
+     *
+     * @param ctx - The execution context containing the abort signal
+     * @param cleanup - Function to run on abort (can be sync or async)
+     *
+     * @example
+     * ```typescript
+     * class BrowserGadget extends Gadget({
+     *   description: 'Fetches web page content',
+     *   schema: z.object({ url: z.string() }),
+     * }) {
+     *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
+     *     const browser = await chromium.launch();
+     *     this.onAbort(ctx, () => browser.close());
+     *
+     *     const page = await browser.newPage();
+     *     this.onAbort(ctx, () => page.close());
+     *
+     *     await page.goto(params.url);
+     *     const content = await page.content();
+     *
+     *     await browser.close();
+     *     return content;
+     *   }
+     * }
+     * ```
+     */
+    onAbort(ctx: ExecutionContext | undefined, cleanup: () => void | Promise<void>): void;
+    /**
+     * Create an AbortController linked to the execution context's signal.
+     * When the parent signal aborts, the returned controller also aborts with the same reason.
+     *
+     * Useful for passing abort signals to child operations like fetch() while still
+     * being able to abort them independently if needed.
+     *
+     * @param ctx - The execution context containing the parent abort signal
+     * @returns A new AbortController linked to the parent signal
+     *
+     * @example
+     * ```typescript
+     * class FetchGadget extends Gadget({
+     *   description: 'Fetches data from URL',
+     *   schema: z.object({ url: z.string() }),
+     * }) {
+     *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
+     *     const controller = this.createLinkedAbortController(ctx);
+     *
+     *     // fetch() will automatically abort when parent times out
+     *     const response = await fetch(params.url, { signal: controller.signal });
+     *     return response.text();
+     *   }
+     * }
+     * ```
+     */
+    createLinkedAbortController(ctx?: ExecutionContext): AbortController;
     /**
      * Auto-generated instruction text for the LLM.
      * Combines name, description, and parameter schema into a formatted instruction.
@@ -1672,16 +1733,17 @@ declare function collectText(agentGenerator: AsyncGenerator<StreamEvent>): Promi
  * LLM CALL LIFECYCLE:
  * 1. onLLMCallStart (observer)
  * 2. beforeLLMCall (controller) - can skip/modify
- * 3. [LLM API Call]
- * 4. For each stream chunk:
+ * 3. onLLMCallReady (observer) - final state before API call
+ * 4. [LLM API Call]
+ * 5. For each stream chunk:
  *    a. interceptRawChunk (interceptor)
  *    b. onStreamChunk (observer)
  *    c. Parse for gadgets
  *    d. If gadget found -> GADGET LIFECYCLE
  *    e. If text -> interceptTextChunk -> emit
- * 5. afterLLMCall (controller) - can append/modify
- * 6. interceptAssistantMessage (interceptor)
- * 7. onLLMCallComplete (observer)
+ * 6. afterLLMCall (controller) - can append/modify
+ * 7. interceptAssistantMessage (interceptor)
+ * 8. onLLMCallComplete (observer)
  *
  * GADGET LIFECYCLE:
  * 1. interceptGadgetParameters (interceptor)
@@ -1705,6 +1767,18 @@ interface ObserveLLMCallContext {
     options: Readonly<LLMGenerationOptions>;
     logger: Logger<ILogObj>;
 }
+/**
+ * Context provided when an LLM call is ready to execute.
+ * Fires AFTER beforeLLMCall controller modifications, BEFORE the actual API call.
+ * Use this for logging the exact request being sent to the LLM.
+ */
+interface ObserveLLMCallReadyContext {
+    iteration: number;
+    maxIterations: number;
+    /** Final options after any controller modifications (e.g., trailing messages) */
+    options: Readonly<LLMGenerationOptions>;
+    logger: Logger<ILogObj>;
+}
 /**
  * Context provided when an LLM call completes successfully.
  * Read-only observation point.
@@ -1786,8 +1860,10 @@ interface ObserveChunkContext {
  * - Run in parallel (no ordering guarantees)
  */
 interface Observers {
-    /** Called when an LLM call starts */
+    /** Called when an LLM call starts (before controller modifications) */
     onLLMCallStart?: (context: ObserveLLMCallContext) => void | Promise<void>;
+    /** Called when an LLM call is ready (after controller modifications, before API call) */
+    onLLMCallReady?: (context: ObserveLLMCallReadyContext) => void | Promise<void>;
     /** Called when an LLM call completes successfully */
     onLLMCallComplete?: (context: ObserveLLMCompleteContext) => void | Promise<void>;
     /** Called when an LLM call fails */

package/dist/testing/index.cjs

@@ -1019,6 +1019,100 @@ var init_gadget = __esm({
           throw new AbortError();
         }
       }
+      /**
+       * Register a cleanup function to run when execution is aborted (timeout or cancellation).
+       * The cleanup function is called immediately if the signal is already aborted.
+       * Errors thrown by the cleanup function are silently ignored.
+       *
+       * Use this to clean up resources like browser instances, database connections,
+       * or child processes when the gadget is cancelled due to timeout.
+       *
+       * @param ctx - The execution context containing the abort signal
+       * @param cleanup - Function to run on abort (can be sync or async)
+       *
+       * @example
+       * ```typescript
+       * class BrowserGadget extends Gadget({
+       *   description: 'Fetches web page content',
+       *   schema: z.object({ url: z.string() }),
+       * }) {
+       *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
+       *     const browser = await chromium.launch();
+       *     this.onAbort(ctx, () => browser.close());
+       *
+       *     const page = await browser.newPage();
+       *     this.onAbort(ctx, () => page.close());
+       *
+       *     await page.goto(params.url);
+       *     const content = await page.content();
+       *
+       *     await browser.close();
+       *     return content;
+       *   }
+       * }
+       * ```
+       */
+      onAbort(ctx, cleanup) {
+        if (!ctx?.signal) return;
+        const safeCleanup = () => {
+          try {
+            const result = cleanup();
+            if (result && typeof result === "object" && "catch" in result) {
+              result.catch(() => {
+              });
+            }
+          } catch {
+          }
+        };
+        if (ctx.signal.aborted) {
+          safeCleanup();
+          return;
+        }
+        ctx.signal.addEventListener("abort", safeCleanup, { once: true });
+      }
+      /**
+       * Create an AbortController linked to the execution context's signal.
+       * When the parent signal aborts, the returned controller also aborts with the same reason.
+       *
+       * Useful for passing abort signals to child operations like fetch() while still
+       * being able to abort them independently if needed.
+       *
+       * @param ctx - The execution context containing the parent abort signal
+       * @returns A new AbortController linked to the parent signal
+       *
+       * @example
+       * ```typescript
+       * class FetchGadget extends Gadget({
+       *   description: 'Fetches data from URL',
+       *   schema: z.object({ url: z.string() }),
+       * }) {
+       *   async execute(params: this['params'], ctx?: ExecutionContext): Promise<string> {
+       *     const controller = this.createLinkedAbortController(ctx);
+       *
+       *     // fetch() will automatically abort when parent times out
+       *     const response = await fetch(params.url, { signal: controller.signal });
+       *     return response.text();
+       *   }
+       * }
+       * ```
+       */
+      createLinkedAbortController(ctx) {
+        const controller = new AbortController();
+        if (ctx?.signal) {
+          if (ctx.signal.aborted) {
+            controller.abort(ctx.signal.reason);
+          } else {
+            ctx.signal.addEventListener(
+              "abort",
+              () => {
+                controller.abort(ctx.signal.reason);
+              },
+              { once: true }
+            );
+          }
+        }
+        return controller;
+      }
       /**
        * Auto-generated instruction text for the LLM.
        * Combines name, description, and parameter schema into a formatted instruction.
@@ -3801,6 +3895,17 @@ var init_agent = __esm({
                 llmOptions = { ...llmOptions, ...action.modifiedOptions };
               }
             }
+            await this.safeObserve(async () => {
+              if (this.hooks.observers?.onLLMCallReady) {
+                const context = {
+                  iteration: currentIteration,
+                  maxIterations: this.maxIterations,
+                  options: llmOptions,
+                  logger: this.logger
+                };
+                await this.hooks.observers.onLLMCallReady(context);
+              }
+            });
             this.logger.info("Calling LLM", { model: this.model });
             this.logger.silly("LLM request details", {
               model: llmOptions.model,