opc-agent 1.4.0 → 2.0.1

package/src/telemetry/index.ts

@@ -0,0 +1,324 @@
+/**
+ * OPC Agent Telemetry — Lightweight OTel-compatible tracing & metrics.
+ * Zero external dependencies. Produces OTLP-compatible JSON.
+ */
+
+import * as fs from 'fs';
+import * as crypto from 'crypto';
+
+// ─── Types ───────────────────────────────────────────────────
+
+export interface Span {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  name: string;
+  kind: 'internal' | 'client' | 'server';
+  startTime: number;    // epoch ms
+  endTime?: number;
+  status: 'ok' | 'error' | 'unset';
+  attributes: Record<string, string | number | boolean>;
+  events: SpanEvent[];
+}
+
+export interface SpanEvent {
+  name: string;
+  timestamp: number;
+  attributes?: Record<string, string | number | boolean>;
+}
+
+export interface Metric {
+  name: string;
+  type: 'counter' | 'gauge' | 'histogram';
+  value: number;
+  timestamp: number;
+  labels: Record<string, string>;
+}
+
+export interface TraceExporter {
+  export(spans: Span[]): Promise<void>;
+}
+
+// ─── ID Generation ───────────────────────────────────────────
+
+export function generateTraceId(): string {
+  return crypto.randomBytes(16).toString('hex'); // 32 hex chars
+}
+
+export function generateSpanId(): string {
+  return crypto.randomBytes(8).toString('hex'); // 16 hex chars
+}
+
+// ─── Tracer ──────────────────────────────────────────────────
+
+export class Tracer {
+  private spans: Span[] = [];
+  private metrics: Metric[] = [];
+  private maxSpans: number;
+  private maxMetrics: number;
+  private exporters: TraceExporter[] = [];
+
+  constructor(options?: { maxSpans?: number; maxMetrics?: number }) {
+    this.maxSpans = options?.maxSpans || 10000;
+    this.maxMetrics = options?.maxMetrics || 50000;
+  }
+
+  startSpan(name: string, options?: {
+    parent?: Span;
+    attributes?: Record<string, string | number | boolean>;
+    kind?: Span['kind'];
+  }): Span {
+    const span: Span = {
+      traceId: options?.parent?.traceId || generateTraceId(),
+      spanId: generateSpanId(),
+      parentSpanId: options?.parent?.spanId,
+      name,
+      kind: options?.kind || 'internal',
+      startTime: Date.now(),
+      status: 'unset',
+      attributes: options?.attributes ? { ...options.attributes } : {},
+      events: [],
+    };
+    this.spans.push(span);
+
+    // Evict oldest spans if over limit
+    if (this.spans.length > this.maxSpans) {
+      const excess = this.spans.length - this.maxSpans;
+      this.spans.splice(0, excess);
+    }
+
+    return span;
+  }
+
+  endSpan(span: Span, status?: Span['status']): void {
+    span.endTime = Date.now();
+    span.status = status || 'ok';
+
+    // Notify exporters
+    for (const exporter of this.exporters) {
+      exporter.export([span]).catch(() => {});
+    }
+  }
+
+  addEvent(span: Span, name: string, attributes?: Record<string, string | number | boolean>): void {
+    span.events.push({ name, timestamp: Date.now(), attributes });
+  }
+
+  // ─── Metrics ─────────────────────────────────────────────
+
+  increment(name: string, value: number = 1, labels: Record<string, string> = {}): void {
+    this.addMetric(name, 'counter', value, labels);
+  }
+
+  gauge(name: string, value: number, labels: Record<string, string> = {}): void {
+    this.addMetric(name, 'gauge', value, labels);
+  }
+
+  histogram(name: string, value: number, labels: Record<string, string> = {}): void {
+    this.addMetric(name, 'histogram', value, labels);
+  }
+
+  private addMetric(name: string, type: Metric['type'], value: number, labels: Record<string, string>): void {
+    this.metrics.push({ name, type, value, timestamp: Date.now(), labels });
+    if (this.metrics.length > this.maxMetrics) {
+      this.metrics.splice(0, this.metrics.length - this.maxMetrics);
+    }
+  }
+
+  // ─── Query ───────────────────────────────────────────────
+
+  getSpans(options?: { limit?: number; traceId?: string; name?: string; since?: number }): Span[] {
+    let result = [...this.spans];
+
+    if (options?.traceId) result = result.filter(s => s.traceId === options.traceId);
+    if (options?.name) result = result.filter(s => s.name === options.name);
+    if (options?.since) result = result.filter(s => s.startTime >= options.since!);
+
+    // Most recent first
+    result.sort((a, b) => b.startTime - a.startTime);
+
+    if (options?.limit) result = result.slice(0, options.limit);
+    return result;
+  }
+
+  getMetrics(options?: { name?: string; since?: number }): Metric[] {
+    let result = [...this.metrics];
+    if (options?.name) result = result.filter(m => m.name === options.name);
+    if (options?.since) result = result.filter(m => m.timestamp >= options.since!);
+    return result;
+  }
+
+  getTrace(traceId: string): Span[] {
+    return this.spans.filter(s => s.traceId === traceId).sort((a, b) => a.startTime - b.startTime);
+  }
+
+  // ─── Export (OTLP-compatible) ────────────────────────────
+
+  addExporter(exporter: TraceExporter): void {
+    this.exporters.push(exporter);
+  }
+
+  exportOTLP(): object {
+    // OTLP JSON format: https://opentelemetry.io/docs/specs/otlp/
+    const spansByResource = this.spans.filter(s => s.endTime != null);
+
+    return {
+      resourceSpans: [{
+        resource: {
+          attributes: [
+            { key: 'service.name', value: { stringValue: 'opc-agent' } },
+          ],
+        },
+        scopeSpans: [{
+          scope: { name: 'opc-telemetry', version: '1.0.0' },
+          spans: spansByResource.map(s => ({
+            traceId: s.traceId,
+            spanId: s.spanId,
+            parentSpanId: s.parentSpanId || '',
+            name: s.name,
+            kind: s.kind === 'server' ? 2 : s.kind === 'client' ? 3 : 1,
+            startTimeUnixNano: String(s.startTime * 1_000_000),
+            endTimeUnixNano: String((s.endTime || s.startTime) * 1_000_000),
+            attributes: Object.entries(s.attributes).map(([key, value]) => ({
+              key,
+              value: typeof value === 'string' ? { stringValue: value }
+                : typeof value === 'number' ? (Number.isInteger(value) ? { intValue: String(value) } : { doubleValue: value })
+                : { boolValue: value },
+            })),
+            events: s.events.map(e => ({
+              timeUnixNano: String(e.timestamp * 1_000_000),
+              name: e.name,
+              attributes: e.attributes ? Object.entries(e.attributes).map(([key, value]) => ({
+                key,
+                value: typeof value === 'string' ? { stringValue: value }
+                  : typeof value === 'number' ? { intValue: String(value) }
+                  : { boolValue: value },
+              })) : [],
+            })),
+            status: {
+              code: s.status === 'ok' ? 1 : s.status === 'error' ? 2 : 0,
+            },
+          })),
+        }],
+      }],
+    };
+  }
+
+  // ─── Stats ───────────────────────────────────────────────
+
+  getStats(): {
+    totalSpans: number;
+    totalTraces: number;
+    avgDuration: number;
+    errorRate: number;
+    spansByName: Record<string, number>;
+    p50Latency: number;
+    p95Latency: number;
+    p99Latency: number;
+  } {
+    const completed = this.spans.filter(s => s.endTime != null);
+    const durations = completed.map(s => s.endTime! - s.startTime).sort((a, b) => a - b);
+    const traceIds = new Set(this.spans.map(s => s.traceId));
+    const errors = completed.filter(s => s.status === 'error').length;
+
+    const spansByName: Record<string, number> = {};
+    for (const s of this.spans) {
+      spansByName[s.name] = (spansByName[s.name] || 0) + 1;
+    }
+
+    const percentile = (arr: number[], p: number): number => {
+      if (arr.length === 0) return 0;
+      const idx = Math.ceil(arr.length * p / 100) - 1;
+      return arr[Math.max(0, idx)];
+    };
+
+    return {
+      totalSpans: this.spans.length,
+      totalTraces: traceIds.size,
+      avgDuration: durations.length > 0 ? durations.reduce((a, b) => a + b, 0) / durations.length : 0,
+      errorRate: completed.length > 0 ? errors / completed.length : 0,
+      spansByName,
+      p50Latency: percentile(durations, 50),
+      p95Latency: percentile(durations, 95),
+      p99Latency: percentile(durations, 99),
+    };
+  }
+
+  clear(): void {
+    this.spans = [];
+    this.metrics = [];
+  }
+}
+
+// ─── Exporters ───────────────────────────────────────────────
+
+export class ConsoleExporter implements TraceExporter {
+  async export(spans: Span[]): Promise<void> {
+    for (const span of spans) {
+      const duration = span.endTime ? `${span.endTime - span.startTime}ms` : 'ongoing';
+      console.log(`[TRACE] ${span.name} (${duration}) [${span.status}] trace=${span.traceId.slice(0, 8)}`);
+    }
+  }
+}
+
+export class FileExporter implements TraceExporter {
+  private filePath: string;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+  }
+
+  async export(spans: Span[]): Promise<void> {
+    const lines = spans.map(s => JSON.stringify(s)).join('\n') + '\n';
+    fs.appendFileSync(this.filePath, lines);
+  }
+}
+
+export class OTLPHttpExporter implements TraceExporter {
+  private endpoint: string;
+
+  constructor(endpoint: string) {
+    this.endpoint = endpoint.replace(/\/$/, '');
+  }
+
+  async export(spans: Span[]): Promise<void> {
+    const body = {
+      resourceSpans: [{
+        resource: {
+          attributes: [
+            { key: 'service.name', value: { stringValue: 'opc-agent' } },
+          ],
+        },
+        scopeSpans: [{
+          scope: { name: 'opc-telemetry', version: '1.0.0' },
+          spans: spans.filter(s => s.endTime).map(s => ({
+            traceId: s.traceId,
+            spanId: s.spanId,
+            parentSpanId: s.parentSpanId || '',
+            name: s.name,
+            kind: s.kind === 'server' ? 2 : s.kind === 'client' ? 3 : 1,
+            startTimeUnixNano: String(s.startTime * 1_000_000),
+            endTimeUnixNano: String((s.endTime || s.startTime) * 1_000_000),
+            attributes: Object.entries(s.attributes).map(([key, value]) => ({
+              key,
+              value: typeof value === 'string' ? { stringValue: value }
+                : typeof value === 'number' ? { intValue: String(value) }
+                : { boolValue: value },
+            })),
+            status: { code: s.status === 'ok' ? 1 : s.status === 'error' ? 2 : 0 },
+          })),
+        }],
+      }],
+    };
+
+    try {
+      await fetch(`${this.endpoint}/v1/traces`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      });
+    } catch {
+      // Best effort
+    }
+  }
+}

