opc-agent 0.2.0 → 0.4.0

package/src/templates/financial-advisor.ts

@@ -0,0 +1,60 @@
+import { BaseSkill } from '../skills/base';
+import type { AgentContext, Message, SkillResult } from '../core/types';
+import type { OADDocument } from '../schema/oad';
+
+export class BudgetAnalysisSkill extends BaseSkill {
+  name = 'budget-analysis';
+  description = 'Analyze budgets and expenses';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (lower.includes('budget') || lower.includes('expense') || lower.includes('cost')) {
+      return this.match('I can help analyze your budget. Please share your income and expense categories, and I\'ll provide insights on spending patterns and savings opportunities.', 0.8);
+    }
+    if (lower.includes('save') || lower.includes('saving')) {
+      return this.match('Common savings strategies: 50/30/20 rule (needs/wants/savings), automate transfers, review subscriptions, negotiate bills, and track daily spending.', 0.75);
+    }
+    return this.noMatch();
+  }
+}
+
+export class FinancialPlanningSkill extends BaseSkill {
+  name = 'financial-planning';
+  description = 'Help with financial planning and advice';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (lower.includes('invest') || lower.includes('portfolio')) {
+      return this.match('For investment planning, consider: risk tolerance, time horizon, diversification, asset allocation, and regular rebalancing. This is general guidance — consult a certified financial advisor for personalized advice.', 0.8);
+    }
+    if (lower.includes('retire') || lower.includes('pension')) {
+      return this.match('Retirement planning essentials: estimate target savings (25x annual expenses), maximize employer matching, consider tax-advantaged accounts, and start early for compound growth.', 0.8);
+    }
+    return this.noMatch();
+  }
+}
+
+export function createFinancialAdvisorConfig(): OADDocument {
+  return {
+    apiVersion: 'opc/v1',
+    kind: 'Agent',
+    metadata: {
+      name: 'financial-advisor',
+      version: '1.0.0',
+      description: 'AI Financial Advisor - budget analysis, expense tracking, financial planning',
+      author: 'OPC',
+      license: 'Apache-2.0',
+    },
+    spec: {
+      model: 'deepseek-chat',
+      systemPrompt: 'You are a financial advisor AI. Help users with budget analysis, expense tracking, and financial planning. Always recommend consulting a certified financial advisor for binding decisions.',
+      skills: [
+        { name: 'budget-analysis', description: 'Analyze budgets and expenses' },
+        { name: 'financial-planning', description: 'Financial planning advice' },
+      ],
+      channels: [{ type: 'web', port: 3000 }],
+      memory: { shortTerm: true, longTerm: false },
+      streaming: false,
+    },
+  };
+}

package/src/templates/hr-recruiter.ts

@@ -0,0 +1,58 @@
+import { BaseSkill } from '../skills/base';
+import type { AgentContext, Message, SkillResult } from '../core/types';
+
+
+export class ResumeScreeningSkill extends BaseSkill {
+  name = 'resume-screening';
+  description = 'Screen resumes against job requirements';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (lower.includes('resume') || lower.includes('cv') || lower.includes('candidate')) {
+      return this.match(
+        'I can help screen resumes. Please share the candidate\'s resume and the job requirements, and I\'ll provide an analysis.',
+        0.8,
+      );
+    }
+    return this.noMatch();
+  }
+}
+
+export class InterviewSchedulingSkill extends BaseSkill {
+  name = 'interview-scheduling';
+  description = 'Help schedule interviews with candidates';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (lower.includes('schedule') || lower.includes('interview') || lower.includes('calendar')) {
+      return this.match(
+        'I can help schedule interviews. Please provide the candidate name, preferred dates, and interview format (phone/video/onsite).',
+        0.8,
+      );
+    }
+    return this.noMatch();
+  }
+}
+
+export function createHRRecruiterConfig() {
+  return {
+    apiVersion: 'opc/v1',
+    kind: 'Agent',
+    metadata: {
+      name: 'hr-recruiter',
+      version: '1.0.0',
+      description: 'HR Recruiter — resume screening, interview scheduling, candidate Q&A',
+      author: 'Deepleaper',
+      license: 'Apache-2.0',
+    },
+    spec: {
+      model: 'deepseek-chat',
+      systemPrompt: 'You are an HR recruiter assistant. Help with resume screening, interview scheduling, and answering candidate questions. Be professional and friendly.',
+      skills: [
+        { name: 'resume-screening', description: 'Screen resumes' },
+        { name: 'interview-scheduling', description: 'Schedule interviews' },
+      ],
+      channels: [{ type: 'web', port: 3000 }],
+    },
+  };
+}

