agentic-ai-framework 1.0.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "agentic-ai-framework",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Reusable agentic framework with session memory, tool calling, CoT, and multi-agent team support",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./providers/claude": "./src/llm/providers/ClaudeProvider.js",
+    "./providers/grok": "./src/llm/providers/GrokProvider.js",
+    "./providers/openai": "./src/llm/providers/OpenAIProvider.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.1.3",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "dotenv": "^16.4.7"
+  },
+  "keywords": [
+    "agent",
+    "llm",
+    "ai",
+    "framework",
+    "tool-calling",
+    "memory"
+  ],
+  "license": "MIT"
+}

package/src/agent/Agent.js

@@ -0,0 +1,278 @@
+import { randomUUID } from 'crypto';
+import { AgentConfig } from './AgentConfig.js';
+import { AgentRunner } from './AgentRunner.js';
+import { SessionMemory } from '../memory/SessionMemory.js';
+import { MemoryManager } from '../memory/MemoryManager.js';
+import { ToolRegistry } from '../tool/ToolRegistry.js';
+import { LLMRouter } from '../llm/LLMRouter.js';
+import { PromptBuilder } from '../prompt/PromptBuilder.js';
+import { AgentError } from '../utils/errors.js';
+import { createLogger } from '../utils/logger.js';
+
+/**
+ * The core Agent class.
+ *
+ * An Agent owns:
+ *   - An LLM provider (via LLMRouter)
+ *   - A PromptBuilder (template + optional CoT injection)
+ *   - A SessionMemory (conversation history + working context)
+ *   - A ToolRegistry (registered tools callable by the LLM)
+ *   - An AgentRunner (the tool-calling loop engine)
+ *
+ * Concurrency note:
+ *   Create a FRESH Agent instance per request in backend handlers.
+ *   Each instance has its own SessionMemory — no shared state between requests.
+ *   See examples/simple-agent.js for the recommended usage pattern.
+ */
+export class Agent {
+    /**
+     * @param {AgentConfig} config
+     */
+    constructor(config) {
+        if (!(config instanceof AgentConfig)) {
+            throw new AgentError('Agent: config must be an AgentConfig instance');
+        }
+
+        this.config = config;
+        this.name = config.name;
+        this.description = config.description ?? '';
+
+        this._log = createLogger('Agent', { agent: this.name });
+
+        // LLM provider (cached globally by LLMRouter)
+        this._llm = LLMRouter.get(config.provider, config.model ?? null, config.apiKey);
+
+        // Memory
+        this._memory = new SessionMemory({ maxMessages: config.maxHistoryMessages });
+        this._memoryManager = config.persistenceDir
+            ? new MemoryManager({ dir: config.persistenceDir })
+            : null;
+
+        // Tools
+        this._toolRegistry = new ToolRegistry();
+
+        // Prompt builder
+        this._promptBuilder = new PromptBuilder({
+            systemPromptTemplate: config.systemPromptTemplate,
+            systemPromptFile: config.systemPromptFile,
+            cotEnabled: config.chainOfThought,
+            cotMode: config.cotMode,
+            cotStyle: config.cotStyle,
+            cotCustomInstructions: config.cotCustomInstructions,
+        });
+
+        // Runner (tool-calling loop engine)
+        this._runner = new AgentRunner({
+            llm: this._llm,
+            toolRegistry: this._toolRegistry,
+            maxIterations: config.maxToolIterations,
+            temperature: config.temperature,
+            maxTokens: config.maxTokens,
+            outputSchema: config.outputSchema,
+            reflectMode: this._promptBuilder.isReflectMode,
+            agentName: this.name,
+            loopTimeoutMs: config.loopTimeoutMs,
+        });
+
+        this._sessionId = null;
+    }
+
+    // ── Tool registration ─────────────────────────────────────────────────────
+
+    /**
+     * Register a tool the agent can call. Chainable.
+     * @param {import('../tool/Tool.js').Tool} tool
+     * @returns {Agent}
+     */
+    registerTool(tool) {
+        this._toolRegistry.register(tool);
+        return this;
+    }
+
+    /**
+     * Register multiple tools at once. Chainable.
+     * @param {import('../tool/Tool.js').Tool[]} tools
+     * @returns {Agent}
+     */
+    registerTools(tools) {
+        for (const tool of tools) this._toolRegistry.register(tool);
+        return this;
+    }
+
+    /**
+     * Get the tool registry. Used by AgentTeam to register delegation tools.
+     * @returns {import('../tool/ToolRegistry.js').ToolRegistry}
+     */
+    getToolRegistry() {
+        return this._toolRegistry;
+    }
+
+    // ── Session lifecycle ─────────────────────────────────────────────────────
+
+    /**
+     * Start a session. If sessionId is provided and a persisted session exists,
+     * its history and context are restored. If no sessionId is provided, a new
+     * UUID is generated.
+     *
+     * @param {string} [sessionId] - Existing session ID to resume, or omit to create new
+     * @returns {Promise<string>} The active sessionId
+     */
+    async startSession(sessionId) {
+        this._sessionId = sessionId ?? randomUUID();
+
+        if (this._memoryManager && sessionId) {
+            const snapshot = await this._memoryManager.load(sessionId);
+            if (snapshot) {
+                this._memory.restore(snapshot);
+                this._log.info({ sessionId, historyLength: this._memory.historyLength }, 'session restored');
+            } else {
+                this._log.info({ sessionId }, 'new session started (no prior data)');
+            }
+        }
+
+        return this._sessionId;
+    }
+
+    /**
+     * Persist the current session memory to disk.
+     * Requires persistenceDir to be configured in AgentConfig.
+     * Requires startSession() to have been called first.
+     */
+    async saveSession() {
+        if (!this._sessionId) {
+            throw new AgentError(`${this.name}: call startSession() before saveSession()`);
+        }
+        if (this._memoryManager) {
+            await this._memoryManager.save(this._sessionId, this._memory.snapshot());
+            this._log.debug({ sessionId: this._sessionId }, 'session saved');
+        }
+    }
+
+    /**
+     * Clear in-memory state and optionally delete the persisted session file.
+     *
+     * @param {boolean} [deletePersisted=false] - If true, also delete the JSON file on disk
+     */
+    async endSession(deletePersisted = false) {
+        if (this._memoryManager && this._sessionId && deletePersisted) {
+            await this._memoryManager.delete(this._sessionId);
+            this._log.info({ sessionId: this._sessionId }, 'session deleted');
+        }
+        this._memory.clear();
+        this._sessionId = null;
+    }
+
+    // ── Working context ───────────────────────────────────────────────────────
+
+    /**
+     * Store a named value in working context. Injected into system prompt as ${key}.
+     * Chainable.
+     *
+     * @param {string} key
+     * @param {*} value
+     * @returns {Agent}
+     */
+    setContext(key, value) {
+        this._memory.setContext(key, value);
+        return this;
+    }
+
+    /**
+     * Retrieve a context value.
+     * @param {string} key
+     * @returns {*}
+     */
+    getContext(key) {
+        return this._memory.getContext(key);
+    }
+
+    // ── Main execution ────────────────────────────────────────────────────────
+
+    /**
+     * Run the agent on a user input.
+     *
+     * The agent:
+     *   1. Builds the system prompt (template + context vars + optional CoT block)
+     *   2. Assembles messages: [system, ...history, user]
+     *   3. Runs the tool-calling loop via AgentRunner
+     *   4. Optionally appends the exchange to session history
+     *
+     * Per-request pattern (stateless, no session needed):
+     *   const result = await agent.run(userInput, { appendToHistory: false });
+     *
+     * Stateful pattern (session memory):
+     *   await agent.startSession('user-123');
+     *   const result = await agent.run(userInput);
+     *   await agent.saveSession();
+     *
+     * @param {string} userInput
+     * @param {Object} [opts={}]
+     * @param {Record<string, string | number | boolean>} [opts.templateVars={}]
+     *   Additional variables for system prompt interpolation (merged with context).
+     * @param {boolean} [opts.appendToHistory=true]
+     *   Whether to add this exchange to session memory.
+     *   Set to false for stateless (per-request) agents.
+     * @returns {Promise<import('./AgentRunner.js').AgentResult>}
+     */
+    async run(userInput, opts = {}) {
+        const { templateVars = {}, appendToHistory = true } = opts;
+
+        this._log.debug({ userInput: userInput.slice(0, 100) }, 'agent.run()');
+
+        // Build system prompt (CoT appended here if cotMode='prompt')
+        const systemPrompt = await this._promptBuilder.build({
+            vars: { ...this._memory.getContextSnapshot(), ...templateVars },
+        });
+
+        // Assemble messages: system + conversation history + new user message
+        const messages = [
+            { role: 'system', content: systemPrompt },
+            ...this._memory.getHistory(),
+            { role: 'user', content: userInput },
+        ];
+
+        // Run the tool-calling loop
+        const result = await this._runner.run(messages);
+
+        // Append exchange to session history (unless disabled)
+        if (appendToHistory) {
+            this._memory.appendExchange(userInput, result.text ?? result.content ?? '');
+        }
+
+        this._log.debug(
+            { success: result.success, iterations: result.iterations, tools: result.toolCallHistory.length },
+            'agent.run() complete'
+        );
+
+        return result;
+    }
+
+    // ── Introspection ─────────────────────────────────────────────────────────
+
+    /**
+     * Get a snapshot of the agent's current state.
+     * @returns {Object}
+     */
+    getInfo() {
+        return {
+            name: this.name,
+            description: this.description,
+            provider: this.config.provider,
+            model: this.config.model ?? 'default',
+            sessionId: this._sessionId,
+            historyLength: this._memory.historyLength,
+            registeredTools: this._toolRegistry.listNames(),
+            persistenceEnabled: !!this._memoryManager,
+            chainOfThought: this.config.chainOfThought,
+            cotMode: this.config.cotMode,
+        };
+    }
+
+    /**
+     * Test connectivity to the configured LLM provider.
+     * @returns {Promise<boolean>}
+     */
+    async testConnection() {
+        return this._llm.testConnection();
+    }
+}

