@operor/cli 0.1.0

package/src/commands/chat.ts

@@ -0,0 +1,310 @@
+import fs from 'fs';
+import { Command } from 'commander';
+import * as clack from '@clack/prompts';
+import * as readline from 'node:readline';
+import type { Skill, Tool } from '@operor/core';
+import { readConfig, configExists } from '../config.js';
+import { applyLLMOverride } from './llm-override.js';
+
+interface ChatOptions {
+  message?: string;
+  debug?: boolean;
+  kb?: boolean;
+  tools?: boolean;
+}
+
+async function buildPipeline(opts: ChatOptions) {
+  const config = readConfig();
+
+  if (!config.LLM_PROVIDER || !config.LLM_API_KEY) {
+    clack.log.error('LLM_PROVIDER and LLM_API_KEY required. Run "operor setup" first.');
+    process.exit(1);
+  }
+
+  const { Operor, LLMIntentClassifier, AgentLoader } = await import('@operor/core');
+  const { AIProvider } = await import('@operor/llm');
+  const { MockProvider } = await import('@operor/provider-mock');
+
+  const llm = new AIProvider({
+    provider: config.LLM_PROVIDER as 'openai' | 'anthropic' | 'google' | 'groq' | 'ollama',
+    apiKey: config.LLM_API_KEY,
+    model: config.LLM_MODEL,
+  });
+
+  let intentClassifier: any;
+  if (config.INTENT_CLASSIFIER === 'llm') {
+    intentClassifier = new LLMIntentClassifier(llm);
+  }
+
+  let skillsModule: any;
+  try { skillsModule = await import('@operor/skills'); } catch {}
+
+  const os = new Operor({
+    debug: !!opts.debug,
+    ...(intentClassifier && { intentClassifier }),
+    ...(skillsModule && { skillsModule }),
+  });
+
+  const provider = new MockProvider();
+  os.addProvider(provider);
+
+  // Load MCP skills + tools
+  const skillInstances: Skill[] = [];
+
+  if (config.SKILLS_ENABLED !== 'false') {
+    try {
+      const { SkillManager, loadSkillsConfig } = await import('@operor/skills');
+      const skillsConfig = loadSkillsConfig();
+      const skillManager = new SkillManager();
+      const skills = await skillManager.initialize(skillsConfig);
+      for (const skill of skills) {
+        os.addSkill(skill);
+        skillInstances.push(skill);
+        if (opts.debug) clack.log.info(`[debug] MCP skill loaded: ${skill.name}`);
+      }
+    } catch (error: any) {
+      if (opts.debug) clack.log.warn(`[debug] MCP skills not available: ${error.message}`);
+    }
+  }
+
+  const allTools: Tool[] = opts.tools !== false
+    ? skillInstances.flatMap((skill) => Object.values(skill.tools))
+    : [];
+
+  // Helper: get prompt skill name+content for an agent (filtered by skills list)
+  const getPromptSkills = (agentSkillNames?: string[]): Array<{name: string, content: string}> => {
+    return skillInstances
+      .filter((s): s is any => typeof (s as any).getContent === 'function')
+      .filter((s) => !agentSkillNames || agentSkillNames.includes(s.name))
+      .map((s) => ({ name: s.name, content: (s as any).getContent() }));
+  };
+
+  // KB runtime (optional) — same pattern as start.ts
+  let kbRuntime: any;
+  let kbStore: any = null;
+  if (opts.kb !== false && config.KB_ENABLED === 'true') {
+    try {
+      const {
+        SQLiteKnowledgeStore,
+        EmbeddingService,
+        TextChunker,
+        IngestionPipeline,
+        RetrievalPipeline,
+        QueryRewriter,
+      } = await import('@operor/knowledge');
+
+      const embedder = new EmbeddingService({
+        provider: (config.KB_EMBEDDING_PROVIDER as any) || 'openai',
+        apiKey: config.KB_EMBEDDING_API_KEY || config.LLM_API_KEY,
+        model: config.KB_EMBEDDING_MODEL,
+      });
+
+      kbStore = new SQLiteKnowledgeStore(
+        config.KB_DB_PATH || './knowledge.db',
+        embedder.dimensions,
+      );
+      await kbStore.initialize();
+
+      // Setup optional LLM query rewriter
+      let queryRewriter: InstanceType<typeof QueryRewriter> | undefined;
+      try {
+        queryRewriter = new QueryRewriter({ model: llm.getModel() });
+      } catch { /* LLM not available for rewriting */ }
+
+      const retrieval = new RetrievalPipeline(kbStore, embedder, {
+        faqThreshold: 0.85,
+        queryRewriter,
+      });
+
+      kbRuntime = {
+        retrieve: async (query: string) => retrieval.retrieve(query),
+        getStats: async () => kbStore.getStats(),
+      };
+
+      if (opts.debug) clack.log.info('[debug] Knowledge Base loaded');
+    } catch (e: any) {
+      clack.log.warn(`Knowledge Base configured but failed to load: ${e?.message}. Continuing without KB.`);
+    }
+  }
+
+  // Check if agents/ directory exists for file-based agent definitions
+  const agentsDir = `${process.cwd()}/agents`;
+  const hasAgentsDir = fs.existsSync(agentsDir);
+
+  if (hasAgentsDir) {
+    // File-based agent definitions — same as start.ts
+    const loader = new AgentLoader(process.cwd());
+    const definitions = await loader.loadAll();
+
+    if (definitions.length === 0) {
+      clack.log.warn('agents/ directory found but no valid agent definitions. Falling back to default agent.');
+    } else {
+      for (const def of definitions) {
+        const agentTools: Tool[] = def.config.skills
+          ? skillInstances
+              .filter((skill) => def.config.skills!.includes(skill.name))
+              .flatMap((skill) => Object.values(skill.tools))
+          : allTools;
+
+        const agent = os.createAgent({
+          ...def.config,
+          tools: agentTools,
+        });
+
+        applyLLMOverride(agent, llm, agentTools, {
+          systemPrompt: def.systemPrompt,
+          kbRuntime,
+          useKB: def.config.knowledgeBase,
+          guardrails: def.config.guardrails,
+          promptSkills: getPromptSkills(def.config.skills),
+        });
+
+        if (opts.debug) {
+          clack.log.info(
+            `[debug] Loaded agent: ${def.config.name}` +
+            (def.config.skills ? ` (skills: ${def.config.skills.join(', ')})` : '') +
+            (def.config.knowledgeBase ? ' (KB)' : '')
+          );
+        }
+      }
+
+      if (opts.debug) clack.log.info(`[debug] Loaded ${definitions.length} agent(s) from agents/`);
+
+      // Wire up assistant message tracking
+      os.on('message:processed', (event) => {
+        os.addAssistantMessage(event.customer.id, event.response.text);
+        if (opts.debug) {
+          clack.log.info(`[debug] Agent: ${event.agent}, intent: ${event.intent?.name || 'default'}, ${event.duration}ms`);
+        }
+      });
+
+      return { os, provider, llm, kbStore };
+    }
+  }
+
+  // Fallback: single default agent (no agents/ directory or empty)
+  const agent = os.createAgent({
+    name: 'support',
+    purpose: 'Customer support agent',
+    personality: 'Friendly, helpful, and professional',
+    triggers: ['*'],
+    tools: allTools,
+    ...(kbRuntime && { knowledgeBase: true }),
+  });
+
+  applyLLMOverride(agent, llm, allTools, {
+    kbRuntime,
+    promptSkills: getPromptSkills(),
+  });
+
+  // Wire up assistant message tracking
+  os.on('message:processed', (event) => {
+    os.addAssistantMessage(event.customer.id, event.response.text);
+    if (opts.debug) {
+      clack.log.info(`[debug] Agent: ${event.agent}, intent: ${event.intent?.name || 'default'}, ${event.duration}ms`);
+    }
+  });
+
+  return { os, provider, llm, kbStore };
+}
+
+export function registerChatCommand(program: Command): void {
+  program
+    .command('chat')
+    .description('Chat with your agent (full pipeline REPL)')
+    .option('-m, --message <text>', 'One-shot mode: send a single message and exit')
+    .option('--debug', 'Show intent, agent selection, and KB retrieval details')
+    .option('--no-kb', 'Skip Knowledge Base context injection')
+    .option('--no-tools', 'Disable tool calling')
+    .action(async (opts: ChatOptions) => {
+      if (!configExists()) {
+        clack.log.error('No configuration found. Run "operor setup" first.');
+        process.exit(1);
+      }
+
+      clack.intro('Operor — Chat');
+
+      const spinner = clack.spinner();
+      spinner.start('Loading pipeline...');
+
+      let pipeline: Awaited<ReturnType<typeof buildPipeline>>;
+      try {
+        pipeline = await buildPipeline(opts);
+      } catch (error: any) {
+        spinner.stop('Failed to load pipeline');
+        clack.log.error(error.message);
+        process.exit(1);
+      }
+
+      const { os, provider, kbStore } = pipeline;
+      await os.start();
+      spinner.stop('Pipeline ready');
+
+      const cleanup = () => {
+        if (kbStore) kbStore.close();
+      };
+
+      if (opts.message) {
+        // One-shot mode
+        const responsePromise = new Promise<string>((resolve) => {
+          os.on('message:processed', (event) => {
+            resolve(event.response.text);
+          });
+        });
+
+        provider.simulateIncomingMessage('+cli-user', opts.message);
+        const response = await responsePromise;
+        console.log(response);
+        cleanup();
+        clack.outro('');
+        return;
+      }
+
+      // Interactive REPL
+      clack.log.info('Type your message and press Enter. Type "exit" or Ctrl+C to quit.\n');
+
+      const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+      });
+
+      const askQuestion = (): void => {
+        rl.question('You: ', async (input) => {
+          const trimmed = input.trim();
+          if (!trimmed || trimmed === 'exit' || trimmed === 'quit') {
+            rl.close();
+            cleanup();
+            clack.outro('Goodbye');
+            return;
+          }
+
+          const responsePromise = new Promise<string>((resolve) => {
+            const handler = (event: any) => {
+              os.removeListener('message:processed', handler);
+              resolve(event.response.text);
+            };
+            os.on('message:processed', handler);
+          });
+
+          provider.simulateIncomingMessage('+cli-user', trimmed);
+
+          try {
+            const response = await responsePromise;
+            console.log(`\nAgent: ${response}\n`);
+          } catch (error: any) {
+            console.log(`\nError: ${error.message}\n`);
+          }
+
+          askQuestion();
+        });
+      };
+
+      rl.on('close', () => {
+        cleanup();
+        clack.outro('Goodbye');
+        process.exit(0);
+      });
+
+      askQuestion();
+    });
+}

