opc-agent 1.2.0 → 1.3.0

package/src/traces/index.ts

@@ -0,0 +1,132 @@
+/**
+ * OPC Agent Traces — Structured logging for agent actions.
+ * 
+ * Collects traces that can be fed to DeepBrain's learn() API.
+ * Inspired by OpenTelemetry spans.
+ */
+
+export interface Span {
+  traceId: string;
+  spanId: string;
+  name: string;
+  startTime: Date;
+  endTime?: Date;
+  attributes: Record<string, string | number | boolean>;
+  events: SpanEvent[];
+  status: 'ok' | 'error' | 'unset';
+}
+
+export interface SpanEvent {
+  name: string;
+  timestamp: Date;
+  attributes?: Record<string, string | number | boolean>;
+}
+
+export interface TraceExporter {
+  export(spans: Span[]): Promise<void>;
+}
+
+/** In-memory buffer that holds spans until flushed */
+export class TraceCollector {
+  private spans: Span[] = [];
+  private exporters: TraceExporter[] = [];
+  private maxBufferSize: number;
+
+  constructor(maxBufferSize = 100) {
+    this.maxBufferSize = maxBufferSize;
+  }
+
+  addExporter(exporter: TraceExporter): void {
+    this.exporters.push(exporter);
+  }
+
+  startSpan(name: string, attributes: Record<string, string | number | boolean> = {}): Span {
+    const span: Span = {
+      traceId: crypto.randomUUID(),
+      spanId: crypto.randomUUID().slice(0, 16),
+      name,
+      startTime: new Date(),
+      attributes,
+      events: [],
+      status: 'unset',
+    };
+    this.spans.push(span);
+    
+    if (this.spans.length >= this.maxBufferSize) {
+      this.flush().catch(() => {}); // Best effort
+    }
+    
+    return span;
+  }
+
+  endSpan(span: Span, status: 'ok' | 'error' = 'ok'): void {
+    span.endTime = new Date();
+    span.status = status;
+  }
+
+  addEvent(span: Span, name: string, attributes?: Record<string, string | number | boolean>): void {
+    span.events.push({ name, timestamp: new Date(), attributes });
+  }
+
+  async flush(): Promise<number> {
+    const toExport = [...this.spans];
+    this.spans = [];
+    
+    for (const exporter of this.exporters) {
+      await exporter.export(toExport);
+    }
+    
+    return toExport.length;
+  }
+
+  getBufferedSpans(): readonly Span[] {
+    return this.spans;
+  }
+
+  get bufferedCount(): number {
+    return this.spans.length;
+  }
+}
+
+/** Console exporter for development */
+export class ConsoleExporter implements TraceExporter {
+  async export(spans: Span[]): Promise<void> {
+    for (const span of spans) {
+      const duration = span.endTime 
+        ? `${span.endTime.getTime() - span.startTime.getTime()}ms`
+        : 'ongoing';
+      console.log(`[TRACE] ${span.name} (${duration}) [${span.status}]`);
+    }
+  }
+}
+
+/** DeepBrain exporter — sends traces to DeepBrain learn() */
+export class DeepBrainExporter implements TraceExporter {
+  private learnEndpoint: string;
+
+  constructor(deepbrainUrl: string = 'http://localhost:3333') {
+    this.learnEndpoint = `${deepbrainUrl}/api/learn`;
+  }
+
+  async export(spans: Span[]): Promise<void> {
+    for (const span of spans) {
+      try {
+        await fetch(this.learnEndpoint, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            action: span.name,
+            result: span.status === 'ok' ? 'success' : 'error',
+            context: {
+              ...span.attributes,
+              duration: span.endTime ? span.endTime.getTime() - span.startTime.getTime() : null,
+              events: span.events.map(e => e.name),
+            },
+          }),
+        });
+      } catch {
+        // Best effort — don't break agent if brain is down
+      }
+    }
+  }
+}