package/src/templates/legal-assistant.ts

@@ -0,0 +1,71 @@
+import { BaseSkill } from '../skills/base';
+import type { AgentContext, Message, SkillResult } from '../core/types';
+import type { OADDocument } from '../schema/oad';
+
+const LEGAL_TERMS: Record<string, string> = {
+  'force majeure': 'A clause that frees parties from obligations due to extraordinary events.',
+  'indemnification': 'One party agrees to compensate the other for certain damages or losses.',
+  'limitation of liability': 'A cap on the amount one party can claim from the other.',
+  'non-compete': 'Restricts a party from competing within a specified scope and timeframe.',
+  'confidentiality': 'Obligations to keep certain information private.',
+  'termination': 'Conditions under which the agreement may be ended.',
+};
+
+export class ContractReviewSkill extends BaseSkill {
+  name = 'contract-review';
+  description = 'Review contracts and identify key clauses';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    for (const [term, explanation] of Object.entries(LEGAL_TERMS)) {
+      if (lower.includes(term)) {
+        return this.match(`📋 **${term.toUpperCase()}**: ${explanation}`, 0.85);
+      }
+    }
+    if (lower.includes('review') || lower.includes('contract')) {
+      return this.match('I can review contracts for key clauses like force majeure, indemnification, limitation of liability, non-compete, confidentiality, and termination provisions.', 0.7);
+    }
+    return this.noMatch();
+  }
+}
+
+export class ComplianceCheckSkill extends BaseSkill {
+  name = 'compliance-check';
+  description = 'Check compliance with regulations';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (lower.includes('gdpr') || lower.includes('privacy')) {
+      return this.match('GDPR compliance requires: data minimization, consent mechanisms, right to erasure, data protection officer, and breach notification within 72 hours.', 0.9);
+    }
+    if (lower.includes('compliance') || lower.includes('regulation')) {
+      return this.match('I can check compliance with GDPR, CCPA, SOX, HIPAA, and other major regulations. Please specify the regulation and context.', 0.7);
+    }
+    return this.noMatch();
+  }
+}
+
+export function createLegalAssistantConfig(): OADDocument {
+  return {
+    apiVersion: 'opc/v1',
+    kind: 'Agent',
+    metadata: {
+      name: 'legal-assistant',
+      version: '1.0.0',
+      description: 'AI Legal Assistant - contract review, compliance checking, legal research',
+      author: 'OPC',
+      license: 'Apache-2.0',
+    },
+    spec: {
+      model: 'deepseek-chat',
+      systemPrompt: 'You are a legal assistant AI. Help users review contracts, check compliance, and research legal topics. Always recommend consulting a qualified attorney for binding decisions.',
+      skills: [
+        { name: 'contract-review', description: 'Review contracts and identify key clauses' },
+        { name: 'compliance-check', description: 'Check regulatory compliance' },
+      ],
+      channels: [{ type: 'web', port: 3000 }],
+      memory: { shortTerm: true, longTerm: false },
+      streaming: false,
+    },
+  };
+}

package/src/templates/project-manager.ts

