opc-agent 1.4.0 → 2.0.1

package/src/protocols/agui/server.ts

@@ -0,0 +1,218 @@
+// AG-UI Server — SSE streaming endpoint for agent-to-frontend communication
+import { IncomingMessage, ServerResponse, Server } from 'http';
+import type { AGUIEvent, AGUIRunRequest, AGUIMessage } from './types';
+import type { BaseAgent } from '../../core/agent';
+import type { Message } from '../../core/types';
+
+// ─── AGUIEventEmitter ────────────────────────────────────────
+
+export class AGUIEventEmitter {
+  private closed = false;
+
+  constructor(private res: ServerResponse) {}
+
+  emit(event: AGUIEvent): void {
+    if (this.closed) return;
+    const data = JSON.stringify(event);
+    this.res.write(`data: ${data}\n\n`);
+  }
+
+  textStart(messageId: string): void {
+    this.emit({ type: 'TEXT_MESSAGE_START', messageId, role: 'assistant', timestamp: now() });
+  }
+
+  textContent(messageId: string, delta: string): void {
+    this.emit({ type: 'TEXT_MESSAGE_CONTENT', messageId, delta, timestamp: now() });
+  }
+
+  textEnd(messageId: string): void {
+    this.emit({ type: 'TEXT_MESSAGE_END', messageId, timestamp: now() });
+  }
+
+  toolCallStart(id: string, name: string): void {
+    this.emit({ type: 'TOOL_CALL_START', toolCallId: id, toolCallName: name, timestamp: now() });
+  }
+
+  toolCallArgs(id: string, delta: string): void {
+    this.emit({ type: 'TOOL_CALL_ARGS', toolCallId: id, delta, timestamp: now() });
+  }
+
+  toolCallEnd(id: string): void {
+    this.emit({ type: 'TOOL_CALL_END', toolCallId: id, timestamp: now() });
+  }
+
+  stateSnapshot(snapshot: Record<string, any>): void {
+    this.emit({ type: 'STATE_SNAPSHOT', snapshot, timestamp: now() });
+  }
+
+  stateDelta(delta: any[]): void {
+    this.emit({ type: 'STATE_DELTA', delta, timestamp: now() });
+  }
+
+  runStarted(runId: string, threadId?: string): void {
+    this.emit({ type: 'RUN_STARTED', runId, ...(threadId ? { threadId } : {}), timestamp: now() });
+  }
+
+  runFinished(runId: string): void {
+    this.emit({ type: 'RUN_FINISHED', runId, timestamp: now() });
+  }
+
+  runError(runId: string, message: string, code?: string): void {
+    this.emit({ type: 'RUN_ERROR', runId, message, ...(code ? { code } : {}), timestamp: now() });
+  }
+
+  stepStarted(stepId: string, stepName?: string): void {
+    this.emit({ type: 'STEP_STARTED', stepId, ...(stepName ? { stepName } : {}), timestamp: now() });
+  }
+
+  stepFinished(stepId: string): void {
+    this.emit({ type: 'STEP_FINISHED', stepId, timestamp: now() });
+  }
+
+  messagesSnapshot(messages: AGUIMessage[]): void {
+    this.emit({ type: 'MESSAGES_SNAPSHOT', messages, timestamp: now() });
+  }
+
+  custom(name: string, value: any): void {
+    this.emit({ type: 'CUSTOM', name, value, timestamp: now() });
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.res.end();
+  }
+
+  get isClosed(): boolean {
+    return this.closed;
+  }
+}
+
+// ─── AGUIServer ──────────────────────────────────────────────
+
+export class AGUIServer {
+  private agent: BaseAgent;
+  private path: string;
+
+  constructor(agent: BaseAgent, config?: { path?: string }) {
+    this.agent = agent;
+    this.path = config?.path ?? '/agui';
+  }
+
+  mount(server: Server): void {
+    const original = server.listeners('request')[0] as any;
+    server.removeAllListeners('request');
+
+    server.on('request', (req: IncomingMessage, res: ServerResponse) => {
+      const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+      if (req.method === 'POST' && url.pathname === this.path) {
+        this.handleRun(req, res);
+      } else if (req.method === 'OPTIONS' && url.pathname === this.path) {
+        res.writeHead(204, {
+          'Access-Control-Allow-Origin': '*',
+          'Access-Control-Allow-Methods': 'POST, OPTIONS',
+          'Access-Control-Allow-Headers': 'Content-Type',
+        });
+        res.end();
+      } else if (original) {
+        original(req, res);
+      } else {
+        res.writeHead(404);
+        res.end('Not Found');
+      }
+    });
+  }
+
+  async handleRun(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    let body = '';
+    for await (const chunk of req) body += chunk;
+
+    let request: AGUIRunRequest;
+    try {
+      request = JSON.parse(body);
+      if (!request.messages || !Array.isArray(request.messages)) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'messages array required' }));
+        return;
+      }
+    } catch {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Invalid JSON' }));
+      return;
+    }
+
+    // Set up SSE
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      'Access-Control-Allow-Origin': '*',
+    });
+
+    const emitter = new AGUIEventEmitter(res);
+    const runId = request.runId ?? `run_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+    try {
+      await this.streamResponse(request, emitter, runId);
+    } catch (err: any) {
+      emitter.runError(runId, err?.message ?? 'Unknown error', 'INTERNAL_ERROR');
+    } finally {
+      emitter.close();
+    }
+  }
+
+  private async streamResponse(request: AGUIRunRequest, emitter: AGUIEventEmitter, runId: string): Promise<void> {
+    emitter.runStarted(runId, request.threadId);
+
+    // Convert AG-UI messages to BaseAgent message format
+    const lastUserMsg = [...request.messages].reverse().find(m => m.role === 'user');
+    if (!lastUserMsg) {
+      emitter.runError(runId, 'No user message found', 'BAD_REQUEST');
+      return;
+    }
+
+    const message: Message = {
+      id: lastUserMsg.id || `msg_${Date.now()}`,
+      role: 'user',
+      content: lastUserMsg.content,
+      timestamp: Date.now(),
+      metadata: {
+        channel: 'agui',
+        sessionId: request.threadId ?? 'agui-default',
+      },
+    };
+
+    const messageId = `msg_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+    // Try streaming if agent supports it
+    try {
+      emitter.textStart(messageId);
+
+      let hasChunks = false;
+      for await (const chunk of this.agent.handleMessageStream(message)) {
+        hasChunks = true;
+        emitter.textContent(messageId, chunk);
+      }
+
+      if (!hasChunks) {
+        // Fallback to non-streaming
+        const response = await this.agent.handleMessage(message);
+        emitter.textContent(messageId, response.content);
+      }
+
+      emitter.textEnd(messageId);
+    } catch {
+      // Fallback to non-streaming handleMessage
+      emitter.textStart(messageId);
+      const response = await this.agent.handleMessage(message);
+      emitter.textContent(messageId, response.content);
+      emitter.textEnd(messageId);
+    }
+
+    emitter.runFinished(runId);
+  }
+}
+
+function now(): string {
+  return new Date().toISOString();
+}

