agent-pulse 1.1.0 → 1.3.0

package/README.md

@@ -49,7 +49,6 @@ const agentWithKey = new Agent({
   provider: new openAI('gpt-4o', process.env.CUSTOM_KEY_NAME || 'your-key'),
   system: 'You are a helpful assistant.'
 });
-```
 
 // Real-time typing effect
 agent.on('token', (chunk) => {
@@ -132,7 +131,8 @@ import { Agent, OpenAIProvider, GoogleProvider, GrokProvider } from 'agent-pulse
 | `files` | string[] | Array of file paths or content strings to include in context. |
 | `tools` | Array | List of executable tools with Zod schemas. |
 | `output_schema` | ZodSchema | Enforce structured JSON output (if supported by provider). |
-| `saveFunction` | function | Async function to persist messages (`(msg) => Promise<void>`). |
+| `saveFunction` | function | Async function to persist messages (`(msg: AgentMessage) => Promise<void>`). |
+| `max_tool_iterations` | number | Max iterations for tool call loops (default: 1). |
 
 ## Events
 
@@ -154,7 +154,8 @@ The `response` event and the `agent.run()` promise resolve to a standardized `Ag
 
 ```typescript
 {
-    content: string | object, // The Markdown text or parsed JSON
+    content: string | object, // The Markdown text, parsed JSON, or tool result (if iterations=1)
+    message?: string,          // The original LLM text response (useful when a tool is also called)
     usage: {
         input_tokens: number,
         output_tokens: number,
@@ -167,6 +168,9 @@ The `response` event and the `agent.run()` promise resolve to a standardized `Ag
 }
 ```
 
+> [!NOTE]
+> If an LLM responds with both text and a tool call (common in Gemini), `content` stays consistent with legacy behavior (holding the tool result), while the new `message` field preserves the original LLM text.
+
 You can access token usage stats from the `usage` property.
 
 ## Error Codes
@@ -226,7 +230,18 @@ if (result.content?.type === 'INTENT_COMPLETE') {
 }
 ```
 
-#### Option B: Events (Side Effects)
+#### Option B: Handling Text + Tool (Gemini Style)
+When using models like Gemini that often provide a text explanation *and* a tool call in one turn, use the `message` field to access the text.
+
+```typescript
+const result = await agent.run("Tell me a joke and then get the weather.");
+
+// If weatherTool was called:
+console.log(result.message); // "Sure! Here's a joke: ... Now, let me get the weather for you."
+console.log(result.content); // { temp: 20, unit: 'celsius' } (The tool result)
+```
+
+#### Option C: Events (Side Effects)
 Best for logging, UI updates, or real-time monitoring.
 
 ```typescript
@@ -238,11 +253,85 @@ agent.on('tool_start', (evt) => {
 agent.on('tool_end', (evt) => {
   console.log(`[UI] ✔️ Tool finished:`, evt.result);
 });
+```
+
+
+### 2. Multi-Turn Tool Calling (Autonomous Agent)
+
+By setting `max_tool_iterations`, the agent can autonomously call tools, receive results, and reason until it has a final answer.
+
+```typescript
+const agent = new Agent({
+  name: 'researcher',
+  provider: new openAI('gpt-4o'),
+  tools: [weatherTool, searchTool],
+  max_tool_iterations: 5 // Allow up to 5 loop turns
+});
 
-await agent.run("I want to go to Tokyo.");
+const result = await agent.run("What's the weather like in London today?");
+// Agent calls weatherTool -> receives result -> reasons -> returns final text.
+```
+
+### 3. Manual Tool Responses (Client-Side Loops)
+
+If your agent is running on a server but needs the **client** to perform an action (like opening a modal or reading a local file), you can return a UI instruction and then send the result back in the next `run()` call.
+
+#### OpenAI Example
+```typescript
+const agent = new Agent({
+  name: 'account-mgr',
+  provider: new openAI('gpt-4o'),
+  tools: [requestConfirmationTool]
+});
+
+// 1. First Run: Agent requests a tool call
+const res = await agent.run("Delete my account ACC-123");
+
+// 2. Client handles the tool call manually (e.g., shows a modal)
+const confirmed = await myUi.showModal(res.content.payload);
+
+// 3. Second Run: Send the result back to the agent
+const final = await agent.run([
+  { role: 'user', content: "Delete my account ACC-123" },
+  { 
+    role: 'assistant', 
+    content: null, 
+    tool_calls: [{ id: 'call_123', name: 'request_delete', arguments: { id: 'ACC-123' } }] 
+  },
+  { 
+    role: 'tool', 
+    tool_call_id: 'call_123', 
+    content: JSON.stringify({ confirmed }) 
+  }
+]);
+```
+
+#### Gemini Example
+The same pattern works for Gemini! While Google's API uses a different internal format (`functionResponse`), **Agent Pulse** handles the mapping for you. Simply use the standardized `tool` role:
+
+```typescript
+const agent = new Agent({
+  name: 'gemini-agent',
+  provider: new google('gemini-1.5-flash')
+});
+
+const final = await agent.run([
+  { role: 'user', content: "Search for weather" },
+  { 
+    role: 'assistant', 
+    content: null, 
+    tool_calls: [{ id: 'call_abc', name: 'get_weather', arguments: { loc: 'London' } }] 
+  },
+  { 
+    role: 'tool', 
+    tool_call_id: 'call_abc', 
+    name: 'get_weather', // Required for Gemini
+    content: JSON.stringify({ temp: 20 }) 
+  }
+]);
 ```
 
