opc-agent 3.0.1 → 4.0.1

package/src/tools/builtin/rl-tools.ts

@@ -0,0 +1,243 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+// In-memory storage fallback
+interface Trajectory {
+  id: string;
+  taskType: string;
+  actions: Array<{ action: string; timestamp: number; reward?: number }>;
+  outcome?: 'success' | 'partial' | 'failure';
+  totalReward: number;
+}
+
+interface PolicyEntry {
+  taskType: string;
+  preferredActions: string[];
+  weights: Record<string, number>;
+}
+
+const trajectories: Trajectory[] = [];
+const policies = new Map<string, PolicyEntry>();
+let currentEpisode: Trajectory | null = null;
+
+function getOrCreateEpisode(taskType: string): Trajectory {
+  if (!currentEpisode || currentEpisode.taskType !== taskType) {
+    currentEpisode = {
+      id: `ep_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      taskType,
+      actions: [],
+      totalReward: 0,
+    };
+    trajectories.push(currentEpisode);
+  }
+  return currentEpisode;
+}
+
+export const rlRecordTrajectory: MCPTool = {
+  name: 'rl_record_trajectory',
+  description: 'Record action sequences and outcomes for RL training',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      taskType: { type: 'string' },
+      action: { type: 'string' },
+      outcome: { type: 'string', enum: ['success', 'partial', 'failure'] },
+    },
+    required: ['taskType', 'action'],
+  },
+  async execute(input): Promise<MCPToolResult> {
+    const ep = getOrCreateEpisode(input.taskType as string);
+    ep.actions.push({ action: input.action as string, timestamp: Date.now() });
+    if (input.outcome) ep.outcome = input.outcome as Trajectory['outcome'];
+    return { content: JSON.stringify({ episodeId: ep.id, actionsRecorded: ep.actions.length }) };
+  },
+};
+
+export const rlEvaluateOutcome: MCPTool = {
+  name: 'rl_evaluate_outcome',
+  description: "Score an action's outcome (success/partial/failure)",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      episodeId: { type: 'string' },
+      outcome: { type: 'string', enum: ['success', 'partial', 'failure'] },
+    },
+    required: ['outcome'],
+  },
+  async execute(input): Promise<MCPToolResult> {
+    const ep = input.episodeId
+      ? trajectories.find(t => t.id === input.episodeId)
+      : currentEpisode;
+    if (!ep) return { content: 'No active episode found', isError: true };
+    ep.outcome = input.outcome as Trajectory['outcome'];
+    const score = ep.outcome === 'success' ? 1 : ep.outcome === 'partial' ? 0.5 : 0;
+    return { content: JSON.stringify({ episodeId: ep.id, outcome: ep.outcome, score }) };
+  },
+};
+
+export const rlGetBestStrategy: MCPTool = {
+  name: 'rl_get_best_strategy',
+  description: 'Retrieve best-performing strategy for a task type',
+  inputSchema: {
+    type: 'object',
+    properties: { taskType: { type: 'string' } },
+    required: ['taskType'],
+  },
+  async execute(input): Promise<MCPToolResult> {
+    const taskType = input.taskType as string;
+    const relevant = trajectories.filter(t => t.taskType === taskType && t.outcome === 'success');
+    if (relevant.length === 0) return { content: JSON.stringify({ strategy: null, message: 'No successful strategies found' }) };
+    const best = relevant.reduce((a, b) => a.totalReward >= b.totalReward ? a : b);
+    return { content: JSON.stringify({ strategy: best.actions.map(a => a.action), totalReward: best.totalReward }) };
+  },
+};
+
+export const rlCompareStrategies: MCPTool = {
+  name: 'rl_compare_strategies',
+  description: 'Compare multiple strategies by success rate',
+  inputSchema: {
+    type: 'object',
+    properties: { taskType: { type: 'string' } },
+    required: ['taskType'],
+  },
+  async execute(input): Promise<MCPToolResult> {
+    const taskType = input.taskType as string;
+    const relevant = trajectories.filter(t => t.taskType === taskType && t.outcome);
+    const total = relevant.length;
+    const successes = relevant.filter(t => t.outcome === 'success').length;
+    const partials = relevant.filter(t => t.outcome === 'partial').length;
+    const failures = relevant.filter(t => t.outcome === 'failure').length;
+    return {
+      content: JSON.stringify({
+        taskType, total, successRate: total ? successes / total : 0,
+        breakdown: { successes, partials, failures },
+      }),
+    };
+  },
+};
+
+export const rlGenerateTrainingData: MCPTool = {
+  name: 'rl_generate_training_data',
+  description: 'Export trajectories as fine-tuning JSONL',
+  inputSchema: {
+    type: 'object',
+    properties: { taskType: { type: 'string' }, minReward: { type: 'number' } },
+  },
+  async execute(input): Promise<MCPToolResult> {
+    let data = trajectories;
+    if (input.taskType) data = data.filter(t => t.taskType === input.taskType);
+    if (input.minReward != null) data = data.filter(t => t.totalReward >= (input.minReward as number));
+    const jsonl = data.map(t => JSON.stringify({
+      messages: [
+        { role: 'system', content: `Task: ${t.taskType}` },
+        ...t.actions.map(a => ({ role: 'assistant', content: a.action })),
+      ],
+      outcome: t.outcome,
+      reward: t.totalReward,
+    })).join('\n');
+    return { content: jsonl || '(no data)' };
+  },
+};
+
+export const rlRewardSignal: MCPTool = {
+  name: 'rl_reward_signal',
+  description: 'Record positive/negative reward for last action',
+  inputSchema: {
+    type: 'object',
+    properties: { reward: { type: 'number' }, reason: { type: 'string' } },
+    required: ['reward'],
+  },
+  async execute(input): Promise<MCPToolResult> {
+    if (!currentEpisode || currentEpisode.actions.length === 0) {
+      return { content: 'No current episode or actions to reward', isError: true };
+    }
+    const lastAction = currentEpisode.actions[currentEpisode.actions.length - 1];
+    lastAction.reward = input.reward as number;
+    currentEpisode.totalReward += input.reward as number;
+    return { content: JSON.stringify({ action: lastAction.action, reward: input.reward, totalReward: currentEpisode.totalReward }) };
+  },
+};
+
+export const rlExplorationSuggest: MCPTool = {
+  name: 'rl_exploration_suggest',
+  description: 'Suggest alternative approaches (exploration)',
+  inputSchema: {
+    type: 'object',
+    properties: { taskType: { type: 'string' }, currentAction: { type: 'string' } },
+    required: ['taskType'],
+  },
+  async execute(input): Promise<MCPToolResult> {
+    const taskType = input.taskType as string;
+    const allActions = new Set<string>();
+    trajectories.filter(t => t.taskType === taskType).forEach(t => t.actions.forEach(a => allActions.add(a.action)));
+    const suggestions = Array.from(allActions).filter(a => a !== input.currentAction).slice(0, 5);
+    if (suggestions.length === 0) {
+      return { content: JSON.stringify({ suggestions: [], message: 'No alternative actions found. Try a completely new approach.' }) };
+    }
+    return { content: JSON.stringify({ suggestions }) };
+  },
+};
+
+export const rlUpdatePolicy: MCPTool = {
+  name: 'rl_update_policy',
+  description: "Update agent's action preferences based on rewards",
+  inputSchema: {
+    type: 'object',
+    properties: { taskType: { type: 'string' }, action: { type: 'string' }, weight: { type: 'number' } },
+    required: ['taskType', 'action', 'weight'],
+  },
+  async execute(input): Promise<MCPToolResult> {
+    const taskType = input.taskType as string;
+    let policy = policies.get(taskType);
+    if (!policy) {
+      policy = { taskType, preferredActions: [], weights: {} };
+      policies.set(taskType, policy);
+    }
+    const action = input.action as string;
+    policy.weights[action] = (policy.weights[action] || 0) + (input.weight as number);
+    policy.preferredActions = Object.entries(policy.weights)
+      .sort(([, a], [, b]) => b - a)
+      .map(([k]) => k);
+    return { content: JSON.stringify({ taskType, preferredActions: policy.preferredActions.slice(0, 5), weights: policy.weights }) };
+  },
+};
+
+export const rlGetStatistics: MCPTool = {
+  name: 'rl_get_statistics',
+  description: 'Get success/failure stats by task type',
+  inputSchema: {
+    type: 'object',
+    properties: { taskType: { type: 'string' } },
+  },
+  async execute(input): Promise<MCPToolResult> {
+    let data = trajectories;
+    if (input.taskType) data = data.filter(t => t.taskType === input.taskType);
+    const stats: Record<string, { total: number; success: number; partial: number; failure: number; avgReward: number }> = {};
+    for (const t of data) {
+      if (!stats[t.taskType]) stats[t.taskType] = { total: 0, success: 0, partial: 0, failure: 0, avgReward: 0 };
+      const s = stats[t.taskType];
+      s.total++;
+      if (t.outcome === 'success') s.success++;
+      else if (t.outcome === 'partial') s.partial++;
+      else if (t.outcome === 'failure') s.failure++;
+      s.avgReward = (s.avgReward * (s.total - 1) + t.totalReward) / s.total;
+    }
+    return { content: JSON.stringify(stats) };
+  },
+};
+
+export const rlResetEpisode: MCPTool = {
+  name: 'rl_reset_episode',
+  description: 'Clear current episode state',
+  inputSchema: { type: 'object', properties: {} },
+  async execute(): Promise<MCPToolResult> {
+    const had = currentEpisode != null;
+    currentEpisode = null;
+    return { content: JSON.stringify({ reset: true, hadActiveEpisode: had }) };
+  },
+};
+
+export const rlTools: MCPTool[] = [
+  rlRecordTrajectory, rlEvaluateOutcome, rlGetBestStrategy, rlCompareStrategies,
+  rlGenerateTrainingData, rlRewardSignal, rlExplorationSuggest, rlUpdatePolicy,
+  rlGetStatistics, rlResetEpisode,
+];

package/src/tools/builtin/vision.ts

@@ -0,0 +1,64 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+import { VisionManager } from '../../core/vision';
+import type { ImageInput } from '../../core/vision';
+
+const manager = new VisionManager();
+
+export const visionAnalyzeTool: MCPTool = {
+  name: 'vision_analyze',
+  description: 'Analyze an image using vision AI. Provide image as URL or base64.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      image_url: { type: 'string', description: 'URL of the image to analyze' },
+      image_base64: { type: 'string', description: 'Base64-encoded image data' },
+      prompt: { type: 'string', description: 'Optional prompt for analysis' },
+    },
+  },
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const imgInput: ImageInput = input.image_url
+      ? { type: 'url', data: input.image_url as string }
+      : { type: 'base64', data: input.image_base64 as string };
+    const result = await manager.analyze(imgInput, input.prompt as string | undefined);
+    return { content: JSON.stringify(result) };
+  },
+};
+
+export const visionExtractTextTool: MCPTool = {
+  name: 'vision_extract_text',
+  description: 'Extract text (OCR) from an image.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      image_url: { type: 'string', description: 'URL of the image' },
+      image_base64: { type: 'string', description: 'Base64-encoded image data' },
+    },
+  },
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const imgInput: ImageInput = input.image_url
+      ? { type: 'url', data: input.image_url as string }
+      : { type: 'base64', data: input.image_base64 as string };
+    const text = await manager.extractText(imgInput);
+    return { content: text };
+  },
+};
+
+export const visionCompareTool: MCPTool = {
+  name: 'vision_compare',
+  description: 'Compare multiple images.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      image_urls: { type: 'array', items: { type: 'string' }, description: 'URLs of images to compare' },
+      prompt: { type: 'string', description: 'Optional comparison prompt' },
+    },
+  },
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const urls = input.image_urls as string[];
+    const images: ImageInput[] = urls.map(url => ({ type: 'url' as const, data: url }));
+    const result = await manager.compareImages(images, input.prompt as string | undefined);
+    return { content: result };
+  },
+};
+
+export const visionTools: MCPTool[] = [visionAnalyzeTool, visionExtractTextTool, visionCompareTool];

package/src/tools/builtin/web-search.ts

@@ -0,0 +1,126 @@
+/**
+ * Web Search & Read Built-in Tools - v0.10.0
+ * Registers web_search and web_read as agent-callable tools.
+ */
+
+import type { MCPTool, MCPToolResult } from '../mcp';
+import { webSearch, DEFAULT_SEARCH_CONFIG, type WebSearchConfig, type SearchEngine } from '../web-search';
+import { scrapeUrl } from '../web-scraper';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import * as os from 'os';
+
+function loadSearchConfig(): WebSearchConfig {
+  try {
+    const cfgPath = join(os.homedir(), '.opc', 'config.json');
+    if (existsSync(cfgPath)) {
+      const cfg = JSON.parse(readFileSync(cfgPath, 'utf-8'));
+      if (cfg.webSearch) {
+        return { ...DEFAULT_SEARCH_CONFIG, ...cfg.webSearch };
+      }
+    }
+  } catch { /* ignore */ }
+  return DEFAULT_SEARCH_CONFIG;
+}
+
+export const webSearchTool: MCPTool = {
+  name: 'web_search',
+  description: 'Search the internet for information. Returns titles, URLs, and snippets from search results. Use when you need current information or facts you\'re unsure about.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'Search query string',
+      },
+      maxResults: {
+        type: 'number',
+        description: 'Maximum number of results to return (default: 5)',
+      },
+      engine: {
+        type: 'string',
+        enum: ['duckduckgo', 'brave', 'searxng', 'google'],
+        description: 'Search engine to use (default: configured engine)',
+      },
+    },
+    required: ['query'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const query = String(input.query ?? '');
+    if (!query.trim()) {
+      return { content: 'Error: empty search query', isError: true };
+    }
+
+    const config = loadSearchConfig();
+    if (!config.enabled) {
+      return { content: 'Web search is disabled in settings.', isError: true };
+    }
+
+    try {
+      const results = await webSearch(query, config, {
+        maxResults: (input.maxResults as number) || 5,
+        engine: input.engine as SearchEngine | undefined,
+      });
+
+      if (results.length === 0) {
+        return { content: `No results found for: ${query}` };
+      }
+
+      const formatted = results.map((r, i) =>
+        `${i + 1}. **${r.title}**\n   ${r.url}\n   ${r.snippet}`
+      ).join('\n\n');
+
+      return {
+        content: `Search results for "${query}":\n\n${formatted}`,
+        metadata: { resultCount: results.length, query },
+      };
+    } catch (err) {
+      return {
+        content: `Search error: ${err instanceof Error ? err.message : String(err)}`,
+        isError: true,
+      };
+    }
+  },
+};
+
+export const webReadTool: MCPTool = {
+  name: 'web_read',
+  description: 'Read and extract the main content from a web page URL. Returns clean markdown text. Use to get detailed information from a specific page.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      url: {
+        type: 'string',
+        description: 'URL of the web page to read',
+      },
+      maxLength: {
+        type: 'number',
+        description: 'Maximum content length in characters (default: 5000)',
+      },
+    },
+    required: ['url'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const url = String(input.url ?? '');
+    if (!url.trim()) {
+      return { content: 'Error: empty URL', isError: true };
+    }
+
+    try {
+      const result = await scrapeUrl(url, (input.maxLength as number) || 5000);
+      return {
+        content: `# ${result.title}\n\nSource: ${result.url}\nWords: ${result.wordCount}\n\n---\n\n${result.content}`,
+        metadata: { title: result.title, url: result.url, wordCount: result.wordCount },
+      };
+    } catch (err) {
+      return {
+        content: `Scrape error: ${err instanceof Error ? err.message : String(err)}`,
+        isError: true,
+      };
+    }
+  },
+};
+
+export const webSearchTools: MCPTool[] = [webSearchTool, webReadTool];