package/src/protocols/agui/types.ts

@@ -0,0 +1,153 @@
+// AG-UI Protocol Types — Agent-User Interaction Protocol
+// https://docs.ag-ui.com
+
+export type AGUIEventType =
+  | 'TEXT_MESSAGE_START'
+  | 'TEXT_MESSAGE_CONTENT'
+  | 'TEXT_MESSAGE_END'
+  | 'TOOL_CALL_START'
+  | 'TOOL_CALL_ARGS'
+  | 'TOOL_CALL_END'
+  | 'STATE_SNAPSHOT'
+  | 'STATE_DELTA'
+  | 'MESSAGES_SNAPSHOT'
+  | 'RUN_STARTED'
+  | 'RUN_FINISHED'
+  | 'RUN_ERROR'
+  | 'STEP_STARTED'
+  | 'STEP_FINISHED'
+  | 'CUSTOM';
+
+export const AGUI_EVENT_TYPES: AGUIEventType[] = [
+  'TEXT_MESSAGE_START', 'TEXT_MESSAGE_CONTENT', 'TEXT_MESSAGE_END',
+  'TOOL_CALL_START', 'TOOL_CALL_ARGS', 'TOOL_CALL_END',
+  'STATE_SNAPSHOT', 'STATE_DELTA', 'MESSAGES_SNAPSHOT',
+  'RUN_STARTED', 'RUN_FINISHED', 'RUN_ERROR',
+  'STEP_STARTED', 'STEP_FINISHED', 'CUSTOM',
+];
+
+export interface AGUIEvent {
+  type: AGUIEventType;
+  timestamp: string;
+  [key: string]: any;
+}
+
+export interface TextMessageStartEvent extends AGUIEvent {
+  type: 'TEXT_MESSAGE_START';
+  messageId: string;
+  role: 'assistant';
+}
+
+export interface TextMessageContentEvent extends AGUIEvent {
+  type: 'TEXT_MESSAGE_CONTENT';
+  messageId: string;
+  delta: string;
+}
+
+export interface TextMessageEndEvent extends AGUIEvent {
+  type: 'TEXT_MESSAGE_END';
+  messageId: string;
+}
+
+export interface ToolCallStartEvent extends AGUIEvent {
+  type: 'TOOL_CALL_START';
+  toolCallId: string;
+  toolCallName: string;
+}
+
+export interface ToolCallArgsEvent extends AGUIEvent {
+  type: 'TOOL_CALL_ARGS';
+  toolCallId: string;
+  delta: string;
+}
+
+export interface ToolCallEndEvent extends AGUIEvent {
+  type: 'TOOL_CALL_END';
+  toolCallId: string;
+}
+
+export interface StateSnapshotEvent extends AGUIEvent {
+  type: 'STATE_SNAPSHOT';
+  snapshot: Record<string, any>;
+}
+
+export interface StateDeltaEvent extends AGUIEvent {
+  type: 'STATE_DELTA';
+  delta: any[]; // JSON Patch (RFC 6902)
+}
+
+export interface MessagesSnapshotEvent extends AGUIEvent {
+  type: 'MESSAGES_SNAPSHOT';
+  messages: AGUIMessage[];
+}
+
+export interface RunStartedEvent extends AGUIEvent {
+  type: 'RUN_STARTED';
+  runId: string;
+  threadId?: string;
+}
+
+export interface RunFinishedEvent extends AGUIEvent {
+  type: 'RUN_FINISHED';
+  runId: string;
+}
+
+export interface RunErrorEvent extends AGUIEvent {
+  type: 'RUN_ERROR';
+  runId: string;
+  message: string;
+  code?: string;
+}
+
+export interface StepStartedEvent extends AGUIEvent {
+  type: 'STEP_STARTED';
+  stepId: string;
+  stepName?: string;
+}
+
+export interface StepFinishedEvent extends AGUIEvent {
+  type: 'STEP_FINISHED';
+  stepId: string;
+}
+
+export interface CustomEvent extends AGUIEvent {
+  type: 'CUSTOM';
+  name: string;
+  value: any;
+}
+
+// ─── Message & Request Types ─────────────────────────────────
+
+export interface AGUIMessage {
+  id: string;
+  role: 'user' | 'assistant' | 'system' | 'tool';
+  content: string;
+  name?: string;
+  toolCallId?: string;
+  toolCalls?: AGUIToolCall[];
+}
+
+export interface AGUIToolCall {
+  id: string;
+  type: 'function';
+  function: { name: string; arguments: string };
+}
+
+export interface AGUIRunRequest {
+  threadId?: string;
+  runId?: string;
+  messages: AGUIMessage[];
+  tools?: AGUIToolDefinition[];
+  context?: any[];
+  forwardedProps?: Record<string, any>;
+}
+
+export interface AGUIToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, any>; // JSON Schema
+}
+
+export function isValidEventType(type: string): type is AGUIEventType {
+  return AGUI_EVENT_TYPES.includes(type as AGUIEventType);
+}