package/src/agent/AgentConfig.js

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import { ConfigError } from '../utils/errors.js';
+
+// Zod schema for AgentConfig validation
+const AgentConfigSchema = z.object({
+    // Required
+    name: z.string().min(1, 'name must be a non-empty string'),
+    provider: z.enum(['grok', 'claude', 'openai']).or(z.string().min(1)),
+    apiKey: z.string().min(1, 'apiKey is required'),
+
+    // Prompt — exactly one of these must be provided
+    systemPromptTemplate: z.string().optional(),
+    systemPromptFile: z.string().optional(),
+
+    // LLM options
+    model: z.string().optional(),
+    temperature: z.number().min(0).max(2).default(0.1),
+    maxTokens: z.number().int().positive().default(4000),
+    maxToolIterations: z.number().int().positive().default(5),
+    outputSchema: z.record(z.unknown()).nullable().default(null),
+
+    // Memory options
+    maxHistoryMessages: z.number().int().positive().default(50),
+    persistenceDir: z.string().nullable().default(null),
+
+    // CoT options
+    chainOfThought: z.boolean().default(true),
+    cotMode: z.enum(['prompt', 'reflect']).default('prompt'),
+    cotStyle: z.enum(['step-by-step', 'pros-cons', 'custom']).default('step-by-step'),
+    cotCustomInstructions: z.string().nullable().default(null),
+
+    // Agent description (used by AgentTeam)
+    description: z.string().default(''),
+
+    // Runner timeout for the tool-calling loop (ms)
+    loopTimeoutMs: z.number().int().positive().default(300000), // 5 minutes
+
+    // LLM request timeout (ms) — passed to the provider
+    requestTimeoutMs: z.number().int().positive().optional(),
+}).strict(); // reject unknown fields to catch typos early
+
+/**
+ * Validated configuration value object for an Agent.
+ * Throws ConfigError on invalid input.
+ */
+export class AgentConfig {
+    /**
+     * @param {Object} options
+     * @param {string} options.name
+     * @param {string} options.provider       - 'grok' | 'claude' | 'openai' | custom
+     * @param {string} options.apiKey
+     * @param {string} [options.systemPromptTemplate] - Inline prompt template
+     * @param {string} [options.systemPromptFile]     - Path to .md prompt file
+     * @param {string} [options.model]
+     * @param {number} [options.temperature=0.1]
+     * @param {number} [options.maxTokens=4000]
+     * @param {number} [options.maxToolIterations=5]
+     * @param {Object} [options.outputSchema=null]   - JSON Schema for structured output
+     * @param {number} [options.maxHistoryMessages=50]
+     * @param {string} [options.persistenceDir=null] - Directory for session persistence
+     * @param {boolean} [options.chainOfThought=true]
+     * @param {string} [options.cotMode='prompt']    - 'prompt' | 'reflect'
+     * @param {string} [options.cotStyle='step-by-step']
+     * @param {string} [options.cotCustomInstructions=null]
+     * @param {string} [options.description='']      - Agent description for AgentTeam
+     */
+    constructor(options) {
+        const result = AgentConfigSchema.safeParse(options);
+        if (!result.success) {
+            const issues = result.error.issues
+                .map(i => `${i.path.join('.')}: ${i.message}`)
+                .join('; ');
+            throw new ConfigError(`Invalid AgentConfig: ${issues}`);
+        }
+
+        const config = result.data;
+
+        // Validate that exactly one prompt source is provided
+        if (!config.systemPromptTemplate && !config.systemPromptFile) {
+            throw new ConfigError(
+                'AgentConfig: provide either systemPromptTemplate (inline string) or systemPromptFile (path to file)',
+                { field: 'systemPromptTemplate | systemPromptFile' }
+            );
+        }
+
+        Object.assign(this, config);
+    }
+}

