Review changes

Author: gspencergoog

packages/a2a_dart/DESIGN.md

@@ -138,38 +138,26 @@ Example `A2AClient` usage:
 ```dart
 final client = A2AClient(url: 'https://example.com/a2a', transport: SseTransport(url: 'https://example.com/a2a'));
 
-// For a simple request-response
+// Create a task
 final task = await client.createTask(Message(
   messageId: '1',
   role: Role.user,
   parts: [const TextPart(text: 'Hello, agent!')],
 ));
 
-// For a streaming response
-final stream = client.messageStream(Message(
-  role: 'user',
-  parts: [TextPart(text: 'Tell me a story.')],
-));
-
+// Execute the task and get a stream of events
+final stream = client.executeTask(task.id);
 await for (final event in stream) {
   // process events
 }
-
-print(task.status.state);
-
-// To execute the task and get a stream of messages:
-final stream = client.executeTask(task.id);
-await for (final message in stream) {
-  // process messages
-}
 ```
 
 ## 6. Server Framework
 
 The server framework will provide the building blocks for creating A2A-compliant agents in Dart.
 
 - **`A2AServer`**: A top-level class that listens for incoming HTTP requests and routes them to the appropriate `RequestHandler`.
-- **`RequestHandler`**: An interface for handling specific A2A methods. Developers will implement this interface to define their agent's behavior.
+- **`RequestHandler`**: An interface for handling specific A2A methods. Developers will implement this interface to define their agent's behavior. The `handle` method returns a `HandlerResult` which can be a `SingleResult` for a single response or a `StreamResult` for a streaming response.
 - **`TaskManager`**: A class responsible for managing the lifecycle of tasks.
 
 ## 7. Error Handling

packages/a2a_dart/GEMINI.md

@@ -10,7 +10,7 @@ The `A2AClient` provides a simple and convenient way to interact with an A2A ser
 
 ## Server
 
-The `A2AServer` provides a flexible and extensible framework for building A2A agents. It is built on top of the `shelf` package and uses a request handler pipeline to process incoming requests. Each `RequestHandler` is responsible for a single RPC method, making it easy to add new functionality to the server.
+The `A2AServer` provides a flexible and extensible framework for building A2A agents. It is built on top of the `shelf` package and uses a request handler pipeline to process incoming requests. Each `RequestHandler` is responsible for a single RPC method, making it easy to add new functionality to the server. The `handle` method of a `RequestHandler` returns a `HandlerResult`, which can be a `SingleResult` for a single response or a `StreamResult` for a streaming response.
 
 ## Data Models
 

packages/a2a_dart/README.md

@@ -15,7 +15,7 @@ Add the following to your `pubspec.yaml` file:
 
 ```yaml
 dependencies:
-  a2a_dart: ^1.0.0
+  a2a_dart: ^0.1.0
 ```
 
 ## Usage
