opc-agent 1.4.0 → 2.0.0

package/src/tools/builtin/file.ts

@@ -0,0 +1,107 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { MCPTool, MCPToolResult } from '../mcp';
+import type { AgentContext } from '../../core/types';
+
+function resolveSafe(basePath: string, targetPath: string): string | null {
+  const resolved = path.resolve(basePath, targetPath);
+  if (!resolved.startsWith(path.resolve(basePath))) return null;
+  return resolved;
+}
+
+function searchFiles(dir: string, query: string, results: string[] = [], maxResults = 20): string[] {
+  if (results.length >= maxResults) return results;
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (results.length >= maxResults) break;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '.git') continue;
+        searchFiles(full, query, results, maxResults);
+      } else if (entry.isFile()) {
+        try {
+          const content = fs.readFileSync(full, 'utf-8');
+          const lines = content.split('\n');
+          for (let i = 0; i < lines.length; i++) {
+            if (lines[i].includes(query)) {
+              results.push(`${full}:${i + 1}: ${lines[i].trim()}`);
+              if (results.length >= maxResults) break;
+            }
+          }
+        } catch { /* skip binary/unreadable */ }
+      }
+    }
+  } catch { /* skip inaccessible dirs */ }
+  return results;
+}
+
+export const fileTool: MCPTool = {
+  name: 'file_operations',
+  description: 'Read, write, list, and search files in the workspace',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: ['read', 'write', 'list', 'search', 'exists'] },
+      path: { type: 'string' },
+      content: { type: 'string' },
+      query: { type: 'string' },
+    },
+    required: ['action'],
+  },
+  async execute(input: Record<string, unknown>, context?: AgentContext): Promise<MCPToolResult> {
+    const action = input.action as string;
+    const workspace = process.cwd();
+    const targetPath = input.path as string | undefined;
+
+    if (action === 'search') {
+      const query = input.query as string;
+      if (!query) return { content: 'query is required for search', isError: true };
+      const results = searchFiles(workspace, query);
+      return { content: results.length ? results.join('\n') : 'No matches found', isError: false };
+    }
+
+    if (action === 'list') {
+      const dir = targetPath ? resolveSafe(workspace, targetPath) : workspace;
+      if (!dir) return { content: 'Path outside workspace', isError: true };
+      try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        const listing = entries.map(e => `${e.isDirectory() ? '[DIR] ' : ''}${e.name}`).join('\n');
+        return { content: listing || '(empty directory)', isError: false };
+      } catch (err) {
+        return { content: `Error listing directory: ${err instanceof Error ? err.message : String(err)}`, isError: true };
+      }
+    }
+
+    if (!targetPath) return { content: 'path is required', isError: true };
+    const resolved = resolveSafe(workspace, targetPath);
+    if (!resolved) return { content: 'Path outside workspace', isError: true };
+
+    switch (action) {
+      case 'read': {
+        try {
+          const content = fs.readFileSync(resolved, 'utf-8');
+          return { content: content.slice(0, 50000), isError: false };
+        } catch (err) {
+          return { content: `Error reading file: ${err instanceof Error ? err.message : String(err)}`, isError: true };
+        }
+      }
+      case 'write': {
+        const content = input.content as string;
+        if (content === undefined) return { content: 'content is required for write', isError: true };
+        try {
+          fs.mkdirSync(path.dirname(resolved), { recursive: true });
+          fs.writeFileSync(resolved, content, 'utf-8');
+          return { content: `Written ${content.length} bytes to ${targetPath}`, isError: false };
+        } catch (err) {
+          return { content: `Error writing file: ${err instanceof Error ? err.message : String(err)}`, isError: true };
+        }
+      }
+      case 'exists': {
+        return { content: String(fs.existsSync(resolved)), isError: false };
+      }
+      default:
+        return { content: `Unknown action: ${action}`, isError: true };
+    }
+  },
+};

package/src/tools/builtin/index.ts

