agentstudio 0.3.0 → 0.3.1

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

@@ -0,0 +1,194 @@
+/**
+ * A2A Configuration Service
+ *
+ * Manages project-level A2A configuration including allowed agents, timeouts, and limits.
+ * Configuration stored in projects/:projectId/.a2a/config.json
+ *
+ * Phase 5: US3 - Agent as A2A Client (config dependency)
+ * Phase 7: US5 - Project-Level A2A Configuration (full implementation)
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import lockfile from 'proper-lockfile';
+import type { A2AConfig } from '../../types/a2a.js';
+import { DEFAULT_A2A_CONFIG } from '../../types/a2a.js';
+import { isIPAddress } from '../../middleware/httpsOnly.js';
+import { getProjectsDir } from '../../config/sdkConfig.js';
+
+const LOCK_OPTIONS = {
+  retries: { retries: 5, minTimeout: 100, maxTimeout: 500 },
+};
+
+/**
+ * Get path to project's A2A config file
+ *
+ * @param projectId - Project identifier (used as directory name)
+ * @returns Absolute path to config file
+ */
+function getConfigPath(projectId: string): string {
+  // Check if the projectId looks like an absolute path
+  if (path.isAbsolute(projectId)) {
+    return path.join(projectId, '.a2a', 'config.json');
+  }
+
+  // Projects are stored in SDK projects directory (e.g., ~/.claude/projects/)
+  const projectsDir = getProjectsDir();
+  return path.join(projectsDir, projectId, '.a2a', 'config.json');
+}
+
+/**
+ * Load A2A configuration for a project
+ *
+ * Returns default config if file doesn't exist.
+ *
+ * @param projectId - Project identifier
+ * @returns A2A configuration or null on error
+ */
+export async function loadA2AConfig(projectId: string): Promise<A2AConfig | null> {
+  const configPath = getConfigPath(projectId);
+
+  try {
+    const data = await fs.readFile(configPath, 'utf-8');
+    const config: A2AConfig = JSON.parse(data);
+    return config;
+  } catch (error) {
+    // If file doesn't exist, return default config
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return DEFAULT_A2A_CONFIG;
+    }
+
+    console.error(`[A2A Config] Error loading config for project ${projectId}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Save A2A configuration for a project
+ *
+ * Creates directory structure if needed.
+ * Uses file locking for concurrent safety.
+ *
+ * @param projectId - Project identifier
+ * @param config - A2A configuration to save
+ */
+export async function saveA2AConfig(projectId: string, config: A2AConfig): Promise<void> {
+  const configPath = getConfigPath(projectId);
+  const configDir = path.dirname(configPath);
+
+  // Ensure directory exists
+  await fs.mkdir(configDir, { recursive: true });
+
+  // Create empty file if it doesn't exist (helps with file locking)
+  try {
+    await fs.access(configPath);
+  } catch {
+    // File doesn't exist, create empty file
+    await fs.writeFile(configPath, '{}', 'utf-8');
+  }
+
+  // Acquire lock for atomic write
+  const release = await lockfile.lock(configPath, LOCK_OPTIONS);
+
+  try {
+    await fs.writeFile(configPath, JSON.stringify(config, null, 2), 'utf-8');
+  } finally {
+    await release();
+  }
+}
+
+/**
+ * Validate A2A configuration
+ *
+ * Checks for required fields and value constraints.
+ *
+ * @param config - Configuration to validate
+ * @returns Validation result with error details if invalid
+ */
+export function validateA2AConfig(config: A2AConfig): {
+  valid: boolean;
+  errors?: string[];
+} {
+  const errors: string[] = [];
+
+  // Validate allowedAgents
+  if (!Array.isArray(config.allowedAgents)) {
+    errors.push('allowedAgents must be an array');
+  } else {
+    config.allowedAgents.forEach((agent, index) => {
+      if (!agent.name || typeof agent.name !== 'string') {
+        errors.push(`allowedAgents[${index}].name is required and must be a string`);
+      }
+
+      if (!agent.url || typeof agent.url !== 'string') {
+        errors.push(`allowedAgents[${index}].url is required and must be a string`);
+      } else {
+        // Validate URL format
+        try {
+          const parsedUrl = new URL(agent.url);
+          // In production, require HTTPS for domain names
+          // IP addresses are exempt (internal/proxy scenarios)
+          if (process.env.NODE_ENV === 'production' && !agent.url.startsWith('https://')) {
+            // Check if hostname is an IP address
+            const isIP = isIPAddress(parsedUrl.hostname);
+            if (!isIP) {
+              errors.push(`allowedAgents[${index}].url must use HTTPS in production (IP addresses exempt)`);
+            }
+          }
+        } catch {
+          errors.push(`allowedAgents[${index}].url is not a valid URL`);
+        }
+      }
+
+      if (agent.apiKey === undefined || typeof agent.apiKey !== 'string') {
+        errors.push(`allowedAgents[${index}].apiKey is required and must be a string`);
+      }
+
+      if (typeof agent.enabled !== 'boolean') {
+        errors.push(`allowedAgents[${index}].enabled must be a boolean`);
+      }
+    });
+  }
+
+  // Validate taskTimeout
+  if (typeof config.taskTimeout !== 'number') {
+    errors.push('taskTimeout must be a number');
+  } else if (config.taskTimeout < 1000 || config.taskTimeout > 1800000) {
+    errors.push('taskTimeout must be between 1000 and 1800000 milliseconds');
+  }
+
+  // Validate maxConcurrentTasks
+  if (typeof config.maxConcurrentTasks !== 'number') {
+    errors.push('maxConcurrentTasks must be a number');
+  } else if (config.maxConcurrentTasks < 1 || config.maxConcurrentTasks > 50) {
+    errors.push('maxConcurrentTasks must be between 1 and 50');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors: errors.length > 0 ? errors : undefined,
+  };
+}
+
+/**
+ * Initialize default A2A config for a new project
+ *
+ * Creates .a2a directory and config.json with default values.
+ *
+ * @param projectId - Project identifier
+ */
+export async function initializeA2AConfig(projectId: string): Promise<void> {
+  const existingConfig = await loadA2AConfig(projectId);
+
+  // Only initialize if config doesn't exist (loadA2AConfig returns DEFAULT_A2A_CONFIG for missing files)
+  const configPath = getConfigPath(projectId);
+  try {
+    await fs.access(configPath);
+    // File exists, don't overwrite
+    return;
+  } catch {
+    // File doesn't exist, create it
+    await saveA2AConfig(projectId, DEFAULT_A2A_CONFIG);
+    console.info(`[A2A Config] Initialized default config for project ${projectId}`);
+  }
+}

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

@@ -0,0 +1,111 @@
+/**
+ * A2A History Service
+ *
+ * Manages the persistence of A2A message history using JSONL files.
+ * This allows retrieving the full event stream of an external agent call later.
+ *
+ * Storage path: {workingDirectory}/.a2a/history/{sessionId}.jsonl
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { ensureDir } from '../../utils/fileUtils.js';
+import { Buffer } from 'buffer';
+
+export class A2AHistoryService {
+  /**
+   * Get the directory path for A2A history
+   */
+  private getHistoryDir(workingDirectory: string): string {
+    return path.join(workingDirectory, '.a2a', 'history');
+  }
+
+  /**
+   * Get the file path for a specific session
+   */
+  private getHistoryFilePath(workingDirectory: string, sessionId: string): string {
+    return path.join(this.getHistoryDir(workingDirectory), `${sessionId}.jsonl`);
+  }
+
+  /**
+   * Append an event to the history file
+   */
+  async appendEvent(workingDirectory: string, sessionId: string, event: any): Promise<void> {
+    const historyDir = this.getHistoryDir(workingDirectory);
+    await ensureDir(historyDir);
+
+    const filePath = this.getHistoryFilePath(workingDirectory, sessionId);
+    const line = JSON.stringify(event) + '\n';
+
+    await fs.appendFile(filePath, line, 'utf-8');
+  }
+
+  /**
+   * Read the full history for a session
+   */
+  async getHistory(workingDirectory: string, sessionId: string): Promise<any[]> {
+    const filePath = this.getHistoryFilePath(workingDirectory, sessionId);
+
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
+      return content
+        .split('\n')
+        .filter((line: string) => line.trim())
+        .map((line: string) => JSON.parse(line));
+    } catch (error: any) {
+      if (error.code === 'ENOENT') {
+        return [];
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Watch the history file and yield new lines as they are written
+   */
+  async *tailHistory(workingDirectory: string, sessionId: string, signal?: AbortSignal): AsyncGenerator<any> {
+    const filePath = this.getHistoryFilePath(workingDirectory, sessionId);
+    let currentSize = 0;
+
+    // Wait for file to exist
+    while (!signal?.aborted) {
+      try {
+        const stats = await fs.stat(filePath);
+        if (stats.isFile()) break;
+      } catch {
+        await new Promise(resolve => setTimeout(resolve, 100));
+      }
+    }
+
+    while (!signal?.aborted) {
+      try {
+        const stats = await fs.stat(filePath);
+        if (stats.size > currentSize) {
+          const handle = await fs.open(filePath, 'r');
+          const buffer = Buffer.alloc(stats.size - currentSize);
+          await handle.read(buffer, 0, stats.size - currentSize, currentSize);
+          await handle.close();
+
+          const content = buffer.toString('utf-8');
+          const lines = content.split('\n').filter((line: string) => line.trim());
+
+          for (const line of lines) {
+            try {
+              yield JSON.parse(line);
+            } catch {
+              // Ignore parse errors
+            }
+          }
+
+          currentSize = stats.size;
+        }
+      } catch {
+        // Ignore errors (e.g. file not found yet)
+      }
+
+      await new Promise(resolve => setTimeout(resolve, 200)); // Poll every 200ms
+    }
+  }
+}
+
+export const a2aHistoryService = new A2AHistoryService();

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

@@ -0,0 +1,40 @@
+import { createA2ASdkMcpServer, getA2AToolName } from './a2aSdkMcp.js';
+
+/**
+ * Helper to integrate A2A SDK MCP server into query options
+ * 
+ * @param queryOptions - The query options object to modify
+ * @param projectId - Project identifier
+ * @param streamEnabled - Whether to enable streaming for external agent calls (default: false)
+ * @returns The modified query options (same object reference)
+ */
+export async function integrateA2AMcpServer(queryOptions: any, projectId: string, streamEnabled: boolean = false) {
+    try {
+        // Create SDK MCP server for A2A (in-process)
+        const { server: a2aServer } = await createA2ASdkMcpServer(projectId, streamEnabled);
+
+        // Add to mcpServers
+        if (a2aServer) {
+            queryOptions.mcpServers = {
+                ...queryOptions.mcpServers,
+                "a2a-client": a2aServer
+            };
+
+            // Add tool to allowedTools
+            const a2aToolName = getA2AToolName();
+            if (!queryOptions.allowedTools) {
+                queryOptions.allowedTools = [a2aToolName];
+            } else {
+                // Avoid duplicates
+                if (!queryOptions.allowedTools.includes(a2aToolName)) {
+                    queryOptions.allowedTools.push(a2aToolName);
+                }
+            }
+        }
+    } catch (error) {
+        console.error('❌ [A2A] Failed to integrate SDK MCP server:', error);
+        // Continue without A2A support rather than failing
+    }
+
+    return queryOptions;
+}

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

@@ -0,0 +1,275 @@
+/**
+ * A2A Query Service - One-shot Query Mode
+ * 
+ * This service provides a one-shot query mode for A2A requests.
+ * Instead of using ClaudeSession (Streaming Input Mode with MessageQueue),
+ * it uses an async generator that naturally completes after yielding the message.
+ * 
+ * Benefits:
+ * - Each A2A request is independent, no session reuse issues
+ * - Query automatically completes when generator ends
+ * - Still supports resume for history context
+ * - Still supports images and multi-part messages via Streaming Input
+ */
+
+import { query, Options } from '@anthropic-ai/claude-agent-sdk';
+import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+
+/**
+ * User message content type for multi-part messages (text + images)
+ */
+export interface UserMessageContent {
+  type: 'text' | 'image';
+  text?: string;
+  source?: {
+    type: 'base64';
+    media_type: string;
+    data: string;
+  };
+}
+
+/**
+ * A2A Query options extending Claude SDK Options
+ */
+export interface A2AQueryOptions extends Options {
+  resume?: string;
+}
+
+/**
+ * Create an async generator for A2A messages
+ * The generator yields the user message and then completes,
+ * allowing the query to naturally finish.
+ * 
+ * Uses 'any' type to match MessageQueue's approach and avoid SDK type incompatibility.
+ * 
+ * @param content - Message content (string or array of content blocks)
+ */
+async function* createA2AMessageGenerator(
+  content: string | UserMessageContent[]
+): AsyncGenerator<any, void, unknown> {
+  const messageContent = typeof content === 'string'
+    ? [{ type: 'text' as const, text: content }]
+    : content;
+
+  yield {
+    type: 'user' as const,
+    message: {
+      role: 'user' as const,
+      content: messageContent
+    }
+  };
+  // Generator ends here, query will naturally complete after processing
+}
+
+/**
+ * Execute a one-shot A2A query
+ * 
+ * This function creates a new query for each A2A request, using an async generator
+ * that completes after yielding the message. This avoids the session reuse issues
+ * that can occur with ClaudeSession's MessageQueue approach.
+ * 
+ * @param message - The user message (text string)
+ * @param images - Optional array of images to include in the message
+ * @param options - Query options including resume sessionId
+ * @param onMessage - Callback for each SDK message
+ * @returns Promise that resolves when query completes
+ */
+export async function executeA2AQuery(
+  message: string,
+  images: Array<{ data: string; mediaType: string }> | undefined,
+  options: A2AQueryOptions,
+  onMessage: (message: SDKMessage) => Promise<void>
+): Promise<{ sessionId: string | null; fullResponse: string; tokensUsed: number }> {
+  // Build message content with optional images
+  const messageContent: UserMessageContent[] = [];
+  
+  // Add images first if present
+  if (images && images.length > 0) {
+    for (const image of images) {
+      messageContent.push({
+        type: 'image',
+        source: {
+          type: 'base64',
+          media_type: image.mediaType,
+          data: image.data
+        }
+      });
+    }
+  }
+  
+  // Add text message
+  messageContent.push({
+    type: 'text',
+    text: message
+  });
+
+  // Internal function to execute the query
+  async function executeQuery(queryOptions: A2AQueryOptions): Promise<{ sessionId: string | null; fullResponse: string; tokensUsed: number }> {
+    // Create the message generator (must be created fresh for each attempt)
+    const messageGen = createA2AMessageGenerator(messageContent);
+
+    let sessionId: string | null = null;
+    let fullResponse = '';
+    let tokensUsed = 0;
+
+    console.log(`🚀 [A2A Query] Starting one-shot query with resume=${queryOptions.resume || 'none'}`);
+
+    // Execute the query
+    const queryResult = query({
+      prompt: messageGen,
+      options: queryOptions
+    });
+
+    // Process responses
+    for await (const sdkMessage of queryResult) {
+      // Capture session ID from system init message
+      if (sdkMessage.type === 'system' && sdkMessage.subtype === 'init' && sdkMessage.session_id) {
+        sessionId = sdkMessage.session_id;
+        console.log(`📝 [A2A Query] Captured sessionId: ${sessionId}`);
+      }
+
+      // Also check for session_id on any message
+      if ((sdkMessage as any).session_id && !sessionId) {
+        sessionId = (sdkMessage as any).session_id;
+      }
+
+      // Extract assistant response text
+      if (sdkMessage.type === 'assistant' && sdkMessage.message?.content) {
+        for (const block of sdkMessage.message.content) {
+          if (block.type === 'text') {
+            fullResponse += block.text;
+          }
+        }
+      }
+
+      // Extract token usage
+      if (sdkMessage.type === 'assistant' && (sdkMessage as any).usage) {
+        const usage = (sdkMessage as any).usage;
+        tokensUsed = (usage.input_tokens || 0) + (usage.output_tokens || 0);
+      }
+
+      // Call the message callback
+      await onMessage(sdkMessage);
+    }
+
+    console.log(`✅ [A2A Query] Query completed, sessionId=${sessionId}, responseLength=${fullResponse.length}`);
+
+    return { sessionId, fullResponse, tokensUsed };
+  }
+
+  // Try with resume first, if it fails due to invalid session, retry without resume
+  try {
+    return await executeQuery(options);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    
+    // Check if the error is due to invalid resume session
+    if (options.resume && (
+      errorMessage.includes('exited with code 1') ||
+      errorMessage.includes('session') ||
+      errorMessage.includes('resume')
+    )) {
+      console.warn(`⚠️ [A2A Query] Resume failed (session may be invalid), retrying without resume...`);
+      
+      // Create new options without resume
+      const { resume, ...optionsWithoutResume } = options;
+      return await executeQuery(optionsWithoutResume);
+    }
+    
+    // Re-throw other errors
+    throw error;
+  }
+}
+
+/**
+ * Execute a one-shot A2A query with SSE streaming
+ * 
+ * Similar to executeA2AQuery but designed for SSE streaming mode.
+ * 
+ * @param message - The user message (text string)
+ * @param images - Optional array of images
+ * @param options - Query options including resume sessionId
+ * @param onMessage - Callback for each SDK message (for SSE streaming)
+ */
+export async function executeA2AQueryStreaming(
+  message: string,
+  images: Array<{ data: string; mediaType: string }> | undefined,
+  options: A2AQueryOptions,
+  onMessage: (message: SDKMessage) => void
+): Promise<{ sessionId: string | null }> {
+  // Build message content with optional images
+  const messageContent: UserMessageContent[] = [];
+  
+  if (images && images.length > 0) {
+    for (const image of images) {
+      messageContent.push({
+        type: 'image',
+        source: {
+          type: 'base64',
+          media_type: image.mediaType,
+          data: image.data
+        }
+      });
+    }
+  }
+  
+  messageContent.push({
+    type: 'text',
+    text: message
+  });
+
+  // Internal function to execute the streaming query
+  async function executeStreamingQuery(queryOptions: A2AQueryOptions): Promise<{ sessionId: string | null }> {
+    // Create the message generator (must be created fresh for each attempt)
+    const messageGen = createA2AMessageGenerator(messageContent);
+
+    let sessionId: string | null = null;
+
+    console.log(`🚀 [A2A Query Streaming] Starting one-shot query with resume=${queryOptions.resume || 'none'}`);
+
+    const queryResult = query({
+      prompt: messageGen,
+      options: queryOptions
+    });
+
+    for await (const sdkMessage of queryResult) {
+      // Capture session ID
+      if (sdkMessage.type === 'system' && sdkMessage.subtype === 'init' && sdkMessage.session_id) {
+        sessionId = sdkMessage.session_id;
+      }
+      if ((sdkMessage as any).session_id && !sessionId) {
+        sessionId = (sdkMessage as any).session_id;
+      }
+
+      // Stream the message (synchronous callback for SSE)
+      onMessage(sdkMessage);
+    }
+
+    console.log(`✅ [A2A Query Streaming] Query completed, sessionId=${sessionId}`);
+
+    return { sessionId };
+  }
+
+  // Try with resume first, if it fails due to invalid session, retry without resume
+  try {
+    return await executeStreamingQuery(options);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    
+    // Check if the error is due to invalid resume session
+    if (options.resume && (
+      errorMessage.includes('exited with code 1') ||
+      errorMessage.includes('session') ||
+      errorMessage.includes('resume')
+    )) {
+      console.warn(`⚠️ [A2A Query Streaming] Resume failed (session may be invalid), retrying without resume...`);
+      
+      // Create new options without resume
+      const { resume, ...optionsWithoutResume } = options;
+      return await executeStreamingQuery(optionsWithoutResume);
+    }
+    
+    // Re-throw other errors
+    throw error;
+  }
+}