package/src/commands/config.ts

@@ -0,0 +1,34 @@
+import { readConfig, writeConfig, configExists } from '../config.js';
+
+export function showConfig(): void {
+  if (!configExists()) {
+    console.error('No configuration found. Run "operor setup" first.');
+    process.exit(1);
+  }
+  const config = readConfig();
+  for (const [key, value] of Object.entries(config)) {
+    const display = key.includes('KEY') || key.includes('TOKEN') || key.includes('SECRET')
+      ? maskValue(value || '')
+      : value;
+    console.log(`  ${key}=${display}`);
+  }
+}
+
+export function setConfigValue(key: string, value: string): void {
+  const config = readConfig();
+  config[key] = value;
+  writeConfig(config);
+  console.log(`  Set ${key}=${key.includes('KEY') ? maskValue(value) : value}`);
+}
+
+export function unsetConfigValue(key: string): void {
+  const config = readConfig();
+  delete config[key];
+  writeConfig(config);
+  console.log(`  Removed ${key}`);
+}
+
+function maskValue(val: string): string {
+  if (val.length <= 8) return '••••••••';
+  return val.slice(0, 4) + '••••' + val.slice(-4);
+}

package/src/commands/converse.ts

@@ -0,0 +1,182 @@
+import { readConfig } from '../config.js';
+import { formatTimestamp } from '../utils.js';
+
+export async function runConverse(options: {
+  scenario?: string;
+  file?: string;
+  turns?: number;
+  persona?: string;
+  verbose?: boolean;
+  json?: boolean;
+  real?: boolean;
+  allowWrites?: boolean;
+  dryRun?: boolean;
+}): Promise<void> {
+  const config = readConfig();
+  const { Operor } = await import('@operor/core');
+  const { MockProvider } = await import('@operor/provider-mock');
+  const {
+    MockShopifySkill,
+    CustomerSimulator,
+    ConversationEvaluator,
+    ConversationRunner,
+    ECOMMERCE_SCENARIOS,
+    SkillTestHarness,
+  } = await import('@operor/testing');
+
+  // Set up LLM if configured
+  let llm: any;
+  if (config.LLM_PROVIDER && config.LLM_API_KEY) {
+    const { AIProvider } = await import('@operor/llm');
+    llm = new AIProvider({
+      provider: config.LLM_PROVIDER as any,
+      apiKey: config.LLM_API_KEY,
+      model: config.LLM_MODEL,
+    });
+  }
+
+  // Determine which scenarios to run
+  let scenarios = [...ECOMMERCE_SCENARIOS];
+
+  if (options.file) {
+    const fs = await import('fs');
+    try {
+      const raw = fs.readFileSync(options.file, 'utf-8');
+      scenarios = JSON.parse(raw);
+    } catch (err) {
+      console.error(`Failed to load scenarios from ${options.file}:`, err);
+      process.exit(1);
+    }
+  }
+
+  if (options.scenario) {
+    const match = scenarios.filter(
+      (s) => s.name.toLowerCase().includes(options.scenario!.toLowerCase()) ||
+             s.id.toLowerCase().includes(options.scenario!.toLowerCase())
+    );
+    if (match.length === 0) {
+      console.error(`No scenario matching "${options.scenario}". Available:`);
+      scenarios.forEach((s) => console.error(`  - ${s.id}: ${s.name}`));
+      process.exit(1);
+    }
+    scenarios = match;
+  }
+
+  // Apply overrides
+  if (options.turns) {
+    scenarios = scenarios.map((s) => ({ ...s, maxTurns: options.turns! }));
+  }
+  if (options.persona) {
+    scenarios = scenarios.map((s) => ({ ...s, persona: options.persona! }));
+  }
+
+  // Set up Operor with mocks
+  const os = new Operor({ debug: false, batchWindowMs: 0 });
+  const provider = new MockProvider();
+  const shopify = new MockShopifySkill();
+
+  // Wrap skill with safety harness if --real or --dry-run
+  let skill: any = shopify;
+  if (options.real || options.dryRun) {
+    skill = new SkillTestHarness(shopify, {
+      allowWrites: options.allowWrites ?? false,
+      dryRun: options.dryRun ?? false,
+    });
+    await skill.authenticate();
+  }
+
+  await os.addProvider(provider);
+  await os.addSkill(skill);
+
+  const allTools = [shopify.tools.get_order, shopify.tools.create_discount, shopify.tools.search_products];
+
+  const agent = os.createAgent({
+    name: 'Test Agent',
+    purpose: 'Handle customer support conversations',
+    personality: 'empathetic and solution-focused',
+    triggers: ['order_tracking', 'general'],
+    tools: allTools,
+    rules: [{
+      name: 'Auto-compensation',
+      condition: async (_ctx: any, toolResults: any[]) => {
+        const order = toolResults.find((t) => t.name === 'get_order');
+        return order?.success && order.result?.isDelayed && order.result?.delayDays >= 2;
+      },
+      action: async () => {
+        const discount = await shopify.tools.create_discount.execute({ percent: 10, validDays: 30 });
+        return { type: 'discount_created', code: discount.code, percent: 10, validDays: 30 };
+      },
+    }],
+  });
+
+  // Set up Knowledge Base if enabled
+  let kbRuntime: any;
+  if (config.KB_ENABLED === 'true') {
+    try {
+      const { SQLiteKnowledgeStore, EmbeddingService, RetrievalPipeline } = await import('@operor/knowledge');
+      const embedder = new EmbeddingService({
+        provider: (config.KB_EMBEDDING_PROVIDER || config.LLM_PROVIDER) as any,
+        apiKey: config.KB_EMBEDDING_API_KEY || config.LLM_API_KEY || '',
+        model: config.KB_EMBEDDING_MODEL,
+      });
+      const kbStore = new SQLiteKnowledgeStore(config.KB_DB_PATH || './knowledge.db', embedder.dimensions);
+      await kbStore.initialize();
+      const retrieval = new RetrievalPipeline(kbStore, embedder);
+      kbRuntime = { retrieve: (q: string) => retrieval.retrieve(q) };
+      console.log('[Operor] 📚 Knowledge Base enabled for conversations');
+    } catch (kbError: any) {
+      console.warn('[Operor] ⚠️  Failed to initialize Knowledge Base:', kbError.message);
+    }
+  }
+
+  // Override agent.process with LLM-based implementation if LLM is configured
+  if (llm) {
+    const { applyLLMOverride } = await import('./llm-override.js');
+    applyLLMOverride(agent, llm, allTools, { kbRuntime });
+  }
+
+  await os.start();
+
+  // Create runner components with LLM if configured
+  const customerSimulator = new CustomerSimulator({ llmProvider: llm });
+  const conversationEvaluator = new ConversationEvaluator({ llmProvider: llm });
+  const runner = new ConversationRunner({
+    agentOS: os,
+    customerSimulator,
+    conversationEvaluator,
+    verbose: options.verbose ?? false,
+  });
+
+  if (!options.json) {
+    console.log(`\n  Running ${scenarios.length} conversation scenario(s)...\n`);
+  }
+
+  const results = await runner.runScenarios(scenarios);
+  await os.stop();
+
+  // Output results
+  if (options.json) {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    let passed = 0;
+    let failed = 0;
+
+    for (const r of results) {
+      const icon = r.passed ? '✓' : '✗';
+      const status = r.passed ? 'PASS' : 'FAIL';
+      console.log(`  ${icon} ${r.scenario.name} — ${status} (${r.turns.length} turns, ${r.duration}ms)`);
+
+      if (!r.passed && r.evaluation.feedback) {
+        console.log(`    ${r.evaluation.feedback}`);
+      }
+
+      if (r.passed) passed++;
+      else failed++;
+    }
+
+    console.log(`\n  Results: ${passed} passed, ${failed} failed out of ${results.length}`);
+    console.log(`  Status: ${failed === 0 ? '✓ ALL PASSED' : '✗ SOME FAILED'}\n`);
+  }
+
+  process.exit(results.every((r) => r.passed) ? 0 : 1);
+}

