@operor/core 0.1.0

package/src/__tests__/AgentLoader.test.ts

@@ -0,0 +1,315 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { AgentLoader } from '../AgentLoader.js';
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agentloader-'));
+});
+
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true });
+});
+
+/** Helper to write a file, creating parent dirs as needed. */
+async function writeFile(relativePath: string, content: string) {
+  const full = path.join(tmpDir, relativePath);
+  await fs.mkdir(path.dirname(full), { recursive: true });
+  await fs.writeFile(full, content, 'utf-8');
+}
+
+describe('AgentLoader', () => {
+  it('returns empty array when agents directory is empty', async () => {
+    await fs.mkdir(path.join(tmpDir, 'agents'), { recursive: true });
+    const loader = new AgentLoader(tmpDir);
+    const defs = await loader.loadAll();
+    expect(defs).toEqual([]);
+  });
+
+  it('skips directories without INSTRUCTIONS.md', async () => {
+    await writeFile('agents/broken/README.md', '# Nothing here');
+    const loader = new AgentLoader(tmpDir);
+    const defs = await loader.loadAll();
+    expect(defs).toEqual([]);
+  });
+
+  it('loads a minimal agent with only INSTRUCTIONS.md', async () => {
+    await writeFile(
+      'agents/support/INSTRUCTIONS.md',
+      [
+        '---',
+        'name: support',
+        'purpose: Handle support tickets',
+        'triggers:',
+        '  - help',
+        '  - support',
+        '---',
+        '',
+        '# Role',
+        '',
+        'You are a support agent.',
+      ].join('\n'),
+    );
+
+    const loader = new AgentLoader(tmpDir);
+    const defs = await loader.loadAll();
+
+    expect(defs).toHaveLength(1);
+    const def = defs[0];
+    expect(def.config.name).toBe('support');
+    expect(def.config.purpose).toBe('Handle support tickets');
+    expect(def.config.triggers).toEqual(['help', 'support']);
+    expect(def.instructionsPath).toBe(
+      path.join(tmpDir, 'agents', 'support', 'INSTRUCTIONS.md'),
+    );
+    expect(def.systemPrompt).toContain('## Instructions');
+    expect(def.systemPrompt).toContain('You are a support agent.');
+  });
+
+  it('loads agent with IDENTITY.md and SOUL.md', async () => {
+    await writeFile(
+      'agents/sales/INSTRUCTIONS.md',
+      [
+        '---',
+        'name: sales',
+        'channels:',
+        '  - whatsapp',
+        'skills:',
+        '  - shopify',
+        'knowledgeBase: true',
+        '---',
+        '',
+        'Sell products.',
+      ].join('\n'),
+    );
+    await writeFile('agents/sales/IDENTITY.md', 'I am SalesBot.');
+    await writeFile('agents/sales/SOUL.md', 'Be persuasive and friendly.');
+
+    const loader = new AgentLoader(tmpDir);
+    const defs = await loader.loadAll();
+
+    expect(defs).toHaveLength(1);
+    const def = defs[0];
+    expect(def.config.channels).toEqual(['whatsapp']);
+    expect(def.config.skills).toEqual(['shopify']);
+    expect(def.config.knowledgeBase).toBe(true);
+    expect(def.systemPrompt).toContain('## Identity');
+    expect(def.systemPrompt).toContain('I am SalesBot.');
+    expect(def.systemPrompt).toContain('## Soul');
+    expect(def.systemPrompt).toContain('Be persuasive and friendly.');
+    expect(def.systemPrompt).toContain('## Instructions');
+    expect(def.systemPrompt).toContain('Sell products.');
+  });
+
+  it('uses _defaults/SOUL.md when agent has no SOUL.md', async () => {
+    await writeFile(
+      'agents/faq/INSTRUCTIONS.md',
+      ['---', 'name: faq', '---', '', 'Answer questions.'].join('\n'),
+    );
+    await writeFile('agents/_defaults/SOUL.md', 'Default personality.');
+
+    const loader = new AgentLoader(tmpDir);
+    const defs = await loader.loadAll();
+
+    expect(defs).toHaveLength(1);
+    expect(defs[0].systemPrompt).toContain('Default personality.');
+  });
+
+  it('agent SOUL.md overrides _defaults/SOUL.md', async () => {
+    await writeFile(
+      'agents/vip/INSTRUCTIONS.md',
+      ['---', 'name: vip', '---', '', 'VIP only.'].join('\n'),
+    );
+    await writeFile('agents/_defaults/SOUL.md', 'Default soul.');
+    await writeFile('agents/vip/SOUL.md', 'VIP soul override.');
+
+    const loader = new AgentLoader(tmpDir);
+    const defs = await loader.loadAll();
+
+    expect(defs).toHaveLength(1);
+    expect(defs[0].systemPrompt).toContain('VIP soul override.');
+    expect(defs[0].systemPrompt).not.toContain('Default soul.');
+  });
+
+  it('includes USER.md in system prompt', async () => {
+    await writeFile(
+      'agents/bot/INSTRUCTIONS.md',
+      ['---', 'name: bot', '---', '', 'Do things.'].join('\n'),
+    );
+    await writeFile('USER.md', 'Business context: We sell coffee.');
+
+    const loader = new AgentLoader(tmpDir);
+    const defs = await loader.loadAll();
+
+    expect(defs).toHaveLength(1);
+    expect(defs[0].systemPrompt).toContain('## User Context');
+    expect(defs[0].systemPrompt).toContain('We sell coffee.');
+  });
+
+  it('parses priority, escalateTo, and guardrails from frontmatter', async () => {
+    await writeFile(
+      'agents/escalation/INSTRUCTIONS.md',
+      [
+        '---',
+        'name: escalation',
+        'priority: 10',
+        'escalateTo: human',
+        'guardrails:',
+        '  blockedTopics:',
+        '    - politics',
+        '  maxResponseLength: 500',
+        '---',
+        '',
+        'Handle escalations.',
+      ].join('\n'),
+    );
+
+    const loader = new AgentLoader(tmpDir);
+    const defs = await loader.loadAll();
+
+    expect(defs).toHaveLength(1);
+    const cfg = defs[0].config;
+    expect(cfg.priority).toBe(10);
+    expect(cfg.escalateTo).toBe('human');
+    expect(cfg.guardrails?.blockedTopics).toEqual(['politics']);
+    expect(cfg.guardrails?.maxResponseLength).toBe(500);
+  });
+
+  it('loadAgent returns null for non-existent agent', async () => {
+    await fs.mkdir(path.join(tmpDir, 'agents'), { recursive: true });
+    const loader = new AgentLoader(tmpDir);
+    const def = await loader.loadAgent('nonexistent');
+    expect(def).toBeNull();
+  });
+
+  it('loadAgent loads a specific agent by name', async () => {
+    await writeFile(
+      'agents/specific/INSTRUCTIONS.md',
+      ['---', 'name: specific', '---', '', 'Specific agent.'].join('\n'),
+    );
+
+    const loader = new AgentLoader(tmpDir);
+    const def = await loader.loadAgent('specific');
+
+    expect(def).not.toBeNull();
+    expect(def!.config.name).toBe('specific');
+  });
+
+  it('falls back to directory name when frontmatter name is missing', async () => {
+    await writeFile(
+      'agents/fallback-name/INSTRUCTIONS.md',
+      ['---', 'purpose: test', '---', '', 'Body.'].join('\n'),
+    );
+
+    const loader = new AgentLoader(tmpDir);
+    const def = await loader.loadAgent('fallback-name');
+
+    expect(def).not.toBeNull();
+    expect(def!.config.name).toBe('fallback-name');
+  });
+
+  it('loads multiple agents and skips _defaults directory', async () => {
+    await writeFile(
+      'agents/a/INSTRUCTIONS.md',
+      ['---', 'name: a', '---', '', 'Agent A.'].join('\n'),
+    );
+    await writeFile(
+      'agents/b/INSTRUCTIONS.md',
+      ['---', 'name: b', '---', '', 'Agent B.'].join('\n'),
+    );
+    await writeFile('agents/_defaults/SOUL.md', 'Default soul.');
+
+    const loader = new AgentLoader(tmpDir);
+    const defs = await loader.loadAll();
+
+    expect(defs).toHaveLength(2);
+    const names = defs.map((d) => d.config.name).sort();
+    expect(names).toEqual(['a', 'b']);
+  });
+
+  it('accepts custom agentsDir path', async () => {
+    const customDir = path.join(tmpDir, 'custom-agents');
+    await writeFile(
+      'custom-agents/bot/INSTRUCTIONS.md',
+      ['---', 'name: bot', '---', '', 'Custom dir.'].join('\n'),
+    );
+
+    const loader = new AgentLoader(tmpDir, customDir);
+    const defs = await loader.loadAll();
+
+    expect(defs).toHaveLength(1);
+    expect(defs[0].config.name).toBe('bot');
+  });
+
+  it('parses skills from frontmatter', async () => {
+    await writeFile(
+      'agents/mcp/INSTRUCTIONS.md',
+      [
+        '---',
+        'name: mcp-agent',
+        'skills:',
+        '  - shopify',
+        '  - search',
+        '---',
+        '',
+        'MCP agent.',
+      ].join('\n'),
+    );
+
+    const loader = new AgentLoader(tmpDir);
+    const defs = await loader.loadAll();
+
+    expect(defs).toHaveLength(1);
+    expect(defs[0].config.skills).toEqual(['shopify', 'search']);
+  });
+
+  it('ignores integrations field in frontmatter (removed)', async () => {
+    await writeFile(
+      'agents/legacy/INSTRUCTIONS.md',
+      [
+        '---',
+        'name: legacy',
+        'integrations:',
+        '  - shopify',
+        '---',
+        '',
+        'Legacy agent.',
+      ].join('\n'),
+    );
+
+    const loader = new AgentLoader(tmpDir);
+    const defs = await loader.loadAll();
+
+    expect(defs).toHaveLength(1);
+    expect(defs[0].config.skills).toBeUndefined();
+  });
+
+  it('builds system prompt with correct section ordering', async () => {
+    await writeFile(
+      'agents/ordered/INSTRUCTIONS.md',
+      ['---', 'name: ordered', '---', '', 'Instructions body.'].join('\n'),
+    );
+    await writeFile('agents/ordered/IDENTITY.md', 'Identity section.');
+    await writeFile('agents/ordered/SOUL.md', 'Soul section.');
+    await writeFile('USER.md', 'User context section.');
+
+    const loader = new AgentLoader(tmpDir);
+    const def = await loader.loadAgent('ordered');
+
+    expect(def).not.toBeNull();
+    const prompt = def!.systemPrompt;
+
+    // Verify ordering: Identity -> Soul -> Instructions -> User Context
+    const identityIdx = prompt.indexOf('## Identity');
+    const soulIdx = prompt.indexOf('## Soul');
+    const instructionsIdx = prompt.indexOf('## Instructions');
+    const userCtxIdx = prompt.indexOf('## User Context');
+
+    expect(identityIdx).toBeLessThan(soulIdx);
+    expect(soulIdx).toBeLessThan(instructionsIdx);
+    expect(instructionsIdx).toBeLessThan(userCtxIdx);
+  });
+});