@@ -0,0 +1,58 @@
+import { BaseSkill } from '../skills/base';
+import type { AgentContext, Message, SkillResult } from '../core/types';
+
+
+export class TaskTrackingSkill extends BaseSkill {
+  name = 'task-tracking';
+  description = 'Track project tasks and status';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (lower.includes('task') || lower.includes('todo') || lower.includes('progress')) {
+      return this.match(
+        'I can help track tasks. Tell me the task name, assignee, and deadline, and I\'ll add it to the tracker.',
+        0.8,
+      );
+    }
+    return this.noMatch();
+  }
+}
+
+export class MeetingNotesSkill extends BaseSkill {
+  name = 'meeting-notes';
+  description = 'Generate and manage meeting notes';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (lower.includes('meeting') || lower.includes('notes') || lower.includes('minutes')) {
+      return this.match(
+        'I can help with meeting notes. Share the meeting details and I\'ll create structured notes with action items.',
+        0.8,
+      );
+    }
+    return this.noMatch();
+  }
+}
+
+export function createProjectManagerConfig() {
+  return {
+    apiVersion: 'opc/v1',
+    kind: 'Agent',
+    metadata: {
+      name: 'project-manager',
+      version: '1.0.0',
+      description: 'Project Manager — task tracking, status updates, meeting notes',
+      author: 'Deepleaper',
+      license: 'Apache-2.0',
+    },
+    spec: {
+      model: 'deepseek-chat',
+      systemPrompt: 'You are a project management assistant. Help track tasks, provide status updates, and manage meeting notes. Be organized and action-oriented.',
+      skills: [
+        { name: 'task-tracking', description: 'Track tasks' },
+        { name: 'meeting-notes', description: 'Manage meeting notes' },
+      ],
+      channels: [{ type: 'web', port: 3000 }],
+    },
+  };
+}

package/src/tools/mcp.ts

@@ -0,0 +1,76 @@
+import type { AgentContext, Message } from '../core/types';
+
+/**
+ * MCP (Model Context Protocol) compatible tool interface.
+ * Tools follow the MCP standard format with JSON Schema input validation.
+ */
+export interface MCPToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>; // JSON Schema
+}
+
+export interface MCPToolResult {
+  content: string;
+  isError?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+export interface MCPTool extends MCPToolDefinition {
+  execute(input: Record<string, unknown>, context?: AgentContext): Promise<MCPToolResult>;
+}
+
+export class MCPToolRegistry {
+  private tools: Map<string, MCPTool> = new Map();
+
+  register(tool: MCPTool): void {
+    this.tools.set(tool.name, tool);
+  }
+
+  unregister(name: string): void {
+    this.tools.delete(name);
+  }
+
+  get(name: string): MCPTool | undefined {
+    return this.tools.get(name);
+  }
+
+  list(): MCPToolDefinition[] {
+    return Array.from(this.tools.values()).map(({ name, description, inputSchema }) => ({
+      name,
+      description,
+      inputSchema,
+    }));
+  }
+
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  async execute(name: string, input: Record<string, unknown>, context?: AgentContext): Promise<MCPToolResult> {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      return { content: `Tool '${name}' not found`, isError: true };
+    }
+    try {
+      return await tool.execute(input, context);
+    } catch (err) {
+      return {
+        content: `Tool execution error: ${err instanceof Error ? err.message : String(err)}`,
+        isError: true,
+      };
+    }
+  }
+}
+
+/**
+ * Create an MCP tool from a simple function.
+ */
+export function createMCPTool(
+  name: string,
+  description: string,
+  inputSchema: Record<string, unknown>,
+  executeFn: (input: Record<string, unknown>, context?: AgentContext) => Promise<MCPToolResult>,
+): MCPTool {
+  return { name, description, inputSchema, execute: executeFn };
+}

package/tests/a2a.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { AgentRegistry } from '../src/core/a2a';
+import { BaseAgent } from '../src/core/agent';
+import { InMemoryStore } from '../src/memory';
+
+function createTestAgent(name: string): BaseAgent {
+  const agent = new BaseAgent({ name, model: 'test', systemPrompt: `I am ${name}` }, new InMemoryStore());
+  return agent;
+}
+
+describe('AgentRegistry (A2A)', () => {
+  let registry: AgentRegistry;
+
+  beforeEach(() => {
+    registry = new AgentRegistry();
+  });
+
+  it('should register and discover agents', () => {
+    const agent = createTestAgent('agent-1');
+    registry.register(agent, [{ name: 'summarize', description: 'Summarize text' }]);
+    
+    const all = registry.discover();
+    expect(all).toHaveLength(1);
+    expect(all[0].agentName).toBe('agent-1');
+  });
+
+  it('should discover by capability', () => {
+    const a1 = createTestAgent('a1');
+    const a2 = createTestAgent('a2');
+    registry.register(a1, [{ name: 'summarize', description: 'Summarize' }]);
+    registry.register(a2, [{ name: 'translate', description: 'Translate' }]);
+
+    const found = registry.discover('translate');
+    expect(found).toHaveLength(1);
+    expect(found[0].agentName).toBe('a2');
+  });
+
+  it('should unregister agents', () => {
+    const agent = createTestAgent('temp');
+    registry.register(agent, []);
+    registry.unregister('temp');
+    expect(registry.discover()).toHaveLength(0);
+  });
+
+  it('should handle request to unknown agent', async () => {
+    const response = await registry.call('a1', 'unknown', 'test', 'hello');
+    expect(response.status).toBe('error');
+  });
+
+  it('should send A2A request and get response', async () => {
+    const agent = createTestAgent('responder');
+    await agent.init();
+    registry.register(agent, [{ name: 'chat', description: 'Chat' }]);
+
+    const response = await registry.call('caller', 'responder', 'chat', 'hello');
+    expect(response.status).toBe('success');
+    expect(response.payload).toBeDefined();
+  });
+
+  it('should get agent by name', () => {
+    const agent = createTestAgent('finder');
+    registry.register(agent, []);
+    expect(registry.getAgent('finder')).toBeDefined();
+    expect(registry.getAgent('none')).toBeUndefined();
+  });
+});