package/tests/gateway.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ToolGateway } from '../src/tools/gateway';
+import type { ToolGatewayConfig } from '../src/tools/gateway';
+
+const baseConfig: ToolGatewayConfig = {
+  enabled: true,
+  endpoint: 'https://gateway.example.com',
+  apiKey: 'test-key',
+};
+
+describe('ToolGateway', () => {
+  it('should load default tools when connect fails', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('network error')));
+    const gw = new ToolGateway(baseConfig);
+    await gw.connect();
+    expect(gw.isConnected).toBe(false);
+    expect(gw.toolCount).toBe(4);
+    expect(gw.listTools().map((t) => t.name)).toContain('gateway:web-search');
+    vi.unstubAllGlobals();
+  });
+
+  it('should filter tools by enabledTools config', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('fail')));
+    const gw = new ToolGateway({ ...baseConfig, enabledTools: ['web-search', 'tts'] });
+    await gw.connect();
+    expect(gw.toolCount).toBe(2);
+    vi.unstubAllGlobals();
+  });
+
+  it('should parse gateway discovery response', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        tools: [
+          { name: 'web-search', description: 'Search', inputSchema: {}, available: true },
+        ],
+      }),
+    }));
+    const gw = new ToolGateway(baseConfig);
+    await gw.connect();
+    expect(gw.isConnected).toBe(true);
+    expect(gw.toolCount).toBe(1);
+    vi.unstubAllGlobals();
+  });
+
+  it('should return MCPTool instances from getTools()', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('fail')));
+    const gw = new ToolGateway(baseConfig);
+    await gw.connect();
+    const tools = gw.getTools();
+    expect(tools.length).toBe(4);
+    expect(tools[0]).toHaveProperty('execute');
+    expect(tools[0]).toHaveProperty('name');
+    vi.unstubAllGlobals();
+  });
+
+  it('should handle invoke errors gracefully', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('timeout')));
+    const gw = new ToolGateway(baseConfig);
+    const result = await gw.invokeTool('web-search', { query: 'test' });
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain('timeout');
+    vi.unstubAllGlobals();
+  });
+
+  it('should not discover tools when disabled', async () => {
+    const gw = new ToolGateway({ ...baseConfig, enabled: false });
+    await gw.connect();
+    expect(gw.toolCount).toBe(0);
+  });
+});

package/tests/streaming.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi } from 'vitest';
+import { StreamingManager, StreamableResponse } from '../src/core/streaming';
+import type { StreamChunk } from '../src/core/streaming';
+
+describe('StreamableResponse', () => {
+  it('should collect chunks and build text', () => {
+    const stream = new StreamableResponse('test-1');
+    stream.push({ id: '0', type: 'text', data: 'Hello ', timestamp: Date.now() });
+    stream.push({ id: '1', type: 'text', data: 'World', timestamp: Date.now() });
+    expect(stream.getText()).toBe('Hello World');
+    expect(stream.length).toBe(2);
+  });
+
+  it('should emit chunk events', () => {
+    const stream = new StreamableResponse('test-2');
+    const received: StreamChunk[] = [];
+    stream.on('chunk', (c: StreamChunk) => received.push(c));
+    stream.push({ id: '0', type: 'text', data: 'hi', timestamp: Date.now() });
+    expect(received.length).toBe(1);
+  });
+
+  it('should emit end event', () => {
+    const stream = new StreamableResponse('test-3');
+    let ended = false;
+    stream.on('end', () => { ended = true; });
+    stream.end();
+    expect(ended).toBe(true);
+    expect(stream.isEnded).toBe(true);
+  });
+
+  it('should apply backpressure at highWaterMark', () => {
+    const stream = new StreamableResponse('test-4', { highWaterMark: 2 });
+    const chunk = (): StreamChunk => ({ id: 'c', type: 'text', data: 'x', timestamp: Date.now() });
+    stream.push(chunk()); // 1 — ok
+    const ok = stream.push(chunk()); // 2 — triggers backpressure
+    expect(ok).toBe(false);
+    expect(stream.isPaused).toBe(true);
+  });
+
+  it('should flush buffer on resume', () => {
+    const stream = new StreamableResponse('test-5', { highWaterMark: 1 });
+    const received: StreamChunk[] = [];
+    stream.on('chunk', (c: StreamChunk) => received.push(c));
+    stream.push({ id: '0', type: 'text', data: 'a', timestamp: Date.now() });
+    // Now paused — next chunk goes to buffer
+    stream.push({ id: '1', type: 'text', data: 'b', timestamp: Date.now() });
+    expect(received.length).toBe(1);
+    stream.resume();
+    expect(received.length).toBe(2);
+    expect(stream.isPaused).toBe(false);
+  });
+
+  it('should reject pushes after end', () => {
+    const stream = new StreamableResponse('test-6');
+    stream.end();
+    const ok = stream.push({ id: '0', type: 'text', data: 'late', timestamp: Date.now() });
+    expect(ok).toBe(false);
+    expect(stream.length).toBe(0);
+  });
+});
+
+describe('StreamingManager', () => {
+  it('should create and manage streams', () => {
+    const mgr = new StreamingManager();
+    const stream = mgr.createStream();
+    expect(stream.id).toMatch(/^stream_/);
+    expect(mgr.activeCount).toBe(1);
+  });
+
+  it('should write chunks and end stream', () => {
+    const mgr = new StreamingManager();
+    const stream = mgr.createStream();
+    mgr.writeChunk(stream.id, 'hello');
+    mgr.writeChunk(stream.id, ' world');
+    mgr.endStream(stream.id);
+    expect(stream.getText()).toBe('hello world');
+    expect(stream.isEnded).toBe(true);
+  });
+
+  it('should return false for unknown stream writes', () => {
+    const mgr = new StreamingManager();
+    expect(mgr.writeChunk('nonexistent', 'data')).toBe(false);
+  });
+
+  it('should format SSE correctly', () => {
+    const chunk: StreamChunk = { id: 'c1', type: 'text', data: 'hi', timestamp: 123 };
+    const sse = StreamingManager.formatSSE(chunk);
+    expect(sse).toContain('event: text');
+    expect(sse).toContain('id: c1');
+    expect(sse).toContain('"data":"hi"');
+  });
+
+  it('should pipe to SSE response', () => {
+    const mgr = new StreamingManager();
+    const stream = mgr.createStream();
+    const written: string[] = [];
+    const mockRes = {
+      write: (d: string) => { written.push(d); return true; },
+      end: vi.fn(),
+      setHeader: vi.fn(),
+    };
+    StreamingManager.pipeSSE(stream, mockRes, { heartbeatInterval: 100_000 });
+    mgr.writeChunk(stream.id, 'data');
+    mgr.endStream(stream.id);
+    expect(written.length).toBeGreaterThan(0);
+    expect(mockRes.end).toHaveBeenCalled();
+    expect(mockRes.setHeader).toHaveBeenCalledWith('Content-Type', 'text/event-stream');
+  });
+});

