@agentionai/agents 1.6.0 → 1.8.0-beta-0

package/README.md

@@ -27,6 +27,7 @@ Get an API key from your chosen provider:
 - **OpenAI**: [platform.openai.com](https://platform.openai.com/api-keys)
 - **Gemini**: [aistudio.google.com](https://aistudio.google.com/app/apikey)
 - **Mistral**: [console.mistral.ai](https://console.mistral.ai/)
+- **OpenRouter**: [openrouter.ai/keys](https://openrouter.ai/keys) — one key, dozens of upstream providers
 - **Ollama** / **llama.cpp**: no API key needed — run models locally (see [Agents guide](https://docs.agention.ai/guide/agents))
 
 Set it as an environment variable:
@@ -62,6 +63,7 @@ import { ClaudeAgent } from '@agentionai/agents/claude';     // Requires @anthro
 import { OpenAiAgent } from '@agentionai/agents/openai';     // Requires openai
 import { GeminiAgent } from '@agentionai/agents/gemini';     // Requires @google/generative-ai
 import { MistralAgent } from '@agentionai/agents/mistral';   // Requires @mistralai/mistralai
+import { OpenRouterAgent } from '@agentionai/agents/openrouter'; // Requires @openrouter/sdk
 import { OllamaAgent } from '@agentionai/agents/ollama';     // Requires ollama (local, no API key)
 import { LlamaCppAgent } from '@agentionai/agents/llamacpp'; // Requires openai (local, no API key)
 ```
@@ -75,9 +77,9 @@ import { ClaudeAgent, OpenAiAgent } from '@agentionai/agents';
 
 ## Features
 
-- **Multi-Provider, No Lock-in** - Claude, OpenAI, Gemini, Mistral, plus local models via Ollama and llama.cpp—same interface. Switch models with one line. `listModels()` asks any provider what it currently offers, in one shared shape.
+- **Multi-Provider, No Lock-in** - Claude, OpenAI, Gemini, Mistral, OpenRouter (one key, dozens of upstream providers), plus local models via Ollama and llama.cpp—same interface. Switch models with one line. `listModels()` asks any provider what it currently offers, in one shared shape.
 - **Composable Context Management** - Tool result masking (lossless, free) + rolling summarization (auto-firing) + sub-agent delegation (token isolation by architecture).
-- **Streaming** - `executeStream()` on Claude, OpenAI, and all OpenAI-compatible agents. Yields `{ type: "text" | "reasoning" }` chunks; tool calls handled transparently.
+- **Streaming** - `executeStream()` on Claude, OpenAI, OpenRouter, and all OpenAI-compatible agents. Yields `{ type: "text" | "reasoning" }` chunks; tool calls handled transparently.
 - **Built-In Tools** - Use provider-defined server-side tools (e.g. Anthropic's web search, bash, text editor) alongside your own.
 - **Composable, Not Magical** - Agents are objects. Pipelines are arrays. No hidden state, no surprises.
 - **Multimodal / Vision** - Send images alongside text with a unified `MessageContent[]` API across all providers.

package/dist/agents/Agent.d.ts

@@ -6,6 +6,8 @@ import { GeminiAgent } from "./google/GeminiAgent";
 import { MistralAgent } from "./mistral/MistralAgent";
 import { OllamaAgent } from "./ollama/OllamaAgent";
 import { LlamaCppAgent } from "./llamacpp/LlamaCppAgent";
+import { OpenRouterAgent } from "./openrouter/OpenRouterAgent";
+import type { OpenRouterSpecificConfig } from "./AgentConfig";
 import { ClaudeModel, OpenAIModel, GeminiModel, MistralModel, OllamaModel, LlamaCppModel } from "./model-types";
 type ClaudeAgentConfig = Omit<BaseAgentConfig, "vendor" | "model"> & {
     vendor: "anthropic";
@@ -33,9 +35,14 @@ type LlamaCppAgentConfig = Omit<BaseAgentConfig, "vendor" | "model"> & {
     model?: LlamaCppModel;
     baseURL?: string;
 };
-type AgentConfig = ClaudeAgentConfig | OpenAIAgentConfig | GeminiAgentConfig | MistralAgentConfig | OllamaAgentConfig | LlamaCppAgentConfig;
+type OpenRouterAgentConfig = Omit<BaseAgentConfig, "vendor" | "model"> & OpenRouterSpecificConfig & {
+    vendor: "openrouter";
+    model?: string;
+    baseURL?: string;
+};
+type AgentConfig = ClaudeAgentConfig | OpenAIAgentConfig | GeminiAgentConfig | MistralAgentConfig | OllamaAgentConfig | LlamaCppAgentConfig | OpenRouterAgentConfig;
 export declare class Agent {
-    static create(config: AgentConfig, history?: History): ClaudeAgent | GeminiAgent | MistralAgent | OllamaAgent | LlamaCppAgent | OpenAiAgent<(string & {}) | "gpt-5-pro" | "gpt-5.2-pro" | "gpt-5.4-pro" | "gpt-5.5-pro" | "o1" | "o1-pro" | "o3" | "o3-mini" | "o4-mini" | "gpt-5" | "gpt-5-mini" | "gpt-5-nano" | "gpt-5.1" | "gpt-5.2" | "gpt-5.4" | "gpt-5.4-mini" | "gpt-5.4-nano" | "gpt-5.5" | "gpt-5.6" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "gpt-4o" | "gpt-4o-mini" | "gpt-4o-2024-11-20" | "gpt-4o-2024-08-06" | "gpt-4o-2024-05-13" | "gpt-4o-mini-2024-07-18" | "gpt-4-turbo" | "gpt-4-turbo-2024-04-09" | "gpt-4-turbo-preview" | "gpt-4-0125-preview" | "gpt-4-1106-preview" | "gpt-4" | "gpt-4-0613" | "gpt-3.5-turbo" | "gpt-3.5-turbo-0125" | "gpt-3.5-turbo-1106" | "o1-preview" | "o1-mini">;
+    static create(config: AgentConfig, history?: History): ClaudeAgent | GeminiAgent | MistralAgent | OllamaAgent | LlamaCppAgent | OpenRouterAgent | OpenAiAgent<(string & {}) | "gpt-5-pro" | "gpt-5.2-pro" | "gpt-5.4-pro" | "gpt-5.5-pro" | "o1" | "o1-pro" | "o3" | "o3-mini" | "o4-mini" | "gpt-5" | "gpt-5-mini" | "gpt-5-nano" | "gpt-5.1" | "gpt-5.2" | "gpt-5.4" | "gpt-5.4-mini" | "gpt-5.4-nano" | "gpt-5.5" | "gpt-5.6" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "gpt-4o" | "gpt-4o-mini" | "gpt-4o-2024-11-20" | "gpt-4o-2024-08-06" | "gpt-4o-2024-05-13" | "gpt-4o-mini-2024-07-18" | "gpt-4-turbo" | "gpt-4-turbo-2024-04-09" | "gpt-4-turbo-preview" | "gpt-4-0125-preview" | "gpt-4-1106-preview" | "gpt-4" | "gpt-4-0613" | "gpt-3.5-turbo" | "gpt-3.5-turbo-0125" | "gpt-3.5-turbo-1106" | "o1-preview" | "o1-mini">;
 }
 export {};
 //# sourceMappingURL=Agent.d.ts.map

package/dist/agents/Agent.js

@@ -7,6 +7,7 @@ const GeminiAgent_1 = require("./google/GeminiAgent");
 const MistralAgent_1 = require("./mistral/MistralAgent");
 const OllamaAgent_1 = require("./ollama/OllamaAgent");
 const LlamaCppAgent_1 = require("./llamacpp/LlamaCppAgent");
+const OpenRouterAgent_1 = require("./openrouter/OpenRouterAgent");
 class Agent {
     static create(config, history) {
         if (config.vendor === "anthropic") {
@@ -27,6 +28,9 @@ class Agent {
         else if (config.vendor === "llamacpp") {
             return new LlamaCppAgent_1.LlamaCppAgent(config, history);
         }
+        else if (config.vendor === "openrouter") {
+            return new OpenRouterAgent_1.OpenRouterAgent(config, history);
+        }
         else {
             throw new Error("No vendor defined");
         }

package/dist/agents/AgentConfig.d.ts

@@ -2,8 +2,9 @@ import { Tool } from "../tools/Tool";
 import { BuiltInTool } from "../tools/BuiltInTool";
 import { BaseAgent } from "./BaseAgent";
 import type { ReasoningEffort } from "./model-types";
+import type { OpenRouterProviderPreferences, OpenRouterReasoningConfig, OpenRouterRetryConfig } from "./openrouter/types";
 /** Supported LLM vendors */
-export type AgentVendor = "openai" | "anthropic" | "mistral" | "gemini" | "ollama" | "llamacpp";
+export type AgentVendor = "openai" | "anthropic" | "mistral" | "gemini" | "ollama" | "llamacpp" | "openrouter";
 /**
  * Common configuration shared by all agents
  */
@@ -163,6 +164,76 @@ export interface LlamaCppSpecificConfig {
     /** Base URL of the llama.cpp server's OpenAI-compatible API (default: `http://localhost:8080/v1`) */
     baseURL?: string;
 }
+/** Vendor-specific configuration for Cerebras */
+export interface CerebrasSpecificConfig {
+    /** Cerebras OpenAI-compatible API base URL. */
+    baseURL?: string;
+}
+/**
+ * Vendor-specific configuration for OpenRouter
+ *
+ * @see https://openrouter.ai/docs/api-reference/chat/send-a-chat-completion-request
+ */
+export interface OpenRouterSpecificConfig {
+    /**
+     * Fallback models, tried in order when the primary `model` cannot serve the
+     * request — including when it is rate limited.
+     *
+     * This is the one throttling mitigation that works against a `:free` model's
+     * daily quota, which no amount of client-side backoff will wait out. Put a
+     * paid model last if you want the run to finish regardless.
+     *
+     * @example
+     * ```typescript
+     * model: "deepseek/deepseek-chat-v3:free",
+     * vendorConfig: { openrouter: { models: ["qwen/qwen3-235b-a22b", "openai/gpt-5.6"] } }
+     * ```
+     */
+    models?: string[];
+    /** Where OpenRouter may route the request. */
+    provider?: OpenRouterProviderPreferences;
+    /**
+     * Retry policy for the chat request.
+     *
+     * Overriding the SDK's own default is deliberate. `@openrouter/sdk` retries
+     * only `5XX` on this endpoint, so a 429 fails on the first response even
+     * though its backoff already knows how to honour `Retry-After`; and its
+     * default `maxElapsedTime` is an hour. The agent instead retries
+     * `429`/`408`/`409`/`5XX` with a two-minute ceiling. Pass
+     * `{ strategy: "none" }` to opt out entirely and handle 429s yourself.
+     */
+    retry?: OpenRouterRetryConfig;
+    /**
+     * HTTP status codes the retry policy applies to. Accepts exact codes
+     * (`"429"`) and families (`"5XX"`). Defaults to
+     * `["408", "409", "429", "5XX"]`.
+     */
+    retryCodes?: string[];
+    /** Reasoning configuration for models that support it. */
+    reasoning?: OpenRouterReasoningConfig;
+    /**
+     * OpenRouter plugins to enable — web search, file parsing, context
+     * compression, moderation. Passed through untouched; see
+     * https://openrouter.ai/docs/guides/features/plugins for the shapes.
+     */
+    plugins?: unknown[];
+    /**
+     * Sticky routing key. Requests sharing one are pinned to the same upstream
+     * provider, which is what makes prompt caching hit across a conversation.
+     * Also groups the requests in OpenRouter's observability views.
+     */
+    sessionId?: string;
+    /** Stable per-end-user identifier used for abuse isolation. Never forwarded raw. */
+    user?: string;
+    /** Processing tier; `"fast"` is an accepted alias for `"priority"`. */
+    serviceTier?: string;
+    /** Sent as `HTTP-Referer` — how OpenRouter attributes traffic to your app. */
+    httpReferer?: string;
+    /** Sent as `X-Title` — the app name shown on OpenRouter's leaderboards. */
+    appTitle?: string;
+    /** Disable parallel tool calling (sends `parallel_tool_calls: false`). */
+    disableParallelToolUse?: boolean;
+}
 /**
  * Generic vendor-specific configuration container
  * This allows any vendor to add custom config without modifying base types
@@ -174,6 +245,7 @@ export interface VendorSpecificConfig {
     gemini?: GeminiSpecificConfig;
     ollama?: OllamaSpecificConfig;
     llamacpp?: LlamaCppSpecificConfig;
+    openrouter?: OpenRouterSpecificConfig;
 }
 /**
  * Complete agent configuration with vendor-specific extensions
@@ -217,10 +289,12 @@ export type TypedAgentConfig<V extends AgentVendor> = CommonAgentConfig & {
         ollama?: OllamaSpecificConfig;
     } : V extends "llamacpp" ? {
         llamacpp?: LlamaCppSpecificConfig;
+    } : V extends "openrouter" ? {
+        openrouter?: OpenRouterSpecificConfig;
     } : never;
 };
 /**
  * Helper type to extract vendor-specific config for a given vendor
  */
-export type VendorConfigFor<V extends AgentVendor> = V extends "anthropic" ? ClaudeSpecificConfig : V extends "openai" ? OpenAISpecificConfig : V extends "mistral" ? MistralSpecificConfig : V extends "gemini" ? GeminiSpecificConfig : V extends "ollama" ? OllamaSpecificConfig : V extends "llamacpp" ? LlamaCppSpecificConfig : never;
+export type VendorConfigFor<V extends AgentVendor> = V extends "anthropic" ? ClaudeSpecificConfig : V extends "openai" ? OpenAISpecificConfig : V extends "mistral" ? MistralSpecificConfig : V extends "gemini" ? GeminiSpecificConfig : V extends "ollama" ? OllamaSpecificConfig : V extends "llamacpp" ? LlamaCppSpecificConfig : V extends "openrouter" ? OpenRouterSpecificConfig : never;
 //# sourceMappingURL=AgentConfig.d.ts.map

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,11 +213,11 @@ 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") {
-            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens || 1024);
+            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
             this.emit(AgentEvent_1.AgentEvent.ERROR, error);
             // Report error to viz
@@ -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,8 +504,13 @@ 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);
+            const error = new AgentError_1.MaxTokensExceededError("Response exceeded maximum token limit", this.config.maxTokens);
             this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
             this.emit(AgentEvent_1.AgentEvent.ERROR, error);
             if (this.vizEventId) {
@@ -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