package/src/tools/document-processor.ts

@@ -0,0 +1,213 @@
+/**
+ * Document Processor - Parse and chunk documents for knowledge learning
+ * Supports: PDF, TXT, MD, DOCX, CSV, JSON
+ */
+
+export interface DocumentChunk {
+  title: string;
+  content: string;
+  metadata: {
+    source: string;
+    format: string;
+    chunkIndex: number;
+    totalChunks?: number;
+    page?: number;
+  };
+}
+
+export interface ProcessedDocument {
+  id: string;
+  filename: string;
+  format: string;
+  size: number;
+  chunks: DocumentChunk[];
+  processedAt: string;
+}
+
+const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50MB
+const CHUNK_TARGET_CHARS = 2000; // ~500 tokens
+const CHUNK_MAX_CHARS = 4000; // ~1000 tokens
+
+export class DocumentProcessor {
+  /**
+   * Process a file buffer into chunks
+   */
+  async process(buffer: Buffer, filename: string): Promise<ProcessedDocument> {
+    if (buffer.length > MAX_FILE_SIZE) {
+      throw new Error(`File too large: ${(buffer.length / 1024 / 1024).toFixed(1)}MB (max 50MB)`);
+    }
+
+    const ext = filename.split('.').pop()?.toLowerCase() || '';
+    let rawText: string;
+
+    switch (ext) {
+      case 'pdf':
+        rawText = await this.parsePDF(buffer);
+        break;
+      case 'docx':
+        rawText = await this.parseDOCX(buffer);
+        break;
+      case 'csv':
+        rawText = this.parseCSV(buffer.toString('utf-8'));
+        break;
+      case 'json':
+        rawText = this.parseJSON(buffer.toString('utf-8'));
+        break;
+      case 'txt':
+      case 'md':
+      case 'markdown':
+        rawText = buffer.toString('utf-8');
+        break;
+      default:
+        // Try as plain text
+        rawText = buffer.toString('utf-8');
+    }
+
+    const chunks = this.chunkText(rawText, filename, ext);
+
+    return {
+      id: `doc-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      filename,
+      format: ext,
+      size: buffer.length,
+      chunks,
+      processedAt: new Date().toISOString(),
+    };
+  }
+
+  private async parsePDF(buffer: Buffer): Promise<string> {
+    try {
+      const pdfParse = require('pdf-parse');
+      const data = await pdfParse(buffer);
+      return data.text || '';
+    } catch (e: any) {
+      throw new Error(`PDF parse failed: ${e.message}`);
+    }
+  }
+
+  private async parseDOCX(buffer: Buffer): Promise<string> {
+    try {
+      const mammoth = require('mammoth');
+      const result = await mammoth.extractRawText({ buffer });
+      return result.value || '';
+    } catch (e: any) {
+      throw new Error(`DOCX parse failed: ${e.message}`);
+    }
+  }
+
+  private parseCSV(text: string): string {
+    const lines = text.split('\n').filter(l => l.trim());
+    if (lines.length === 0) return '';
+
+    const headers = lines[0].split(',').map(h => h.trim().replace(/^"|"$/g, ''));
+    const rows = lines.slice(1);
+
+    // Convert CSV to readable text
+    return rows.map((row, i) => {
+      const values = this.parseCSVLine(row);
+      const pairs = headers.map((h, j) => `${h}: ${values[j] || ''}`);
+      return `Record ${i + 1}:\n${pairs.join('\n')}`;
+    }).join('\n\n');
+  }
+
+  private parseCSVLine(line: string): string[] {
+    const result: string[] = [];
+    let current = '';
+    let inQuotes = false;
+    for (const ch of line) {
+      if (ch === '"') { inQuotes = !inQuotes; }
+      else if (ch === ',' && !inQuotes) { result.push(current.trim()); current = ''; }
+      else { current += ch; }
+    }
+    result.push(current.trim());
+    return result;
+  }
+
+  private parseJSON(text: string): string {
+    try {
+      const data = JSON.parse(text);
+      if (Array.isArray(data)) {
+        return data.map((item, i) => `Item ${i + 1}:\n${JSON.stringify(item, null, 2)}`).join('\n\n');
+      }
+      return JSON.stringify(data, null, 2);
+    } catch {
+      return text;
+    }
+  }
+
+  /**
+   * Smart chunking: split by headings/paragraphs, respecting size limits
+   */
+  private chunkText(text: string, filename: string, format: string): DocumentChunk[] {
+    if (!text.trim()) return [];
+
+    // Split by markdown headings or double newlines
+    const sections = text.split(/\n(?=#{1,3}\s)|(?:\n\s*\n)/).filter(s => s.trim());
+    const chunks: DocumentChunk[] = [];
+    let currentChunk = '';
+    let currentTitle = filename;
+
+    for (const section of sections) {
+      const headingMatch = section.match(/^(#{1,3})\s+(.+)/);
+      if (headingMatch) {
+        currentTitle = headingMatch[2].trim();
+      }
+
+      if (currentChunk.length + section.length > CHUNK_MAX_CHARS && currentChunk.length > 0) {
+        chunks.push({
+          title: currentTitle,
+          content: currentChunk.trim(),
+          metadata: { source: filename, format, chunkIndex: chunks.length },
+        });
+        currentChunk = '';
+      }
+
+      currentChunk += section + '\n\n';
+
+      if (currentChunk.length >= CHUNK_TARGET_CHARS) {
+        chunks.push({
+          title: currentTitle,
+          content: currentChunk.trim(),
+          metadata: { source: filename, format, chunkIndex: chunks.length },
+        });
+        currentChunk = '';
+      }
+    }
+
+    if (currentChunk.trim()) {
+      chunks.push({
+        title: currentTitle,
+        content: currentChunk.trim(),
+        metadata: { source: filename, format, chunkIndex: chunks.length },
+      });
+    }
+
+    // If we got no chunks from section splitting (e.g. dense text), force-split
+    if (chunks.length === 0 && text.trim()) {
+      const words = text.split(/\s+/);
+      let buf = '';
+      for (const w of words) {
+        if (buf.length + w.length + 1 > CHUNK_MAX_CHARS && buf) {
+          chunks.push({
+            title: filename,
+            content: buf.trim(),
+            metadata: { source: filename, format, chunkIndex: chunks.length },
+          });
+          buf = '';
+        }
+        buf += w + ' ';
+      }
+      if (buf.trim()) {
+        chunks.push({
+          title: filename,
+          content: buf.trim(),
+          metadata: { source: filename, format, chunkIndex: chunks.length },
+        });
+      }
+    }
+
+    // Set totalChunks
+    for (const c of chunks) c.metadata.totalChunks = chunks.length;
+    return chunks;
+  }
+}