package/src/dtv/data.ts

@@ -1,29 +0,0 @@
-export interface DataSource {
-  readonly name: string;
-  readonly type: string;
-  read(key: string): Promise<unknown>;
-}
-
-/**
- * MRGConfig reader — read-only data layer for agents.
- * Agents can read business data but cannot modify source systems.
- */
-export class MRGConfigReader implements DataSource {
-  readonly name = 'mrg-config';
-  readonly type = 'config';
-  private data: Map<string, unknown>;
-
-  constructor(initial?: Record<string, unknown>) {
-    this.data = new Map(Object.entries(initial ?? {}));
-  }
-
-  async read(key: string): Promise<unknown> {
-    return this.data.get(key);
-  }
-
-  load(data: Record<string, unknown>): void {
-    for (const [k, v] of Object.entries(data)) {
-      this.data.set(k, v);
-    }
-  }
-}

package/src/dtv/trust.ts

@@ -1,43 +0,0 @@
-import type { TrustLevelType } from '../schema/oad';
-
-/**
- * Trust levels: sandbox → verified → certified → listed
- *
- * - sandbox:   No network, no file system, limited capabilities
- * - verified:  Identity verified, basic capabilities
- * - certified: Passed security audit, full capabilities
- * - listed:    Published in OPC marketplace
- */
-export class TrustManager {
-  private level: TrustLevelType;
-
-  constructor(level: TrustLevelType = 'sandbox') {
-    this.level = level;
-  }
-
-  getLevel(): TrustLevelType {
-    return this.level;
-  }
-
-  canAccessNetwork(): boolean {
-    return this.level !== 'sandbox';
-  }
-
-  canAccessFileSystem(): boolean {
-    return this.level === 'certified' || this.level === 'listed';
-  }
-
-  canPublish(): boolean {
-    return this.level === 'listed';
-  }
-
-  upgrade(to: TrustLevelType): void {
-    const order: TrustLevelType[] = ['sandbox', 'verified', 'certified', 'listed'];
-    const currentIdx = order.indexOf(this.level);
-    const targetIdx = order.indexOf(to);
-    if (targetIdx <= currentIdx) {
-      throw new Error(`Cannot downgrade trust from ${this.level} to ${to}`);
-    }
-    this.level = to;
-  }
-}

package/src/dtv/value.ts