package/src/__tests__/InMemoryStore.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { InMemoryStore } from '../InMemoryStore.js';
+
+describe('InMemoryStore — per-agent memory', () => {
+  let store: InMemoryStore;
+
+  beforeEach(() => {
+    store = new InMemoryStore();
+  });
+
+  it('stores and retrieves messages without agentId (global)', async () => {
+    await store.addMessage('c1', { role: 'user', content: 'hello', timestamp: 1 });
+    await store.addMessage('c1', { role: 'assistant', content: 'hi', timestamp: 2 });
+
+    const history = await store.getHistory('c1');
+    expect(history).toHaveLength(2);
+    expect(history[0].content).toBe('hello');
+    expect(history[1].content).toBe('hi');
+  });
+
+  it('isolates messages by agentId', async () => {
+    await store.addMessage('c1', { role: 'user', content: 'sales question', timestamp: 1 }, 'sales');
+    await store.addMessage('c1', { role: 'user', content: 'support question', timestamp: 2 }, 'support');
+    await store.addMessage('c1', { role: 'user', content: 'global message', timestamp: 3 });
+
+    const salesHistory = await store.getHistory('c1', 50, 'sales');
+    const supportHistory = await store.getHistory('c1', 50, 'support');
+    const globalHistory = await store.getHistory('c1', 50);
+
+    expect(salesHistory).toHaveLength(1);
+    expect(salesHistory[0].content).toBe('sales question');
+
+    expect(supportHistory).toHaveLength(1);
+    expect(supportHistory[0].content).toBe('support question');
+
+    expect(globalHistory).toHaveLength(1);
+    expect(globalHistory[0].content).toBe('global message');
+  });
+
+  it('respects limit per agent scope', async () => {
+    for (let i = 0; i < 10; i++) {
+      await store.addMessage('c1', { role: 'user', content: `msg ${i}`, timestamp: i }, 'agent-a');
+    }
+
+    const limited = await store.getHistory('c1', 3, 'agent-a');
+    expect(limited).toHaveLength(3);
+    expect(limited[0].content).toBe('msg 7');
+    expect(limited[2].content).toBe('msg 9');
+  });
+
+  it('returns empty array for unknown agentId', async () => {
+    await store.addMessage('c1', { role: 'user', content: 'hello', timestamp: 1 }, 'sales');
+
+    const history = await store.getHistory('c1', 50, 'unknown-agent');
+    expect(history).toHaveLength(0);
+  });
+});

