opc-agent 0.3.0 → 0.5.0

package/src/core/a2a.ts

@@ -0,0 +1,143 @@
+import { EventEmitter } from 'events';
+import { Room } from './room';
+import type { Message, IAgent } from './types';
+import { Logger } from './logger';
+
+// ── A2A Types ───────────────────────────────────────────────
+
+export interface AgentCapability {
+  name: string;
+  description: string;
+  inputSchema?: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+}
+
+export interface AgentRegistration {
+  agentName: string;
+  capabilities: AgentCapability[];
+  endpoint?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface A2ARequest {
+  id: string;
+  from: string;
+  to: string;
+  capability: string;
+  payload: string;
+  timestamp: number;
+  timeout?: number;
+}
+
+export interface A2AResponse {
+  requestId: string;
+  from: string;
+  status: 'success' | 'error' | 'timeout';
+  payload?: string;
+  error?: string;
+  timestamp: number;
+}
+
+// ── Agent Registry ──────────────────────────────────────────
+
+export class AgentRegistry extends EventEmitter {
+  private registrations: Map<string, AgentRegistration> = new Map();
+  private agents: Map<string, IAgent> = new Map();
+  private room: Room;
+  private logger = new Logger('a2a');
+
+  constructor(room?: Room) {
+    super();
+    this.room = room ?? new Room('a2a-default');
+  }
+
+  register(agent: IAgent, capabilities: AgentCapability[]): void {
+    const reg: AgentRegistration = { agentName: agent.name, capabilities };
+    this.registrations.set(agent.name, reg);
+    this.agents.set(agent.name, agent);
+    this.room.addAgent(agent);
+    this.logger.info('Agent registered', { name: agent.name, capabilities: capabilities.map(c => c.name) });
+    this.emit('agent:registered', reg);
+  }
+
+  unregister(name: string): void {
+    this.registrations.delete(name);
+    this.agents.delete(name);
+    this.room.removeAgent(name);
+    this.emit('agent:unregistered', name);
+  }
+
+  discover(capability?: string): AgentRegistration[] {
+    const all = Array.from(this.registrations.values());
+    if (!capability) return all;
+    return all.filter(r => r.capabilities.some(c => c.name === capability));
+  }
+
+  getAgent(name: string): IAgent | undefined {
+    return this.agents.get(name);
+  }
+
+  async request(req: A2ARequest): Promise<A2AResponse> {
+    const agent = this.agents.get(req.to);
+    if (!agent) {
+      return {
+        requestId: req.id,
+        from: req.to,
+        status: 'error',
+        error: `Agent "${req.to}" not found`,
+        timestamp: Date.now(),
+      };
+    }
+
+    const message: Message = {
+      id: req.id,
+      role: 'user',
+      content: req.payload,
+      timestamp: req.timestamp,
+      metadata: { a2a: true, from: req.from, capability: req.capability },
+    };
+
+    this.emit('request', req);
+
+    try {
+      const timeoutMs = req.timeout ?? 30000;
+      const response = await Promise.race([
+        agent.handleMessage(message),
+        new Promise<never>((_, reject) =>
+          setTimeout(() => reject(new Error('A2A request timeout')), timeoutMs),
+        ),
+      ]);
+
+      const res: A2AResponse = {
+        requestId: req.id,
+        from: req.to,
+        status: 'success',
+        payload: response.content,
+        timestamp: Date.now(),
+      };
+      this.emit('response', res);
+      return res;
+    } catch (err) {
+      const res: A2AResponse = {
+        requestId: req.id,
+        from: req.to,
+        status: (err as Error).message.includes('timeout') ? 'timeout' : 'error',
+        error: (err as Error).message,
+        timestamp: Date.now(),
+      };
+      this.emit('response', res);
+      return res;
+    }
+  }
+
+  async call(from: string, to: string, capability: string, payload: string): Promise<A2AResponse> {
+    return this.request({
+      id: `a2a_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      from,
+      to,
+      capability,
+      payload,
+      timestamp: Date.now(),
+    });
+  }
+}

package/src/core/hitl.ts

@@ -0,0 +1,138 @@
+import { EventEmitter } from 'events';
+import { Logger } from './logger';
+
+// ── HITL Types ──────────────────────────────────────────────
+
+export interface ApprovalRequest {
+  id: string;
+  action: string;
+  description: string;
+  context?: Record<string, unknown>;
+  timeoutMs: number;
+  defaultAction: 'approve' | 'deny';
+  createdAt: number;
+}
+
+export interface ApprovalResponse {
+  requestId: string;
+  decision: 'approve' | 'deny';
+  respondedBy?: string;
+  respondedAt: number;
+  timedOut: boolean;
+}
+
+export type ApprovalHandler = (request: ApprovalRequest) => Promise<ApprovalResponse>;
+
+export interface HITLConfig {
+  /** Actions that always require approval */
+  requireApproval: string[];
+  /** Default timeout in ms */
+  defaultTimeoutMs: number;
+  /** Default action on timeout */
+  defaultAction: 'approve' | 'deny';
+}
+
+// ── HITL Manager ────────────────────────────────────────────
+
+export class HITLManager extends EventEmitter {
+  private config: HITLConfig;
+  private handler: ApprovalHandler | null = null;
+  private pending: Map<string, { request: ApprovalRequest; resolve: (r: ApprovalResponse) => void }> = new Map();
+  private logger = new Logger('hitl');
+
+  constructor(config?: Partial<HITLConfig>) {
+    super();
+    this.config = {
+      requireApproval: config?.requireApproval ?? [],
+      defaultTimeoutMs: config?.defaultTimeoutMs ?? 60000,
+      defaultAction: config?.defaultAction ?? 'deny',
+    };
+  }
+
+  setHandler(handler: ApprovalHandler): void {
+    this.handler = handler;
+  }
+
+  needsApproval(action: string): boolean {
+    if (this.config.requireApproval.includes('*')) return true;
+    return this.config.requireApproval.includes(action);
+  }
+
+  async requestApproval(action: string, description: string, context?: Record<string, unknown>): Promise<ApprovalResponse> {
+    const request: ApprovalRequest = {
+      id: `hitl_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      action,
+      description,
+      context,
+      timeoutMs: this.config.defaultTimeoutMs,
+      defaultAction: this.config.defaultAction,
+      createdAt: Date.now(),
+    };
+
+    this.emit('approval:requested', request);
+    this.logger.info('Approval requested', { id: request.id, action });
+
+    if (this.handler) {
+      try {
+        const response = await Promise.race([
+          this.handler(request),
+          this.createTimeout(request),
+        ]);
+        this.emit('approval:responded', response);
+        return response;
+      } catch {
+        return this.timeoutResponse(request);
+      }
+    }
+
+    // No handler: wait for manual response via respond()
+    return new Promise<ApprovalResponse>((resolve) => {
+      this.pending.set(request.id, { request, resolve });
+
+      setTimeout(() => {
+        if (this.pending.has(request.id)) {
+          this.pending.delete(request.id);
+          const response = this.timeoutResponse(request);
+          this.emit('approval:timeout', response);
+          resolve(response);
+        }
+      }, request.timeoutMs);
+    });
+  }
+
+  respond(requestId: string, decision: 'approve' | 'deny', respondedBy?: string): boolean {
+    const entry = this.pending.get(requestId);
+    if (!entry) return false;
+
+    this.pending.delete(requestId);
+    const response: ApprovalResponse = {
+      requestId,
+      decision,
+      respondedBy,
+      respondedAt: Date.now(),
+      timedOut: false,
+    };
+    entry.resolve(response);
+    this.emit('approval:responded', response);
+    return true;
+  }
+
+  getPending(): ApprovalRequest[] {
+    return Array.from(this.pending.values()).map(e => e.request);
+  }
+
+  private createTimeout(request: ApprovalRequest): Promise<ApprovalResponse> {
+    return new Promise((resolve) => {
+      setTimeout(() => resolve(this.timeoutResponse(request)), request.timeoutMs);
+    });
+  }
+
+  private timeoutResponse(request: ApprovalRequest): ApprovalResponse {
+    return {
+      requestId: request.id,
+      decision: request.defaultAction,
+      respondedAt: Date.now(),
+      timedOut: true,
+    };
+  }
+}

package/src/core/performance.ts

@@ -0,0 +1,187 @@
+import { Logger } from '../core/logger';
+
+// ── Connection Pool ─────────────────────────────────────────
+
+export interface PooledConnection {
+  id: string;
+  provider: string;
+  createdAt: number;
+  lastUsedAt: number;
+  inUse: boolean;
+}
+
+export class ConnectionPool {
+  private pool: Map<string, PooledConnection[]> = new Map();
+  private maxPerProvider: number;
+  private ttlMs: number;
+  private logger = new Logger('connection-pool');
+
+  constructor(maxPerProvider = 5, ttlMs = 300000) {
+    this.maxPerProvider = maxPerProvider;
+    this.ttlMs = ttlMs;
+  }
+
+  acquire(provider: string): PooledConnection {
+    const connections = this.pool.get(provider) ?? [];
+    
+    // Cleanup expired
+    const now = Date.now();
+    const active = connections.filter(c => now - c.createdAt < this.ttlMs);
+    
+    // Find available
+    const available = active.find(c => !c.inUse);
+    if (available) {
+      available.inUse = true;
+      available.lastUsedAt = now;
+      return available;
+    }
+
+    // Create new if under limit
+    if (active.length < this.maxPerProvider) {
+      const conn: PooledConnection = {
+        id: `conn_${now}_${Math.random().toString(36).slice(2, 8)}`,
+        provider,
+        createdAt: now,
+        lastUsedAt: now,
+        inUse: true,
+      };
+      active.push(conn);
+      this.pool.set(provider, active);
+      return conn;
+    }
+
+    // Wait for one (return oldest used for now)
+    const oldest = active.sort((a, b) => a.lastUsedAt - b.lastUsedAt)[0];
+    oldest.inUse = true;
+    oldest.lastUsedAt = now;
+    return oldest;
+  }
+
+  release(id: string): void {
+    for (const connections of this.pool.values()) {
+      const conn = connections.find(c => c.id === id);
+      if (conn) {
+        conn.inUse = false;
+        return;
+      }
+    }
+  }
+
+  getStats(): Record<string, { total: number; inUse: number }> {
+    const stats: Record<string, { total: number; inUse: number }> = {};
+    for (const [provider, connections] of this.pool) {
+      stats[provider] = {
+        total: connections.length,
+        inUse: connections.filter(c => c.inUse).length,
+      };
+    }
+    return stats;
+  }
+
+  drain(): void {
+    this.pool.clear();
+  }
+}
+
+// ── Request Batcher ─────────────────────────────────────────
+
+export interface BatchRequest<T> {
+  payload: T;
+  resolve: (result: unknown) => void;
+  reject: (error: Error) => void;
+}
+
+export class RequestBatcher<T> {
+  private queue: BatchRequest<T>[] = [];
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private maxBatchSize: number;
+  private delayMs: number;
+  private processor: (batch: T[]) => Promise<unknown[]>;
+  private logger = new Logger('batcher');
+
+  constructor(
+    processor: (batch: T[]) => Promise<unknown[]>,
+    maxBatchSize = 10,
+    delayMs = 50,
+  ) {
+    this.processor = processor;
+    this.maxBatchSize = maxBatchSize;
+    this.delayMs = delayMs;
+  }
+
+  add(payload: T): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      this.queue.push({ payload, resolve, reject });
+
+      if (this.queue.length >= this.maxBatchSize) {
+        this.flush();
+      } else if (!this.timer) {
+        this.timer = setTimeout(() => this.flush(), this.delayMs);
+      }
+    });
+  }
+
+  async flush(): Promise<void> {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+
+    if (this.queue.length === 0) return;
+
+    const batch = this.queue.splice(0, this.maxBatchSize);
+    try {
+      const results = await this.processor(batch.map(b => b.payload));
+      batch.forEach((req, i) => req.resolve(results[i]));
+    } catch (err) {
+      batch.forEach(req => req.reject(err as Error));
+    }
+  }
+
+  get pending(): number {
+    return this.queue.length;
+  }
+}
+
+// ── Lazy Loader ─────────────────────────────────────────────
+
+export class LazyLoader<T> {
+  private cache: Map<string, T> = new Map();
+  private loaders: Map<string, () => Promise<T>> = new Map();
+
+  register(name: string, loader: () => Promise<T>): void {
+    this.loaders.set(name, loader);
+  }
+
+  async get(name: string): Promise<T> {
+    const cached = this.cache.get(name);
+    if (cached) return cached;
+
+    const loader = this.loaders.get(name);
+    if (!loader) throw new Error(`No loader registered for "${name}"`);
+
+    const instance = await loader();
+    this.cache.set(name, instance);
+    return instance;
+  }
+
+  isLoaded(name: string): boolean {
+    return this.cache.has(name);
+  }
+
+  evict(name: string): void {
+    this.cache.delete(name);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  get loadedCount(): number {
+    return this.cache.size;
+  }
+
+  get registeredCount(): number {
+    return this.loaders.size;
+  }
+}

package/src/core/versioning.ts

@@ -0,0 +1,106 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { Logger } from './logger';
+
+// ── Versioning Types ────────────────────────────────────────
+
+export interface VersionEntry {
+  version: string;
+  timestamp: number;
+  description?: string;
+  oadSnapshot: string; // serialized OAD YAML
+}
+
+export interface Migration {
+  fromVersion: string;
+  toVersion: string;
+  migrate: (oad: Record<string, unknown>) => Record<string, unknown>;
+}
+
+// ── Version Manager ─────────────────────────────────────────
+
+export class VersionManager {
+  private versions: VersionEntry[] = [];
+  private migrations: Migration[] = [];
+  private storePath: string;
+  private logger = new Logger('versioning');
+
+  constructor(storePath?: string) {
+    this.storePath = storePath ?? '.opc-versions.json';
+    this.load();
+  }
+
+  private load(): void {
+    try {
+      if (fs.existsSync(this.storePath)) {
+        const data = JSON.parse(fs.readFileSync(this.storePath, 'utf-8'));
+        this.versions = data.versions ?? [];
+      }
+    } catch {
+      this.versions = [];
+    }
+  }
+
+  private save(): void {
+    fs.writeFileSync(this.storePath, JSON.stringify({ versions: this.versions }, null, 2));
+  }
+
+  snapshot(version: string, oadYaml: string, description?: string): void {
+    this.versions.push({
+      version,
+      timestamp: Date.now(),
+      description,
+      oadSnapshot: oadYaml,
+    });
+    this.save();
+    this.logger.info('Version snapshot saved', { version });
+  }
+
+  list(): VersionEntry[] {
+    return [...this.versions];
+  }
+
+  get(version: string): VersionEntry | undefined {
+    return this.versions.find(v => v.version === version);
+  }
+
+  getCurrent(): VersionEntry | undefined {
+    return this.versions[this.versions.length - 1];
+  }
+
+  rollback(version: string): string | null {
+    const entry = this.get(version);
+    if (!entry) {
+      this.logger.warn('Version not found', { version });
+      return null;
+    }
+    this.logger.info('Rolling back to version', { version });
+    return entry.oadSnapshot;
+  }
+
+  registerMigration(migration: Migration): void {
+    this.migrations.push(migration);
+  }
+
+  migrate(oad: Record<string, unknown>, fromVersion: string, toVersion: string): Record<string, unknown> {
+    let current = fromVersion;
+    let result = { ...oad };
+
+    while (current !== toVersion) {
+      const migration = this.migrations.find(m => m.fromVersion === current);
+      if (!migration) {
+        throw new Error(`No migration path from ${current} to ${toVersion}`);
+      }
+      result = migration.migrate(result);
+      current = migration.toVersion;
+      this.logger.info('Migration applied', { from: migration.fromVersion, to: migration.toVersion });
+    }
+
+    return result;
+  }
+
+  clear(): void {
+    this.versions = [];
+    this.save();
+  }
+}