@operor/core 0.1.0

package/src/types.ts

@@ -0,0 +1,286 @@
+// Core types for Operor
+
+export interface IncomingMessage {
+  id: string;
+  from: string;
+  text: string;
+  timestamp: number;
+  channel: 'whatsapp' | 'instagram' | 'facebook' | 'sms' | 'telegram';
+  provider: string;
+  metadata?: Record<string, any>;
+  /** Raw file/media buffer (e.g. downloaded WhatsApp document) */
+  mediaBuffer?: Buffer;
+  /** Original file name of the attachment */
+  mediaFileName?: string;
+  /** MIME type of the attachment */
+  mediaMimeType?: string;
+}
+
+export interface OutgoingMessage {
+  to: string;
+  text: string;
+  metadata?: Record<string, any>;
+  /** Optional file/media buffer for document attachments */
+  mediaBuffer?: Buffer;
+  /** File name for the attachment */
+  mediaFileName?: string;
+  /** MIME type of the attachment */
+  mediaMimeType?: string;
+}
+
+export interface Customer {
+  id: string;
+  phone?: string;
+  email?: string;
+  name?: string;
+  whatsappId?: string;
+  instagramId?: string;
+  facebookId?: string;
+  metadata?: Record<string, any>;
+  lifetimeValue?: number;
+  firstInteraction?: Date;
+  lastInteraction?: Date;
+}
+
+export interface Intent {
+  intent: string;
+  confidence: number;
+  entities: Record<string, any>;
+}
+
+export interface IntentClassifier {
+  classify(message: string, agents: AgentConfig[], history?: ConversationMessage[]): Promise<Intent>;
+}
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  params: Record<string, any>;
+  result?: any;
+  duration?: number;
+  success?: boolean;
+  error?: string;
+}
+
+export interface ConversationMessage {
+  role: 'user' | 'assistant';
+  content: string;
+  timestamp: number;
+  toolCalls?: ToolCall[];
+}
+
+export interface AgentResponse {
+  text: string;
+  toolCalls?: ToolCall[];
+  duration: number;
+  cost?: number;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+  };
+  metadata?: Record<string, any>;
+  mediaBuffer?: Buffer;
+  mediaFileName?: string;
+  mediaMimeType?: string;
+}
+
+export interface Tool {
+  name: string;
+  description: string;
+  parameters: Record<string, any>;
+  execute: (params: any) => Promise<any>;
+}
+
+export interface BusinessRule {
+  name: string;
+  description?: string;
+  condition: (context: any, toolResults: any[]) => Promise<boolean> | boolean;
+  action: (context: any, toolResults: any[]) => Promise<any> | any;
+}
+
+export interface AgentConfig {
+  name: string;
+  purpose?: string;
+  personality?: string;
+  triggers?: string[];
+  channels?: string[];
+  tools?: Tool[];
+  rules?: BusinessRule[];
+  guardrails?: GuardrailConfig;
+  knowledgeBase?: boolean;       // opt-in per agent to use KB
+  skills?: string[];             // skill names to load (e.g. MCP servers)
+  systemPrompt?: string;         // full system prompt for LLM
+  priority?: number;             // routing priority (higher = preferred)
+  escalateTo?: string;           // agent name to escalate to
+  /** Raw markdown body from INSTRUCTIONS.md (after YAML frontmatter) */
+  _rawInstructions?: string;
+  /** Raw content from IDENTITY.md */
+  _rawIdentity?: string;
+  /** Raw content from SOUL.md (agent-level or inherited from _defaults) */
+  _rawSoul?: string;
+}
+
+export interface MessageProvider {
+  name: string;
+  connect(): Promise<void>;
+  disconnect(): Promise<void>;
+  sendMessage(to: string, message: OutgoingMessage): Promise<void>;
+  /** Show a typing indicator to the user (e.g. "composing…" in WhatsApp, "typing…" in Telegram). */
+  sendTypingIndicator?(to: string): Promise<void>;
+  on(event: string, handler: (...args: any[]) => void): void;
+  off(event: string, handler: (...args: any[]) => void): void;
+}
+
+export interface Skill {
+  name: string;
+  initialize(): Promise<void>;
+  isReady(): boolean;
+  tools: Record<string, Tool>;
+  close?(): Promise<void>;
+}
+
+export interface LLMConfig {
+  provider: 'openai' | 'anthropic' | 'ollama' | 'mock';
+  apiKey?: string;
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+}
+
+export interface LLMResponse {
+  text: string;
+  toolCalls?: ToolCall[];
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  cost?: number;
+}
+
+export interface MemoryConfig {
+  type: 'memory' | 'redis' | 'postgres';
+  connectionString?: string;
+}
+
+export interface MemoryStore {
+  getCustomer(id: string): Promise<Customer | null>;
+  getCustomerByPhone(phone: string): Promise<Customer | null>;
+  upsertCustomer(customer: Customer): Promise<void>;
+  getHistory(customerId: string, limit?: number, agentId?: string): Promise<ConversationMessage[]>;
+  addMessage(customerId: string, message: ConversationMessage, agentId?: string): Promise<void>;
+  initialize(): Promise<void>;
+  close(): Promise<void>;
+  getSetting?(key: string): Promise<string | null>;
+  setSetting?(key: string, value: string | null): Promise<void>;
+  clearHistory?(customerId?: string, agentId?: string): Promise<{ deletedCount: number }>;
+}
+
+export interface ConversationContext {
+  customer: Customer;
+  history: ConversationMessage[];
+  currentMessage: IncomingMessage;
+  intent?: Intent;
+}
+
+export interface KnowledgeStoreConfig {
+  dbPath?: string;           // default './operor-kb.db'
+  embeddingProvider?: 'openai' | 'ollama';
+  embeddingModel?: string;   // default 'text-embedding-3-small'
+  embeddingApiKey?: string;
+  embeddingBaseUrl?: string;
+  dimensions?: number;       // default 1536
+}
+
+export interface TrainingModeConfig {
+  enabled: boolean;
+  whitelist: string[];       // phone numbers allowed to use training commands
+}
+
+export interface GuardrailConfig {
+  systemRules?: string[];        // rules injected into system prompt
+  blockedTopics?: string[];      // topics to refuse
+  escalationTriggers?: string[]; // phrases that trigger human handoff
+  maxResponseLength?: number;    // max chars in response
+}
+
+/** Runtime KB interface for training mode. Keeps core decoupled from @operor/knowledge. */
+export interface KnowledgeBaseRuntime {
+  ingestFaq(question: string, answer: string, metadata?: Record<string, any>): Promise<{ id: string; existingMatch?: { id: string; question: string; answer: string; score: number } }>;
+  listDocuments(): Promise<KBDocumentSummary[]>;
+  deleteDocument(id: string): Promise<void>;
+  retrieve(query: string): Promise<{ results: KBRetrievalHit[]; context: string; isFaqMatch: boolean }>;
+  getStats(): Promise<{ documentCount: number; chunkCount: number; embeddingDimensions: number; dbSizeBytes: number }>;
+  /** Ingest a single URL (webpage). */
+  ingestUrl?(url: string): Promise<{ id: string; title?: string; chunks: number }>;
+  /** Crawl and ingest an entire website. */
+  ingestSite?(url: string, options?: { maxDepth?: number; maxPages?: number; onProgress?: (crawled: number, total: number, url: string) => void }): Promise<{ documents: number; chunks: number }>;
+  /** Ingest a file from a Buffer (e.g. media attachment from messaging). */
+  ingestFile?(buffer: Buffer, fileName: string): Promise<{ id: string; title?: string; chunks: number }>;
+  /** Rebuild all vector embeddings using the current embedding provider. */
+  rebuild?(): Promise<{ documentsRebuilt: number; chunksRebuilt: number; oldDimensions: number; newDimensions: number }>;
+}
+
+export interface KBDocumentSummary {
+  id: string;
+  sourceType: string;
+  sourceUrl?: string;
+  fileName?: string;
+  title?: string;
+  content: string;
+  createdAt: number;
+}
+
+export interface KBRetrievalHit {
+  chunk: { content: string };
+  document: { title?: string };
+  score: number;
+}
+
+export interface OperorConfig {
+  apiKey?: string;
+  llm?: LLMConfig;
+  /** LLM provider instance — used by /model commands for runtime switching */
+  llmProvider?: any;
+  memory?: MemoryStore;
+  intentClassifier?: IntentClassifier;
+  debug?: boolean;
+  batchWindowMs?: number;
+  autoAddAssistantMessages?: boolean;
+  knowledgeStore?: KnowledgeStoreConfig;
+  trainingMode?: TrainingModeConfig;
+  kb?: KnowledgeBaseRuntime;
+  /** Directory where agent definitions are stored (for /import to write files) */
+  agentsDir?: string;
+  /** Training Copilot command handler — injected when COPILOT_ENABLED=true */
+  copilotHandler?: {
+    handleCommand(command: string, args: string, adminPhone: string, reply: (text: string) => Promise<void>): Promise<void>;
+  };
+  /** Training Copilot query tracker — called after each message is processed */
+  copilotTracker?: {
+    maybeTrack(event: any): Promise<void>;
+  };
+  /** Analytics collector — attaches to Operor events to record message analytics */
+  analyticsCollector?: {
+    attach(os: any): void;
+    detach?(os: any): void;
+  };
+  /** Analytics store — exposed so training commands (/stats) can query metrics */
+  analyticsStore?: any;
+  /** Skills module — injected from CLI to avoid circular dependency (core cannot depend on skills) */
+  skillsModule?: any;
+  /** Project root directory — used for mcp.json path resolution */
+  projectRoot?: string;
+}
+
+export interface AgentDefinition {
+  config: AgentConfig;
+  systemPrompt: string;
+  instructionsPath: string;
+}
+
+export interface AgentEvent {
+  type: 'message' | 'response' | 'tool_call' | 'error';
+  timestamp: number;
+  data: any;
+}

