@agentionai/agents 1.6.0 → 1.7.0-beta.0

package/dist/agents/BaseAgent.d.ts

@@ -2,8 +2,11 @@ import EventEmitter from "events";
 import { Tool } from "../tools/Tool";
 import { History, HistoryEntry, MessageRole, MessageContent, ImageMimeType } from "../history/History";
 import { AgentVendor, CommonAgentConfig, VendorSpecificConfig } from "./AgentConfig";
+import { AbortError } from "./errors/AgentError";
+import { ExecuteOptions } from "./cancellation";
 export type { HistoryEntry, MessageRole, MessageContent, ImageMimeType };
 export type { AgentVendor };
+export type { ExecuteOptions };
 /**
  * Agent config as used across all agents
  * @deprecated Use CommonAgentConfig with vendorConfig instead
@@ -173,9 +176,16 @@ export declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> ext
      *
      */
     constructor(config: BaseAgentConfig, history?: History);
-    abstract execute(input: TInput): Promise<TOutput>;
+    /**
+     * Run the agent on `input`.
+     *
+     * @param options Per-run options. `options.signal` cancels the run: the
+     *                in-flight provider request is aborted and the promise
+     *                rejects with an {@link AbortError}.
+     */
+    abstract execute(input: TInput, options?: ExecuteOptions): Promise<TOutput>;
     protected abstract process(input: TInput): Promise<TOutput>;
-    protected abstract handleResponse(response: unknown): Promise<unknown>;
+    protected abstract handleResponse(response: unknown, options?: ExecuteOptions): Promise<unknown>;
     protected getToolDefinitions(): unknown[];
     /**
      * List the models the provider currently offers, straight from its models
@@ -220,6 +230,18 @@ export declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> ext
     getHistoryEntries(): HistoryEntry[];
     getTools(): Tool<unknown>[];
     clearHistory(): void;
+    /**
+     * Build the {@link AbortError} for a cancelled run and emit it as an
+     * `AgentEvent.ERROR`, so a cancellation reaches error listeners the same way
+     * every other failure does.
+     *
+     * Returns the error rather than throwing it, leaving the caller to report it
+     * to whatever visualization event is open before rethrowing.
+     *
+     * @param error  What the provider threw once the signal fired.
+     * @param signal The signal supplied to this run, if any.
+     */
+    protected abortError(error: unknown, signal?: AbortSignal): AbortError;
     protected abstract parseUsage(input: unknown): TokenUsage;
     /**
      * Clear accumulated usage. Called at the start of every `execute()` /

package/dist/agents/BaseAgent.js

@@ -8,6 +8,7 @@ const events_1 = __importDefault(require("events"));
 const Tool_1 = require("../tools/Tool");
 const History_1 = require("../history/History");
 const AgentError_1 = require("./errors/AgentError");
+const AgentEvent_1 = require("./AgentEvent");
 /**
  * The base agent is what the other agents are inheriting from
  * Handles the BaseConfig
@@ -136,6 +137,22 @@ class BaseAgent extends events_1.default {
     clearHistory() {
         this.history.clear();
     }
+    /**
+     * Build the {@link AbortError} for a cancelled run and emit it as an
+     * `AgentEvent.ERROR`, so a cancellation reaches error listeners the same way
+     * every other failure does.
+     *
+     * Returns the error rather than throwing it, leaving the caller to report it
+     * to whatever visualization event is open before rethrowing.
+     *
+     * @param error  What the provider threw once the signal fired.
+     * @param signal The signal supplied to this run, if any.
+     */
+    abortError(error, signal) {
+        const abortError = new AgentError_1.AbortError(`Execution of agent ${this.getName()} was aborted`, signal?.reason ?? error);
+        this.emit(AgentEvent_1.AgentEvent.ERROR, abortError);
+        return abortError;
+    }
     /**
      * Clear accumulated usage. Called at the start of every `execute()` /
      * `executeStream()` so `lastTokenUsage` describes a single execution.

package/dist/agents/anthropic/ClaudeAgent.d.ts

@@ -3,6 +3,7 @@ import { Message, type ModelInfo as AnthropicModelInfo, ToolUnion, Usage } from
 import { type ToolDefinition } from "../../tools/Tool";
 import { type BuiltInTool } from "../../tools/BuiltInTool";
 import { BaseAgent, BaseAgentConfig, ModelInfo, TokenUsage } from "../BaseAgent";
+import { ExecuteOptions } from "../cancellation";
 import { History, MessageContent } from "../../history/History";
 import { StreamChunk } from "../openai-compatible/OpenAICompatibleAgent";
 import { ClaudeModel } from "../model-types";
@@ -151,8 +152,8 @@ export declare class ClaudeAgent extends BaseAgent {
         metadata: Record<string, string> | undefined;
     };
     protected process(_input: string): Promise<string>;
-    execute(input: string | MessageContent[]): Promise<string>;
-    protected handleResponse(response: Message): Promise<string>;
+    execute(input: string | MessageContent[], options?: ExecuteOptions): Promise<string>;
+    protected handleResponse(response: Message, options?: ExecuteOptions): Promise<string>;
     private handleToolUse;
     /**
      * Stream a response as an async generator of `StreamChunk` objects.
@@ -168,7 +169,7 @@ export declare class ClaudeAgent extends BaseAgent {
      * }
      * ```
      */