package/src/agent/AgentRunner.js

@@ -0,0 +1,256 @@
+import { createLogger } from '../utils/logger.js';
+
+/**
+ * Executes the tool-calling loop for an agent.
+ *
+ * This is the core engine extracted from the existing masterAgent, sqlAgent, etc.
+ * Each of those had ~50 lines of identical loop code; this replaces all of them.
+ *
+ * Flow:
+ *   1. Call LLM with current messages + registered tools
+ *   2. If LLM returns tool calls → execute tools, append results, loop
+ *   3. If LLM returns final text answer → return AgentResult
+ *   4. If max iterations reached → return failure result
+ *
+ * Optionally, if cotMode='reflect', a second LLM call is made after the final
+ * answer to verify and potentially improve it.
+ */
+export class AgentRunner {
+    /**
+     * @param {Object} options
+     * @param {import('../llm/BaseLLMProvider.js').BaseLLMProvider} options.llm
+     * @param {import('../tool/ToolRegistry.js').ToolRegistry} options.toolRegistry
+     * @param {number} options.maxIterations
+     * @param {number} options.temperature
+     * @param {number} options.maxTokens
+     * @param {Object|null} options.outputSchema  - JSON Schema for structured output
+     * @param {boolean} options.reflectMode       - Whether to run reflection pass after answer
+     * @param {string} options.agentName          - For logging
+     */
+    constructor({ llm, toolRegistry, maxIterations, temperature, maxTokens, outputSchema, reflectMode, agentName, loopTimeoutMs }) {
+        this._llm = llm;
+        this._toolRegistry = toolRegistry;
+        this._maxIterations = maxIterations;
+        this._temperature = temperature;
+        this._maxTokens = maxTokens;
+        this._outputSchema = outputSchema;
+        this._reflectMode = reflectMode ?? false;
+        this._loopTimeoutMs = loopTimeoutMs ?? 300000; // 5 minutes default
+        this._log = createLogger('AgentRunner', { agent: agentName });
+    }
+
+    /**
+     * Run the tool-calling loop given an already-assembled messages array.
+     *
+     * @param {Array<{role: string, content: string}>} messages - System + history + user message
+     * @returns {Promise<AgentResult>}
+     *
+     * @typedef {Object} AgentResult
+     * @property {boolean} success
+     * @property {string}  [content]         - Raw LLM text output
+     * @property {Object}  [parsed]          - Parsed JSON (when outputSchema set)
+     * @property {string}  [text]            - Convenience: parsed.text_answer ?? parsed.answer ?? content
+     * @property {Array}   toolCallHistory   - All tool calls with timestamps
+     * @property {Object}  [usage]           - Token usage from final LLM call
+     * @property {number}  iterations        - Number of tool-calling iterations
+     * @property {string}  [error]           - Present when success=false
+     * @property {Object}  [cotTrace]        - Present when reflectMode=true
+     */
+    async run(messages) {
+        const tools = this._toolRegistry.getDefinitions();
+        const hasTools = tools.length > 0;
+        const toolCallHistory = [];
+        let iteration = 0;
+        let currentMessages = [...messages];
+
+        // Extract the original user question for reflect-mode
+        const userQuestion = messages.findLast(m => m.role === 'user')?.content ?? '';
+
+        const loopStart = Date.now();
+
+        while (iteration <= this._maxIterations) {
+            // Guard against runaway loops
+            if (Date.now() - loopStart > this._loopTimeoutMs) {
+                return {
+                    success: false,
+                    error: `Tool-calling loop timed out after ${this._loopTimeoutMs}ms`,
+                    toolCallHistory,
+                    iterations: iteration,
+                };
+            }
+            let response;
+
+            try {
+                const callOptions = {
+                    messages: currentMessages,
+                    temperature: this._temperature,
+                    maxTokens: this._maxTokens,
+                    enableTools: hasTools,
+                    tools: hasTools ? tools : undefined,
+                };
+
+                response = await this._callLLMWithRetry(callOptions);
+
+            } catch (err) {
+                return {
+                    success: false,
+                    error: `LLM call failed: ${err.message}`,
+                    toolCallHistory,
+                    iterations: iteration,
+                };
+            }
+
+            // ── Tool calls requested ─────────────────────────────────────────
+            if (response.toolCalls?.length > 0) {
+                iteration++;
+
+                if (iteration > this._maxIterations) {
+                    return {
+                        success: false,
+                        error: `Max tool iterations (${this._maxIterations}) reached without final answer`,
+                        toolCallHistory,
+                        iterations: iteration,
+                    };
+                }
+
+                // Update messages with assistant's tool-call response
+                currentMessages = response.messages ?? [...currentMessages];
+
+                for (const toolCall of response.toolCalls) {
+                    this._log.debug({ tool: toolCall.name, args: toolCall.arguments }, 'executing tool');
+
+                    let toolResult;
+                    try {
+                        toolResult = await this._toolRegistry.execute(toolCall.name, toolCall.arguments);
+                    } catch (err) {
+                        toolResult = `Error executing tool "${toolCall.name}": ${err.message}`;
+                        this._log.warn({ tool: toolCall.name, err: err.message }, 'tool execution failed');
+                    }
+
+                    toolCallHistory.push({
+                        id: toolCall.id,
+                        name: toolCall.name,
+                        arguments: toolCall.arguments,
+                        result: typeof toolResult === 'string' ? toolResult.slice(0, 500) : toolResult, // truncate for log
+                        iteration,
+                        timestamp: new Date().toISOString(),
+                    });
+
+                    // Append tool result to messages
+                    currentMessages.push({
+                        role: 'tool',
+                        tool_call_id: toolCall.id,
+                        name: toolCall.name,
+                        content: toolResult,
+                    });
+                }
+
+                continue; // next iteration
+            }
+
+            // ── Final answer ─────────────────────────────────────────────────
+            if (response.content || response.parsed) {
+                const baseResult = {
+                    success: true,
+                    content: response.content,
+                    parsed: response.parsed ?? null,
+                    text: response.parsed?.text_answer
+                        ?? response.parsed?.answer
+                        ?? response.content
+                        ?? '',
+                    toolCallHistory,
+                    usage: response.usage,
+                    iterations: iteration,
+                };
+
+                // Reflect mode: make a second call to verify the answer
+                if (this._reflectMode && userQuestion) {
+                    return this._reflect(baseResult, userQuestion, currentMessages);
+                }
+
+                return baseResult;
+            }
+
+            // Empty response — shouldn't happen but break to avoid infinite loop
+            break;
+        }
+
+        return {
+            success: false,
+            error: 'Agent returned empty response',
+            toolCallHistory,
+            iterations: iteration,
+        };
+    }
+
+    /**
+     * Reflection pass: asks the LLM to verify and potentially improve its answer.
+     * @param {AgentResult} baseResult
+     * @param {string} userQuestion
+     * @param {Array} currentMessages
+     * @returns {Promise<AgentResult>}
+     */
+    async _reflect(baseResult, userQuestion, currentMessages) {
+        const reflectPrompt = `Review your answer below. Does it fully and correctly address the original question?
+If the answer is correct and complete, repeat it unchanged.
+If it has issues, provide the correct answer.
+
+Original question: ${userQuestion}
+
+Your answer: ${baseResult.text}`;
+
+        try {
+            const reflectMessages = [
+                ...currentMessages,
+                { role: 'user', content: reflectPrompt },
+            ];
+
+            const reflectResponse = await this._llm.complete('', {
+                messages: reflectMessages,
+                temperature: 0.1,
+                maxTokens: this._maxTokens,
+            });
+
+            const improvedText = reflectResponse.content || baseResult.text;
+
+            return {
+                ...baseResult,
+                text: improvedText,
+                content: improvedText,
+                cotTrace: {
+                    original: baseResult.text,
+                    reflected: improvedText,
+                    changed: improvedText !== baseResult.text,
+                },
+            };
+        } catch (err) {
+            this._log.warn({ err: err.message }, 'reflect pass failed — returning original answer');
+            return { ...baseResult, cotTrace: { original: baseResult.text, reflectError: err.message } };
+        }
+    }
+
+    /**
+     * Call the LLM with retry + exponential backoff for transient errors (429, 5xx, timeouts).
+     * @param {Object} callOptions
+     * @param {number} [maxRetries=2]
+     * @returns {Promise<Object>}
+     */
+    async _callLLMWithRetry(callOptions, maxRetries = 2) {
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return this._outputSchema
+                    ? await this._llm.completeWithSchema('', this._outputSchema, callOptions)
+                    : await this._llm.complete('', callOptions);
+            } catch (err) {
+                lastError = err;
+                const isTransient = /timed out|429|500|502|503|504|rate.limit/i.test(err.message);
+                if (!isTransient || attempt >= maxRetries) throw err;
+                const delayMs = Math.min(1000 * 2 ** attempt, 8000);
+                this._log.warn({ attempt: attempt + 1, delayMs, err: err.message }, 'transient LLM error — retrying');
+                await new Promise(r => setTimeout(r, delayMs));
+            }
+        }
+        throw lastError;
+    }
+}