@@ -1,47 +0,0 @@
-/**
- * Value tracking — metrics and ROI for agent operations.
- */
-export interface ValueMetric {
-  name: string;
-  value: number;
-  unit: string;
-  timestamp: number;
-}
-
-export class ValueTracker {
-  private metrics: Map<string, ValueMetric[]> = new Map();
-  private trackedNames: Set<string>;
-
-  constructor(metricNames: string[] = []) {
-    this.trackedNames = new Set(metricNames);
-  }
-
-  record(name: string, value: number, unit: string = ''): void {
-    if (!this.metrics.has(name)) {
-      this.metrics.set(name, []);
-    }
-    this.metrics.get(name)!.push({ name, value, unit, timestamp: Date.now() });
-  }
-
-  getMetrics(name: string): ValueMetric[] {
-    return this.metrics.get(name) ?? [];
-  }
-
-  getAverage(name: string): number {
-    const m = this.getMetrics(name);
-    if (m.length === 0) return 0;
-    return m.reduce((sum, v) => sum + v.value, 0) / m.length;
-  }
-
-  getSummary(): Record<string, { count: number; average: number; last: number }> {
-    const result: Record<string, { count: number; average: number; last: number }> = {};
-    for (const [name, values] of this.metrics) {
-      result[name] = {
-        count: values.length,
-        average: this.getAverage(name),
-        last: values[values.length - 1]?.value ?? 0,
-      };
-    }
-    return result;
-  }
-}

package/src/marketplace/index.ts

