@agentionai/agents 1.6.0 → 1.8.0-beta-0

package/dist/agents/openai/OpenAiAgent.d.ts

@@ -1,4 +1,5 @@
 import { BaseAgent, BaseAgentConfig, ModelInfo, TokenUsage } from "../BaseAgent";
+import { ExecuteOptions } from "../cancellation";
 import { History, MessageContent } from "../../history/History";
 import { Tool, Response, ResponseUsage } from "openai/resources/responses/responses";
 import type { Model as OpenAIModelCard } from "openai/resources/models";
@@ -95,8 +96,8 @@ export declare class OpenAiAgent<M extends OpenAIModel = OpenAIModel> extends Ba
      */
     private buildReasoningParams;
     protected process(_input: string): Promise<string>;
-    execute(input: string | MessageContent[]): Promise<string>;
-    protected handleResponse(response: Response): Promise<string>;
+    execute(input: string | MessageContent[], options?: ExecuteOptions): Promise<string>;
+    protected handleResponse(response: Response, options?: ExecuteOptions): Promise<string>;
     private handleToolUse;
     /**
      * Stream a response as an async generator of `StreamChunk` objects.
@@ -110,7 +111,7 @@ export declare class OpenAiAgent<M extends OpenAIModel = OpenAIModel> extends Ba
      * }
      * ```
      */
-    executeStream(input: string | MessageContent[]): AsyncGenerator<StreamChunk>;
+    executeStream(input: string | MessageContent[], options?: ExecuteOptions): AsyncGenerator<StreamChunk>;
     private streamTurn;
     protected parseUsage(input: ResponseUsage): TokenUsage;
 }

package/dist/agents/openai/OpenAiAgent.js

@@ -8,6 +8,7 @@ exports.lowestReasoningEffort = lowestReasoningEffort;
 const openai_1 = __importDefault(require("openai"));
 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");
@@ -72,7 +73,13 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         const user = config.user ?? vendorConfig.user;
         this.config = {
             model: config.model || "gpt-4.1-mini",
-            maxTokens: config.maxTokens || 1024,
+            // No default. `max_output_tokens` is optional on the Responses API, and
+            // omitting it lets the model use its full output budget. A default here
+            // silently truncated every response — and on reasoning models it was
+            // worse than a truncation, since reasoning tokens count against the same
+            // budget: a small cap could be spent entirely on thinking, returning
+            // `status: "incomplete"` with no text at all.
+            maxTokens: config.maxTokens,
             disableParallelToolUse,
             disableReasoning,
             reasoningEffort,
@@ -163,7 +170,7 @@ class OpenAiAgent 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();
@@ -204,11 +211,19 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 // Note: Responses API doesn't support seed, presence_penalty, frequency_penalty, stop
                 user: this.config.user,
                 ...this.buildReasoningParams(),
-            });
+            }, { 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 && typeof error === "object" && "error" in error) {
                 const openAIError = error;
                 const apiError = new AgentError_1.ApiError(`OpenAI API error: ${openAIError.error.message || "Unknown error"}`, openAIError.status, openAIError.error);
@@ -239,7 +254,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             this.history.endExecution();
         }
     }
-    async handleResponse(response) {
+    async handleResponse(response, options) {
         if (!response.output || !response.output.length) {
             const error = new AgentError_1.ExecutionError("Invalid response format: missing output");
             this.emit(AgentEvent_1.AgentEvent.ERROR, error);
@@ -288,6 +303,11 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         }
         else if (toolCalls.length) {
             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 function
+                // call in history with no output to answer it.
+                (0, cancellation_1.throwIfAborted)(options?.signal, `Execution of agent ${this.getName()}`);
                 // Add assistant message with tool calls to history (normalized)
                 const functionCalls = toolCalls.map((tc) => ({
                     id: tc.id || tc.call_id,
@@ -297,7 +317,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 }));
                 const assistantEntry = transformers_1.openAiTransformer.fromProviderMessage("assistant", response.output_text || "", functionCalls);
                 this.addToHistory(assistantEntry);
-                const toolResponses = await this.handleToolUse(toolCalls);
+                const toolResponses = await this.handleToolUse(toolCalls, options);
                 // Add tool results to history (normalized)
                 for (const result of toolResponses) {
                     const resultEntry = transformers_1.openAiTransformer.toolResultEntry(result.call_id, result.output, false);
@@ -318,9 +338,9 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                         // Note: Responses API doesn't support seed, presence_penalty, frequency_penalty, stop
                         user: this.config.user,
                         ...this.buildReasoningParams(),
-                    });
+                    }, { signal: options?.signal });
                     this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
