opc-agent 0.7.0 → 0.8.0

package/src/core/orchestrator.ts

@@ -0,0 +1,215 @@
+import { EventEmitter } from 'events';
+import type { AgentContext, Message } from './types';
+
+/**
+ * Multi-Agent Orchestrator — v0.8.0
+ * Routes messages to specialized sub-agents, supports parallel execution and handoffs.
+ */
+
+export interface AgentNode {
+  id: string;
+  name: string;
+  description: string;
+  /** Patterns or intents this agent handles */
+  routes: string[];
+  /** Function that processes a message and returns a response */
+  handler: (context: AgentContext, message: Message) => Promise<Message>;
+  /** Priority for routing conflicts (higher wins) */
+  priority?: number;
+}
+
+export interface OrchestratorWorkflow {
+  name: string;
+  description?: string;
+  /** Ordered list of agent IDs for sequential execution */
+  steps?: string[];
+  /** List of agent IDs for parallel execution */
+  parallel?: string[];
+  /** Router config: auto-route based on message content */
+  router?: {
+    agents: string[];
+    fallback?: string;
+  };
+}
+
+export interface HandoffRequest {
+  fromAgent: string;
+  toAgent: string;
+  context: AgentContext;
+  reason: string;
+}
+
+export interface OrchestratorConfig {
+  agents: AgentNode[];
+  workflows?: OrchestratorWorkflow[];
+  defaultWorkflow?: string;
+  maxParallel?: number;
+}
+
+export class Orchestrator extends EventEmitter {
+  private agents: Map<string, AgentNode> = new Map();
+  private workflows: Map<string, OrchestratorWorkflow> = new Map();
+  private defaultWorkflow?: string;
+  private maxParallel: number;
+
+  constructor(config: OrchestratorConfig) {
+    super();
+    this.maxParallel = config.maxParallel ?? 5;
+    this.defaultWorkflow = config.defaultWorkflow;
+
+    for (const agent of config.agents) {
+      this.agents.set(agent.id, agent);
+    }
+    for (const wf of config.workflows ?? []) {
+      this.workflows.set(wf.name, wf);
+    }
+  }
+
+  /** Register a new agent node */
+  registerAgent(agent: AgentNode): void {
+    this.agents.set(agent.id, agent);
+    this.emit('agent:registered', agent.id);
+  }
+
+  /** Unregister an agent */
+  unregisterAgent(id: string): void {
+    this.agents.delete(id);
+    this.emit('agent:unregistered', id);
+  }
+
+  /** Route a message to the best-matching agent */
+  route(message: Message): AgentNode | undefined {
+    const content = message.content.toLowerCase();
+    let bestMatch: AgentNode | undefined;
+    let bestPriority = -1;
+
+    for (const agent of this.agents.values()) {
+      for (const route of agent.routes) {
+        if (content.includes(route.toLowerCase()) || new RegExp(route, 'i').test(content)) {
+          const priority = agent.priority ?? 0;
+          if (priority > bestPriority) {
+            bestMatch = agent;
+            bestPriority = priority;
+          }
+          break;
+        }
+      }
+    }
+    return bestMatch;
+  }
+
+  /** Execute a single agent */
+  async executeAgent(agentId: string, context: AgentContext, message: Message): Promise<Message> {
+    const agent = this.agents.get(agentId);
+    if (!agent) throw new Error(`Agent not found: ${agentId}`);
+    this.emit('agent:execute', agentId, message);
+    const result = await agent.handler(context, message);
+    this.emit('agent:complete', agentId, result);
+    return result;
+  }
+
+  /** Run multiple agents in parallel */
+  async executeParallel(
+    agentIds: string[],
+    context: AgentContext,
+    message: Message
+  ): Promise<Map<string, Message>> {
+    const results = new Map<string, Message>();
+    const batches: string[][] = [];
+
+    // Batch by maxParallel
+    for (let i = 0; i < agentIds.length; i += this.maxParallel) {
+      batches.push(agentIds.slice(i, i + this.maxParallel));
+    }
+
+    for (const batch of batches) {
+      const promises = batch.map(async (id) => {
+        const result = await this.executeAgent(id, context, message);
+        results.set(id, result);
+      });
+      await Promise.all(promises);
+    }
+
+    return results;
+  }
+
+  /** Execute a named workflow */
+  async executeWorkflow(
+    workflowName: string,
+    context: AgentContext,
+    message: Message
+  ): Promise<Message[]> {
+    const wf = this.workflows.get(workflowName);
+    if (!wf) throw new Error(`Workflow not found: ${workflowName}`);
+
+    const results: Message[] = [];
+
+    // Sequential steps
+    if (wf.steps) {
+      let currentMessage = message;
+      for (const agentId of wf.steps) {
+        const result = await this.executeAgent(agentId, context, currentMessage);
+        results.push(result);
+        currentMessage = result; // chain output → next input
+      }
+    }
+
+    // Parallel execution
+    if (wf.parallel) {
+      const parallelResults = await this.executeParallel(wf.parallel, context, message);
+      results.push(...parallelResults.values());
+    }
+
+    // Router-based
+    if (wf.router) {
+      const matched = this.route(message);
+      const targetId = matched && wf.router.agents.includes(matched.id)
+        ? matched.id
+        : wf.router.fallback;
+      if (targetId) {
+        const result = await this.executeAgent(targetId, context, message);
+        results.push(result);
+      }
+    }
+
+    return results;
+  }
+
+  /** Hand off conversation from one agent to another */
+  async handoff(request: HandoffRequest): Promise<Message> {
+    this.emit('agent:handoff', request);
+    const { toAgent, context } = request;
+    const lastMessage = context.messages[context.messages.length - 1];
+    if (!lastMessage) throw new Error('No message in context for handoff');
+    return this.executeAgent(toAgent, context, lastMessage);
+  }
+
+  /** Process an incoming message using the default workflow or routing */
+  async process(context: AgentContext, message: Message): Promise<Message[]> {
+    if (this.defaultWorkflow) {
+      return this.executeWorkflow(this.defaultWorkflow, context, message);
+    }
+
+    // Fallback: route to single agent
+    const agent = this.route(message);
+    if (agent) {
+      const result = await this.executeAgent(agent.id, context, message);
+      return [result];
+    }
+
+    return [{
+      id: `orch-${Date.now()}`,
+      role: 'assistant',
+      content: 'No agent available to handle this request.',
+      timestamp: Date.now(),
+    }];
+  }
+
+  getAgents(): AgentNode[] {
+    return Array.from(this.agents.values());
+  }
+
+  getWorkflows(): OrchestratorWorkflow[] {
+    return Array.from(this.workflows.values());
+  }
+}