package/src/commands/doctor.ts

@@ -0,0 +1,154 @@
+import * as clack from '@clack/prompts';
+import { readConfig, configExists } from '../config.js';
+
+export async function runDoctor(): Promise<void> {
+  clack.intro('Operor Doctor');
+
+  if (!configExists()) {
+    clack.log.error('.env file not found. Run "operor setup" first.');
+    process.exit(1);
+  }
+
+  const config = readConfig();
+  let allPassed = true;
+
+  // 1. Check .env exists
+  clack.log.success('.env file found');
+
+  // 2. Validate LLM
+  if (config.LLM_PROVIDER && config.LLM_API_KEY) {
+    const spinner = clack.spinner();
+    spinner.start(`Testing ${config.LLM_PROVIDER} LLM connection...`);
+    try {
+      const { AIProvider } = await import('@operor/llm');
+      const llm = new AIProvider({
+        provider: config.LLM_PROVIDER as any,
+        apiKey: config.LLM_API_KEY,
+        model: config.LLM_MODEL,
+      });
+      await llm.complete([{ role: 'user', content: 'ping' }], { maxTokens: 5 });
+      spinner.stop(`${config.LLM_PROVIDER} LLM: OK`);
+    } catch (error: any) {
+      spinner.stop(`${config.LLM_PROVIDER} LLM: FAILED — ${error.message}`);
+      allPassed = false;
+    }
+  } else {
+    clack.log.warning('LLM not configured');
+    allPassed = false;
+  }
+
+  // 3. Validate MCP Skills
+  if (config.SKILLS_ENABLED !== 'false') {
+    const skillSpinner = clack.spinner();
+    skillSpinner.start('Checking MCP Skills...');
+    try {
+      const { loadSkillsConfig, SkillManager } = await import('@operor/skills');
+      const skillsConfig = loadSkillsConfig();
+      const enabledSkills = skillsConfig.skills.filter((s: any) => s.enabled !== false);
+
+      if (enabledSkills.length === 0) {
+        skillSpinner.stop('MCP Skills: No skills configured in mcp.json');
+      } else {
+        // Validate config only (don't start servers)
+        const errors: string[] = [];
+        for (const skill of enabledSkills) {
+          const error = SkillManager.validateConfig(skill);
+          if (error) errors.push(`${skill.name}: ${error}`);
+        }
+        if (errors.length > 0) {
+          skillSpinner.stop(`MCP Skills: ${errors.length} config error(s)`);
+          for (const err of errors) clack.log.warning(`  ${err}`);
+          allPassed = false;
+        } else {
+          skillSpinner.stop(`MCP Skills: ${enabledSkills.length} skill(s) configured`);
+        }
+      }
+    } catch (error: any) {
+      skillSpinner.stop('MCP Skills: Not available (mcp.json not found or @operor/skills not installed)');
+    }
+  }
+
+  // 4. Validate channel credentials
+  if (config.CHANNEL === 'telegram' && config.TELEGRAM_BOT_TOKEN) {
+    clack.log.success('Telegram bot token configured');
+  } else if (config.CHANNEL === 'wati') {
+    if (config.WATI_API_TOKEN && config.WATI_TENANT_ID) {
+      clack.log.success('WATI credentials configured');
+    } else {
+      clack.log.error('WATI: missing WATI_API_TOKEN or WATI_TENANT_ID');
+      allPassed = false;
+    }
+  }
+
+  // 5. Knowledge Base checks
+  if (config.KB_ENABLED === 'true') {
+    const kbSpinner = clack.spinner();
+    kbSpinner.start('Checking Knowledge Base...');
+    try {
+      // Check DB path is writable
+      const { writeFileSync, unlinkSync, existsSync } = await import('node:fs');
+      const { dirname } = await import('node:path');
+      const { mkdirSync } = await import('node:fs');
+      const dbPath = config.KB_DB_PATH || './knowledge.db';
+      const dir = dirname(dbPath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      const testFile = dbPath + '.write-test';
+      writeFileSync(testFile, '');
+      unlinkSync(testFile);
+
+      // Check embedding API key (unless ollama)
+      if (config.KB_EMBEDDING_PROVIDER !== 'ollama' && !config.KB_EMBEDDING_API_KEY) {
+        kbSpinner.stop('Knowledge Base: WARNING — no embedding API key set');
+        allPassed = false;
+      } else {
+        // Try loading sqlite-vec
+        try {
+          await import('@operor/knowledge');
+          kbSpinner.stop('Knowledge Base: OK');
+        } catch {
+          kbSpinner.stop('Knowledge Base: OK (config valid, @operor/knowledge not installed yet)');
+        }
+      }
+    } catch (error: any) {
+      kbSpinner.stop(`Knowledge Base: FAILED — ${error.message}`);
+      allPassed = false;
+    }
+  }
+
+  // 6. Analytics checks
+  if (config.ANALYTICS_ENABLED !== 'false') {
+    const analyticsSpinner = clack.spinner();
+    analyticsSpinner.start('Checking Analytics...');
+    try {
+      const { writeFileSync, unlinkSync, existsSync } = await import('node:fs');
+      const { dirname } = await import('node:path');
+      const { mkdirSync } = await import('node:fs');
+      const dbPath = config.ANALYTICS_DB_PATH || './analytics.db';
+      const dir = dirname(dbPath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      const testFile = dbPath + '.write-test';
+      writeFileSync(testFile, '');
+      unlinkSync(testFile);
+      analyticsSpinner.stop('Analytics: OK (DB path writable)');
+    } catch (error: any) {
+      analyticsSpinner.stop(`Analytics: FAILED — ${error.message}`);
+      allPassed = false;
+    }
+  }
+
+  // 7. Check Node.js version
+  const nodeVersion = process.versions.node;
+  const major = parseInt(nodeVersion.split('.')[0]);
+  if (major >= 18) {
+    clack.log.success(`Node.js ${nodeVersion}`);
+  } else {
+    clack.log.error(`Node.js ${nodeVersion} — requires >= 18`);
+    allPassed = false;
+  }
+
+  clack.outro(allPassed ? 'All checks passed!' : 'Some checks failed. Fix the issues above.');
+}