agentstudio 0.3.0 → 0.3.1

package/backend/src/services/a2a/a2aSdkMcp.ts

@@ -0,0 +1,208 @@
+/**
+ * A2A Client SDK MCP Server
+ *
+ * Implements an in-process MCP server using Claude Agent SDK that enables
+ * agents to call external A2A-compatible agents with dynamic tool documentation.
+ *
+ * Features:
+ * - Dynamic tool description based on project's A2A configuration
+ * - SessionId support for multi-turn conversations
+ * - Integration with existing callExternalAgent function
+ */
+
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { loadA2AConfig } from './a2aConfigService.js';
+import { callExternalAgent } from './a2aClientTool.js';
+import type { CallExternalAgentInput } from '../../types/a2a.js';
+
+/**
+ * Generate dynamic tool description based on project's A2A configuration
+ *
+ * Lists all enabled external agents to help Claude decide which agent to call.
+ *
+ * @param projectId - Project identifier
+ * @returns Tool description with available agents
+ */
+async function generateToolDescription(projectId: string): Promise<string> {
+    const config = await loadA2AConfig(projectId);
+
+    if (!config) {
+        return 'Call an external A2A-compatible agent. No A2A configuration found for this project.';
+    }
+
+    const enabledAgents = config.allowedAgents.filter((a) => a.enabled);
+
+    let description = 'Call an external A2A-compatible agent to delegate tasks or retrieve information. ';
+
+    if (enabledAgents.length > 0) {
+        description += '\n\nAvailable external agents:\n';
+        for (const agent of enabledAgents) {
+            description += `\n• ${agent.name}`;
+            if (agent.description) {
+                description += `: ${agent.description}`;
+            }
+            description += `\n  URL: ${agent.url}`;
+        }
+        description += '\n\nUse the agentUrl parameter to specify which agent to call. Please also include the agentName parameter for better UI display.';
+    } else {
+        description += 'No external agents are currently configured or enabled.';
+    }
+
+    return description;
+}
+
+/**
+ * Create SDK MCP server for A2A client tool
+ *
+ * This server runs in-process within the Claude Agent SDK and provides
+ * a tool for calling external A2A agents.
+ *
+ * @param projectId - Project identifier for loading A2A configuration
+ * @param streamEnabled - Whether to enable streaming for external agent calls (default: false)
+ * @returns SDK MCP server instance and tool definitions
+ */
+export async function createA2ASdkMcpServer(projectId: string, streamEnabled: boolean = false) {
+    // Generate dynamic tool description
+    const toolDescription = await generateToolDescription(projectId);
+
+    // Define the tool
+    const callExternalAgentTool = tool(
+        'call_external_agent',
+        toolDescription,
+        {
+            agentUrl: z
+                .string()
+                .url()
+                .describe('Target A2A agent URL (e.g., https://analytics.example.com/a2a/agent-id)'),
+            agentName: z
+                .string()
+                .optional()
+                .describe('Name of the agent being called (e.g., "AI Editor"). Please provide this for better UI display.'),
+            message: z
+                .string()
+                .min(1)
+                .max(10000)
+                .describe('Message or task description to send to the external agent'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Session ID for continuing a conversation with the external agent. Provide this if you want to continue a previous session.'),
+            useTask: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Use async task mode for long-running operations (default: false for synchronous)'),
+
+        },
+        async (args) => {
+            try {
+                // Prepare input for callExternalAgent
+                // Use streamEnabled from server configuration, not user input
+                const input: CallExternalAgentInput = {
+                    agentUrl: args.agentUrl,
+                    message: args.message,
+                    sessionId: args.sessionId,
+                    useTask: args.useTask,
+                    stream: streamEnabled,  // Use server-configured stream setting
+                };
+
+                // Call external agent using existing function
+                const result = await callExternalAgent(input, projectId);
+
+                // Format response for Claude
+                if (result.success) {
+                    const content: any[] = [];
+                    let responseText = '';
+
+                    if (result.data) {
+                        if (typeof result.data === 'string') {
+                            responseText = result.data;
+                        } else {
+                            responseText = JSON.stringify(result.data, null, 2);
+                        }
+                    }
+
+                    // 1. Add Agent Response
+                    content.push({
+                        type: 'text',
+                        text: responseText || 'External agent call completed successfully.',
+                    });
+
+                    // Include task information if async mode
+                    if (result.taskId) {
+                        let taskInfo = `Task ID: ${result.taskId}`;
+                        if (result.status) {
+                            taskInfo += `\nStatus: ${result.status}`;
+                        }
+                        content.push({
+                            type: 'text',
+                            text: taskInfo,
+                        });
+                    }
+
+                    // 2. Add Session ID Info (if present)
+                    if (result.sessionId) {
+                        content.push({
+                            type: 'text',
+                            text: `[System] Session ID: ${result.sessionId}\nTo continue this conversation, please use this "sessionId" in your next call to this agent.`,
+                        });
+                    }
+
+                    return { content };
+                } else {
+                    // Handle error response
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error calling external agent: ${result.error || 'Unknown error'}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            } catch (error) {
+                // Handle unexpected errors
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                console.error('[A2A SDK MCP] Error executing call_external_agent tool:', error);
+
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Failed to call external agent: ${errorMessage}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    // Create SDK MCP server with the tool
+    const server = createSdkMcpServer({
+        name: 'a2a-client',
+        version: '1.0.0',
+        tools: [callExternalAgentTool],
+    });
+
+    // Return both server and tool for testing
+    return {
+        server,
+        tool: callExternalAgentTool,
+    };
+}
+
+/**
+ * Get tool name as it appears to Claude
+ *
+ * SDK MCP tools are prefixed with "mcp__{server_name}__"
+ *
+ * @returns Full tool name
+ */
+export function getA2AToolName(): string {
+    return 'mcp__a2a-client__call_external_agent';
+}
+
+

package/backend/src/services/a2a/a2aStreamEvents.ts

@@ -0,0 +1,166 @@
+/**
+ * A2A Stream Events
+ * 
+ * Global EventEmitter for notifying about A2A streaming call status.
+ * This allows the MCP tool to communicate with the main SSE stream
+ * to notify the frontend about new streaming sessions.
+ * 
+ * Uses A2A standard protocol event types:
+ * - Message: Direct response message
+ * - Task: Task object for complex processing
+ * - TaskStatusUpdateEvent: Task status updates with optional message content
+ * - TaskArtifactUpdateEvent: Artifact updates (files, data)
+ */
+
+import { EventEmitter } from 'events';
+
+// Import A2A standard types
+import type {
+  Message,
+  Task,
+  TaskStatusUpdateEvent,
+  TaskArtifactUpdateEvent,
+  Part,
+  TextPart,
+  FilePart,
+  DataPart,
+  TaskState,
+} from '@a2a-js/sdk';
+
+// Re-export A2A types for use in other modules
+export type {
+  Message,
+  Task,
+  TaskStatusUpdateEvent,
+  TaskArtifactUpdateEvent,
+  Part,
+  TextPart,
+  FilePart,
+  DataPart,
+  TaskState,
+};
+
+/**
+ * A2A Stream Event Data - union of all possible A2A streaming events
+ */
+export type A2AStreamEventData = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
+
+/**
+ * Event payload for A2A stream start notification
+ */
+export interface A2AStreamStartEvent {
+  type: 'a2a_stream_start';
+  sessionId: string;
+  contextId?: string;  // A2A contextId for task correlation
+  taskId?: string;     // A2A taskId if available
+  projectId: string;
+  agentUrl: string;
+  message: string;
+  timestamp: number;
+}
+
+/**
+ * Event payload for A2A stream data notification (A2A standard event)
+ */
+export interface A2AStreamDataEvent {
+  type: 'a2a_stream_data';
+  sessionId: string;
+  projectId: string;
+  agentUrl: string;           // Agent URL for frontend matching
+  event: A2AStreamEventData;  // The actual A2A standard event
+  timestamp: number;
+}
+
+/**
+ * Event payload for A2A stream end notification
+ */
+export interface A2AStreamEndEvent {
+  type: 'a2a_stream_end';
+  sessionId: string;
+  projectId: string;
+  success: boolean;
+  error?: string;
+  finalState?: TaskState;  // Final task state if available
+  timestamp: number;
+}
+
+export type A2AStreamEvent = A2AStreamStartEvent | A2AStreamDataEvent | A2AStreamEndEvent;
+
+/**
+ * Global EventEmitter for A2A stream notifications
+ * 
+ * Events:
+ * - 'a2a_stream_start': Emitted when a streaming A2A call begins
+ * - 'a2a_stream_data': Emitted for each A2A standard event received
+ * - 'a2a_stream_end': Emitted when the streaming call completes
+ */
+class A2AStreamEventEmitter extends EventEmitter {
+  constructor() {
+    super();
+    // Increase max listeners since multiple SSE connections may listen
+    this.setMaxListeners(100);
+  }
+
+  /**
+   * Emit a2a_stream_start event
+   */
+  emitStreamStart(payload: Omit<A2AStreamStartEvent, 'type' | 'timestamp'>): void {
+    const event: A2AStreamStartEvent = {
+      ...payload,
+      type: 'a2a_stream_start',
+      timestamp: Date.now(),
+    };
+    this.emit('a2a_stream_start', event);
+  }
+
+  /**
+   * Emit a2a_stream_data event with A2A standard event
+   */
+  emitStreamData(payload: Omit<A2AStreamDataEvent, 'type' | 'timestamp'>): void {
+    const event: A2AStreamDataEvent = {
+      ...payload,
+      type: 'a2a_stream_data',
+      timestamp: Date.now(),
+    };
+    this.emit('a2a_stream_data', event);
+  }
+
+  /**
+   * Emit a2a_stream_end event
+   */
+  emitStreamEnd(payload: Omit<A2AStreamEndEvent, 'type' | 'timestamp'>): void {
+    const event: A2AStreamEndEvent = {
+      ...payload,
+      type: 'a2a_stream_end',
+      timestamp: Date.now(),
+    };
+    this.emit('a2a_stream_end', event);
+  }
+}
+
+// Singleton instance
+export const a2aStreamEventEmitter = new A2AStreamEventEmitter();
+
+/**
+ * Helper function to extract text content from A2A Part array
+ */
+export function extractTextFromParts(parts: Part[]): string {
+  return parts
+    .filter((part): part is TextPart => part.kind === 'text')
+    .map(part => part.text)
+    .join('');
+}
+
+/**
+ * Helper function to create a text part
+ */
+export function createTextPart(text: string): TextPart {
+  return { kind: 'text', text };
+}
+
+/**
+ * Helper function to determine if an event is final (stream should close)
+ */
+export function isTerminalState(state: TaskState): boolean {
+  return ['completed', 'failed', 'canceled', 'rejected'].includes(state);
+}

package/backend/src/services/a2a/agentCardService.ts

@@ -0,0 +1,256 @@
+/**
+ * Agent Card Service
+ *
+ * Generates Agent Cards from AgentConfig for A2A protocol discovery.
+ * Agent Cards are auto-generated and should never be manually maintained.
+ *
+ * Pure function approach: generateAgentCard(agentConfig, projectContext) -> AgentCard
+ *
+ * Phase 4: US2 - Agent Card Auto-Generation
+ */
+
+import type { AgentConfig, AgentTool } from '../../types/agents.js';
+import type { AgentCard, Skill, SecurityScheme, JSONSchema } from '../../types/a2a.js';
+
+/**
+ * Project context metadata for Agent Card generation
+ */
+export interface ProjectContext {
+  projectId: string;
+  projectName: string;
+  workingDirectory: string;
+  a2aAgentId: string;
+  baseUrl: string; // e.g., "https://agentstudio.cc"
+}
+
+/**
+ * Generate Agent Card from agent configuration (pure function)
+ *
+ * This is a pure function with no side effects - it takes agent config and project context
+ * and returns a complete Agent Card compliant with A2A protocol v1.0.
+ *
+ * @param agentConfig - Agent configuration with tools and metadata
+ * @param projectContext - Project-specific context (ID, name, working directory, A2A ID, baseUrl)
+ * @returns Complete Agent Card ready for A2A protocol exposure
+ */
+export function generateAgentCard(
+  agentConfig: AgentConfig,
+  projectContext: ProjectContext
+): AgentCard {
+  // Extract skills from agent's tools
+  const skills = extractSkillsFromTools(agentConfig.allowedTools);
+
+  // Determine agent category
+  const agentCategory = agentConfig.source === 'plugin' ? ('subagent' as const) : ('builtin' as const);
+
+  // Build Agent Card
+  const agentCard: AgentCard = {
+    // A2A Protocol required fields
+    name: agentConfig.name,
+    description: agentConfig.description,
+    version: agentConfig.version,
+    url: `${projectContext.baseUrl}/a2a/${projectContext.a2aAgentId}`,
+
+    // Agent capabilities (skills extracted from tools)
+    skills,
+
+    // Authentication requirements (API key only for now)
+    securitySchemes: [
+      {
+        type: 'apiKey' as const,
+        in: 'header' as const,
+        name: 'Authorization' as const,
+        scheme: 'bearer' as const,
+      },
+    ],
+
+    // AgentStudio-specific context
+    context: {
+      a2aAgentId: projectContext.a2aAgentId,
+      projectId: projectContext.projectId,
+      projectName: projectContext.projectName,
+      workingDirectory: projectContext.workingDirectory,
+      agentType: agentConfig.id,
+      agentCategory,
+    },
+  };
+
+  return agentCard;
+}
+
+/**
+ * Extract skills from agent's enabled MCP tools
+ *
+ * Converts AgentTool[] to Skill[] by mapping tool names to skill definitions.
+ * Only includes enabled tools.
+ *
+ * @param tools - Array of agent tools with enable/disable state
+ * @returns Array of skills for Agent Card
+ */
+function extractSkillsFromTools(tools: AgentTool[]): Skill[] {
+  const skills: Skill[] = [];
+
+  // Filter to enabled tools only
+  const enabledTools = tools.filter((tool) => tool.enabled);
+
+  for (const tool of enabledTools) {
+    const skill = toolToSkill(tool);
+    if (skill) {
+      skills.push(skill);
+    }
+  }
+
+  return skills;
+}
+
+/**
+ * Convert a single AgentTool to a Skill definition
+ *
+ * Maps common tool names to their skill schemas. For unknown tools,
+ * generates a generic skill with minimal schema.
+ *
+ * @param tool - Agent tool configuration
+ * @returns Skill definition or null if tool should be excluded
+ */
+function toolToSkill(tool: AgentTool): Skill | null {
+  // Map common tools to skill definitions
+  const toolSchemas: Record<string, Omit<Skill, 'name'>> = {
+    // File operations
+    read_file: {
+      description: 'Read content from a file',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'File path to read' },
+        },
+        required: ['path'],
+      },
+      outputSchema: {
+        type: 'object',
+        properties: {
+          content: { type: 'string', description: 'File content' },
+        },
+      },
+    },
+    write_file: {
+      description: 'Write content to a file',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'File path to write' },
+          content: { type: 'string', description: 'Content to write' },
+        },
+        required: ['path', 'content'],
+      },
+      outputSchema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean' },
+        },
+      },
+    },
+    edit_file: {
+      description: 'Edit file content with search and replace',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'File path to edit' },
+          old_string: { type: 'string', description: 'Text to replace' },
+          new_string: { type: 'string', description: 'Replacement text' },
+        },
+        required: ['path', 'old_string', 'new_string'],
+      },
+      outputSchema: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean' },
+        },
+      },
+    },
+    // Command execution
+    execute_command: {
+      description: 'Execute shell command',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          command: { type: 'string', description: 'Shell command to execute' },
+        },
+        required: ['command'],
+      },
+      outputSchema: {
+        type: 'object',
+        properties: {
+          stdout: { type: 'string' },
+          stderr: { type: 'string' },
+          exitCode: { type: 'number' },
+        },
+      },
+    },
+    // Search
+    grep: {
+      description: 'Search for patterns in files',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string', description: 'Search pattern' },
+          path: { type: 'string', description: 'Directory to search' },
+        },
+        required: ['pattern'],
+      },
+      outputSchema: {
+        type: 'object',
+        properties: {
+          matches: {
+            type: 'array',
+            items: { type: 'string' },
+          },
+        },
+      },
+    },
+    glob: {
+      description: 'Find files matching glob pattern',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string', description: 'Glob pattern' },
+        },
+        required: ['pattern'],
+      },
+      outputSchema: {
+        type: 'object',
+        properties: {
+          files: {
+            type: 'array',
+            items: { type: 'string' },
+          },
+        },
+      },
+    },
+  };
+
+  // Check if we have a predefined schema for this tool
+  const schema = toolSchemas[tool.name];
+
+  if (schema) {
+    return {
+      name: tool.name,
+      ...schema,
+    };
+  }
+
+  // For unknown tools, generate generic schema
+  return {
+    name: tool.name,
+    description: `Execute ${tool.name} tool`,
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        result: { type: 'string' },
+      },
+    },
+  };
+}