package/src/tools/builtin/datetime.ts

@@ -0,0 +1,41 @@
+import type { MCPTool, MCPToolResult } from '../mcp';
+
+export const datetimeTool: MCPTool = {
+  name: 'datetime',
+  description: 'Get current date, time, timezone info',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      format: { type: 'string', default: 'iso' },
+      timezone: { type: 'string' },
+    },
+  },
+  async execute(input: Record<string, unknown>): Promise<MCPToolResult> {
+    const now = new Date();
+    const timezone = input.timezone as string | undefined;
+    const format = (input.format as string) || 'iso';
+
+    let content: string;
+    if (format === 'iso') {
+      content = now.toISOString();
+    } else if (format === 'locale') {
+      content = timezone
+        ? now.toLocaleString('en-US', { timeZone: timezone })
+        : now.toLocaleString();
+    } else if (format === 'unix') {
+      content = String(Math.floor(now.getTime() / 1000));
+    } else {
+      content = now.toISOString();
+    }
+
+    return {
+      content: JSON.stringify({
+        iso: now.toISOString(),
+        unix: Math.floor(now.getTime() / 1000),
+        formatted: content,
+        timezone: timezone || Intl.DateTimeFormat().resolvedOptions().timeZone,
+      }),
+      isError: false,
+    };
+  },
+};

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,
+      };
+    }
+  },
+};