-### 2. File Input
+### 4. File Input
 
 Pass file content context to the agent.
 
@@ -257,7 +346,7 @@ const agent = new Agent({
 });
 ```
 
-### 3. Structured Output (JSON)
+### 4. Structured Output (JSON)
 
 Enforce a specific JSON schema for the response.
 
@@ -285,7 +374,7 @@ agent.on('response', (result) => {
 await agent.run("How do I make pancakes?");
 ```
 
-### 4. Server-Side Streaming (SSE)
+### 5. Server-Side Streaming (SSE)
 
 Bridge agent events to a Server-Sent Events stream for frontend consumption (e.g., in Express).
 
@@ -311,7 +400,7 @@ app.get('/chat', async (req, res) => {
 });
 ```
 
-### 5. Google Search Grounding
+### 6. Google Search Grounding
 
 Enable real-time search results and citations with Google models.
 
@@ -359,7 +448,7 @@ const agent = new Agent({
     provider: new MyProvider('my-model')
 });
 ```
-# To locally link the package
+## To locally link the package
 
 1. Run `npm link` in the agent-pulse directory
 2. Run `npm link agent-pulse --legacy-peer-deps` in your project directory

package/dist/agent.d.ts

@@ -1,8 +1,8 @@
 import { EventEmitter } from 'events';
-import { AgentConfig, AgentResponse } from './types';
+import { AgentConfig, AgentResponse, AgentMessage } from './types';
 export declare class Agent extends EventEmitter {
     private config;
     private provider;
     constructor(config: AgentConfig);
-    run(inputContext: string | any[]): Promise<AgentResponse>;
+    run(inputContext: string | AgentMessage[]): Promise<AgentResponse>;
 }

package/dist/agent.js

