opc-agent 2.0.0 → 2.0.1

package/src/protocols/a2a/client.ts

@@ -0,0 +1,132 @@
+import type { A2AAgentCard, A2ATask, A2AMessage, JsonRpcResponse } from './types';
+
+export class A2AClient {
+  private agentUrl: string;
+  private auth?: { scheme: string; token: string };
+
+  constructor(agentUrl: string, auth?: { scheme: string; token: string }) {
+    this.agentUrl = agentUrl.endsWith('/') ? agentUrl.slice(0, -1) : agentUrl;
+    this.auth = auth;
+  }
+
+  private getHeaders(): Record<string, string> {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (this.auth) {
+      if (this.auth.scheme === 'bearer') {
+        headers['Authorization'] = `Bearer ${this.auth.token}`;
+      } else if (this.auth.scheme === 'apiKey') {
+        headers['X-API-Key'] = this.auth.token;
+      }
+    }
+    return headers;
+  }
+
+  private async rpc(method: string, params?: any): Promise<any> {
+    const body = JSON.stringify({
+      jsonrpc: '2.0',
+      id: `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      method,
+      params,
+    });
+
+    const res = await fetch(this.agentUrl, {
+      method: 'POST',
+      headers: this.getHeaders(),
+      body,
+    });
+
+    const json: JsonRpcResponse = await res.json() as any;
+    if (json.error) {
+      const err: any = new Error(json.error.message);
+      err.code = json.error.code;
+      throw err;
+    }
+    return json.result;
+  }
+
+  async getAgentCard(): Promise<A2AAgentCard> {
+    const res = await fetch(`${this.agentUrl}/.well-known/agent.json`, {
+      headers: this.getHeaders(),
+    });
+    if (!res.ok) throw new Error(`Failed to fetch agent card: ${res.status}`);
+    return res.json() as any;
+  }
+
+  async sendTask(message: A2AMessage, options?: { taskId?: string; sessionId?: string }): Promise<A2ATask> {
+    return this.rpc('tasks/send', {
+      id: options?.taskId || `task_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      sessionId: options?.sessionId,
+      message,
+    });
+  }
+
+  async sendTaskSubscribe(
+    message: A2AMessage,
+    onEvent: (event: any) => void,
+    options?: { taskId?: string },
+  ): Promise<void> {
+    const body = JSON.stringify({
+      jsonrpc: '2.0',
+      id: `${Date.now()}`,
+      method: 'tasks/sendSubscribe',
+      params: {
+        id: options?.taskId || `task_${Date.now()}`,
+        message,
+      },
+    });
+
+    const res = await fetch(this.agentUrl, {
+      method: 'POST',
+      headers: this.getHeaders(),
+      body,
+    });
+
+    if (!res.ok || !res.body) throw new Error(`SSE failed: ${res.status}`);
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          try {
+            onEvent(JSON.parse(line.slice(6)));
+          } catch { /* skip malformed */ }
+        }
+      }
+    }
+  }
+
+  async getTask(taskId: string): Promise<A2ATask> {
+    return this.rpc('tasks/get', { id: taskId });
+  }
+
+  async cancelTask(taskId: string): Promise<A2ATask> {
+    return this.rpc('tasks/cancel', { id: taskId });
+  }
+
+  async sendText(text: string, options?: { taskId?: string }): Promise<string> {
+    const task = await this.sendTask(
+      { role: 'user', parts: [{ type: 'text', text }] },
+      options,
+    );
+
+    // Extract text from last agent message
+    const agentMessages = task.history.filter(m => m.role === 'agent');
+    const last = agentMessages[agentMessages.length - 1];
+    if (!last) return '';
+
+    return last.parts
+      .filter(p => p.type === 'text')
+      .map(p => (p as any).text)
+      .join('\n');
+  }
+}

package/src/protocols/a2a/index.ts

@@ -0,0 +1,8 @@
+export type {
+  A2AAgentCard, A2AAgentSkill, A2ATask, A2ATaskStatus, A2ATaskState,
+  A2AMessage, A2AMessagePart, A2AArtifact, JsonRpcRequest, JsonRpcResponse,
+} from './types';
+export { JSON_RPC_ERRORS } from './types';
+export { A2AServer } from './server';
+export { A2AClient } from './client';
+export { oadToAgentCard } from './utils';

