@operor/core 0.1.0

package/src/Agent.ts

@@ -0,0 +1,267 @@
+import EventEmitter from 'eventemitter3';
+import type {
+  AgentConfig,
+  ConversationContext,
+  AgentResponse,
+  ToolCall,
+  Tool,
+  IncomingMessage,
+  Customer,
+} from './types.js';
+
+export class Agent extends EventEmitter {
+  public readonly id: string;
+  public readonly name: string;
+  public readonly config: AgentConfig;
+  private tools: Map<string, Tool> = new Map();
+
+  constructor(config: AgentConfig) {
+    super();
+    this.id = `agent_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    this.name = config.name;
+    this.config = config;
+
+    // Register tools
+    config.tools?.forEach((tool) => {
+      this.tools.set(tool.name, tool);
+    });
+  }
+
+  /**
+   * Check if this agent should handle the given intent
+   */
+  matchesIntent(intent: string): boolean {
+    if (!this.config.triggers || this.config.triggers.length === 0) {
+      return true; // Match all if no triggers specified
+    }
+
+    const lowerIntent = intent.toLowerCase();
+    return this.config.triggers.some((trigger) =>
+      trigger === '*' || lowerIntent.includes(trigger.toLowerCase())
+    );
+  }
+
+  /**
+   * Process a message
+   */
+  async process(context: ConversationContext): Promise<AgentResponse> {
+    const startTime = Date.now();
+
+    try {
+      // For now, simple implementation without LLM
+      // In production, this would call LLM with tools
+      const response = await this.generateResponse(context);
+      const duration = Date.now() - startTime;
+
+      return {
+        text: response.text,
+        toolCalls: response.toolCalls,
+        duration,
+        cost: 0.001, // Mock cost
+      };
+    } catch (error) {
+      const duration = Date.now() - startTime;
+      throw new Error(`Agent processing failed: ${error}`);
+    }
+  }
+
+  /**
+   * Generate response (simplified - would use LLM in production)
+   */
+  private async generateResponse(
+    context: ConversationContext
+  ): Promise<{ text: string; toolCalls?: ToolCall[] }> {
+    const { currentMessage, customer, history } = context;
+    const toolCalls: ToolCall[] = [];
+
+    // Simple pattern matching for demo
+    const text = currentMessage.text.toLowerCase();
+
+    // Check for product search patterns
+    const productKeywords = ['headphones', 'keyboard', 'mouse', 'cable', 'product', 'electronics', 'stock', 'available', 'carry', 'sell'];
+    const matchedKeyword = productKeywords.find(kw => text.includes(kw));
+    const hasProductQuery = !!matchedKeyword;
+
+    if (hasProductQuery) {
+      const searchProductsTool = this.tools.get('search_products');
+      if (searchProductsTool) {
+        // Extract product name from matched keyword instead of using full message
+        const query = matchedKeyword || currentMessage.text;
+
+        const toolCall: ToolCall = {
+          id: `tool_${Date.now()}`,
+          name: 'search_products',
+          params: { query, limit: 5 },
+        };
+
+        try {
+          const result = await searchProductsTool.execute({ query, limit: 5 });
+          toolCall.result = result;
+          toolCall.success = true;
+          toolCall.duration = 100;
+          toolCalls.push(toolCall);
+        } catch (error) {
+          toolCall.success = false;
+          toolCall.error = String(error);
+          toolCalls.push(toolCall);
+        }
+      }
+    }
+
+    // Check for order number pattern
+    const orderMatch = text.match(/#?(\d{4,})/);
+    if (orderMatch) {
+      const orderId = orderMatch[1];
+
+      // Try to execute get_order tool if available
+      const getOrderTool = this.tools.get('get_order');
+      if (getOrderTool) {
+        const toolCall: ToolCall = {
+          id: `tool_${Date.now()}`,
+          name: 'get_order',
+          params: { orderId },
+        };
+
+        try {
+          const result = await getOrderTool.execute({ orderId });
+          toolCall.result = result;
+          toolCall.success = true;
+          toolCall.duration = 100;
+          toolCalls.push(toolCall);
+
+          // Check business rules
+          const ruleActions = await this.applyBusinessRules(context, toolCalls);
+
+          // Generate response based on tool results
+          let responseText = `I found your order #${orderId}.\n\n`;
+          responseText += `Status: ${result.status}\n`;
+
+          if (result.tracking) {
+            responseText += `Tracking: ${result.tracking}\n`;
+          }
+
+          if (ruleActions.length > 0) {
+            for (const action of ruleActions) {
+              if (action.type === 'discount_created') {
+                responseText += `\nI apologize for the delay! I've created a ${action.percent}% discount code for you: ${action.code} (valid ${action.validDays} days)`;
+              }
+            }
+          }
+
+          // Append product search results if both tools were called
+          if (hasProductQuery) {
+            const searchResult = toolCalls.find(tc => tc.name === 'search_products');
+            if (searchResult?.success && searchResult.result?.found > 0) {
+              responseText += `\n\nI also found ${searchResult.result.found} product(s) matching your search:\n\n`;
+              for (const product of searchResult.result.products) {
+                responseText += `• ${product.title} by ${product.vendor} - $${product.price}`;
+                if (!product.available) responseText += ' (Out of stock)';
+                responseText += '\n';
+              }
+            }
+          }
+
+          return { text: responseText, toolCalls };
+        } catch (error) {
+          toolCall.success = false;
+          toolCall.error = String(error);
+          toolCalls.push(toolCall);
+        }
+      }
+    }
+
+    // If we have product search results but no order, generate product-only response
+    if (hasProductQuery && toolCalls.some(tc => tc.name === 'search_products')) {
+      const searchResult = toolCalls.find(tc => tc.name === 'search_products');
+      if (searchResult?.success) {
+        let responseText = '';
+        if (searchResult.result?.found > 0) {
+          responseText = `I found ${searchResult.result.found} product(s) matching your search:\n\n`;
+          for (const product of searchResult.result.products) {
+            responseText += `• ${product.title} by ${product.vendor} - $${product.price}`;
+            if (!product.available) responseText += ' (Out of stock)';
+            responseText += '\n';
+          }
+        } else {
+          responseText = `I couldn't find any products matching "${matchedKeyword}". Would you like to try a different search?`;
+        }
+        return { text: responseText, toolCalls };
+      }
+    }
+
+    // Check if this is a greeting or first message
+    const greetings = ['hello', 'hi', 'hey', 'good morning', 'good afternoon', 'good evening'];
+    const isGreeting = greetings.some(g => text.trim().startsWith(g));
+    const isFirstMessage = !history || history.length === 0;
+
+    // Only introduce on first message or explicit greeting
+    if (isFirstMessage || isGreeting) {
+      return {
+        text: `Hi ${customer.name || 'there'}! I'm ${this.name}. ${this.config.purpose || 'How can I help you today?'}`,
+        toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+      };
+    }
+
+    // For follow-up messages, provide a helpful response without re-introducing
+    return {
+      text: `I understand. How can I assist you further?`,
+      toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+    };
+  }
+
+  /**
+   * Apply business rules
+   */
+  private async applyBusinessRules(
+    context: ConversationContext,
+    toolResults: ToolCall[]
+  ): Promise<any[]> {
+    const actions: any[] = [];
+
+    if (!this.config.rules) return actions;
+
+    for (const rule of this.config.rules) {
+      try {
+        const shouldApply = await rule.condition(context, toolResults);
+        if (shouldApply) {
+          const action = await rule.action(context, toolResults);
+          actions.push(action);
+
+          // Execute action tools if needed
+          if (action.toolName && this.tools.has(action.toolName)) {
+            const tool = this.tools.get(action.toolName)!;
+            const result = await tool.execute(action.params);
+            action.result = result;
+          }
+        }
+      } catch (error) {
+        console.error(`Rule "${rule.name}" failed:`, error);
+      }
+    }
+
+    return actions;
+  }
+
+  /**
+   * Get agent configuration
+   */
+  getConfig(): AgentConfig {
+    return { ...this.config };
+  }
+
+  /**
+   * Get available tools
+   */
+  getTools(): Tool[] {
+    return Array.from(this.tools.values());
+  }
+
+  /**
+   * Register tools dynamically (e.g., from integrations)
+   */
+  registerTools(tools: Tool[]): void {
+    tools.forEach((tool) => {
+      this.tools.set(tool.name, tool);
+    });
+  }
+}

