@jterrazz/intelligence 1.1.1 → 1.3.0

package/README.md

@@ -30,22 +30,22 @@ Get your first agent running in under a minute. This example uses a preset to cr
 
 ```typescript
 import {
-  ChatAgentAdapter,
-  OpenRouterModelAdapter,
+  AutonomousAgentAdapter,
+  OpenRouterAdapter,
   SystemPromptAdapter,
-  PROMPTS,
+  PROMPT_LIBRARY,
 } from '@jterrazz/intelligence';
 
 // 1. Set up the model provider
-const model = new OpenRouterModelAdapter({
+const model = new OpenRouterAdapter({
   apiKey: process.env.OPENROUTER_API_KEY!, // Make sure to set this environment variable
   modelName: 'anthropic/claude-3.5-sonnet',
 });
 
 // 2. Create an agent using a preset prompt
-const agent = new ChatAgentAdapter('discord-bot', {
+const agent = new AutonomousAgentAdapter('discord-bot', {
   model,
-  systemPrompt: new SystemPromptAdapter(PROMPTS.PRESETS.DISCORD_COMMUNITY_ANIMATOR),
+  systemPrompt: new SystemPromptAdapter(PROMPT_LIBRARY.PRESETS.COMMUNITY_ANIMATOR),
 });
 
 // 3. Run the agent
@@ -63,10 +63,14 @@ console.log(response);
 
 Instead of writing monolithic prompts, the library provides a collection of composable string constants. Mix and match them to build a precise, fine-grained system prompt that defines your agent's behavior.
 
-- **`PERSONA`**: Who the agent is (e.g., `EXPERT_ADVISOR`).
-- **`TONE`**: How the agent communicates (e.g., `PROFESSIONAL`, `EMPATHETIC`).
-- **`FORMAT`** How the agent structures its response (e.g., `MARKDOWN`, `JSON`).
-- **`DIRECTIVES`**: Core rules the agent must follow (e.g., `BE_SAFE`, `BE_FACTUAL`).
+- **`FOUNDATIONS`**: Core, non-negotiable rules (e.g., `PROMPT_LIBRARY.FOUNDATIONS.ETHICAL_CONDUCT`).
+- **`PERSONAS`**: The agent's identity and purpose (e.g., `PROMPT_LIBRARY.PERSONAS.EXPERT_ADVISOR`).
+- **`DOMAINS`**: The agent's area of expertise (e.g., `PROMPT_LIBRARY.DOMAINS.SOFTWARE_ENGINEERING`).
+- **`TONES`**: The emotional flavor of communication (e.g., `PROMPT_LIBRARY.TONES.PROFESSIONAL`).
+- **`FORMATS`**: The structural format of the output (e.g., `PROMPT_LIBRARY.FORMATS.JSON`).
+- **`LANGUAGES`**: The natural language for the response (e.g., `PROMPT_LIBRARY.LANGUAGES.ENGLISH_NATIVE`).
+- **`VERBOSITY`**: The level of detail in the response (e.g., `PROMPT_LIBRARY.VERBOSITY.DETAILED`).
+- **`RESPONSES`**: The strategic approach to responding (e.g., `PROMPT_LIBRARY.RESPONSES.ALWAYS_ENGAGE`).
 
 This approach makes agent behavior more predictable and easier to modify.
 
@@ -100,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 `OpenRouterModelAdapter` 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.
 
@@ -120,26 +124,26 @@ This recipe creates an agent that acts as an expert software engineer, providing
 
 ```typescript
 import {
-  ChatAgentAdapter,
-  OpenRouterModelAdapter,
+  AutonomousAgentAdapter,
+  OpenRouterAdapter,
   SystemPromptAdapter,
   UserPromptAdapter,
-  PROMPTS,
+  PROMPT_LIBRARY,
 } from '@jterrazz/intelligence';
 
-const model = new OpenRouterModelAdapter({
+const model = new OpenRouterAdapter({
   apiKey: process.env.OPENROUTER_API_KEY!,
   modelName: 'anthropic/claude-3.5-sonnet',
 });
 
 // 1. Compose the system prompt from multiple parts (using rest arguments)
 const systemPrompt = new SystemPromptAdapter(
-  PROMPTS.PERSONA.EXPERT_ADVISOR,
-  PROMPTS.DOMAIN.SOFTWARE_ENGINEERING,
-  PROMPTS.TONE.PROFESSIONAL,
-  PROMPTS.VERBOSITY.DETAILED,
-  PROMPTS.FORMAT.MARKDOWN,
-  PROMPTS.DIRECTIVES.BE_FACTUAL,
+  PROMPT_LIBRARY.PERSONAS.EXPERT_ADVISOR,
+  PROMPT_LIBRARY.DOMAINS.SOFTWARE_ENGINEERING,
+  PROMPT_LIBRARY.TONES.PROFESSIONAL,
+  PROMPT_LIBRARY.VERBOSITY.DETAILED,
+  PROMPT_LIBRARY.FORMATS.MARKDOWN,
+  PROMPT_LIBRARY.FOUNDATIONS.FACTUAL_ACCURACY,
 );
 
 // 2. Create the user request (using a single array)
@@ -149,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,
 });
