@agentionai/agents 0.13.0 → 1.0.0

package/dist/agents/llamacpp/LlamaCppAgent.js

@@ -1,16 +1,7 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LlamaCppAgent = void 0;
-const openai_1 = __importDefault(require("openai"));
-const BaseAgent_1 = require("../BaseAgent");
-const AgentEvent_1 = require("../AgentEvent");
-const AgentError_1 = require("../errors/AgentError");
-const transformers_1 = require("../../history/transformers");
-const VizReporter_1 = require("../../viz/VizReporter");
-const VizConfig_1 = require("../../viz/VizConfig");
+const OpenAICompatibleAgent_1 = require("../openai-compatible/OpenAICompatibleAgent");
 /**
  * Agent for locally-hosted models served by a llama.cpp server (`llama-server`),
  * which exposes an OpenAI-compatible `/v1/chat/completions` API.
@@ -23,7 +14,6 @@ const VizConfig_1 = require("../../viz/VizConfig");
  *   id: "1",
  *   name: "Assistant",
  *   description: "A helpful assistant",
- *   apiKey: "",
  *   baseURL: "http://localhost:8080/v1",
  * });
  *
@@ -35,227 +25,19 @@ const VizConfig_1 = require("../../viz/VizConfig");
  * const models = await agent.listModels();
  * ```
  */