package/src/AgentLoader.ts

@@ -0,0 +1,165 @@
+import fs from 'fs/promises';
+import path from 'path';
+import matter from 'gray-matter';
+import type { AgentConfig, AgentDefinition, GuardrailConfig } from './types.js';
+
+/**
+ * YAML frontmatter schema for INSTRUCTIONS.md files.
+ */
+interface AgentFrontmatter {
+  name: string;
+  purpose?: string;
+  triggers?: string[];
+  channels?: string[];
+  skills?: string[];
+  knowledgeBase?: boolean;
+  priority?: number;
+  escalateTo?: string;
+  guardrails?: GuardrailConfig;
+}
+
+/**
+ * Loads agent definitions from a file-based directory structure.
+ *
+ * Expected layout:
+ *   agents/
+ *     _defaults/
+ *       SOUL.md          (optional global soul/personality)
+ *     <agent-name>/
+ *       INSTRUCTIONS.md  (required — YAML frontmatter + markdown body)
+ *       IDENTITY.md      (optional — identity/persona)
+ *       SOUL.md          (optional — overrides _defaults/SOUL.md)
+ *   USER.md              (optional — workspace-level user context)
+ */
+export class AgentLoader {
+  private agentsDir: string;
+  private workspaceRoot: string;
+
+  constructor(workspaceRoot: string, agentsDir?: string) {
+    this.workspaceRoot = workspaceRoot;
+    this.agentsDir = agentsDir ?? path.join(workspaceRoot, 'agents');
+  }
+
+  /**
+   * Load all agent definitions from the agents directory.
+   */
+  async loadAll(): Promise<AgentDefinition[]> {
+    const entries = await fs.readdir(this.agentsDir, { withFileTypes: true });
+    const agentDirs = entries.filter(
+      (e) => e.isDirectory() && !e.name.startsWith('_'),
+    );
+
+    const definitions: AgentDefinition[] = [];
+    for (const dir of agentDirs) {
+      const def = await this.loadAgent(dir.name);
+      if (def) definitions.push(def);
+    }
+
+    return definitions;
+  }
+
+  /**
+   * Load a single agent definition by directory name.
+   */
+  async loadAgent(name: string): Promise<AgentDefinition | null> {
+    const agentDir = path.join(this.agentsDir, name);
+    const instructionsPath = path.join(agentDir, 'INSTRUCTIONS.md');
+
+    // INSTRUCTIONS.md is required
+    const instructionsRaw = await readFileOrNull(instructionsPath);
+    if (instructionsRaw === null) return null;
+
+    // Parse frontmatter + body
+    const { data: frontmatter, content: body } = matter(instructionsRaw) as {
+      data: AgentFrontmatter;
+      content: string;
+    };
+
+    // Read optional files
+    const [identity, agentSoul, defaultSoul, userContext] = await Promise.all([
+      readFileOrNull(path.join(agentDir, 'IDENTITY.md')),
+      readFileOrNull(path.join(agentDir, 'SOUL.md')),
+      readFileOrNull(path.join(this.agentsDir, '_defaults', 'SOUL.md')),
+      readFileOrNull(path.join(this.workspaceRoot, 'USER.md')),
+    ]);
+
+    // Build system prompt
+    const soul = agentSoul ?? defaultSoul;
+    const systemPrompt = buildSystemPrompt({
+      identity,
+      soul,
+      body,
+      userContext,
+      guardrails: frontmatter.guardrails,
+    });
+
+    // Build AgentConfig
+    const skills = frontmatter.skills;
+    const config: AgentConfig = {
+      name: frontmatter.name ?? name,
+      purpose: frontmatter.purpose,
+      triggers: frontmatter.triggers,
+      channels: frontmatter.channels,
+      skills,
+      knowledgeBase: frontmatter.knowledgeBase,
+      priority: frontmatter.priority,
+      escalateTo: frontmatter.escalateTo,
+      guardrails: frontmatter.guardrails,
+      systemPrompt,
+      _rawInstructions: body.trim() || undefined,
+      _rawIdentity: identity?.trim() || undefined,
+      _rawSoul: soul?.trim() || undefined,
+    };
+
+    return { config, systemPrompt, instructionsPath };
+  }
+}
+
+/**
+ * Read a file and return its contents, or null if it doesn't exist.
+ */
+export async function readFileOrNull(filePath: string): Promise<string | null> {
+  try {
+    return await fs.readFile(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assemble the system prompt from structured sections.
+ */
+export function buildSystemPrompt(parts: {
+  identity: string | null;
+  soul: string | null;
+  body: string;
+  userContext: string | null;
+  guardrails?: GuardrailConfig;
+}): string {
+  const sections: string[] = [];
+
+  if (parts.identity) {
+    sections.push(`## Identity\n\n${parts.identity.trim()}`);
+  }
+
+  if (parts.soul) {
+    sections.push(`## Soul\n\n${parts.soul.trim()}`);
+  }
+
+  if (parts.body.trim()) {
+    sections.push(`## Instructions\n\n${parts.body.trim()}`);
+  }
+
+  if (parts.userContext) {
+    sections.push(`## User Context\n\n${parts.userContext.trim()}`);
+  }
+
+  if (parts.guardrails?.systemRules && parts.guardrails.systemRules.length > 0) {
+    const rules = parts.guardrails.systemRules
+      .map((rule, i) => `${i + 1}. ${rule}`)
+      .join('\n');
+    sections.push(`## System Rules\n\nYou MUST follow these rules at all times:\n${rules}`);
+  }
+
+  return sections.join('\n\n');
+}

package/src/AgentVersionStore.ts

@@ -0,0 +1,59 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+export interface VersionSnapshot {
+  timestamp: string;
+  instructions?: string;
+  identity?: string;
+  soul?: string;
+  frontmatter?: Record<string, any>;
+  editedBy?: string;
+  changeDescription?: string;
+}
+
+const MAX_VERSIONS = 20;
+
+export class AgentVersionStore {
+  private agentsDir?: string;
+  private memory = new Map<string, VersionSnapshot[]>();
+
+  constructor(agentsDir?: string) {
+    this.agentsDir = agentsDir;
+  }
+
+  async saveVersion(agentName: string, snapshot: VersionSnapshot): Promise<void> {
+    const history = await this.loadHistory(agentName);
+    history.unshift(snapshot);
+    if (history.length > MAX_VERSIONS) history.length = MAX_VERSIONS;
+
+    if (this.agentsDir) {
+      const dir = path.join(this.agentsDir, '_versions');
+      await fs.mkdir(dir, { recursive: true });
+      await fs.writeFile(path.join(dir, `${agentName}.json`), JSON.stringify(history, null, 2));
+    } else {
+      this.memory.set(agentName, history);
+    }
+  }
+
+  async getHistory(agentName: string, limit?: number): Promise<VersionSnapshot[]> {
+    const history = await this.loadHistory(agentName);
+    return limit ? history.slice(0, limit) : history;
+  }
+
+  async getVersion(agentName: string, index: number): Promise<VersionSnapshot | null> {
+    const history = await this.loadHistory(agentName);
+    return history[index] ?? null;
+  }
+
+  private async loadHistory(agentName: string): Promise<VersionSnapshot[]> {
+    if (this.agentsDir) {
+      try {
+        const data = await fs.readFile(path.join(this.agentsDir, '_versions', `${agentName}.json`), 'utf-8');
+        return JSON.parse(data);
+      } catch {
+        return [];
+      }
+    }
+    return [...(this.memory.get(agentName) ?? [])];
+  }
+}

package/src/Guardrails.ts

@@ -0,0 +1,60 @@
+import type { GuardrailConfig } from './types.js';
+
+export interface GuardrailCheckResult {
+  allowed: boolean;
+  reason?: string;
+  escalate?: boolean;
+}
+
+export class GuardrailEngine {
+  /**
+   * Check incoming message against guardrail config.
+   * Returns whether the message is allowed, and whether it should escalate.
+   */
+  checkInput(message: string, config: GuardrailConfig): GuardrailCheckResult {
+    const lowerMessage = message.toLowerCase();
+
+    // Check escalation triggers first
+    if (config.escalationTriggers) {
+      for (const trigger of config.escalationTriggers) {
+        if (lowerMessage.includes(trigger.toLowerCase())) {
+          return { allowed: false, reason: `Escalation triggered: "${trigger}"`, escalate: true };
+        }
+      }
+    }
+
+    // Check blocked topics
+    if (config.blockedTopics) {
+      for (const topic of config.blockedTopics) {
+        if (lowerMessage.includes(topic.toLowerCase())) {
+          return { allowed: false, reason: `Blocked topic: "${topic}"` };
+        }
+      }
+    }
+
+    return { allowed: true };
+  }
+
+  /**
+   * Check outgoing response against guardrail config.
+   * Returns whether the response is allowed to be sent.
+   */
+  checkOutput(response: string, config: GuardrailConfig): GuardrailCheckResult {
+    // Check max response length
+    if (config.maxResponseLength && response.length > config.maxResponseLength) {
+      return { allowed: false, reason: `Response exceeds max length (${response.length}/${config.maxResponseLength})` };
+    }
+
+    // Check blocked topics in response
+    if (config.blockedTopics) {
+      const lowerResponse = response.toLowerCase();
+      for (const topic of config.blockedTopics) {
+        if (lowerResponse.includes(topic.toLowerCase())) {
+          return { allowed: false, reason: `Response contains blocked topic: "${topic}"` };
+        }
+      }
+    }
+
+    return { allowed: true };
+  }
+}

package/src/InMemoryStore.ts

@@ -0,0 +1,89 @@
+import type { Customer, ConversationMessage, MemoryStore } from './types.js';
+
+/**
+ * Default in-memory implementation of MemoryStore.
+ * Data is lost on restart. Used as the default when no external store is provided.
+ */
+export class InMemoryStore implements MemoryStore {
+  private customers: Map<string, Customer> = new Map();
+  private phoneIndex: Map<string, string> = new Map();
+  private conversations: Map<string, ConversationMessage[]> = new Map();
+  private settings: Map<string, string> = new Map();
+
+  async initialize(): Promise<void> {}
+
+  async getCustomer(id: string): Promise<Customer | null> {
+    return this.customers.get(id) || null;
+  }
+
+  async getCustomerByPhone(phone: string): Promise<Customer | null> {
+    const customerId = this.phoneIndex.get(phone);
+    if (!customerId) return null;
+    return this.customers.get(customerId) || null;
+  }
+
+  async upsertCustomer(customer: Customer): Promise<void> {
+    this.customers.set(customer.id, customer);
+    if (customer.phone) {
+      this.phoneIndex.set(customer.phone, customer.id);
+    }
+  }
+
+  async getHistory(customerId: string, limit = 50, agentId?: string): Promise<ConversationMessage[]> {
+    const key = agentId ? `${customerId}:${agentId}` : customerId;
+    const history = this.conversations.get(key) || [];
+    return history.slice(-limit);
+  }
+
+  async addMessage(customerId: string, message: ConversationMessage, agentId?: string): Promise<void> {
+    const key = agentId ? `${customerId}:${agentId}` : customerId;
+    if (!this.conversations.has(key)) {
+      this.conversations.set(key, []);
+    }
+    const history = this.conversations.get(key)!;
+    history.push(message);
+    if (history.length > 50) {
+      history.splice(0, history.length - 50);
+    }
+  }
+
+  async clearHistory(customerId?: string, agentId?: string): Promise<{ deletedCount: number }> {
+    let deletedCount = 0;
+    if (customerId) {
+      // Delete matching keys
+      for (const [key, messages] of this.conversations) {
+        const [cid, aid] = key.includes(':') ? key.split(':') : [key, undefined];
+        if (cid === customerId && (!agentId || aid === agentId)) {
+          deletedCount += messages.length;
+          this.conversations.delete(key);
+        }
+      }
+    } else {
+      // Delete all
+      for (const messages of this.conversations.values()) {
+        deletedCount += messages.length;
+      }
+      this.conversations.clear();
+    }
+    return { deletedCount };
+  }
+
+  async getSetting(key: string): Promise<string | null> {
+    return this.settings.get(key) ?? null;
+  }
+
+  async setSetting(key: string, value: string | null): Promise<void> {
+    if (value === null) {
+      this.settings.delete(key);
+    } else {
+      this.settings.set(key, value);
+    }
+  }
+
+  async close(): Promise<void> {
+    this.customers.clear();
+    this.phoneIndex.clear();
+    this.conversations.clear();
+    this.settings.clear();
+  }
+}