package/tests/analytics.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { Analytics } from '../src/analytics';
+
+describe('Analytics', () => {
+  it('should track messages', () => {
+    const analytics = new Analytics();
+    analytics.recordMessage(100);
+    analytics.recordMessage(200);
+    const snap = analytics.getSnapshot();
+    expect(snap.messagesProcessed).toBe(2);
+    expect(snap.avgResponseTimeMs).toBe(150);
+  });
+
+  it('should track skill usage', () => {
+    const analytics = new Analytics();
+    analytics.recordSkillUsage('faq');
+    analytics.recordSkillUsage('faq');
+    analytics.recordSkillUsage('handoff');
+    const snap = analytics.getSnapshot();
+    expect(snap.skillUsage['faq']).toBe(2);
+    expect(snap.skillUsage['handoff']).toBe(1);
+  });
+
+  it('should track errors', () => {
+    const analytics = new Analytics();
+    analytics.recordError();
+    analytics.recordError();
+    expect(analytics.getSnapshot().errorCount).toBe(2);
+  });
+
+  it('should track token usage', () => {
+    const analytics = new Analytics();
+    analytics.recordTokens(100, 50);
+    analytics.recordTokens(200, 100);
+    const snap = analytics.getSnapshot();
+    expect(snap.tokenUsage.input).toBe(300);
+    expect(snap.tokenUsage.output).toBe(150);
+    expect(snap.tokenUsage.total).toBe(450);
+  });
+
+  it('should reset analytics', () => {
+    const analytics = new Analytics();
+    analytics.recordMessage(100);
+    analytics.recordError();
+    analytics.reset();
+    const snap = analytics.getSnapshot();
+    expect(snap.messagesProcessed).toBe(0);
+    expect(snap.errorCount).toBe(0);
+  });
+});

package/tests/hitl.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { HITLManager } from '../src/core/hitl';
+
+describe('HITLManager', () => {
+  let hitl: HITLManager;
+
+  beforeEach(() => {
+    hitl = new HITLManager({
+      requireApproval: ['delete', 'deploy'],
+      defaultTimeoutMs: 500,
+      defaultAction: 'deny',
+    });
+  });
+
+  it('should check if action needs approval', () => {
+    expect(hitl.needsApproval('delete')).toBe(true);
+    expect(hitl.needsApproval('read')).toBe(false);
+  });
+
+  it('should approve via handler', async () => {
+    hitl.setHandler(async (req) => ({
+      requestId: req.id,
+      decision: 'approve',
+      respondedAt: Date.now(),
+      timedOut: false,
+    }));
+
+    const response = await hitl.requestApproval('delete', 'Delete record #123');
+    expect(response.decision).toBe('approve');
+    expect(response.timedOut).toBe(false);
+  });
+
+  it('should deny via handler', async () => {
+    hitl.setHandler(async (req) => ({
+      requestId: req.id,
+      decision: 'deny',
+      respondedAt: Date.now(),
+      timedOut: false,
+    }));
+
+    const response = await hitl.requestApproval('deploy', 'Deploy to production');
+    expect(response.decision).toBe('deny');
+  });
+
+  it('should timeout with default action', async () => {
+    // No handler, no manual response → timeout
+    const response = await hitl.requestApproval('delete', 'Test timeout');
+    expect(response.timedOut).toBe(true);
+    expect(response.decision).toBe('deny'); // default action
+  });
+
+  it('should handle manual respond', async () => {
+    const promise = hitl.requestApproval('delete', 'Manual test');
+    const pending = hitl.getPending();
+    expect(pending).toHaveLength(1);
+    
+    hitl.respond(pending[0].id, 'approve', 'admin');
+    const response = await promise;
+    expect(response.decision).toBe('approve');
+    expect(response.respondedBy).toBe('admin');
+  });
+
+  it('should return false for unknown respond', () => {
+    expect(hitl.respond('unknown-id', 'approve')).toBe(false);
+  });
+
+  it('should match wildcard approval', () => {
+    const wildcard = new HITLManager({ requireApproval: ['*'] });
+    expect(wildcard.needsApproval('anything')).toBe(true);
+  });
+});