-class LlamaCppAgent extends BaseAgent_1.BaseAgent {
+class LlamaCppAgent extends OpenAICompatibleAgent_1.OpenAICompatibleAgent {
     constructor(config, history) {
-        super({ ...config, vendor: "llamacpp" }, history);
-        /** Count of tool calls in current execution */
-        this.currentToolCallCount = 0;
         const vendorConfig = config.vendorConfig?.llamacpp || {};
         const baseURL = config.baseURL ?? vendorConfig.baseURL ?? "http://localhost:8080/v1";
-        this.client = new openai_1.default({
-            apiKey: config.apiKey || "not-needed",
+        super({
+            ...config,
+            vendor: "llamacpp",
             baseURL,
-        });
-        this.config = {
-            model: config.model || "default",
-            baseURL,
-            maxTokens: config.maxTokens,
-            temperature: config.temperature,
-            topP: config.topP,
-            stopSequences: config.stopSequences,
-            seed: config.seed,
-            presencePenalty: config.presencePenalty,
-            frequencyPenalty: config.frequencyPenalty,
-            apiKey: config.apiKey,
-        };
-        this.addSystemMessage(this.getSystemMessage());
-    }
-    /**
-     * List the models currently available on the llama.cpp server (via its
-     * OpenAI-compatible `/v1/models` endpoint).
-     */
-    async listModels() {
-        try {
-            const page = await this.client.models.list();
-            return page.data;
-        }
-        catch (error) {
-            throw new AgentError_1.ExecutionError(`Failed to list llama.cpp models: ${error instanceof Error ? error.message : "Unknown error"}`);
-        }
-    }
-    getToolDefinitions() {
-        return Array.from(this.tools.values()).map((tool) => {
-            const prompt = tool.getPrompt();
-            return {
-                type: "function",
-                function: {
-                    name: prompt.name,
-                    description: prompt.description,
-                    parameters: prompt.input_schema,
-                },
-            };
-        });
-    }
-    async process(_input) {
-        return "";
-    }
-    async execute(input) {
-        this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
-        this.lastTokenUsage = undefined;
-        this.currentToolCallCount = 0;
-        const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
-        if (VizConfig_1.vizConfig.isEnabled()) {
-            this.vizEventId = VizReporter_1.vizReporter.agentStart(this.id, this.name, this.config.model, "llamacpp", inputPreview);
-        }
-        if (this.history.transient) {
-            this.history.clear();
-            this.addSystemMessage(this.getSystemMessage());
-        }
-        if (typeof input === "string") {
-            this.addTextToHistory("user", input);
-        }
-        else {
-            this.addMessageToHistory("user", input);
-        }
-        this.history.setSessionAnchor();
-        this.history.beginExecution();
-        try {
-            const response = await this.callLlamaCpp();
-            this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, response);
-            return await this.handleResponse(response);
-        }
-        catch (error) {
-            if (error instanceof openai_1.default.APIError) {
-                const apiError = new AgentError_1.ApiError(`llama.cpp API error: ${error.message}`, error.status, error);
-                this.emit(AgentEvent_1.AgentEvent.ERROR, apiError);
-                if (this.vizEventId) {
-                    VizReporter_1.vizReporter.agentError(this.vizEventId, "ApiError", apiError.message, error.status === 429);
-                    this.vizEventId = undefined;
-                }
-                throw apiError;
-            }
-            if (error instanceof AgentError_1.ExecutionError || error instanceof AgentError_1.ApiError) {
-                this.emit(AgentEvent_1.AgentEvent.ERROR, error);
-                if (this.vizEventId) {
-                    VizReporter_1.vizReporter.agentError(this.vizEventId, error.constructor.name, error.message, false);
-                    this.vizEventId = undefined;
-                }
-                throw error;
-            }
-            const executionError = new AgentError_1.ExecutionError(`llama.cpp error: ${error instanceof Error ? error.message : "Unknown error"}`);
-            this.emit(AgentEvent_1.AgentEvent.ERROR, executionError);
-            if (this.vizEventId) {
-                VizReporter_1.vizReporter.agentError(this.vizEventId, "ExecutionError", executionError.message, false);
-                this.vizEventId = undefined;
-            }
-            throw executionError;
-        }
-        finally {
-            this.history.endExecution();
-        }
-    }
-    async callLlamaCpp() {
-        const messages = transformers_1.chatCompletionsTransformer.toProvider(this.history.getEntries());
-        const tools = this.tools.size > 0 ? this.getToolDefinitions() : undefined;
-        return this.client.chat.completions.create({
-            model: this.config.model,
-            messages,
-            tools,
-            stream: false,
-            max_tokens: this.config.maxTokens,
-            temperature: this.config.temperature,
-            top_p: this.config.topP,
-            stop: this.config.stopSequences,
-            seed: this.config.seed,
-            presence_penalty: this.config.presencePenalty,
-            frequency_penalty: this.config.frequencyPenalty,
-        });
-    }
-    async handleResponse(response) {
-        const usage = this.parseUsage(response);
-        if (this.lastTokenUsage) {
-            this.lastTokenUsage.input_tokens += usage.input_tokens;
-            this.lastTokenUsage.output_tokens += usage.output_tokens;
-            this.lastTokenUsage.total_tokens += usage.total_tokens;
-        }
-        else {
-            this.lastTokenUsage = { ...usage };
-        }
-        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);
-            this.emit(AgentEvent_1.AgentEvent.MAX_TOKENS_EXCEEDED, error);
-            this.emit(AgentEvent_1.AgentEvent.ERROR, error);
-            if (this.vizEventId) {
-                VizReporter_1.vizReporter.agentError(this.vizEventId, "MaxTokensExceededError", error.message, false);
-                this.vizEventId = undefined;
-            }
-            throw error;
-        }
-        const hasToolCalls = message.tool_calls && message.tool_calls.length > 0;
-        if (!hasToolCalls) {
-            const textContent = message.content || "";
-            const entry = transformers_1.chatCompletionsTransformer.fromProviderMessage(message);
-            this.addToHistory(entry);
-            this.emit(AgentEvent_1.AgentEvent.DONE, message, usage);
-            if (this.vizEventId) {
-                VizReporter_1.vizReporter.agentComplete(this.vizEventId, {
-                    input: this.lastTokenUsage?.input_tokens || 0,
-                    output: this.lastTokenUsage?.output_tokens || 0,
-                    total: this.lastTokenUsage?.total_tokens || 0,
-                }, "end_turn", this.currentToolCallCount > 0, this.currentToolCallCount, textContent);
-                this.vizEventId = undefined;
-            }
-            return textContent;
-        }
-        // Tool calls detected
-        const toolCalls = message.tool_calls;
-        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);
-        for (const result of toolResults) {
-            const resultEntry = transformers_1.chatCompletionsTransformer.toolResultEntry(result.toolCallId, result.content);
-            this.addToHistory(resultEntry);
-        }
-        // Continue conversation with tool results
-        try {
-            const newResponse = await this.callLlamaCpp();
-            this.emit(AgentEvent_1.AgentEvent.AFTER_EXECUTE, newResponse);
-            return this.handleResponse(newResponse);
-        }
-        catch (error) {
-            const executionError = new AgentError_1.ExecutionError(`llama.cpp error during tool response: ${error instanceof Error ? error.message : "Unknown error"}`);
-            this.emit(AgentEvent_1.AgentEvent.ERROR, executionError);
-            throw executionError;
-        }
-    }
-    async handleToolCalls(toolCalls) {
-        return Promise.all(toolCalls.map(async (toolCall) => {
-            const toolName = toolCall.type === "function" ? toolCall.function.name : "";
-            const tool = this.tools.get(toolName);
-            const toolCallId = toolCall.id;
-            if (toolCall.type !== "function" || !tool) {
-                const errorMessage = `Tool '${toolName}' not found`;
-                const error = new AgentError_1.ToolExecutionError(errorMessage, toolName, toolCall.type === "function" ? toolCall.function.arguments : undefined);
-                this.emit(AgentEvent_1.AgentEvent.TOOL_ERROR, error);
-                return { toolCallId, content: errorMessage };
-            }
-            try {
-                const args = JSON.parse(toolCall.function.arguments || "{}");
-                const result = await tool.execute(this.getId(), this.getName(), args, toolCallId, this.config.model, "llamacpp");
-                return { toolCallId, content: JSON.stringify(result) };
-            }
-            catch (error) {
-                const errorMessage = `Error executing tool '${toolName}': ${error instanceof Error ? error.message : "Unknown error"}`;
-                if (this.debug) {
-                    console.error(errorMessage);
-                }
-                const toolError = new AgentError_1.ToolExecutionError(errorMessage, toolName, toolCall.function.arguments);
-                this.emit(AgentEvent_1.AgentEvent.TOOL_ERROR, toolError);
-                return { toolCallId, content: errorMessage };
-            }
-        }));
+            model: config.model ?? "default",
+        }, history);
     }