-                    return this.handleResponse(newResponse);
+                    return this.handleResponse(newResponse, options);
                 }
                 catch (error) {
                     if (error && typeof error === "object" && "error" in error) {
@@ -358,7 +378,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             throw error;
         }
     }
-    async handleToolUse(content) {
+    async handleToolUse(content, options) {
         if (!content || !content.length) {
             throw new AgentError_1.ExecutionError("Invalid tool calls content");
         }
@@ -389,7 +409,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 catch (parseError) {
                     throw new AgentError_1.ToolExecutionError(`Invalid tool arguments: ${parseError instanceof Error ? parseError.message : "Parse error"}`, toolName, toolCall.arguments);
                 }
-                const result = await tool.execute(this.getId(), this.getName(), toolArgs, toolCall.id || "", this.config.model, "openai");
+                const result = await tool.execute(this.getId(), this.getName(), toolArgs, toolCall.id || "", this.config.model, "openai", { signal: options?.signal });
                 return {
                     call_id: toolCall.call_id,
                     output: JSON.stringify(result),
@@ -422,7 +442,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
      * }
      * ```
      */
-    async *executeStream(input) {
+    async *executeStream(input, options) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
         this.resetTokenUsage();
         this.currentToolCallCount = 0;
@@ -443,9 +463,17 @@ class OpenAiAgent 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 AgentError_1.AgentError) {
                 this.emit(AgentEvent_1.AgentEvent.ERROR, error);
                 if (this.vizEventId) {
@@ -476,7 +504,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             this.history.endExecution();
         }
     }
-    async *streamTurn() {
+    async *streamTurn(options) {
         const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
         this.startTurnTimer();
         const stream = await this.client.responses.create({
@@ -490,7 +518,7 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             top_p: this.config.topP,
             user: this.config.user,
             ...this.buildReasoningParams("auto"),
-        });
+        }, { signal: options?.signal });
         let completedEvent = null;
         for await (const event of stream) {
             if (event.type === "response.output_text.delta") {
@@ -510,15 +538,22 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
                 }
             }
             if (event.type === "response.incomplete") {
-                throw new AgentError_1.MaxTokensExceededError("Response incomplete: max tokens reached", this.config.maxTokens || 1024);
+                throw new AgentError_1.MaxTokensExceededError("Response incomplete: max tokens reached", this.config.maxTokens);
             }
         }
+        // The SDK's stream iterator swallows the abort and simply stops yielding.
+        // Without this the turn would fail as a malformed stream instead of a
+        // cancellation — checked here so the tokens already spent are reported.
+        (0, cancellation_1.throwIfAborted)(options?.signal, `Execution of agent ${this.getName()}`);
         if (!completedEvent) {
             throw new AgentError_1.ExecutionError("OpenAI stream ended without a completed event");
         }
         const response = completedEvent.response;
         const toolCalls = response.output.filter((o) => o.type === "function_call");
         if (toolCalls.length > 0) {
+            // As in handleResponse(): bail out before the assistant turn is written,
+            // so a cancelled run leaves no unanswered function call in history.
+            (0, cancellation_1.throwIfAborted)(options?.signal, `Execution of agent ${this.getName()}`);
             this.emit(AgentEvent_1.AgentEvent.TOOL_USE, toolCalls);
             this.currentToolCallCount += toolCalls.length;
             const functionCalls = toolCalls.map((tc) => ({
@@ -529,11 +564,11 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
             }));
             const assistantEntry = transformers_1.openAiTransformer.fromProviderMessage("assistant", response.output_text || "", functionCalls);
             this.addToHistory(assistantEntry);
-            const toolResults = await this.handleToolUse(toolCalls);
+            const toolResults = await this.handleToolUse(toolCalls, options);
             for (const result of toolResults) {
                 this.addToHistory(transformers_1.openAiTransformer.toolResultEntry(result.call_id, result.output, false));
             }
-            yield* this.streamTurn();
+            yield* this.streamTurn(options);
         }
         else {
             const textContent = response.output_text || "";

package/dist/agents/openai-compatible/OpenAICompatibleAgent.d.ts

@@ -3,6 +3,7 @@ import { ChatCompletion, ChatCompletionTool } from "openai/resources/chat/comple
 import { Model } from "openai/resources/models";
 import { BaseAgent, BaseAgentConfig, ModelInfo, TokenUsage } from "../BaseAgent";
 import { AgentVendor } from "../AgentConfig";
+import { ExecuteOptions } from "../cancellation";
 import { History, MessageContent } from "../../history/History";
 /**
  * A single chunk yielded by `executeStream()`.
@@ -50,9 +51,9 @@ export declare abstract class OpenAICompatibleAgent extends BaseAgent {
     listModels(): Promise<ModelInfo<Model>[]>;
     protected getToolDefinitions(): ChatCompletionTool[];
     protected process(_input: string): Promise<string>;
-    execute(input: string | MessageContent[]): Promise<string>;
+    execute(input: string | MessageContent[], options?: ExecuteOptions): Promise<string>;
     private callProvider;
-    protected handleResponse(response: ChatCompletion): Promise<string>;
+    protected handleResponse(response: ChatCompletion, options?: ExecuteOptions): Promise<string>;
     private handleToolCalls;
     /**
      * Stream a response as an async generator of `StreamChunk` objects.
@@ -69,7 +70,7 @@ export declare abstract class OpenAICompatibleAgent extends BaseAgent {
      * }
      * ```
      */
-    executeStream(input: string | MessageContent[]): AsyncGenerator<StreamChunk>;
+    executeStream(input: string | MessageContent[], options?: ExecuteOptions): AsyncGenerator<StreamChunk>;
     private streamTurn;
     private accumulateStreamUsage;
     protected parseUsage(response: ChatCompletion): TokenUsage;

package/dist/agents/openai-compatible/OpenAICompatibleAgent.js

@@ -7,6 +7,7 @@ exports.OpenAICompatibleAgent = void 0;
 const openai_1 = __importDefault(require("openai"));
 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");
@@ -84,7 +85,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
     async process(_input) {
         return "";
     }
-    async execute(input) {
+    async execute(input, options) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
         this.resetTokenUsage();
         this.currentToolCallCount = 0;
@@ -105,11 +106,19 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
         this.history.setSessionAnchor();
         this.history.beginExecution();
         try {
-            const response = await this.callProvider();
+            const response = await this.callProvider(options);
             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 openai_1.default.APIError) {
                 const apiError = new AgentError_1.ApiError(`${this.getVendorName()} API error: ${error.message}`, error.status, error);
                 this.emit(AgentEvent_1.AgentEvent.ERROR, apiError);
@@ -139,7 +148,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             this.history.endExecution();
         }
     }
-    async callProvider() {
+    async callProvider(options) {
         const messages = transformers_1.chatCompletionsTransformer.toProvider(this.history.getEntries());
         const tools = this.tools.size > 0 ? this.getToolDefinitions() : undefined;
         this.startTurnTimer();
@@ -156,14 +165,14 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             presence_penalty: this.config.presencePenalty,
             frequency_penalty: this.config.frequencyPenalty,
             ...this.buildExtraRequestParams(),
-        });
+        }, { signal: options?.signal });
     }