package/src/index.ts

@@ -58,6 +58,22 @@ export type { AgentManifest, PublishOptions, InstallOptions } from './marketplac
 // v0.7.0 modules
 export { createAuthMiddleware, getActiveSessions } from './core/auth';
 export type { AuthConfig, AuthSession } from './core/auth';
+// v0.8.0 modules
+export { Orchestrator } from './core/orchestrator';
+export type { AgentNode, OrchestratorWorkflow, OrchestratorConfig, HandoffRequest } from './core/orchestrator';
+export { AgentPipeline, compose } from './core/compose';
+export type { ComposableAgent, ComposeOptions } from './core/compose';
+export { EmailChannel } from './channels/email';
+export type { EmailChannelConfig, EmailMessage } from './channels/email';
+export { SlackChannel } from './channels/slack';
+export type { SlackChannelConfig, SlashCommandConfig, SlashCommandPayload } from './channels/slack';
+export { WeChatChannel } from './channels/wechat';
+export type { WeChatChannelConfig, WeChatMessage, TemplateMessageData } from './channels/wechat';
+export { CalculatorTool } from './tools/calculator';
+export { DateTimeTool } from './tools/datetime';
+export { JsonTransformTool } from './tools/json-transform';
+export { TextAnalysisTool } from './tools/text-analysis';
+
 export { HttpSkill } from './skills/http';
 export { WebhookTriggerSkill } from './skills/webhook-trigger';
 export type { WebhookTarget } from './skills/webhook-trigger';

package/src/tools/calculator.ts