-    parseUsage(response) {
-        const usage = response.usage;
-        return {
-            input_tokens: usage?.prompt_tokens ?? 0,
-            output_tokens: usage?.completion_tokens ?? 0,
-            total_tokens: usage?.total_tokens ?? 0,
-        };
+    getVendorName() {
+        return "llama.cpp";
     }
 }
 exports.LlamaCppAgent = LlamaCppAgent;

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

@@ -2,6 +2,7 @@ import { BaseAgent, BaseAgentConfig, TokenUsage } from "../BaseAgent";
 import { History, MessageContent } from "../../history/History";
 import { Tool, Response, ResponseUsage } from "openai/resources/responses/responses";
 import { OpenAIModel } from "../model-types";
+import { StreamChunk } from "../openai-compatible/OpenAICompatibleAgent";
 type AgentConfig = BaseAgentConfig & {
     apiKey: string;
     model?: OpenAIModel;
@@ -42,6 +43,20 @@ export declare class OpenAiAgent extends BaseAgent {
     execute(input: string | MessageContent[]): Promise<string>;
     protected handleResponse(response: Response): Promise<string>;
     private handleToolUse;
+    /**
+     * Stream a response as an async generator of `StreamChunk` objects.
+     * Yields `{ type: "text" }` for visible output and `{ type: "reasoning" }` for
+     * reasoning summary tokens (o-series models). Tool calls are handled transparently.
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of agent.executeStream("Explain recursion")) {
+     *   if (chunk.type === "text") process.stdout.write(chunk.content);
+     * }
+     * ```
+     */
+    executeStream(input: string | MessageContent[]): AsyncGenerator<StreamChunk>;
+    private streamTurn;
     protected parseUsage(input: ResponseUsage): TokenUsage;
 }
 export {};

package/dist/agents/openai/OpenAiAgent.js

@@ -341,6 +341,156 @@ class OpenAiAgent extends BaseAgent_1.BaseAgent {
         }));
         return toolResults;
     }