@@ -0,0 +1,28 @@
+import type { MCPTool } from '../mcp';
+import { fileTool } from './file';
+import { webTool } from './web';
+import { shellTool } from './shell';
+import { datetimeTool } from './datetime';
+
+export { fileTool, webTool, shellTool, datetimeTool };
+
+const ALL_BUILTIN_TOOLS: MCPTool[] = [fileTool, webTool, shellTool, datetimeTool];
+
+const BUILTIN_MAP = new Map<string, MCPTool>(
+  ALL_BUILTIN_TOOLS.map(t => [t.name, t])
+);
+
+/**
+ * Get all built-in tools.
+ */
+export function getBuiltinTools(): MCPTool[] {
+  return [...ALL_BUILTIN_TOOLS];
+}
+
+/**
+ * Get specific built-in tools by name. If no names given, returns all.
+ */
+export function getBuiltinToolsByName(names?: string[]): MCPTool[] {
+  if (!names || names.length === 0) return getBuiltinTools();
+  return names.map(n => BUILTIN_MAP.get(n)).filter((t): t is MCPTool => !!t);
+}

package/src/tools/builtin/shell.ts

@@ -0,0 +1,43 @@
+import { execSync } from 'child_process';
+import * as path from 'path';
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const shellTool: MCPTool = {
+  name: 'shell_exec',
+  description: 'Execute a shell command (sandboxed to workspace)',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      command: { type: 'string' },
+      timeout: { type: 'number', default: 30000 },
+    },
+    required: ['command'],
+  },
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const command = input.command as string;
+    const timeout = (input.timeout as number) || 30000;
+    const workspace = process.cwd();
+
+    // Block path traversal attempts
+    if (command.includes('..')) {
+      return { content: 'Commands with ".." are not allowed for security', isError: true };
+    }
+
+    try {
+      const output = execSync(command, {
+        cwd: workspace,
+        timeout,
+        encoding: 'utf-8',
+        maxBuffer: 1024 * 1024,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+      const result = (output || '').slice(0, 5000);
+      return { content: result || '(no output)', isError: false };
+    } catch (err: any) {
+      const stderr = err.stderr ? String(err.stderr).slice(0, 2500) : '';
+      const stdout = err.stdout ? String(err.stdout).slice(0, 2500) : '';
+      const output = [stdout, stderr].filter(Boolean).join('\n') || err.message;
+      return { content: `Command failed: ${output.slice(0, 5000)}`, isError: true };
+    }
+  },
+};

package/src/tools/builtin/web.ts

@@ -0,0 +1,35 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const webTool: MCPTool = {
+  name: 'web_fetch',
+  description: 'Fetch content from a URL',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      url: { type: 'string' },
+      method: { type: 'string', enum: ['GET', 'POST'], default: 'GET' },
+      maxLength: { type: 'number', default: 5000 },
+    },
+    required: ['url'],
+  },
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const url = input.url as string;
+    const method = (input.method as string) || 'GET';
+    const maxLength = (input.maxLength as number) || 5000;
+
+    try {
+      const response = await fetch(url, { method, signal: AbortSignal.timeout(15000) });
+      const text = await response.text();
+      const truncated = text.length > maxLength ? text.slice(0, maxLength) + '\n...[truncated]' : text;
+      return {
+        content: `Status: ${response.status}\n\n${truncated}`,
+        isError: false,
+      };
+    } catch (err) {
+      return {
+        content: `Fetch error: ${err instanceof Error ? err.message : String(err)}`,
+        isError: true,
+      };
+    }
+  },
+};

package/src/tools/mcp-client.ts