package/src/protocols/a2a/server.ts

@@ -0,0 +1,333 @@
+import { createServer, IncomingMessage, ServerResponse } from 'http';
+import type {
+  A2AAgentCard, A2ATask, A2ATaskStatus, A2AMessage, A2AArtifact,
+  JsonRpcRequest, JsonRpcResponse,
+} from './types';
+import { JSON_RPC_ERRORS } from './types';
+import { oadToAgentCard } from './utils';
+
+export class A2AServer {
+  private tasks: Map<string, A2ATask> = new Map();
+  private agent: any;
+  private card: A2AAgentCard;
+  private server: any;
+  private taskHandler?: (task: A2ATask) => Promise<A2ATask>;
+
+  constructor(agent: any, config?: { card?: Partial<A2AAgentCard>; oad?: any; port?: number }) {
+    this.agent = agent;
+
+    // Build card from OAD if available, then overlay explicit config
+    const baseCard = config?.oad
+      ? oadToAgentCard(config.oad, config?.card?.url || `http://localhost:${config?.port || 3001}`)
+      : {
+          name: agent?.name || 'opc-agent',
+          description: agent?.config?.systemPrompt?.slice(0, 200) || 'OPC Agent',
+          url: `http://localhost:${config?.port || 3001}`,
+          version: '1.0.0',
+          capabilities: { streaming: true, pushNotifications: false, stateTransitionHistory: true },
+          skills: [],
+          defaultInputModes: ['text'],
+          defaultOutputModes: ['text'],
+        };
+
+    this.card = { ...baseCard, ...config?.card } as A2AAgentCard;
+  }
+
+  /** Set custom handler for processing tasks */
+  onTask(handler: (task: A2ATask) => Promise<A2ATask>): void {
+    this.taskHandler = handler;
+  }
+
+  getAgentCard(): A2AAgentCard {
+    return this.card;
+  }
+
+  getTasks(): A2ATask[] {
+    return Array.from(this.tasks.values());
+  }
+
+  /** Mount A2A routes on an existing HTTP server handler */
+  mount(handleRequest: (req: IncomingMessage, res: ServerResponse) => void): (req: IncomingMessage, res: ServerResponse) => void {
+    return (req: IncomingMessage, res: ServerResponse) => {
+      const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+
+      // /.well-known/agent.json
+      if (url.pathname === '/.well-known/agent.json' && req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(this.card, null, 2));
+        return;
+      }
+
+      // JSON-RPC endpoint
+      if (url.pathname === '/' && req.method === 'POST') {
+        this.handleHTTP(req, res);
+        return;
+      }
+
+      // Fall through to original handler
+      handleRequest(req, res);
+    };
+  }
+
+  async start(port: number): Promise<void> {
+    this.card.url = `http://localhost:${port}`;
+    return new Promise((resolve) => {
+      this.server = createServer((req, res) => {
+        const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+
+        if (url.pathname === '/.well-known/agent.json' && req.method === 'GET') {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify(this.card, null, 2));
+          return;
+        }
+
+        if (url.pathname === '/' && req.method === 'POST') {
+          this.handleHTTP(req, res);
+          return;
+        }
+
+        res.writeHead(404);
+        res.end('Not Found');
+      });
+
+      this.server.listen(port, () => resolve());
+    });
+  }
+
+  async stop(): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.server) {
+        this.server.close(() => resolve());
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  private async handleHTTP(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const body = await this.readBody(req);
+    let rpcReq: JsonRpcRequest;
+
+    try {
+      rpcReq = JSON.parse(body);
+    } catch {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(this.rpcError(null, JSON_RPC_ERRORS.PARSE_ERROR, 'Parse error')));
+      return;
+    }
+
+    if (!rpcReq.jsonrpc || rpcReq.jsonrpc !== '2.0' || !rpcReq.method) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(this.rpcError(rpcReq?.id ?? null, JSON_RPC_ERRORS.INVALID_REQUEST, 'Invalid Request')));
+      return;
+    }
+
+    // SSE for streaming
+    if (rpcReq.method === 'tasks/sendSubscribe') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+      });
+
+      try {
+        await this.tasksSendSubscribe(rpcReq.params, (event: any) => {
+          res.write(`data: ${JSON.stringify(event)}\n\n`);
+        });
+      } catch (err: any) {
+        res.write(`data: ${JSON.stringify({ error: err.message })}\n\n`);
+      }
+      res.end();
+      return;
+    }
+
+    const result = await this.handleRPC(rpcReq.method, rpcReq.params, rpcReq.id);
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(result));
+  }
+
+  private async handleRPC(method: string, params: any, id: string | number | null): Promise<JsonRpcResponse> {
+    try {
+      let result: any;
+      switch (method) {
+        case 'tasks/send':
+          result = await this.tasksSend(params);
+          break;
+        case 'tasks/get':
+          result = await this.tasksGet(params);
+          break;
+        case 'tasks/cancel':
+          result = await this.tasksCancel(params);
+          break;
+        default:
+          return this.rpcError(id, JSON_RPC_ERRORS.METHOD_NOT_FOUND, `Method not found: ${method}`);
+      }
+      return { jsonrpc: '2.0', id: id!, result };
+    } catch (err: any) {
+      if (err.code) {
+        return this.rpcError(id, err.code, err.message);
+      }
+      return this.rpcError(id, JSON_RPC_ERRORS.INTERNAL_ERROR, err.message);
+    }
+  }
+
+  async tasksSend(params: { id: string; sessionId?: string; message: A2AMessage; metadata?: any }): Promise<A2ATask> {
+    const taskId = params.id;
+    const sessionId = params.sessionId || `session_${Date.now()}`;
+
+    let task = this.tasks.get(taskId);
+    if (!task) {
+      task = {
+        id: taskId,
+        sessionId,
+        status: { state: 'submitted', timestamp: new Date().toISOString() },
+        history: [],
+        artifacts: [],
+        metadata: params.metadata,
+      };
+      this.tasks.set(taskId, task);
+    }
+
+    // Add user message to history
+    task.history.push(params.message);
+    task.status = { state: 'working', timestamp: new Date().toISOString() };
+
+    // Process with custom handler or agent
+    if (this.taskHandler) {
+      task = await this.taskHandler(task);
+      this.tasks.set(taskId, task);
+      return task;
+    }
+
+    // Default: use agent.handleMessage if available
+    if (this.agent?.handleMessage) {
+      try {
+        const textContent = params.message.parts
+          .filter((p: any) => p.type === 'text')
+          .map((p: any) => p.text)
+          .join('\n');
+
+        const response = await this.agent.handleMessage({
+          id: taskId,
+          role: 'user',
+          content: textContent,
+          timestamp: Date.now(),
+        });
+
+        const agentMessage: A2AMessage = {
+          role: 'agent',
+          parts: [{ type: 'text', text: response.content }],
+        };
+
+        task.history.push(agentMessage);
+        task.status = { state: 'completed', message: agentMessage, timestamp: new Date().toISOString() };
+      } catch (err: any) {
+        task.status = {
+          state: 'failed',
+          message: { role: 'agent', parts: [{ type: 'text', text: err.message }] },
+          timestamp: new Date().toISOString(),
+        };
+      }
+    } else {
+      // No agent — just mark completed with echo
+      const agentMessage: A2AMessage = {
+        role: 'agent',
+        parts: [{ type: 'text', text: 'No agent handler configured' }],
+      };
+      task.history.push(agentMessage);
+      task.status = { state: 'completed', message: agentMessage, timestamp: new Date().toISOString() };
+    }
+
+    this.tasks.set(taskId, task);
+    return task;
+  }
+
+  async tasksSendSubscribe(params: any, onEvent: (event: any) => void): Promise<void> {
+    const taskId = params.id;
+    const sessionId = params.sessionId || `session_${Date.now()}`;
+
+    let task: A2ATask = {
+      id: taskId,
+      sessionId,
+      status: { state: 'submitted', timestamp: new Date().toISOString() },
+      history: [],
+      artifacts: [],
+      metadata: params.metadata,
+    };
+    this.tasks.set(taskId, task);
+    task.history.push(params.message);
+
+    // Emit submitted
+    onEvent({ jsonrpc: '2.0', result: { id: taskId, status: task.status } });
+
+    task.status = { state: 'working', timestamp: new Date().toISOString() };
+    onEvent({ jsonrpc: '2.0', result: { id: taskId, status: task.status } });
+
+    // Process
+    if (this.agent?.handleMessage) {
+      const textContent = params.message.parts
+        .filter((p: any) => p.type === 'text')
+        .map((p: any) => p.text)
+        .join('\n');
+
+      try {
+        const response = await this.agent.handleMessage({
+          id: taskId, role: 'user', content: textContent, timestamp: Date.now(),
+        });
+
+        const agentMessage: A2AMessage = { role: 'agent', parts: [{ type: 'text', text: response.content }] };
+        task.history.push(agentMessage);
+        task.status = { state: 'completed', message: agentMessage, timestamp: new Date().toISOString() };
+      } catch (err: any) {
+        task.status = { state: 'failed', message: { role: 'agent', parts: [{ type: 'text', text: err.message }] }, timestamp: new Date().toISOString() };
+      }
+    } else {
+      const msg: A2AMessage = { role: 'agent', parts: [{ type: 'text', text: 'No agent handler' }] };
+      task.history.push(msg);
+      task.status = { state: 'completed', message: msg, timestamp: new Date().toISOString() };
+    }
+
+    this.tasks.set(taskId, task);
+    onEvent({ jsonrpc: '2.0', result: { id: taskId, status: task.status, history: task.history } });
+  }
+
+  async tasksGet(params: { id: string; historyLength?: number }): Promise<A2ATask> {
+    const task = this.tasks.get(params.id);
+    if (!task) {
+      const err: any = new Error(`Task not found: ${params.id}`);
+      err.code = JSON_RPC_ERRORS.TASK_NOT_FOUND;
+      throw err;
+    }
+
+    if (params.historyLength !== undefined) {
+      return { ...task, history: task.history.slice(-params.historyLength) };
+    }
+    return task;
+  }
+
+  async tasksCancel(params: { id: string }): Promise<A2ATask> {
+    const task = this.tasks.get(params.id);
+    if (!task) {
+      const err: any = new Error(`Task not found: ${params.id}`);
+      err.code = JSON_RPC_ERRORS.TASK_NOT_FOUND;
+      throw err;
+    }
+
+    task.status = { state: 'canceled', timestamp: new Date().toISOString() };
+    this.tasks.set(params.id, task);
+    return task;
+  }
+
+  private rpcError(id: any, code: number, message: string): JsonRpcResponse {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+  }
+
+  private readBody(req: IncomingMessage): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      req.on('data', (chunk: Buffer) => chunks.push(chunk));
+      req.on('end', () => resolve(Buffer.concat(chunks).toString()));
+      req.on('error', reject);
+    });
+  }
+}