package/src/protocols/index.ts

@@ -0,0 +1,2 @@
+// Protocols barrel export
+export * from './agui';

package/src/protocols/mcp/agent-tools.ts

@@ -0,0 +1,134 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import type { MCPServerToolDefinition, MCPResourceDefinition } from './types';
+
+/**
+ * Convert an OPC agent into MCP tool definitions.
+ * Works with any agent-like object that has name/handleMessage/brain.
+ */
+export function agentToMCPTools(agent: any): MCPServerToolDefinition[] {
+  const tools: MCPServerToolDefinition[] = [];
+  const agentName = agent?.name || agent?.config?.name || 'agent';
+
+  // 1. Chat tool
+  tools.push({
+    name: 'chat',
+    description: `Chat with ${agentName} agent`,
+    inputSchema: {
+      type: 'object',
+      properties: { message: { type: 'string', description: 'Message to send to the agent' } },
+      required: ['message'],
+    },
+    handler: async (args: any) => {
+      if (typeof agent.handleMessage === 'function') {
+        const result = await agent.handleMessage({
+          role: 'user', content: args.message, channel: 'mcp',
+        });
+        return typeof result === 'string' ? result : result?.content || JSON.stringify(result);
+      }
+      return `Agent ${agentName} does not support handleMessage`;
+    },
+  });
+
+  // 2. Memory search
+  tools.push({
+    name: 'memory_search',
+    description: 'Search agent memory/knowledge',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string', description: 'Search query' } },
+      required: ['query'],
+    },
+    handler: async (args: any) => {
+      const brain = agent.brain || agent.memory || agent.memoryStore;
+      if (brain && typeof brain.query === 'function') {
+        return await brain.query(args.query);
+      }
+      if (brain && typeof brain.search === 'function') {
+        return await brain.search(args.query);
+      }
+      return 'Memory search not available';
+    },
+  });
+
+  // 3. Memory store
+  tools.push({
+    name: 'memory_store',
+    description: 'Store knowledge in agent memory',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        slug: { type: 'string', description: 'Identifier/key for the memory entry' },
+        content: { type: 'string', description: 'Content to store' },
+      },
+      required: ['slug', 'content'],
+    },
+    handler: async (args: any) => {
+      const brain = agent.brain || agent.memory || agent.memoryStore;
+      if (brain && typeof brain.put === 'function') {
+        await brain.put(args.slug, args.content);
+        return `Stored: ${args.slug}`;
+      }
+      if (brain && typeof brain.store === 'function') {
+        await brain.store(args.slug, args.content);
+        return `Stored: ${args.slug}`;
+      }
+      return 'Memory store not available';
+    },
+  });
+
+  // 4. Expose agent skills as individual tools
+  const skills = agent.skills || agent.skillRegistry?.list?.() || [];
+  for (const skill of Array.isArray(skills) ? skills : []) {
+    const skillName = skill.name || skill.id;
+    if (!skillName) continue;
+    tools.push({
+      name: `skill_${skillName}`,
+      description: skill.description || `Execute ${skillName} skill`,
+      inputSchema: skill.inputSchema || {
+        type: 'object',
+        properties: { input: { type: 'string' } },
+        required: ['input'],
+      },
+      handler: async (args: any) => {
+        if (typeof skill.execute === 'function') {
+          return await skill.execute(args);
+        }
+        return `Skill ${skillName} not executable`;
+      },
+    });
+  }
+
+  return tools;
+}
+
+/**
+ * Expose agent files and brain pages as MCP resources.
+ */
+export function agentToMCPResources(agent: any, agentDir: string): MCPResourceDefinition[] {
+  const resources: MCPResourceDefinition[] = [];
+
+  // Standard agent files
+  const standardFiles = [
+    { name: 'SOUL.md', desc: 'Agent personality and identity' },
+    { name: 'CONTEXT.md', desc: 'Agent context' },
+    { name: 'AGENTS.md', desc: 'Agent instructions' },
+    { name: 'USER.md', desc: 'User profile' },
+    { name: 'agent.yaml', desc: 'Agent OAD configuration' },
+  ];
+
+  for (const file of standardFiles) {
+    const filePath = join(agentDir, file.name);
+    if (existsSync(filePath)) {
+      resources.push({
+        uri: `agent:///${file.name}`,
+        name: file.name,
+        description: file.desc,
+        mimeType: file.name.endsWith('.yaml') ? 'text/yaml' : 'text/markdown',
+        handler: async () => readFileSync(filePath, 'utf-8'),
+      });
+    }
+  }
+
+  return resources;
+}

package/src/protocols/mcp/index.ts

@@ -0,0 +1,8 @@
+export type {
+  MCPServerConfig, MCPServerToolDefinition, MCPResourceDefinition,
+  MCPPromptDefinition, MCPPromptArgument, MCPPromptMessage,
+  JsonRpcRequest, JsonRpcResponse,
+} from './types';
+export { MCP_ERRORS } from './types';
+export { MCPServer } from './server';
+export { agentToMCPTools, agentToMCPResources } from './agent-tools';