-    executeStream(input: string | MessageContent[]): AsyncGenerator<StreamChunk>;
+    executeStream(input: string | MessageContent[], options?: ExecuteOptions): AsyncGenerator<StreamChunk>;
     private streamTurn;
     protected parseUsage(input: Usage): TokenUsage;
 }

package/dist/agents/anthropic/ClaudeAgent.js

@@ -4,6 +4,7 @@ exports.ClaudeAgent = void 0;
 const sdk_1 = require("@anthropic-ai/sdk");
 const BaseAgent_1 = require("../BaseAgent");
 const AgentEvent_1 = require("../AgentEvent");
+const cancellation_1 = require("../cancellation");
 const AgentError_1 = require("../errors/AgentError");
 const History_1 = require("../../history/History");
 const transformers_1 = require("../../history/transformers");
@@ -143,7 +144,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
     async process(_input) {
         return "";
     }
-    async execute(input) {
+    async execute(input, options) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
         // Reset token usage for this execution
         this.resetTokenUsage();
@@ -173,11 +174,19 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         this.history.beginExecution();
         try {
             this.startTurnTimer();
-            const response = (await this.client.messages.create(this.buildMessageParams()));
+            const response = (await this.client.messages.create(this.buildMessageParams(), { signal: options?.signal }));
             this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, response);
-            return await this.handleResponse(response);
+            return await this.handleResponse(response, options);
         }
         catch (error) {
+            if ((0, cancellation_1.isAbortError)(error, options?.signal)) {
+                const abortError = this.abortError(error, options?.signal);
+                if (this.vizEventId) {
+                    VizReporter_1.vizReporter.agentError(this.vizEventId, "AbortError", abortError.message, false);
+                    this.vizEventId = undefined;
+                }
+                throw abortError;
+            }
             if (error instanceof sdk_1.APIError) {
                 const apiError = new AgentError_1.ApiError(`Anthropic API error: ${error.message}`, error.status, error);
                 this.emit(AgentEvent_1.AgentEvent.ERROR, apiError);
@@ -204,7 +213,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
             this.history.endExecution();
         }
     }