package/src/protocols/a2a/types.ts

@@ -0,0 +1,88 @@
+// Google A2A Protocol Types — https://google.github.io/A2A/
+
+export interface A2AAgentCard {
+  name: string;
+  description: string;
+  url: string;
+  version: string;
+  capabilities: {
+    streaming: boolean;
+    pushNotifications: boolean;
+    stateTransitionHistory: boolean;
+  };
+  skills: A2AAgentSkill[];
+  defaultInputModes: string[];
+  defaultOutputModes: string[];
+  authentication?: {
+    schemes: string[];
+  };
+}
+
+export interface A2AAgentSkill {
+  id: string;
+  name: string;
+  description: string;
+  tags: string[];
+  examples?: string[];
+}
+
+export interface A2ATask {
+  id: string;
+  sessionId: string;
+  status: A2ATaskStatus;
+  history: A2AMessage[];
+  artifacts: A2AArtifact[];
+  metadata?: Record<string, any>;
+}
+
+export type A2ATaskState = 'submitted' | 'working' | 'input-required' | 'completed' | 'canceled' | 'failed';
+
+export interface A2ATaskStatus {
+  state: A2ATaskState;
+  message?: A2AMessage;
+  timestamp: string;
+}
+
+export interface A2AMessage {
+  role: 'user' | 'agent';
+  parts: A2AMessagePart[];
+}
+
+export type A2AMessagePart =
+  | { type: 'text'; text: string }
+  | { type: 'file'; file: { name: string; mimeType: string; bytes?: string; uri?: string } }
+  | { type: 'data'; data: Record<string, any> };
+
+export interface A2AArtifact {
+  name: string;
+  description?: string;
+  parts: A2AMessagePart[];
+  index: number;
+  append?: boolean;
+  lastChunk?: boolean;
+}
+
+export interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id: string | number;
+  method: string;
+  params?: any;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  result?: any;
+  error?: { code: number; message: string; data?: any };
+}
+
+// Standard JSON-RPC error codes
+export const JSON_RPC_ERRORS = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  TASK_NOT_FOUND: -32001,
+  TASK_CANCELED: -32002,
+} as const;