package/test/integration.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { Operor } from '../src/index.js';
+import { MockProvider } from '@operor/provider-mock';
+import { MockShopifySkill } from '@operor/testing';
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe('Operor Integration', () => {
+  let os: Operor;
+  let provider: MockProvider;
+  let shopify: MockShopifySkill;
+
+  let messagesProcessed = 0;
+  let toolCallsExecuted = 0;
+  let rulesTriggered = 0;
+
+  beforeAll(async () => {
+    os = new Operor({ debug: false, batchWindowMs: 0 });
+    provider = new MockProvider();
+    shopify = new MockShopifySkill();
+
+    await os.addProvider(provider);
+    await os.addSkill(shopify);
+
+    os.createAgent({
+      name: 'Order Tracker',
+      purpose: 'Track orders and handle issues',
+      personality: 'empathetic and solution-focused',
+      triggers: ['order_tracking', 'general'],
+
+      tools: [shopify.tools.get_order, shopify.tools.create_discount],
+
+      rules: [
+        {
+          name: 'Auto-compensation for delays',
+          condition: async (_context: any, toolResults: any[]) => {
+            const getOrderResult = toolResults.find((t) => t.name === 'get_order');
+            if (!getOrderResult || !getOrderResult.success) return false;
+            const order = getOrderResult.result;
+            return order.isDelayed && order.delayDays >= 2;
+          },
+          action: async () => {
+            rulesTriggered++;
+            const discount = await shopify.tools.create_discount.execute({
+              percent: 10,
+              validDays: 30,
+            });
+            return {
+              type: 'discount_created',
+              code: discount.code,
+              percent: discount.percent,
+              validDays: discount.validDays,
+            };
+          },
+        },
+      ],
+    });
+
+    // Wait for all 4 messages to be processed
+    const allProcessed = new Promise<void>((resolve) => {
+      os.on('message:processed', (event: any) => {
+        messagesProcessed++;
+        if (event.toolCalls) {
+          toolCallsExecuted += event.toolCalls.length;
+        }
+        if (messagesProcessed >= 4) resolve();
+      });
+    });
+
+    await os.start();
+
+    // Run test scenarios sequentially
+    provider.simulateIncomingMessage('+1', 'Where is my order #12345?');
+    await sleep(100);
+    provider.simulateIncomingMessage('+2', 'Check order #67890');
+    await sleep(100);
+    provider.simulateIncomingMessage('+3', 'Where is order #99999?');
+    await sleep(100);
+    provider.simulateIncomingMessage('+4', 'Hello!');
+
+    await allProcessed;
+  }, 15000);
+
+  afterAll(async () => {
+    await os.stop();
+  });
+
+  it('should process all 4 messages', () => {
+    expect(messagesProcessed).toBe(4);
+  });
+
+  it('should execute tool calls', () => {
+    expect(toolCallsExecuted).toBeGreaterThanOrEqual(2);
+  });
+
+  it('should trigger business rules for delayed orders', () => {
+    expect(rulesTriggered).toBeGreaterThanOrEqual(1);
+  });
+
+  it('should create discounts via business rules', () => {
+    expect(shopify.getDiscounts().length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('should register agents', () => {
+    expect(os.getAgents().length).toBe(1);
+  });
+
+  it('should stop cleanly', async () => {
+    await os.stop();
+    expect(os.isActive()).toBe(false);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "test", "**/*.test.ts"]
+}

package/tsdown.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['esm'],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  outExtensions: () => ({ js: '.js', dts: '.d.ts' }),
+});

package/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config';
+import { resolve } from 'path';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@operor/testing': resolve(__dirname, '../testing/src/index.ts'),
+    },
+  },
+});