-    async handleResponse(response) {
+    async handleResponse(response, options) {
         // Store token usage for metrics tracking
         const usage = this.accumulateUsage(this.parseUsage(response.usage));
         if (response.stop_reason === "max_tokens") {
@@ -253,19 +262,24 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         }
         else if (response.stop_reason === "tool_use") {
             try {
+                // Stop before the assistant turn is written: nothing else would notice
+                // a cancellation until the next provider call, and bailing out here
+                // avoids both running the tools' side effects and leaving a tool_use
+                // in history with no tool_result to answer it.
+                (0, cancellation_1.throwIfAborted)(options?.signal, `Execution of agent ${this.getName()}`);
                 this.emit(AgentEvent_1.AgentEvent.TOOL_USE, response.content);
                 // Add assistant response to history (normalized format)
                 const assistantEntry = transformers_1.anthropicTransformer.fromProviderContent("assistant", response.content);
                 this.addToHistory(assistantEntry);
-                const toolResults = await this.handleToolUse(response.content);
+                const toolResults = await this.handleToolUse(response.content, options);
                 // Add tool results to history (normalized format)
                 this.addMessageToHistory("user", toolResults);
                 // Continue conversation with tool results
                 try {
                     this.startTurnTimer();
-                    const newResponse = (await this.client.messages.create(this.buildMessageParams()));
+                    const newResponse = (await this.client.messages.create(this.buildMessageParams(), { signal: options?.signal }));
                     this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
-                    return this.handleResponse(newResponse);
+                    return this.handleResponse(newResponse, options);
                 }
                 catch (error) {
                     if (error instanceof sdk_1.APIError) {
@@ -292,7 +306,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         this.emit(AgentEvent_1.AgentEvent.ERROR, error);
         throw error;
     }
-    async handleToolUse(content) {
+    async handleToolUse(content, options) {
         const toolUseBlocks = content.filter((block) => block.type === "tool_use");
         if (!toolUseBlocks.length) {
             throw new AgentError_1.ExecutionError("No tool use blocks found in content");
@@ -323,7 +337,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                 ? VizReporter_1.vizReporter.toolStart(block.name, block.id, block.input, agentSource)
                 : undefined;
             try {
-                const result = await tool.execute(this.getId(), this.getName(), block.input, block.id, this.config.model, "anthropic");
+                const result = await tool.execute(this.getId(), this.getName(), block.input, block.id, this.config.model, "anthropic", { signal: options?.signal });
                 if (vizEventId) {
                     VizReporter_1.vizReporter.toolComplete(vizEventId, block.name, block.id, true, result);
                 }
@@ -358,7 +372,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
      * }
      * ```
      */
-    async *executeStream(input) {
+    async *executeStream(input, options) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
         this.resetTokenUsage();
         this.currentToolCallCount = 0;
@@ -379,9 +393,17 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         this.history.setSessionAnchor();
         this.history.beginExecution();
         try {
-            yield* this.streamTurn();
+            yield* this.streamTurn(options);
         }
         catch (error) {
+            if ((0, cancellation_1.isAbortError)(error, options?.signal)) {
+                const abortError = this.abortError(error, options?.signal);
+                if (this.vizEventId) {
+                    VizReporter_1.vizReporter.agentError(this.vizEventId, "AbortError", abortError.message, false);
+                    this.vizEventId = undefined;
+                }
+                throw abortError;
+            }
             if (error instanceof sdk_1.APIError) {
                 const apiError = new AgentError_1.ApiError(`Anthropic API error: ${error.message}`, error.status, error);
                 this.emit(AgentEvent_1.AgentEvent.ERROR, apiError);
@@ -409,12 +431,12 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
             this.history.endExecution();
         }
     }
-    async *streamTurn() {
+    async *streamTurn(options) {
         this.startTurnTimer();
         const stream = await this.client.messages.create({
             ...this.buildMessageParams(),
             stream: true,
-        });
+        }, { signal: options?.signal });
         const blocks = new Map();
         let textContent = "";
         let stopReason = null;
@@ -482,6 +504,11 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
             output_tokens: outputTokens,
             total_tokens: inputTokens + outputTokens,
         });
+        // The SDK's stream iterator swallows the abort and simply stops yielding,
+        // so without this an interrupted stream would look like a short but
+        // complete turn — writing partial text to history and emitting DONE.
+        // Checked after accumulateUsage() so the tokens already spent are reported.
+        (0, cancellation_1.throwIfAborted)(options?.signal, `Execution of agent ${this.getName()}`);
         if (stopReason === "max_tokens") {
             const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 1024);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
@@ -518,13 +545,16 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         }
         const toolUseBlocks = orderedBlocks.filter((b) => b.type === "tool_use");
         if (stopReason === "tool_use" && toolUseBlocks.length > 0) {
+            // As in handleResponse(): bail out before the assistant turn is written,
+            // so a cancelled run leaves no unanswered tool_use in history.
+            (0, cancellation_1.throwIfAborted)(options?.signal, `Execution of agent ${this.getName()}`);
             this.emit(AgentEvent_1.AgentEvent.TOOL_USE, orderedBlocks);
             this.currentToolCallCount += toolUseBlocks.length;
             const assistantEntry = transformers_1.anthropicTransformer.fromProviderContent("assistant", orderedBlocks);
             this.addToHistory(assistantEntry);
-            const toolResults = await this.handleToolUse(orderedBlocks);
+            const toolResults = await this.handleToolUse(orderedBlocks, options);
             this.addMessageToHistory("user", toolResults);
-            yield* this.streamTurn();
+            yield* this.streamTurn(options);
         }
         else {
             const assistantEntry = transformers_1.anthropicTransformer.fromProviderContent("assistant", orderedBlocks);

package/dist/agents/cancellation.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Options accepted by every agent's `execute()` and `executeStream()`.
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ * setTimeout(() => controller.abort(), 5_000);
+ *
+ * try {
+ *   await agent.execute("Write an essay", { signal: controller.signal });
+ * } catch (error) {
+ *   if (error instanceof AbortError) console.log("cancelled");
+ * }
+ * ```
+ */
+export interface ExecuteOptions {
+    /**
+     * Cancels the run. The in-flight provider request is aborted, no further
+     * requests or tools are started, and the call rejects with an
+     * {@link AbortError}. History already written by the run is left in place, so
+     * a non-transient agent keeps whatever turns completed before the abort.
+     */
+    signal?: AbortSignal;
+}
+/** Options passed to a tool's `execute`, carrying the current run's signal. */
+export interface ToolExecuteOptions {
+    /** The `AbortSignal` of the agent run this tool call belongs to. */
+    signal?: AbortSignal;
+}
+/**
+ * Whether an error represents a cancellation rather than a genuine failure.
+ *
+ * The signal is authoritative: once it has fired, whatever the provider threw
+ * on the way out is a consequence of the abort — including errors an agent
+ * wrapped in `ExecutionError` before it reached the top-level handler. The
+ * error's own `name` is only consulted when no aborted signal was supplied.
+ */
+export declare function isAbortError(error: unknown, signal?: AbortSignal): boolean;
+/**
+ * Throw an {@link AbortError} if the signal has already fired.
+ *
+ * Used at the points between provider calls where nothing would otherwise
+ * notice the cancellation — before starting tool execution in particular, so a
+ * cancelled run does not fire off side effects it will never use.
+ */
+export declare function throwIfAborted(signal: AbortSignal | undefined, context: string): void;
+/**
+ * Combine two optional signals into one that fires as soon as either does.
+ *
+ * Returns the other signal unchanged when only one is present, and `undefined`
+ * when neither is. Written by hand rather than with `AbortSignal.any`, which
+ * needs Node 20.
+ */
+export declare function combineSignals(a?: AbortSignal, b?: AbortSignal): AbortSignal | undefined;
+//# sourceMappingURL=cancellation.d.ts.map

package/dist/agents/cancellation.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAbortError = isAbortError;
+exports.throwIfAborted = throwIfAborted;
+exports.combineSignals = combineSignals;
+const AgentError_1 = require("./errors/AgentError");
+/**
+ * The `name` each provider SDK gives its cancellation error. Checked as a
+ * fallback for the case where the caller's own signal is not the one that
+ * fired — a client-level timeout, for instance.
+ */
+const ABORT_ERROR_NAMES = new Set([
+    "AbortError", // fetch / DOMException, ollama, and our own AbortError
+    "APIUserAbortError", // @anthropic-ai/sdk, openai
+    "RequestAbortedError", // @mistralai/mistralai
+    "GoogleGenerativeAIAbortError", // @google/generative-ai
+]);
+/**
+ * Whether an error represents a cancellation rather than a genuine failure.
+ *
+ * The signal is authoritative: once it has fired, whatever the provider threw
+ * on the way out is a consequence of the abort — including errors an agent
+ * wrapped in `ExecutionError` before it reached the top-level handler. The
+ * error's own `name` is only consulted when no aborted signal was supplied.
+ */
+function isAbortError(error, signal) {
+    if (signal?.aborted)
+        return true;
+    const name = error?.name;
+    return typeof name === "string" && ABORT_ERROR_NAMES.has(name);
+}
+/**
+ * Throw an {@link AbortError} if the signal has already fired.
+ *
+ * Used at the points between provider calls where nothing would otherwise
+ * notice the cancellation — before starting tool execution in particular, so a
+ * cancelled run does not fire off side effects it will never use.
+ */
+function throwIfAborted(signal, context) {
+    if (!signal?.aborted)
+        return;
+    throw new AgentError_1.AbortError(`${context} was aborted`, signal.reason);
+}
+/**
+ * Combine two optional signals into one that fires as soon as either does.
+ *
+ * Returns the other signal unchanged when only one is present, and `undefined`
+ * when neither is. Written by hand rather than with `AbortSignal.any`, which
+ * needs Node 20.
+ */
+function combineSignals(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    if (a.aborted)
+        return a;
+    if (b.aborted)
+        return b;
+    const controller = new AbortController();
+    const abort = (source) => () => controller.abort(source.reason);
+    const onA = abort(a);
+    const onB = abort(b);
+    a.addEventListener("abort", onA, { once: true });
+    b.addEventListener("abort", onB, { once: true });
+    controller.signal.addEventListener("abort", () => {
+        a.removeEventListener("abort", onA);
+        b.removeEventListener("abort", onB);
+    }, { once: true });
+    return controller.signal;
+}
+//# sourceMappingURL=cancellation.js.map

package/dist/agents/errors/AgentError.d.ts

@@ -36,6 +36,22 @@ export declare class MaxRetriesExceededError extends AgentError {
     maxRetries: number;
     constructor(message: string, maxRetries: number);
 }
+/**
+ * Error thrown when an execution is cancelled through the `AbortSignal` passed
+ * to `execute()` / `executeStream()`.
+ *
+ * `name` is `"AbortError"`, matching the platform convention, so callers that
+ * already check `err.name === "AbortError"` keep working.
+ */
+export declare class AbortError extends AgentError {
+    reason?: unknown | undefined;
+    /**
+     * @param message Error message
+     * @param reason The signal's `reason`, or the underlying provider error when
+     *               the signal did not carry one.
+     */
+    constructor(message: string, reason?: unknown | undefined);
+}
 /**
  * Error thrown when tool execution fails
  */

package/dist/agents/errors/AgentError.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ToolExecutionError = exports.MaxRetriesExceededError = exports.MaxTokensExceededError = exports.ApiError = exports.ExecutionError = exports.AgentError = void 0;
+exports.ToolExecutionError = exports.AbortError = exports.MaxRetriesExceededError = exports.MaxTokensExceededError = exports.ApiError = exports.ExecutionError = exports.AgentError = void 0;
 /**
  * Base error class for all agent-related errors
  */
@@ -59,6 +59,26 @@ class MaxRetriesExceededError extends AgentError {
     }
 }
 exports.MaxRetriesExceededError = MaxRetriesExceededError;
+/**
+ * Error thrown when an execution is cancelled through the `AbortSignal` passed
+ * to `execute()` / `executeStream()`.
+ *
+ * `name` is `"AbortError"`, matching the platform convention, so callers that
+ * already check `err.name === "AbortError"` keep working.
+ */
+class AbortError extends AgentError {
+    /**
+     * @param message Error message
+     * @param reason The signal's `reason`, or the underlying provider error when
+     *               the signal did not carry one.
+     */
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = "AbortError";
+    }
+}
+exports.AbortError = AbortError;
 /**
  * Error thrown when tool execution fails
  */

package/dist/agents/google/GeminiAgent.d.ts

@@ -1,5 +1,6 @@
 import { FunctionDeclarationsTool, GenerateContentResult, Schema } from "@google/generative-ai";
 import { BaseAgent, BaseAgentConfig, ModelInfo, TokenUsage } from "../BaseAgent";
+import { ExecuteOptions } from "../cancellation";
 import { History, MessageContent } from "../../history/History";
 import { GeminiModel } from "../model-types";
 /**
@@ -123,8 +124,8 @@ export declare class GeminiAgent extends BaseAgent {
      */
     private mapJsonSchemaTypeToGemini;
     protected process(_input: string): Promise<string>;
-    execute(input: string | MessageContent[]): Promise<string>;
-    protected handleResponse(response: GenerateContentResult): Promise<string>;
+    execute(input: string | MessageContent[], options?: ExecuteOptions): Promise<string>;
+    protected handleResponse(response: GenerateContentResult, options?: ExecuteOptions): Promise<string>;
     private handleFunctionCalls;
     protected parseUsage(input: {
         promptTokenCount?: number;

package/dist/agents/google/GeminiAgent.js

@@ -4,6 +4,7 @@ exports.GeminiAgent = exports.GEMINI_RETIRED_MODELS = void 0;
 const generative_ai_1 = require("@google/generative-ai");
 const BaseAgent_1 = require("../BaseAgent");
 const AgentEvent_1 = require("../AgentEvent");
+const cancellation_1 = require("../cancellation");
 const AgentError_1 = require("../errors/AgentError");
 const transformers_1 = require("../../history/transformers");
 const VizReporter_1 = require("../../viz/VizReporter");
@@ -251,7 +252,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
     async process(_input) {
         return "";
     }
-    async execute(input) {
+    async execute(input, options) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
         // Reset token usage for this execution
         this.resetTokenUsage();
@@ -297,11 +298,23 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
                     responseMimeType: this.config.responseMimeType,
                     responseSchema: this.config.responseSchema,
                 },
-            });
+            }, 
+            // Note: an abort only stops the client from waiting — Google still
+            // runs and bills the request. Merged over the model's own request
+            // options, so `customHeaders` set at construction survive.
+            { signal: options?.signal });
             this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, response);
-            return await this.handleResponse(response);
+            return await this.handleResponse(response, options);
         }
         catch (error) {
+            if ((0, cancellation_1.isAbortError)(error, options?.signal)) {
+                const abortError = this.abortError(error, options?.signal);
+                if (this.vizEventId) {
+                    VizReporter_1.vizReporter.agentError(this.vizEventId, "AbortError", abortError.message, false);
+                    this.vizEventId = undefined;
+                }
+                throw abortError;
+            }
             const err = error;
             if (err.status) {
                 const apiError = new AgentError_1.ApiError(`Gemini API error: ${err.message || "Unknown error"}`, err.status, error);
@@ -328,7 +341,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
             this.history.endExecution();
         }
     }
-    async handleResponse(response) {
+    async handleResponse(response, options) {
         const result = response.response;
         // Parse and track usage
         if (result.usageMetadata) {
@@ -377,11 +390,16 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
         }
         // Handle function calls
         try {
+            // Stop before the assistant turn is written: nothing else would notice a
+            // cancellation until the next provider call, and bailing out here avoids
+            // both running the tools' side effects and leaving a functionCall in
+            // history with no functionResponse to answer it.
+            (0, cancellation_1.throwIfAborted)(options?.signal, `Execution of agent ${this.getName()}`);
             this.emit(AgentEvent_1.AgentEvent.TOOL_USE, functionCalls);
             // Add assistant response with function calls to history (normalized)
             const assistantEntry = transformers_1.geminiTransformer.fromProviderContent("assistant", parts);
             this.addToHistory(assistantEntry);
-            const toolResults = await this.handleFunctionCalls(functionCalls);
+            const toolResults = await this.handleFunctionCalls(functionCalls, options);
             // Add tool results to history (normalized)
             for (const tr of toolResults) {
                 const resultEntry = transformers_1.geminiTransformer.toolResultEntry(tr.name, tr.response);
@@ -407,9 +425,9 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
                         responseMimeType: this.config.responseMimeType,
                         responseSchema: this.config.responseSchema,
                     },
-                });
+                }, { signal: options?.signal });
                 this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
-                return this.handleResponse(newResponse);
+                return this.handleResponse(newResponse, options);
             }
             catch (error) {
                 const err = error;
@@ -438,7 +456,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
             throw toolError;
         }
     }