@@ -0,0 +1,131 @@
+import { spawn, type ChildProcess } from 'child_process';
+import type { MCPToolDefinition, MCPToolResult } from './mcp';
+
+export interface MCPServerConfig {
+  name: string;
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+
+export class MCPClient {
+  private process: ChildProcess | null = null;
+  private config: MCPServerConfig | null = null;
+  private nextId = 1;
+  private pending = new Map<number, { resolve: (v: any) => void; reject: (e: Error) => void }>();
+  private buffer = '';
+  private connected = false;
+
+  async connect(config: MCPServerConfig): Promise<void> {
+    this.config = config;
+    this.process = spawn(config.command, config.args ?? [], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, ...config.env },
+    });
+
+    this.process.stdout!.on('data', (data: Buffer) => {
+      this.buffer += data.toString();
+      this.processBuffer();
+    });
+
+    this.process.on('error', (err) => {
+      for (const [, p] of this.pending) p.reject(err);
+      this.pending.clear();
+    });
+
+    this.process.on('exit', () => {
+      this.connected = false;
+      for (const [, p] of this.pending) p.reject(new Error('MCP server exited'));
+      this.pending.clear();
+    });
+
+    // Send initialize
+    await this.sendRequest('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'opc-agent', version: '0.7.0' },
+    });
+
+    // Send initialized notification
+    this.sendNotification('notifications/initialized', {});
+    this.connected = true;
+  }
+
+  private processBuffer(): void {
+    const lines = this.buffer.split('\n');
+    this.buffer = lines.pop() ?? '';
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const msg = JSON.parse(trimmed);
+        if (msg.id !== undefined && this.pending.has(msg.id)) {
+          const p = this.pending.get(msg.id)!;
+          this.pending.delete(msg.id);
+          if (msg.error) {
+            p.reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+          } else {
+            p.resolve(msg.result);
+          }
+        }
+      } catch { /* skip non-JSON lines */ }
+    }
+  }
+
+  private sendRequest(method: string, params?: Record<string, unknown>): Promise<any> {
+    return new Promise((resolve, reject) => {
+      if (!this.process?.stdin?.writable) {
+        reject(new Error('MCP server not connected'));
+        return;
+      }
+      const id = this.nextId++;
+      this.pending.set(id, { resolve, reject });
+      const msg = JSON.stringify({ jsonrpc: '2.0', method, params: params ?? {}, id });
+      this.process.stdin.write(msg + '\n');
+
+      // Timeout after 30s
+      setTimeout(() => {
+        if (this.pending.has(id)) {
+          this.pending.delete(id);
+          reject(new Error(`MCP request timed out: ${method}`));
+        }
+      }, 30000);
+    });
+  }
+
+  private sendNotification(method: string, params: Record<string, unknown>): void {
+    if (!this.process?.stdin?.writable) return;
+    const msg = JSON.stringify({ jsonrpc: '2.0', method, params });
+    this.process.stdin.write(msg + '\n');
+  }
+
+  async listTools(): Promise<MCPToolDefinition[]> {
+    const result = await this.sendRequest('tools/list');
+    return (result.tools ?? []).map((t: any) => ({
+      name: t.name,
+      description: t.description ?? '',
+      inputSchema: t.inputSchema ?? {},
+    }));
+  }
+
+  async callTool(name: string, input: Record<string, unknown>): Promise<MCPToolResult> {
+    const result = await this.sendRequest('tools/call', { name, arguments: input });
+    const content = (result.content ?? [])
+      .map((c: any) => c.text ?? JSON.stringify(c))
+      .join('\n');
+    return { content, isError: result.isError ?? false };
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.process) {
+      this.process.kill();
+      this.process = null;
+    }
+    this.connected = false;
+    this.pending.clear();
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+}