-    async handleResponse(response) {
+    async handleResponse(response, options) {
         const usage = this.accumulateUsage(this.parseUsage(response));
         const choice = response.choices[0];
         const message = choice.message;
         if (choice.finish_reason === "length") {
-            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) {
@@ -189,19 +198,24 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             return textContent;
         }
         const toolCalls = message.tool_calls;
+        // 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 call in history
+        // with no tool message to answer it.
+        (0, cancellation_1.throwIfAborted)(options?.signal, `Execution of agent ${this.getName()}`);
         this.emit(AgentEvent_1.AgentEvent.TOOL_USE, toolCalls);
         this.currentToolCallCount += toolCalls.length;
         const assistantEntry = transformers_1.chatCompletionsTransformer.fromProviderMessage(message);
         this.addToHistory(assistantEntry);
-        const toolResults = await this.handleToolCalls(toolCalls);
+        const toolResults = await this.handleToolCalls(toolCalls, options);
         for (const result of toolResults) {
             const resultEntry = transformers_1.chatCompletionsTransformer.toolResultEntry(result.toolCallId, result.content);
             this.addToHistory(resultEntry);
         }
         try {
-            const newResponse = await this.callProvider();
+            const newResponse = await this.callProvider(options);
             this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
-            return this.handleResponse(newResponse);
+            return this.handleResponse(newResponse, options);
         }
         catch (error) {
             const executionError = new AgentError_1.ExecutionError(`${this.getVendorName()} error during tool response: ${error instanceof Error ? error.message : "Unknown error"}`);
@@ -209,7 +223,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             throw executionError;
         }
     }
-    async handleToolCalls(toolCalls) {
+    async handleToolCalls(toolCalls, options) {
         return Promise.all(toolCalls.map(async (toolCall) => {
             const toolName = toolCall.type === "function" ? toolCall.function.name : "";
             const tool = this.tools.get(toolName);
@@ -224,7 +238,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             }
             try {
                 const args = JSON.parse(toolCall.function.arguments || "{}");
-                const result = await tool.execute(this.getId(), this.getName(), args, toolCallId, this.config.model, this.vendor);
+                const result = await tool.execute(this.getId(), this.getName(), args, toolCallId, this.config.model, this.vendor, { signal: options?.signal });
                 return { toolCallId, content: JSON.stringify(result) };
             }
             catch (error) {
@@ -253,7 +267,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
      * }
      * ```
      */
-    async *executeStream(input) {
+    async *executeStream(input, options) {
         this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
         this.resetTokenUsage();
         this.currentToolCallCount = 0;
@@ -274,9 +288,17 @@ class OpenAICompatibleAgent 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 openai_1.default.APIError) {
                 const apiError = new AgentError_1.ApiError(`${this.getVendorName()} API error: ${error.message}`, error.status, error);
                 this.emit(AgentEvent_1.AgentEvent.ERROR, apiError);
@@ -306,7 +328,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             this.history.endExecution();
         }
     }
-    async *streamTurn() {
+    async *streamTurn(options) {
         const messages = transformers_1.chatCompletionsTransformer.toProvider(this.history.getEntries());
         const tools = this.tools.size > 0 ? this.getToolDefinitions() : undefined;
         this.startTurnTimer();
@@ -324,7 +346,7 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             presence_penalty: this.config.presencePenalty,
             frequency_penalty: this.config.frequencyPenalty,
             ...this.buildExtraRequestParams(),
-        });
+        }, { signal: options?.signal });
         let textContent = "";
         let reasoningContent = "";
         const toolCallAcc = new Map();
@@ -383,8 +405,12 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
         // continues into a tool call still reports what it spent.
         if (streamUsage)
             this.accumulateStreamUsage(streamUsage);
+        // 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.
+        (0, cancellation_1.throwIfAborted)(options?.signal, `Execution of agent ${this.getName()}`);
         if (finishReason === "length") {
-            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) {
@@ -394,6 +420,9 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
             throw error;
         }
         if (finishReason === "tool_calls" && toolCallAcc.size > 0) {
+            // As in handleResponse(): bail out before the assistant turn is written,
+            // so a cancelled run leaves no unanswered tool call in history.
+            (0, cancellation_1.throwIfAborted)(options?.signal, `Execution of agent ${this.getName()}`);
             const toolCalls = Array.from(toolCallAcc.entries())
                 .sort(([a], [b]) => a - b)
                 .map(([, tc]) => ({
@@ -410,11 +439,11 @@ class OpenAICompatibleAgent extends BaseAgent_1.BaseAgent {
                 reasoning_content: reasoningContent || null,
             });
             this.addToHistory(assistantEntry);
-            const toolResults = await this.handleToolCalls(toolCalls);
+            const toolResults = await this.handleToolCalls(toolCalls, options);
             for (const result of toolResults) {
                 this.addToHistory(transformers_1.chatCompletionsTransformer.toolResultEntry(result.toolCallId, result.content));
             }
-            yield* this.streamTurn();
+            yield* this.streamTurn(options);
         }
         else {
             const assistantEntry = transformers_1.chatCompletionsTransformer.fromProviderMessage({