@agenticc/core 1.0.0

package/dist/conversation/session.js

@@ -0,0 +1,285 @@
+/**
+ * Session Management
+ *
+ * Manages conversation sessions for the Agent.
+ * Each session maintains its own conversation history and metadata.
+ *
+ * _Requirements: 9.1, 9.4_
+ */
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * Session Manager
+ *
+ * Manages the lifecycle of conversation sessions.
+ * Provides methods for creating, retrieving, and managing sessions.
+ */
+export class SessionManager {
+    sessions = new Map();
+    defaultSessionId = 'default';
+    /**
+     * Create a new session
+     *
+     * @param options - Session creation options
+     * @returns The new session ID
+     */
+    createSession(options) {
+        const id = options?.id ?? uuidv4();
+        // Check if session already exists
+        if (this.sessions.has(id)) {
+            throw new Error(`Session with ID "${id}" already exists`);
+        }
+        const now = new Date();
+        const session = {
+            id,
+            messages: [],
+            createdAt: now,
+            updatedAt: now,
+            metadata: options?.metadata,
+            active: true,
+        };
+        // Add system message if provided
+        if (options?.systemMessage) {
+            session.messages.push({
+                id: uuidv4(),
+                role: 'system',
+                content: options.systemMessage,
+                timestamp: now,
+            });
+        }
+        this.sessions.set(id, session);
+        return id;
+    }
+    /**
+     * Get a session by ID
+     *
+     * @param sessionId - Session ID
+     * @returns The session or undefined if not found
+     */
+    getSession(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    /**
+     * Get or create a session
+     *
+     * @param sessionId - Session ID
+     * @param options - Options for creating if not exists
+     * @returns The session
+     */
+    getOrCreateSession(sessionId, options) {
+        let session = this.sessions.get(sessionId);
+        if (!session) {
+            this.createSession({ ...options, id: sessionId });
+            session = this.sessions.get(sessionId);
+        }
+        return session;
+    }
+    /**
+     * Check if a session exists
+     *
+     * @param sessionId - Session ID
+     * @returns True if session exists
+     */
+    hasSession(sessionId) {
+        return this.sessions.has(sessionId);
+    }
+    /**
+     * Get all sessions matching query options
+     *
+     * @param options - Query options
+     * @returns Array of matching sessions
+     */
+    querySessions(options) {
+        let sessions = Array.from(this.sessions.values());
+        // Apply filters
+        if (options?.active !== undefined) {
+            sessions = sessions.filter((s) => s.active === options.active);
+        }
+        if (options?.createdAfter) {
+            sessions = sessions.filter((s) => s.createdAt >= options.createdAfter);
+        }
+        if (options?.createdBefore) {
+            sessions = sessions.filter((s) => s.createdAt <= options.createdBefore);
+        }
+        // Sort by creation date (newest first)
+        sessions.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
+        // Apply pagination
+        if (options?.offset) {
+            sessions = sessions.slice(options.offset);
+        }
+        if (options?.limit) {
+            sessions = sessions.slice(0, options.limit);
+        }
+        return sessions;
+    }
+    /**
+     * Get conversation history for a session
+     * Messages are returned in chronological order (oldest first)
+     *
+     * @param sessionId - Session ID
+     * @returns Array of messages ordered by timestamp
+     */
+    getHistory(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return [];
+        }
+        // Return a copy sorted by timestamp (chronological order)
+        return [...session.messages].sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+    }
+    /**
+     * Add a user message to a session
+     *
+     * @param sessionId - Session ID
+     * @param content - Message content
+     * @param metadata - Optional metadata
+     * @returns The created message
+     */
+    addUserMessage(sessionId, content, metadata) {
+        const session = this.getOrCreateSession(sessionId);
+        const message = {
+            id: uuidv4(),
+            role: 'user',
+            content,
+            timestamp: new Date(),
+            metadata,
+        };
+        session.messages.push(message);
+        session.updatedAt = new Date();
+        return message;
+    }
+    /**
+     * Add an assistant message to a session
+     *
+     * @param sessionId - Session ID
+     * @param response - Agent response
+     * @param metadata - Optional metadata
+     * @returns The created message
+     */
+    addAssistantMessage(sessionId, response, metadata) {
+        const session = this.getOrCreateSession(sessionId);
+        const message = {
+            id: uuidv4(),
+            role: 'assistant',
+            content: 'message' in response ? response.message : JSON.stringify(response),
+            timestamp: new Date(),
+            responseType: response.type,
+            metadata,
+        };
+        // Add tool calls if present
+        if (response.type === 'execute' && response.toolCalls) {
+            message.toolCalls = response.toolCalls;
+        }
+        session.messages.push(message);
+        session.updatedAt = new Date();
+        return message;
+    }
+    /**
+     * Add a system message to a session
+     *
+     * @param sessionId - Session ID
+     * @param content - Message content
+     * @returns The created message
+     */
+    addSystemMessage(sessionId, content) {
+        const session = this.getOrCreateSession(sessionId);
+        const message = {
+            id: uuidv4(),
+            role: 'system',
+            content,
+            timestamp: new Date(),
+        };
+        session.messages.push(message);
+        session.updatedAt = new Date();
+        return message;
+    }
+    /**
+     * Close a session (mark as inactive)
+     *
+     * @param sessionId - Session ID
+     * @returns True if session was closed
+     */
+    closeSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return false;
+        }
+        session.active = false;
+        session.updatedAt = new Date();
+        return true;
+    }
+    /**
+     * Delete a session
+     *
+     * @param sessionId - Session ID
+     * @returns True if session was deleted
+     */
+    deleteSession(sessionId) {
+        return this.sessions.delete(sessionId);
+    }
+    /**
+     * Clear all messages in a session
+     *
+     * @param sessionId - Session ID
+     * @returns True if session was cleared
+     */
+    clearSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return false;
+        }
+        session.messages = [];
+        session.updatedAt = new Date();
+        return true;
+    }
+    /**
+     * Update session metadata
+     *
+     * @param sessionId - Session ID
+     * @param metadata - New metadata (merged with existing)
+     * @returns True if session was updated
+     */
+    updateMetadata(sessionId, metadata) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return false;
+        }
+        session.metadata = { ...session.metadata, ...metadata };
+        session.updatedAt = new Date();
+        return true;
+    }
+    /**
+     * Get the default session ID
+     */
+    getDefaultSessionId() {
+        return this.defaultSessionId;
+    }
+    /**
+     * Set the default session ID
+     */
+    setDefaultSessionId(sessionId) {
+        this.defaultSessionId = sessionId;
+    }
+    /**
+     * Get total number of sessions
+     */
+    getSessionCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Get total number of messages across all sessions
+     */
+    getTotalMessageCount() {
+        let count = 0;
+        for (const session of this.sessions.values()) {
+            count += session.messages.length;
+        }
+        return count;
+    }
+}
+/**
+ * Create a new SessionManager instance
+ */
+export function createSessionManager() {
+    return new SessionManager();
+}
+//# sourceMappingURL=session.js.map

