opc-agent 2.0.0 → 2.0.2

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/types/agent-workstation.d.ts

@@ -0,0 +1,2 @@
+declare module "agent-workstation";
+declare module "deepbrain";

package/tests/a2a-protocol.test.ts

@@ -0,0 +1,285 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { A2AServer } from '../src/protocols/a2a/server';
+import { A2AClient } from '../src/protocols/a2a/client';
+import { oadToAgentCard } from '../src/protocols/a2a/utils';
+import { JSON_RPC_ERRORS } from '../src/protocols/a2a/types';
+import type { A2AAgentCard, A2ATask, A2AMessage } from '../src/protocols/a2a/types';
+
+// Mock agent
+function createMockAgent(name = 'test-agent') {
+  return {
+    name,
+    config: { systemPrompt: 'I am a test agent' },
+    handleMessage: async (msg: any) => ({ content: `Echo: ${msg.content}`, role: 'assistant' }),
+  };
+}
+
+describe('oadToAgentCard', () => {
+  it('should generate card from OAD', () => {
+    const oad = {
+      metadata: { name: 'my-agent', description: 'A test agent', version: '2.0.0' },
+      spec: {
+        skills: [
+          { id: 'sum', name: 'Summarize', description: 'Summarize text', tags: ['nlp'] },
+        ],
+        channels: [{ type: 'websocket' }],
+      },
+    };
+    const card = oadToAgentCard(oad, 'http://localhost:3001');
+    expect(card.name).toBe('my-agent');
+    expect(card.description).toBe('A test agent');
+    expect(card.version).toBe('2.0.0');
+    expect(card.url).toBe('http://localhost:3001');
+    expect(card.skills).toHaveLength(1);
+    expect(card.skills[0].id).toBe('sum');
+    expect(card.capabilities.streaming).toBe(true);
+  });
+
+  it('should create default skill when none defined', () => {
+    const oad = { metadata: { name: 'basic', description: 'Basic agent' }, spec: {} };
+    const card = oadToAgentCard(oad, 'http://localhost:3001');
+    expect(card.skills).toHaveLength(1);
+    expect(card.skills[0].id).toBe('default');
+  });
+
+  it('should handle empty OAD', () => {
+    const card = oadToAgentCard({}, 'http://localhost:3001');
+    expect(card.name).toBe('opc-agent');
+    expect(card.url).toBe('http://localhost:3001');
+  });
+
+  it('should strip trailing slash from URL', () => {
+    const card = oadToAgentCard({}, 'http://localhost:3001/');
+    expect(card.url).toBe('http://localhost:3001');
+  });
+});
+
+describe('A2AServer', () => {
+  let server: A2AServer;
+  const PORT = 39871;
+
+  beforeEach(async () => {
+    const agent = createMockAgent();
+    server = new A2AServer(agent, {
+      card: { name: 'test-server', description: 'Test', url: `http://localhost:${PORT}` },
+    });
+    await server.start(PORT);
+  });
+
+  afterEach(async () => {
+    await server.stop();
+  });
+
+  it('should serve /.well-known/agent.json', async () => {
+    const res = await fetch(`http://localhost:${PORT}/.well-known/agent.json`);
+    expect(res.status).toBe(200);
+    const card: A2AAgentCard = await res.json() as any;
+    expect(card.name).toBe('test-server');
+  });
+
+  it('should handle tasks/send', async () => {
+    const res = await fetch(`http://localhost:${PORT}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0', id: '1', method: 'tasks/send',
+        params: { id: 'task-1', message: { role: 'user', parts: [{ type: 'text', text: 'Hello' }] } },
+      }),
+    });
+    const json = await res.json() as any;
+    expect(json.result.id).toBe('task-1');
+    expect(json.result.status.state).toBe('completed');
+    expect(json.result.history).toHaveLength(2); // user + agent
+  });
+
+  it('should handle tasks/get', async () => {
+    // First create a task
+    await fetch(`http://localhost:${PORT}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0', id: '1', method: 'tasks/send',
+        params: { id: 'task-get-1', message: { role: 'user', parts: [{ type: 'text', text: 'Hi' }] } },
+      }),
+    });
+
+    // Then get it
+    const res = await fetch(`http://localhost:${PORT}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: '2', method: 'tasks/get', params: { id: 'task-get-1' } }),
+    });
+    const json = await res.json() as any;
+    expect(json.result.id).toBe('task-get-1');
+    expect(json.result.status.state).toBe('completed');
+  });
+
+  it('should handle tasks/cancel', async () => {
+    // Create task
+    await fetch(`http://localhost:${PORT}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0', id: '1', method: 'tasks/send',
+        params: { id: 'task-cancel-1', message: { role: 'user', parts: [{ type: 'text', text: 'Hi' }] } },
+      }),
+    });
+
+    const res = await fetch(`http://localhost:${PORT}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: '2', method: 'tasks/cancel', params: { id: 'task-cancel-1' } }),
+    });
+    const json = await res.json() as any;
+    expect(json.result.status.state).toBe('canceled');
+  });
+
+  it('should return error for unknown task', async () => {
+    const res = await fetch(`http://localhost:${PORT}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: '1', method: 'tasks/get', params: { id: 'nonexistent' } }),
+    });
+    const json = await res.json() as any;
+    expect(json.error).toBeDefined();
+    expect(json.error.code).toBe(JSON_RPC_ERRORS.TASK_NOT_FOUND);
+  });
+
+  it('should return error for unknown method', async () => {
+    const res = await fetch(`http://localhost:${PORT}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: '1', method: 'unknown/method', params: {} }),
+    });
+    const json = await res.json() as any;
+    expect(json.error).toBeDefined();
+    expect(json.error.code).toBe(JSON_RPC_ERRORS.METHOD_NOT_FOUND);
+  });
+
+  it('should return parse error for invalid JSON', async () => {
+    const res = await fetch(`http://localhost:${PORT}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: 'not json',
+    });
+    const json = await res.json() as any;
+    expect(json.error.code).toBe(JSON_RPC_ERRORS.PARSE_ERROR);
+  });
+
+  it('should return getAgentCard()', () => {
+    const card = server.getAgentCard();
+    expect(card.name).toBe('test-server');
+    expect(card.capabilities).toBeDefined();
+  });
+});
+
+describe('A2AClient', () => {
+  let server: A2AServer;
+  let client: A2AClient;
+  const PORT = 39872;
+
+  beforeEach(async () => {
+    const agent = createMockAgent();
+    server = new A2AServer(agent, {
+      card: { name: 'client-test', description: 'Test' },
+    });
+    await server.start(PORT);
+    client = new A2AClient(`http://localhost:${PORT}`);
+  });
+
+  afterEach(async () => {
+    await server.stop();
+  });
+
+  it('should getAgentCard', async () => {
+    const card = await client.getAgentCard();
+    expect(card.name).toBe('client-test');
+  });
+
+  it('should sendText and get response', async () => {
+    const response = await client.sendText('Hello agent');
+    expect(response).toContain('Echo: Hello agent');
+  });
+
+  it('should sendTask with message', async () => {
+    const task = await client.sendTask(
+      { role: 'user', parts: [{ type: 'text', text: 'Test message' }] },
+      { taskId: 'client-task-1' },
+    );
+    expect(task.id).toBe('client-task-1');
+    expect(task.status.state).toBe('completed');
+  });
+
+  it('should getTask', async () => {
+    await client.sendText('setup', { taskId: 'get-test' });
+    const task = await client.getTask('get-test');
+    expect(task.id).toBe('get-test');
+  });
+
+  it('should cancelTask', async () => {
+    await client.sendText('setup', { taskId: 'cancel-test' });
+    const task = await client.cancelTask('cancel-test');
+    expect(task.status.state).toBe('canceled');
+  });
+});
+
+describe('Task state transitions', () => {
+  it('should track state transitions through task lifecycle', async () => {
+    const states: string[] = [];
+    const agent = createMockAgent();
+    const server = new A2AServer(agent);
+    
+    server.onTask(async (task) => {
+      states.push(task.status.state);
+      task.status = { state: 'working', timestamp: new Date().toISOString() };
+      states.push('working');
+      task.status = { state: 'completed', timestamp: new Date().toISOString() };
+      states.push('completed');
+      return task;
+    });
+
+    const PORT = 39873;
+    await server.start(PORT);
+    
+    const client = new A2AClient(`http://localhost:${PORT}`);
+    await client.sendText('test');
+    
+    expect(states).toContain('working');
+    expect(states).toContain('completed');
+    
+    await server.stop();
+  });
+});
+
+describe('Message part types', () => {
+  it('should handle text parts', async () => {
+    const server = new A2AServer(createMockAgent());
+    const PORT = 39874;
+    await server.start(PORT);
+
+    const msg: A2AMessage = { role: 'user', parts: [{ type: 'text', text: 'hello' }] };
+    const client = new A2AClient(`http://localhost:${PORT}`);
+    const task = await client.sendTask(msg);
+    expect(task.history[0].parts[0].type).toBe('text');
+
+    await server.stop();
+  });
+
+  it('should handle file parts in message', () => {
+    const msg: A2AMessage = {
+      role: 'user',
+      parts: [{ type: 'file', file: { name: 'test.txt', mimeType: 'text/plain', bytes: 'aGVsbG8=' } }],
+    };
+    expect(msg.parts[0].type).toBe('file');
+    expect((msg.parts[0] as any).file.name).toBe('test.txt');
+  });
+
+  it('should handle data parts in message', () => {
+    const msg: A2AMessage = {
+      role: 'user',
+      parts: [{ type: 'data', data: { key: 'value', count: 42 } }],
+    };
+    expect(msg.parts[0].type).toBe('data');
+    expect((msg.parts[0] as any).data.key).toBe('value');
+  });
+});