package/src/guardrails.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GuardrailEngine } from './Guardrails.js';
+import { Operor } from './Operor.js';
+import type { GuardrailConfig, IncomingMessage, MessageProvider, OutgoingMessage } from './types.js';
+import EventEmitter from 'eventemitter3';
+
+// --- GuardrailEngine tests ---
+
+describe('GuardrailEngine', () => {
+  let engine: GuardrailEngine;
+
+  beforeEach(() => {
+    engine = new GuardrailEngine();
+  });
+
+  describe('checkInput', () => {
+    it('allows messages with no blocked topics', () => {
+      const config: GuardrailConfig = { blockedTopics: ['politics'] };
+      const result = engine.checkInput('What is your return policy?', config);
+      expect(result.allowed).toBe(true);
+    });
+
+    it('blocks messages containing blocked topics (case-insensitive)', () => {
+      const config: GuardrailConfig = { blockedTopics: ['politics', 'religion'] };
+      const result = engine.checkInput('What do you think about POLITICS?', config);
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain('politics');
+    });
+
+    it('detects escalation triggers', () => {
+      const config: GuardrailConfig = { escalationTriggers: ['speak to a human', 'talk to manager'] };
+      const result = engine.checkInput('I want to speak to a human please', config);
+      expect(result.allowed).toBe(false);
+      expect(result.escalate).toBe(true);
+      expect(result.reason).toContain('speak to a human');
+    });
+
+    it('escalation takes priority over blocked topics', () => {
+      const config: GuardrailConfig = {
+        blockedTopics: ['complaint'],
+        escalationTriggers: ['speak to a human'],
+      };
+      const result = engine.checkInput('I have a complaint, speak to a human', config);
+      expect(result.escalate).toBe(true);
+    });
+
+    it('allows messages when config has no rules', () => {
+      const result = engine.checkInput('Hello there', {});
+      expect(result.allowed).toBe(true);
+    });
+  });
+
+  describe('checkOutput', () => {
+    it('allows responses within max length', () => {
+      const config: GuardrailConfig = { maxResponseLength: 100 };
+      const result = engine.checkOutput('Short response', config);
+      expect(result.allowed).toBe(true);
+    });
+
+    it('blocks responses exceeding max length', () => {
+      const config: GuardrailConfig = { maxResponseLength: 10 };
+      const result = engine.checkOutput('This response is way too long', config);
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain('max length');
+    });
+
+    it('blocks responses containing blocked topics', () => {
+      const config: GuardrailConfig = { blockedTopics: ['competitor'] };
+      const result = engine.checkOutput('You should try our competitor instead', config);
+      expect(result.allowed).toBe(false);
+      expect(result.reason).toContain('competitor');
+    });
+
+    it('allows responses when config has no rules', () => {
+      const result = engine.checkOutput('Any response', {});
+      expect(result.allowed).toBe(true);
+    });
+  });
+});
+
+// --- Training mode tests ---
+
+class TestMockProvider extends EventEmitter implements MessageProvider {
+  public readonly name = 'mock';
+  public sentMessages: { to: string; message: OutgoingMessage }[] = [];
+
+  async connect(): Promise<void> {}
+  async disconnect(): Promise<void> {}
+  async sendMessage(to: string, message: OutgoingMessage): Promise<void> {
+    this.sentMessages.push({ to, message });
+  }
+}
+
+describe('Operor Training Mode', () => {
+  let os: Operor;
+  let provider: TestMockProvider;
+
+  beforeEach(async () => {
+    provider = new TestMockProvider();
+    os = new Operor({
+      trainingMode: { enabled: true, whitelist: ['+1234567890'] },
+      batchWindowMs: 0, // no batching delay for tests
+    });
+    await os.addProvider(provider);
+    os.createAgent({ name: 'test-agent', triggers: ['*'] });
+    await os.start();
+  });
+
+  const simulateMessage = (from: string, text: string) => {
+    const message: IncomingMessage = {
+      id: `msg_${Date.now()}`,
+      from,
+      text,
+      timestamp: Date.now(),
+      channel: 'whatsapp',
+      provider: 'mock',
+    };
+    provider.emit('message', message);
+  };
+
+  it('emits training:command for whitelisted user sending /help', async () => {
+    const commandSpy = vi.fn();
+    os.on('training:command', commandSpy);
+
+    simulateMessage('+1234567890', '/help');
+
+    // Wait for batch processing (setTimeout 0 + async)
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(commandSpy).toHaveBeenCalledWith(
+      expect.objectContaining({ command: '/help' })
+    );
+  });
+
+  it('sends help text for /help command', async () => {
+    simulateMessage('+1234567890', '/help');
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(provider.sentMessages.length).toBeGreaterThanOrEqual(1);
+    const helpMsg = provider.sentMessages.find((m) =>
+      m.message.text.includes('Quick start:')
+    );
+    expect(helpMsg).toBeDefined();
+  });
+
+  it('emits training:command for /teach', async () => {
+    const commandSpy = vi.fn();
+    os.on('training:command', commandSpy);
+
+    simulateMessage('+1234567890', '/teach Our return policy is 30 days');
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(commandSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        command: '/teach',
+        args: ['Our', 'return', 'policy', 'is', '30', 'days'],
+      })
+    );
+  });
+
+  it('ignores training commands from non-whitelisted users', async () => {
+    const commandSpy = vi.fn();
+    os.on('training:command', commandSpy);
+
+    simulateMessage('+9999999999', '/help');
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(commandSpy).not.toHaveBeenCalled();
+  });
+
+  it('passes non-command messages through to normal processing', async () => {
+    const processedSpy = vi.fn();
+    os.on('message:processed', processedSpy);
+
+    simulateMessage('+1234567890', 'Hello, what is your return policy?');
+    await new Promise((r) => setTimeout(r, 50));
+
+    expect(processedSpy).toHaveBeenCalled();
+  });
+});

package/src/index.ts

@@ -0,0 +1,11 @@
+export { Operor } from './Operor.js';
+export { Agent } from './Agent.js';
+export { InMemoryStore } from './InMemoryStore.js';
+export { AgentLoader, buildSystemPrompt, readFileOrNull } from './AgentLoader.js';
+export { KeywordIntentClassifier } from './KeywordIntentClassifier.js';
+export { LLMIntentClassifier } from './LLMIntentClassifier.js';
+export { GuardrailEngine } from './Guardrails.js';
+export type { GuardrailCheckResult } from './Guardrails.js';
+export { AgentVersionStore } from './AgentVersionStore.js';
+export type { VersionSnapshot } from './AgentVersionStore.js';
+export * from './types.js';