docs: restructure AI documentation into .agents and .claude directories

.claude/architecture/EVENTQUEUE.md

@@ -0,0 +1,151 @@
+# EventQueue Architecture - A2A Java SDK
+
+> **Quick Reference** for event processing, queue management, and task lifecycle
+
+## Overview
+
+The EventQueue architecture guarantees:
+1. **Events persist BEFORE clients see them** (no unpersisted events visible)
+2. **Serial processing** eliminates concurrent update race conditions
+3. **Task state drives queue lifecycle** (fire-and-forget support, late reconnections)
+
+## Architecture Diagram
+
+```
+AgentExecutor.execute() [YOUR CODE]
+    ↓
+AgentEmitter → MainQueue.enqueueEvent()
+    ↓
+MainEventBus.submit() [ALL events queue here FIRST]
+    ↓
+MainEventBusProcessor.take() [single background thread]
+    ↓
+1. TaskStore.save() FIRST ← Persist before visibility
+2. PushNotificationSender.send()
+3. MainQueue.distributeToChildren() ← Clients see LAST
+    ↓
+ChildQueue → EventConsumer → ResultAggregator → Client
+```
+
+**Key Insight**: All events flow through a single-threaded processor that persists events BEFORE distributing to clients.
+
+---
+
+## Core Components
+
+### MainEventBus
+**Location**: `server-common/.../events/MainEventBus.java`
+
+- `@ApplicationScoped` CDI bean - single instance shared by all MainQueues
+- `LinkedBlockingDeque<MainEventBusContext>` - thread-safe centralized queue
+- `submit(taskId, eventQueue, item)` - enqueue events (called by MainQueue)
+- `take()` - blocking consumption (called by MainEventBusProcessor)
+
+**Guarantees**: Events persist BEFORE distribution, serial processing, push notifications AFTER persistence
+
+### MainEventBusProcessor
+**Location**: `server-common/.../events/MainEventBusProcessor.java`
+
+Single background thread "MainEventBusProcessor" that processes events in order:
+1. `TaskManager.process(event)` → persist to TaskStore
+2. `PushNotificationSender.send()` → notifications
+3. `mainQueue.distributeToChildren()` → clients receive
+
+**Exception Handling**: Converts `TaskStoreException` to `InternalError` events, continues processing
+
+### EventQueue System
+**Location**: `server-common/.../events/EventQueue.java`
+
+**Queue Types**:
+- **MainQueue**: No local queue - events submit directly to MainEventBus
+- **ChildQueue**: Has local queue for client consumption
+
+**Characteristics**: Bounded (1000 events), thread-safe, graceful shutdown, hook support
+
+### QueueManager
+**Location**: `server-common/.../events/QueueManager.java`
+
+- `createOrTap(taskId)` → Get existing MainQueue or create new
+- `tap(taskId)` → Create ChildQueue for existing MainQueue
+- **Default**: InMemoryQueueManager (thread-safe ConcurrentHashMap)
+- **Replicated**: ReplicatedQueueManager (Kafka-based)
+
+### EventConsumer & ResultAggregator
+**Locations**: `server-common/.../events/EventConsumer.java`, `server-common/.../tasks/ResultAggregator.java`
+
+**EventConsumer**: Polls queue, returns `Flow.Publisher<Event>`, closes queue on final event
+
+**ResultAggregator** bridges EventConsumer and DefaultRequestHandler:
+- `consumeAndBreakOnInterrupt()` - Non-streaming (polls until terminal/AUTH_REQUIRED)
+- `consumeAndEmit()` - Streaming (returns Flow.Publisher immediately)
+- `consumeAll()` - Simple consumption
+
+---
+
+## Key Concepts
+
+### Queue Structure
+- MainQueue has NO local queue (events → MainEventBus directly)
+- Only ChildQueues have local queues
+- `MainQueue.dequeueEventItem()` throws `UnsupportedOperationException`
+- `MainQueue.size()` returns `mainEventBus.size()`
+- `ChildQueue.size()` returns local queue size
+
+### Terminal Events
+Events that cause polling loop exit:
+- `TaskStatusUpdateEvent` with `isFinal() == true`
+- `Message` (legacy)
+- `Task` with state: COMPLETED, CANCELED, FAILED, REJECTED, UNKNOWN
+
+### AUTH_REQUIRED Special Case
+- Returns task to client immediately
+- Agent continues in background
+- Queue stays open, async cleanup
+- Future events update TaskStore
+
+---
+
+## Deep Dives
+
+For detailed documentation on specific aspects:
+
+- **[Queue Lifecycle & Two-Level Protection](eventqueue/LIFECYCLE.md)**
+  - THE BIG IDEA: fire-and-forget, late reconnections
+  - TaskStateProvider interface and state-driven cleanup
+  - Memory management and cleanup modes
+
+- **[Request Flows](eventqueue/FLOWS.md)**
+  - Non-streaming vs streaming flows
+  - DefaultRequestHandler orchestration
+  - Background cleanup patterns
+
+- **[Usage Scenarios & Pitfalls](eventqueue/SCENARIOS.md)**
+  - Fire-and-forget pattern (TCK)
+  - Late resubscription scenarios
+  - Tapping and multiple consumers
+  - Common mistakes to avoid
+
+---
+
+## Key Files Reference
+
+| Component | Path |
+|-----------|------|
+| MainEventBus | `server-common/.../events/MainEventBus.java` |
+| MainEventBusProcessor | `server-common/.../events/MainEventBusProcessor.java` |
+| EventQueue | `server-common/.../events/EventQueue.java` |
+| QueueManager | `server-common/.../events/QueueManager.java` |
+| InMemoryQueueManager | `server-common/.../events/InMemoryQueueManager.java` |
+| EventConsumer | `server-common/.../events/EventConsumer.java` |
+| ResultAggregator | `server-common/.../tasks/ResultAggregator.java` |
+| DefaultRequestHandler | `server-common/.../requesthandlers/DefaultRequestHandler.java` |
+| TaskStateProvider | `server-common/.../tasks/TaskStateProvider.java` |
+| AgentEmitter | `server-common/.../tasks/AgentEmitter.java` |
+
+---
+
+## Related Documentation
+
+- **Main Architecture**: `AGENTS.md` - High-level system overview
+- **Task Persistence**: See TaskStore exception handling in main docs
+- **Replication**: `extras/queue-manager-replicated/README.md`