@@ -159,34 +163,34 @@ 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,
-  OpenRouterModelAdapter,
+  BasicAgentAdapter,
+  OpenRouterAdapter,
   SystemPromptAdapter,
   UserPromptAdapter,
-  PROMPTS,
+  PROMPT_LIBRARY,
 } from '@jterrazz/intelligence';
 
-const model = new OpenRouterModelAdapter({
+const model = new OpenRouterAdapter({
   apiKey: process.env.OPENROUTER_API_KEY!,
   modelName: 'anthropic/claude-3.5-sonnet',
 });
 
 // 1. Create a simple system prompt for text processing
 const systemPrompt = new SystemPromptAdapter(
-  PROMPTS.PERSONA.EXPERT_ADVISOR,
-  PROMPTS.TONE.PROFESSIONAL,
-  PROMPTS.FORMAT.MARKDOWN,
+  PROMPT_LIBRARY.PERSONAS.EXPERT_ADVISOR,
+  PROMPT_LIBRARY.TONES.PROFESSIONAL,
+  PROMPT_LIBRARY.FORMATS.MARKDOWN,
   '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,
 });
@@ -201,21 +205,21 @@ 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,
-  OpenRouterModelAdapter,
+  BasicAgentAdapter,
+  OpenRouterAdapter,
   SystemPromptAdapter,
   UserPromptAdapter,
-  PROMPTS,
+  PROMPT_LIBRARY,
 } from '@jterrazz/intelligence';
 import { z } from 'zod/v4';
 
-const model = new OpenRouterModelAdapter({
+const model = new OpenRouterAdapter({
   apiKey: process.env.OPENROUTER_API_KEY!,
   modelName: 'anthropic/claude-3.5-sonnet',
 });
@@ -230,14 +234,14 @@ const extractionSchema = z.object({
 
 // 2. Create a system prompt for data extraction
 const systemPrompt = new SystemPromptAdapter(
-  PROMPTS.PERSONA.EXPERT_ADVISOR,
-  PROMPTS.TONE.PROFESSIONAL,
-  PROMPTS.FORMAT.JSON,
+  PROMPT_LIBRARY.PERSONAS.EXPERT_ADVISOR,
+  PROMPT_LIBRARY.TONES.PROFESSIONAL,
+  PROMPT_LIBRARY.FORMATS.JSON,
   '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,
@@ -262,11 +266,12 @@ This example shows how to give an agent a tool and have it respond to a user que
 
 ```typescript
 import {
-  ChatAgentAdapter,
-  OpenRouterModelAdapter,
+  AutonomousAgentAdapter,
+  OpenRouterAdapter,
   SafeToolAdapter,
   SystemPromptAdapter,
-  PROMPTS,
+  UserPromptAdapter,
+  PROMPT_LIBRARY,
 } from '@jterrazz/intelligence';
 import { z } from 'zod/v4';
 
@@ -286,14 +291,14 @@ 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(PROMPTS.PRESETS.EMPATHETIC_SUPPORT_AGENT), // A good general-purpose preset
+  systemPrompt: new SystemPromptAdapter(PROMPT_LIBRARY.PRESETS.EMPATHETIC_SUPPORT_AGENT), // A good general-purpose preset
   tools: [weatherTool], // Pass the tool instance directly
 });
 
 // 3. Run the agent with a user query that requires the tool
-const response = await agent.run({ generate: () => "What's the weather like in Boston?" });
+const response = await agent.run(new UserPromptAdapter("What's the weather like in Boston?"));
 
 console.log(response);
 // Expected output: "The weather in Boston is 75°F and sunny."
@@ -305,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.  |
-| `PROMPTS`                | 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}

@@ -160,20 +160,20 @@ function _ts_generator(thisArg, body) {
 import { ChatPromptTemplate } from '@langchain/core/prompts';
 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. Any formatting guidelines within the <OBJECTIVE> section (like message templates) apply ONLY to the content that goes inside the "RESPOND: " part of your final answer.\n\nYou 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. The input must start with "RESPOND: " or "SILENT: ".\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</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<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) {
@@ -213,6 +213,12 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
                                     throw new Error('Agent returned an invalid result structure.');
                                 }
                                 agentResponse = this.parseAgentOutput(result.output);
+                                if (!agentResponse) {
+                                    return [
+                                        2,
+                                        null
+                                    ];
+                                }
                                 if (!agentResponse.shouldRespond) {
                                     ;
                                     (_this_options_logger2 = this.options.logger) === null || _this_options_logger2 === void 0 ? void 0 : _this_options_logger2.info("[".concat(this.name, "] Agent chose to remain silent."), {
@@ -318,13 +324,10 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
                         shouldRespond: false
                     };
                 }
-                (_this_options_logger = this.options.logger) === null || _this_options_logger === void 0 ? void 0 : _this_options_logger.warn("[".concat(this.name, "] Agent output was missing 'RESPOND:' or 'SILENT:' prefix. Treating as a direct response."), {
+                (_this_options_logger = this.options.logger) === null || _this_options_logger === void 0 ? void 0 : _this_options_logger.error("[".concat(this.name, "] Agent output was missing 'RESPOND:' or 'SILENT:' prefix."), {
                     rawOutput: output
                 });
-                return {
-                    message: text,
-                    shouldRespond: true
-                };
+                return null;
             }
         },
         {
@@ -352,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;
+}