@@ -11,64 +11,96 @@ class Agent extends events_1.EventEmitter {
     async run(inputContext) {
         this.emit('start', { timestamp: Date.now(), inputContext });
         const startTime = Date.now();
-        // Persistence: Save User Message if input is a string (new message)
+        // 1. Initialize message history
+        let messages = [];
+        if (Array.isArray(inputContext)) {
+            messages = [...inputContext];
+        }
+        else {
+            const content = typeof inputContext === 'string' ? inputContext : String(inputContext);
+            const userContent = this.config.prompt ? `${this.config.prompt}\n\n${content}` : content;
+            messages.push({ role: 'user', content: userContent });
+        }
+        // Persistence: Save initial User Message if it's new
         if (typeof inputContext === 'string' && this.config.saveFunction) {
             try {
-                await this.config.saveFunction({ role: 'user', content: inputContext });
+                const lastMsg = messages[messages.length - 1];
+                await this.config.saveFunction(lastMsg);
             }
             catch (err) {
                 console.error("Failed to save user message:", err);
             }
         }
-        // Normalize input context
-        let finalPrompt;
-        if (Array.isArray(inputContext)) {
-            finalPrompt = inputContext;
-        }
-        else {
-            const prompt = typeof inputContext === 'string' ? inputContext : String(inputContext);
-            finalPrompt = this.config.prompt ? `${this.config.prompt}\n\n${prompt}` : prompt;
-        }
+        let iterations = 0;
+        const maxIterations = this.config.max_tool_iterations || 1;
+        let lastResponse = null;
         try {
-            const response = await this.provider.generate(this.config.system, finalPrompt, this.config.files, this.config.tools, this.config.config, this.config.output_schema, (token) => this.emit('token', token));
-            // Handle Tool Execution
-            if (response.tool_calls && this.config.tools) {
-                for (const call of response.tool_calls) {
-                    const tool = this.config.tools.find(t => t.name === call.name);
-                    if (tool) {
-                        try {
-                            // Execute the tool
-                            // Note: In this lightweight framework, we return the tool result as the final content.
-                            // This supports the "Intent Detection" pattern where the goal is to trigger an action, not just chat.
-                            this.emit('tool_start', { tool: tool.name, arguments: call.arguments });
-                            const result = await tool.execute(call.arguments);
-                            this.emit('tool_end', { tool: tool.name, result });
-                            response.content = result;
-                        }
-                        catch (e) {
-                            console.error(`Error executing tool ${tool.name}:`, e);
-                        }
-                    }
+            while (iterations < maxIterations) {
+                iterations++;
+                const response = await this.provider.generate(this.config.system, messages, this.config.files, this.config.tools, this.config.config, this.config.output_schema, (token) => this.emit('token', token));
+                lastResponse = response;
+                // Capture the original text as the "message" (LLM's primary text response)
+                if (typeof response.content === 'string') {
+                    lastResponse.message = response.content;
                 }
-            }
-            // Add latency to meta
-            response.meta.latency_ms = Date.now() - startTime;
-            // Persistence: Save Assistant Response
-            if (this.config.saveFunction) {
-                try {
-                    await this.config.saveFunction({
+                // Handle Tool Execution
+                if (response.tool_calls && this.config.tools) {
+                    // Add Assistant's tool call message to history
+                    const assistantMsg = {
                         role: 'assistant',
-                        content: response.content,
-                        usage: response.usage,
-                        meta: response.meta
-                    });
-                }
-                catch (err) {
-                    console.error("Failed to save assistant response:", err);
+                        content: response.content || null,
+                        tool_calls: response.tool_calls
+                    };
+                    messages.push(assistantMsg);
+                    if (this.config.saveFunction) {
+                        await this.config.saveFunction(assistantMsg);
+                    }
+                    let lastToolResult = null;
+                    for (const call of response.tool_calls) {
+                        const tool = this.config.tools.find(t => t.name === call.name);
+                        if (tool) {
+                            try {
+                                this.emit('tool_start', { tool: tool.name, arguments: call.arguments });
+                                const result = await tool.execute(call.arguments);
+                                this.emit('tool_end', { tool: tool.name, result });
+                                lastToolResult = result;
+                                const toolMsg = {
+                                    role: 'tool',
+                                    tool_call_id: call.id,
+                                    name: tool.name,
+                                    content: typeof result === 'string' ? result : JSON.stringify(result)
+                                };
+                                messages.push(toolMsg);
+                                if (this.config.saveFunction) {
+                                    await this.config.saveFunction(toolMsg);
+                                }
+                            }
+                            catch (e) {
+                                console.error(`Error executing tool ${tool.name}:`, e);
+                                // Add error as tool result so LLM knows what happened
+                                const errorMsg = {
+                                    role: 'tool',
+                                    tool_call_id: call.id,
+                                    name: tool.name,
+                                    content: `Error: ${e instanceof Error ? e.message : String(e)}`
+                                };
+                                messages.push(errorMsg);
+                            }
+                        }
+                    }
+                    // For the "Intent Detection" pattern (maxIterations = 1), 
+                    // we return the last tool result as the content to preserve legacy behavior.
+                    if (maxIterations === 1 && lastToolResult !== null) {
+                        lastResponse.content = lastToolResult;
+                    }
+                    // If we have more iterations, continue the loop
+                    if (iterations < maxIterations) {
+                        continue;
+                    }
                 }
+                // If no tool calls OR we reached limit, break and return
+                break;
             }
-            this.emit('response', response);
-            return response;
         }
         catch (error) {
             this.emit('error', {
@@ -78,6 +110,27 @@ class Agent extends events_1.EventEmitter {
             });
             throw error;
         }
+        if (!lastResponse) {
+            throw new Error("Agent failed to generate a response");
+        }
+        // Add latency to meta
+        lastResponse.meta.latency_ms = Date.now() - startTime;
+        // Persistence: Save Final Assistant Response
+        if (this.config.saveFunction) {
+            try {
+                await this.config.saveFunction({
+                    role: 'assistant',
+                    content: lastResponse.content,
+                    usage: lastResponse.usage,
+                    meta: lastResponse.meta
+                });
+            }
+            catch (err) {
+                console.error("Failed to save assistant response:", err);
+            }
+        }
+        this.emit('response', lastResponse);
+        return lastResponse;
     }
 }
 exports.Agent = Agent;

package/dist/providers/google.d.ts

@@ -1,8 +1,8 @@
-import { LLMProvider, AgentTool, AgentResponse } from '../types';
+import { LLMProvider, AgentTool, AgentResponse, AgentMessage } from '../types';
 import { z } from 'zod';
 export declare class GoogleProvider implements LLMProvider {
     private client;
     private model;
     constructor(model: string, apiKey?: string);
-    generate(system: string | undefined, prompt: string | any[], files: string[] | undefined, tools: AgentTool[] | undefined, config: Record<string, any> | undefined, output_schema: z.ZodType<any> | undefined, onToken: (token: string) => void): Promise<AgentResponse>;
+    generate(system: string | undefined, prompt: string | AgentMessage[], files: string[] | undefined, tools: AgentTool[] | undefined, config: Record<string, any> | undefined, output_schema: z.ZodType<any> | undefined, onToken: (token: string) => void): Promise<AgentResponse>;
 }

package/dist/providers/google.js

@@ -59,10 +59,35 @@ class GoogleProvider {
         let contents;
         if (Array.isArray(prompt)) {
             // Mapping standardized history to Google's format
-            contents = prompt.map(m => ({
-                role: m.role === 'assistant' ? 'model' : 'user',
-                parts: [{ text: m.content }]
-            }));
+            contents = prompt.map(m => {
+                const parts = [];
+                if (m.role === 'tool') {
+                    parts.push({
+                        functionResponse: {
+                            name: m.name,
+                            response: typeof m.content === 'string' ? JSON.parse(m.content) : m.content
+                        }
+                    });
+                    return { role: 'user', parts }; // SDK v2 uses 'user' for function response
+                }
+                if (m.tool_calls) {
+                    for (const tc of m.tool_calls) {
+                        parts.push({
+                            functionCall: {
+                                name: tc.name,
+                                args: tc.arguments
+                            }
+                        });
+                    }
+                }
+                if (m.content) {
+                    parts.push({ text: m.content });
+                }
+                return {
+                    role: m.role === 'assistant' ? 'model' : 'user',
+                    parts
+                };
+            });
             // Handle files by appending to the last message if it's from user
             if (files && files.length > 0) {
                 const lastMsg = contents[contents.length - 1];

package/dist/providers/grok.d.ts

@@ -1,8 +1,8 @@
-import { LLMProvider, AgentTool, AgentResponse } from '../types';
+import { LLMProvider, AgentTool, AgentResponse, AgentMessage } from '../types';
 import { z } from 'zod';
 export declare class GrokProvider implements LLMProvider {
     private client;
     private model;
     constructor(model: string, apiKey?: string);
-    generate(system: string | undefined, prompt: string | any[], files: string[] | undefined, tools: AgentTool[] | undefined, config: Record<string, any> | undefined, output_schema: z.ZodType<any> | undefined, onToken: (token: string) => void): Promise<AgentResponse>;
+    generate(system: string | undefined, prompt: string | AgentMessage[], files: string[] | undefined, tools: AgentTool[] | undefined, config: Record<string, any> | undefined, output_schema: z.ZodType<any> | undefined, onToken: (token: string) => void): Promise<AgentResponse>;
 }

package/dist/providers/grok.js

@@ -24,9 +24,33 @@ class GrokProvider {
             messages.push({ role: 'system', content: system });
         }
         if (Array.isArray(prompt)) {
-            // If prompt is an array, we assume it's a list of messages (history)
-            // We append them directly. 
-            messages.push(...prompt);
+            // Mapping AgentMessage to OpenAI messages (Grok is compatible)
+            for (const msg of prompt) {
+                if (msg.role === 'user') {
+                    messages.push({ role: 'user', content: msg.content });
+                }
+                else if (msg.role === 'assistant') {
+                    messages.push({
+                        role: 'assistant',
+                        content: msg.content || null,
+                        tool_calls: msg.tool_calls?.map(tc => ({
+                            id: tc.id,
+                            type: 'function',
+                            function: {
+                                name: tc.name,
+                                arguments: typeof tc.arguments === 'string' ? tc.arguments : JSON.stringify(tc.arguments)
+                            }
+                        }))
+                    });
+                }
+                else if (msg.role === 'tool') {
+                    messages.push({
+                        role: 'tool',
+                        tool_call_id: msg.tool_call_id,
+                        content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content)
+                    });
+                }
+            }
         }
         else {
             // Handle files - read markdown files and inject into prompt

package/dist/providers/openai.d.ts

@@ -1,8 +1,8 @@
-import { LLMProvider, AgentTool, AgentResponse } from '../types';
+import { LLMProvider, AgentTool, AgentResponse, AgentMessage } from '../types';
 import { z } from 'zod';
 export declare class OpenAIProvider implements LLMProvider {
     private client;
     private model;
     constructor(model: string, apiKey?: string);
-    generate(system: string | undefined, prompt: string | any[], files: string[] | undefined, tools: AgentTool[] | undefined, config: Record<string, any> | undefined, output_schema: z.ZodType<any> | undefined, onToken: (token: string) => void): Promise<AgentResponse>;
+    generate(system: string | undefined, prompt: string | AgentMessage[], files: string[] | undefined, tools: AgentTool[] | undefined, config: Record<string, any> | undefined, output_schema: z.ZodType<any> | undefined, onToken: (token: string) => void): Promise<AgentResponse>;
 }

package/dist/providers/openai.js

@@ -22,9 +22,33 @@ class OpenAIProvider {
             messages.push({ role: 'system', content: system });
         }
         if (Array.isArray(prompt)) {
-            // If prompt is an array, we assume it's a list of messages (history)
-            // We append them directly. 
-            messages.push(...prompt);
+            // Mapping AgentMessage to OpenAI messages
+            for (const msg of prompt) {
+                if (msg.role === 'user') {
+                    messages.push({ role: 'user', content: msg.content });
+                }
+                else if (msg.role === 'assistant') {
+                    messages.push({
+                        role: 'assistant',
+                        content: msg.content || null,
+                        tool_calls: msg.tool_calls?.map(tc => ({
+                            id: tc.id,
+                            type: 'function',
+                            function: {
+                                name: tc.name,
+                                arguments: typeof tc.arguments === 'string' ? tc.arguments : JSON.stringify(tc.arguments)
+                            }
+                        }))
+                    });
+                }
+                else if (msg.role === 'tool') {
+                    messages.push({
+                        role: 'tool',
+                        tool_call_id: msg.tool_call_id,
+                        content: typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content)
+                    });
+                }
+            }
         }
         else {
             // Handle files - read markdown files and inject into prompt

package/dist/types.d.ts

@@ -1,4 +1,13 @@
 import { z } from 'zod';
+export interface AgentMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | any;
+    name?: string;
+    tool_calls?: any[];
+    tool_call_id?: string;
+    usage?: any;
+    meta?: any;
+}
 export interface AgentConfig {
     name: string;
     provider: LLMProvider;
@@ -8,7 +17,8 @@ export interface AgentConfig {
     config?: Record<string, any>;
     tools?: AgentTool[];
     output_schema?: z.ZodType<any>;
-    saveFunction?: (message: any) => Promise<void> | void;
+    saveFunction?: (message: AgentMessage) => Promise<void> | void;
+    max_tool_iterations?: number;
 }
 export interface AgentTool {
     name: string;
@@ -19,6 +29,7 @@ export interface AgentTool {
 export interface AgentResponse {
     content: string | object;
     tool_calls?: any[];
+    message?: string;
     usage: {
         input_tokens: number;
         output_tokens: number;
@@ -41,5 +52,5 @@ export interface AgentError {
     details?: any;
 }
 export interface LLMProvider {
-    generate(system: string | undefined, prompt: string | any[], files: string[] | undefined, tools: AgentTool[] | undefined, config: Record<string, any> | undefined, output_schema: z.ZodType<any> | undefined, onToken: (token: string) => void): Promise<AgentResponse>;
+    generate(system: string | undefined, prompt: string | AgentMessage[], files: string[] | undefined, tools: AgentTool[] | undefined, config: Record<string, any> | undefined, output_schema: z.ZodType<any> | undefined, onToken: (token: string) => void): Promise<AgentResponse>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "agent-pulse",
-    "version": "1.1.0",
+    "version": "1.3.0",
     "description": "A lightweight, agentic AI framework for JavaScript/TypeScript",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",