.claude/architecture/eventqueue/FLOWS.md

@@ -0,0 +1,228 @@
+# Request Flows - EventQueue Processing
+
+> Deep-dive on streaming vs non-streaming request handling
+
+## Non-Streaming Flow (`onMessageSend()`)
+
+**Location**: `DefaultRequestHandler.java`
+
+```
+1. initMessageSend()
+   → Create TaskManager & RequestContext
+
+2. queueManager.createOrTap(taskId)
+   → Get/create EventQueue (MainQueue or ChildQueue)
+
+3. registerAndExecuteAgentAsync()
+   → Start AgentExecutor in background thread
+
+4. resultAggregator.consumeAndBreakOnInterrupt(consumer)
+   → Poll queue until terminal event or AUTH_REQUIRED
+   → Blocking wait for events
+
+5. cleanup(queue, task, async)
+   → Close queue immediately OR in background
+
+6. Return Task/Message to client
+```
+
+### Terminal Events
+
+Events that cause polling loop exit:
+- `TaskStatusUpdateEvent` with `isFinal() == true`
+- `Message` (legacy)
+- `Task` with state: COMPLETED, CANCELED, FAILED, REJECTED, UNKNOWN
+
+### AUTH_REQUIRED Special Case
+
+**Behavior**:
+- Returns current task to client immediately
+- Agent continues running in background
+- Queue stays open, cleanup happens async
+- Future events update TaskStore
+
+**Why**: Allows client to handle authentication prompt while agent waits for credentials.
+
+---
+
+## Streaming Flow (`onMessageSendStream()`)
+
+**Location**: `DefaultRequestHandler.java`
+
+```
+1. initMessageSend()
+   → Same as non-streaming
+
+2. queueManager.createOrTap(taskId)
+   → Same
+
+3. registerAndExecuteAgentAsync()
+   → Same
+
+4. resultAggregator.consumeAndEmit(consumer)
+   → Returns Flow.Publisher<Event> immediately
+   → Non-blocking
+
+5. processor() wraps publisher:
+   - Validates task ID
+   - Adds task to QueueManager
+   - Stores push notification config
+   - Sends push notifications
+
+6. cleanup(queue, task, true)
+   → ALWAYS async for streaming
+
+7. Return Flow.Publisher<StreamingEventKind>
+```
+
+### Key Difference
+
+**Non-Streaming**: Blocks until terminal event, then returns Task/Message
+**Streaming**: Returns Flow.Publisher immediately, client receives events as they arrive
+
+**Cleanup**: Streaming ALWAYS uses async cleanup (background thread)
+
+---
+
+## EventConsumer Details
+
+**Location**: `server-common/.../events/EventConsumer.java`
+
+**Purpose**: Consumes events from EventQueue and exposes as reactive stream
+
+**Key Methods**:
+- `consume()` → Returns `Flow.Publisher<Event>`
+- Polls queue with 500ms timeout
+- Closes queue on final event
+- Thread-safe concurrent consumption
+
+**Usage**:
+```java
+EventConsumer consumer = new EventConsumer(eventQueue);
+Flow.Publisher<Event> publisher = consumer.consume();
+// Subscribe to receive events as they arrive
+```
+
+---
+
+## ResultAggregator Modes
+
+**Location**: `server-common/.../tasks/ResultAggregator.java`
+
+Bridges EventConsumer and DefaultRequestHandler with three consumption modes:
+
+### 1. consumeAndBreakOnInterrupt()
+
+**Used by**: `onMessageSend()` (non-streaming)
+
+**Behavior**:
+- Polls queue until terminal event or AUTH_REQUIRED
+- Returns `EventTypeAndInterrupt(event, interrupted)`
+- Blocking operation
+- Exits early on AUTH_REQUIRED (interrupted = true)
+
+**Use Case**: Non-streaming requests that need single final response
+
+### 2. consumeAndEmit()
+
+**Used by**: `onMessageSendStream()` (streaming)
+
+**Behavior**:
+- Returns all events as `Flow.Publisher<Event>`
+- Non-blocking, immediate return
+- Client subscribes to stream
+- Events delivered as they arrive
+
+**Use Case**: Streaming requests where client wants all events in real-time
+
+### 3. consumeAll()
+
+**Used by**: `onCancelTask()`
+
+**Behavior**:
+- Consumes all events from queue
+- Returns first `Message` or final `Task` found
+- Simple consumption without streaming
+- Blocks until queue exhausted
+
+**Use Case**: Task cancellation where final state matters
+
+---
+
+## Flow Comparison Table
+
+| Aspect | Non-Streaming | Streaming |
+|--------|---------------|-----------|
+| **ResultAggregator Mode** | consumeAndBreakOnInterrupt | consumeAndEmit |
+| **Return Type** | Task/Message | Flow.Publisher |
+| **Blocking** | Yes (until terminal event) | No (immediate return) |
+| **Cleanup** | Immediate or async | Always async |
+| **AUTH_REQUIRED** | Early exit, return task | Continue streaming |
+| **Use Case** | Simple request/response | Real-time event updates |
+
+---
+
+## Cleanup Integration
+
+### Actual Implementation: Always Asynchronous
+
+**Reality**: Cleanup is ALWAYS asynchronous in both streaming and non-streaming flows. The cleanup happens in the `finally` block via `cleanupProducer()`, which runs in a background thread.
+
+```java
+// Both flows (in finally block):
+cleanupProducer(agentFuture, consumptionFuture, taskId, queue, isStreaming)
+    .whenComplete((res, err) -> {
+        if (err != null) {
+            LOGGER.error("Error during async cleanup for task {}", taskId, err);
+        }
+    });
+```
+
+**Key Points**:
+- Cleanup is initiated in `finally` block regardless of flow outcome
+- `cleanupProducer()` waits for both agent and consumption futures to complete
+- Queue closure happens in background, never blocking the request thread
+- For streaming: EventConsumer manages queue lifecycle via `agentCompleted` flag
+- For non-streaming: Queue is closed directly after agent completes
+
+### Streaming Cleanup
+
+```java
+cleanup(queue, task, true);  // ALWAYS async for streaming
+```
+
+**Logic**: Streaming always uses async cleanup because:
+- Publisher already returned to client
+- Events may still be processing
+- Queue cleanup happens in background
+
+---
+
+## Thread Model
+
+### Agent Execution Thread
+- `CompletableFuture.runAsync(agentExecutor::execute, executor)`
+- Agent runs in background thread pool
+- Enqueues events to MainQueue
+
+### MainEventBusProcessor Thread
+- Single background thread: "MainEventBusProcessor"
+- Processes events from MainEventBus
+- Persists to TaskStore, distributes to ChildQueues
+
+### Consumer Thread
+- Non-streaming: Request handler thread (blocking)
+- Streaming: Subscriber thread (reactive)
+- Polls ChildQueue for events
+
+### Cleanup Thread
+- Async cleanup: Background thread pool
+- Immediate cleanup: Request handler thread
+
+---
+
+## Related Documentation
+
+- **[Main Overview](../EVENTQUEUE.md)** - Architecture and components
+- **[Lifecycle](LIFECYCLE.md)** - Queue lifecycle and cleanup
+- **[Scenarios](SCENARIOS.md)** - Real-world usage patterns