package/src/protocols/a2a/utils.ts

@@ -0,0 +1,50 @@
+import type { A2AAgentCard, A2AAgentSkill } from './types';
+
+/**
+ * Convert an OAD (Open Agent Definition) document to an A2A AgentCard.
+ */
+export function oadToAgentCard(oad: any, baseUrl: string): A2AAgentCard {
+  const meta = oad?.metadata || {};
+  const spec = oad?.spec || {};
+
+  // Extract skills from OAD
+  const skills: A2AAgentSkill[] = (spec.skills || []).map((s: any, i: number) => ({
+    id: s.id || s.name || `skill-${i}`,
+    name: s.name || `Skill ${i}`,
+    description: s.description || '',
+    tags: s.tags || [],
+    examples: s.examples || [],
+  }));
+
+  // If no skills defined, create one from the agent description
+  if (skills.length === 0 && (spec.systemPrompt || meta.description)) {
+    skills.push({
+      id: 'default',
+      name: meta.name || 'default',
+      description: meta.description || spec.systemPrompt?.slice(0, 200) || 'General agent capability',
+      tags: ['general'],
+    });
+  }
+
+  // Detect capabilities from OAD
+  const channels = spec.channels || [];
+  const hasStreaming = channels.some((c: any) => c.type === 'websocket' || c.type === 'web');
+
+  const url = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+
+  return {
+    name: meta.name || 'opc-agent',
+    description: meta.description || '',
+    url,
+    version: meta.version || '1.0.0',
+    capabilities: {
+      streaming: hasStreaming,
+      pushNotifications: false,
+      stateTransitionHistory: true,
+    },
+    skills,
+    defaultInputModes: ['text'],
+    defaultOutputModes: ['text'],
+    authentication: spec.auth ? { schemes: [spec.auth.type || 'bearer'] } : undefined,
+  };
+}

