@igniter-js/agents 0.1.0

package/dist/index.mjs

@@ -0,0 +1,4011 @@
+import { IgniterError } from '@igniter-js/core';
+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 { IgniterTelemetryEvents } from '@igniter-js/telemetry';
+import { z } from 'zod';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+
+// src/errors/agent.error.ts
+var IgniterAgentErrorCode = /* @__PURE__ */ ((IgniterAgentErrorCode3) => {
+  IgniterAgentErrorCode3["UNKNOWN"] = "IGNITER_AGENT_UNKNOWN_ERROR";
+  IgniterAgentErrorCode3["INVALID_CONFIG"] = "IGNITER_AGENT_INVALID_CONFIG";
+  IgniterAgentErrorCode3["MISSING_REQUIRED"] = "IGNITER_AGENT_MISSING_REQUIRED";
+  IgniterAgentErrorCode3["AGENT_NOT_INITIALIZED"] = "IGNITER_AGENT_NOT_INITIALIZED";
+  IgniterAgentErrorCode3["AGENT_MODEL_MISSING"] = "IGNITER_AGENT_MODEL_MISSING";
+  IgniterAgentErrorCode3["AGENT_BUILD_FAILED"] = "IGNITER_AGENT_BUILD_FAILED";
+  IgniterAgentErrorCode3["MCP_CONNECTION_FAILED"] = "IGNITER_AGENT_MCP_CONNECTION_FAILED";
+  IgniterAgentErrorCode3["MCP_CLIENT_NOT_FOUND"] = "IGNITER_AGENT_MCP_CLIENT_NOT_FOUND";
+  IgniterAgentErrorCode3["MCP_TOOL_ERROR"] = "IGNITER_AGENT_MCP_TOOL_ERROR";
+  IgniterAgentErrorCode3["MCP_INVALID_CONFIG"] = "IGNITER_AGENT_MCP_INVALID_CONFIG";
+  IgniterAgentErrorCode3["TOOL_EXECUTION_FAILED"] = "IGNITER_AGENT_TOOL_EXECUTION_FAILED";
+  IgniterAgentErrorCode3["TOOL_NOT_FOUND"] = "IGNITER_AGENT_TOOL_NOT_FOUND";
+  IgniterAgentErrorCode3["TOOL_VALIDATION_FAILED"] = "IGNITER_AGENT_TOOL_VALIDATION_FAILED";
+  IgniterAgentErrorCode3["AGENT_CONTEXT_SCHEMA_INVALID"] = "IGNITER_AGENT_CONTEXT_SCHEMA_INVALID";
+  IgniterAgentErrorCode3["MEMORY_PROVIDER_ERROR"] = "IGNITER_AGENT_MEMORY_PROVIDER_ERROR";
+  IgniterAgentErrorCode3["MEMORY_NOT_FOUND"] = "IGNITER_AGENT_MEMORY_NOT_FOUND";
+  IgniterAgentErrorCode3["MEMORY_UPDATE_FAILED"] = "IGNITER_AGENT_MEMORY_UPDATE_FAILED";
+  IgniterAgentErrorCode3["ADAPTER_CONNECTION_FAILED"] = "IGNITER_AGENT_ADAPTER_CONNECTION_FAILED";
+  IgniterAgentErrorCode3["ADAPTER_OPERATION_FAILED"] = "IGNITER_AGENT_ADAPTER_OPERATION_FAILED";
+  IgniterAgentErrorCode3["ADAPTER_NOT_INITIALIZED"] = "IGNITER_AGENT_ADAPTER_NOT_INITIALIZED";
+  return IgniterAgentErrorCode3;
+})(IgniterAgentErrorCode || {});
+var IgniterAgentError = class extends IgniterError {
+  /**
+   * Creates a new IgniterAgentError.
+   *
+   * @param options - Error configuration options
+   */
+  constructor(options) {
+    super({
+      message: options.message,
+      code: options.code,
+      statusCode: options.statusCode ?? 500,
+      causer: options.causer,
+      details: options.details,
+      metadata: options.metadata,
+      logger: options.logger,
+      cause: options.cause
+    });
+    this.name = "IgniterAgentError";
+  }
+};
+var IgniterAgentConfigError = class extends IgniterAgentError {
+  constructor(options) {
+    super({
+      ...options,
+      code: "IGNITER_AGENT_INVALID_CONFIG" /* INVALID_CONFIG */,
+      metadata: { ...options.metadata, field: options.field }
+    });
+    this.name = "IgniterAgentConfigError";
+    this.field = options.field;
+  }
+};
+var IgniterAgentMCPError = class extends IgniterAgentError {
+  constructor(options) {
+    super({
+      ...options,
+      metadata: { ...options.metadata, mcpName: options.mcpName }
+    });
+    this.name = "IgniterAgentMCPError";
+    this.mcpName = options.mcpName;
+  }
+};
+var IgniterAgentToolError = class extends IgniterAgentError {
+  constructor(options) {
+    super({
+      ...options,
+      code: "IGNITER_AGENT_TOOL_EXECUTION_FAILED" /* TOOL_EXECUTION_FAILED */,
+      metadata: { ...options.metadata, toolName: options.toolName }
+    });
+    this.name = "IgniterAgentToolError";
+    this.toolName = options.toolName;
+  }
+};
+var IgniterAgentMemoryError = class extends IgniterAgentError {
+  constructor(options) {
+    super(options);
+    this.name = "IgniterAgentMemoryError";
+  }
+};
+var IgniterAgentAdapterError = class extends IgniterAgentError {
+  constructor(options) {
+    super({
+      ...options,
+      metadata: { ...options.metadata, adapterName: options.adapterName }
+    });
+    this.name = "IgniterAgentAdapterError";
+    this.adapterName = options.adapterName;
+  }
+};
+function isIgniterAgentError(error) {
+  return error instanceof IgniterAgentError;
+}
+function isIgniterAgentMCPError(error) {
+  return error instanceof IgniterAgentMCPError;
+}
+function isIgniterAgentToolError(error) {
+  return error instanceof IgniterAgentToolError;
+}
+function wrapError(error, options = {}) {
+  if (isIgniterAgentError(error)) {
+    return error;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  const cause = error instanceof Error ? error : void 0;
+  return new IgniterAgentError({
+    message,
+    code: "IGNITER_AGENT_UNKNOWN_ERROR" /* UNKNOWN */,
+    ...options,
+    cause
+  });
+}
+
+// src/core/manager.ts
+var IgniterAgentManagerCore = class _IgniterAgentManagerCore {
+  /**
+   * Creates a new IgniterAgentManager.
+   *
+   * @param options - Manager configuration options
+   *
+   * @example
+   * ```typescript
+   * const manager = new IgniterAgentManager({
+   *   autoStart: false,
+   *   continueOnError: true
+   * });
+   * ```
+   */
+  constructor(options) {
+    /**
+     * Agent statuses.
+     * @internal
+     */
+    this._statuses = /* @__PURE__ */ new Map();
+    this._options = {
+      logger: options.logger,
+      telemetry: options.telemetry,
+      agents: options.agents ?? {},
+      autoStart: options.autoStart ?? false,
+      continueOnError: options.continueOnError ?? true,
+      onAgentStart: options.onAgentStart ?? (() => {
+      }),
+      onAgentError: options.onAgentError ?? (() => {
+      }),
+      onToolCallStart: options.onToolCallStart ?? (() => {
+      }),
+      onToolCallEnd: options.onToolCallEnd ?? (() => {
+      }),
+      onToolCallError: options.onToolCallError ?? (() => {
+      }),
+      onMCPStart: options.onMCPStart ?? (() => {
+      }),
+      onMCPError: options.onMCPError ?? (() => {
+      })
+    };
+    for (const [name, agent] of Object.entries(this._options.agents)) {
+      this.applyManagerContext(name, agent);
+      this._statuses.set(name, {
+        name,
+        status: "idle",
+        registeredAt: /* @__PURE__ */ new Date(),
+        toolsetCount: Object.keys(agent.getToolsets()).length
+      });
+    }
+  }
+  applyManagerContext(name, agent) {
+    const logger = this._options.logger;
+    const telemetry = this._options.telemetry;
+    if (logger) {
+      const scopedLogger = logger.child?.("IgniterAgent", { agent: name }) ?? logger;
+      agent.attachLogger?.(scopedLogger);
+    }
+    if (telemetry) {
+      agent.attachTelemetry?.(telemetry);
+    }
+    agent.attachHooks?.({
+      onToolCallStart: this._options.onToolCallStart,
+      onToolCallEnd: this._options.onToolCallEnd,
+      onToolCallError: this._options.onToolCallError,
+      onMCPStart: this._options.onMCPStart,
+      onMCPError: this._options.onMCPError
+    });
+  }
+  /**
+   * Creates a new IgniterAgentManager with default options.
+   * @param options - Manager configuration options
+   * @returns A new IgniterAgentManager instance
+   * @example
+   * ```typescript
+   * const manager = IgniterAgentManager.create({
+   *   autoStart: true
+   * });
+   * ```
+   */
+  static create() {
+    return new _IgniterAgentManagerCore({
+      agents: {}
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * REGISTRATION
+   * --------------------------------------------------------------------------- */
+  /**
+   * Registers an agent with the manager.
+   *
+   * @description
+   * Adds an agent to the manager's registry. If `autoStart` is enabled,
+   * the agent will be started immediately after registration.
+   *
+   * @param name - Unique name for the agent
+   * @param agent - The built agent instance
+   * @returns This manager for chaining
+   * @throws {IgniterAgentError} If an agent with the name already exists
+   *
+   * @example
+   * ```typescript
+   * manager
+   *   .register('support', supportAgent)
+   *   .register('sales', salesAgent);
+   * ```
+   */
+  register(name, agent) {
+    if (this._options.agents[name]) {
+      throw new IgniterAgentError({
+        message: `Agent '${name}' is already registered`,
+        code: "IGNITER_AGENT_INVALID_CONFIG" /* INVALID_CONFIG */,
+        causer: "IgniterAgentManager",
+        metadata: { operation: "register" }
+      });
+    }
+    this._options.agents[name] = agent;
+    this.applyManagerContext(name, agent);
+    this._statuses.set(name, {
+      name,
+      status: "idle",
+      registeredAt: /* @__PURE__ */ new Date(),
+      toolsetCount: Object.keys(agent.getToolsets()).length
+    });
+    if (this._options.autoStart) {
+      this.start(name).catch((err) => {
+        this._options.onAgentError(name, err);
+      });
+    }
+    return this;
+  }
+  /**
+   * Unregisters an agent from the manager.
+   *
+   * @param name - The agent name to unregister
+   * @returns True if the agent was unregistered
+   *
+   * @example
+   * ```typescript
+   * manager.unregister('old-agent');
+   * ```
+   */
+  unregister(name) {
+    const removed = delete this._options.agents[name];
+    this._statuses.delete(name);
+    return removed;
+  }
+  /**
+   * Checks if an agent is registered.
+   *
+   * @param name - The agent name to check
+   * @returns True if the agent is registered
+   */
+  has(name) {
+    return Boolean(this._options.agents[name]);
+  }
+  /* ---------------------------------------------------------------------------
+   * LIFECYCLE
+   * --------------------------------------------------------------------------- */
+  /**
+   * Starts a specific agent.
+   *
+   * @description
+   * Initializes the agent's MCP connections and prepares it for use.
+   *
+   * @param name - The agent name to start
+   * @returns The agent's toolsets after initialization
+   * @throws {IgniterAgentError} If the agent is not found
+   *
+   * @example
+   * ```typescript
+   * const toolsets = await manager.start('support');
+   * console.log('Connected toolsets:', Object.keys(toolsets));
+   * ```
+   */
+  async start(name) {
+    const agent = this._options.agents[name];
+    const info = this._statuses.get(name);
+    if (!agent || !info) {
+      throw new IgniterAgentError({
+        message: `Agent '${name}' is not registered`,
+        code: "IGNITER_AGENT_NOT_INITIALIZED" /* AGENT_NOT_INITIALIZED */,
+        causer: "IgniterAgentManager",
+        metadata: { operation: "start" }
+      });
+    }
+    try {
+      info.status = "starting";
+      this._options.logger?.debug("IgniterAgentManager.start started", {
+        agent: name
+      });
+      await agent.start();
+      info.status = "running";
+      info.startedAt = /* @__PURE__ */ new Date();
+      info.toolsetCount = Object.keys(agent.getToolsets()).length;
+      this._options.onAgentStart?.(name);
+      this._options.logger?.success?.("IgniterAgentManager.start success", {
+        agent: name
+      });
+      return agent;
+    } catch (error) {
+      info.status = "error";
+      info.error = error instanceof Error ? error : new Error(String(error));
+      this._options.onAgentError?.(name, info.error);
+      this._options.logger?.error("IgniterAgentManager.start failed", info.error);
+      throw error;
+    }
+  }
+  /**
+   * Starts all registered agents.
+   *
+   * @description
+   * Initializes all agents in parallel. If `continueOnError` is true,
+   * failed agents won't prevent others from starting.
+   *
+   * @returns Map of agent names to their results (toolsets or errors)
+   *
+   * @example
+   * ```typescript
+   * const results = await manager.startAll();
+   *
+   * for (const [name, result] of results) {
+   *   if (result instanceof Error) {
+   *     console.error(`${name} failed:`, result.message);
+   *   } else {
+   *     console.log(`${name} started with ${Object.keys(result).length} toolsets`);
+   *   }
+   * }
+   * ```
+   */
+  async startAll() {
+    const results = /* @__PURE__ */ new Map();
+    const promises = Object.keys(this._options.agents).map(async (name) => {
+      try {
+        const builtAgent = await this.start(name);
+        results.set(name, builtAgent.getToolsets());
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        results.set(name, err);
+        if (!this._options.continueOnError) {
+          throw error;
+        }
+      }
+    });
+    await Promise.all(promises);
+    this._options.logger?.info("IgniterAgentManager.startAll completed", {
+      agents: this.getNames().length,
+      failed: this.getFailedAgents().length
+    });
+    return results;
+  }
+  /* ---------------------------------------------------------------------------
+   * ACCESS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Gets a registered agent by name.
+   *
+   * @param name - The agent name
+   * @returns The agent instance
+   * @throws {IgniterAgentError} If the agent is not found
+   *
+   * @example
+   * ```typescript
+   * const agent = manager.get('support');
+   * const response = await agent.generate({ messages: [...] });
+   * ```
+   */
+  get(name) {
+    const agent = this._options.agents[name];
+    if (!agent) {
+      throw new IgniterAgentError({
+        message: `Agent '${name}' is not registered`,
+        code: "IGNITER_AGENT_NOT_INITIALIZED" /* AGENT_NOT_INITIALIZED */,
+        causer: "IgniterAgentManager",
+        metadata: { operation: "get" }
+      });
+    }
+    return agent;
+  }
+  /**
+   * Gets an agent if it exists, undefined otherwise.
+   *
+   * @param name - The agent name
+   * @returns The agent instance or undefined
+   */
+  tryGet(name) {
+    return this._options.agents[name];
+  }
+  /**
+   * Gets all registered agent names.
+   *
+   * @returns Array of agent names
+   */
+  getNames() {
+    return Object.keys(this._options.agents);
+  }
+  /**
+   * Gets the number of registered agents.
+   *
+   * @returns Agent count
+   */
+  get size() {
+    return Object.keys(this._options.agents).length;
+  }
+  /* ---------------------------------------------------------------------------
+   * STATUS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Gets information about a specific agent.
+   *
+   * @param name - The agent name
+   * @returns Agent information or undefined
+   */
+  getInfo(name) {
+    return this._statuses.get(name);
+  }
+  /**
+   * Gets status information for all agents.
+   *
+   * @returns Array of agent information objects
+   *
+   * @example
+   * ```typescript
+   * const status = manager.getStatus();
+   *
+   * for (const info of status) {
+   *   console.log(`${info.name}: ${info.status}`);
+   * }
+   * ```
+   */
+  getStatus() {
+    return Array.from(this._statuses.values());
+  }
+  /**
+   * Checks if all agents are running.
+   *
+   * @returns True if all agents are in 'running' status
+   */
+  isAllRunning() {
+    for (const info of this._statuses.values()) {
+      if (info.status !== "running") {
+        return false;
+      }
+    }
+    return Object.keys(this._options.agents).length > 0;
+  }
+  /**
+   * Gets agents that are in error state.
+   *
+   * @returns Array of agent info for failed agents
+   */
+  getFailedAgents() {
+    return Array.from(this._statuses.values()).filter(
+      (info) => info.status === "error"
+    );
+  }
+};
+var BaseAgentAttributesSchema = z.object({
+  /**
+   * The agent name.
+   */
+  "ctx.agent.name": z.string(),
+  /**
+   * The current scope (if scoped).
+   */
+  "ctx.agent.scope": z.string().optional(),
+  /**
+   * The scope identifier value.
+   */
+  "ctx.agent.scopeId": z.string().optional()
+});
+var LifecycleAttributesSchema = BaseAgentAttributesSchema.extend({
+  /**
+   * Number of toolsets registered.
+   */
+  "ctx.lifecycle.toolsetCount": z.number().optional(),
+  /**
+   * Number of MCP connections configured.
+   */
+  "ctx.lifecycle.mcpCount": z.number().optional(),
+  /**
+   * Whether memory adapter is configured.
+   */
+  "ctx.lifecycle.hasMemory": z.boolean().optional()
+});
+var GenerationAttributesSchema = BaseAgentAttributesSchema.extend({
+  /**
+   * The model used for generation.
+   */
+  "ctx.generation.model": z.string().optional(),
+  /**
+   * Number of input messages.
+   */
+  "ctx.generation.inputMessages": z.number().optional(),
+  /**
+   * Number of input tokens (if available).
+   */
+  "ctx.generation.inputTokens": z.number().optional(),
+  /**
+   * Number of output tokens (if available).
+   */
+  "ctx.generation.outputTokens": z.number().optional(),
+  /**
+   * Total tokens used (if available).
+   */
+  "ctx.generation.totalTokens": z.number().optional(),
+  /**
+   * Generation duration in milliseconds.
+   */
+  "ctx.generation.durationMs": z.number().optional(),
+  /**
+   * Number of tool calls made during generation.
+   */
+  "ctx.generation.toolCalls": z.number().optional(),
+  /**
+   * Whether the response was streamed.
+   */
+  "ctx.generation.streamed": z.boolean().optional()
+});
+var ToolAttributesSchema = BaseAgentAttributesSchema.extend({
+  /**
+   * The toolset name.
+   */
+  "ctx.tool.toolset": z.string(),
+  /**
+   * The tool name (within the toolset).
+   */
+  "ctx.tool.name": z.string(),
+  /**
+   * The full tool identifier (toolset_name).
+   */
+  "ctx.tool.fullName": z.string(),
+  /**
+   * Tool execution duration in milliseconds.
+   */
+  "ctx.tool.durationMs": z.number().optional()
+});
+var MCPAttributesSchema = BaseAgentAttributesSchema.extend({
+  /**
+   * The MCP configuration name.
+   */
+  "ctx.mcp.name": z.string(),
+  /**
+   * The MCP transport type (stdio, http).
+   */
+  "ctx.mcp.type": z.enum(["stdio", "http"]),
+  /**
+   * Number of tools provided by this MCP.
+   */
+  "ctx.mcp.toolCount": z.number().optional(),
+  /**
+   * Connection duration in milliseconds.
+   */
+  "ctx.mcp.durationMs": z.number().optional()
+});
+var MemoryAttributesSchema = BaseAgentAttributesSchema.extend({
+  /**
+   * The memory operation type.
+   */
+  "ctx.memory.operation": z.enum([
+    "getWorkingMemory",
+    "updateWorkingMemory",
+    "getMessages",
+    "saveMessage",
+    "getChats",
+    "saveChat",
+    "getChat",
+    "updateChatTitle",
+    "deleteChat"
+  ]),
+  /**
+   * The memory scope (user, chat, global).
+   */
+  "ctx.memory.scope": z.string().optional(),
+  /**
+   * Number of items affected.
+   */
+  "ctx.memory.count": z.number().optional(),
+  /**
+   * Operation duration in milliseconds.
+   */
+  "ctx.memory.durationMs": z.number().optional()
+});
+var ErrorAttributesSchema = BaseAgentAttributesSchema.extend({
+  /**
+   * The error code.
+   */
+  "ctx.error.code": z.string(),
+  /**
+   * The sanitized error message (no sensitive data).
+   */
+  "ctx.error.message": z.string().optional(),
+  /**
+   * The operation that failed.
+   */
+  "ctx.error.operation": z.string().optional(),
+  /**
+   * The component that threw the error.
+   */
+  "ctx.error.component": z.string().optional()
+});
+var IgniterAgentTelemetryEvents = IgniterTelemetryEvents.namespace(
+  "igniter.agent"
+).event("lifecycle.start.started", LifecycleAttributesSchema).event("lifecycle.start.success", LifecycleAttributesSchema).event("lifecycle.start.error", ErrorAttributesSchema).event("lifecycle.stop.started", LifecycleAttributesSchema).event("lifecycle.stop.success", LifecycleAttributesSchema).event("lifecycle.stop.error", ErrorAttributesSchema).event("generation.generate.started", GenerationAttributesSchema).event("generation.generate.success", GenerationAttributesSchema).event("generation.generate.error", ErrorAttributesSchema).event("generation.stream.started", GenerationAttributesSchema).event("generation.stream.chunk", GenerationAttributesSchema).event("generation.stream.success", GenerationAttributesSchema).event("generation.stream.error", ErrorAttributesSchema).event("tool.execute.started", ToolAttributesSchema).event("tool.execute.success", ToolAttributesSchema).event("tool.execute.error", ErrorAttributesSchema).event("mcp.connect.started", MCPAttributesSchema).event("mcp.connect.success", MCPAttributesSchema).event("mcp.connect.error", ErrorAttributesSchema).event("mcp.disconnect.started", MCPAttributesSchema).event("mcp.disconnect.success", MCPAttributesSchema).event("mcp.disconnect.error", ErrorAttributesSchema).event("memory.operation.started", MemoryAttributesSchema).event("memory.operation.success", MemoryAttributesSchema).event("memory.operation.error", ErrorAttributesSchema).build();
+
+// src/core/memory.ts
+var MEMORY_ERROR_CODE = "IGNITER_AGENT_MEMORY_PROVIDER_ERROR" /* MEMORY_PROVIDER_ERROR */;
+var IgniterAgentMemoryCore = class {
+  constructor(config, agentName, logger, telemetry) {
+    this.provider = config.provider;
+    this.agentName = agentName;
+    this.logger = logger;
+    this.telemetry = telemetry;
+  }
+  getBaseAttributes(operation, scope) {
+    const attributes = {
+      "ctx.agent.name": this.agentName,
+      "ctx.memory.operation": operation
+    };
+    if (scope) {
+      attributes["ctx.memory.scope"] = scope;
+    }
+    return attributes;
+  }
+  emitStart(operation, scope) {
+    this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("memory.operation.started"), {
+      level: "debug",
+      attributes: this.getBaseAttributes(operation, scope)
+    });
+  }
+  emitSuccess(operation, durationMs, scope, count) {
+    const attributes = {
+      ...this.getBaseAttributes(operation, scope),
+      "ctx.memory.durationMs": durationMs
+    };
+    if (count !== void 0) {
+      attributes["ctx.memory.count"] = count;
+    }
+    this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("memory.operation.success"), {
+      level: "debug",
+      attributes
+    });
+  }
+  emitError(operation, error, scope) {
+    const attributes = {
+      ...this.getBaseAttributes(operation, scope),
+      "ctx.error.code": MEMORY_ERROR_CODE,
+      "ctx.error.message": error.message,
+      "ctx.error.operation": operation,
+      "ctx.error.component": "memory"
+    };
+    this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("memory.operation.error"), {
+      level: "error",
+      attributes
+    });
+  }
+  async runOperation(operation, scope, handler, count) {
+    const start = Date.now();
+    this.emitStart(operation, scope);
+    this.logger?.debug(`IgniterAgent.memory.${operation} started`, {
+      agent: this.agentName,
+      scope
+    });
+    try {
+      const result = await handler();
+      const durationMs = Date.now() - start;
+      this.emitSuccess(operation, durationMs, scope, count?.(result));
+      this.logger?.success?.(
+        `IgniterAgent.memory.${operation} success`,
+        { agent: this.agentName, scope, durationMs }
+      );
+      return result;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.emitError(operation, error, scope);
+      this.logger?.error(`IgniterAgent.memory.${operation} failed`, error);
+      throw new IgniterAgentMemoryError({
+        message: error.message,
+        code: MEMORY_ERROR_CODE,
+        cause: error,
+        metadata: { operation }
+      });
+    }
+  }
+  async getWorkingMemory(params) {
+    return this.runOperation(
+      "getWorkingMemory",
+      params.scope,
+      () => this.provider.getWorkingMemory(params)
+    );
+  }
+  async updateWorkingMemory(params) {
+    await this.runOperation(
+      "updateWorkingMemory",
+      params.scope,
+      () => this.provider.updateWorkingMemory(params)
+    );
+  }
+  async saveMessage(message) {
+    await this.runOperation(
+      "saveMessage",
+      void 0,
+      async () => {
+        if (!this.provider.saveMessage) {
+          throw new Error("saveMessage is not supported by the provider");
+        }
+        await this.provider.saveMessage(message);
+      }
+    );
+  }
+  async getMessages(params) {
+    return this.runOperation(
+      "getMessages",
+      void 0,
+      async () => {
+        if (!this.provider.getMessages) {
+          throw new Error("getMessages is not supported by the provider");
+        }
+        return this.provider.getMessages(params);
+      },
+      (result) => result.length
+    );
+  }
+  async saveChat(chat) {
+    await this.runOperation(
+      "saveChat",
+      void 0,
+      async () => {
+        if (!this.provider.saveChat) {
+          throw new Error("saveChat is not supported by the provider");
+        }
+        await this.provider.saveChat(chat);
+      }
+    );
+  }
+  async getChats(params) {
+    return this.runOperation(
+      "getChats",
+      void 0,
+      async () => {
+        if (!this.provider.getChats) {
+          throw new Error("getChats is not supported by the provider");
+        }
+        return this.provider.getChats(params);
+      },
+      (result) => result.length
+    );
+  }
+  async getChat(chatId) {
+    return this.runOperation(
+      "getChat",
+      void 0,
+      async () => {
+        if (!this.provider.getChat) {
+          throw new Error("getChat is not supported by the provider");
+        }
+        return this.provider.getChat(chatId);
+      }
+    );
+  }
+  async updateChatTitle(chatId, title) {
+    await this.runOperation(
+      "updateChatTitle",
+      void 0,
+      async () => {
+        if (!this.provider.updateChatTitle) {
+          throw new Error("updateChatTitle is not supported by the provider");
+        }
+        await this.provider.updateChatTitle(chatId, title);
+      }
+    );
+  }
+  async deleteChat(chatId) {
+    await this.runOperation(
+      "deleteChat",
+      void 0,
+      async () => {
+        if (!this.provider.deleteChat) {
+          throw new Error("deleteChat is not supported by the provider");
+        }
+        await this.provider.deleteChat(chatId);
+      }
+    );
+  }
+};
+
+// src/core/agent.ts
+var IgniterAgentCore = class {
+  constructor(agent) {
+    this._agent = agent;
+    this.logger = agent.logger;
+    this.telemetry = agent.telemetry;
+    this.hooks = agent.hooks ?? {};
+    if (agent.memory) {
+      this.memory = new IgniterAgentMemoryCore(agent.memory, String(agent.name), this.logger, this.telemetry);
+    }
+  }
+  /**
+   * Attaches a logger instance to the agent.
+   */
+  attachLogger(logger) {
+    if (!logger) return;
+    if (!this.logger) {
+      this.logger = logger;
+      if (this._agent.memory) {
+        this.memory = new IgniterAgentMemoryCore(
+          this._agent.memory,
+          this.getName(),
+          this.logger,
+          this.telemetry
+        );
+      }
+    }
+  }
+  /**
+   * Attaches a telemetry manager to the agent.
+   */
+  attachTelemetry(telemetry) {
+    if (!telemetry) return;
+    if (!this.telemetry) {
+      this.telemetry = telemetry;
+      if (this._agent.memory) {
+        this.memory = new IgniterAgentMemoryCore(
+          this._agent.memory,
+          this.getName(),
+          this.logger,
+          this.telemetry
+        );
+      }
+    }
+  }
+  /**
+   * Attaches hook callbacks to the agent.
+   */
+  attachHooks(hooks) {
+    if (!hooks) return;
+    const merge = (current, incoming) => {
+      if (!current) return incoming;
+      if (!incoming) return current;
+      return ((...args) => {
+        current(...args);
+        incoming(...args);
+      });
+    };
+    this.hooks = {
+      onAgentStart: merge(this.hooks.onAgentStart, hooks.onAgentStart),
+      onAgentError: merge(this.hooks.onAgentError, hooks.onAgentError),
+      onToolCallStart: merge(this.hooks.onToolCallStart, hooks.onToolCallStart),
+      onToolCallEnd: merge(this.hooks.onToolCallEnd, hooks.onToolCallEnd),
+      onToolCallError: merge(this.hooks.onToolCallError, hooks.onToolCallError),
+      onMCPStart: merge(this.hooks.onMCPStart, hooks.onMCPStart),
+      onMCPError: merge(this.hooks.onMCPError, hooks.onMCPError)
+    };
+  }
+  /**
+   * Returns the agent name.
+   */
+  getName() {
+    return String(this._agent.name);
+  }
+  /**
+   * Starts the agent by initializing all MCP connections.
+   */
+  async start() {
+    const startTime = Date.now();
+    const toolsets = this._agent.toolsets;
+    const mcpConfigs = Object.values(this._agent.configs || {});
+    const lifecycleAttributes = {
+      "ctx.agent.name": this.getName(),
+      "ctx.lifecycle.toolsetCount": Object.keys(toolsets || {}).length,
+      "ctx.lifecycle.mcpCount": mcpConfigs.length,
+      "ctx.lifecycle.hasMemory": Boolean(this.memory)
+    };
+    this.logger?.debug("IgniterAgent.start started", lifecycleAttributes);
+    this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("lifecycle.start.started"), {
+      level: "debug",
+      attributes: lifecycleAttributes
+    });
+    try {
+      for (const mcpConfig of mcpConfigs) {
+        const mcpStart = Date.now();
+        this.hooks.onMCPStart?.(this.getName(), mcpConfig.name);
+        this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("mcp.connect.started"), {
+          level: "debug",
+          attributes: {
+            "ctx.agent.name": this.getName(),
+            "ctx.mcp.name": mcpConfig.name,
+            "ctx.mcp.type": mcpConfig.type
+          }
+        });
+        try {
+          const mcpToolset = await this.initializeMCPClient(mcpConfig);
+          toolsets[mcpConfig.name] = mcpToolset;
+          this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("mcp.connect.success"), {
+            level: "debug",
+            attributes: {
+              "ctx.agent.name": this.getName(),
+              "ctx.mcp.name": mcpConfig.name,
+              "ctx.mcp.type": mcpConfig.type,
+              "ctx.mcp.toolCount": Object.keys(mcpToolset.tools || {}).length,
+              "ctx.mcp.durationMs": Date.now() - mcpStart
+            }
+          });
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("mcp.connect.error"), {
+            level: "error",
+            attributes: {
+              "ctx.agent.name": this.getName(),
+              "ctx.mcp.name": mcpConfig.name,
+              "ctx.mcp.type": mcpConfig.type,
+              "ctx.mcp.durationMs": Date.now() - mcpStart,
+              ...this.getErrorAttributes(err, "mcp.connect")
+            }
+          });
+          this.logger?.error("IgniterAgent.mcp.connect failed", err);
+          throw err;
+        }
+      }
+      const durationMs = Date.now() - startTime;
+      this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("lifecycle.start.success"), {
+        level: "debug",
+        attributes: {
+          ...lifecycleAttributes,
+          "ctx.lifecycle.toolsetCount": Object.keys(this._agent.toolsets || {}).length,
+          "ctx.lifecycle.mcpCount": mcpConfigs.length
+        }
+      });
+      this.logger?.success?.("IgniterAgent.start success", {
+        ...lifecycleAttributes,
+        durationMs
+      });
+      this.hooks.onAgentStart?.(this.getName());
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("lifecycle.start.error"), {
+        level: "error",
+        attributes: {
+          ...lifecycleAttributes,
+          ...this.getErrorAttributes(err, "lifecycle.start")
+        }
+      });
+      this.logger?.error("IgniterAgent.start failed", err);
+      this.hooks.onAgentError?.(this.getName(), err);
+      throw err;
+    }
+  }
+  /**
+   * Stops the agent by disconnecting MCP toolsets.
+   */
+  async stop() {
+    const startTime = Date.now();
+    const mcpConfigs = Object.values(this._agent.configs || {});
+    const lifecycleAttributes = {
+      "ctx.agent.name": this.getName(),
+      "ctx.lifecycle.toolsetCount": Object.keys(this._agent.toolsets || {}).length,
+      "ctx.lifecycle.mcpCount": mcpConfigs.length,
+      "ctx.lifecycle.hasMemory": Boolean(this.memory)
+    };
+    this.logger?.debug("IgniterAgent.stop started", lifecycleAttributes);
+    this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("lifecycle.stop.started"), {
+      level: "debug",
+      attributes: lifecycleAttributes
+    });
+    try {
+      for (const mcpConfig of mcpConfigs) {
+        const mcpStart = Date.now();
+        this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("mcp.disconnect.started"), {
+          level: "debug",
+          attributes: {
+            "ctx.agent.name": this.getName(),
+            "ctx.mcp.name": mcpConfig.name,
+            "ctx.mcp.type": mcpConfig.type
+          }
+        });
+        try {
+          const existing = this._agent.toolsets[mcpConfig.name];
+          if (existing?.disconnect) {
+            await existing.disconnect();
+          }
+          if (existing) {
+            this._agent.toolsets[mcpConfig.name] = {
+              ...existing,
+              status: "disconnected",
+              tools: {}
+            };
+          }
+          this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("mcp.disconnect.success"), {
+            level: "debug",
+            attributes: {
+              "ctx.agent.name": this.getName(),
+              "ctx.mcp.name": mcpConfig.name,
+              "ctx.mcp.type": mcpConfig.type,
+              "ctx.mcp.durationMs": Date.now() - mcpStart
+            }
+          });
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("mcp.disconnect.error"), {
+            level: "error",
+            attributes: {
+              "ctx.agent.name": this.getName(),
+              "ctx.mcp.name": mcpConfig.name,
+              "ctx.mcp.type": mcpConfig.type,
+              "ctx.mcp.durationMs": Date.now() - mcpStart,
+              ...this.getErrorAttributes(err, "mcp.disconnect")
+            }
+          });
+          this.logger?.error("IgniterAgent.mcp.disconnect failed", err);
+          throw err;
+        }
+      }
+      const durationMs = Date.now() - startTime;
+      this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("lifecycle.stop.success"), {
+        level: "debug",
+        attributes: {
+          ...lifecycleAttributes,
+          "ctx.lifecycle.toolsetCount": Object.keys(this._agent.toolsets || {}).length,
+          "ctx.lifecycle.mcpCount": mcpConfigs.length
+        }
+      });
+      this.logger?.success?.("IgniterAgent.stop success", {
+        ...lifecycleAttributes,
+        durationMs
+      });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("lifecycle.stop.error"), {
+        level: "error",
+        attributes: {
+          ...lifecycleAttributes,
+          ...this.getErrorAttributes(err, "lifecycle.stop")
+        }
+      });
+      this.logger?.error("IgniterAgent.stop failed", err);
+      throw err;
+    }
+  }
+  /**
+   * 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(IgniterAgentTelemetryEvents.get.key("generation.generate.started"), {
+      level: "debug",
+      attributes
+    });
+    try {
+      const agent = this.getAgentInstanceWithContext(
+        input.options
+      );
+      const result = await agent.generate(input);
+      const durationMs = Date.now() - startTime;
+      this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("generation.generate.success"), {
+        level: "debug",
+        attributes: {
+          ...attributes,
+          "ctx.generation.durationMs": durationMs
+        }
+      });
+      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(IgniterAgentTelemetryEvents.get.key("generation.generate.error"), {
+        level: "error",
+        attributes: {
+          ...attributes,
+          ...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(IgniterAgentTelemetryEvents.get.key("generation.stream.started"), {
+      level: "debug",
+      attributes
+    });
+    try {
+      const agent = this.getAgentInstanceWithContext(
+        input.options
+      );
+      const result = await agent.stream(input);
+      const durationMs = Date.now() - startTime;
+      const emitChunk = () => {
+        this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("generation.stream.chunk"), {
+          level: "debug",
+          attributes
+        });
+      };
+      const wrapped = this.wrapStreamResult(result, emitChunk);
+      this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("generation.stream.success"), {
+        level: "debug",
+        attributes: {
+          ...attributes,
+          "ctx.generation.durationMs": durationMs
+        }
+      });
+      this.logger?.success?.("IgniterAgent.stream success", {
+        ...attributes,
+        durationMs
+      });
+      return wrapped;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.telemetry?.emit(IgniterAgentTelemetryEvents.get.key("generation.stream.error"), {
+        level: "error",
+        attributes: {
+          ...attributes,
+          ...this.getErrorAttributes(err, "generation.stream")
+        }
+      });
+      this.logger?.error("IgniterAgent.stream failed", err);
+      throw err;
+    }
+  }
+  /**
+   * Gets all registered toolsets.
+   */
+  getToolsets() {
+    return this._agent.toolsets;
+  }
+  /**
+   * Gets the configured model.
+   */
+  getModel() {
+    return this._agent.model;
+  }
+  /**
+   * Gets the configured instructions.
+   */
+  getInstructions() {
+    return this._agent.instructions;
+  }
+  /**
+   * Gets the context schema.
+   */
+  getContextSchema() {
+    return this._agent.schema;
+  }
+  /**
+   * 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;
+      }
+    }
+    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(IgniterAgentTelemetryEvents.get.key("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(IgniterAgentTelemetryEvents.get.key("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(IgniterAgentTelemetryEvents.get.key("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;
+  }
+  getErrorAttributes(error, operation) {
+    return {
+      "ctx.error.code": error.code ?? error.name ?? "IGNITER_AGENT_UNKNOWN_ERROR" /* UNKNOWN */,
+      "ctx.error.message": error.message,
+      "ctx.error.operation": operation,
+      "ctx.error.component": "agent"
+    };
+  }
+  getAgentInstanceWithContext(context) {
+    const tools = this.getTools();
+    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({
+      model: this._agent.model,
+      instructions: this._agent.instructions ? this._agent.instructions.build(context) : "",
+      tools,
+      callOptionsSchema: this._agent.schema
+    });
+  }
+  async initializeMCPClient(mcpConfig) {
+    if (this._agent.toolsets[mcpConfig.name]) {
+      return this._agent.toolsets[mcpConfig.name];
+    }
+    let client = null;
+    try {
+      if (mcpConfig.type === "stdio") {
+        const stdioConfig = mcpConfig;
+        this.logger?.debug("IgniterAgent.mcp.connect stdio", {
+          command: stdioConfig.command,
+          args: stdioConfig.args
+        });
+        client = await experimental_createMCPClient({
+          transport: new StdioClientTransport({
+            command: stdioConfig.command,
+            args: stdioConfig.args,
+            env: stdioConfig.env
+          })
+        });
+      }
+      if (mcpConfig.type === "http") {
+        const httpConfig = mcpConfig;
+        this.logger?.debug("IgniterAgent.mcp.connect http", {
+          url: httpConfig.url
+        });
+        const url = new URL(httpConfig.url);
+        client = await experimental_createMCPClient({
+          transport: new StreamableHTTPClientTransport(url, {
+            requestInit: {
+              headers: httpConfig.headers
+            }
+          })
+        });
+      }
+      if (!client) {
+        throw new IgniterAgentMCPError({
+          message: `Failed to create MCP client for '${mcpConfig.name}'`,
+          code: "IGNITER_AGENT_MCP_CONNECTION_FAILED" /* MCP_CONNECTION_FAILED */,
+          mcpName: mcpConfig.name
+        });
+      }
+      const tools = await client.tools();
+      return {
+        type: mcpConfig.type,
+        status: "connected",
+        name: mcpConfig.name,
+        tools
+      };
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.hooks.onMCPError?.(this.getName(), mcpConfig.name, err);
+      throw err;
+    }
+  }
+};
+
+// src/builders/main.builder.ts
+var IgniterAgentManagerBuilder = class _IgniterAgentManagerBuilder {
+  constructor(manager) {
+    this._manager = manager;
+  }
+  addAgent(name, agent) {
+    return new _IgniterAgentManagerBuilder({
+      logger: this._manager.logger,
+      telemetry: this._manager.telemetry,
+      autoStart: this._manager.autoStart,
+      continueOnError: this._manager.continueOnError,
+      onAgentStart: this._manager.onAgentStart,
+      onAgentError: this._manager.onAgentError,
+      onToolCallStart: this._manager.onToolCallStart,
+      onToolCallEnd: this._manager.onToolCallEnd,
+      onToolCallError: this._manager.onToolCallError,
+      onMCPStart: this._manager.onMCPStart,
+      onMCPError: this._manager.onMCPError,
+      agents: {
+        ...this._manager.agents,
+        [name]: agent
+      }
+    });
+  }
+  withLogger(logger) {
+    return new _IgniterAgentManagerBuilder({
+      ...this._manager,
+      logger
+    });
+  }
+  withTelemetry(telemetry) {
+    return new _IgniterAgentManagerBuilder({
+      ...this._manager,
+      telemetry
+    });
+  }
+  withAutoStart(autoStart) {
+    return new _IgniterAgentManagerBuilder({
+      ...this._manager,
+      autoStart
+    });
+  }
+  withContinueOnError(continueOnError) {
+    return new _IgniterAgentManagerBuilder({
+      ...this._manager,
+      continueOnError
+    });
+  }
+  onAgentStart(callback) {
+    return new _IgniterAgentManagerBuilder({
+      ...this._manager,
+      onAgentStart: callback
+    });
+  }
+  onAgentError(callback) {
+    return new _IgniterAgentManagerBuilder({
+      ...this._manager,
+      onAgentError: callback
+    });
+  }
+  onToolCallStart(callback) {
+    const manager = new _IgniterAgentManagerBuilder({
+      ...this._manager,
+      onToolCallStart: callback
+    });
+    return manager;
+  }
+  onToolCallEnd(callback) {
+    const manager = new _IgniterAgentManagerBuilder({
+      ...this._manager,
+      onToolCallEnd: callback
+    });
+    return manager;
+  }
+  onToolCallError(callback) {
+    const manager = new _IgniterAgentManagerBuilder({
+      ...this._manager,
+      onToolCallError: callback
+    });
+    return manager;
+  }
+  onMCPStart(callback) {
+    const manager = new _IgniterAgentManagerBuilder({
+      ...this._manager,
+      onMCPStart: callback
+    });
+    return manager;
+  }
+  onMCPError(callback) {
+    const manager = new _IgniterAgentManagerBuilder({
+      ...this._manager,
+      onMCPError: callback
+    });
+    return manager;
+  }
+  static create() {
+    return new _IgniterAgentManagerBuilder({
+      agents: {},
+      autoStart: false,
+      continueOnError: true
+    });
+  }
+  build() {
+    return new IgniterAgentManagerCore(this._manager);
+  }
+};
+var IgniterAgentManager = {
+  create: IgniterAgentManagerBuilder.create
+};
+
+// src/builders/prompt.builder.ts
+var TEMPLATE_PATTERN = /\{\{\s*([^}]+?)\s*\}\}/g;
+var resolvePath = (value, path) => {
+  if (!path) return void 0;
+  return path.split(".").reduce((acc, key) => {
+    if (acc && typeof acc === "object" && key in acc) {
+      return acc[key];
+    }
+    return void 0;
+  }, value);
+};
+var IgniterAgentPromptBuilder = class _IgniterAgentPromptBuilder {
+  constructor(template) {
+    this.template = template;
+  }
+  /**
+   * Creates a new prompt builder.
+   *
+   * @param template - Prompt template string with {{placeholders}}
+   * @returns A new prompt builder instance
+   */
+  static create(template) {
+    return new _IgniterAgentPromptBuilder(
+      template
+    );
+  }
+  /**
+   * Builds the prompt string with the provided context.
+   *
+   * @param context - Context data used for interpolation
+   * @returns The resolved prompt string
+   */
+  build(context) {
+    return this.template.replace(TEMPLATE_PATTERN, (_match, path) => {
+      const value = resolvePath(context, String(path));
+      return value === void 0 || value === null ? "" : String(value);
+    });
+  }
+  /**
+   * Returns the raw prompt template string.
+   */
+  getTemplate() {
+    return this.template;
+  }
+};
+var IgniterAgentPrompt = IgniterAgentPromptBuilder;
+
+// src/builders/agent.builder.ts
+var IgniterAgentBuilder = class _IgniterAgentBuilder {
+  /**
+   * Creates a new IgniterAgentBuilder instance.
+   *
+   * @param config - Initial configuration
+   * @internal
+   */
+  constructor(config = {}) {
+    this._config = {
+      name: "agent",
+      toolsets: {},
+      configs: {},
+      instructions: IgniterAgentPromptBuilder.create(""),
+      ...config
+    };
+  }
+  /* ---------------------------------------------------------------------------
+   * STATIC FACTORY METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Creates a new agent builder.
+   *
+   * @description
+   * Primary entry point for creating an agent. Returns a new builder
+   * instance that can be configured using fluent methods.
+   *
+   * @returns A new IgniterAgentBuilder instance
+   *
+   * @example
+   * ```typescript
+   * const agent = IgniterAgent.create('my-agent')
+   *   .withModel(openai('gpt-4'))
+   *   .build();
+   * ```
+   *
+   * @public
+   */
+  static create(name = "agent") {
+    return new _IgniterAgentBuilder({
+      name
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * BUILDER METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Sets the language model.
+   *
+   * @description
+   * Configures the AI model that powers the agent. Supports any model
+   * provider compatible with the Vercel AI SDK.
+   *
+   * @typeParam TNewModel - The new model type
+   * @param model - The language model instance
+   * @returns A new builder with the model set
+   *
+   * @example
+   * ```typescript
+   * import { openai } from '@ai-sdk/openai';
+   * import { anthropic } from '@ai-sdk/anthropic';
+   * import { google } from '@ai-sdk/google';
+   *
+   * // Using OpenAI
+   * const agent1 = IgniterAgent.create()
+   *   .withModel(openai('gpt-4-turbo'))
+   *   .build();
+   *
+   * // Using Anthropic
+   * const agent2 = IgniterAgent.create()
+   *   .withModel(anthropic('claude-3-opus'))
+   *   .build();
+   *
+   * // Using Google
+   * const agent3 = IgniterAgent.create()
+   *   .withModel(google('gemini-pro'))
+   *   .build();
+   * ```
+   *
+   * @public
+   */
+  withModel(model) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      model
+    });
+  }
+  /**
+   * Sets the prompt instructions.
+   *
+   * @description
+   * Configures the agent's system prompt using an IgniterAgentPrompt template.
+   * The prompt defines the agent's behavior, personality, and capabilities.
+   *
+   * @typeParam TNewInstructions - The new instructions type
+   * @param instructions - The prompt template instance
+   * @returns A new builder with the instructions set
+   *
+   * @example
+   * ```typescript
+   * const agent = IgniterAgent.create()
+   *   .withPrompt(
+   *     IgniterAgentPrompt.create(`
+   *       You are a helpful coding assistant specialized in TypeScript.
+   *
+   *       Guidelines:
+   *       - Always provide type-safe code
+   *       - Include JSDoc comments
+   *       - Follow best practices
+   *     `)
+   *   )
+   *   .build();
+   * ```
+   *
+   * @public
+   */
+  withPrompt(instructions) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      instructions
+    });
+  }
+  /**
+   * Attaches a logger instance for operational logs.
+   */
+  withLogger(logger) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      logger
+    });
+  }
+  /**
+   * Attaches a telemetry manager for observability.
+   */
+  withTelemetry(telemetry) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      telemetry
+    });
+  }
+  /**
+   * Configures persistent memory for the agent.
+   */
+  withMemory(memory) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      memory
+    });
+  }
+  /**
+   * Callback when the agent starts.
+   */
+  onAgentStart(callback) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      hooks: {
+        ...this._config.hooks,
+        onAgentStart: callback
+      }
+    });
+  }
+  /**
+   * Callback when the agent errors.
+   */
+  onAgentError(callback) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      hooks: {
+        ...this._config.hooks,
+        onAgentError: callback
+      }
+    });
+  }
+  /**
+   * Callback when a tool call starts.
+   */
+  onToolCallStart(callback) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      hooks: {
+        ...this._config.hooks,
+        onToolCallStart: callback
+      }
+    });
+  }
+  /**
+   * Callback when a tool call completes.
+   */
+  onToolCallEnd(callback) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      hooks: {
+        ...this._config.hooks,
+        onToolCallEnd: callback
+      }
+    });
+  }
+  /**
+   * Callback when a tool call fails.
+   */
+  onToolCallError(callback) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      hooks: {
+        ...this._config.hooks,
+        onToolCallError: callback
+      }
+    });
+  }
+  /**
+   * Callback when an MCP connection starts.
+   */
+  onMCPStart(callback) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      hooks: {
+        ...this._config.hooks,
+        onMCPStart: callback
+      }
+    });
+  }
+  /**
+   * Callback when an MCP connection fails.
+   */
+  onMCPError(callback) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      hooks: {
+        ...this._config.hooks,
+        onMCPError: callback
+      }
+    });
+  }
+  /**
+   * Sets the context schema.
+   *
+   * @description
+   * Configures a Zod schema for validating context passed to the agent.
+   * The context is available in prompt templates and can be used to
+   * customize agent behavior per-request.
+   *
+   * @typeParam TNewSchema - The new schema type
+   * @param schema - The Zod schema for context validation
+   * @returns A new builder with the schema set
+   *
+   * @example
+   * ```typescript
+   * import { z } from 'zod';
+   *
+   * const contextSchema = z.object({
+   *   userId: z.string(),
+   *   chatId: z.string(),
+   *   userRole: z.enum(['admin', 'user', 'guest']),
+   *   preferences: z.object({
+   *     language: z.string().default('en'),
+   *     theme: z.string().optional()
+   *   })
+   * });
+   *
+   * const agent = IgniterAgent.create()
+   *   .withContextSchema(contextSchema)
+   *   .build();
+   *
+   * // Context is type-safe when calling generate
+   * await agent.generate({
+   *   messages: [...],
+   *   options: {
+   *     userId: 'user_123',
+   *     chatId: 'chat_456',
+   *     userRole: 'admin',
+   *     preferences: { language: 'pt' }
+   *   }
+   * });
+   * ```
+   *
+   * @public
+   */
+  withContextSchema(schema) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      schema
+    });
+  }
+  /**
+    * Adds a toolset to the agent.
+    *
+    * @description
+    * Registers a toolset with the agent. The toolset's tools become available
+    * for the AI to invoke. Multiple toolsets can be added to a single agent.
+    *
+    * Tool names are prefixed with the toolset name to avoid collisions:
+    * `{toolsetName}_{toolName}`
+    *
+    * @typeParam TNewToolset - The toolset type
+    * @param toolset - The toolset to register
+    * @returns A new builder with the toolset added
+    *
+    * @example
+    * ```typescript
+  * const githubToolset = IgniterAgentToolset.create('github')
+  *   .addTool(createIssueTool)
+  *   .addTool(listReposTool)
+    *   .build();
+    *
+  * const dockerToolset = IgniterAgentToolset.create('docker')
+  *   .addTool(buildImageTool)
+  *   .addTool(runContainerTool)
+    *   .build();
+    *
+    * const agent = IgniterAgent.create()
+    *   .addToolset(githubToolset)  // Adds github_createIssue, github_listRepos
+    *   .addToolset(dockerToolset)  // Adds docker_build, docker_run
+    *   .build();
+    * ```
+    *
+    * @public
+    */
+  addToolset(toolset) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      toolsets: {
+        ...this._config.toolsets,
+        [toolset.name]: toolset
+      }
+    });
+  }
+  /**
+   * Adds an MCP configuration to the agent.
+   *
+   * @description
+   * Registers an MCP server configuration with the agent. The MCP server
+   * will be connected when `agent.start()` is called, and its tools will
+   * become available for the AI to invoke.
+   *
+   * @typeParam TMCPType - The MCP transport type
+   * @typeParam TMCPName - The MCP configuration name
+   * @param config - The MCP configuration
+   * @returns A new builder with the MCP config added
+   *
+   * @example
+   * ```typescript
+   * const filesystemMCP = IgniterAgentMCPClient.create('filesystem')
+   *   .withType('stdio')
+   *   .withCommand('npx')
+   *   .withArgs(['-y', '@modelcontextprotocol/server-filesystem', '/tmp'])
+   *   .build();
+   *
+   * const remoteMCP = IgniterAgentMCPClient.create('remote-api')
+   *   .withType('http')
+   *   .withURL('https://api.example.com/mcp')
+   *   .withHeaders({ 'Authorization': 'Bearer xxx' })
+   *   .build();
+   *
+   * const agent = IgniterAgent.create()
+   *   .addMCP(filesystemMCP)
+   *   .addMCP(remoteMCP)
+   *   .build();
+   *
+   * // MCP connections are established here
+   * await agent.start();
+   * ```
+   *
+   * @public
+   */
+  addMCP(config) {
+    return new _IgniterAgentBuilder({
+      ...this._config,
+      configs: {
+        ...this._config.configs,
+        [config.name]: config
+      }
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * BUILD METHOD
+   * --------------------------------------------------------------------------- */
+  /**
+   * Builds and returns the completed agent.
+   *
+   * @description
+   * Finalizes the agent configuration and returns a runtime agent object.
+   * The agent provides methods for:
+   * - `start()`: Initialize MCP connections
+   * - `generate()`: Generate a single response
+   * - `stream()`: Stream a response
+   * - Accessors for configuration
+   *
+   * @returns The built agent runtime object
+   *
+   * @example
+   * ```typescript
+   * const agent = IgniterAgent.create('assistant')
+   *   .withModel(openai('gpt-4'))
+   *   .addToolset(myToolset)
+   *   .build();
+   *
+   * // Start the agent
+   * await agent.start();
+   *
+   * // Generate a response
+   * const result = await agent.generate({
+   *   messages: [{ role: 'user', content: 'Hello!' }]
+   * });
+   *
+   * // Access configuration
+   * console.log('Model:', agent.getModel());
+   * console.log('Toolsets:', agent.getToolsets());
+   * ```
+   *
+   * @public
+   */
+  build() {
+    return new IgniterAgentCore(this._config);
+  }
+  /* ---------------------------------------------------------------------------
+   * ACCESSORS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Gets the current configuration (partial).
+   *
+   * @returns The current configuration state
+   * @public
+   */
+  getConfig() {
+    return { ...this._config };
+  }
+  /**
+   * Gets the agent name.
+   *
+   * @returns The agent's name
+   * @public
+   */
+  getName() {
+    return this._config.name;
+  }
+};
+var IgniterAgent = {
+  create: IgniterAgentBuilder.create
+};
+var IgniterAgentToolsetBuilder = class _IgniterAgentToolsetBuilder {
+  /**
+   * Creates a new IgniterAgentToolsetBuilder instance.
+   *
+   * @param params - The toolset name and initial tools
+   * @internal
+   */
+  constructor(params) {
+    this._name = params.name;
+    this._tools = params.tools;
+  }
+  /* ---------------------------------------------------------------------------
+   * STATIC FACTORY METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+    * Creates a new toolset builder with the given name.
+    *
+    * @description
+    * This is the primary entry point for creating a new toolset.
+    * The name must be unique within an agent and is used as a prefix
+    * for tool names when the toolset is registered.
+    *
+    * @typeParam TName - The toolset name type
+    * @param name - Unique name for the toolset
+    * @returns A new IgniterAgentToolsetBuilder instance
+    *
+    * @example
+    * ```typescript
+  * const tool = IgniterAgentTool
+  *   .create('doSomething')
+  *   .withDescription('Does something')
+  *   .withInputect({}))
+  *   .withExecute(async () => ({ ok: true }))
+  *   .build();
+  *
+  * const toolset = IgniterAgentToolset
+  *   .create('myTools')
+  *   .addTool(tool)
+  *   .build();
+    * ```
+    *
+    * @public
+    */
+  static create(name) {
+    if (!name || typeof name !== "string") {
+      throw new IgniterAgentConfigError({
+        message: "Toolset name is required and must be a non-empty string",
+        field: "name"
+      });
+    }
+    return new _IgniterAgentToolsetBuilder({
+      name,
+      tools: {}
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * BUILDER METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+    * Changes the toolset name.
+    *
+    * @description
+    * Allows renaming the toolset during the building process.
+    * This creates a new builder instance with the new name.
+    *
+    * @typeParam TNewName - The new name type
+    * @param name - The new name for the toolset
+    * @returns A new builder with the updated name
+    *
+    * @example
+    * ```typescript
+  * const toolset = IgniterAgentToolset
+  *   .create('temp')
+  *   .withName('production')  // Rename to 'production'
+  *   .addTool(myTool)
+  *   .build();
+    * ```
+    *
+    * @public
+    */
+  withName(name) {
+    return new _IgniterAgentToolsetBuilder({
+      name,
+      tools: this._tools
+    });
+  }
+  /**
+   * Adds a tool to the toolset.
+   *
+   * @description
+   * Adds a built tool definition to the toolset. The tool is automatically
+   * wrapped with error handling that returns a consistent result format
+   * (`{ success: true, data: ... }` or `{ success: false, error: ... }`).
+   *
+   * @typeParam TToolName - The tool name type
+   * @param dto - The built tool definition
+   * @returns A new builder with the tool added
+   *
+   * @example
+   * ```typescript
+   * const greetTool = IgniterAgentTool.create('greet')
+   *   .withDescription('Greets a user')
+   *   .withInputect({ name: z.string() }))
+   *   .withExecute(async ({ name }) => `Hello, ${name}!`)
+   *   .build();
+   *
+   * const toolset = IgniterAgentToolset.create('utils')
+   *   .addTool(greetTool)
+   *   .build();
+   * ```
+   *
+   * @public
+   */
+  addTool(dto) {
+    if (!dto.name || typeof dto.name !== "string") {
+      throw new IgniterAgentConfigError({
+        message: "Tool name is required and must be a non-empty string",
+        field: "name",
+        metadata: { toolset: this._name }
+      });
+    }
+    const wrappedTool = tool({
+      description: dto.description,
+      inputSchema: dto.inputSchema,
+      outputSchema: dto.outputSchema,
+      execute: async (params, options) => {
+        if (!dto.execute) {
+          const result = {
+            success: false,
+            error: `Tool '${dto.name}' has no execute method`
+          };
+          return result;
+        }
+        try {
+          const response = await dto.execute(params, options);
+          const result = {
+            success: true,
+            data: response
+          };
+          return result;
+        } catch (error) {
+          console.error(
+            `[IgniterAgent] Error executing tool '${dto.name}':`,
+            error
+          );
+          const errorMessage = error instanceof Error ? error.message : String(error);
+          const result = {
+            success: false,
+            error: errorMessage
+          };
+          return result;
+        }
+      }
+    });
+    return new _IgniterAgentToolsetBuilder({
+      name: this._name,
+      tools: {
+        ...this._tools,
+        [dto.name]: wrappedTool
+      }
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * BUILD METHOD
+   * --------------------------------------------------------------------------- */
+  /**
+    * Builds and returns the completed toolset.
+    *
+    * @description
+    * Finalizes the toolset configuration and returns an object that can
+    * be registered with an agent using `addToolset()`.
+    *
+    * The returned object includes:
+    * - `name`: The toolset's unique identifier
+    * - `type`: Always `'custom'` for user-defined toolsets
+    * - `status`: Always `'connected'` for custom toolsets
+    * - `tools`: The tools collection
+    * - `toolset`: Reference to the raw tools object
+    *
+    * @returns The completed toolset configuration
+    *
+    * @example
+    * ```typescript
+  * const toolset = IgniterAgentToolset
+  *   .create('utils')
+  *   .addTool(formatDateTool)
+  *   .addTool(parseJsonTool)
+  *   .build();
+    *
+    * console.log(toolset.name);   // 'utils'
+    * console.log(toolset.type);   // 'custom'
+    * console.log(toolset.status); // 'connected'
+    * console.log(Object.keys(toolset.tools)); // ['formatDate', 'parseJSON']
+    * ```
+    *
+    * @public
+    */
+  build() {
+    return {
+      type: "custom",
+      name: this._name,
+      toolset: this._tools,
+      status: "connected",
+      tools: this._tools,
+      $Infer: {}
+    };
+  }
+  /* ---------------------------------------------------------------------------
+   * ACCESSORS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Gets the current toolset name.
+   *
+   * @returns The toolset's name
+   * @public
+   */
+  getName() {
+    return this._name;
+  }
+  /**
+   * Gets the current tools collection.
+   *
+   * @returns The tools object
+   * @public
+   */
+  getTools() {
+    return this._tools;
+  }
+  /**
+   * Gets the number of tools in the toolset.
+   *
+   * @returns The tool count
+   * @public
+   */
+  getToolCount() {
+    return Object.keys(this._tools).length;
+  }
+};
+var IgniterAgentToolset = {
+  create: IgniterAgentToolsetBuilder.create
+};
+
+// src/builders/tool.builder.ts
+var IgniterAgentToolBuilder = class _IgniterAgentToolBuilder {
+  /**
+   * Creates a new IgniterAgentToolBuilder instance.
+   *
+   * @param name - The tool name
+   * @param definition - Partial tool definition
+   * @internal
+   */
+  constructor(definition = {}) {
+    this._definition = definition;
+  }
+  /* ---------------------------------------------------------------------------
+   * STATIC FACTORY METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Creates a new tool builder with the given name.
+   *
+   * @description
+   * The name must be unique within a toolset.
+   *
+   * @typeParam TNewName - The tool name type
+   * @param name - Unique name for the tool
+   * @returns A new IgniterAgentToolBuilder instance
+   *
+   * @public
+   */
+  static create(name) {
+    if (!name || typeof name !== "string") {
+      throw new IgniterAgentConfigError({
+        message: "Tool name is required and must be a non-empty string",
+        field: "name"
+      });
+    }
+    return new _IgniterAgentToolBuilder({
+      name
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * BUILDER METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Sets the tool description.
+   *
+   * @param description - Human-readable description shown to the AI
+   * @returns A new builder with the description set
+   *
+   * @public
+   */
+  withDescription(description) {
+    if (!description || typeof description !== "string") {
+      throw new IgniterAgentConfigError({
+        message: "Tool description is required and must be a non-empty string",
+        field: "description",
+        metadata: { tool: this._definition.name }
+      });
+    }
+    return new _IgniterAgentToolBuilder({
+      ...this._definition,
+      description
+    });
+  }
+  /**
+   * Sets the tool parameters schema.
+   *
+   * @typeParam TNewParams - The new parameters type
+   * @param parameters - Zod schema defining input parameters
+   * @returns A new builder with the parameters set
+   *
+   * @public
+   */
+  withInput(inputSchema) {
+    if (!inputSchema) {
+      throw new IgniterAgentConfigError({
+        message: "Tool parameters schema is required",
+        field: "parameters",
+        metadata: { tool: this._definition.name }
+      });
+    }
+    return new _IgniterAgentToolBuilder({
+      ...this._definition,
+      inputSchema
+    });
+  }
+  /**
+   * Sets the tool output schema.
+   *
+   * @typeParam TNewResult - The new result type
+   * @param outputSchema - Zod schema defining the tool's output
+   * @returns A new builder with the output schema set
+   *
+   * @public
+   */
+  withOutput(outputSchema) {
+    if (!outputSchema) {
+      throw new IgniterAgentConfigError({
+        message: "Tool output schema is required",
+        field: "outputSchema",
+        metadata: { tool: this._definition.name }
+      });
+    }
+    return new _IgniterAgentToolBuilder({
+      ...this._definition,
+      outputSchema
+    });
+  }
+  /**
+   * Sets the tool execution handler.
+   *
+   * @typeParam TNewResult - The new result type
+   * @param execute - Function that performs the tool's logic
+   * @returns A new builder with the execute handler set
+   *
+   * @public
+   */
+  withExecute(execute) {
+    if (typeof execute !== "function") {
+      throw new IgniterAgentConfigError({
+        message: "Tool execute handler must be a function",
+        field: "execute",
+        metadata: { tool: this._definition.name }
+      });
+    }
+    return new _IgniterAgentToolBuilder({
+      ...this._definition,
+      execute
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * BUILD METHOD
+   * --------------------------------------------------------------------------- */
+  /**
+   * Builds and returns the completed tool definition.
+   *
+   * @returns The completed tool definition with its name
+   *
+   * @public
+   */
+  build() {
+    const { name, description, inputSchema, outputSchema, execute } = this._definition;
+    if (!name) {
+      throw new IgniterAgentConfigError({
+        message: "Tool name is required before building",
+        field: "name"
+      });
+    }
+    if (!description) {
+      throw new IgniterAgentConfigError({
+        message: "Tool description is required before building",
+        field: "description",
+        metadata: { tool: this._definition.name }
+      });
+    }
+    if (!inputSchema) {
+      throw new IgniterAgentConfigError({
+        message: "Tool parameters schema is required before building",
+        field: "parameters",
+        metadata: { tool: this._definition.name }
+      });
+    }
+    if (!execute) {
+      throw new IgniterAgentConfigError({
+        message: "Tool execute handler is required before building",
+        field: "execute",
+        metadata: { tool: this._definition.name }
+      });
+    }
+    return {
+      name,
+      description,
+      inputSchema,
+      outputSchema,
+      execute,
+      $Infer: {}
+    };
+  }
+};
+var IgniterAgentTool = {
+  create: IgniterAgentToolBuilder.create
+};
+
+// src/builders/mcp.builder.ts
+var IgniterAgentMCPBuilder = class _IgniterAgentMCPBuilder {
+  /**
+   * Creates a new IgniterAgentMCPBuilder instance.
+   *
+   * @param config - Initial configuration
+   * @internal
+   */
+  constructor(config = {}) {
+    this._config = config;
+  }
+  /* ---------------------------------------------------------------------------
+   * STATIC FACTORY METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Creates a new MCP builder with the given name.
+   *
+   * @description
+   * This is the primary entry point for creating an MCP configuration.
+   * The name must be unique within an agent and is used to identify
+   * the MCP server and its tools.
+   *
+   * After calling `create()`, you must call `withType()` to specify
+   * the transport type before configuring transport-specific options.
+   *
+   * @typeParam TNewName - The configuration name type
+   * @param name - Unique name for the MCP configuration
+   * @returns A new IgniterAgentMCPBuilder instance
+   *
+   * @example
+   * ```typescript
+   * const mcpConfig = IgniterAgentMCPBuilder
+   *   .create('my-mcp')
+   *   .withType('stdio')  // or 'http'
+   *   .withCommand('...')  // available after withType('stdio')
+   *   .build();
+   * ```
+   *
+   * @public
+   */
+  static create(name) {
+    if (!name || typeof name !== "string") {
+      throw new IgniterAgentConfigError({
+        message: "MCP configuration name is required and must be a non-empty string",
+        field: "name"
+      });
+    }
+    return new _IgniterAgentMCPBuilder({
+      name
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * COMMON BUILDER METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Sets the configuration name.
+   *
+   * @description
+   * Allows changing the configuration name during the building process.
+   *
+   * @typeParam TNewName - The new name type
+   * @param name - The new name for the configuration
+   * @returns A new builder with the updated name
+   *
+   * @public
+   */
+  withName(name) {
+    return new _IgniterAgentMCPBuilder({
+      ...this._config,
+      name
+    });
+  }
+  /**
+   * Sets the transport type for the MCP connection.
+   *
+   * @description
+   * Specifies how the agent will communicate with the MCP server:
+   * - `stdio`: Spawns a local process and communicates via stdin/stdout
+   * - `http`: Connects to a remote server via HTTP/HTTPS
+   *
+   * After calling this method, transport-specific methods become available:
+   * - For `stdio`: `withCommand()`, `withArgs()`, `withEnv()`
+   * - For `http`: `withURL()`, `withHeaders()`
+   *
+   * @typeParam TNewType - The transport type
+   * @param type - The transport type to use
+   * @returns A new builder configured for the specified transport
+   *
+   * @example
+   * ```typescript
+   * // Stdio transport
+   * const stdioConfig = IgniterAgentMCPBuilder
+   *   .create('local')
+   *   .withType('stdio')
+   *   .withCommand('python')
+   *   .withArgs(['mcp_server.py'])
+   *   .build();
+   *
+   * // HTTP transport
+   * const httpConfig = IgniterAgentMCPBuilder
+   *   .create('remote')
+   *   .withType('http')
+   *   .withURL('https://api.example.com/mcp')
+   *   .build();
+   * ```
+   *
+   * @public
+   */
+  withType(type) {
+    if (type !== "stdio" && type !== "http") {
+      throw new IgniterAgentConfigError({
+        message: `Invalid MCP transport type: '${type}'. Must be 'stdio' or 'http'`,
+        field: "type",
+        metadata: { validTypes: ["stdio", "http"] }
+      });
+    }
+    return new _IgniterAgentMCPBuilder({
+      ...this._config,
+      type
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * STDIO-SPECIFIC BUILDER METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Sets the command to execute for stdio transport.
+   *
+   * @description
+   * Specifies the executable to run when starting the MCP server process.
+   * Common values include `npx`, `node`, `python`, `deno`, etc.
+   *
+   * @param command - The command to execute
+   * @returns A new builder with the command set
+   * @throws {IgniterAgentConfigError} If transport type is not 'stdio'
+   *
+   * @example
+   * ```typescript
+   * const config = IgniterAgentMCPBuilder
+   *   .create('filesystem')
+   *   .withType('stdio')
+   *   .withCommand('npx')
+   *   .withArgs(['-y', '@modelcontextprotocol/server-filesystem'])
+   *   .build();
+   * ```
+   *
+   * @public
+   */
+  withCommand(command) {
+    this._assertStdioType("withCommand");
+    if (!command || typeof command !== "string") {
+      throw new IgniterAgentConfigError({
+        message: "Command is required and must be a non-empty string",
+        field: "command",
+        metadata: { mcpName: this._config.name }
+      });
+    }
+    return new _IgniterAgentMCPBuilder({
+      ...this._config,
+      command
+    });
+  }
+  /**
+   * Sets the arguments to pass to the command.
+   *
+   * @description
+   * Specifies command-line arguments for the MCP server process.
+   *
+   * @param args - Array of command arguments
+   * @returns A new builder with the arguments set
+   * @throws {IgniterAgentConfigError} If transport type is not 'stdio'
+   *
+   * @example
+   * ```typescript
+   * const config = IgniterAgentMCPBuilder
+   *   .create('filesystem')
+   *   .withType('stdio')
+   *   .withCommand('npx')
+   *   .withArgs([
+   *     '-y',
+   *     '@modelcontextprotocol/server-filesystem',
+   *     '/home/user/documents',
+   *     '--read-only'
+   *   ])
+   *   .build();
+   * ```
+   *
+   * @public
+   */
+  withArgs(args) {
+    this._assertStdioType("withArgs");
+    if (!Array.isArray(args)) {
+      throw new IgniterAgentConfigError({
+        message: "Args must be an array of strings",
+        field: "args",
+        metadata: { mcpName: this._config.name }
+      });
+    }
+    return new _IgniterAgentMCPBuilder({
+      ...this._config,
+      args
+    });
+  }
+  /**
+   * Sets environment variables for the command process.
+   *
+   * @description
+   * Specifies environment variables to pass to the MCP server process.
+   * Useful for passing API keys, configuration, or feature flags.
+   *
+   * @param env - Record of environment variable names to values
+   * @returns A new builder with the environment variables set
+   * @throws {IgniterAgentConfigError} If transport type is not 'stdio'
+   *
+   * @example
+   * ```typescript
+   * const config = IgniterAgentMCPBuilder
+   *   .create('github')
+   *   .withType('stdio')
+   *   .withCommand('npx')
+   *   .withArgs(['-y', '@modelcontextprotocol/server-github'])
+   *   .withEnv({
+   *     GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
+   *     GITHUB_ORG: 'my-organization',
+   *     DEBUG: 'mcp:*'
+   *   })
+   *   .build();
+   * ```
+   *
+   * @public
+   */
+  withEnv(env) {
+    this._assertStdioType("withEnv");
+    if (!env || typeof env !== "object") {
+      throw new IgniterAgentConfigError({
+        message: "Env must be an object mapping variable names to values",
+        field: "env",
+        metadata: { mcpName: this._config.name }
+      });
+    }
+    return new _IgniterAgentMCPBuilder({
+      ...this._config,
+      env
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * HTTP-SPECIFIC BUILDER METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Sets the URL for HTTP transport.
+   *
+   * @description
+   * Specifies the endpoint URL for the remote MCP server.
+   * Must be a valid HTTP or HTTPS URL.
+   *
+   * @param url - The MCP server URL
+   * @returns A new builder with the URL set
+   * @throws {IgniterAgentConfigError} If transport type is not 'http' or URL is invalid
+   *
+   * @example
+   * ```typescript
+   * const config = IgniterAgentMCPBuilder
+   *   .create('opencode')
+   *   .withType('http')
+   *   .withURL('https://sandbox.example.com/mcp/v1')
+   *   .build();
+   * ```
+   *
+   * @public
+   */
+  withURL(url) {
+    this._assertHttpType("withURL");
+    if (!url || typeof url !== "string") {
+      throw new IgniterAgentConfigError({
+        message: "URL is required and must be a non-empty string",
+        field: "url",
+        metadata: { mcpName: this._config.name }
+      });
+    }
+    try {
+      new URL(url);
+    } catch {
+      throw new IgniterAgentConfigError({
+        message: `Invalid URL format: '${url}'`,
+        field: "url",
+        metadata: { mcpName: this._config.name }
+      });
+    }
+    return new _IgniterAgentMCPBuilder({
+      ...this._config,
+      url
+    });
+  }
+  /**
+   * Sets HTTP headers for requests to the MCP server.
+   *
+   * @description
+   * Specifies headers to include in all HTTP requests to the MCP server.
+   * Commonly used for authentication, API keys, or content type.
+   *
+   * @param headers - Record of header names to values
+   * @returns A new builder with the headers set
+   * @throws {IgniterAgentConfigError} If transport type is not 'http'
+   *
+   * @example
+   * ```typescript
+   * const config = IgniterAgentMCPBuilder
+   *   .create('authenticated-mcp')
+   *   .withType('http')
+   *   .withURL('https://api.example.com/mcp')
+   *   .withHeaders({
+   *     'Authorization': `Bearer ${process.env.API_TOKEN}`,
+   *     'X-Client-ID': 'my-app',
+   *     'Content-Type': 'application/json'
+   *   })
+   *   .build();
+   * ```
+   *
+   * @public
+   */
+  withHeaders(headers) {
+    this._assertHttpType("withHeaders");
+    if (!headers || typeof headers !== "object") {
+      throw new IgniterAgentConfigError({
+        message: "Headers must be an object mapping header names to values",
+        field: "headers",
+        metadata: { mcpName: this._config.name }
+      });
+    }
+    return new _IgniterAgentMCPBuilder({
+      ...this._config,
+      headers
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * BUILD METHOD
+   * --------------------------------------------------------------------------- */
+  /**
+   * Builds and returns the completed MCP configuration.
+   *
+   * @description
+   * Validates the configuration and returns a typed configuration object
+   * that can be registered with an agent using `addMCP()`.
+   *
+   * @returns The completed MCP configuration
+   * @throws {IgniterAgentConfigError} If required fields are missing
+   *
+   * @example
+   * ```typescript
+   * const mcpConfig = IgniterAgentMCPBuilder
+   *   .create('filesystem')
+   *   .withType('stdio')
+   *   .withCommand('npx')
+   *   .withArgs(['-y', '@modelcontextprotocol/server-filesystem', '/tmp'])
+   *   .build();
+   *
+   * // Use with an agent
+   * const agent = IgniterAgent.create()
+   *   .addMCP(mcpConfig)
+   *   .build();
+   * ```
+   *
+   * @public
+   */
+  build() {
+    if (!this._config.name) {
+      throw new IgniterAgentConfigError({
+        message: "MCP configuration name is required",
+        field: "name"
+      });
+    }
+    if (!this._config.type) {
+      throw new IgniterAgentConfigError({
+        message: 'MCP transport type is required. Call withType("stdio") or withType("http")',
+        field: "type",
+        metadata: { mcpName: this._config.name }
+      });
+    }
+    if (this._config.type === "stdio") {
+      const config = this._config;
+      if (!config.command) {
+        throw new IgniterAgentConfigError({
+          message: "Command is required for stdio transport",
+          field: "command",
+          metadata: { mcpName: this._config.name }
+        });
+      }
+      if (!config.args) {
+        throw new IgniterAgentConfigError({
+          message: "Args are required for stdio transport",
+          field: "args",
+          metadata: { mcpName: this._config.name }
+        });
+      }
+      return {
+        type: "stdio",
+        name: config.name,
+        command: config.command,
+        args: config.args,
+        env: config.env
+      };
+    }
+    if (this._config.type === "http") {
+      const config = this._config;
+      if (!config.url) {
+        throw new IgniterAgentConfigError({
+          message: "URL is required for http transport",
+          field: "url",
+          metadata: { mcpName: this._config.name }
+        });
+      }
+      return {
+        type: "http",
+        name: config.name,
+        url: config.url,
+        headers: config.headers
+      };
+    }
+    throw new IgniterAgentConfigError({
+      message: `Invalid transport type: '${this._config.type}'`,
+      field: "type",
+      metadata: { mcpName: this._config.name }
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * PRIVATE HELPER METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Asserts that the current transport type is 'stdio'.
+   * @internal
+   */
+  _assertStdioType(methodName) {
+    if (this._config.type !== "stdio") {
+      throw new IgniterAgentConfigError({
+        message: `${methodName}() is only available for stdio transport. Current type: '${this._config.type || "not set"}'. Call withType('stdio') first.`,
+        field: "type",
+        metadata: { mcpName: this._config.name, operation: methodName }
+      });
+    }
+  }
+  /**
+   * Asserts that the current transport type is 'http'.
+   * @internal
+   */
+  _assertHttpType(methodName) {
+    if (this._config.type !== "http") {
+      throw new IgniterAgentConfigError({
+        message: `${methodName}() is only available for http transport. Current type: '${this._config.type || "not set"}'. Call withType('http') first.`,
+        field: "type",
+        metadata: { mcpName: this._config.name, operation: methodName }
+      });
+    }
+  }
+};
+var IgniterAgentMCPClient = {
+  create: IgniterAgentMCPBuilder.create
+};
+
+// src/adapters/memory.adapter.ts
+var IgniterAgentInMemoryAdapter = class _IgniterAgentInMemoryAdapter {
+  /**
+   * Creates a new IgniterAgentInMemoryAdapter.
+   * 
+   * @param options - Adapter configuration
+   * 
+   * @example
+   * ```typescript
+   * const adapter = new IgniterAgentInMemoryAdapter({
+   *   namespace: 'myapp',
+   *   maxMessages: 1000,
+   *   maxChats: 100
+   * });
+   * ```
+   */
+  constructor(options = {}) {
+    /**
+     * Storage for working memory.
+     * Key format: `{namespace}:{scope}:{identifier}`
+     * @internal
+     */
+    this._workingMemory = /* @__PURE__ */ new Map();
+    /**
+     * Storage for conversation messages.
+     * Key format: `{namespace}:{chatId}`
+     * @internal
+     */
+    this._messages = /* @__PURE__ */ new Map();
+    /**
+     * Storage for chat sessions.
+     * Key format: `{namespace}:{chatId}`
+     * @internal
+     */
+    this._chats = /* @__PURE__ */ new Map();
+    this.options = {
+      namespace: options.namespace ?? "igniter",
+      maxMessages: options.maxMessages ?? 1e3,
+      maxChats: options.maxChats ?? 100
+    };
+  }
+  /**
+   * Factory method to create a new adapter instance.
+   * @param options - Adapter configuration
+   * @returns A new IgniterAgentInMemoryAdapter instance
+   *
+   * @example
+   * ```typescript
+   * const adapter = IgniterAgentInMemoryAdapter.create({
+   *   namespace: 'test',
+   * });
+   * ```
+   */
+  static create(options) {
+    return new _IgniterAgentInMemoryAdapter(options);
+  }
+  /* ---------------------------------------------------------------------------
+   * HELPER METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Generates a storage key with namespace prefix.
+   * @internal
+   */
+  _key(...parts) {
+    return [this.options.namespace, ...parts].join(":");
+  }
+  /* ---------------------------------------------------------------------------
+   * LIFECYCLE METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Connects to the storage backend (no-op for in-memory).
+   * 
+   * @description
+   * In-memory adapter doesn't require connection setup.
+   * This method exists for interface compatibility.
+   */
+  async connect() {
+  }
+  /**
+   * Disconnects from the storage backend (no-op for in-memory).
+   * 
+   * @description
+   * In-memory adapter doesn't require disconnection.
+   * This method exists for interface compatibility.
+   */
+  async disconnect() {
+  }
+  /**
+   * Checks if the adapter is connected.
+   * 
+   * @returns Always true for in-memory adapter
+   */
+  isConnected() {
+    return true;
+  }
+  /**
+   * Clears all stored data.
+   * 
+   * @description
+   * Removes all working memory, messages, and chat sessions.
+   * Use with caution.
+   * 
+   * @example
+   * ```typescript
+   * // Clear all data (useful for testing)
+   * await adapter.clear();
+   * ```
+   */
+  async clear() {
+    this._workingMemory.clear();
+    this._messages.clear();
+    this._chats.clear();
+  }
+  /* ---------------------------------------------------------------------------
+   * WORKING MEMORY METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Gets working memory for a scope and identifier.
+   * 
+   * @param params - The scope and identifier
+   * @returns The working memory or null if not found
+   * 
+   * @example
+   * ```typescript
+   * const memory = await adapter.getWorkingMemory({
+   *   scope: 'chat',
+   *   identifier: 'chat_123'
+   * });
+   * 
+   * if (memory) {
+   *   console.log('Content:', memory.content);
+   *   console.log('Updated:', memory.updatedAt);
+   * }
+   * ```
+   */
+  async getWorkingMemory(params) {
+    const key = this._key("memory", params.scope, params.identifier);
+    return this._workingMemory.get(key) ?? null;
+  }
+  /**
+   * Updates working memory for a scope and identifier.
+   * 
+   * @param params - The scope, identifier, and new content
+   * 
+   * @example
+   * ```typescript
+   * await adapter.updateWorkingMemory({
+   *   scope: 'chat',
+   *   identifier: 'chat_123',
+   *   content: `
+   *     ## User Preferences
+   *     - Prefers TypeScript
+   *     - Uses VS Code
+   *   `
+   * });
+   * ```
+   */
+  async updateWorkingMemory(params) {
+    const key = this._key("memory", params.scope, params.identifier);
+    this._workingMemory.set(key, {
+      content: params.content,
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+  }
+  /* ---------------------------------------------------------------------------
+   * MESSAGE METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Saves a message to the conversation history.
+   * 
+   * @param message - The message to save
+   * 
+   * @example
+   * ```typescript
+   * await adapter.saveMessage({
+   *   chatId: 'chat_123',
+   *   userId: 'user_456',
+   *   role: 'user',
+   *   content: 'How do I use TypeScript?',
+   *   timestamp: new Date()
+   * });
+   * ```
+   */
+  async saveMessage(message) {
+    const key = this._key("messages", message.chatId);
+    let messages = this._messages.get(key);
+    if (!messages) {
+      messages = [];
+      this._messages.set(key, messages);
+    }
+    messages.push(message);
+    if (messages.length > this.options.maxMessages) {
+      messages.splice(0, messages.length - this.options.maxMessages);
+    }
+  }
+  /**
+   * Gets messages from the conversation history.
+   * 
+   * @typeParam T - The message type to return
+   * @param params - Query parameters
+   * @returns Array of messages
+   * 
+   * @example
+   * ```typescript
+   * const messages = await adapter.getMessages({
+   *   chatId: 'chat_123',
+   *   limit: 50
+   * });
+   * 
+   * for (const msg of messages) {
+   *   console.log(`[${msg.role}]: ${msg.content}`);
+   * }
+   * ```
+   */
+  async getMessages(params) {
+    const key = this._key("messages", params.chatId);
+    let messages = this._messages.get(key) ?? [];
+    if (params.userId) {
+      messages = messages.filter((m) => m.userId === params.userId);
+    }
+    if (params.limit && params.limit > 0) {
+      messages = messages.slice(-params.limit);
+    }
+    return messages.map((m) => ({
+      id: `${m.chatId}-${m.timestamp.getTime()}`,
+      role: m.role,
+      content: m.content,
+      createdAt: m.timestamp
+    }));
+  }
+  /* ---------------------------------------------------------------------------
+   * CHAT SESSION METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Saves or updates a chat session.
+   * 
+   * @param chat - The chat session to save
+   * 
+   * @example
+   * ```typescript
+   * await adapter.saveChat({
+   *   chatId: 'chat_123',
+   *   userId: 'user_456',
+   *   title: 'TypeScript Help',
+   *   createdAt: new Date(),
+   *   updatedAt: new Date(),
+   *   messageCount: 0
+   * });
+   * ```
+   */
+  async saveChat(chat) {
+    const key = this._key("chats", chat.chatId);
+    this._chats.set(key, chat);
+    if (this._chats.size > this.options.maxChats) {
+      const entries = Array.from(this._chats.entries()).sort((a, b) => a[1].updatedAt.getTime() - b[1].updatedAt.getTime());
+      const toRemove = entries.slice(0, this._chats.size - this.options.maxChats);
+      for (const [k] of toRemove) {
+        this._chats.delete(k);
+      }
+    }
+  }
+  /**
+   * Gets chat sessions matching the query parameters.
+   * 
+   * @param params - Query parameters
+   * @returns Array of chat sessions
+   * 
+   * @example
+   * ```typescript
+   * const chats = await adapter.getChats({
+   *   userId: 'user_456',
+   *   search: 'typescript',
+   *   limit: 10
+   * });
+   * 
+   * for (const chat of chats) {
+   *   console.log(`${chat.title} (${chat.messageCount} messages)`);
+   * }
+   * ```
+   */
+  async getChats(params) {
+    let chats = Array.from(this._chats.values());
+    if (params.userId) {
+      chats = chats.filter((c) => c.userId === params.userId);
+    }
+    if (params.search) {
+      const searchLower = params.search.toLowerCase();
+      chats = chats.filter(
+        (c) => c.title?.toLowerCase().includes(searchLower)
+      );
+    }
+    chats.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+    if (params.limit && params.limit > 0) {
+      chats = chats.slice(0, params.limit);
+    }
+    return chats;
+  }
+  /**
+   * Gets a specific chat session by ID.
+   * 
+   * @param chatId - The chat ID
+   * @returns The chat session or null if not found
+   * 
+   * @example
+   * ```typescript
+   * const chat = await adapter.getChat('chat_123');
+   * 
+   * if (chat) {
+   *   console.log('Title:', chat.title);
+   *   console.log('Messages:', chat.messageCount);
+   * }
+   * ```
+   */
+  async getChat(chatId) {
+    const key = this._key("chats", chatId);
+    return this._chats.get(key) ?? null;
+  }
+  /**
+   * Updates the title of a chat session.
+   * 
+   * @param chatId - The chat ID
+   * @param title - The new title
+   * 
+   * @example
+   * ```typescript
+   * await adapter.updateChatTitle('chat_123', 'New Title');
+   * ```
+   */
+  async updateChatTitle(chatId, title) {
+    const key = this._key("chats", chatId);
+    const chat = this._chats.get(key);
+    if (chat) {
+      chat.title = title;
+      chat.updatedAt = /* @__PURE__ */ new Date();
+    }
+  }
+  /**
+   * Deletes a chat session and its messages.
+   * 
+   * @param chatId - The chat ID to delete
+   * 
+   * @example
+   * ```typescript
+   * await adapter.deleteChat('chat_123');
+   * ```
+   */
+  async deleteChat(chatId) {
+    const chatKey = this._key("chats", chatId);
+    const messagesKey = this._key("messages", chatId);
+    this._chats.delete(chatKey);
+    this._messages.delete(messagesKey);
+  }
+  /* ---------------------------------------------------------------------------
+   * STATS METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Gets storage statistics.
+   * 
+   * @returns Current storage stats
+   * 
+   * @example
+   * ```typescript
+   * const stats = await adapter.getStats();
+   * console.log(`Storing ${stats.messageCount} messages`);
+   * console.log(`Across ${stats.chatCount} chats`);
+   * ```
+   */
+  async getStats() {
+    let messageCount = 0;
+    for (const messages of this._messages.values()) {
+      messageCount += messages.length;
+    }
+    return {
+      workingMemoryCount: this._workingMemory.size,
+      messageCount,
+      chatCount: this._chats.size,
+      timestamp: /* @__PURE__ */ new Date()
+    };
+  }
+};
+var IgniterAgentJSONFileAdapter = class _IgniterAgentJSONFileAdapter {
+  /**
+   * Creates a new IgniterAgentJSONFileAdapter.
+   * 
+   * @param options - Adapter configuration
+   * 
+   * @example
+   * ```typescript
+   * const adapter = new IgniterAgentJSONFileAdapter({
+   *   dataDir: './memory',
+   *   namespace: 'myapp'
+   * });
+   * ```
+   */
+  constructor(options = {}) {
+    /**
+     * Whether the adapter is currently connected and ready to use.
+     * @internal
+     */
+    this._connected = false;
+    /**
+     * In-memory cache of working memory entries.
+     * @internal
+     */
+    this._workingMemoryCache = /* @__PURE__ */ new Map();
+    /**
+     * In-memory cache of messages.
+     * @internal
+     */
+    this._messagesCache = /* @__PURE__ */ new Map();
+    /**
+     * In-memory cache of chat sessions.
+     * @internal
+     */
+    this._chatsCache = /* @__PURE__ */ new Map();
+    this.options = {
+      dataDir: options.dataDir ?? "./igniter-agent-memory",
+      namespace: options.namespace ?? "igniter",
+      autoSync: options.autoSync ?? true,
+      debug: options.debug ?? false,
+      maxMessages: options.maxMessages ?? 1e3,
+      maxChats: options.maxChats ?? 100
+    };
+  }
+  /**
+   * Factory method to create a new adapter instance.
+   * @param options - Adapter configuration
+   * @returns A new IgniterAgentJSONFileAdapter instance
+   *
+   * @example
+   * ```typescript
+   * const adapter = IgniterAgentJSONFileAdapter.create({
+   *   dataDir: './data',
+   * });
+   * ```
+   */
+  static create(options) {
+    return new _IgniterAgentJSONFileAdapter(options);
+  }
+  /* ---------------------------------------------------------------------------
+   * PRIVATE HELPER METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Logs debug messages if debug mode is enabled.
+   * @internal
+   */
+  _log(message, data) {
+    if (this.options.debug) {
+      console.log(`[IgniterAgentJSONFileAdapter] ${message}`, data ?? "");
+    }
+  }
+  /**
+   * Gets the path for the working memory JSON file.
+   * @internal
+   */
+  _getWorkingMemoryPath() {
+    return join(this.options.dataDir, "working-memory.json");
+  }
+  /**
+   * Gets the path for the chats JSON file.
+   * @internal
+   */
+  _getChatsPath() {
+    return join(this.options.dataDir, "chats.json");
+  }
+  /**
+   * Gets the directory for message files.
+   * @internal
+   */
+  _getMessagesDir() {
+    return join(this.options.dataDir, "messages");
+  }
+  /**
+   * Gets the path for a specific chat's messages JSON file.
+   * @internal
+   */
+  _getMessagesPath(chatId) {
+    return join(this._getMessagesDir(), `${chatId}.json`);
+  }
+  /**
+   * Generates a cache key with namespace prefix.
+   * @internal
+   */
+  _key(...parts) {
+    return [this.options.namespace, ...parts].join(":");
+  }
+  /**
+   * Loads working memory from disk.
+   * @internal
+   */
+  async _loadWorkingMemory() {
+    try {
+      const path = this._getWorkingMemoryPath();
+      const content = await readFile(path, "utf-8");
+      const data = JSON.parse(content);
+      this._workingMemoryCache.clear();
+      for (const [key, value] of Object.entries(data)) {
+        this._workingMemoryCache.set(key, {
+          content: value.content,
+          updatedAt: new Date(value.updatedAt)
+        });
+      }
+      this._log("Loaded working memory", {
+        entries: this._workingMemoryCache.size
+      });
+    } catch (err) {
+      this._log("Working memory file not found, starting fresh");
+    }
+  }
+  /**
+   * Loads chats from disk.
+   * @internal
+   */
+  async _loadChats() {
+    try {
+      const path = this._getChatsPath();
+      const content = await readFile(path, "utf-8");
+      const data = JSON.parse(content);
+      this._chatsCache.clear();
+      for (const [key, value] of Object.entries(data)) {
+        const chat = value;
+        this._chatsCache.set(key, {
+          chatId: chat.chatId,
+          userId: chat.userId,
+          title: chat.title,
+          createdAt: new Date(chat.createdAt),
+          updatedAt: new Date(chat.updatedAt),
+          messageCount: chat.messageCount
+        });
+      }
+      this._log("Loaded chats", { entries: this._chatsCache.size });
+    } catch (err) {
+      this._log("Chats file not found, starting fresh");
+    }
+  }
+  /**
+   * Loads a specific chat's messages from disk.
+   * @internal
+   */
+  async _loadMessages(chatId) {
+    try {
+      const path = this._getMessagesPath(chatId);
+      const content = await readFile(path, "utf-8");
+      const data = JSON.parse(content);
+      const key = this._key("messages", chatId);
+      const messages = data.map(
+        (msg) => ({
+          chatId: msg.chatId,
+          userId: msg.userId,
+          role: msg.role,
+          content: msg.content,
+          timestamp: new Date(msg.timestamp)
+        })
+      );
+      this._messagesCache.set(key, messages);
+      this._log("Loaded messages", { chatId, count: messages.length });
+    } catch (err) {
+      this._log("Messages file not found for chat", { chatId });
+    }
+  }
+  /**
+   * Saves working memory to disk.
+   * @internal
+   */
+  async _saveWorkingMemory() {
+    const path = this._getWorkingMemoryPath();
+    const data = {};
+    for (const [key, value] of this._workingMemoryCache.entries()) {
+      data[key] = {
+        content: value.content,
+        updatedAt: value.updatedAt.toISOString()
+      };
+    }
+    await writeFile(path, JSON.stringify(data, null, 2));
+    this._log("Saved working memory");
+  }
+  /**
+   * Saves chats to disk.
+   * @internal
+   */
+  async _saveChats() {
+    const path = this._getChatsPath();
+    const data = {};
+    for (const [key, value] of this._chatsCache.entries()) {
+      data[key] = {
+        chatId: value.chatId,
+        userId: value.userId,
+        title: value.title,
+        createdAt: value.createdAt.toISOString(),
+        updatedAt: value.updatedAt.toISOString(),
+        messageCount: value.messageCount
+      };
+    }
+    await writeFile(path, JSON.stringify(data, null, 2));
+    this._log("Saved chats");
+  }
+  /**
+   * Saves messages for a specific chat to disk.
+   * @internal
+   */
+  async _saveMessages(chatId) {
+    const key = this._key("messages", chatId);
+    const messages = this._messagesCache.get(key) ?? [];
+    const path = this._getMessagesPath(chatId);
+    const data = messages.map((msg) => ({
+      chatId: msg.chatId,
+      userId: msg.userId,
+      role: msg.role,
+      content: msg.content,
+      timestamp: msg.timestamp.toISOString()
+    }));
+    await writeFile(path, JSON.stringify(data, null, 2));
+    this._log("Saved messages", { chatId, count: messages.length });
+  }
+  /* ---------------------------------------------------------------------------
+   * LIFECYCLE METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Connects to the storage backend and loads data from disk.
+   * 
+   * @description
+   * Creates necessary directories and loads all data into memory cache.
+   * Must be called before using the adapter.
+   * 
+   * @throws {Error} If directory creation fails
+   * 
+   * @example
+   * ```typescript
+   * const adapter = new IgniterAgentJSONFileAdapter();
+   * await adapter.connect();
+   * ```
+   */
+  async connect() {
+    try {
+      await mkdir(this.options.dataDir, { recursive: true });
+      await mkdir(this._getMessagesDir(), { recursive: true });
+      await this._loadWorkingMemory();
+      await this._loadChats();
+      this._connected = true;
+      this._log("Connected successfully", {
+        dataDir: this.options.dataDir
+      });
+    } catch (err) {
+      this._log("Connection failed", err);
+      throw err;
+    }
+  }
+  /**
+   * Disconnects from the storage backend.
+   * 
+   * @description
+   * Syncs any pending changes to disk before disconnecting.
+   * 
+   * @example
+   * ```typescript
+   * await adapter.disconnect();
+   * ```
+   */
+  async disconnect() {
+    if (this._connected) {
+      await this.sync();
+      this._connected = false;
+      this._log("Disconnected");
+    }
+  }
+  /**
+   * Checks if the adapter is connected and ready to use.
+   * 
+   * @returns True if connected, false otherwise
+   */
+  isConnected() {
+    return this._connected;
+  }
+  /**
+   * Manually syncs all in-memory data to disk.
+   * 
+   * @description
+   * Called automatically if autoSync is enabled. Can be called manually
+   * to ensure data is persisted to disk.
+   * 
+   * @example
+   * ```typescript
+   * await adapter.updateWorkingMemory({ ... });
+   * await adapter.sync(); // Ensure written to disk
+   * ```
+   */
+  async sync() {
+    try {
+      await this._saveWorkingMemory();
+      await this._saveChats();
+      for (const chatId of this._messagesCache.keys()) {
+        const idParts = chatId.split(":");
+        if (idParts.length > 0) {
+          const actualChatId = idParts[idParts.length - 1];
+          await this._saveMessages(actualChatId);
+        }
+      }
+      this._log("Synced all data to disk");
+    } catch (err) {
+      this._log("Sync failed", err);
+      throw err;
+    }
+  }
+  /**
+   * Clears all stored data from disk and memory.
+   * 
+   * @description
+   * Removes all working memory, messages, and chat sessions.
+   * Use with caution.
+   * 
+   * @example
+   * ```typescript
+   * await adapter.clear();
+   * ```
+   */
+  async clear() {
+    this._workingMemoryCache.clear();
+    this._messagesCache.clear();
+    this._chatsCache.clear();
+    if (this.options.autoSync) {
+      await this.sync();
+    }
+    this._log("Cleared all data");
+  }
+  /* ---------------------------------------------------------------------------
+   * WORKING MEMORY METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Gets working memory for a scope and identifier.
+   * 
+   * @param params - The scope and identifier
+   * @returns The working memory or null if not found
+   * 
+   * @example
+   * ```typescript
+   * const memory = await adapter.getWorkingMemory({
+   *   scope: 'chat',
+   *   identifier: 'chat_123'
+   * });
+   * 
+   * if (memory) {
+   *   console.log('Content:', memory.content);
+   * }
+   * ```
+   */
+  async getWorkingMemory(params) {
+    const key = this._key("memory", params.scope, params.identifier);
+    return this._workingMemoryCache.get(key) ?? null;
+  }
+  /**
+   * Updates working memory for a scope and identifier.
+   * 
+   * @param params - The scope, identifier, and new content
+   * 
+   * @example
+   * ```typescript
+   * await adapter.updateWorkingMemory({
+   *   scope: 'chat',
+   *   identifier: 'chat_123',
+   *   content: 'User prefers TypeScript'
+   * });
+   * ```
+   */
+  async updateWorkingMemory(params) {
+    const key = this._key("memory", params.scope, params.identifier);
+    this._workingMemoryCache.set(key, {
+      content: params.content,
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+    if (this.options.autoSync) {
+      await this._saveWorkingMemory();
+    }
+  }
+  /* ---------------------------------------------------------------------------
+   * MESSAGE METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Saves a message to the conversation history.
+   * 
+   * @param message - The message to save
+   * 
+   * @example
+   * ```typescript
+   * await adapter.saveMessage({
+   *   chatId: 'chat_123',
+   *   userId: 'user_456',
+   *   role: 'user',
+   *   content: 'How do I use TypeScript?',
+   *   timestamp: new Date()
+   * });
+   * ```
+   */
+  async saveMessage(message) {
+    const key = this._key("messages", message.chatId);
+    let messages = this._messagesCache.get(key);
+    if (!messages) {
+      messages = [];
+      this._messagesCache.set(key, messages);
+    }
+    messages.push(message);
+    if (messages.length > this.options.maxMessages) {
+      messages.splice(0, messages.length - this.options.maxMessages);
+    }
+    if (this.options.autoSync) {
+      await this._saveMessages(message.chatId);
+    }
+  }
+  /**
+   * Gets messages from the conversation history.
+   * 
+   * @typeParam T - The message type to return
+   * @param params - Query parameters
+   * @returns Array of messages
+   * 
+   * @example
+   * ```typescript
+   * const messages = await adapter.getMessages({
+   *   chatId: 'chat_123',
+   *   limit: 50
+   * });
+   * 
+   * for (const msg of messages) {
+   *   console.log(`[${msg.role}]: ${msg.content}`);
+   * }
+   * ```
+   */
+  async getMessages(params) {
+    const key = this._key("messages", params.chatId);
+    if (!this._messagesCache.has(key)) {
+      await this._loadMessages(params.chatId);
+    }
+    let messages = this._messagesCache.get(key) ?? [];
+    if (params.userId) {
+      messages = messages.filter((m) => m.userId === params.userId);
+    }
+    if (params.limit && params.limit > 0) {
+      messages = messages.slice(-params.limit);
+    }
+    return messages.map((m) => ({
+      id: `${m.chatId}-${m.timestamp.getTime()}`,
+      role: m.role,
+      content: m.content,
+      createdAt: m.timestamp
+    }));
+  }
+  /* ---------------------------------------------------------------------------
+   * CHAT SESSION METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Saves or updates a chat session.
+   * 
+   * @param chat - The chat session to save
+   * 
+   * @example
+   * ```typescript
+   * await adapter.saveChat({
+   *   chatId: 'chat_123',
+   *   userId: 'user_456',
+   *   title: 'TypeScript Help',
+   *   createdAt: new Date(),
+   *   updatedAt: new Date(),
+   *   messageCount: 0
+   * });
+   * ```
+   */
+  async saveChat(chat) {
+    const key = this._key("chats", chat.chatId);
+    this._chatsCache.set(key, chat);
+    if (this._chatsCache.size > this.options.maxChats) {
+      const entries = Array.from(this._chatsCache.entries()).sort(
+        (a, b) => a[1].updatedAt.getTime() - b[1].updatedAt.getTime()
+      );
+      const toRemove = entries.slice(
+        0,
+        this._chatsCache.size - this.options.maxChats
+      );
+      for (const [k] of toRemove) {
+        this._chatsCache.delete(k);
+      }
+    }
+    if (this.options.autoSync) {
+      await this._saveChats();
+    }
+  }
+  /**
+   * Gets chat sessions matching the query parameters.
+   * 
+   * @param params - Query parameters
+   * @returns Array of chat sessions
+   * 
+   * @example
+   * ```typescript
+   * const chats = await adapter.getChats({
+   *   userId: 'user_456',
+   *   search: 'typescript',
+   *   limit: 10
+   * });
+   * 
+   * for (const chat of chats) {
+   *   console.log(`${chat.title} (${chat.messageCount} messages)`);
+   * }
+   * ```
+   */
+  async getChats(params) {
+    let chats = Array.from(this._chatsCache.values());
+    if (params.userId) {
+      chats = chats.filter((c) => c.userId === params.userId);
+    }
+    if (params.search) {
+      const searchLower = params.search.toLowerCase();
+      chats = chats.filter(
+        (c) => c.title?.toLowerCase().includes(searchLower)
+      );
+    }
+    chats.sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+    if (params.limit && params.limit > 0) {
+      chats = chats.slice(0, params.limit);
+    }
+    return chats;
+  }
+  /**
+   * Gets a specific chat session by ID.
+   * 
+   * @param chatId - The chat ID
+   * @returns The chat session or null if not found
+   * 
+   * @example
+   * ```typescript
+   * const chat = await adapter.getChat('chat_123');
+   * 
+   * if (chat) {
+   *   console.log('Title:', chat.title);
+   * }
+   * ```
+   */
+  async getChat(chatId) {
+    const key = this._key("chats", chatId);
+    return this._chatsCache.get(key) ?? null;
+  }
+  /**
+   * Updates the title of a chat session.
+   * 
+   * @param chatId - The chat ID
+   * @param title - The new title
+   * 
+   * @example
+   * ```typescript
+   * await adapter.updateChatTitle('chat_123', 'New Title');
+   * ```
+   */
+  async updateChatTitle(chatId, title) {
+    const key = this._key("chats", chatId);
+    const chat = this._chatsCache.get(key);
+    if (chat) {
+      chat.title = title;
+      chat.updatedAt = /* @__PURE__ */ new Date();
+      if (this.options.autoSync) {
+        await this._saveChats();
+      }
+    }
+  }
+  /**
+   * Deletes a chat session and its messages.
+   * 
+   * @param chatId - The chat ID to delete
+   * 
+   * @example
+   * ```typescript
+   * await adapter.deleteChat('chat_123');
+   * ```
+   */
+  async deleteChat(chatId) {
+    const chatKey = this._key("chats", chatId);
+    const messagesKey = this._key("messages", chatId);
+    this._chatsCache.delete(chatKey);
+    this._messagesCache.delete(messagesKey);
+    if (this.options.autoSync) {
+      await this._saveChats();
+      try {
+        const path = this._getMessagesPath(chatId);
+        await readFile(path);
+        this._log("Messages file for deleted chat still exists");
+      } catch {
+      }
+    }
+  }
+  /* ---------------------------------------------------------------------------
+   * STATS METHODS
+   * --------------------------------------------------------------------------- */
+  /**
+   * Gets storage statistics.
+   * 
+   * @returns Current storage stats
+   * 
+   * @example
+   * ```typescript
+   * const stats = await adapter.getStats();
+   * console.log(`Storing ${stats.messageCount} messages`);
+   * console.log(`Across ${stats.chatCount} chats`);
+   * ```
+   */
+  async getStats() {
+    let messageCount = 0;
+    for (const messages of this._messagesCache.values()) {
+      messageCount += messages.length;
+    }
+    return {
+      workingMemoryCount: this._workingMemoryCache.size,
+      messageCount,
+      chatCount: this._chatsCache.size,
+      timestamp: /* @__PURE__ */ new Date()
+    };
+  }
+};
+
+// 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, IgniterAgentTelemetryEvents, IgniterAgentTool, IgniterAgentToolBuilder, IgniterAgentToolError, IgniterAgentToolset, IgniterAgentToolsetBuilder, IgniterAgentValidationUtils, isIgniterAgentError, isIgniterAgentMCPError, isIgniterAgentToolError, wrapError };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map