package/tests/auto-learn.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { SkillLearner, skillToMarkdown, parseSkillMarkdown, type LearnedSkill } from '../src/skills/auto-learn';
+
+function makeSkill(overrides: Partial<LearnedSkill> = {}): LearnedSkill {
+  return {
+    name: 'test-skill',
+    description: 'A test skill',
+    trigger: 'deploy|deployment',
+    instructions: '1. Check env\n2. Run deploy\n3. Verify',
+    examples: ['deploy to production', 'run deployment'],
+    createdAt: new Date('2026-01-01T00:00:00Z'),
+    usageCount: 0,
+    version: 1,
+    ...overrides,
+  };
+}
+
+describe('SkillLearner', () => {
+  let tmpDir: string;
+  let learner: SkillLearner;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opc-skills-'));
+    learner = new SkillLearner(tmpDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('saveSkill / loadLearnedSkills', () => {
+    it('should save and load a skill', async () => {
+      const skill = makeSkill();
+      await learner.saveSkill(skill);
+
+      const loaded = await learner.loadLearnedSkills();
+      expect(loaded).toHaveLength(1);
+      expect(loaded[0].name).toBe('test-skill');
+      expect(loaded[0].description).toBe('A test skill');
+      expect(loaded[0].trigger).toBe('deploy|deployment');
+      expect(loaded[0].examples).toEqual(['deploy to production', 'run deployment']);
+    });
+
+    it('should create directory if not exists', async () => {
+      const nested = path.join(tmpDir, 'deep', 'nested');
+      const l = new SkillLearner(nested);
+      await l.saveSkill(makeSkill());
+      expect(fs.existsSync(path.join(nested, 'test-skill.md'))).toBe(true);
+    });
+
+    it('should return empty array for nonexistent dir', async () => {
+      const l = new SkillLearner(path.join(tmpDir, 'nope'));
+      const skills = await l.loadLearnedSkills();
+      expect(skills).toEqual([]);
+    });
+  });
+
+  describe('matchSkill', () => {
+    it('should match by regex pattern', async () => {
+      await learner.saveSkill(makeSkill({ trigger: 'deploy|deployment' }));
+      await learner.loadLearnedSkills();
+
+      expect(learner.matchSkill('please deploy to production')).not.toBeNull();
+      expect(learner.matchSkill('run deployment now')).not.toBeNull();
+      expect(learner.matchSkill('hello world')).toBeNull();
+    });
+
+    it('should match by keyword fallback for invalid regex', async () => {
+      // Use an actually invalid regex so the catch branch is triggered
+      await learner.saveSkill(makeSkill({ trigger: '(deploy[broken, kubernetes' }));
+      await learner.loadLearnedSkills();
+
+      expect(learner.matchSkill('kubernetes cluster')).not.toBeNull();
+      expect(learner.matchSkill('random text')).toBeNull();
+    });
+
+    it('should return null if not loaded', () => {
+      expect(learner.matchSkill('deploy')).toBeNull();
+    });
+  });
+
+  describe('skillToMarkdown / parseSkillMarkdown', () => {
+    it('should round-trip a skill through markdown', () => {
+      const skill = makeSkill();
+      const md = skillToMarkdown(skill);
+      const parsed = parseSkillMarkdown(md);
+
+      expect(parsed).not.toBeNull();
+      expect(parsed!.name).toBe(skill.name);
+      expect(parsed!.description).toBe(skill.description);
+      expect(parsed!.trigger).toBe(skill.trigger);
+      expect(parsed!.instructions).toBe(skill.instructions);
+      expect(parsed!.examples).toEqual(skill.examples);
+      expect(parsed!.version).toBe(1);
+      expect(parsed!.usageCount).toBe(0);
+    });
+
+    it('should return null for invalid markdown', () => {
+      expect(parseSkillMarkdown('just some text')).toBeNull();
+    });
+  });
+});

package/tests/builtin-tools.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtempSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { getBuiltinTools, getBuiltinToolsByName } from '../src/tools/builtin';
+import { fileTool, shellTool, datetimeTool } from '../src/tools/builtin';
+
+describe('getBuiltinTools', () => {
+  it('returns 4 tools', () => {
+    const tools = getBuiltinTools();
+    expect(tools).toHaveLength(4);
+    const names = tools.map(t => t.name);
+    expect(names).toContain('file_operations');
+    expect(names).toContain('web_fetch');
+    expect(names).toContain('shell_exec');
+    expect(names).toContain('datetime');
+  });
+
+  it('getBuiltinToolsByName filters correctly', () => {
+    const tools = getBuiltinToolsByName(['datetime', 'file_operations']);
+    expect(tools).toHaveLength(2);
+  });
+
+  it('getBuiltinToolsByName with no args returns all', () => {
+    expect(getBuiltinToolsByName()).toHaveLength(4);
+  });
+});
+
+describe('file_operations tool', () => {
+  // file tool resolves paths relative to cwd, so use relative paths from a temp dir
+  // Actually, it uses process.cwd() as workspace. Let's just test with paths relative to cwd.
+  const testFile = `tmp-test-${Date.now()}.txt`;
+
+  afterAll(() => {
+    try { require('fs').unlinkSync(testFile); } catch {}
+  });
+
+  it('write and read a file', async () => {
+    const writeRes = await fileTool.execute({ action: 'write', path: testFile, content: 'hello' });
+    expect(writeRes.isError).toBe(false);
+
+    const readRes = await fileTool.execute({ action: 'read', path: testFile });
+    expect(readRes.isError).toBe(false);
+    expect(readRes.content).toBe('hello');
+  });
+
+  it('list files', async () => {
+    const res = await fileTool.execute({ action: 'list', path: '.' });
+    expect(res.isError).toBe(false);
+    expect(res.content).toContain('package.json');
+  });
+
+  it('exists check', async () => {
+    const res = await fileTool.execute({ action: 'exists', path: testFile });
+    expect(res.content).toBe('true');
+
+    const res2 = await fileTool.execute({ action: 'exists', path: 'nope-does-not-exist.txt' });
+    expect(res2.content).toBe('false');
+  });
+
+  it('rejects path outside workspace', async () => {
+    const res = await fileTool.execute({ action: 'read', path: '../../etc/passwd' });
+    expect(res.isError).toBe(true);
+  });
+});
+
+describe('datetime tool', () => {
+  it('returns valid JSON with iso field', async () => {
+    const res = await datetimeTool.execute({});
+    expect(res.isError).toBe(false);
+    const parsed = JSON.parse(res.content);
+    expect(parsed.iso).toBeDefined();
+    expect(new Date(parsed.iso).toISOString()).toBe(parsed.iso);
+  });
+});
+
+describe('shell_exec tool', () => {
+  it('runs a command', async () => {
+    const res = await shellTool.execute({ command: 'echo hello' });
+    expect(res.isError).toBe(false);
+    expect(res.content).toContain('hello');
+  });
+});

package/tests/cli.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+
+describe('CLI: opc chat slash commands', () => {
+  // Test that slash commands are recognized patterns
+  const slashCommands = ['/help', '/quit', '/exit', '/clear', '/skills', '/memory', '/info'];
+
+  it('should define all expected slash commands', () => {
+    const cliSource = fs.readFileSync(path.join(__dirname, '..', 'src', 'cli.ts'), 'utf-8');
+    for (const cmd of slashCommands) {
+      expect(cliSource).toContain(`'${cmd}'`);
+    }
+  });
+
+  it('chat command should be registered', () => {
+    const cliSource = fs.readFileSync(path.join(__dirname, '..', 'src', 'cli.ts'), 'utf-8');
+    expect(cliSource).toContain(".command('chat')");
+    expect(cliSource).toContain('Interactive CLI chat with the agent');
+  });
+
+  it('init command should generate SOUL.md and CONTEXT.md', () => {
+    const cliSource = fs.readFileSync(path.join(__dirname, '..', 'src', 'cli.ts'), 'utf-8');
+    expect(cliSource).toContain("'SOUL.md'");
+    expect(cliSource).toContain("'CONTEXT.md'");
+    expect(cliSource).toContain('# Project Context');
+    expect(cliSource).toContain('Personality');
+  });
+
+  it('chat banner should include expected elements', () => {
+    const cliSource = fs.readFileSync(path.join(__dirname, '..', 'src', 'cli.ts'), 'utf-8');
+    expect(cliSource).toContain('OPC Agent — Interactive Chat');
+    expect(cliSource).toContain('/help for commands');
+    expect(cliSource).toContain('╔');
+    expect(cliSource).toContain('╚');
+  });
+
+  it('chat should load SOUL.md and CONTEXT.md', () => {
+    const cliSource = fs.readFileSync(path.join(__dirname, '..', 'src', 'cli.ts'), 'utf-8');
+    expect(cliSource).toContain("'SOUL.md'");
+    expect(cliSource).toContain("'CONTEXT.md'");
+    // Should prepend to system prompt
+    expect(cliSource).toContain('soulContent');
+    expect(cliSource).toContain('contextContent');
+  });
+});