-    async handleFunctionCalls(functionCalls) {
+    async handleFunctionCalls(functionCalls, options) {
         if (!functionCalls.length) {
             throw new AgentError_1.ExecutionError("No function calls found in response");
         }
@@ -462,7 +480,7 @@ class GeminiAgent extends BaseAgent_1.BaseAgent {
             try {
                 const args = (fc.args || {});
                 const result = await tool.execute(this.getId(), this.getName(), args, toolName, // Gemini uses function name as ID
-                this.config.model, "gemini");
+                this.config.model, "gemini", { signal: options?.signal });
                 return {
                     name: toolName,
                     response: JSON.stringify(result),

package/dist/agents/mistral/MistralAgent.d.ts

@@ -1,4 +1,5 @@
 import { BaseAgent, BaseAgentConfig, ModelInfo, TokenUsage } from "../BaseAgent";
+import { ExecuteOptions } from "../cancellation";
 import { History, MessageContent } from "../../history/History";
 import { ChatCompletionResponse, ModelList, Tool, UsageInfo } from "@mistralai/mistralai/models/components";
 import { MistralModel } from "../model-types";
@@ -66,8 +67,8 @@ export declare class MistralAgent extends BaseAgent {
     listModels(): Promise<ModelInfo<MistralModelCard>[]>;
     protected getToolDefinitions(): Tool[];
     protected process(_input: string): Promise<string>;
-    execute(input: string | MessageContent[]): Promise<string>;
-    protected handleResponse(response: ChatCompletionResponse): Promise<string>;
+    execute(input: string | MessageContent[], options?: ExecuteOptions): Promise<string>;
+    protected handleResponse(response: ChatCompletionResponse, options?: ExecuteOptions): Promise<string>;
     private handleToolCalls;
     protected parseUsage(input: UsageInfo): TokenUsage;
 }