@@ -1,223 +0,0 @@
-/**
- * Agent Marketplace - Package, publish, and install agents
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import * as crypto from 'crypto';
-import { execSync } from 'child_process';
-
-export interface AgentManifest {
-  name: string;
-  version: string;
-  description: string;
-  author: string;
-  license: string;
-  oadVersion: string;
-  channels: string[];
-  skills: string[];
-  files: string[];
-  checksum: string;
-  publishedAt: string;
-  homepage?: string;
-  repository?: string;
-  tags?: string[];
-}
-
-export interface PublishOptions {
-  oadPath: string;
-  outputDir?: string;
-  includeKnowledge?: boolean;
-}
-
-export interface InstallOptions {
-  source: string; // local path or URL
-  targetDir?: string;
-}
-
-function computeChecksum(filePath: string): string {
-  const content = fs.readFileSync(filePath);
-  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
-}
-
-export async function publishAgent(options: PublishOptions): Promise<{ archivePath: string; manifest: AgentManifest }> {
-  const { oadPath, outputDir = '.', includeKnowledge = false } = options;
-  const absOad = path.resolve(oadPath);
-  const baseDir = path.dirname(absOad);
-
-  if (!fs.existsSync(absOad)) {
-    throw new Error(`OAD file not found: ${absOad}`);
-  }
-
-  // Dynamic import yaml
-  const yaml = await import('js-yaml');
-  const oadContent = fs.readFileSync(absOad, 'utf-8');
-  const oad = yaml.load(oadContent) as any;
-
-  const name = oad.metadata?.name ?? 'unnamed-agent';
-  const version = oad.metadata?.version ?? '0.0.0';
-  const safeName = name.toLowerCase().replace(/[^a-z0-9-]/g, '-');
-
-  // Collect files to package
-  const filesToPack: { rel: string; abs: string }[] = [
-    { rel: path.basename(absOad), abs: absOad },
-  ];
-
-  // Include common files
-  const extras = ['.env.example', 'README.md', 'package.json'];
-  for (const f of extras) {
-    const fp = path.join(baseDir, f);
-    if (fs.existsSync(fp)) {
-      filesToPack.push({ rel: f, abs: fp });
-    }
-  }
-
-  // Include knowledge base if requested
-  if (includeKnowledge) {
-    const kbFile = path.join(baseDir, '.opc-knowledge.json');
-    if (fs.existsSync(kbFile)) {
-      filesToPack.push({ rel: '.opc-knowledge.json', abs: kbFile });
-    }
-  }
-
-  // Include prompts directory if exists
-  const promptsDir = path.join(baseDir, 'prompts');
-  if (fs.existsSync(promptsDir) && fs.statSync(promptsDir).isDirectory()) {
-    const promptFiles = fs.readdirSync(promptsDir);
-    for (const pf of promptFiles) {
-      filesToPack.push({ rel: `prompts/${pf}`, abs: path.join(promptsDir, pf) });
-    }
-  }
-
-  // Build manifest
-  const manifest: AgentManifest = {
-    name: safeName,
-    version,
-    description: oad.metadata?.description ?? '',
-    author: oad.metadata?.author ?? '',
-    license: oad.metadata?.license ?? 'Apache-2.0',
-    oadVersion: 'opc/v1',
-    channels: (oad.spec?.channels ?? []).map((c: any) => c.type),
-    skills: (oad.spec?.skills ?? []).map((s: any) => s.name),
-    files: filesToPack.map(f => f.rel),
-    checksum: '',
-    publishedAt: new Date().toISOString(),
-    tags: oad.metadata?.marketplace?.tags,
-  };
-
-  // Create staging directory
-  const stageDir = path.join(outputDir, `.opc-stage-${safeName}`);
-  fs.mkdirSync(stageDir, { recursive: true });
-
-  for (const f of filesToPack) {
-    const dest = path.join(stageDir, f.rel);
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.copyFileSync(f.abs, dest);
-  }
-
-  // Write manifest
-  fs.writeFileSync(path.join(stageDir, 'opc-manifest.json'), JSON.stringify(manifest, null, 2));
-
-  // Create tar.gz
-  const archiveName = `${safeName}-${version}.tar.gz`;
-  const archivePath = path.join(outputDir, archiveName);
-
-  try {
-    execSync(`tar -czf "${archivePath}" -C "${stageDir}" .`, { stdio: 'pipe' });
-  } catch {
-    // Fallback: just zip the directory content list
-    // On Windows without tar, create a simple zip-like package
-    const packageData = {
-      manifest,
-      files: filesToPack.map(f => ({
-        path: f.rel,
-        content: fs.readFileSync(f.abs, 'utf-8'),
-      })),
-    };
-    fs.writeFileSync(
-      archivePath.replace('.tar.gz', '.opc.json'),
-      JSON.stringify(packageData, null, 2),
-    );
-  }
-
-  // Compute checksum
-  if (fs.existsSync(archivePath)) {
-    manifest.checksum = computeChecksum(archivePath);
-  }
-
-  // Cleanup staging
-  fs.rmSync(stageDir, { recursive: true, force: true });
-
-  // Write final manifest
-  fs.writeFileSync(
-    path.join(outputDir, 'opc-manifest.json'),
-    JSON.stringify(manifest, null, 2),
-  );
-
-  return { archivePath: fs.existsSync(archivePath) ? archivePath : archivePath.replace('.tar.gz', '.opc.json'), manifest };
-}
-
-export async function installAgent(options: InstallOptions): Promise<{ dir: string; manifest: AgentManifest }> {
-  const { source, targetDir } = options;
-  const absSource = path.resolve(source);
-
-  if (!fs.existsSync(absSource)) {
-    throw new Error(`Package not found: ${absSource}`);
-  }
-
-  let manifest: AgentManifest;
-  let installDir: string;
-
-  if (absSource.endsWith('.opc.json')) {
-    // JSON package format
-    const pkg = JSON.parse(fs.readFileSync(absSource, 'utf-8'));
-    manifest = pkg.manifest;
-    installDir = targetDir ?? path.join('.', manifest.name);
-    fs.mkdirSync(installDir, { recursive: true });
-
-    for (const f of pkg.files) {
-      const dest = path.join(installDir, f.path);
-      fs.mkdirSync(path.dirname(dest), { recursive: true });
-      fs.writeFileSync(dest, f.content, 'utf-8');
-    }
-    fs.writeFileSync(path.join(installDir, 'opc-manifest.json'), JSON.stringify(manifest, null, 2));
-  } else {
-    // tar.gz format
-    const tmpDir = path.join(path.dirname(absSource), '.opc-extract-tmp');
-    fs.mkdirSync(tmpDir, { recursive: true });
-
-    try {
-      execSync(`tar -xzf "${absSource}" -C "${tmpDir}"`, { stdio: 'pipe' });
-    } catch {
-      throw new Error('Failed to extract package. Ensure tar is available.');
-    }
-
-    const manifestPath = path.join(tmpDir, 'opc-manifest.json');
-    if (!fs.existsSync(manifestPath)) {
-      fs.rmSync(tmpDir, { recursive: true, force: true });
-      throw new Error('Invalid package: missing opc-manifest.json');
-    }
-
-    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-    installDir = targetDir ?? path.join('.', manifest.name);
-
-    // Move files
-    fs.mkdirSync(installDir, { recursive: true });
-    const copyRecursive = (src: string, dest: string) => {
-      const entries = fs.readdirSync(src, { withFileTypes: true });
-      for (const entry of entries) {
-        const srcPath = path.join(src, entry.name);
-        const destPath = path.join(dest, entry.name);
-        if (entry.isDirectory()) {
-          fs.mkdirSync(destPath, { recursive: true });
-          copyRecursive(srcPath, destPath);
-        } else {
-          fs.copyFileSync(srcPath, destPath);
-        }
-      }
-    };
-    copyRecursive(tmpDir, installDir);
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-
-  return { dir: installDir, manifest };
-}