@datalayer/agent-runtimes 0.0.2

package/lib/components/chat/protocols/A2AAdapter.js

@@ -0,0 +1,388 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { generateMessageId, createAssistantMessage } from '../types/message';
+import { BaseProtocolAdapter } from './BaseProtocolAdapter';
+/**
+ * A2A protocol adapter
+ * Uses JSON-RPC 2.0 with SSE streaming for responses
+ */
+export class A2AAdapter extends BaseProtocolAdapter {
+    type = 'a2a';
+    transport = 'sse';
+    a2aConfig;
+    abortController = null;
+    agentCard = null;
+    currentTaskId = null;
+    constructor(config) {
+        super(config);
+        this.a2aConfig = {
+            enableA2UI: true,
+            ...config,
+        };
+    }
+    /**
+     * Connect and discover agent card
+     */
+    async connect() {
+        this.setConnectionState('connecting');
+        try {
+            // Fetch agent card from .well-known endpoint
+            const agentUrl = this.a2aConfig.agentUrl || this.a2aConfig.baseUrl;
+            const wellKnownUrl = new URL('/.well-known/agent.json', agentUrl).toString();
+            const response = await fetch(wellKnownUrl, {
+                method: 'GET',
+                headers: this.buildHeaders(),
+                signal: this.createTimeoutSignal(),
+            });
+            if (response.ok) {
+                this.agentCard = await response.json();
+            }
+            this.setConnectionState('connected');
+        }
+        catch (error) {
+            console.warn('[A2AAdapter] Could not fetch agent card:', error);
+            // Still mark as connected, card is optional
+            this.setConnectionState('connected');
+        }
+    }
+    /**
+     * Disconnect and terminate any ongoing agent execution
+     */
+    disconnect() {
+        if (this.abortController) {
+            this.abortController.abort();
+            this.abortController = null;
+        }
+        // Send terminate request to backend if we have a task ID
+        if (this.currentTaskId) {
+            this.terminateTask(this.currentTaskId).catch(err => {
+                console.warn('[A2AAdapter] Failed to terminate task:', err);
+            });
+        }
+        this.setConnectionState('disconnected');
+    }
+    /**
+     * Terminate a running task on the backend
+     */
+    async terminateTask(taskId) {
+        try {
+            // Derive the terminate endpoint from the base URL
+            const baseUrl = new URL(this.a2aConfig.baseUrl);
+            const terminateUrl = `${baseUrl.origin}/api/v1/a2a/terminate`;
+            const response = await fetch(terminateUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    task_id: taskId || this.currentTaskId,
+                }),
+            });
+            if (!response.ok) {
+                console.warn(`[A2AAdapter] Terminate request failed: ${response.status}`);
+            }
+            else {
+                const result = await response.json();
+                console.debug('[A2AAdapter] Terminate result:', result);
+            }
+        }
+        catch (err) {
+            // Ignore errors - task may have already completed
+            console.debug('[A2AAdapter] Terminate request error:', err);
+        }
+    }
+    /**
+     * Get agent card
+     */
+    async getAgentCard() {
+        return this.agentCard;
+    }
+    /**
+     * Send a message through A2A protocol
+     */
+    async sendMessage(message, options) {
+        this.abortController = new AbortController();
+        const taskId = options?.threadId || this.currentTaskId || generateMessageId();
+        this.currentTaskId = taskId;
+        // Build A2A message parts (A2A uses 'kind' discriminator, not 'type')
+        const parts = [];
+        if (typeof message.content === 'string') {
+            parts.push({ kind: 'text', text: message.content });
+        }
+        else if (Array.isArray(message.content)) {
+            for (const part of message.content) {
+                if (part.type === 'text') {
+                    parts.push({ kind: 'text', text: part.text });
+                }
+                else if (part.type === 'activity') {
+                    parts.push({ kind: 'data', data: part.data });
+                }
+            }
+        }
+        // Build JSON-RPC request with A2A message format
+        // Use message/stream for SSE streaming responses
+        const messageId = generateMessageId();
+        const jsonRpcRequest = {
+            jsonrpc: '2.0',
+            method: 'message/stream',
+            params: {
+                message: {
+                    kind: 'message',
+                    messageId,
+                    role: message.role,
+                    parts,
+                },
+                configuration: {
+                    acceptedOutputModes: ['text', 'text/plain'],
+                    requestedExtensions: this.a2aConfig.enableA2UI ? ['a2ui'] : [],
+                },
+            },
+            id: taskId,
+        };
+        try {
+            const response = await fetch(this.a2aConfig.baseUrl, {
+                method: 'POST',
+                headers: this.buildHeaders({
+                    Accept: 'text/event-stream, application/json',
+                }),
+                body: JSON.stringify(jsonRpcRequest),
+                signal: this.abortController.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`A2A request failed: ${response.status} ${response.statusText}`);
+            }
+            // Check content type to decide how to parse
+            const contentType = response.headers.get('content-type') || '';
+            if (contentType.includes('text/event-stream')) {
+                // Parse SSE stream
+                await this.parseSSEStream(response);
+            }
+            else {
+                // Parse as JSON response
+                const jsonResponse = await response.json();
+                console.log('[A2AAdapter] JSON response:', JSON.stringify(jsonResponse, null, 2));
+                this.handleA2AEvent(jsonResponse);
+            }
+        }
+        catch (error) {
+            if (error.name === 'AbortError') {
+                return;
+            }
+            this.emit({
+                type: 'error',
+                error: error instanceof Error ? error : new Error(String(error)),
+                timestamp: new Date(),
+            });
+            throw error;
+        }
+        finally {
+            this.abortController = null;
+        }
+    }
+    /**
+     * Send tool result back
+     */
+    async sendToolResult(toolCallId, result) {
+        // A2A tool results are sent as data parts
+        this.emit({
+            type: 'tool-result',
+            toolResult: result,
+            timestamp: new Date(),
+        });
+    }
+    /**
+     * Check feature support
+     */
+    supportsFeature(feature) {
+        const supportedFeatures = [
+            'streaming',
+            'agent-discovery',
+            'a2ui',
+            'activity-messages',
+            'multi-agent',
+        ];
+        return supportedFeatures.includes(feature);
+    }
+    /**
+     * Parse SSE stream from A2A response
+     */
+    async parseSSEStream(response) {
+        const reader = response.body?.getReader();
+        if (!reader) {
+            throw new Error('Response body is not readable');
+        }
+        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: ')) {
+                        const data = line.slice(6);
+                        try {
+                            const event = JSON.parse(data);
+                            this.handleA2AEvent(event);
+                        }
+                        catch (e) {
+                            console.warn('[A2AAdapter] Failed to parse event data:', e);
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    /**
+     * Handle A2A protocol events
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handleA2AEvent(event) {
+        console.log('[A2AAdapter] Received event:', JSON.stringify(event, null, 2));
+        // Handle JSON-RPC response
+        if (event.result) {
+            this.handleTaskUpdate(event.result);
+        }
+        else if (event.error) {
+            this.emit({
+                type: 'error',
+                error: new Error(event.error.message || 'A2A error'),
+                timestamp: new Date(),
+            });
+        }
+    }
+    /**
+     * Handle task update from A2A
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handleTaskUpdate(task) {
+        console.log('[A2AAdapter] Handling task update:', JSON.stringify(task, null, 2));
+        // Handle different event kinds in SSE streaming
+        const eventKind = task.kind;
+        // Handle direct message events (from streaming)
+        if (eventKind === 'message' && task.role === 'agent') {
+            this.processA2AMessage(task);
+            return;
+        }
+        // Handle status updates
+        if (eventKind === 'status-update') {
+            const state = task.status?.state;
+            console.log('[A2AAdapter] Status update:', state, 'final:', task.final);
+            if (task.final &&
+                (state === 'completed' || state === 'failed' || state === 'canceled')) {
+                this.emit({
+                    type: 'state-update',
+                    data: { state, final: true },
+                    timestamp: new Date(),
+                });
+            }
+            return;
+        }
+        // Handle artifact updates
+        if (eventKind === 'artifact-update') {
+            console.log('[A2AAdapter] Artifact update:', task.artifact);
+            // Artifacts contain the final result, but we already process messages
+            // Could emit as activity if needed
+            return;
+        }
+        // Handle task events (initial task submission response)
+        if (eventKind === 'task') {
+            // Store task ID for potential cancellation
+            if (task.id) {
+                this.currentTaskId = task.id;
+            }
+            // A2A uses 'history' for message history
+            const messages = task.history || task.messages || [];
+            // Process messages, but skip user messages (we already have them)
+            for (const msg of messages) {
+                if (msg.role === 'assistant' ||
+                    msg.role === 'model' ||
+                    msg.role === 'agent') {
+                    this.processA2AMessage(msg);
+                }
+            }
+            return;
+        }
+        // Fallback: Check for legacy format
+        const messages = task.history || task.messages || [];
+        // Process messages, but skip user messages (we already have them)
+        for (const msg of messages) {
+            if (msg.role === 'assistant' ||
+                msg.role === 'model' ||
+                msg.role === 'agent') {
+                this.processA2AMessage(msg);
+            }
+        }
+        // Check task status - it's an object with 'state' property
+        const taskState = typeof task.status === 'object' ? task.status?.state : task.status;
+        if (taskState === 'completed' && task.result) {
+            this.emit({
+                type: 'message',
+                message: createAssistantMessage(typeof task.result === 'string'
+                    ? task.result
+                    : JSON.stringify(task.result)),
+                timestamp: new Date(),
+            });
+        }
+    }
+    /**
+     * Process individual A2A message
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    processA2AMessage(msg) {
+        console.log('[A2AAdapter] Processing message:', JSON.stringify(msg, null, 2));
+        if (!msg.parts)
+            return;
+        let textContent = '';
+        const activities = [];
+        for (const part of msg.parts) {
+            // A2A uses 'kind' discriminator, not 'type'
+            const partKind = part.kind || part.type;
+            if (partKind === 'text' && part.text) {
+                textContent += part.text;
+            }
+            else if (partKind === 'data') {
+                // Check for A2UI messages
+                if (part.data?.beginRendering ||
+                    part.data?.surfaceUpdate ||
+                    part.data?.dataModelUpdate) {
+                    activities.push({
+                        type: 'a2ui',
+                        data: part.data,
+                    });
+                }
+                else {
+                    activities.push({
+                        type: 'data',
+                        data: part.data,
+                    });
+                }
+            }
+        }
+        // Emit text message
+        if (textContent) {
+            console.log('[A2AAdapter] Emitting text message:', textContent);
+            this.emit({
+                type: 'message',
+                message: createAssistantMessage(textContent),
+                timestamp: new Date(),
+            });
+        }
+        // Emit activity messages (including A2UI)
+        for (const activity of activities) {
+            this.emit({
+                type: 'activity',
+                activity,
+                timestamp: new Date(),
+            });
+        }
+    }
+}

package/lib/components/chat/protocols/ACPAdapter.d.ts

@@ -0,0 +1,161 @@
+/**
+ * ACP (Agent Communication Protocol) adapter using WebSocket transport.
+ *
+ * Implements the Agent Client Protocol as specified at:
+ * https://agentclientprotocol.com
+ *
+ * Key Protocol Features:
+ * - JSON-RPC 2.0 message format
+ * - Protocol version: 1 (integer for MAJOR version)
+ * - Methods: initialize, session/new, session/prompt, session/cancel
+ * - Session updates via session/update notifications
+ * - Permission handling via session/request_permission
+ *
+ * @module components/chat/protocols/ACPAdapter
+ */
+import { type PermissionOption, type ToolCallUpdate } from '@agentclientprotocol/sdk';
+import type { ProtocolAdapterConfig } from '../types/protocol';
+import type { ChatMessage } from '../types/message';
+import type { ToolDefinition, ToolExecutionResult } from '../types/tool';
+import { BaseProtocolAdapter } from './BaseProtocolAdapter';
+/**
+ * ACP session tracking
+ */
+export interface ACPSession {
+    sessionId: string;
+    agentId: string;
+    createdAt: string;
+    status: 'active' | 'inactive' | 'error';
+}
+/**
+ * ACP agent info
+ */
+export interface ACPAgent {
+    id: string;
+    name: string;
+    description?: string;
+    capabilities?: Record<string, unknown>;
+}
+/**
+ * Pending permission request
+ */
+export interface ACPPendingPermission {
+    /** JSON-RPC request ID for the response */
+    requestId: string | number;
+    /** Session ID */
+    sessionId: string;
+    /** Tool call details */
+    toolCall: ToolCallUpdate;
+    /** Permission options */
+    options: PermissionOption[];
+}
+/**
+ * ACP specific configuration
+ */
+export interface ACPAdapterConfig extends ProtocolAdapterConfig {
+    /** WebSocket URL (ws:// or wss://) */
+    wsUrl?: string;
+    /** Client capabilities to advertise */
+    clientCapabilities?: {
+        fs?: {
+            readTextFile?: boolean;
+            writeTextFile?: boolean;
+        };
+        terminal?: boolean;
+    };
+    /** Callback when permission is requested */
+    onPermissionRequest?: (permission: ACPPendingPermission) => void;
+}
+/**
+ * ACP protocol adapter
+ * Uses WebSocket with JSON-RPC 2.0 for bidirectional communication
+ */
+export declare class ACPAdapter extends BaseProtocolAdapter {
+    readonly type: "acp";
+    readonly transport: "websocket";
+    private acpConfig;
+    private ws;
+    private session;
+    private agent;
+    private streamingContent;
+    private streamingMessageId;
+    private pendingPermission;
+    private pendingRequests;
+    constructor(config: ACPAdapterConfig);
+    /**
+     * Get current session
+     */
+    getSession(): ACPSession | null;
+    /**
+     * Get agent info
+     */
+    getAgent(): ACPAgent | null;
+    /**
+     * Get pending permission request
+     */
+    getPendingPermission(): ACPPendingPermission | null;
+    /**
+     * Connect to ACP WebSocket endpoint
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from WebSocket and terminate any running session
+     */
+    disconnect(): void;
+    /**
+     * Terminate a running session on the backend via session/cancel
+     */
+    terminateSession(sessionId?: string): Promise<void>;
+    /**
+     * Send a message through ACP protocol
+     */
+    sendMessage(message: ChatMessage, _options?: {
+        tools?: ToolDefinition[];
+        threadId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Send tool result back through ACP
+     */
+    sendToolResult(toolCallId: string, result: ToolExecutionResult): Promise<void>;
+    /**
+     * Grant permission (respond to session/request_permission)
+     */
+    grantPermission(optionId?: string): void;
+    /**
+     * Deny permission (respond with cancelled)
+     */
+    denyPermission(): void;
+    /**
+     * Check feature support
+     */
+    supportsFeature(feature: string): boolean;
+    /**
+     * Generate unique message ID
+     */
+    private generateId;
+    /**
+     * Send ACP JSON-RPC request
+     */
+    private sendRequest;
+    /**
+     * Send ACP JSON-RPC response
+     */
+    private sendResponse;
+    /**
+     * Handle incoming WebSocket message
+     */
+    private handleMessage;
+    /**
+     * Handle session update notifications
+     */
+    private handleSessionUpdate;
+    /**
+     * Handle permission request from agent
+     */
+    private handlePermissionRequest;
+    /**
+     * Handle completion (stopReason received)
+     */
+    private handleCompletion;
+}