@igniter-js/agents 0.1.12 → 0.1.14

package/dist/index.mjs

@@ -1,8 +1,9 @@
-import { IgniterError } from '@igniter-js/core';
+import { IgniterError } from '@igniter-js/common';
 import { experimental_createMCPClient } from '@ai-sdk/mcp';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { ToolLoopAgent, tool } from 'ai';
+import { ToolLoopAgent, generateText, Output, tool } from 'ai';
+import { z } from 'zod';
 import { readFile, writeFile, mkdir } from 'fs/promises';
 import { join } from 'path';
 
@@ -386,7 +387,12 @@ var IgniterAgentManagerCore = class _IgniterAgentManagerCore {
    * @example
    * ```typescript
    * const agent = manager.get('support');
-   * const response = await agent.generate({ messages: [...] });
+   * const response = await agent.generate({
+   *   chatId: 'chat_123',
+   *   userId: 'user_123',
+   *   context: {},
+   *   message: { role: 'user', content: 'Hello!' }
+   * });
    * ```
    */
   get(name) {
@@ -661,6 +667,244 @@ var IgniterAgentMemoryCore = class {
   }
 };
 
+// src/utils/strings.ts
+var IgniterAgentStringUtils = class {
+  /**
+   * Generates a unique identifier.
+   */
+  static generateId(prefix) {
+    const random = Math.random().toString(36).substring(2, 12);
+    return prefix ? `${prefix}_${random}` : random;
+  }
+  /**
+   * Truncates a string to a maximum length.
+   */
+  static truncate(str, maxLength, suffix = "...") {
+    if (str.length <= maxLength) return str;
+    return str.slice(0, maxLength - suffix.length) + suffix;
+  }
+  /**
+   * Converts a string to snake_case.
+   */
+  static toSnakeCase(str) {
+    return str.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "");
+  }
+  /**
+   * Converts a string to camelCase.
+   */
+  static toCamelCase(str) {
+    return str.replace(/[-_](.)/g, (_, char) => char.toUpperCase()).replace(/^(.)/, (char) => char.toLowerCase());
+  }
+};
+
+// src/utils/objects.ts
+var IgniterAgentObjectUtils = class _IgniterAgentObjectUtils {
+  /**
+   * Deep merges two objects.
+   */
+  static deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+      const sourceValue = source[key];
+      const targetValue = target[key];
+      if (sourceValue !== null && typeof sourceValue === "object" && !Array.isArray(sourceValue) && targetValue !== null && typeof targetValue === "object" && !Array.isArray(targetValue)) {
+        result[key] = _IgniterAgentObjectUtils.deepMerge(
+          targetValue,
+          sourceValue
+        );
+      } else {
+        result[key] = sourceValue;
+      }
+    }
+    return result;
+  }
+  /**
+   * Picks specified keys from an object.
+   */
+  static pick(obj, keys) {
+    const result = {};
+    for (const key of keys) {
+      if (key in obj) {
+        result[key] = obj[key];
+      }
+    }
+    return result;
+  }
+  /**
+   * Omits specified keys from an object.
+   */
+  static omit(obj, keys) {
+    const result = { ...obj };
+    for (const key of keys) {
+      delete result[key];
+    }
+    return result;
+  }
+};
+
+// src/utils/async.ts
+var IgniterAgentAsyncUtils = class _IgniterAgentAsyncUtils {
+  /**
+   * Delays execution for a specified duration.
+   */
+  static delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  /**
+   * Retries an async function with exponential backoff.
+   */
+  static async retry(fn, options = {}) {
+    const {
+      maxAttempts = 3,
+      baseDelay = 1e3,
+      maxDelay = 3e4,
+      onRetry
+    } = options;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        if (attempt === maxAttempts) {
+          throw lastError;
+        }
+        onRetry?.(attempt, lastError);
+        const delayMs = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
+        await _IgniterAgentAsyncUtils.delay(delayMs);
+      }
+    }
+    throw lastError;
+  }
+};
+
+// src/utils/validation.ts
+var IgniterAgentValidationUtils = class {
+  /**
+   * Checks if a value is defined (not null or undefined).
+   */
+  static isDefined(value) {
+    return value !== null && value !== void 0;
+  }
+  /**
+   * Checks if a value is a non-empty string.
+   */
+  static isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+  }
+  /**
+   * Checks if a value is a plain object.
+   */
+  static isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+  }
+};
+
+// src/utils/context.ts
+var IgniterAgentContext = class {
+  /**
+   * Private constructor to prevent instantiation.
+   * This is a static-only utility class.
+   */
+  constructor() {
+  }
+  /**
+   * Creates an execution context to pass to AI SDK's experimental_context.
+   *
+   * Your context object is spread at the top level, merged with writer and metadata.
+   * This means you can access your fields directly without a wrapper.
+   *
+   * @template TContext - Your custom context type (must be an object)
+   * @param options - The context creation options
+   * @returns The merged execution context ready for AI SDK
+   *
+   * @example Basic usage
+   * ```typescript
+   * const context = IgniterAgentContext.create({
+   *   context: { userId: '123', db: database, permissions: ['read', 'write'] },
+   *   writer: streamWriter
+   * });
+   * // Access in tools: executionOptions.experimental_context.userId
+   * ```
+   *
+   * @example With typed context
+   * ```typescript
+   * interface MyAppContext {
+   *   tenant: string;
+   *   workspace: string;
+   *   features: string[];
+   * }
+   *
+   * const context = IgniterAgentContext.create<MyAppContext>({
+   *   context: { tenant: 'acme', workspace: 'main', features: ['analytics'] },
+   *   writer: streamWriter
+   * });
+   * // Access in tools: executionOptions.experimental_context.tenant
+   * ```
+   *
+   * @example With metadata for tracing
+   * ```typescript
+   * const context = IgniterAgentContext.create({
+   *   context: { userId: '123', tenantId: 'acme' },
+   *   writer: streamWriter,
+   *   metadata: { agent: 'reports', requestId: 'req_123' }
+   * });
+   * ```
+   */
+  static create(options) {
+    return {
+      ...options.context,
+      writer: options.writer,
+      metadata: {
+        startTime: /* @__PURE__ */ new Date(),
+        ...options.metadata
+      }
+    };
+  }
+  /**
+   * Gets your custom context from execution options.
+   *
+   * Your context fields are available directly in experimental_context (no wrapper).
+   * This helper provides type-safe access.
+   *
+   * @template T - Your custom context type (object)
+   * @param executionOptions - Tool execution options from AI SDK
+   * @returns Your custom context or undefined if not available
+   *
+   * @example Direct access (no helper needed)
+   * ```typescript
+   * export const myTool = tool({
+   *   execute: async (params, executionOptions) => {
+   *     // Access fields directly
+   *     const userId = executionOptions.experimental_context.userId;
+   *     const db = executionOptions.experimental_context.db;
+   *   }
+   * });
+   * ```
+   *
+   * @example With typed helper
+   * ```typescript
+   * interface AppContext {
+   *   userId: string;
+   *   tenantId: string;
+   *   db: Database;
+   * }
+   *
+   * export const myTool = tool({
+   *   execute: async (params, executionOptions) => {
+   *     const ctx = IgniterAgentContext.get<AppContext>(executionOptions);
+   *     if (ctx) {
+   *       const user = await ctx.db.users.findOne(ctx.userId);
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  static get(executionOptions) {
+    return executionOptions?.experimental_context;
+  }
+};
+
 // src/core/agent.ts
 var IgniterAgentCore = class {
   constructor(agent) {
@@ -914,101 +1158,107 @@ var IgniterAgentCore = class {
     }
   }
   /**
-   * Generates a response from the agent.
-   */
-  async generate(input) {
-    const startTime = Date.now();
-    const attributes = {
-      "ctx.agent.name": this.getName(),
-      "ctx.generation.inputMessages": Array.isArray(input.messages) ? input.messages.length : void 0,
-      "ctx.generation.streamed": false
-    };
-    this.logger?.debug("IgniterAgent.generate started", attributes);
-    this.telemetry?.emit("igniter.agent.generation.generate.started", {
-      level: "debug",
-      attributes
+   * Generates a response for the given message or messages.
+   *
+   * @description
+   * Accepts either a single `message` or an array of `messages`.
+   * When both are provided, `message` takes precedence.
+   *
+   * @param params - The parameters for the generate call.
+   * @returns The generated response.
+   */
+  async generate(params) {
+    const { message, messages } = this.resolveMessageInput(params);
+    const requestId = `req_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+    const historyMessages = await this.initializeChatMemory({
+      chatId: params.chatId,
+      userId: params.userId,
+      agentId: this.getName(),
+      message
     });
+    const agent = this.prepare({
+      chatId: params.chatId,
+      userId: params.userId,
+      agentId: this.getName(),
+      message,
+      requestId,
+      context: params.context,
+      streamed: false
+    });
+    const inputMessages = params.message ? [message] : messages;
+    const resolvedMessages = historyMessages ? [...historyMessages, ...inputMessages] : inputMessages;
     try {
-      const agent = this.getAgentInstanceWithContext(
-        input.options
-      );
-      const result = await agent.generate(input);
-      const durationMs = Date.now() - startTime;
-      this.telemetry?.emit("igniter.agent.generation.generate.success", {
-        level: "debug",
-        attributes: {
-          ...attributes,
-          "ctx.generation.durationMs": durationMs
-        }
+      return await agent.generate({
+        abortSignal: params.abortSignal,
+        options: params.options,
+        messages: resolvedMessages,
+        prompt: params.prompt
       });
-      this.logger?.success?.("IgniterAgent.generate success", {
-        ...attributes,
-        durationMs
-      });
-      return result;
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
       this.telemetry?.emit("igniter.agent.generation.generate.error", {
         level: "error",
         attributes: {
-          ...attributes,
+          "ctx.agent.name": this.getName(),
+          "ctx.agent.chatId": params.chatId,
+          "ctx.agent.userId": params.userId,
+          "ctx.generation.streamed": false,
           ...this.getErrorAttributes(err, "generation.generate")
         }
       });
-      this.logger?.error("IgniterAgent.generate failed", err);
       throw err;
     }
   }
   /**
-   * Streams a response from the agent.
-   */
-  async stream(input) {
-    const startTime = Date.now();
-    const attributes = {
-      "ctx.agent.name": this.getName(),
-      "ctx.generation.inputMessages": Array.isArray(input.messages) ? input.messages.length : void 0,
-      "ctx.generation.streamed": true
-    };
-    this.logger?.debug("IgniterAgent.stream started", attributes);
-    this.telemetry?.emit("igniter.agent.generation.stream.started", {
-      level: "debug",
-      attributes
+   * Streams a response for the given message or messages.
+   *
+   * @description
+   * Accepts either a single `message` or an array of `messages`.
+   * When both are provided, `message` takes precedence.
+   *
+   * @param params - The parameters for the stream call.
+   * @returns The streaming response.
+   */
+  async stream(params) {
+    const { message, messages } = this.resolveMessageInput(params);
+    const requestId = `req_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+    const historyMessages = await this.initializeChatMemory({
+      chatId: params.chatId,
+      userId: params.userId,
+      agentId: this.getName(),
+      message
     });
+    const agent = this.prepare({
+      chatId: params.chatId,
+      userId: params.userId,
+      agentId: this.getName(),
+      message,
+      requestId,
+      context: params.context,
+      streamed: true
+    });
+    const inputMessages = params.message ? [message] : messages;
+    const resolvedMessages = historyMessages ? [...historyMessages, ...inputMessages] : inputMessages;
     try {
-      const agent = this.getAgentInstanceWithContext(
-        input.options
-      );
-      const result = await agent.stream(input);
-      const durationMs = Date.now() - startTime;
-      const emitChunk = () => {
-        this.telemetry?.emit("igniter.agent.generation.stream.chunk", {
-          level: "debug",
-          attributes
-        });
-      };
-      const wrapped = this.wrapStreamResult(result, emitChunk);
-      this.telemetry?.emit("igniter.agent.generation.stream.success", {
-        level: "debug",
-        attributes: {
-          ...attributes,
-          "ctx.generation.durationMs": durationMs
-        }
-      });
-      this.logger?.success?.("IgniterAgent.stream success", {
-        ...attributes,
-        durationMs
+      return await agent.stream({
+        abortSignal: params.abortSignal,
+        experimental_transform: params.experimental_transform,
+        options: params.options,
+        messages: resolvedMessages,
+        prompt: params.prompt
       });
-      return wrapped;
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
       this.telemetry?.emit("igniter.agent.generation.stream.error", {
         level: "error",
         attributes: {
-          ...attributes,
+          "ctx.agent.name": this.getName(),
+          "ctx.agent.chatId": params.chatId,
+          "ctx.agent.userId": params.userId,
+          "ctx.generation.streamed": true,
           ...this.getErrorAttributes(err, "generation.stream")
         }
       });
-      this.logger?.error("IgniterAgent.stream failed", err);
       throw err;
     }
   }
@@ -1040,109 +1290,16 @@ var IgniterAgentCore = class {
    * Gets all registered tools from all toolsets.
    */
   getTools() {
-    const toolsets = this.getToolsets();
-    const allTools = {};
-    for (const toolset of Object.values(toolsets)) {
-      for (const [toolName, tool2] of Object.entries(toolset.tools)) {
-        const wrapped = this.wrapToolExecution(toolset.name, toolName, tool2);
-        allTools[toolName] = wrapped;
-      }
-    }
+    const allTools = this.initializeTools({
+      chatId: "",
+      userId: "",
+      agentId: this.getName()
+    });
     return allTools;
   }
-  wrapToolExecution(toolsetName, toolName, tool2) {
-    if (!tool2 || !tool2.execute || typeof tool2.execute !== "function") {
-      return tool2;
-    }
-    const execute = tool2.execute;
-    const fullName = `${toolsetName}.${toolName}`;
-    const agentName = this.getName();
-    return {
-      ...tool2,
-      execute: async (input, options) => {
-        const startTime = Date.now();
-        this.hooks.onToolCallStart?.(agentName, fullName, input);
-        this.telemetry?.emit("igniter.agent.tool.execute.started", {
-          level: "debug",
-          attributes: {
-            "ctx.agent.name": agentName,
-            "ctx.tool.toolset": toolsetName,
-            "ctx.tool.name": toolName,
-            "ctx.tool.fullName": fullName
-          }
-        });
-        this.logger?.debug("IgniterAgent.tool.execute started", {
-          agent: agentName,
-          tool: fullName
-        });
-        try {
-          const result = await execute(input, options);
-          const durationMs = Date.now() - startTime;
-          this.hooks.onToolCallEnd?.(agentName, fullName, result);
-          this.telemetry?.emit("igniter.agent.tool.execute.success", {
-            level: "debug",
-            attributes: {
-              "ctx.agent.name": agentName,
-              "ctx.tool.toolset": toolsetName,
-              "ctx.tool.name": toolName,
-              "ctx.tool.fullName": fullName,
-              "ctx.tool.durationMs": durationMs
-            }
-          });
-          this.logger?.success?.("IgniterAgent.tool.execute success", {
-            agent: agentName,
-            tool: fullName,
-            durationMs
-          });
-          return result;
-        } catch (error) {
-          const err = error instanceof Error ? error : new Error(String(error));
-          this.hooks.onToolCallError?.(agentName, fullName, err);
-          this.telemetry?.emit("igniter.agent.tool.execute.error", {
-            level: "error",
-            attributes: {
-              "ctx.agent.name": agentName,
-              "ctx.tool.toolset": toolsetName,
-              "ctx.tool.name": toolName,
-              "ctx.tool.fullName": fullName,
-              ...this.getErrorAttributes(err, "tool.execute")
-            }
-          });
-          this.logger?.error("IgniterAgent.tool.execute failed", err);
-          throw err;
-        }
-      }
-    };
-  }
-  wrapStreamResult(result, onChunk) {
-    if (!result) {
-      return result;
-    }
-    if (typeof result[Symbol.asyncIterator] === "function") {
-      const iterable = result;
-      return {
-        [Symbol.asyncIterator]: async function* () {
-          for await (const chunk of iterable) {
-            onChunk();
-            yield chunk;
-          }
-        }
-      };
-    }
-    const maybeTextStream = result.textStream;
-    if (maybeTextStream && typeof maybeTextStream[Symbol.asyncIterator] === "function") {
-      return {
-        ...result,
-        textStream: (async function* () {
-          for await (const chunk of maybeTextStream) {
-            onChunk();
-            yield chunk;
-          }
-        })()
-      };
-    }
-    return result;
-  }
+  /**
+   * Gets error attributes for telemetry.
+   */
   getErrorAttributes(error, operation) {
     return {
       "ctx.error.code": error.code ?? error.name ?? "IGNITER_AGENT_UNKNOWN_ERROR" /* UNKNOWN */,
@@ -1151,31 +1308,345 @@ var IgniterAgentCore = class {
       "ctx.error.component": "agent"
     };
   }
-  getAgentInstanceWithContext(context) {
-    const tools = this.getTools();
+  /**
+   * Gets an agent instance with the given context.
+   */
+  prepare(params) {
+    const tools = this.initializeTools({
+      chatId: params.chatId,
+      userId: params.userId,
+      agentId: this._agent.name
+    });
     if (!this._agent.model) {
       throw new IgniterAgentConfigError({
         message: "Model is required. Call withModel() before build()",
         field: "model"
       });
     }
-    if (this._agent.schema !== void 0) {
-      const parseResult = this._agent.schema.safeParse(context);
-      if (parseResult.success) {
-        context = parseResult.data;
-      } else {
-        throw new IgniterAgentError({
-          message: "Invalid context schema",
-          code: "IGNITER_AGENT_CONTEXT_SCHEMA_INVALID" /* AGENT_CONTEXT_SCHEMA_INVALID */
-        });
-      }
-    }
     return new ToolLoopAgent({
+      id: this._agent.name,
       model: this._agent.model,
-      instructions: this._agent.instructions ? this._agent.instructions.build(context) : "",
+      instructions: this._agent.instructions.getTemplate(),
       tools,
-      callOptionsSchema: this._agent.schema
+      callOptionsSchema: this._agent.schema,
+      prepareCall: async (options) => {
+        const isStreamed = Boolean(params.streamed);
+        const eventPrefix = isStreamed ? "stream" : "generate";
+        this.logger?.debug(`IgniterAgent.${eventPrefix} started`, {
+          "ctx.agent.name": this.getName(),
+          "ctx.agent.chatId": params.chatId,
+          "ctx.agent.userId": params.userId,
+          "ctx.generation.inputMessages": options.messages?.length || 0,
+          "ctx.generation.streamed": isStreamed
+        });
+        this.telemetry?.emit(`igniter.agent.generation.${eventPrefix}.started`, {
+          level: "debug",
+          attributes: {
+            "ctx.agent.name": this.getName(),
+            "ctx.agent.chatId": params.chatId,
+            "ctx.agent.userId": params.userId,
+            "ctx.generation.inputMessages": options.messages?.length || 0,
+            "ctx.generation.streamed": isStreamed
+          }
+        });
+        if (this._agent.instructions && options.options) {
+          if (this._agent.memory?.working?.enabled && this._agent.memory.working.template) {
+            this._agent.instructions = this._agent.instructions.addAppended(
+              "memory",
+              this._agent.memory.working.template
+            );
+          }
+          options.instructions = this._agent.instructions.build(options.options);
+        }
+        if (params.prepareCall) {
+          return params.prepareCall(options);
+        }
+        return options;
+      },
+      onStepFinish: async (step) => {
+        if (params.streamed) {
+          return;
+        }
+        this.logger?.debug("IgniterAgent.generate step", {
+          "ctx.agent.name": this.getName(),
+          "ctx.chatId": params.chatId,
+          "ctx.userId": params.userId,
+          "ctx.generation.usage.inputTokens": step.usage.inputTokens,
+          "ctx.generation.usage.outputTokens": step.usage.outputTokens,
+          "ctx.generation.usage.totalTokens": step.usage.totalTokens,
+          "ctx.generation.streamed": false
+        });
+        this.telemetry?.emit("igniter.agent.generation.generate.step", {
+          level: "debug",
+          attributes: {
+            "ctx.agent.name": this.getName(),
+            "ctx.chatId": params.chatId,
+            "ctx.userId": params.userId,
+            "ctx.generation.usage.inputTokens": step.usage.inputTokens,
+            "ctx.generation.usage.outputTokens": step.usage.outputTokens,
+            "ctx.generation.usage.totalTokens": step.usage.totalTokens,
+            "ctx.generation.streamed": false
+          }
+        });
+      },
+      onFinish: (result) => {
+        if (params.streamed) {
+          return;
+        }
+        this.logger?.debug("IgniterAgent.generate success", {
+          "ctx.agent.name": this.getName(),
+          "ctx.chatId": params.chatId,
+          "ctx.userId": params.userId,
+          "ctx.generation.usage.inputTokens": result.usage.inputTokens,
+          "ctx.generation.usage.outputTokens": result.usage.outputTokens,
+          "ctx.generation.usage.totalTokens": result.usage.totalTokens,
+          "ctx.generation.streamed": false
+        });
+        this.telemetry?.emit("igniter.agent.generation.generate.success", {
+          level: "debug",
+          attributes: {
+            "ctx.agent.name": this.getName(),
+            "ctx.chatId": params.chatId,
+            "ctx.userId": params.userId,
+            "ctx.generation.usage.inputTokens": result.usage.inputTokens,
+            "ctx.generation.usage.outputTokens": result.usage.outputTokens,
+            "ctx.generation.usage.totalTokens": result.usage.totalTokens,
+            "ctx.generation.streamed": false
+          }
+        });
+      },
+      activeTools: params.activeTools,
+      experimental_context: IgniterAgentContext.create({
+        context: params.context,
+        memory: this._agent.memory,
+        metadata: {
+          agent: this.getName(),
+          chatId: params.chatId,
+          userId: params.userId,
+          requestId: params.requestId,
+          startTime: /* @__PURE__ */ new Date()
+        }
+      }),
+      experimental_download: params.experimental_download,
+      experimental_repairToolCall: params.experimental_repairToolCall,
+      experimental_telemetry: params.experimental_telemetry,
+      frequencyPenalty: params.frequencyPenalty,
+      maxOutputTokens: params.maxOutputTokens,
+      maxRetries: params.maxRetries,
+      output: params.output,
+      prepareStep: params.prepareStep,
+      presencePenalty: params.presencePenalty,
+      providerOptions: params.providerOptions,
+      seed: params.seed,
+      stopSequences: params.stopSequences,
+      stopWhen: params.stopWhen,
+      temperature: params.temperature,
+      toolChoice: params.toolChoice,
+      topK: params.topK,
+      topP: params.topP,
+      headers: params.headers
+    });
+  }
+  async initializeChatMemory({
+    chatId,
+    userId,
+    agentId,
+    message
+  }) {
+    if (!this.memory || !this._agent.memory?.chats?.enabled) {
+      return;
+    }
+    let chat = await this.memory.getChat(chatId);
+    const { generateSuggestions, generateTitle } = this._agent.memory.chats;
+    if (!chat) {
+      let title = "New conversation";
+      if (generateTitle?.enabled) {
+        const response = await generateText({
+          model: generateTitle.model || this._agent.model,
+          messages: [message],
+          system: generateTitle.instructions || "Analyze the chat history and generate a title for the chat",
+          output: Output.object({
+            schema: z.object({
+              title: z.string().min(1).max(100)
+            })
+          })
+        });
+        title = response.output.title;
+      }
+      await this.memory.saveChat({
+        chatId,
+        createdAt: /* @__PURE__ */ new Date(),
+        updatedAt: /* @__PURE__ */ new Date(),
+        messageCount: 0,
+        title
+      });
+      chat = await this.memory.getChat(chatId);
+    }
+    if (!chat) {
+      throw new IgniterAgentError({
+        code: "IGNITER_AGENT_MISSING_REQUIRED" /* MISSING_REQUIRED */,
+        message: "Chat not found and could not be created",
+        metadata: {
+          chatId,
+          userId,
+          agentId
+        }
+      });
+    }
+    if (!this._agent.memory?.history?.enabled) {
+      return;
+    }
+    const messages = await this.memory.getMessages({
+      chatId,
+      limit: this._agent.memory?.history?.limit
     });
+    return messages;
+  }
+  resolveMessageInput(params) {
+    const message = params.message ?? params.messages?.[params.messages.length - 1];
+    if (!message) {
+      throw new IgniterAgentError({
+        code: "IGNITER_AGENT_MISSING_REQUIRED" /* MISSING_REQUIRED */,
+        message: "Either 'message' or 'messages' must be provided",
+        metadata: {
+          missing: "message"
+        }
+      });
+    }
+    const messages = params.message ? [message] : params.messages || [];
+    return { message, messages };
+  }
+  initializeTools({
+    chatId,
+    userId,
+    agentId
+  }) {
+    const toolsets = this.getToolsets();
+    const allTools = {};
+    for (const toolset of Object.values(toolsets)) {
+      for (const [toolName, tool3] of Object.entries(toolset.tools)) {
+        allTools[toolName] = {
+          ...tool3,
+          execute: async (args, options) => {
+            if (!tool3.execute) {
+              throw new IgniterAgentError({
+                code: "IGNITER_AGENT_MISSING_REQUIRED" /* MISSING_REQUIRED */,
+                message: "Tool does not have an execute function",
+                metadata: { toolName }
+              });
+            }
+            try {
+              const startTime = Date.now();
+              const toolsetName = toolset.name ?? "unknown";
+              const toolAttributes = {
+                "ctx.agent.name": this.getName(),
+                "ctx.tool.toolset": toolsetName,
+                "ctx.tool.name": toolName,
+                "ctx.tool.fullName": `${toolsetName}.${toolName}`
+              };
+              this.hooks.onToolCallStart?.(this.getName(), toolName, args);
+              this.telemetry?.emit("igniter.agent.tool.execute.started", {
+                level: "debug",
+                attributes: toolAttributes
+              });
+              const result = await tool3.execute(args, {
+                ...options,
+                experimental_context: {
+                  ...options.experimental_context || {},
+                  chatId,
+                  userId,
+                  agentId
+                }
+              });
+              this.telemetry?.emit("igniter.agent.tool.execute.success", {
+                level: "debug",
+                attributes: {
+                  ...toolAttributes,
+                  "ctx.tool.durationMs": Date.now() - startTime
+                }
+              });
+              this.hooks.onToolCallEnd?.(this.getName(), toolName, result);
+              return {
+                success: true,
+                result
+              };
+            } catch (error) {
+              const err = error instanceof Error ? error : new Error(String(error));
+              const toolsetName = toolset.name ?? "unknown";
+              this.telemetry?.emit("igniter.agent.tool.execute.error", {
+                level: "error",
+                attributes: {
+                  "ctx.agent.name": this.getName(),
+                  "ctx.tool.toolset": toolsetName,
+                  "ctx.tool.name": toolName,
+                  "ctx.tool.fullName": `${toolsetName}.${toolName}`,
+                  ...this.getErrorAttributes(err, "tool.execute")
+                }
+              });
+              this.hooks.onToolCallError?.(this.getName(), toolName, err);
+              throw err;
+            }
+          }
+        };
+      }
+    }
+    if (this._agent.memory?.working?.enabled) {
+      const scope = this._agent.memory?.working.scope;
+      const isChatMemory = scope === "chat";
+      const identifier = isChatMemory ? chatId : userId;
+      allTools["internal__update_working_memory"] = tool({
+        description: "Remember important information for later in the conversation",
+        inputSchema: z.object({
+          content: z.string().describe("Updated working memory following the template structure")
+        }),
+        execute: async (args, options) => {
+          const { content } = args;
+          if (this.memory) {
+            await this.memory.updateWorkingMemory({
+              scope,
+              identifier,
+              content
+            });
+          } else {
+            await this._agent.memory?.provider.updateWorkingMemory({
+              scope,
+              identifier,
+              content
+            });
+          }
+          return {
+            success: true
+          };
+        }
+      });
+      if (this._agent.memory?.history?.enabled) {
+        allTools["internal__search_on_chat_history"] = tool({
+          description: "Search on chat history",
+          inputSchema: z.object({
+            content: z.string().describe("Search query"),
+            limit: z.number().optional().describe("Limit number of results"),
+            dateFrom: z.date().optional().describe("Search from date"),
+            dateTo: z.date().optional().describe("Search to date")
+          }),
+          execute: async (args, options) => {
+            const { content, limit, dateFrom, dateTo } = args;
+            const result = await this._agent.memory?.provider?.search?.({
+              chatId,
+              userId,
+              limit,
+              search: content,
+              dateFrom,
+              dateTo
+            });
+            return {
+              success: true,
+              result
+            };
+          }
+        });
+      }
+    }
+    return allTools;
   }
   async initializeMCPClient(mcpConfig) {
     if (this._agent.toolsets[mcpConfig.name]) {
@@ -1355,8 +1826,9 @@ var resolvePath = (value, path) => {
   }, value);
 };
 var IgniterAgentPromptBuilder = class _IgniterAgentPromptBuilder {
-  constructor(template) {
+  constructor(template, appended) {
     this.template = template;
+    this.appended = appended;
   }
   /**
    * Creates a new prompt builder.
@@ -1364,9 +1836,10 @@ var IgniterAgentPromptBuilder = class _IgniterAgentPromptBuilder {
    * @param template - Prompt template string with {{placeholders}}
    * @returns A new prompt builder instance
    */
-  static create(template) {
+  static create(template, appended = {}) {
     return new _IgniterAgentPromptBuilder(
-      template
+      template,
+      appended
     );
   }
   /**
@@ -1376,10 +1849,53 @@ var IgniterAgentPromptBuilder = class _IgniterAgentPromptBuilder {
    * @returns The resolved prompt string
    */
   build(context) {
-    return this.template.replace(TEMPLATE_PATTERN, (_match, path) => {
+    const resolveTemplate = (template) => template.replace(TEMPLATE_PATTERN, (_match, path) => {
       const value = resolvePath(context, String(path));
       return value === void 0 || value === null ? "" : String(value);
     });
+    const appendedTemplates = Object.values(this.appended).map((prompt) => {
+      if (typeof prompt === "string") {
+        return resolveTemplate(prompt);
+      }
+      if (prompt && typeof prompt === "object" && "build" in prompt) {
+        return prompt.build(context);
+      }
+      return "";
+    });
+    const appendedString = appendedTemplates.filter(Boolean).join("\n\n");
+    const templateString = resolveTemplate(this.template);
+    if (!appendedString) {
+      return templateString;
+    }
+    return templateString + "\n\n" + appendedString;
+  }
+  /**
+   * Appends another prompt template to this one.
+   */
+  addAppended(key, prompt) {
+    return new _IgniterAgentPromptBuilder(
+      this.template,
+      {
+        ...this.appended,
+        [key]: prompt
+      }
+    );
+  }
+  /**
+   * Removes an appended prompt template from this one.
+   */
+  removeAppended(key) {
+    const { [key]: _, ...rest } = this.appended;
+    return new _IgniterAgentPromptBuilder(
+      this.template,
+      rest
+    );
+  }
+  /**
+   * Returns the appended prompts.
+   */
+  getAppended() {
+    return this.appended;
   }
   /**
    * Returns the raw prompt template string.
@@ -1655,13 +2171,13 @@ var IgniterAgentBuilder = class _IgniterAgentBuilder {
    *
    * // Context is type-safe when calling generate
    * await agent.generate({
-   *   messages: [...],
-   *   options: {
-   *     userId: 'user_123',
-   *     chatId: 'chat_456',
+   *   chatId: 'chat_456',
+   *   userId: 'user_123',
+   *   context: {
    *     userRole: 'admin',
    *     preferences: { language: 'pt' }
-   *   }
+   *   },
+   *   message: { role: 'user', content: 'Hello!' }
    * });
    * ```
    *
@@ -1791,7 +2307,10 @@ var IgniterAgentBuilder = class _IgniterAgentBuilder {
    *
    * // Generate a response
    * const result = await agent.generate({
-   *   messages: [{ role: 'user', content: 'Hello!' }]
+   *   chatId: 'chat_123',
+   *   userId: 'user_123',
+   *   context: {},
+   *   message: { role: 'user', content: 'Hello!' }
    * });
    *
    * // Access configuration
@@ -3724,139 +4243,6 @@ var IgniterAgentJSONFileAdapter = class _IgniterAgentJSONFileAdapter {
   }
 };
 
-// src/utils/strings.ts
-var IgniterAgentStringUtils = class {
-  /**
-   * Generates a unique identifier.
-   */
-  static generateId(prefix) {
-    const random = Math.random().toString(36).substring(2, 12);
-    return prefix ? `${prefix}_${random}` : random;
-  }
-  /**
-   * Truncates a string to a maximum length.
-   */
-  static truncate(str, maxLength, suffix = "...") {
-    if (str.length <= maxLength) return str;
-    return str.slice(0, maxLength - suffix.length) + suffix;
-  }
-  /**
-   * Converts a string to snake_case.
-   */
-  static toSnakeCase(str) {
-    return str.replace(/([A-Z])/g, "_$1").toLowerCase().replace(/^_/, "");
-  }
-  /**
-   * Converts a string to camelCase.
-   */
-  static toCamelCase(str) {
-    return str.replace(/[-_](.)/g, (_, char) => char.toUpperCase()).replace(/^(.)/, (char) => char.toLowerCase());
-  }
-};
-
-// src/utils/objects.ts
-var IgniterAgentObjectUtils = class _IgniterAgentObjectUtils {
-  /**
-   * Deep merges two objects.
-   */
-  static deepMerge(target, source) {
-    const result = { ...target };
-    for (const key in source) {
-      const sourceValue = source[key];
-      const targetValue = target[key];
-      if (sourceValue !== null && typeof sourceValue === "object" && !Array.isArray(sourceValue) && targetValue !== null && typeof targetValue === "object" && !Array.isArray(targetValue)) {
-        result[key] = _IgniterAgentObjectUtils.deepMerge(
-          targetValue,
-          sourceValue
-        );
-      } else {
-        result[key] = sourceValue;
-      }
-    }
-    return result;
-  }
-  /**
-   * Picks specified keys from an object.
-   */
-  static pick(obj, keys) {
-    const result = {};
-    for (const key of keys) {
-      if (key in obj) {
-        result[key] = obj[key];
-      }
-    }
-    return result;
-  }
-  /**
-   * Omits specified keys from an object.
-   */
-  static omit(obj, keys) {
-    const result = { ...obj };
-    for (const key of keys) {
-      delete result[key];
-    }
-    return result;
-  }
-};
-
-// src/utils/async.ts
-var IgniterAgentAsyncUtils = class _IgniterAgentAsyncUtils {
-  /**
-   * Delays execution for a specified duration.
-   */
-  static delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-  /**
-   * Retries an async function with exponential backoff.
-   */
-  static async retry(fn, options = {}) {
-    const {
-      maxAttempts = 3,
-      baseDelay = 1e3,
-      maxDelay = 3e4,
-      onRetry
-    } = options;
-    let lastError;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-      try {
-        return await fn();
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-        if (attempt === maxAttempts) {
-          throw lastError;
-        }
-        onRetry?.(attempt, lastError);
-        const delayMs = Math.min(baseDelay * Math.pow(2, attempt - 1), maxDelay);
-        await _IgniterAgentAsyncUtils.delay(delayMs);
-      }
-    }
-    throw lastError;
-  }
-};
-
-// src/utils/validation.ts
-var IgniterAgentValidationUtils = class {
-  /**
-   * Checks if a value is defined (not null or undefined).
-   */
-  static isDefined(value) {
-    return value !== null && value !== void 0;
-  }
-  /**
-   * Checks if a value is a non-empty string.
-   */
-  static isNonEmptyString(value) {
-    return typeof value === "string" && value.length > 0;
-  }
-  /**
-   * Checks if a value is a plain object.
-   */
-  static isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
-  }
-};
-
-export { IgniterAgent, IgniterAgentAdapterError, IgniterAgentAsyncUtils, IgniterAgentBuilder, IgniterAgentConfigError, IgniterAgentCore, IgniterAgentError, IgniterAgentErrorCode, IgniterAgentInMemoryAdapter, IgniterAgentJSONFileAdapter, IgniterAgentMCPBuilder, IgniterAgentMCPClient, IgniterAgentMCPError, IgniterAgentManager, IgniterAgentManagerBuilder, IgniterAgentManagerCore, IgniterAgentMemoryCore, IgniterAgentMemoryError, IgniterAgentObjectUtils, IgniterAgentPrompt, IgniterAgentPromptBuilder, IgniterAgentStringUtils, IgniterAgentTool, IgniterAgentToolBuilder, IgniterAgentToolError, IgniterAgentToolset, IgniterAgentToolsetBuilder, IgniterAgentValidationUtils, isIgniterAgentError, isIgniterAgentMCPError, isIgniterAgentToolError, wrapError };
+export { IgniterAgent, IgniterAgentAdapterError, IgniterAgentAsyncUtils, IgniterAgentBuilder, IgniterAgentConfigError, IgniterAgentContext, IgniterAgentCore, IgniterAgentError, IgniterAgentErrorCode, IgniterAgentInMemoryAdapter, IgniterAgentJSONFileAdapter, IgniterAgentMCPBuilder, IgniterAgentMCPClient, IgniterAgentMCPError, IgniterAgentManager, IgniterAgentManagerBuilder, IgniterAgentManagerCore, IgniterAgentMemoryCore, IgniterAgentMemoryError, IgniterAgentObjectUtils, IgniterAgentPrompt, IgniterAgentPromptBuilder, IgniterAgentStringUtils, IgniterAgentTool, IgniterAgentToolBuilder, IgniterAgentToolError, IgniterAgentToolset, IgniterAgentToolsetBuilder, IgniterAgentValidationUtils, isIgniterAgentError, isIgniterAgentMCPError, isIgniterAgentToolError, wrapError };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map