+    /**
+     * Stream a response as an async generator of `StreamChunk` objects.
+     * Yields `{ type: "text" }` for visible output and `{ type: "reasoning" }` for
+     * reasoning summary tokens (o-series models). Tool calls are handled transparently.
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of agent.executeStream("Explain recursion")) {
+     *   if (chunk.type === "text") process.stdout.write(chunk.content);
+     * }
+     * ```
+     */
+    async *executeStream(input) {
+        this.emit(AgentEvent_1.AgentEvent.BEFORE_EXECUTE, input);
+        this.lastTokenUsage = undefined;
+        this.currentToolCallCount = 0;
+        const inputPreview = typeof input === "string" ? input : JSON.stringify(input);
+        if (VizConfig_1.vizConfig.isEnabled()) {
+            this.vizEventId = VizReporter_1.vizReporter.agentStart(this.id, this.name, this.config.model, "openai", inputPreview);
+        }
+        if (this.history.transient) {
+            this.history.clear();
+            this.addSystemMessage(this.getSystemMessage());
+        }
+        if (typeof input === "string") {
+            this.addTextToHistory("user", input);
+        }
+        else {
+            this.addMessageToHistory("user", input);
+        }
+        this.history.setSessionAnchor();
+        this.history.beginExecution();
+        try {
+            yield* this.streamTurn();
+        }
+        catch (error) {
+            if (error instanceof AgentError_1.AgentError) {
+                this.emit(AgentEvent_1.AgentEvent.ERROR, error);
+                if (this.vizEventId) {
+                    VizReporter_1.vizReporter.agentError(this.vizEventId, error.constructor.name, error.message, false);
+                    this.vizEventId = undefined;
+                }
+                throw error;
+            }
+            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);
+                this.emit(AgentEvent_1.AgentEvent.ERROR, apiError);
+                if (this.vizEventId) {
+                    VizReporter_1.vizReporter.agentError(this.vizEventId, "ApiError", apiError.message, openAIError.error.code === "rate_limit_exceeded");
+                    this.vizEventId = undefined;
+                }
+                throw apiError;
+            }
+            const executionError = new AgentError_1.ExecutionError(`OpenAI error: ${error instanceof Error ? error.message : "Unknown error"}`);
+            this.emit(AgentEvent_1.AgentEvent.ERROR, executionError);
+            if (this.vizEventId) {
+                VizReporter_1.vizReporter.agentError(this.vizEventId, "ExecutionError", executionError.message, false);
+                this.vizEventId = undefined;
+            }
+            throw executionError;
+        }
+        finally {
+            this.history.endExecution();
+        }
+    }
+    async *streamTurn() {
+        const inputMessages = transformers_1.openAiTransformer.toProvider(this.history.getEntries());
+        const stream = await this.client.responses.create({
+            model: this.config.model,
+            max_output_tokens: this.config.maxTokens,
+            input: inputMessages,
+            tools: this.getToolDefinitions(),
+            store: false,
+            stream: true,
+            temperature: this.config.temperature,
+            top_p: this.config.topP,
+            user: this.config.user,
+            ...(this.config.disableReasoning && { reasoning: { effort: null } }),
+            ...(this.config.reasoningEffort && !this.config.disableReasoning && {
+                // `summary: "auto"` is required for the Responses API to stream
+                // `response.reasoning_summary_text.delta` events.
+                reasoning: { effort: this.config.reasoningEffort, summary: "auto" },
+            }),
+        });
+        let completedEvent = null;
+        for await (const event of stream) {
+            if (event.type === "response.output_text.delta") {
+                this.emit(AgentEvent_1.AgentEvent.CHUNK, event.delta);
+                yield { type: "text", content: event.delta };
+            }
+            if (event.type === "response.reasoning_summary_text.delta") {
+                this.emit(AgentEvent_1.AgentEvent.REASONING_CHUNK, event.delta);
+                yield { type: "reasoning", content: event.delta };
+            }
+            if (event.type === "response.completed") {
+                completedEvent = event;
+                if (event.response.usage) {
+                    const usage = this.parseUsage(event.response.usage);
+                    if (this.lastTokenUsage) {
+                        this.lastTokenUsage.input_tokens += usage.input_tokens;
+                        this.lastTokenUsage.output_tokens += usage.output_tokens;
+                        this.lastTokenUsage.total_tokens += usage.total_tokens;
+                    }
+                    else {
+                        this.lastTokenUsage = { ...usage };
+                    }
+                }
+            }
+            if (event.type === "response.incomplete") {
+                throw new AgentError_1.MaxTokensExceededError("Response incomplete: max tokens reached", this.config.maxTokens || 1024);
+            }
+        }
+        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) {
+            this.emit(AgentEvent_1.AgentEvent.TOOL_USE, toolCalls);
+            this.currentToolCallCount += toolCalls.length;
+            const functionCalls = toolCalls.map((tc) => ({
+                id: tc.id || tc.call_id,
+                call_id: tc.call_id,
+                name: tc.name,
+                arguments: tc.arguments,
+            }));
+            const assistantEntry = transformers_1.openAiTransformer.fromProviderMessage("assistant", response.output_text || "", functionCalls);
+            this.addToHistory(assistantEntry);
+            const toolResults = await this.handleToolUse(toolCalls);
+            for (const result of toolResults) {
+                this.addToHistory(transformers_1.openAiTransformer.toolResultEntry(result.call_id, result.output, false));
+            }
+            yield* this.streamTurn();
+        }
+        else {
+            const textContent = response.output_text || "";
+            const entry = transformers_1.openAiTransformer.fromProviderMessage("assistant", textContent);
+            this.addToHistory(entry);
+            this.emit(AgentEvent_1.AgentEvent.DONE, response, this.lastTokenUsage);
+            if (this.vizEventId) {
+                VizReporter_1.vizReporter.agentComplete(this.vizEventId, {
+                    input: this.lastTokenUsage?.input_tokens || 0,
+                    output: this.lastTokenUsage?.output_tokens || 0,
+                    total: this.lastTokenUsage?.total_tokens || 0,
+                }, "end_turn", this.currentToolCallCount > 0, this.currentToolCallCount, textContent);
+                this.vizEventId = undefined;
+            }
+        }
+    }
     parseUsage(input) {
         return {
             input_tokens: input.input_tokens,

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

@@ -0,0 +1,75 @@
+import OpenAI from "openai";
+import { ChatCompletion, ChatCompletionTool } from "openai/resources/chat/completions";
+import { Model } from "openai/resources/models";
+import { BaseAgent, BaseAgentConfig, TokenUsage } from "../BaseAgent";
+import { AgentVendor } from "../AgentConfig";
+import { History, MessageContent } from "../../history/History";
+/**
+ * A single chunk yielded by `executeStream()`.
+ * - `"text"` — visible output token
+ * - `"reasoning"` — internal reasoning token (DeepSeek-style `reasoning_content`)
+ */
+export type StreamChunk = {
+    type: "text" | "reasoning";
+    content: string;
+};
+export type OpenAICompatibleConfig = BaseAgentConfig & {
+    /** Base URL of the OpenAI-compatible `/v1` endpoint (required) */
+    baseURL: string;
+    model?: string;
+    maxTokens?: number;
+};
+/**
+ * Abstract base class for agents that talk to any OpenAI-compatible
+ * `/v1/chat/completions` endpoint (llama.cpp, vLLM, LM Studio, etc.).
+ *
+ * Subclasses must implement:
+ * - `getVendorName()` — human-readable name used in error messages (e.g. `"llama.cpp"`)
+ *
+ * Subclasses may override:
+ * - `buildExtraRequestParams()` — extra fields merged into the completions request
+ */
+export declare abstract class OpenAICompatibleAgent extends BaseAgent {
+    protected client: OpenAI;
+    protected config: Partial<OpenAICompatibleConfig>;
+    lastTokenUsage?: TokenUsage;
+    private vizEventId?;
+    private currentToolCallCount;
+    constructor(config: OpenAICompatibleConfig & {
+        vendor: AgentVendor;
+    }, history?: History);
+    /** Human-readable vendor name used in error messages (e.g. `"llama.cpp"`). */
+    protected abstract getVendorName(): string;
+    /** Extra fields to merge into the chat completions request. Override for vendor-specific params. */
+    protected buildExtraRequestParams(): Record<string, unknown>;
+    /**
+     * List the models available on the server via the `/v1/models` endpoint.
+     */
+    listModels(): Promise<Model[]>;
+    protected getToolDefinitions(): ChatCompletionTool[];
+    protected process(_input: string): Promise<string>;
+    execute(input: string | MessageContent[]): Promise<string>;
+    private callProvider;
+    protected handleResponse(response: ChatCompletion): Promise<string>;
+    private handleToolCalls;
+    /**
+     * Stream a response as an async generator of `StreamChunk` objects.
+     *
+     * Yields `{ type: "text" }` for visible output and `{ type: "reasoning" }` for
+     * internal reasoning tokens (models that expose `reasoning_content`, e.g. DeepSeek R1).
+     * Tool calls are executed transparently — the generator continues streaming after
+     * each tool-call round-trip.
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of agent.executeStream("Explain recursion")) {
+     *   if (chunk.type === "text") process.stdout.write(chunk.content);
+     * }
+     * ```
+     */
+    executeStream(input: string | MessageContent[]): AsyncGenerator<StreamChunk>;
+    private streamTurn;
+    private accumulateStreamUsage;
+    protected parseUsage(response: ChatCompletion): TokenUsage;
+}
+//# sourceMappingURL=OpenAICompatibleAgent.d.ts.map