package/src/protocols/agui/client.ts

@@ -0,0 +1,83 @@
+// AG-UI Client — Connects to AG-UI SSE endpoint
+import type { AGUIEvent, AGUIRunRequest, AGUIMessage } from './types';
+import { isValidEventType } from './types';
+
+export class AGUIClient {
+  private endpoint: string;
+  private controller?: AbortController;
+
+  constructor(endpoint: string) {
+    this.endpoint = endpoint;
+  }
+
+  async run(request: AGUIRunRequest, onEvent: (event: AGUIEvent) => void): Promise<void> {
+    this.controller = new AbortController();
+
+    const res = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(request),
+      signal: this.controller.signal,
+    });
+
+    if (!res.ok) {
+      throw new Error(`AG-UI request failed: ${res.status} ${res.statusText}`);
+    }
+
+    if (!res.body) {
+      throw new Error('No response body');
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+
+        for (const line of lines) {
+          if (line.startsWith('data: ')) {
+            try {
+              const event: AGUIEvent = JSON.parse(line.slice(6));
+              if (event.type && isValidEventType(event.type)) {
+                onEvent(event);
+              }
+            } catch {
+              // skip malformed events
+            }
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+
+  async sendText(text: string, onChunk: (text: string) => void): Promise<string> {
+    let fullText = '';
+    const request: AGUIRunRequest = {
+      messages: [{ id: `msg_${Date.now()}`, role: 'user', content: text }],
+    };
+
+    await this.run(request, (event) => {
+      if (event.type === 'TEXT_MESSAGE_CONTENT') {
+        const delta = (event as any).delta as string;
+        fullText += delta;
+        onChunk(delta);
+      }
+    });
+
+    return fullText;
+  }
+
+  abort(): void {
+    this.controller?.abort();
+    this.controller = undefined;
+  }
+}

package/src/protocols/agui/index.ts

@@ -0,0 +1,4 @@
+// AG-UI Protocol — barrel export
+export * from './types';
+export { AGUIServer, AGUIEventEmitter } from './server';
+export { AGUIClient } from './client';