@@ -45,8 +45,8 @@ void main() async {
 
   // Execute the task and stream the results.
   final stream = client.executeTask(task.id);
-  await for (final message in stream) {
-    print('Received message: ${message.messageId}');
+  await for (final event in stream) {
+    print('Received event: ${event.type}');
   }
 }
 ```

packages/a2a_dart/lib/src/client/sse_transport.dart

@@ -63,6 +63,7 @@ class SseTransport extends HttpTransport {
             } catch (e) {
               throw A2AException.parsing(message: e.toString());
             }
+          }
         } else if (line.startsWith('data:')) {
           data.add(line.substring(5).trim());
         } else if (line.startsWith(':')) {

packages/a2a_dart/lib/src/server/a2a_server.dart

@@ -11,6 +11,7 @@ import 'package:shelf/shelf.dart';
 import 'package:shelf/shelf_io.dart' as io;
 import 'package:shelf_router/shelf_router.dart';
 
+import 'handler_result.dart';
 import 'request_handler.dart';
 
 /// A server for handling A2A RPC calls.
@@ -120,30 +121,29 @@ class A2AServer {
         if (handler != null) {
           final result = await handler.handle(params);
           _log.info('Returning successful response for method $method');
-          if (result.containsKey('stream')) {
-            final stream = result['stream'] as Stream<Map<String, dynamic>>;
-            final responseStream = stream.map((event) {
-              return utf8.encode(
-                'data: ${jsonEncode({
-                      'jsonrpc': '2.0',
-                      'result': event,
-                      'id': id
-                    })}\n\n',
-              );
-            });
-            return Response.ok(
-              responseStream,
-              headers: {
-                'Content-Type': 'text/event-stream',
-                'Cache-Control': 'no-cache',
-                'Connection': 'keep-alive',
-              },
-            );
-          }
-          return Response.ok(
-            jsonEncode({'jsonrpc': '2.0', 'result': result, 'id': id}),
-            headers: {'Content-Type': 'application/json'},
-          );
+
+          return switch (result) {
+            SingleResult(data: final data) => Response.ok(
+                jsonEncode({'jsonrpc': '2.0', 'result': data, 'id': id}),
+                headers: {'Content-Type': 'application/json'},
+              ),
+            StreamResult(stream: final stream) => Response.ok(
+                stream.map((event) {
+                  return utf8.encode(
+                    'data: ${jsonEncode({
+                          'jsonrpc': '2.0',
+                          'result': event,
+                          'id': id
+                        })}\n\n',
+                  );
+                }),
+                headers: {
+                  'Content-Type': 'text/event-stream',
+                  'Cache-Control': 'no-cache',
+                  'Connection': 'keep-alive',
+                },
+              ),
+          };
         } else {
           return Response.notFound(
             jsonEncode({

packages/a2a_dart/lib/src/server/create_task_handler.dart

@@ -5,6 +5,7 @@
 import 'dart:async';
 
 import '../core/message.dart';
+import 'handler_result.dart';
 import 'request_handler.dart';
 import 'task_manager.dart';
 
@@ -25,14 +26,11 @@ class CreateTaskHandler implements RequestHandler {
   String get method => 'create_task';
 
   @override
-  FutureOr<Map<String, dynamic>> handle(Map<String, dynamic> params) {
-    // The 'message' parameter is part of the A2A specification for 'create_task',
-    // but it is not yet used in this implementation.
-    // ignore: unused_local_variable
+  FutureOr<HandlerResult> handle(Map<String, dynamic> params) {
     final message = Message.fromJson(params['message'] as Map<String, dynamic>);
 
-    final task = _taskManager.createTask();
+    final task = _taskManager.createTask(message);
 
-    return task.toJson();
+    return SingleResult(task.toJson());
   }
 }

packages/a2a_dart/lib/src/server/handler_result.dart

@@ -0,0 +1,26 @@
+// Copyright 2025 The Flutter Authors.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:async';
+
+/// A sealed class representing the result of a [RequestHandler].
+sealed class HandlerResult {}
+
+/// A [HandlerResult] that represents a single, non-streaming response.
+class SingleResult extends HandlerResult {
+  /// The data to be returned in the response.
+  final Map<String, dynamic> data;
+
+  /// Creates a [SingleResult] with the given [data].
+  SingleResult(this.data);
+}
+
+/// A [HandlerResult] that represents a streaming response.
+class StreamResult extends HandlerResult {
+  /// The stream of data to be returned in the response.
+  final Stream<Map<String, dynamic>> stream;
+
+  /// Creates a [StreamResult] with the given [stream].
+  StreamResult(this.stream);
+}

packages/a2a_dart/lib/src/server/request_handler.dart

@@ -4,7 +4,9 @@
 
 import 'dart:async';
 
-/// A handler for a specific A2A RPC method.
+import 'handler_result.dart';
+
+/// Defines the interface for a handler of a specific A2A RPC method.
 ///
 /// Implement this class to create a handler for a specific RPC method. The
 /// [A2AServer] will delegate requests to the appropriate handler based on the
@@ -18,5 +20,5 @@ abstract class RequestHandler {
   /// The [params] are the parameters of the RPC call. This method should return
   /// a [FutureOr] of a [Map] that will be sent as the `result` of the JSON-RPC
   /// 2.0 response.
-  FutureOr<Map<String, dynamic>> handle(Map<String, dynamic> params);
+  FutureOr<HandlerResult> handle(Map<String, dynamic> params);
 }

packages/a2a_dart/lib/src/server/task_manager.dart

@@ -2,6 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
+import 'package:a2a_dart/src/core/message.dart';
 import 'package:a2a_dart/src/core/task.dart';
 import 'package:uuid/uuid.dart';
 
@@ -16,12 +17,13 @@ class TaskManager {
   /// Creates a new [Task] with a unique ID and `submitted` status.
   ///
   /// The new task is stored in the task manager and then returned.
-  Task createTask() {
+  Task createTask([Message? message]) {
     final taskId = _uuid.v4();
     final contextId = _uuid.v4();
     final task = Task(
       id: taskId,
       contextId: contextId,
+      history: [if (message != null) message],
       status: const TaskStatus(state: TaskState.submitted),
     );
     _tasks[taskId] = task;

packages/a2a_dart/test/integration/client_server_test.dart

@@ -12,6 +12,7 @@ import 'package:a2a_dart/src/core/part.dart';
 import 'package:a2a_dart/src/core/task.dart';
 import 'package:a2a_dart/src/server/a2a_server.dart';
 import 'package:a2a_dart/src/server/create_task_handler.dart';
+import 'package:a2a_dart/src/server/handler_result.dart';
 import 'package:a2a_dart/src/server/request_handler.dart';
 import 'package:a2a_dart/src/server/task_manager.dart';
 import 'package:logging/logging.dart';
@@ -26,7 +27,7 @@ class MockExecuteTaskHandler implements RequestHandler {
   String get method => 'execute_task';
 
   @override
-  FutureOr<Map<String, dynamic>> handle(Map<String, dynamic> params) {
+  FutureOr<HandlerResult> handle(Map<String, dynamic> params) {
     final streamController = StreamController<Map<String, dynamic>>();
     final taskId = params['task_id'] as String;
     final task = taskManager.getTask(taskId)!;
@@ -74,7 +75,7 @@ class MockExecuteTaskHandler implements RequestHandler {
     );
     streamController.close();
 
-    return {'stream': streamController.stream};
+    return StreamResult(streamController.stream);
   }
 }