feat(embabel): Phase 3 — Akces Platform Development Goals, Actions, and Conditions

[jwijgerd]

Phase 3: Akces Platform Development Goals, Actions, and Conditions

Replaces: #307 (please close that issue)
Incorporates changes from: PR #303

Tracking issue: #311
Module: main/agentic
Can start: After Phase 1 + Annotation Extensions (#312) is merged
Can run concurrently with: Phase 2 (#313)
Blocks: Phase 4

📋 Plan reference: Phase 3: Akces Platform Development Goals, Actions, and Conditions (lines 451–571)

---

Overview

Higher-level Goals, Actions, and Conditions that enable an agentic aggregate to reason about and extend an Akces-based platform. These components provide the core agent capabilities for command processing, event handling, aggregate state analysis, and cross-aggregate coordination.

---

Tasks

3.1 Condition: IsCommandProcessingCondition

• @Condition(name = "isCommandProcessing")
• Returns true if the current agent context contains a command to process (as opposed to an external event)
• Enables different goal planning for command-initiated vs. event-initiated agent loops

3.2 Condition: IsExternalEventCondition

• @Condition(name = "isExternalEvent")
• Returns true if the current agent context was triggered by an external domain event
• Complement to isCommandProcessing — external events often require different reasoning strategies

3.3 Action: EmitDomainEventsAction — REMOVED

Removed in PR #303. Domain events produced by agent actions are placed on the Blackboard directly. The AgentProcessResultTranslator collects all DomainEvent objects from the blackboard after each tick() — no explicit "emit" action needed.

3.4 Action: SendCommandAction

• @Action(description = "Send a command to another aggregate via the command bus")
• Takes a Command object from the blackboard
• Routes it through the CommandBus (AgenticAggregatePartition implements CommandBus)
• Enables cross-aggregate coordination from within the agent

3.5 Action: AnalyzeAggregateStateAction

• @Action(description = "Analyze the current aggregate state using LLM reasoning", readOnly = true)
• Reads aggregate state from blackboard
• Serializes to structured representation
• Invokes LLM reasoning with context-specific prompts
• Returns analysis results on blackboard
• Framework building block — a reusable Action for higher-level Goals and future extensions (kept per architect decision)

3.6 Action: DiscoverAggregateServicesAction

• @Action(description = "Discover other aggregates in the system and their supported commands", readOnly = true)
• Reads List<AggregateServiceRecord> from the blackboard (populated by agentic handler adapters before agent invocation)
• For each record provides: aggregateName, commandTopic, domainEventTopic, type (STANDARD/AGENTIC), supportedCommands, producedEvents, consumedEvents
• Returns structured summary for LLM reasoning about system topology
• Blackboard setup: AkcesAgenticAggregateController maintains aggregateServices map; adapters place records on blackboard

3.7 Goal: ProcessCommandGoal

• Goal: "ProcessCommand" — "Process an incoming command through AI-assisted reasoning and produce domain events"
• Precondition: isCommandProcessing
• Plan:
  1. RecallMemoriesAction → load relevant prior knowledge
  2. AnalyzeAggregateStateAction → understand current state
  3. (LLM reasoning with MCP tools) → determine actions and produce domain events on the blackboard (including error events from agentProducedErrors)
  4. LearnFromProcessGoal (sub-goal) → learn from experience
• Replaces deterministic @CommandHandler for commands in agentHandledCommands
• Note: No EmitDomainEventsAction step — events are collected from Blackboard by AgentProcessResultTranslator

3.8 Goal: ReactToExternalEventGoal

• Goal: "ReactToExternalEvent" — "React to an external domain event through AI-assisted reasoning"
• Precondition: isExternalEvent
• Plan:
  1. RecallMemoriesAction → load relevant prior knowledge
  2. AnalyzeAggregateStateAction → understand current state
  3. (LLM reasoning) → determine appropriate response and produce domain events on the blackboard (including error events)
  4. SendCommandAction → send commands if needed
  5. LearnFromProcessGoal (sub-goal) → learn from experience
• Top-level goal for handling external events in agentHandledEvents

3.9 Goal: ManageKnowledgeGoal — REMOVED

Removed in PR #303. Memory management (storing, recalling, forgetting, capacity enforcement) is fully handled by LearnFromProcessGoal (section 2.7), which runs as a sub-goal after every command/event processing cycle. A separate knowledge management goal would duplicate this responsibility.

---

Changes from PR #303

• EmitDomainEventsAction (3.3) REMOVED — AgentProcessResultTranslator collects events from Blackboard directly
• ManageKnowledgeGoal (3.9) REMOVED — redundant with LearnFromProcessGoal
• ProcessCommandGoal plan updated — no longer includes EmitDomainEventsAction step; events produced directly on Blackboard
• ReactToExternalEventGoal plan updated — same change
• AnalyzeAggregateStateAction — explicitly marked as "framework building block" per architect decision

---

Acceptance Criteria

• IsCommandProcessingCondition and IsExternalEventCondition correctly evaluate blackboard context
• SendCommandAction routes commands through CommandBus
• AnalyzeAggregateStateAction serializes state and invokes LLM reasoning
• DiscoverAggregateServicesAction exposes AggregateServiceRecords from blackboard with all fields
• ProcessCommandGoal is correctly defined with isCommandProcessing precondition
• ReactToExternalEventGoal is correctly defined with isExternalEvent precondition
• No EmitDomainEventsAction or ManageKnowledgeGoal implementations
• All goals reference the correct sub-actions and sub-goals
• All existing tests still pass
• Code follows Java 25 conventions with JavaDoc