@jterrazz/intelligence 1.2.0 → 1.3.0

package/README.md

@@ -30,7 +30,7 @@ Get your first agent running in under a minute. This example uses a preset to cr
 
 ```typescript
 import {
-  ChatAgentAdapter,
+  AutonomousAgentAdapter,
   OpenRouterAdapter,
   SystemPromptAdapter,
   PROMPT_LIBRARY,
@@ -43,7 +43,7 @@ const model = new OpenRouterAdapter({
 });
 
 // 2. Create an agent using a preset prompt
-const agent = new ChatAgentAdapter('discord-bot', {
+const agent = new AutonomousAgentAdapter('discord-bot', {
   model,
   systemPrompt: new SystemPromptAdapter(PROMPT_LIBRARY.PRESETS.COMMUNITY_ANIMATOR),
 });
@@ -104,7 +104,7 @@ The adapter handles errors gracefully and integrates seamlessly with the agent,
 The library is built on a hexagonal architecture.
 
 - **Ports (`/ports`)**: Define the contracts (interfaces) for core components like `Agent`, `Model`, and `Tool`.
-- **Adapters (`/adapters`)**: Provide concrete implementations. For example, `ChatAgentAdapter` is an adapter that uses LangChain, and `OpenRouterAdapter` is an adapter for the OpenRouter API.
+- **Adapters (`/adapters`)**: Provide concrete implementations. For example, `AutonomousAgentAdapter` is an adapter that uses LangChain, and `OpenRouterAdapter` is an adapter for the OpenRouter API.
 
 This separation of concerns means you can easily create your own adapters to support different models or services without changing the application's core logic.
 
@@ -124,7 +124,7 @@ This recipe creates an agent that acts as an expert software engineer, providing
 
 ```typescript
 import {
-  ChatAgentAdapter,
+  AutonomousAgentAdapter,
   OpenRouterAdapter,
   SystemPromptAdapter,
   UserPromptAdapter,
@@ -153,7 +153,7 @@ const userPrompt = new UserPromptAdapter([
 ]);
 
 // 3. Configure and run the agent
-const agent = new ChatAgentAdapter('code-reviewer', {
+const agent = new AutonomousAgentAdapter('code-reviewer', {
   model,
   systemPrompt,
 });
@@ -163,13 +163,13 @@ const response = await agent.run(userPrompt);
 console.log(response);
 ```
 
-### Recipe: Simple Text Processor (QueryAgent)
+### Recipe: Simple Text Processor (BasicAgent)
 
-This example shows how to use the simpler `QueryAgentAdapter` for one-shot responses without tools.
+This example shows how to use the simpler `BasicAgentAdapter` for one-shot responses without tools.
 
 ```typescript
 import {
-  QueryAgentAdapter,
+  BasicAgentAdapter,
   OpenRouterAdapter,
   SystemPromptAdapter,
   UserPromptAdapter,
@@ -189,8 +189,8 @@ const systemPrompt = new SystemPromptAdapter(
   'You are a helpful assistant that improves text clarity and grammar.',
 );
 
-// 2. Create a query agent (no tools needed)
-const agent = new QueryAgentAdapter('text-processor', {
+// 2. Create a basic agent (no tools needed)
+const agent = new BasicAgentAdapter('text-processor', {
   model,
   systemPrompt,
 });
@@ -205,13 +205,13 @@ console.log(response);
 // Expected output: A grammatically corrected and improved version of the text
 ```
 
-### Recipe: Structured Data Extraction (QueryAgent with Schema)
+### Recipe: Structured Data Extraction (BasicAgent with Schema)
 
-This example shows how to use `QueryAgentAdapter` with schema parsing for structured responses.
+This example shows how to use `BasicAgentAdapter` with schema parsing for structured responses.
 
 ```typescript
 import {
-  QueryAgentAdapter,
+  BasicAgentAdapter,
   OpenRouterAdapter,
   SystemPromptAdapter,
   UserPromptAdapter,
@@ -240,8 +240,8 @@ const systemPrompt = new SystemPromptAdapter(
   'You extract contact information from text and return it as JSON.',
 );
 
-// 3. Create a query agent with schema parsing
-const agent = new QueryAgentAdapter('contact-extractor', {
+// 3. Create a basic agent with schema parsing
+const agent = new BasicAgentAdapter('contact-extractor', {
   model,
   schema: extractionSchema,
   systemPrompt,
@@ -266,7 +266,7 @@ This example shows how to give an agent a tool and have it respond to a user que
 
 ```typescript
 import {
-  ChatAgentAdapter,
+  AutonomousAgentAdapter,
   OpenRouterAdapter,
   SafeToolAdapter,
   SystemPromptAdapter,
@@ -291,7 +291,7 @@ const weatherTool = new SafeToolAdapter(
 );
 
 // 2. Create an agent that knows how to use tools
-const agent = new ChatAgentAdapter('weather-bot', {
+const agent = new AutonomousAgentAdapter('weather-bot', {
   model,
   systemPrompt: new SystemPromptAdapter(PROMPT_LIBRARY.PRESETS.EMPATHETIC_SUPPORT_AGENT), // A good general-purpose preset
   tools: [weatherTool], // Pass the tool instance directly
@@ -310,16 +310,16 @@ console.log(response);
 
 ### Core Components
 
-| Class                    | Description                                                                |
-| ------------------------ | -------------------------------------------------------------------------- |
-| `ChatAgentAdapter`       | The main agent implementation. Runs prompts and coordinates tools.         |
-| `QueryAgentAdapter`      | A simpler agent for one-shot responses without tools or complex logic.     |
-| `OpenRouterModelAdapter` | An adapter for connecting to any model on the OpenRouter platform.         |
-| `SafeToolAdapter`        | A type-safe wrapper for creating tools with validation and error handling. |
-| `SystemPromptAdapter`    | A simple adapter to generate a system prompt string from a prompt array.   |
-| `UserPromptAdapter`      | A simple adapter to generate a user prompt string from a prompt array.     |
-| `AIResponseParser`       | A utility to parse a model's string output into a typed object using Zod.  |
-| `PROMPT_LIBRARY`         | A frozen object containing the entire composable prompt library.           |
+| Class                    | Description                                                                     |
+| ------------------------ | ------------------------------------------------------------------------------- |
+| `AutonomousAgentAdapter` | The main agent implementation. Runs prompts and coordinates tools autonomously. |
+| `BasicAgentAdapter`      | A basic agent for one-shot responses without tools or complex logic.            |
+| `OpenRouterModelAdapter` | An adapter for connecting to any model on the OpenRouter platform.              |
+| `SafeToolAdapter`        | A type-safe wrapper for creating tools with validation and error handling.      |
+| `SystemPromptAdapter`    | A simple adapter to generate a system prompt string from a prompt array.        |
+| `UserPromptAdapter`      | A simple adapter to generate a user prompt string from a prompt array.          |
+| `AIResponseParser`       | A utility to parse a model's string output into a typed object using Zod.       |
+| `PROMPT_LIBRARY`         | A frozen object containing the entire composable prompt library.                |
 
 ## Contributing
 

package/dist/adapters/agents/{chat-agent.adapter.d.ts → autonomous-agent.adapter.d.ts}

@@ -5,7 +5,7 @@ import type { ModelPort } from '../../ports/model.port.js';
 import type { PromptPort } from '../../ports/prompt.port.js';
 import type { ToolPort } from '../../ports/tool.port.js';
 import type { SystemPromptAdapter } from '../prompts/system-prompt.adapter.js';
-export interface ChatAgentOptions<T = unknown> {
+export interface AutonomousAgentOptions<T = unknown> {
     logger?: LoggerPort;
     model: ModelPort;
     schema?: z.ZodSchema<T>;
@@ -14,13 +14,13 @@ export interface ChatAgentOptions<T = unknown> {
     verbose?: boolean;
 }
 /**
- * An advanced agent that uses tools and a structured prompt to engage in conversational chat.
+ * An autonomous agent that uses tools and a structured prompt to accomplish tasks.
  * It can decide whether to respond or remain silent and supports schema-validated responses.
  */
-export declare class ChatAgentAdapter<T = unknown> implements AgentPort {
+export declare class AutonomousAgentAdapter<T = unknown> implements AgentPort {
     readonly name: string;
     private readonly options;
-    constructor(name: string, options: ChatAgentOptions<T>);
+    constructor(name: string, options: AutonomousAgentOptions<T>);
     run(userPrompt?: PromptPort): Promise<null | string>;
     private createExecutor;
     private parseAgentOutput;

package/dist/adapters/agents/{chat-agent.adapter.js → autonomous-agent.adapter.js}

@@ -162,18 +162,18 @@ import { AgentExecutor, createStructuredChatAgent } from 'langchain/agents';
 import { AIResponseParser } from '../utils/ai-response-parser.js';
 var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<OUTPUT_FORMAT>\nCRITICAL: The format instructions in this section are the ONLY valid way to structure your response. Your entire response MUST be a single JSON markdown code block. Any formatting guidelines within the <OBJECTIVE> section apply ONLY to the content inside the "RESPOND:" part of your final "action_input".\n\nREQUIRED: You have two ways to respond:\n\n1.  **Call a tool** to gather information. For this, you MUST output a JSON blob with the tool\'s name and its input.\n    *Valid tool names are: {tool_names}*\n    ```json\n    {{\n      "action": "tool_name_to_use",\n      "action_input": "the input for the tool, or an empty object {{}} if no input is needed"\n    }}\n    ```\n\n2.  **Provide the Final Answer** once you have enough information. For this, you MUST output a JSON blob with the "Final Answer" action.\n    The "action_input" for a "Final Answer" MUST be a string that begins with either "RESPOND: " for a message or "SILENT: " for no message. This prefix is a literal part of the output string and MUST NOT be omitted.\n    - To send a message:\n      ```json\n      {{\n        "action": "Final Answer",\n        "action_input": "RESPOND: <your response message>"\n      }}\n      ```\n    - To stay silent:\n      ```json\n      {{\n        "action": "Final Answer",\n        "action_input": "SILENT: <your reason for staying silent>"\n      }}\n      ```\n\n    YOU MUST ALWAYS INCLUDE "RESPOND:" OR "SILENT:" IN YOUR FINAL ANSWER\'S "action_input". FAILURE TO DO SO WILL CAUSE AN ERROR.\n</OUTPUT_FORMAT>\n\n<EXECUTION_CONTEXT>\nThis is internal data for your reference.\n\n<TOOLS>\n{tools}\n</TOOLS>\n\n<WORKING_MEMORY>\nThis is your internal thought process and previous tool usage.\n{agent_scratchpad}\n</WORKING_MEMORY>\n</EXECUTION_CONTEXT>\n';
 /**
- * An advanced agent that uses tools and a structured prompt to engage in conversational chat.
+ * An autonomous agent that uses tools and a structured prompt to accomplish tasks.
  * It can decide whether to respond or remain silent and supports schema-validated responses.
- */ export var ChatAgentAdapter = /*#__PURE__*/ function() {
+ */ export var AutonomousAgentAdapter = /*#__PURE__*/ function() {
     "use strict";
-    function ChatAgentAdapter(name, options) {
-        _class_call_check(this, ChatAgentAdapter);
+    function AutonomousAgentAdapter(name, options) {
+        _class_call_check(this, AutonomousAgentAdapter);
         _define_property(this, "name", void 0);
         _define_property(this, "options", void 0);
         this.name = name;
         this.options = options;
     }
-    _create_class(ChatAgentAdapter, [
+    _create_class(AutonomousAgentAdapter, [
         {
             key: "run",
             value: function run(userPrompt) {
@@ -355,7 +355,7 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
             }
         }
     ]);
-    return ChatAgentAdapter;
+    return AutonomousAgentAdapter;
 }();
 
-//# sourceMappingURL=chat-agent.adapter.js.map
+//# sourceMappingURL=autonomous-agent.adapter.js.map

package/dist/adapters/agents/autonomous-agent.adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/adapters/agents/autonomous-agent.adapter.ts"],"sourcesContent":["import { type LoggerPort } from '@jterrazz/logger';\nimport { ChatPromptTemplate } from '@langchain/core/prompts';\nimport { AgentExecutor, createStructuredChatAgent } from 'langchain/agents';\nimport { type z } from 'zod/v4';\n\nimport { type AgentPort } from '../../ports/agent.port.js';\nimport type { ModelPort } from '../../ports/model.port.js';\nimport type { PromptPort } from '../../ports/prompt.port.js';\nimport type { ToolPort } from '../../ports/tool.port.js';\n\nimport { AIResponseParser } from '../utils/ai-response-parser.js';\n\nimport type { SystemPromptAdapter } from '../prompts/system-prompt.adapter.js';\n\nexport interface AutonomousAgentOptions<T = unknown> {\n    logger?: LoggerPort;\n    model: ModelPort;\n    schema?: z.ZodSchema<T>;\n    systemPrompt: SystemPromptAdapter;\n    tools: ToolPort[];\n    verbose?: boolean;\n}\n\nconst SYSTEM_PROMPT_TEMPLATE = `\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<OUTPUT_FORMAT>\nCRITICAL: The format instructions in this section are the ONLY valid way to structure your response. Your entire response MUST be a single JSON markdown code block. Any formatting guidelines within the <OBJECTIVE> section apply ONLY to the content inside the \"RESPOND:\" part of your final \"action_input\".\n\nREQUIRED: You have two ways to respond:\n\n1.  **Call a tool** to gather information. For this, you MUST output a JSON blob with the tool's name and its input.\n    *Valid tool names are: {tool_names}*\n    \\`\\`\\`json\n    {{\n      \"action\": \"tool_name_to_use\",\n      \"action_input\": \"the input for the tool, or an empty object {{}} if no input is needed\"\n    }}\n    \\`\\`\\`\n\n2.  **Provide the Final Answer** once you have enough information. For this, you MUST output a JSON blob with the \"Final Answer\" action.\n    The \"action_input\" for a \"Final Answer\" MUST be a string that begins with either \"RESPOND: \" for a message or \"SILENT: \" for no message. This prefix is a literal part of the output string and MUST NOT be omitted.\n    - To send a message:\n      \\`\\`\\`json\n      {{\n        \"action\": \"Final Answer\",\n        \"action_input\": \"RESPOND: <your response message>\"\n      }}\n      \\`\\`\\`\n    - To stay silent:\n      \\`\\`\\`json\n      {{\n        \"action\": \"Final Answer\",\n        \"action_input\": \"SILENT: <your reason for staying silent>\"\n      }}\n      \\`\\`\\`\n\n    YOU MUST ALWAYS INCLUDE \"RESPOND:\" OR \"SILENT:\" IN YOUR FINAL ANSWER'S \"action_input\". FAILURE TO DO SO WILL CAUSE AN ERROR.\n</OUTPUT_FORMAT>\n\n<EXECUTION_CONTEXT>\nThis is internal data for your reference.\n\n<TOOLS>\n{tools}\n</TOOLS>\n\n<WORKING_MEMORY>\nThis is your internal thought process and previous tool usage.\n{agent_scratchpad}\n</WORKING_MEMORY>\n</EXECUTION_CONTEXT>\n`;\n\n/**\n * An autonomous agent that uses tools and a structured prompt to accomplish tasks.\n * It can decide whether to respond or remain silent and supports schema-validated responses.\n */\nexport class AutonomousAgentAdapter<T = unknown> implements AgentPort {\n    constructor(\n        public readonly name: string,\n        private readonly options: AutonomousAgentOptions<T>,\n    ) {}\n\n    async run(userPrompt?: PromptPort): Promise<null | string> {\n        this.options.logger?.debug(`[${this.name}] Starting chat execution.`);\n\n        try {\n            const executor = await this.createExecutor();\n            const userInput = this.resolveUserInput(userPrompt);\n\n            const result = await executor.invoke({ input: userInput });\n\n            this.options.logger?.debug(`[${this.name}] Agent execution completed.`, {\n                hasOutput: 'output' in result,\n            });\n\n            if (!result || typeof result.output !== 'string') {\n                throw new Error('Agent returned an invalid result structure.');\n            }\n\n            const agentResponse = this.parseAgentOutput(result.output);\n\n            if (!agentResponse) {\n                return null;\n            }\n\n            if (!agentResponse.shouldRespond) {\n                this.options.logger?.info(`[${this.name}] Agent chose to remain silent.`, {\n                    reason: agentResponse.reason,\n                });\n                return null;\n            }\n\n            const message = agentResponse.message ?? '';\n\n            if (this.options.schema) {\n                this.validateResponseContent(message, this.options.schema);\n                this.options.logger?.info(\n                    `[${this.name}] Execution finished; response content validated.`,\n                );\n            } else {\n                this.options.logger?.info(`[${this.name}] Execution finished.`);\n            }\n\n            return message;\n        } catch (error) {\n            this.options.logger?.error(`[${this.name}] Chat execution failed.`, {\n                error: error instanceof Error ? error.message : 'Unknown error',\n            });\n            return null;\n        }\n    }\n\n    private async createExecutor(): Promise<AgentExecutor> {\n        const model = this.options.model.getModel();\n        const tools = this.options.tools.map((tool) => tool.getDynamicTool());\n\n        const prompt = ChatPromptTemplate.fromMessages([\n            [\n                'system',\n                SYSTEM_PROMPT_TEMPLATE.replace(\n                    '{mission_prompt}',\n                    this.options.systemPrompt.generate(),\n                ),\n            ],\n            ['human', '{input}'],\n        ]);\n\n        const agent = await createStructuredChatAgent({\n            llm: model,\n            prompt,\n            tools,\n        });\n\n        return AgentExecutor.fromAgentAndTools({\n            agent,\n            tools,\n            verbose: this.options.verbose,\n        });\n    }\n\n    private parseAgentOutput(output: string): null | {\n        message?: string;\n        reason?: string;\n        shouldRespond: boolean;\n    } {\n        const text = output.trim();\n\n        const respondMatch = text.match(/^RESPOND:\\s*([\\s\\S]+)$/i);\n        if (respondMatch) {\n            return { message: respondMatch[1].trim(), shouldRespond: true };\n        }\n\n        const silentMatch = text.match(/^SILENT:\\s*([\\s\\S]+)$/i);\n        if (silentMatch) {\n            return { reason: silentMatch[1].trim(), shouldRespond: false };\n        }\n\n        this.options.logger?.error(\n            `[${this.name}] Agent output was missing 'RESPOND:' or 'SILENT:' prefix.`,\n            { rawOutput: output },\n        );\n\n        return null;\n    }\n\n    private resolveUserInput(userPrompt?: PromptPort): string {\n        if (userPrompt) {\n            return userPrompt.generate();\n        }\n        return 'Proceed with your instructions.';\n    }\n\n    private validateResponseContent<TResponse>(\n        content: string,\n        schema: z.ZodSchema<TResponse>,\n    ): void {\n        try {\n            new AIResponseParser(schema).parse(content);\n        } catch (error) {\n            this.options.logger?.error(\n                `[${this.name}] Failed to validate response content against schema.`,\n                {\n                    error: error instanceof Error ? error.message : 'Unknown error',\n                    rawContent: content,\n                },\n            );\n            throw new Error('Invalid response content from model.');\n        }\n    }\n}\n"],"names":["ChatPromptTemplate","AgentExecutor","createStructuredChatAgent","AIResponseParser","SYSTEM_PROMPT_TEMPLATE","AutonomousAgentAdapter","name","options","run","userPrompt","executor","userInput","result","agentResponse","message","error","logger","debug","createExecutor","resolveUserInput","invoke","input","hasOutput","output","Error","parseAgentOutput","shouldRespond","info","reason","schema","validateResponseContent","model","tools","prompt","agent","getModel","map","tool","getDynamicTool","fromMessages","replace","systemPrompt","generate","llm","fromAgentAndTools","verbose","text","trim","respondMatch","match","silentMatch","rawOutput","content","parse","rawContent"],"mappings":"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"}

package/dist/adapters/agents/basic-agent.adapter.d.ts

@@ -0,0 +1,26 @@
+import { type LoggerPort } from '@jterrazz/logger';
+import { type z } from 'zod/v4';
+import { type AgentPort } from '../../ports/agent.port.js';
+import type { ModelPort } from '../../ports/model.port.js';
+import type { PromptPort } from '../../ports/prompt.port.js';
+import type { SystemPromptAdapter } from '../prompts/system-prompt.adapter.js';
+export interface BasicAgentOptions<T = string> {
+    logger?: LoggerPort;
+    model: ModelPort;
+    schema?: z.ZodSchema<T>;
+    systemPrompt: SystemPromptAdapter;
+    verbose?: boolean;
+}
+/**
+ * A basic agent for direct, one-shot interactions with a model.
+ * It supports optional response parsing against a Zod schema but does not use tools.
+ */
+export declare class BasicAgentAdapter<T = string> implements AgentPort {
+    readonly name: string;
+    private readonly options;
+    constructor(name: string, options: BasicAgentOptions<T>);
+    run(userPrompt?: PromptPort): Promise<null | string>;
+    private invokeModel;
+    private parseResponse;
+    private resolveUserInput;
+}

package/dist/adapters/agents/basic-agent.adapter.js

@@ -0,0 +1,303 @@
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _class_call_check(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+function _defineProperties(target, props) {
+    for(var i = 0; i < props.length; i++){
+        var descriptor = props[i];
+        descriptor.enumerable = descriptor.enumerable || false;
+        descriptor.configurable = true;
+        if ("value" in descriptor) descriptor.writable = true;
+        Object.defineProperty(target, descriptor.key, descriptor);
+    }
+}
+function _create_class(Constructor, protoProps, staticProps) {
+    if (protoProps) _defineProperties(Constructor.prototype, protoProps);
+    if (staticProps) _defineProperties(Constructor, staticProps);
+    return Constructor;
+}
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _instanceof(left, right) {
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() {
+        return this;
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+import { AIResponseParser } from '../utils/ai-response-parser.js';
+/**
+ * A basic agent for direct, one-shot interactions with a model.
+ * It supports optional response parsing against a Zod schema but does not use tools.
+ */ export var BasicAgentAdapter = /*#__PURE__*/ function() {
+    "use strict";
+    function BasicAgentAdapter(name, options) {
+        _class_call_check(this, BasicAgentAdapter);
+        _define_property(this, "name", void 0);
+        _define_property(this, "options", void 0);
+        this.name = name;
+        this.options = options;
+    }
+    _create_class(BasicAgentAdapter, [
+        {
+            key: "run",
+            value: function run(userPrompt) {
+                return _async_to_generator(function() {
+                    var _this_options_logger, content, _this_options_logger1, _this_options_logger2, error, _this_options_logger3;
+                    return _ts_generator(this, function(_state) {
+                        switch(_state.label){
+                            case 0:
+                                (_this_options_logger = this.options.logger) === null || _this_options_logger === void 0 ? void 0 : _this_options_logger.debug("[".concat(this.name, "] Starting query execution."));
+                                _state.label = 1;
+                            case 1:
+                                _state.trys.push([
+                                    1,
+                                    3,
+                                    ,
+                                    4
+                                ]);
+                                return [
+                                    4,
+                                    this.invokeModel(userPrompt)
+                                ];
+                            case 2:
+                                content = _state.sent();
+                                if (this.options.schema) {
+                                    ;
+                                    this.parseResponse(content, this.options.schema);
+                                    (_this_options_logger1 = this.options.logger) === null || _this_options_logger1 === void 0 ? void 0 : _this_options_logger1.info("[".concat(this.name, "] Execution finished and response parsed."));
+                                } else {
+                                    ;
+                                    (_this_options_logger2 = this.options.logger) === null || _this_options_logger2 === void 0 ? void 0 : _this_options_logger2.info("[".concat(this.name, "] Execution finished."));
+                                }
+                                return [
+                                    2,
+                                    content
+                                ];
+                            case 3:
+                                error = _state.sent();
+                                (_this_options_logger3 = this.options.logger) === null || _this_options_logger3 === void 0 ? void 0 : _this_options_logger3.error("[".concat(this.name, "] Execution failed."), {
+                                    error: _instanceof(error, Error) ? error.message : 'Unknown error'
+                                });
+                                return [
+                                    2,
+                                    null
+                                ];
+                            case 4:
+                                return [
+                                    2
+                                ];
+                        }
+                    });
+                }).call(this);
+            }
+        },
+        {
+            key: "invokeModel",
+            value: function invokeModel(userPrompt) {
+                return _async_to_generator(function() {
+                    var _this_options_logger, userInput, systemMessage, messages, _this_options_logger1, response, content;
+                    return _ts_generator(this, function(_state) {
+                        switch(_state.label){
+                            case 0:
+                                userInput = this.resolveUserInput(userPrompt);
+                                systemMessage = this.options.systemPrompt.generate();
+                                messages = [
+                                    {
+                                        content: systemMessage,
+                                        role: 'system'
+                                    },
+                                    {
+                                        content: userInput,
+                                        role: 'user'
+                                    }
+                                ];
+                                (_this_options_logger = this.options.logger) === null || _this_options_logger === void 0 ? void 0 : _this_options_logger.debug("[".concat(this.name, "] Invoking model..."), {
+                                    hasSchema: !!this.options.schema
+                                });
+                                if (this.options.verbose) {
+                                    ;
+                                    (_this_options_logger1 = this.options.logger) === null || _this_options_logger1 === void 0 ? void 0 : _this_options_logger1.info("[".concat(this.name, "] Sending messages to model..."), {
+                                        messages: messages
+                                    });
+                                }
+                                return [
+                                    4,
+                                    this.options.model.getModel().invoke(messages)
+                                ];
+                            case 1:
+                                response = _state.sent();
+                                content = response.content;
+                                if (typeof content !== 'string') {
+                                    throw new Error('Model returned a non-string content type.');
+                                }
+                                return [
+                                    2,
+                                    content
+                                ];
+                        }
+                    });
+                }).call(this);
+            }
+        },
+        {
+            key: "parseResponse",
+            value: function parseResponse(content, schema) {
+                try {
+                    new AIResponseParser(schema).parse(content);
+                } catch (error) {
+                    var _this_options_logger;
+                    (_this_options_logger = this.options.logger) === null || _this_options_logger === void 0 ? void 0 : _this_options_logger.error("[".concat(this.name, "] Failed to parse model response."), {
+                        error: _instanceof(error, Error) ? error.message : 'Unknown error',
+                        rawContent: content
+                    });
+                    throw new Error('Invalid response format from model.');
+                }
+            }
+        },
+        {
+            key: "resolveUserInput",
+            value: function resolveUserInput(userPrompt) {
+                if (userPrompt) {
+                    return userPrompt.generate();
+                }
+                return 'Proceed with your instructions.';
+            }
+        }
+    ]);
+    return BasicAgentAdapter;
+}();
+
+//# sourceMappingURL=basic-agent.adapter.js.map

package/dist/adapters/agents/basic-agent.adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/adapters/agents/basic-agent.adapter.ts"],"sourcesContent":["import { type LoggerPort } from '@jterrazz/logger';\nimport { type z } from 'zod/v4';\n\nimport { type AgentPort } from '../../ports/agent.port.js';\nimport type { ModelPort } from '../../ports/model.port.js';\nimport type { PromptPort } from '../../ports/prompt.port.js';\n\nimport { AIResponseParser } from '../utils/ai-response-parser.js';\n\nimport type { SystemPromptAdapter } from '../prompts/system-prompt.adapter.js';\n\nexport interface BasicAgentOptions<T = string> {\n    logger?: LoggerPort;\n    model: ModelPort;\n    schema?: z.ZodSchema<T>;\n    systemPrompt: SystemPromptAdapter;\n    verbose?: boolean;\n}\n\n/**\n * A basic agent for direct, one-shot interactions with a model.\n * It supports optional response parsing against a Zod schema but does not use tools.\n */\nexport class BasicAgentAdapter<T = string> implements AgentPort {\n    constructor(\n        public readonly name: string,\n        private readonly options: BasicAgentOptions<T>,\n    ) {}\n\n    async run(userPrompt?: PromptPort): Promise<null | string> {\n        this.options.logger?.debug(`[${this.name}] Starting query execution.`);\n\n        try {\n            const content = await this.invokeModel(userPrompt);\n\n            if (this.options.schema) {\n                this.parseResponse(content, this.options.schema);\n                this.options.logger?.info(`[${this.name}] Execution finished and response parsed.`);\n            } else {\n                this.options.logger?.info(`[${this.name}] Execution finished.`);\n            }\n\n            return content;\n        } catch (error) {\n            this.options.logger?.error(`[${this.name}] Execution failed.`, {\n                error: error instanceof Error ? error.message : 'Unknown error',\n            });\n            return null;\n        }\n    }\n\n    private async invokeModel(userPrompt?: PromptPort): Promise<string> {\n        const userInput = this.resolveUserInput(userPrompt);\n        const systemMessage = this.options.systemPrompt.generate();\n\n        const messages = [\n            { content: systemMessage, role: 'system' as const },\n            { content: userInput, role: 'user' as const },\n        ];\n\n        this.options.logger?.debug(`[${this.name}] Invoking model...`, {\n            hasSchema: !!this.options.schema,\n        });\n\n        if (this.options.verbose) {\n            this.options.logger?.info(`[${this.name}] Sending messages to model...`, {\n                messages,\n            });\n        }\n\n        const response = await this.options.model.getModel().invoke(messages);\n        const { content } = response;\n\n        if (typeof content !== 'string') {\n            throw new Error('Model returned a non-string content type.');\n        }\n\n        return content;\n    }\n\n    private parseResponse<TResponse>(content: string, schema: z.ZodSchema<TResponse>): void {\n        try {\n            new AIResponseParser(schema).parse(content);\n        } catch (error) {\n            this.options.logger?.error(`[${this.name}] Failed to parse model response.`, {\n                error: error instanceof Error ? error.message : 'Unknown error',\n                rawContent: content,\n            });\n            throw new Error('Invalid response format from model.');\n        }\n    }\n\n    private resolveUserInput(userPrompt?: PromptPort): string {\n        if (userPrompt) {\n            return userPrompt.generate();\n        }\n        return 'Proceed with your instructions.';\n    }\n}\n"],"names":["AIResponseParser","BasicAgentAdapter","name","options","run","userPrompt","content","error","logger","debug","invokeModel","schema","parseResponse","info","Error","message","userInput","systemMessage","messages","response","resolveUserInput","systemPrompt","generate","role","hasSchema","verbose","model","getModel","invoke","parse","rawContent"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOA,SAASA,gBAAgB,QAAQ,iCAAiC;AAYlE;;;CAGC,GACD,OAAO,IAAA,AAAMC,kCAAN;;aAAMA,kBAEL,AAAgBC,IAAY,EAC5B,AAAiBC,OAA6B;gCAHzCF;;;aAEWC,OAAAA;aACCC,UAAAA;;kBAHZF;;YAMHG,KAAAA;mBAAN,SAAMA,IAAIC,UAAuB;;wBAC7B,sBAGUC,SAIF,uBAEA,uBAICC,OACL;;;;iCAdJ,uBAAA,IAAI,CAACJ,OAAO,CAACK,MAAM,cAAnB,2CAAA,qBAAqBC,KAAK,CAAC,AAAC,IAAa,OAAV,IAAI,CAACP,IAAI,EAAC;;;;;;;;;gCAGrB;;oCAAM,IAAI,CAACQ,WAAW,CAACL;;;gCAAjCC,UAAU;gCAEhB,IAAI,IAAI,CAACH,OAAO,CAACQ,MAAM,EAAE;;oCACrB,IAAI,CAACC,aAAa,CAACN,SAAS,IAAI,CAACH,OAAO,CAACQ,MAAM;qCAC/C,wBAAA,IAAI,CAACR,OAAO,CAACK,MAAM,cAAnB,4CAAA,sBAAqBK,IAAI,CAAC,AAAC,IAAa,OAAV,IAAI,CAACX,IAAI,EAAC;gCAC5C,OAAO;;qCACH,wBAAA,IAAI,CAACC,OAAO,CAACK,MAAM,cAAnB,4CAAA,sBAAqBK,IAAI,CAAC,AAAC,IAAa,OAAV,IAAI,CAACX,IAAI,EAAC;gCAC5C;gCAEA;;oCAAOI;;;gCACFC;iCACL,wBAAA,IAAI,CAACJ,OAAO,CAACK,MAAM,cAAnB,4CAAA,sBAAqBD,KAAK,CAAC,AAAC,IAAa,OAAV,IAAI,CAACL,IAAI,EAAC,wBAAsB;oCAC3DK,OAAOA,AAAK,YAALA,OAAiBO,SAAQP,MAAMQ,OAAO,GAAG;gCACpD;gCACA;;oCAAO;;;;;;;;gBAEf;;;;YAEcL,KAAAA;mBAAd,SAAcA,YAAYL,UAAuB;;wBAS7C,sBARMW,WACAC,eAEAC,UAUF,uBAKEC,UACEb;;;;gCAnBFU,YAAY,IAAI,CAACI,gBAAgB,CAACf;gCAClCY,gBAAgB,IAAI,CAACd,OAAO,CAACkB,YAAY,CAACC,QAAQ;gCAElDJ;oCACF;wCAAEZ,SAASW;wCAAeM,MAAM;oCAAkB;oCAClD;wCAAEjB,SAASU;wCAAWO,MAAM;oCAAgB;;iCAGhD,uBAAA,IAAI,CAACpB,OAAO,CAACK,MAAM,cAAnB,2CAAA,qBAAqBC,KAAK,CAAC,AAAC,IAAa,OAAV,IAAI,CAACP,IAAI,EAAC,wBAAsB;oCAC3DsB,WAAW,CAAC,CAAC,IAAI,CAACrB,OAAO,CAACQ,MAAM;gCACpC;gCAEA,IAAI,IAAI,CAACR,OAAO,CAACsB,OAAO,EAAE;;qCACtB,wBAAA,IAAI,CAACtB,OAAO,CAACK,MAAM,cAAnB,4CAAA,sBAAqBK,IAAI,CAAC,AAAC,IAAa,OAAV,IAAI,CAACX,IAAI,EAAC,mCAAiC;wCACrEgB,UAAAA;oCACJ;gCACJ;gCAEiB;;oCAAM,IAAI,CAACf,OAAO,CAACuB,KAAK,CAACC,QAAQ,GAAGC,MAAM,CAACV;;;gCAAtDC,WAAW;gCACTb,UAAYa,SAAZb;gCAER,IAAI,OAAOA,YAAY,UAAU;oCAC7B,MAAM,IAAIQ,MAAM;gCACpB;gCAEA;;oCAAOR;;;;gBACX;;;;YAEQM,KAAAA;mBAAR,SAAQA,cAAyBN,OAAe,EAAEK,MAA8B;gBAC5E,IAAI;oBACA,IAAIX,iBAAiBW,QAAQkB,KAAK,CAACvB;gBACvC,EAAE,OAAOC,OAAO;wBACZ;qBAAA,uBAAA,IAAI,CAACJ,OAAO,CAACK,MAAM,cAAnB,2CAAA,qBAAqBD,KAAK,CAAC,AAAC,IAAa,OAAV,IAAI,CAACL,IAAI,EAAC,sCAAoC;wBACzEK,OAAOA,AAAK,YAALA,OAAiBO,SAAQP,MAAMQ,OAAO,GAAG;wBAChDe,YAAYxB;oBAChB;oBACA,MAAM,IAAIQ,MAAM;gBACpB;YACJ;;;YAEQM,KAAAA;mBAAR,SAAQA,iBAAiBf,UAAuB;gBAC5C,IAAIA,YAAY;oBACZ,OAAOA,WAAWiB,QAAQ;gBAC9B;gBACA,OAAO;YACX;;;WA1ESrB;IA2EZ"}

package/dist/adapters/agents/query-agent.adapter.d.ts

@@ -4,7 +4,7 @@ import { type AgentPort } from '../../ports/agent.port.js';
 import type { ModelPort } from '../../ports/model.port.js';
 import type { PromptPort } from '../../ports/prompt.port.js';
 import type { SystemPromptAdapter } from '../prompts/system-prompt.adapter.js';
-export interface QueryAgentOptions<T = string> {
+export interface BasicAgentOptions<T = string> {
     logger?: LoggerPort;
     model: ModelPort;
     schema?: z.ZodSchema<T>;
@@ -12,13 +12,13 @@ export interface QueryAgentOptions<T = string> {
     verbose?: boolean;
 }
 /**
- * A simple agent for direct, one-shot interactions with a model.
+ * A basic agent for direct, one-shot interactions with a model.
  * It supports optional response parsing against a Zod schema but does not use tools.
  */
-export declare class QueryAgentAdapter<T = string> implements AgentPort {
+export declare class BasicAgentAdapter<T = string> implements AgentPort {
     readonly name: string;
     private readonly options;
-    constructor(name: string, options: QueryAgentOptions<T>);
+    constructor(name: string, options: BasicAgentOptions<T>);
     run(userPrompt?: PromptPort): Promise<null | string>;
     private invokeModel;
     private parseResponse;

package/dist/adapters/agents/query-agent.adapter.js

@@ -159,18 +159,18 @@ function _ts_generator(thisArg, body) {
 }
 import { AIResponseParser } from '../utils/ai-response-parser.js';
 /**
- * A simple agent for direct, one-shot interactions with a model.
+ * A basic agent for direct, one-shot interactions with a model.
  * It supports optional response parsing against a Zod schema but does not use tools.
- */ export var QueryAgentAdapter = /*#__PURE__*/ function() {
+ */ export var BasicAgentAdapter = /*#__PURE__*/ function() {
     "use strict";
-    function QueryAgentAdapter(name, options) {
-        _class_call_check(this, QueryAgentAdapter);
+    function BasicAgentAdapter(name, options) {
+        _class_call_check(this, BasicAgentAdapter);
         _define_property(this, "name", void 0);
         _define_property(this, "options", void 0);
         this.name = name;
         this.options = options;
     }
-    _create_class(QueryAgentAdapter, [
+    _create_class(BasicAgentAdapter, [
         {
             key: "run",
             value: function run(userPrompt) {
@@ -297,7 +297,7 @@ import { AIResponseParser } from '../utils/ai-response-parser.js';
             }
         }
     ]);
-    return QueryAgentAdapter;
+    return BasicAgentAdapter;
 }();
 
 //# sourceMappingURL=query-agent.adapter.js.map

package/dist/adapters/agents/query-agent.adapter.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/adapters/agents/query-agent.adapter.ts"],"sourcesContent":["import { type LoggerPort } from '@jterrazz/logger';\nimport { type z } from 'zod/v4';\n\nimport { type AgentPort } from '../../ports/agent.port.js';\nimport type { ModelPort } from '../../ports/model.port.js';\nimport type { PromptPort } from '../../ports/prompt.port.js';\n\nimport { AIResponseParser } from '../utils/ai-response-parser.js';\n\nimport type { SystemPromptAdapter } from '../prompts/system-prompt.adapter.js';\n\nexport interface QueryAgentOptions<T = string> {\n    logger?: LoggerPort;\n    model: ModelPort;\n    schema?: z.ZodSchema<T>;\n    systemPrompt: SystemPromptAdapter;\n    verbose?: boolean;\n}\n\n/**\n * A simple agent for direct, one-shot interactions with a model.\n * It supports optional response parsing against a Zod schema but does not use tools.\n */\nexport class QueryAgentAdapter<T = string> implements AgentPort {\n    constructor(\n        public readonly name: string,\n        private readonly options: QueryAgentOptions<T>,\n    ) {}\n\n    async run(userPrompt?: PromptPort): Promise<null | string> {\n        this.options.logger?.debug(`[${this.name}] Starting query execution.`);\n\n        try {\n            const content = await this.invokeModel(userPrompt);\n\n            if (this.options.schema) {\n                this.parseResponse(content, this.options.schema);\n                this.options.logger?.info(`[${this.name}] Execution finished and response parsed.`);\n            } else {\n                this.options.logger?.info(`[${this.name}] Execution finished.`);\n            }\n\n            return content;\n        } catch (error) {\n            this.options.logger?.error(`[${this.name}] Execution failed.`, {\n                error: error instanceof Error ? error.message : 'Unknown error',\n            });\n            return null;\n        }\n    }\n\n    private async invokeModel(userPrompt?: PromptPort): Promise<string> {\n        const userInput = this.resolveUserInput(userPrompt);\n        const systemMessage = this.options.systemPrompt.generate();\n\n        const messages = [\n            { content: systemMessage, role: 'system' as const },\n            { content: userInput, role: 'user' as const },\n        ];\n\n        this.options.logger?.debug(`[${this.name}] Invoking model...`, {\n            hasSchema: !!this.options.schema,\n        });\n\n        if (this.options.verbose) {\n            this.options.logger?.info(`[${this.name}] Sending messages to model...`, {\n                messages,\n            });\n        }\n\n        const response = await this.options.model.getModel().invoke(messages);\n        const { content } = response;\n\n        if (typeof content !== 'string') {\n            throw new Error('Model returned a non-string content type.');\n        }\n\n        return content;\n    }\n\n    private parseResponse<TResponse>(content: string, schema: z.ZodSchema<TResponse>): void {\n        try {\n            new AIResponseParser(schema).parse(content);\n        } catch (error) {\n            this.options.logger?.error(`[${this.name}] Failed to parse model response.`, {\n                error: error instanceof Error ? error.message : 'Unknown error',\n                rawContent: content,\n            });\n            throw new Error('Invalid response format from model.');\n        }\n    }\n\n    private resolveUserInput(userPrompt?: PromptPort): string {\n        if (userPrompt) {\n            return userPrompt.generate();\n        }\n        return 'Proceed with your instructions.';\n    }\n}\n"],"names":["AIResponseParser","QueryAgentAdapter","name","options","run","userPrompt","content","error","logger","debug","invokeModel","schema","parseResponse","info","Error","message","userInput","systemMessage","messages","response","resolveUserInput","systemPrompt","generate","role","hasSchema","verbose","model","getModel","invoke","parse","rawContent"],"mappings":"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"}
+{"version":3,"sources":["../../../src/adapters/agents/query-agent.adapter.ts"],"sourcesContent":["import { type LoggerPort } from '@jterrazz/logger';\nimport { type z } from 'zod/v4';\n\nimport { type AgentPort } from '../../ports/agent.port.js';\nimport type { ModelPort } from '../../ports/model.port.js';\nimport type { PromptPort } from '../../ports/prompt.port.js';\n\nimport { AIResponseParser } from '../utils/ai-response-parser.js';\n\nimport type { SystemPromptAdapter } from '../prompts/system-prompt.adapter.js';\n\nexport interface BasicAgentOptions<T = string> {\n    logger?: LoggerPort;\n    model: ModelPort;\n    schema?: z.ZodSchema<T>;\n    systemPrompt: SystemPromptAdapter;\n    verbose?: boolean;\n}\n\n/**\n * A basic agent for direct, one-shot interactions with a model.\n * It supports optional response parsing against a Zod schema but does not use tools.\n */\nexport class BasicAgentAdapter<T = string> implements AgentPort {\n    constructor(\n        public readonly name: string,\n        private readonly options: BasicAgentOptions<T>,\n    ) {}\n\n    async run(userPrompt?: PromptPort): Promise<null | string> {\n        this.options.logger?.debug(`[${this.name}] Starting query execution.`);\n\n        try {\n            const content = await this.invokeModel(userPrompt);\n\n            if (this.options.schema) {\n                this.parseResponse(content, this.options.schema);\n                this.options.logger?.info(`[${this.name}] Execution finished and response parsed.`);\n            } else {\n                this.options.logger?.info(`[${this.name}] Execution finished.`);\n            }\n\n            return content;\n        } catch (error) {\n            this.options.logger?.error(`[${this.name}] Execution failed.`, {\n                error: error instanceof Error ? error.message : 'Unknown error',\n            });\n            return null;\n        }\n    }\n\n    private async invokeModel(userPrompt?: PromptPort): Promise<string> {\n        const userInput = this.resolveUserInput(userPrompt);\n        const systemMessage = this.options.systemPrompt.generate();\n\n        const messages = [\n            { content: systemMessage, role: 'system' as const },\n            { content: userInput, role: 'user' as const },\n        ];\n\n        this.options.logger?.debug(`[${this.name}] Invoking model...`, {\n            hasSchema: !!this.options.schema,\n        });\n\n        if (this.options.verbose) {\n            this.options.logger?.info(`[${this.name}] Sending messages to model...`, {\n                messages,\n            });\n        }\n\n        const response = await this.options.model.getModel().invoke(messages);\n        const { content } = response;\n\n        if (typeof content !== 'string') {\n            throw new Error('Model returned a non-string content type.');\n        }\n\n        return content;\n    }\n\n    private parseResponse<TResponse>(content: string, schema: z.ZodSchema<TResponse>): void {\n        try {\n            new AIResponseParser(schema).parse(content);\n        } catch (error) {\n            this.options.logger?.error(`[${this.name}] Failed to parse model response.`, {\n                error: error instanceof Error ? error.message : 'Unknown error',\n                rawContent: content,\n            });\n            throw new Error('Invalid response format from model.');\n        }\n    }\n\n    private resolveUserInput(userPrompt?: PromptPort): string {\n        if (userPrompt) {\n            return userPrompt.generate();\n        }\n        return 'Proceed with your instructions.';\n    }\n}\n"],"names":["AIResponseParser","BasicAgentAdapter","name","options","run","userPrompt","content","error","logger","debug","invokeModel","schema","parseResponse","info","Error","message","userInput","systemMessage","messages","response","resolveUserInput","systemPrompt","generate","role","hasSchema","verbose","model","getModel","invoke","parse","rawContent"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOA,SAASA,gBAAgB,QAAQ,iCAAiC;AAYlE;;;CAGC,GACD,OAAO,IAAA,AAAMC,kCAAN;;aAAMA,kBAEL,AAAgBC,IAAY,EAC5B,AAAiBC,OAA6B;gCAHzCF;;;aAEWC,OAAAA;aACCC,UAAAA;;kBAHZF;;YAMHG,KAAAA;mBAAN,SAAMA,IAAIC,UAAuB;;wBAC7B,sBAGUC,SAIF,uBAEA,uBAICC,OACL;;;;iCAdJ,uBAAA,IAAI,CAACJ,OAAO,CAACK,MAAM,cAAnB,2CAAA,qBAAqBC,KAAK,CAAC,AAAC,IAAa,OAAV,IAAI,CAACP,IAAI,EAAC;;;;;;;;;gCAGrB;;oCAAM,IAAI,CAACQ,WAAW,CAACL;;;gCAAjCC,UAAU;gCAEhB,IAAI,IAAI,CAACH,OAAO,CAACQ,MAAM,EAAE;;oCACrB,IAAI,CAACC,aAAa,CAACN,SAAS,IAAI,CAACH,OAAO,CAACQ,MAAM;qCAC/C,wBAAA,IAAI,CAACR,OAAO,CAACK,MAAM,cAAnB,4CAAA,sBAAqBK,IAAI,CAAC,AAAC,IAAa,OAAV,IAAI,CAACX,IAAI,EAAC;gCAC5C,OAAO;;qCACH,wBAAA,IAAI,CAACC,OAAO,CAACK,MAAM,cAAnB,4CAAA,sBAAqBK,IAAI,CAAC,AAAC,IAAa,OAAV,IAAI,CAACX,IAAI,EAAC;gCAC5C;gCAEA;;oCAAOI;;;gCACFC;iCACL,wBAAA,IAAI,CAACJ,OAAO,CAACK,MAAM,cAAnB,4CAAA,sBAAqBD,KAAK,CAAC,AAAC,IAAa,OAAV,IAAI,CAACL,IAAI,EAAC,wBAAsB;oCAC3DK,OAAOA,AAAK,YAALA,OAAiBO,SAAQP,MAAMQ,OAAO,GAAG;gCACpD;gCACA;;oCAAO;;;;;;;;gBAEf;;;;YAEcL,KAAAA;mBAAd,SAAcA,YAAYL,UAAuB;;wBAS7C,sBARMW,WACAC,eAEAC,UAUF,uBAKEC,UACEb;;;;gCAnBFU,YAAY,IAAI,CAACI,gBAAgB,CAACf;gCAClCY,gBAAgB,IAAI,CAACd,OAAO,CAACkB,YAAY,CAACC,QAAQ;gCAElDJ;oCACF;wCAAEZ,SAASW;wCAAeM,MAAM;oCAAkB;oCAClD;wCAAEjB,SAASU;wCAAWO,MAAM;oCAAgB;;iCAGhD,uBAAA,IAAI,CAACpB,OAAO,CAACK,MAAM,cAAnB,2CAAA,qBAAqBC,KAAK,CAAC,AAAC,IAAa,OAAV,IAAI,CAACP,IAAI,EAAC,wBAAsB;oCAC3DsB,WAAW,CAAC,CAAC,IAAI,CAACrB,OAAO,CAACQ,MAAM;gCACpC;gCAEA,IAAI,IAAI,CAACR,OAAO,CAACsB,OAAO,EAAE;;qCACtB,wBAAA,IAAI,CAACtB,OAAO,CAACK,MAAM,cAAnB,4CAAA,sBAAqBK,IAAI,CAAC,AAAC,IAAa,OAAV,IAAI,CAACX,IAAI,EAAC,mCAAiC;wCACrEgB,UAAAA;oCACJ;gCACJ;gCAEiB;;oCAAM,IAAI,CAACf,OAAO,CAACuB,KAAK,CAACC,QAAQ,GAAGC,MAAM,CAACV;;;gCAAtDC,WAAW;gCACTb,UAAYa,SAAZb;gCAER,IAAI,OAAOA,YAAY,UAAU;oCAC7B,MAAM,IAAIQ,MAAM;gCACpB;gCAEA;;oCAAOR;;;;gBACX;;;;YAEQM,KAAAA;mBAAR,SAAQA,cAAyBN,OAAe,EAAEK,MAA8B;gBAC5E,IAAI;oBACA,IAAIX,iBAAiBW,QAAQkB,KAAK,CAACvB;gBACvC,EAAE,OAAOC,OAAO;wBACZ;qBAAA,uBAAA,IAAI,CAACJ,OAAO,CAACK,MAAM,cAAnB,2CAAA,qBAAqBD,KAAK,CAAC,AAAC,IAAa,OAAV,IAAI,CAACL,IAAI,EAAC,sCAAoC;wBACzEK,OAAOA,AAAK,YAALA,OAAiBO,SAAQP,MAAMQ,OAAO,GAAG;wBAChDe,YAAYxB;oBAChB;oBACA,MAAM,IAAIQ,MAAM;gBACpB;YACJ;;;YAEQM,KAAAA;mBAAR,SAAQA,iBAAiBf,UAAuB;gBAC5C,IAAIA,YAAY;oBACZ,OAAOA,WAAWiB,QAAQ;gBAC9B;gBACA,OAAO;YACX;;;WA1ESrB;IA2EZ"}

package/dist/index.cjs

@@ -629,17 +629,17 @@ function _ts_generator$2(thisArg, body) {
 }
 var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<OUTPUT_FORMAT>\nCRITICAL: The format instructions in this section are the ONLY valid way to structure your response. Your entire response MUST be a single JSON markdown code block. Any formatting guidelines within the <OBJECTIVE> section apply ONLY to the content inside the "RESPOND:" part of your final "action_input".\n\nREQUIRED: You have two ways to respond:\n\n1.  **Call a tool** to gather information. For this, you MUST output a JSON blob with the tool\'s name and its input.\n    *Valid tool names are: {tool_names}*\n    ```json\n    {{\n      "action": "tool_name_to_use",\n      "action_input": "the input for the tool, or an empty object {{}} if no input is needed"\n    }}\n    ```\n\n2.  **Provide the Final Answer** once you have enough information. For this, you MUST output a JSON blob with the "Final Answer" action.\n    The "action_input" for a "Final Answer" MUST be a string that begins with either "RESPOND: " for a message or "SILENT: " for no message. This prefix is a literal part of the output string and MUST NOT be omitted.\n    - To send a message:\n      ```json\n      {{\n        "action": "Final Answer",\n        "action_input": "RESPOND: <your response message>"\n      }}\n      ```\n    - To stay silent:\n      ```json\n      {{\n        "action": "Final Answer",\n        "action_input": "SILENT: <your reason for staying silent>"\n      }}\n      ```\n\n    YOU MUST ALWAYS INCLUDE "RESPOND:" OR "SILENT:" IN YOUR FINAL ANSWER\'S "action_input". FAILURE TO DO SO WILL CAUSE AN ERROR.\n</OUTPUT_FORMAT>\n\n<EXECUTION_CONTEXT>\nThis is internal data for your reference.\n\n<TOOLS>\n{tools}\n</TOOLS>\n\n<WORKING_MEMORY>\nThis is your internal thought process and previous tool usage.\n{agent_scratchpad}\n</WORKING_MEMORY>\n</EXECUTION_CONTEXT>\n';
 /**
- * An advanced agent that uses tools and a structured prompt to engage in conversational chat.
+ * An autonomous agent that uses tools and a structured prompt to accomplish tasks.
  * It can decide whether to respond or remain silent and supports schema-validated responses.
- */ var ChatAgentAdapter = /*#__PURE__*/ function() {
-    function ChatAgentAdapter(name, options) {
-        _class_call_check$5(this, ChatAgentAdapter);
+ */ var AutonomousAgentAdapter = /*#__PURE__*/ function() {
+    function AutonomousAgentAdapter(name, options) {
+        _class_call_check$5(this, AutonomousAgentAdapter);
         _define_property$5(this, "name", void 0);
         _define_property$5(this, "options", void 0);
         this.name = name;
         this.options = options;
     }
-    _create_class$5(ChatAgentAdapter, [
+    _create_class$5(AutonomousAgentAdapter, [
         {
             key: "run",
             value: function run(userPrompt) {
@@ -818,7 +818,7 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
             }
         }
     ]);
-    return ChatAgentAdapter;
+    return AutonomousAgentAdapter;
 }();
 
 function asyncGeneratorStep$1(gen, resolve, reject, _next, _throw, key, arg) {
@@ -980,17 +980,17 @@ function _ts_generator$1(thisArg, body) {
     }
 }
 /**
- * A simple agent for direct, one-shot interactions with a model.
+ * A basic agent for direct, one-shot interactions with a model.
  * It supports optional response parsing against a Zod schema but does not use tools.
- */ var QueryAgentAdapter = /*#__PURE__*/ function() {
-    function QueryAgentAdapter(name, options) {
-        _class_call_check$4(this, QueryAgentAdapter);
+ */ var BasicAgentAdapter = /*#__PURE__*/ function() {
+    function BasicAgentAdapter(name, options) {
+        _class_call_check$4(this, BasicAgentAdapter);
         _define_property$4(this, "name", void 0);
         _define_property$4(this, "options", void 0);
         this.name = name;
         this.options = options;
     }
-    _create_class$4(QueryAgentAdapter, [
+    _create_class$4(BasicAgentAdapter, [
         {
             key: "run",
             value: function run(userPrompt) {
@@ -1114,7 +1114,7 @@ function _ts_generator$1(thisArg, body) {
             }
         }
     ]);
-    return QueryAgentAdapter;
+    return BasicAgentAdapter;
 }();
 
 function _class_call_check$3(instance, Constructor) {
@@ -1720,10 +1720,10 @@ function _ts_generator(thisArg, body) {
 }();
 
 exports.AIResponseParser = AIResponseParser;
-exports.ChatAgentAdapter = ChatAgentAdapter;
+exports.AutonomousAgentAdapter = AutonomousAgentAdapter;
+exports.BasicAgentAdapter = BasicAgentAdapter;
 exports.OpenRouterAdapter = OpenRouterModelAdapter;
 exports.PROMPT_LIBRARY = PROMPT_LIBRARY;
-exports.QueryAgentAdapter = QueryAgentAdapter;
 exports.SafeToolAdapter = SafeToolAdapter;
 exports.SystemPromptAdapter = SystemPromptAdapter;
 exports.UserPromptAdapter = UserPromptAdapter;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { ChatAgentAdapter } from './adapters/agents/chat-agent.adapter.js';
-export { QueryAgentAdapter } from './adapters/agents/query-agent.adapter.js';
+export { AutonomousAgentAdapter } from './adapters/agents/autonomous-agent.adapter.js';
+export { BasicAgentAdapter } from './adapters/agents/basic-agent.adapter.js';
 export { OpenRouterModelAdapter as OpenRouterAdapter } from './adapters/models/openrouter-model.adapter.js';
 export { PROMPT_LIBRARY } from './adapters/prompts/library/index.js';
 export { SystemPromptAdapter } from './adapters/prompts/system-prompt.adapter.js';

package/dist/index.js

@@ -1,5 +1,5 @@
-export { ChatAgentAdapter } from './adapters/agents/chat-agent.adapter.js';
-export { QueryAgentAdapter } from './adapters/agents/query-agent.adapter.js';
+export { AutonomousAgentAdapter } from './adapters/agents/autonomous-agent.adapter.js';
+export { BasicAgentAdapter } from './adapters/agents/basic-agent.adapter.js';
 export { OpenRouterModelAdapter as OpenRouterAdapter } from './adapters/models/openrouter-model.adapter.js';
 export { PROMPT_LIBRARY } from './adapters/prompts/library/index.js';
 export { SystemPromptAdapter } from './adapters/prompts/system-prompt.adapter.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export { ChatAgentAdapter } from './adapters/agents/chat-agent.adapter.js';\nexport { QueryAgentAdapter } from './adapters/agents/query-agent.adapter.js';\nexport { OpenRouterModelAdapter as OpenRouterAdapter } from './adapters/models/openrouter-model.adapter.js';\nexport { PROMPT_LIBRARY } from './adapters/prompts/library/index.js';\nexport { SystemPromptAdapter } from './adapters/prompts/system-prompt.adapter.js';\nexport { UserPromptAdapter } from './adapters/prompts/user-prompt.adapter.js';\nexport { SafeToolAdapter } from './adapters/tools/safe-tool.adapter.js';\nexport { AIResponseParser } from './adapters/utils/ai-response-parser.js';\n\nexport * from './ports/agent.port.js';\nexport * from './ports/model.port.js';\nexport * from './ports/prompt.port.js';\nexport * from './ports/tool.port.js';\n"],"names":["ChatAgentAdapter","QueryAgentAdapter","OpenRouterModelAdapter","OpenRouterAdapter","PROMPT_LIBRARY","SystemPromptAdapter","UserPromptAdapter","SafeToolAdapter","AIResponseParser"],"mappings":"AAAA,SAASA,gBAAgB,QAAQ,0CAA0C;AAC3E,SAASC,iBAAiB,QAAQ,2CAA2C;AAC7E,SAASC,0BAA0BC,iBAAiB,QAAQ,gDAAgD;AAC5G,SAASC,cAAc,QAAQ,sCAAsC;AACrE,SAASC,mBAAmB,QAAQ,8CAA8C;AAClF,SAASC,iBAAiB,QAAQ,4CAA4C;AAC9E,SAASC,eAAe,QAAQ,wCAAwC;AACxE,SAASC,gBAAgB,QAAQ,yCAAyC;AAE1E,cAAc,wBAAwB;AACtC,cAAc,wBAAwB;AACtC,cAAc,yBAAyB;AACvC,cAAc,uBAAuB"}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export { AutonomousAgentAdapter } from './adapters/agents/autonomous-agent.adapter.js';\nexport { BasicAgentAdapter } from './adapters/agents/basic-agent.adapter.js';\nexport { OpenRouterModelAdapter as OpenRouterAdapter } from './adapters/models/openrouter-model.adapter.js';\nexport { PROMPT_LIBRARY } from './adapters/prompts/library/index.js';\nexport { SystemPromptAdapter } from './adapters/prompts/system-prompt.adapter.js';\nexport { UserPromptAdapter } from './adapters/prompts/user-prompt.adapter.js';\nexport { SafeToolAdapter } from './adapters/tools/safe-tool.adapter.js';\nexport { AIResponseParser } from './adapters/utils/ai-response-parser.js';\n\nexport * from './ports/agent.port.js';\nexport * from './ports/model.port.js';\nexport * from './ports/prompt.port.js';\nexport * from './ports/tool.port.js';\n"],"names":["AutonomousAgentAdapter","BasicAgentAdapter","OpenRouterModelAdapter","OpenRouterAdapter","PROMPT_LIBRARY","SystemPromptAdapter","UserPromptAdapter","SafeToolAdapter","AIResponseParser"],"mappings":"AAAA,SAASA,sBAAsB,QAAQ,gDAAgD;AACvF,SAASC,iBAAiB,QAAQ,2CAA2C;AAC7E,SAASC,0BAA0BC,iBAAiB,QAAQ,gDAAgD;AAC5G,SAASC,cAAc,QAAQ,sCAAsC;AACrE,SAASC,mBAAmB,QAAQ,8CAA8C;AAClF,SAASC,iBAAiB,QAAQ,4CAA4C;AAC9E,SAASC,eAAe,QAAQ,wCAAwC;AACxE,SAASC,gBAAgB,QAAQ,yCAAyC;AAE1E,cAAc,wBAAwB;AACtC,cAAc,wBAAwB;AACtC,cAAc,yBAAyB;AACvC,cAAc,uBAAuB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jterrazz/intelligence",
   "author": "Jean-Baptiste Terrazzoni <contact@jterrazz.com>",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "exports": {
     ".": {
       "require": "./dist/index.cjs",

package/dist/adapters/agents/chat-agent.adapter.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../src/adapters/agents/chat-agent.adapter.ts"],"sourcesContent":["import { type LoggerPort } from '@jterrazz/logger';\nimport { ChatPromptTemplate } from '@langchain/core/prompts';\nimport { AgentExecutor, createStructuredChatAgent } from 'langchain/agents';\nimport { type z } from 'zod/v4';\n\nimport { type AgentPort } from '../../ports/agent.port.js';\nimport type { ModelPort } from '../../ports/model.port.js';\nimport type { PromptPort } from '../../ports/prompt.port.js';\nimport type { ToolPort } from '../../ports/tool.port.js';\n\nimport { AIResponseParser } from '../utils/ai-response-parser.js';\n\nimport type { SystemPromptAdapter } from '../prompts/system-prompt.adapter.js';\n\nexport interface ChatAgentOptions<T = unknown> {\n    logger?: LoggerPort;\n    model: ModelPort;\n    schema?: z.ZodSchema<T>;\n    systemPrompt: SystemPromptAdapter;\n    tools: ToolPort[];\n    verbose?: boolean;\n}\n\nconst SYSTEM_PROMPT_TEMPLATE = `\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<OUTPUT_FORMAT>\nCRITICAL: The format instructions in this section are the ONLY valid way to structure your response. Your entire response MUST be a single JSON markdown code block. Any formatting guidelines within the <OBJECTIVE> section apply ONLY to the content inside the \"RESPOND:\" part of your final \"action_input\".\n\nREQUIRED: You have two ways to respond:\n\n1.  **Call a tool** to gather information. For this, you MUST output a JSON blob with the tool's name and its input.\n    *Valid tool names are: {tool_names}*\n    \\`\\`\\`json\n    {{\n      \"action\": \"tool_name_to_use\",\n      \"action_input\": \"the input for the tool, or an empty object {{}} if no input is needed\"\n    }}\n    \\`\\`\\`\n\n2.  **Provide the Final Answer** once you have enough information. For this, you MUST output a JSON blob with the \"Final Answer\" action.\n    The \"action_input\" for a \"Final Answer\" MUST be a string that begins with either \"RESPOND: \" for a message or \"SILENT: \" for no message. This prefix is a literal part of the output string and MUST NOT be omitted.\n    - To send a message:\n      \\`\\`\\`json\n      {{\n        \"action\": \"Final Answer\",\n        \"action_input\": \"RESPOND: <your response message>\"\n      }}\n      \\`\\`\\`\n    - To stay silent:\n      \\`\\`\\`json\n      {{\n        \"action\": \"Final Answer\",\n        \"action_input\": \"SILENT: <your reason for staying silent>\"\n      }}\n      \\`\\`\\`\n\n    YOU MUST ALWAYS INCLUDE \"RESPOND:\" OR \"SILENT:\" IN YOUR FINAL ANSWER'S \"action_input\". FAILURE TO DO SO WILL CAUSE AN ERROR.\n</OUTPUT_FORMAT>\n\n<EXECUTION_CONTEXT>\nThis is internal data for your reference.\n\n<TOOLS>\n{tools}\n</TOOLS>\n\n<WORKING_MEMORY>\nThis is your internal thought process and previous tool usage.\n{agent_scratchpad}\n</WORKING_MEMORY>\n</EXECUTION_CONTEXT>\n`;\n\n/**\n * An advanced agent that uses tools and a structured prompt to engage in conversational chat.\n * It can decide whether to respond or remain silent and supports schema-validated responses.\n */\nexport class ChatAgentAdapter<T = unknown> implements AgentPort {\n    constructor(\n        public readonly name: string,\n        private readonly options: ChatAgentOptions<T>,\n    ) {}\n\n    async run(userPrompt?: PromptPort): Promise<null | string> {\n        this.options.logger?.debug(`[${this.name}] Starting chat execution.`);\n\n        try {\n            const executor = await this.createExecutor();\n            const userInput = this.resolveUserInput(userPrompt);\n\n            const result = await executor.invoke({ input: userInput });\n\n            this.options.logger?.debug(`[${this.name}] Agent execution completed.`, {\n                hasOutput: 'output' in result,\n            });\n\n            if (!result || typeof result.output !== 'string') {\n                throw new Error('Agent returned an invalid result structure.');\n            }\n\n            const agentResponse = this.parseAgentOutput(result.output);\n\n            if (!agentResponse) {\n                return null;\n            }\n\n            if (!agentResponse.shouldRespond) {\n                this.options.logger?.info(`[${this.name}] Agent chose to remain silent.`, {\n                    reason: agentResponse.reason,\n                });\n                return null;\n            }\n\n            const message = agentResponse.message ?? '';\n\n            if (this.options.schema) {\n                this.validateResponseContent(message, this.options.schema);\n                this.options.logger?.info(\n                    `[${this.name}] Execution finished; response content validated.`,\n                );\n            } else {\n                this.options.logger?.info(`[${this.name}] Execution finished.`);\n            }\n\n            return message;\n        } catch (error) {\n            this.options.logger?.error(`[${this.name}] Chat execution failed.`, {\n                error: error instanceof Error ? error.message : 'Unknown error',\n            });\n            return null;\n        }\n    }\n\n    private async createExecutor(): Promise<AgentExecutor> {\n        const model = this.options.model.getModel();\n        const tools = this.options.tools.map((tool) => tool.getDynamicTool());\n\n        const prompt = ChatPromptTemplate.fromMessages([\n            [\n                'system',\n                SYSTEM_PROMPT_TEMPLATE.replace(\n                    '{mission_prompt}',\n                    this.options.systemPrompt.generate(),\n                ),\n            ],\n            ['human', '{input}'],\n        ]);\n\n        const agent = await createStructuredChatAgent({\n            llm: model,\n            prompt,\n            tools,\n        });\n\n        return AgentExecutor.fromAgentAndTools({\n            agent,\n            tools,\n            verbose: this.options.verbose,\n        });\n    }\n\n    private parseAgentOutput(output: string): null | {\n        message?: string;\n        reason?: string;\n        shouldRespond: boolean;\n    } {\n        const text = output.trim();\n\n        const respondMatch = text.match(/^RESPOND:\\s*([\\s\\S]+)$/i);\n        if (respondMatch) {\n            return { message: respondMatch[1].trim(), shouldRespond: true };\n        }\n\n        const silentMatch = text.match(/^SILENT:\\s*([\\s\\S]+)$/i);\n        if (silentMatch) {\n            return { reason: silentMatch[1].trim(), shouldRespond: false };\n        }\n\n        this.options.logger?.error(\n            `[${this.name}] Agent output was missing 'RESPOND:' or 'SILENT:' prefix.`,\n            { rawOutput: output },\n        );\n\n        return null;\n    }\n\n    private resolveUserInput(userPrompt?: PromptPort): string {\n        if (userPrompt) {\n            return userPrompt.generate();\n        }\n        return 'Proceed with your instructions.';\n    }\n\n    private validateResponseContent<TResponse>(\n        content: string,\n        schema: z.ZodSchema<TResponse>,\n    ): void {\n        try {\n            new AIResponseParser(schema).parse(content);\n        } catch (error) {\n            this.options.logger?.error(\n                `[${this.name}] Failed to validate response content against schema.`,\n                {\n                    error: error instanceof Error ? error.message : 'Unknown error',\n                    rawContent: content,\n                },\n            );\n            throw new Error('Invalid response content from model.');\n        }\n    }\n}\n"],"names":["ChatPromptTemplate","AgentExecutor","createStructuredChatAgent","AIResponseParser","SYSTEM_PROMPT_TEMPLATE","ChatAgentAdapter","name","options","run","userPrompt","executor","userInput","result","agentResponse","message","error","logger","debug","createExecutor","resolveUserInput","invoke","input","hasOutput","output","Error","parseAgentOutput","shouldRespond","info","reason","schema","validateResponseContent","model","tools","prompt","agent","getModel","map","tool","getDynamicTool","fromMessages","replace","systemPrompt","generate","llm","fromAgentAndTools","verbose","text","trim","respondMatch","match","silentMatch","rawOutput","content","parse","rawContent"],"mappings":"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"}