@jterrazz/intelligence 1.2.0 → 1.4.0

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 { 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<TOutput = string> {\n    logger?: LoggerPort;\n    model: ModelPort;\n    schema?: z.ZodSchema<TOutput>;\n    systemPrompt: SystemPromptAdapter;\n    tools: ToolPort[];\n    verbose?: boolean;\n}\n\nconst SYSTEM_PROMPT_TEMPLATE = `\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<GLOBAL_WRAPPER_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\n{schema_format}\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 * @template TOutput - The TypeScript type of the output\n */\nexport class AutonomousAgentAdapter<TOutput = string> implements AgentPort<PromptPort, TOutput> {\n    constructor(\n        public readonly name: string,\n        private readonly options: AutonomousAgentOptions<TOutput>,\n    ) {}\n\n    async run(input?: PromptPort): Promise<null | TOutput> {\n        this.options.logger?.debug(`[${this.name}] Starting chat execution.`);\n\n        try {\n            const executor = await this.createExecutor();\n            const userInput = this.resolveUserInput(input);\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                const validatedResponse = this.validateResponseContent(\n                    message,\n                    this.options.schema,\n                );\n\n                this.options.logger?.info(\n                    `[${this.name}] Execution finished; response content validated.`,\n                );\n                return validatedResponse;\n            } else {\n                this.options.logger?.info(`[${this.name}] Execution finished.`);\n                // When no schema is provided, we assume TOutput is string (default), so message is the result\n                return message as TOutput;\n            }\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        // Add schema format instructions if schema is provided\n        let schemaFormatInstructions = '';\n        if (this.options.schema) {\n            const jsonSchema = z.toJSONSchema(this.options.schema);\n            console.log(jsonSchema.type);\n            const isPrimitiveType = ['boolean', 'integer', 'number', 'string'].includes(\n                jsonSchema.type as string,\n            );\n\n            if (isPrimitiveType) {\n                schemaFormatInstructions = `\n\nSCHEMA VALIDATION: When providing a \"RESPOND:\" answer, the content after \"RESPOND: \" must be a ${jsonSchema.type} value that matches this schema:\n\n\\`\\`\\`json\n${JSON.stringify(jsonSchema, null, 2)}\n\\`\\`\\`\n\nExample format:\n\\`\\`\\`json\n{{\n  \"action\": \"Final Answer\",\n  \"action_input\": \"RESPOND: your ${jsonSchema.type} value here\"\n}}\n\\`\\`\\`\n\nDo not wrap the ${jsonSchema.type} value in JSON - just provide the raw value after \"RESPOND: \".`;\n            } else {\n                schemaFormatInstructions = `\n\nSCHEMA VALIDATION: When providing a \"RESPOND:\" answer, the content after \"RESPOND: \" must be valid JSON that matches this exact schema:\n\n\\`\\`\\`json\n${JSON.stringify(jsonSchema, null, 2).replace(/{/g, '{{').replace(/}/g, '}}')}\n\\`\\`\\`\n\nExample format:\n\\`\\`\\`json\n{{\n  \"action\": \"Final Answer\",\n  \"action_input\": \"RESPOND: {{\\\\\"field1\\\\\": \\\\\"value1\\\\\", \\\\\"field2\\\\\": \\\\\"value2\\\\\"}}\"\n}}\n\\`\\`\\`\n`;\n            }\n        }\n\n        const prompt = ChatPromptTemplate.fromMessages([\n            [\n                'system',\n                SYSTEM_PROMPT_TEMPLATE.replace(\n                    '{mission_prompt}',\n                    this.options.systemPrompt.generate(),\n                ).replace('{schema_format}', schemaFormatInstructions),\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(input?: PromptPort): string {\n        if (input) {\n            return input.generate();\n        }\n        return 'Proceed with your instructions.';\n    }\n\n    private validateResponseContent<TResponse>(\n        content: string,\n        schema: z.ZodSchema<TResponse>,\n    ): TResponse {\n        try {\n            return 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","z","AIResponseParser","SYSTEM_PROMPT_TEMPLATE","AutonomousAgentAdapter","name","options","run","input","executor","userInput","result","agentResponse","message","validatedResponse","error","logger","debug","createExecutor","resolveUserInput","invoke","hasOutput","output","Error","parseAgentOutput","shouldRespond","info","reason","schema","validateResponseContent","model","tools","schemaFormatInstructions","jsonSchema","isPrimitiveType","prompt","agent","getModel","map","tool","getDynamicTool","toJSONSchema","console","log","type","includes","JSON","stringify","replace","fromMessages","systemPrompt","generate","llm","fromAgentAndTools","verbose","text","trim","respondMatch","match","silentMatch","rawOutput","content","parse","rawContent"],"mappings":"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"}