@@ -0,0 +1,73 @@
+import type { MCPTool, MCPToolResult } from './mcp';
+
+/**
+ * Calculator Tool — v0.8.0
+ * Safe math expression evaluation as an LLM function tool.
+ */
+export const CalculatorTool: MCPTool = {
+  name: 'calculator',
+  description: 'Evaluate a mathematical expression. Supports basic arithmetic, powers, sqrt, abs, min, max, round, ceil, floor, PI, E.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      expression: {
+        type: 'string',
+        description: 'Mathematical expression to evaluate, e.g. "2 + 3 * 4" or "sqrt(144) + PI"',
+      },
+    },
+    required: ['expression'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const expr = String(input.expression ?? '');
+    try {
+      const result = safeEval(expr);
+      return { content: String(result) };
+    } catch (err) {
+      return { content: `Error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};
+
+/** Safe math evaluator — no eval(), no arbitrary code */
+function safeEval(expr: string): number {
+  // Whitelist: digits, operators, parens, dots, commas, spaces, and known functions
+  const sanitized = expr.replace(/\s+/g, '');
+  const allowed = /^[0-9+\-*/().,%^a-zA-Z_]+$/;
+  if (!allowed.test(sanitized)) {
+    throw new Error('Invalid characters in expression');
+  }
+
+  // Replace known math functions/constants
+  const prepared = sanitized
+    .replace(/\bPI\b/gi, String(Math.PI))
+    .replace(/\bE\b/g, String(Math.E))
+    .replace(/\bsqrt\b/gi, 'Math.sqrt')
+    .replace(/\babs\b/gi, 'Math.abs')
+    .replace(/\bmin\b/gi, 'Math.min')
+    .replace(/\bmax\b/gi, 'Math.max')
+    .replace(/\bround\b/gi, 'Math.round')
+    .replace(/\bceil\b/gi, 'Math.ceil')
+    .replace(/\bfloor\b/gi, 'Math.floor')
+    .replace(/\bpow\b/gi, 'Math.pow')
+    .replace(/\blog\b/gi, 'Math.log')
+    .replace(/\blog10\b/gi, 'Math.log10')
+    .replace(/\bsin\b/gi, 'Math.sin')
+    .replace(/\bcos\b/gi, 'Math.cos')
+    .replace(/\btan\b/gi, 'Math.tan')
+    .replace(/\^/g, '**');
+
+  // Block anything that isn't math
+  if (/[a-zA-Z_]/.test(prepared.replace(/Math\.\w+/g, ''))) {
+    throw new Error('Unsupported function or variable in expression');
+  }
+
+  // Use Function constructor with restricted scope
+  const fn = new Function('Math', `"use strict"; return (${prepared});`);
+  const result = fn(Math);
+
+  if (typeof result !== 'number' || !isFinite(result)) {
+    throw new Error('Expression did not evaluate to a finite number');
+  }
+  return result;
+}

package/src/tools/datetime.ts

@@ -0,0 +1,149 @@
+import type { MCPTool, MCPToolResult } from './mcp';
+
+/**
+ * DateTime Tool — v0.8.0
+ * Date/time operations as an LLM function tool.
+ */
+export const DateTimeTool: MCPTool = {
+  name: 'datetime',
+  description: 'Get current date/time, format dates, calculate date differences, or add/subtract time.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      operation: {
+        type: 'string',
+        enum: ['now', 'format', 'diff', 'add', 'parse'],
+        description: 'Operation to perform',
+      },
+      date: {
+        type: 'string',
+        description: 'Date string (ISO 8601 or common format)',
+      },
+      date2: {
+        type: 'string',
+        description: 'Second date for diff operation',
+      },
+      format: {
+        type: 'string',
+        description: 'Output format: iso, date, time, datetime, unix, relative',
+      },
+      amount: {
+        type: 'number',
+        description: 'Amount to add (can be negative)',
+      },
+      unit: {
+        type: 'string',
+        enum: ['milliseconds', 'seconds', 'minutes', 'hours', 'days', 'weeks', 'months', 'years'],
+        description: 'Unit for add operation',
+      },
+      timezone: {
+        type: 'string',
+        description: 'IANA timezone (e.g. Asia/Shanghai, America/New_York)',
+      },
+    },
+    required: ['operation'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    try {
+      const op = String(input.operation);
+      const tz = input.timezone as string | undefined;
+
+      switch (op) {
+        case 'now': {
+          const now = new Date();
+          const fmt = (input.format as string) ?? 'iso';
+          return { content: formatDate(now, fmt, tz) };
+        }
+
+        case 'format': {
+          const d = parseDate(input.date as string);
+          const fmt = (input.format as string) ?? 'iso';
+          return { content: formatDate(d, fmt, tz) };
+        }
+
+        case 'diff': {
+          const d1 = parseDate(input.date as string);
+          const d2 = input.date2 ? parseDate(input.date2 as string) : new Date();
+          const diffMs = d2.getTime() - d1.getTime();
+          const days = Math.floor(Math.abs(diffMs) / 86400000);
+          const hours = Math.floor((Math.abs(diffMs) % 86400000) / 3600000);
+          const mins = Math.floor((Math.abs(diffMs) % 3600000) / 60000);
+          const sign = diffMs < 0 ? '-' : '';
+          return {
+            content: JSON.stringify({
+              milliseconds: diffMs,
+              readable: `${sign}${days}d ${hours}h ${mins}m`,
+              days: diffMs / 86400000,
+            }),
+          };
+        }
+
+        case 'add': {
+          const d = input.date ? parseDate(input.date as string) : new Date();
+          const amount = Number(input.amount ?? 0);
+          const unit = String(input.unit ?? 'days');
+          const result = addTime(d, amount, unit);
+          const fmt = (input.format as string) ?? 'iso';
+          return { content: formatDate(result, fmt, tz) };
+        }
+
+        case 'parse': {
+          const d = parseDate(input.date as string);
+          return {
+            content: JSON.stringify({
+              iso: d.toISOString(),
+              unix: d.getTime(),
+              year: d.getFullYear(),
+              month: d.getMonth() + 1,
+              day: d.getDate(),
+              weekday: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'][d.getDay()],
+            }),
+          };
+        }
+
+        default:
+          return { content: `Unknown operation: ${op}`, isError: true };
+      }
+    } catch (err) {
+      return { content: `Error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};
+
+function parseDate(s: string): Date {
+  const d = new Date(s);
+  if (isNaN(d.getTime())) throw new Error(`Invalid date: ${s}`);
+  return d;
+}
+
+function formatDate(d: Date, fmt: string, tz?: string): string {
+  if (tz) {
+    const localeStr = d.toLocaleString('en-US', { timeZone: tz });
+    d = new Date(localeStr);
+  }
+  switch (fmt) {
+    case 'iso': return d.toISOString();
+    case 'date': return d.toISOString().split('T')[0];
+    case 'time': return d.toTimeString().split(' ')[0];
+    case 'datetime': return d.toISOString().replace('T', ' ').replace(/\.\d+Z$/, '');
+    case 'unix': return String(d.getTime());
+    default: return d.toISOString();
+  }
+}
+
+function addTime(d: Date, amount: number, unit: string): Date {
+  const result = new Date(d);
+  switch (unit) {
+    case 'milliseconds': result.setTime(result.getTime() + amount); break;
+    case 'seconds': result.setTime(result.getTime() + amount * 1000); break;
+    case 'minutes': result.setTime(result.getTime() + amount * 60000); break;
+    case 'hours': result.setTime(result.getTime() + amount * 3600000); break;
+    case 'days': result.setDate(result.getDate() + amount); break;
+    case 'weeks': result.setDate(result.getDate() + amount * 7); break;
+    case 'months': result.setMonth(result.getMonth() + amount); break;
+    case 'years': result.setFullYear(result.getFullYear() + amount); break;
+    default: throw new Error(`Unknown unit: ${unit}`);
+  }
+  return result;
+}

package/src/tools/json-transform.ts

@@ -0,0 +1,187 @@
+import type { MCPTool, MCPToolResult } from './mcp';
+
+/**
+ * JSON Transform Tool — v0.8.0
+ * Parse, query, and transform JSON data as an LLM function tool.
+ */
+export const JsonTransformTool: MCPTool = {
+  name: 'json_transform',
+  description: 'Parse, query (JSONPath-like), transform, flatten, or merge JSON data.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      operation: {
+        type: 'string',
+        enum: ['parse', 'query', 'flatten', 'unflatten', 'merge', 'pick', 'omit', 'sort', 'filter', 'map_keys'],
+        description: 'Operation to perform on the JSON data',
+      },
+      data: {
+        description: 'JSON string or object to operate on',
+      },
+      data2: {
+        description: 'Second JSON for merge operation',
+      },
+      path: {
+        type: 'string',
+        description: 'Dot-notation path for query (e.g. "users.0.name")',
+      },
+      keys: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Keys for pick/omit operations',
+      },
+      sortBy: {
+        type: 'string',
+        description: 'Key to sort array by',
+      },
+      order: {
+        type: 'string',
+        enum: ['asc', 'desc'],
+      },
+      filterKey: {
+        type: 'string',
+        description: 'Key to filter by',
+      },
+      filterValue: {
+        description: 'Value to match for filter',
+      },
+    },
+    required: ['operation', 'data'],
+  },
+
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    try {
+      const op = String(input.operation);
+      const data = typeof input.data === 'string' ? JSON.parse(input.data) : input.data;
+
+      switch (op) {
+        case 'parse':
+          return { content: JSON.stringify(data, null, 2) };
+
+        case 'query': {
+          const path = String(input.path ?? '');
+          const result = getByPath(data, path);
+          return { content: JSON.stringify(result, null, 2) };
+        }
+
+        case 'flatten':
+          return { content: JSON.stringify(flatten(data), null, 2) };
+
+        case 'unflatten':
+          return { content: JSON.stringify(unflatten(data as Record<string, unknown>), null, 2) };
+
+        case 'merge': {
+          const data2 = typeof input.data2 === 'string' ? JSON.parse(input.data2) : input.data2;
+          return { content: JSON.stringify(deepMerge(data, data2), null, 2) };
+        }
+
+        case 'pick': {
+          const keys = input.keys as string[] ?? [];
+          const result: Record<string, unknown> = {};
+          for (const k of keys) {
+            if (k in data) result[k] = data[k];
+          }
+          return { content: JSON.stringify(result, null, 2) };
+        }
+
+        case 'omit': {
+          const keys = new Set(input.keys as string[] ?? []);
+          const result: Record<string, unknown> = {};
+          for (const [k, v] of Object.entries(data)) {
+            if (!keys.has(k)) result[k] = v;
+          }
+          return { content: JSON.stringify(result, null, 2) };
+        }
+
+        case 'sort': {
+          if (!Array.isArray(data)) return { content: 'Data must be an array for sort', isError: true };
+          const sortBy = String(input.sortBy ?? '');
+          const order = input.order === 'desc' ? -1 : 1;
+          const sorted = [...data].sort((a, b) => {
+            const va = sortBy ? a[sortBy] : a;
+            const vb = sortBy ? b[sortBy] : b;
+            return va < vb ? -order : va > vb ? order : 0;
+          });
+          return { content: JSON.stringify(sorted, null, 2) };
+        }
+
+        case 'filter': {
+          if (!Array.isArray(data)) return { content: 'Data must be an array for filter', isError: true };
+          const fk = String(input.filterKey ?? '');
+          const fv = input.filterValue;
+          const filtered = data.filter((item) => item[fk] === fv);
+          return { content: JSON.stringify(filtered, null, 2) };
+        }
+
+        case 'map_keys': {
+          // Rename keys: path is "old:new,old2:new2"
+          const mapping = String(input.path ?? '').split(',').reduce((acc, pair) => {
+            const [old, nw] = pair.split(':');
+            if (old && nw) acc[old.trim()] = nw.trim();
+            return acc;
+          }, {} as Record<string, string>);
+          const result: Record<string, unknown> = {};
+          for (const [k, v] of Object.entries(data)) {
+            result[mapping[k] ?? k] = v;
+          }
+          return { content: JSON.stringify(result, null, 2) };
+        }
+
+        default:
+          return { content: `Unknown operation: ${op}`, isError: true };
+      }
+    } catch (err) {
+      return { content: `Error: ${(err as Error).message}`, isError: true };
+    }
+  },
+};
+
+function getByPath(obj: unknown, path: string): unknown {
+  return path.split('.').reduce((curr: any, key) => {
+    if (curr == null) return undefined;
+    const idx = Number(key);
+    return Number.isInteger(idx) && Array.isArray(curr) ? curr[idx] : curr[key];
+  }, obj);
+}
+
+function flatten(obj: unknown, prefix = ''): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+    for (const [k, v] of Object.entries(obj)) {
+      const key = prefix ? `${prefix}.${k}` : k;
+      if (v && typeof v === 'object' && !Array.isArray(v)) {
+        Object.assign(result, flatten(v, key));
+      } else {
+        result[key] = v;
+      }
+    }
+  }
+  return result;
+}
+
+function unflatten(obj: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const parts = key.split('.');
+    let curr: any = result;
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (!(parts[i] in curr)) curr[parts[i]] = {};
+      curr = curr[parts[i]];
+    }
+    curr[parts[parts.length - 1]] = value;
+  }
+  return result;
+}
+
+function deepMerge(a: any, b: any): any {
+  if (!b) return a;
+  const result = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    if (v && typeof v === 'object' && !Array.isArray(v) && result[k] && typeof result[k] === 'object') {
+      result[k] = deepMerge(result[k], v);
+    } else {
+      result[k] = v;
+    }
+  }
+  return result;
+}