package/tests/i18n.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from 'vitest';
+import { t, setLocale, getLocale, detectLocale, addMessages } from '../src/i18n';
+
+describe('i18n', () => {
+  it('should return English messages by default', () => {
+    setLocale('en');
+    expect(t('agent.greeting')).toBe('Hello! How can I help you?');
+  });
+
+  it('should return Chinese messages', () => {
+    setLocale('zh-CN');
+    expect(t('agent.greeting')).toBe('您好！有什么可以帮您的？');
+    setLocale('en'); // reset
+  });
+
+  it('should interpolate params', () => {
+    setLocale('en');
+    expect(t('agent.started', { name: 'TestBot' })).toBe('Agent "TestBot" started successfully');
+  });
+
+  it('should fall back to key if not found', () => {
+    expect(t('nonexistent.key')).toBe('nonexistent.key');
+  });
+
+  it('should get and set locale', () => {
+    setLocale('zh-CN');
+    expect(getLocale()).toBe('zh-CN');
+    setLocale('en');
+    expect(getLocale()).toBe('en');
+  });
+
+  it('should add custom messages', () => {
+    addMessages('en', { 'custom.key': 'Custom value' });
+    expect(t('custom.key')).toBe('Custom value');
+  });
+
+  it('should detect locale from environment', () => {
+    const locale = detectLocale();
+    expect(['en', 'zh-CN']).toContain(locale);
+  });
+});

package/tests/mcp.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { MCPToolRegistry, createMCPTool } from '../src/tools/mcp';
+
+describe('MCP Tool System', () => {
+  it('should register and list tools', () => {
+    const registry = new MCPToolRegistry();
+    const tool = createMCPTool('calculator', 'Basic calculator', {
+      type: 'object',
+      properties: { expression: { type: 'string' } },
+    }, async (input) => ({ content: `Result: ${input.expression}` }));
+
+    registry.register(tool);
+    expect(registry.has('calculator')).toBe(true);
+    expect(registry.list().length).toBe(1);
+    expect(registry.list()[0].name).toBe('calculator');
+  });
+
+  it('should execute a tool', async () => {
+    const registry = new MCPToolRegistry();
+    registry.register(createMCPTool('echo', 'Echo tool', {}, async (input) => ({
+      content: `Echo: ${input.text}`,
+    })));
+
+    const result = await registry.execute('echo', { text: 'hello' });
+    expect(result.content).toBe('Echo: hello');
+    expect(result.isError).toBeUndefined();
+  });
+
+  it('should return error for missing tool', async () => {
+    const registry = new MCPToolRegistry();
+    const result = await registry.execute('nonexistent', {});
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('not found');
+  });
+
+  it('should handle tool execution errors', async () => {
+    const registry = new MCPToolRegistry();
+    registry.register(createMCPTool('failing', 'Fails', {}, async () => {
+      throw new Error('boom');
+    }));
+
+    const result = await registry.execute('failing', {});
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('boom');
+  });
+
+  it('should unregister tools', () => {
+    const registry = new MCPToolRegistry();
+    registry.register(createMCPTool('temp', 'Temp', {}, async () => ({ content: '' })));
+    expect(registry.has('temp')).toBe(true);
+    registry.unregister('temp');
+    expect(registry.has('temp')).toBe(false);
+  });
+});