package/dist/adapters/agents/{query-agent.adapter.d.ts → basic-agent.adapter.d.ts}

@@ -1,25 +1,26 @@
 import { type LoggerPort } from '@jterrazz/logger';
-import { type z } from 'zod/v4';
+import { 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 QueryAgentOptions<T = string> {
+export interface BasicAgentOptions<TOutput = string> {
     logger?: LoggerPort;
     model: ModelPort;
-    schema?: z.ZodSchema<T>;
+    schema?: z.ZodSchema<TOutput>;
     systemPrompt: SystemPromptAdapter;
     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.
+ * @template TOutput - The TypeScript type of the output
  */
-export declare class QueryAgentAdapter<T = string> implements AgentPort {
+export declare class BasicAgentAdapter<TOutput = string> implements AgentPort<PromptPort, TOutput> {
     readonly name: string;
     private readonly options;
-    constructor(name: string, options: QueryAgentOptions<T>);
-    run(userPrompt?: PromptPort): Promise<null | string>;
+    constructor(name: string, options: BasicAgentOptions<TOutput>);
+    run(input?: PromptPort): Promise<null | TOutput>;
     private invokeModel;
     private parseResponse;
     private resolveUserInput;

package/dist/adapters/agents/{query-agent.adapter.js → basic-agent.adapter.js}

@@ -157,25 +157,27 @@ function _ts_generator(thisArg, body) {
         };
     }
 }
+import { z } from 'zod/v4';
 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() {
+ * @template TOutput - The TypeScript type of the output
+ */ 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) {
+            value: function run(input) {
                 return _async_to_generator(function() {
-                    var _this_options_logger, content, _this_options_logger1, _this_options_logger2, error, _this_options_logger3;
+                    var _this_options_logger, content, _this_options_logger1, parsedResponse, _this_options_logger2, error, _this_options_logger3;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -190,21 +192,30 @@ import { AIResponseParser } from '../utils/ai-response-parser.js';
                                 ]);
                                 return [
                                     4,
-                                    this.invokeModel(userPrompt)
+                                    this.invokeModel(input)
                                 ];
                             case 2:
                                 content = _state.sent();
                                 if (this.options.schema) {
                                     ;
-                                    this.parseResponse(content, this.options.schema);
+                                    parsedResponse = 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."));
+                                    return [
+                                        2,
+                                        parsedResponse
+                                    ];
                                 } else {
                                     ;
                                     (_this_options_logger2 = this.options.logger) === null || _this_options_logger2 === void 0 ? void 0 : _this_options_logger2.info("[".concat(this.name, "] Execution finished."));
+                                    // When no schema is provided, we assume TOutput is string (default), so content is the result
+                                    return [
+                                        2,
+                                        content
+                                    ];
                                 }
                                 return [
-                                    2,
-                                    content
+                                    3,
+                                    4
                                 ];
                             case 3:
                                 error = _state.sent();
@@ -226,14 +237,29 @@ import { AIResponseParser } from '../utils/ai-response-parser.js';
         },
         {
             key: "invokeModel",
-            value: function invokeModel(userPrompt) {
+            value: function invokeModel(input) {
                 return _async_to_generator(function() {
-                    var _this_options_logger, userInput, systemMessage, messages, _this_options_logger1, response, content;
+                    var _this_options_logger, userInput, systemMessage, jsonSchema, isPrimitiveType, messages, _this_options_logger1, response, content;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
                             case 0:
-                                userInput = this.resolveUserInput(userPrompt);
+                                userInput = this.resolveUserInput(input);
                                 systemMessage = this.options.systemPrompt.generate();
+                                // Add schema definition to system prompt if schema is provided
+                                if (this.options.schema) {
+                                    jsonSchema = z.toJSONSchema(this.options.schema);
+                                    isPrimitiveType = [
+                                        'boolean',
+                                        'integer',
+                                        'number',
+                                        'string'
+                                    ].includes(jsonSchema.type);
+                                    if (isPrimitiveType) {
+                                        systemMessage += "\n\n<OUTPUT_FORMAT>\nYou must respond with a ".concat(jsonSchema.type, " value that matches this schema:\n\n```json\n").concat(JSON.stringify(jsonSchema, null, 2), "\n```\n\nYour response should be only the ").concat(jsonSchema.type, " value, without any JSON wrapping or additional text.\n</OUTPUT_FORMAT>");
+                                    } else {
+                                        systemMessage += "\n\n<OUTPUT_FORMAT>\nYou must respond with valid JSON that matches this exact schema:\n\n```json\n".concat(JSON.stringify(jsonSchema, null, 2), "\n```\n\nYour response must be parseable JSON that validates against this schema. Do not include any text outside the JSON.\n</OUTPUT_FORMAT>");
+                                    }
+                                }
                                 messages = [
                                     {
                                         content: systemMessage,
@@ -276,7 +302,7 @@ import { AIResponseParser } from '../utils/ai-response-parser.js';
             key: "parseResponse",
             value: function parseResponse(content, schema) {
                 try {
-                    new AIResponseParser(schema).parse(content);
+                    return 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."), {
@@ -289,15 +315,15 @@ import { AIResponseParser } from '../utils/ai-response-parser.js';
         },
         {
             key: "resolveUserInput",
-            value: function resolveUserInput(userPrompt) {
-                if (userPrompt) {
-                    return userPrompt.generate();
+            value: function resolveUserInput(input) {
+                if (input) {
+                    return input.generate();
                 }
                 return 'Proceed with your instructions.';
             }
         }
     ]);
-    return QueryAgentAdapter;
+    return BasicAgentAdapter;
 }();
 
-//# sourceMappingURL=query-agent.adapter.js.map
+//# 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 { 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<TOutput = string> {\n    logger?: LoggerPort;\n    model: ModelPort;\n    schema?: z.ZodSchema<TOutput>;\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 * @template TOutput - The TypeScript type of the output\n */\nexport class BasicAgentAdapter<TOutput = string> implements AgentPort<PromptPort, TOutput> {\n    constructor(\n        public readonly name: string,\n        private readonly options: BasicAgentOptions<TOutput>,\n    ) {}\n\n    async run(input?: PromptPort): Promise<null | TOutput> {\n        this.options.logger?.debug(`[${this.name}] Starting query execution.`);\n\n        try {\n            const content = await this.invokeModel(input);\n\n            if (this.options.schema) {\n                const parsedResponse = this.parseResponse(content, this.options.schema);\n                this.options.logger?.info(`[${this.name}] Execution finished and response parsed.`);\n                return parsedResponse;\n            } else {\n                this.options.logger?.info(`[${this.name}] Execution finished.`);\n                // When no schema is provided, we assume TOutput is string (default), so content is the result\n                return content as TOutput;\n            }\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(input?: PromptPort): Promise<string> {\n        const userInput = this.resolveUserInput(input);\n        let systemMessage = this.options.systemPrompt.generate();\n\n        // Add schema definition to system prompt if schema is provided\n        if (this.options.schema) {\n            const jsonSchema = z.toJSONSchema(this.options.schema);\n            const isPrimitiveType = ['boolean', 'integer', 'number', 'string'].includes(\n                jsonSchema.type as string,\n            );\n\n            if (isPrimitiveType) {\n                systemMessage += `\\n\\n<OUTPUT_FORMAT>\nYou must respond with a ${jsonSchema.type} value that matches this schema:\n\n\\`\\`\\`json\n${JSON.stringify(jsonSchema, null, 2)}\n\\`\\`\\`\n\nYour response should be only the ${jsonSchema.type} value, without any JSON wrapping or additional text.\n</OUTPUT_FORMAT>`;\n            } else {\n                systemMessage += `\\n\\n<OUTPUT_FORMAT>\nYou must respond with valid JSON that matches this exact schema:\n\n\\`\\`\\`json\n${JSON.stringify(jsonSchema, null, 2)}\n\\`\\`\\`\n\nYour response must be parseable JSON that validates against this schema. Do not include any text outside the JSON.\n</OUTPUT_FORMAT>`;\n            }\n        }\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>): TResponse {\n        try {\n            return 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(input?: PromptPort): string {\n        if (input) {\n            return input.generate();\n        }\n        return 'Proceed with your instructions.';\n    }\n}\n"],"names":["z","AIResponseParser","BasicAgentAdapter","name","options","run","input","content","parsedResponse","error","logger","debug","invokeModel","schema","parseResponse","info","Error","message","userInput","systemMessage","jsonSchema","isPrimitiveType","messages","response","resolveUserInput","systemPrompt","generate","toJSONSchema","includes","type","JSON","stringify","role","hasSchema","verbose","model","getModel","invoke","parse","rawContent"],"mappings":"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"}

package/dist/index.cjs

@@ -627,24 +627,25 @@ 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';
+var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<GLOBAL_WRAPPER_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\n{schema_format}\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);
+ * @template TOutput - The TypeScript type of the output
+ */ 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) {
+            value: function run(input) {
                 return _async_to_generator$2(function() {
-                    var _this_options_logger, _this_options_logger1, executor, userInput, result, agentResponse, _this_options_logger2, _agentResponse_message, message, _this_options_logger3, _this_options_logger4, error, _this_options_logger5;
+                    var _this_options_logger, _this_options_logger1, executor, userInput, result, agentResponse, _this_options_logger2, _agentResponse_message, message, _this_options_logger3, validatedResponse, _this_options_logger4, error, _this_options_logger5;
                     return _ts_generator$2(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -663,7 +664,7 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
                                 ];
                             case 2:
                                 executor = _state.sent();
-                                userInput = this.resolveUserInput(userPrompt);
+                                userInput = this.resolveUserInput(input);
                                 return [
                                     4,
                                     executor.invoke({
@@ -696,15 +697,20 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
                                 }
                                 message = (_agentResponse_message = agentResponse.message) !== null && _agentResponse_message !== void 0 ? _agentResponse_message : '';
                                 if (this.options.schema) {
-                                    this.validateResponseContent(message, this.options.schema);
+                                    validatedResponse = this.validateResponseContent(message, this.options.schema);
                                     (_this_options_logger3 = this.options.logger) === null || _this_options_logger3 === void 0 ? void 0 : _this_options_logger3.info("[".concat(this.name, "] Execution finished; response content validated."));
+                                    return [
+                                        2,
+                                        validatedResponse
+                                    ];
                                 } else {
                                     (_this_options_logger4 = this.options.logger) === null || _this_options_logger4 === void 0 ? void 0 : _this_options_logger4.info("[".concat(this.name, "] Execution finished."));
+                                    // When no schema is provided, we assume TOutput is string (default), so message is the result
+                                    return [
+                                        2,
+                                        message
+                                    ];
                                 }
-                                return [
-                                    2,
-                                    message
-                                ];
                             case 4:
                                 error = _state.sent();
                                 (_this_options_logger5 = this.options.logger) === null || _this_options_logger5 === void 0 ? void 0 : _this_options_logger5.error("[".concat(this.name, "] Chat execution failed."), {
@@ -727,7 +733,7 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
             key: "createExecutor",
             value: function createExecutor() {
                 return _async_to_generator$2(function() {
-                    var model, tools, prompt, agent;
+                    var model, tools, schemaFormatInstructions, jsonSchema, isPrimitiveType, prompt, agent;
                     return _ts_generator$2(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -735,10 +741,27 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
                                 tools = this.options.tools.map(function(tool) {
                                     return tool.getDynamicTool();
                                 });
+                                // Add schema format instructions if schema is provided
+                                schemaFormatInstructions = '';
+                                if (this.options.schema) {
+                                    jsonSchema = v4.z.toJSONSchema(this.options.schema);
+                                    console.log(jsonSchema.type);
+                                    isPrimitiveType = [
+                                        'boolean',
+                                        'integer',
+                                        'number',
+                                        'string'
+                                    ].includes(jsonSchema.type);
+                                    if (isPrimitiveType) {
+                                        schemaFormatInstructions = '\n\nSCHEMA VALIDATION: When providing a "RESPOND:" answer, the content after "RESPOND: " must be a '.concat(jsonSchema.type, " value that matches this schema:\n\n```json\n").concat(JSON.stringify(jsonSchema, null, 2), '\n```\n\nExample format:\n```json\n{{\n  "action": "Final Answer",\n  "action_input": "RESPOND: your ').concat(jsonSchema.type, ' value here"\n}}\n```\n\nDo not wrap the ').concat(jsonSchema.type, ' value in JSON - just provide the raw value after "RESPOND: ".');
+                                    } else {
+                                        schemaFormatInstructions = '\n\nSCHEMA VALIDATION: When providing a "RESPOND:" answer, the content after "RESPOND: " must be valid JSON that matches this exact schema:\n\n```json\n'.concat(JSON.stringify(jsonSchema, null, 2).replace(/{/g, '{{').replace(/}/g, '}}'), '\n```\n\nExample format:\n```json\n{{\n  "action": "Final Answer",\n  "action_input": "RESPOND: {{\\"field1\\": \\"value1\\", \\"field2\\": \\"value2\\"}}"\n}}\n```\n');
+                                    }
+                                }
                                 prompt = prompts.ChatPromptTemplate.fromMessages([
                                     [
                                         'system',
-                                        SYSTEM_PROMPT_TEMPLATE.replace('{mission_prompt}', this.options.systemPrompt.generate())
+                                        SYSTEM_PROMPT_TEMPLATE.replace('{mission_prompt}', this.options.systemPrompt.generate()).replace('{schema_format}', schemaFormatInstructions)
                                     ],
                                     [
                                         'human',
@@ -795,9 +818,9 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
         },
         {
             key: "resolveUserInput",
-            value: function resolveUserInput(userPrompt) {
-                if (userPrompt) {
-                    return userPrompt.generate();
+            value: function resolveUserInput(input) {
+                if (input) {
+                    return input.generate();
                 }
                 return 'Proceed with your instructions.';
             }
@@ -806,7 +829,7 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
             key: "validateResponseContent",
             value: function validateResponseContent(content, schema) {
                 try {
-                    new AIResponseParser(schema).parse(content);
+                    return 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 validate response content against schema."), {
@@ -818,7 +841,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,22 +1003,23 @@ 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);
+ * @template TOutput - The TypeScript type of the output
+ */ 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) {
+            value: function run(input) {
                 return _async_to_generator$1(function() {
-                    var _this_options_logger, content, _this_options_logger1, _this_options_logger2, error, _this_options_logger3;
+                    var _this_options_logger, content, _this_options_logger1, parsedResponse, _this_options_logger2, error, _this_options_logger3;
                     return _ts_generator$1(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -1010,20 +1034,25 @@ function _ts_generator$1(thisArg, body) {
                                 ]);
                                 return [
                                     4,
-                                    this.invokeModel(userPrompt)
+                                    this.invokeModel(input)
                                 ];
                             case 2:
                                 content = _state.sent();
                                 if (this.options.schema) {
-                                    this.parseResponse(content, this.options.schema);
+                                    parsedResponse = 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."));
+                                    return [
+                                        2,
+                                        parsedResponse
+                                    ];
                                 } else {
                                     (_this_options_logger2 = this.options.logger) === null || _this_options_logger2 === void 0 ? void 0 : _this_options_logger2.info("[".concat(this.name, "] Execution finished."));
+                                    // When no schema is provided, we assume TOutput is string (default), so content is the result
+                                    return [
+                                        2,
+                                        content
+                                    ];
                                 }
-                                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."), {
@@ -1044,14 +1073,29 @@ function _ts_generator$1(thisArg, body) {
         },
         {
             key: "invokeModel",
-            value: function invokeModel(userPrompt) {
+            value: function invokeModel(input) {
                 return _async_to_generator$1(function() {
-                    var _this_options_logger, userInput, systemMessage, messages, _this_options_logger1, response, content;
+                    var _this_options_logger, userInput, systemMessage, jsonSchema, isPrimitiveType, messages, _this_options_logger1, response, content;
                     return _ts_generator$1(this, function(_state) {
                         switch(_state.label){
                             case 0:
-                                userInput = this.resolveUserInput(userPrompt);
+                                userInput = this.resolveUserInput(input);
                                 systemMessage = this.options.systemPrompt.generate();
+                                // Add schema definition to system prompt if schema is provided
+                                if (this.options.schema) {
+                                    jsonSchema = v4.z.toJSONSchema(this.options.schema);
+                                    isPrimitiveType = [
+                                        'boolean',
+                                        'integer',
+                                        'number',
+                                        'string'
+                                    ].includes(jsonSchema.type);
+                                    if (isPrimitiveType) {
+                                        systemMessage += "\n\n<OUTPUT_FORMAT>\nYou must respond with a ".concat(jsonSchema.type, " value that matches this schema:\n\n```json\n").concat(JSON.stringify(jsonSchema, null, 2), "\n```\n\nYour response should be only the ").concat(jsonSchema.type, " value, without any JSON wrapping or additional text.\n</OUTPUT_FORMAT>");
+                                    } else {
+                                        systemMessage += "\n\n<OUTPUT_FORMAT>\nYou must respond with valid JSON that matches this exact schema:\n\n```json\n".concat(JSON.stringify(jsonSchema, null, 2), "\n```\n\nYour response must be parseable JSON that validates against this schema. Do not include any text outside the JSON.\n</OUTPUT_FORMAT>");
+                                    }
+                                }
                                 messages = [
                                     {
                                         content: systemMessage,
@@ -1093,7 +1137,7 @@ function _ts_generator$1(thisArg, body) {
             key: "parseResponse",
             value: function parseResponse(content, schema) {
                 try {
-                    new AIResponseParser(schema).parse(content);
+                    return 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."), {
@@ -1106,15 +1150,15 @@ function _ts_generator$1(thisArg, body) {
         },
         {
             key: "resolveUserInput",
-            value: function resolveUserInput(userPrompt) {
-                if (userPrompt) {
-                    return userPrompt.generate();
+            value: function resolveUserInput(input) {
+                if (input) {
+                    return input.generate();
                 }
                 return 'Proceed with your instructions.';
             }
         }
     ]);
-    return QueryAgentAdapter;
+    return BasicAgentAdapter;
 }();
 
 function _class_call_check$3(instance, Constructor) {
@@ -1720,10 +1764,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, type AutonomousAgentOptions, } from './adapters/agents/autonomous-agent.adapter.js';
+export { BasicAgentAdapter, type BasicAgentOptions, } 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 {\n    AutonomousAgentAdapter,\n    type AutonomousAgentOptions,\n} from './adapters/agents/autonomous-agent.adapter.js';\nexport {\n    BasicAgentAdapter,\n    type BasicAgentOptions,\n} 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,SACIA,sBAAsB,QAEnB,gDAAgD;AACvD,SACIC,iBAAiB,QAEd,2CAA2C;AAClD,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/dist/ports/agent.port.d.ts

@@ -1,11 +1,13 @@
 import type { PromptPort } from './prompt.port.js';
 /**
- * Port for chat agents
+ * Port for chat agents with generic input and output types
+ * @template TInput - The type of input parameters the agent accepts
+ * @template TOutput - The type of output the agent returns
  */
-export interface AgentPort {
+export interface AgentPort<TInput = PromptPort, TOutput = string> {
     /**
-     * Run the agent with optional user prompt and return optional response
-     * @param userPrompt - The user prompt to process
+     * Run the agent with optional input and return optional response
+     * @param input - The input to process
      */
-    run(userPrompt?: PromptPort): Promise<null | string>;
+    run(input?: TInput): Promise<null | TOutput>;
 }

package/dist/ports/agent.port.js

@@ -1,5 +1,7 @@
 /**
- * Port for chat agents
+ * Port for chat agents with generic input and output types
+ * @template TInput - The type of input parameters the agent accepts
+ * @template TOutput - The type of output the agent returns
  */ export { };
 
 //# sourceMappingURL=agent.port.js.map

package/dist/ports/agent.port.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/ports/agent.port.ts"],"sourcesContent":["import type { PromptPort } from './prompt.port.js';\n\n/**\n * Port for chat agents\n */\nexport interface AgentPort {\n    /**\n     * Run the agent with optional user prompt and return optional response\n     * @param userPrompt - The user prompt to process\n     */\n    run(userPrompt?: PromptPort): Promise<null | string>;\n}\n"],"names":[],"mappings":"AAEA;;CAEC,GACD,WAMC"}
+{"version":3,"sources":["../../src/ports/agent.port.ts"],"sourcesContent":["import type { PromptPort } from './prompt.port.js';\n\n/**\n * Port for chat agents with generic input and output types\n * @template TInput - The type of input parameters the agent accepts\n * @template TOutput - The type of output the agent returns\n */\nexport interface AgentPort<TInput = PromptPort, TOutput = string> {\n    /**\n     * Run the agent with optional input and return optional response\n     * @param input - The input to process\n     */\n    run(input?: TInput): Promise<null | TOutput>;\n}\n"],"names":[],"mappings":"AAEA;;;;CAIC,GACD,WAMC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jterrazz/intelligence",
   "author": "Jean-Baptiste Terrazzoni <contact@jterrazz.com>",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "exports": {
     ".": {
       "require": "./dist/index.cjs",
@@ -24,10 +24,10 @@
   },
   "dependencies": {
     "@jterrazz/logger": "^1.3.4",
-    "@langchain/community": "^0.3.46",
-    "@langchain/core": "^0.3.58",
-    "@langchain/openai": "^0.5.13",
-    "zod": "^3.25.65"
+    "@langchain/community": "^0.3.47",
+    "@langchain/core": "^0.3.61",
+    "@langchain/openai": "^0.5.15",
+    "zod": "^3.25.67"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"