package/dist/conversation/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/conversation/session.ts"],"names":[],"mappings":"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"}

package/dist/core/agent.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Agent Core
+ *
+ * Main Agent class that orchestrates the agentic loop, plugin management,
+ * knowledge retrieval, and response handling.
+ *
+ * Refactored to use:
+ * - PluginManager for tool management (replacing ToolRegistry)
+ * - AgenticLoop for autonomous LLM decision-making
+ * - Confirmation mechanism for high-risk operations
+ *
+ * _Requirements: 1.1-1.7, 4.1, 4.5, 4.7_
+ */
+import type { AgentConfig } from '../types/config.js';
+import type { AgentResponse, ToolCallRecord } from '../types/response.js';
+import type { Tool } from '../types/tool.js';
+import type { AgentPlugin, PluginInfo } from '../types/plugin.js';
+import type { StreamEvent } from '../types/streaming.js';
+import { LLMManager } from '../llm/manager.js';
+import { KnowledgeStore } from '../knowledge/store.js';
+import { Retriever } from '../knowledge/retriever.js';
+import { PluginManager } from './plugin-manager.js';
+import { AgenticLoop } from './agentic-loop.js';
+/**
+ * Message in conversation history
+ */
+export interface Message {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    timestamp: Date;
+    toolCalls?: ToolCallRecord[];
+    responseType?: string;
+}
+/**
+ * Conversation session
+ */
+export interface Session {
+    id: string;
+    messages: Message[];
+    createdAt: Date;
+    updatedAt: Date;
+    metadata?: Record<string, unknown>;
+    /** Pending confirmation state */
+    pendingConfirmation?: PendingConfirmation;
+}
+/**
+ * Pending confirmation state
+ */
+export interface PendingConfirmation {
+    /** The tool that requires confirmation */
+    toolName: string;
+    /** Arguments for the tool */
+    arguments: Record<string, unknown>;
+    /** Original user message */
+    userMessage: string;
+    /** Timestamp when confirmation was requested */
+    timestamp: Date;
+}
+/**
+ * Agent options for chat
+ */
+export interface ChatOptions {
+    /** Session ID (creates new session if not provided) */
+    sessionId?: string;
+    /** Skip knowledge retrieval */
+    skipKnowledge?: boolean;
+    /** Skip confirmation for this request */
+    skipConfirmation?: boolean;
+    /** Additional context */
+    context?: Record<string, unknown>;
+    /** System prompt override */
+    systemPrompt?: string;
+    /** Abort signal for cancellation */
+    abortSignal?: AbortSignal;
+    /** Callback for streaming events */
+    onEvent?: (event: StreamEvent) => void;
+    /** Message ID for streaming events */
+    messageId?: string;
+    /**
+     * Historical messages loaded from database.
+     * Used for stateless operation - Agent does not maintain session state in memory.
+     */
+    history?: Message[];
+    /**
+     * Pending confirmation state loaded from database.
+     * Used for stateless operation when user needs to confirm a high-risk operation.
+     */
+    pendingConfirmation?: PendingConfirmation;
+}
+/**
+ * Agent
+ *
+ * Main AI Agent class that coordinates all components to process
+ * user messages and generate appropriate responses using the agentic loop.
+ */
+export declare class Agent {
+    private config;
+    private behavior;
+    private llmManager;
+    private knowledgeStore;
+    private embedder?;
+    private retriever;
+    private pluginManager;
+    private agenticLoop;
+    private responseHandler;
+    private logger;
+    private logLevel;
+    private metricsEnabled;
+    private pluginContext;
+    constructor(config: AgentConfig);
+    /**
+     * Process a user message and generate a response
+     *
+     * Pure Stateless Implementation:
+     * - Does not maintain session state in memory
+     * - History is passed in via options.history (loaded from database)
+     * - PendingConfirmation is passed in via options.pendingConfirmation
+     * - Returns pendingConfirmation in response for external persistence
+     *
+     * _Requirements: 1.1, 1.2, 1.3, 2.3, 2.4_
+     */
+    chat(message: string, options?: ChatOptions): Promise<AgentResponse>;
+    /**
+     * Convert external Message history to LoopMessage format
+     */
+    private convertHistoryToLoopMessages;
+    /**
+     * Map an error to a streaming error code
+     */
+    private mapErrorToCode;
+    /**
+     * Retrieve knowledge context with streaming events
+     * Requirement: 3.1
+     */
+    private retrieveKnowledgeContextWithEvents;
+    /**
+     * Handle user's response to a confirmation request
+     *
+     * Stateless version: receives pendingConfirmation from database via options
+     */
+    private handleConfirmationResponse;
+    /**
+     * Check if any tool in the potential execution requires confirmation
+     *
+     * _Requirements: 4.7_
+     */
+    private checkConfirmationNeeded;
+    /**
+     * Create a confirmation response
+     */
+    private createConfirmResponse;
+    /**
+     * Convert agentic loop result to agent response
+     */
+    private loopResultToResponse;
+    /**
+     * Retrieve knowledge context for the message
+     * @deprecated Use retrieveKnowledgeContextWithEvents instead
+     */
+    private retrieveKnowledgeContext;
+    /**
+     * Continue processing after user confirmation
+     *
+     * @deprecated In stateless mode, confirmations should be handled by passing
+     * pendingConfirmation via options.pendingConfirmation in chat()
+     */
+    confirm(confirmed: boolean, sessionId?: string, options?: ChatOptions): Promise<AgentResponse>;
+    /**
+     * Add knowledge to the knowledge base
+     */
+    addKnowledge(content: string, category: string, title?: string): Promise<string>;
+    /**
+     * Load a plugin
+     */
+    loadPlugin(plugin: AgentPlugin): Promise<void>;
+    /**
+     * Unload a plugin
+     */
+    unloadPlugin(pluginName: string): Promise<boolean>;
+    /**
+     * List all loaded plugins
+     */
+    listPlugins(): PluginInfo[];
+    /**
+     * Get a specific plugin
+     */
+    getPlugin(name: string): AgentPlugin | undefined;
+    /**
+     * Check if a plugin is loaded
+     */
+    hasPlugin(name: string): boolean;
+    /**
+     * Register a tool with the agent (legacy method)
+     * @deprecated Use loadPlugin instead
+     */
+    registerTool(tool: Tool): void;
+    /**
+     * Register multiple tools (legacy method)
+     * @deprecated Use loadPlugin instead
+     */
+    registerTools(tools: Tool[]): void;
+    /**
+     * @deprecated In stateless mode, history should be passed via options.history in chat()
+     * This method is kept for backward compatibility but does nothing.
+     */
+    importSessionHistory(_sessionId: string, _messages: Array<{
+        id: string;
+        role: string;
+        content: string;
+        createdAt: Date | string;
+        toolCalls?: string | null;
+        responseType?: string | null;
+    }>): void;
+    /**
+     * @deprecated In stateless mode, Agent does not maintain session state.
+     * Always returns false.
+     */
+    hasSessionHistory(_sessionId: string): boolean;
+    /**
+     * @deprecated In stateless mode, history is not stored in Agent.
+     * Always returns empty array.
+     */
+    getHistory(_sessionId?: string): Message[];
+    /**
+     * @deprecated In stateless mode, sessions are managed externally (database).
+     * Returns a generated UUID for compatibility.
+     */
+    createSession(_metadata?: Record<string, unknown>): string;
+    /**
+     * Create tool context for execution
+     */
+    private createToolContext;
+    /**
+     * Create plugin context for dependency injection
+     */
+    private createPluginContext;
+    /**
+     * Create a logger instance with log level filtering
+     */
+    private createLogger;
+    /**
+     * Create a logger wrapper for custom logger
+     */
+    private createCustomLogger;
+    /**
+     * Get the LLM Manager
+     */
+    getLLMManager(): LLMManager;
+    /**
+     * Get the Plugin Manager
+     */
+    getPluginManager(): PluginManager;
+    /**
+     * Get the Knowledge Store
+     */
+    getKnowledgeStore(): KnowledgeStore;
+    /**
+     * Get the Retriever
+     */
+    getRetriever(): Retriever;
+    /**
+     * Get the Agentic Loop
+     */
+    getAgenticLoop(): AgenticLoop;
+    /**
+     * Get the current session ID
+     * @deprecated In stateless mode, session ID should be managed externally.
+     * Returns a placeholder value for compatibility.
+     */
+    getCurrentSessionId(): string;
+}
+/**
+ * Create an Agent with simplified configuration
+ */
+export declare function createAgent(llmProvider: 'openai' | 'claude' | 'qwen' | 'siliconflow', apiKey: string, model: string, options?: Partial<AgentConfig>): Agent;
+//# sourceMappingURL=agent.d.ts.map

package/dist/core/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"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"}